sgr-agent-core：用 YAML 约束推理流程的 Python 研究代理框架
Schema-Guided Reasoning (SGR) has agentic system design created by neuraldeep community
秒懂
- 它是什么？
- 它把代理的推理步骤写成结构化的 schema，而不是让模型自由发挥；对需要可控、可配置研究流程的团队有吸引力，但对只想调一次 API 的人来说，配置成本偏高。
- 适合谁用？
- 如果你的团队在做深度研究类代理，并且希望把推理步骤、工具调用和澄清流程固定在一份 YAML 里，而不是散落在提示词字符串中，sgr-agent-core 值得先花半小时跑通 Docker 那一条命令。反过来，如果你只是要一个能回答问题的聊天接口，或者不想维护 config.yaml 里的 llm.api_key、tools.web_search_tool.api_key 这些键，这个框架的抽象层只会增加你的工作量。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 20 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它要解决的不是「让模型会推理」，而是「让推理过程可被配置」
多数代理框架把行为写在提示词里：一段系统提示、几个函数描述，剩下的交给模型自己决定先搜索还是先回答。sgr-agent-core 走的是另一条路。README 把 Schema-Guided Reasoning 描述为「结构化推理」与「灵活工具选择」的结合，落到工程上就是：一次任务被拆成两个阶段，第一阶段按固定的 schema 产出推理结果，第二阶段再决定调用哪些工具。schema 是配置的一部分，不是模型临场生成的。
这套设计的目标用户很明确：要构建研究型代理，并且需要流程可复现的人。README 里列出的场景是搜索、推理、澄清三类工具的组合，配合 OpenAI 兼容的 REST API 对外提供服务。它不试图做一个通用聊天机器人，也不提供图形界面。你要么把它当 Python 库用，要么把它当服务跑起来，然后自己接前端。
这里有一个容易被忽略的取舍：schema 约束越强，模型在边缘问题上的自由度越小。对一个需要「先查证再下结论」的研究任务，这是优点；对一个需要临场发挥的对话任务，这是负担。框架同时提供 SGRAgent、ToolCallingAgent、SGRToolCallingAgent 三种代理类型，本质上是在这个光谱上给你三个档位。
两阶段架构与三种代理类型的分工
README 反复提到「two-phase architecture」，但没有在正文里展开每一步的具体输入输出。可以确认的是：BaseAgent 是一个可扩展接口，三种代理都建立在它之上，工具的类别被划为搜索、推理、澄清。澄清这一项值得单独说，因为 sgrsh 的命令行说明里提到它会「处理代理发出的澄清与对话（中间结果）请求」，说明代理在信息不足时可以向调用方反问，而不是硬猜。这在研究场景里比在客服场景里更常见。
三种代理的差别，从命名上能读出的信息是：SGRAgent 走纯 schema 引导的路径，ToolCallingAgent 走标准的函数调用路径，SGRToolCallingAgent 是两者的混合。仓库的贡献者名单里专门列了一位负责「Hybrid FC research」的人，说明混合模式是项目当前投入研究的方向之一。至于混合模式内部如何决定何时用 schema、何时用原生 function calling，README 没有给出机制说明，文档站点的框架章节是唯一可能的出处。
数据流的可见部分止于此：配置进、任务进、SSE 流式响应出、报告写入挂载的 reports 目录。中间态的持久化方式、多轮任务之间是否共享上下文，从给出的材料里无法确认。
启动路径：Docker 一条命令，或者 pip 一个包
README 把 Docker 称为最快的上手方式，并且给了完整命令。流程是克隆仓库、创建 logs 与 reports 两个目录并赋予写权限、从 config.yaml.example 复制出 config.yaml、填入密钥，然后运行容器。容器镜像来自 ghcr.io/vamplabai/sgr-agent-core:latest，端口映射到 8010，配置文件和两个输出目录以卷的方式挂载进去。服务起来后，OpenAI 兼容端点在 8010，Swagger UI 在 /docs。
配置里需要填的键，README 点名了三处：llm.api_key、tools.web_search_tool.api_key、tools.extract_page_content_tool.tavily_api_key。后两个都标注为可选，且都指向 Tavily，也就是说默认的搜索与网页正文提取能力绑定在同一个服务商上。想换搜索后端，得改工具实现而不是改一个 URL。
如果只想要库，pip install sgr-agent-core 即可。想直接跑服务，命令行入口是 sgr，短选项 -c，等价于 python -m sgr_agent_core.server --config-file ...。交互式使用走 sgrsh：它会在当前目录自动找 config.yaml，支持单次查询和交互式聊天两种模式，用 --agent 或 -a 指定代理，用 -c 指定配置文件。README 里的示例查询用的是俄语，说明这个社区的主要使用语言不止英语。
第三个入口是 sgracp，走 Agent Client Protocol，通过 stdio 传输换行分隔的 JSON-RPC，给支持 ACP 的编辑器用。它复用同一份 YAML，配置里可选的 acp.agent 键决定暴露哪个 agents 条目，不写就用第一个。
Docker 快速开始里的权限处理是个信号
README 的 Docker 步骤里有一行 sudo chmod 777 logs reports。把挂载目录设成全局可写，在本地开发机上无所谓，在任何共享环境里都需要替换成明确的属主和权限位。文档没有解释为什么容器需要这么宽的权限，可能是容器内进程的 UID 与宿主机不一致。这不是框架本身的缺陷，但它说明快速开始脚本是按「先跑起来」优化的，不是按「直接上生产」优化的。README 里「Production Ready」的说法与这一行放在一起看，需要读者自己判断边界。
另一个约束来自挂载方式：配置文件是 :ro 只读挂载，改配置要重启容器。对需要频繁调 schema 的调试阶段，这意味着每次调整都要走一遍重启流程。把配置放到容器外是好事，但只读意味着热更新这条路被堵死了。
日志和报告落在宿主机目录里，这是个务实的选择：容器可以随时删除，产物留在本地。代价是并发运行多个实例时需要自己规划目录，否则会互相覆盖。
基准数字能说明什么，不能说明什么
README 给出了一组 SimpleQA 上的结果：在 gpt-4.1-mini 上准确率 86.08%，正确 3724 条，错误 554 条，未尝试 48 条。数字旁边有指向 benchmark 目录下结果文件的链接。这是项目自己发布的数字，没有第三方复现，也没有说明评测时的配置、温度参数、工具可用性以及「未尝试」如何计入分母。用 3724 除以 3724+554 得到的比例与 86.08% 接近，说明未尝试的那部分大概率没有算进准确率分母，这会让数字看起来比实际严格口径更好看。
更实际的问题是这个数字的迁移性。SimpleQA 是短答案事实性问答，而框架的卖点是多步研究流程。一个在单跳事实上表现好的配置，不必然在多跳研究任务上表现好。仓库里可见的只有这一个基准，没有消融实验说明 schema 引导相比原生 function calling 带来了多少增益。想验证混合模式的价值，只能自己去跑。
所以这组数字的正确用法是当作一个量级参考：至少说明默认配置在某个标准集上不是随机水平。它不构成选型依据。
什么时候它不合适
最明显的不匹配是低延迟的问答服务。两阶段架构意味着至少两次模型往返，加上工具调用，响应时间天然比单次补全长。SSE 流式能改善体感，但改变不了总时长。如果你的场景是毫秒级响应的检索问答，这个框架的抽象层只会拖慢你。
第二类不匹配是工具生态已经固定的团队。默认的搜索与正文提取都绑在 Tavily 上，配置里没有提供第二个搜索后端的示例。要接自建检索或别的搜索 API，需要按 BaseAgent 和工具的接口自己写实现。README 说扩展容易，但没有给出自定义工具的完整示例，只有 examples/ 目录的指引。
第三类是对确定性要求极高的场景。schema 引导提高了结构化程度，但模型仍然在 schema 内部做选择，输出不是可证明正确的。如果业务流程要求每一步都能被审计到具体规则，那么把推理交给模型本身就不成立，无论 schema 多严格。
还有一点：README 里没有提到速率限制、重试策略、并发任务隔离这些运行期问题。对一个要长期跑的服务，这些是需要自己补的。
和直接用 OpenAI 函数调用比，差在哪
最直接的替代方案是不用框架，直接调 OpenAI 兼容接口的 function calling，自己写循环。差别在于控制点放在哪里。裸 function calling 里，模型每一轮自由决定调哪个函数，你只能通过函数描述和系统提示间接影响它。sgr-agent-core 把一次任务的前半段固定成 schema 产出的推理结果，模型在更窄的空间里做选择。
这个差别的代价是灵活性。裸 function calling 能处理你没预料到的工具组合，schema 引导的流程在遇到 schema 没覆盖的情况时，要么退化到通用路径，要么失败。项目提供 ToolCallingAgent 和 SGRToolCallingAgent，某种程度上就是在承认纯 schema 路径不够用，需要保留一条原生函数调用的退路。
另一个替代方向是 LangGraph 这类把代理建模成状态机的库。区别在于状态机把控制流写在代码里，schema 引导把控制流写在配置和模型输出里。前者更可预测、更难写错，后者更容易让非工程角色参与调整。选哪个取决于谁拥有这套流程的定义权。
值得说明的是，README 没有做任何横向对比，也没有提到与其他框架的互操作。所以上面的比较是从机制层面推出来的，不是文档里的结论。
维护成本、许可证与需要先验证的事
许可证是 MIT，这对商业使用和二次分发都很宽松。需要注意的不是许可证本身，而是依赖链：默认配置把搜索能力指向 Tavily，那是另一家的服务条款和计费方式，MIT 覆盖不到。模型侧同理，llm.api_key 指向的服务商有自己的使用政策。把这两层分清楚，比读许可证正文更重要。
维护节奏上，仓库给出的发布记录是 0.6.0 在 2026 年 1 月、0.7.0 在 3 月、0.7.1 在 7 月，主分支最后一次推送在 2026 年 8 月。版本号还在 0.x，意味着 API 有变动空间，锁版本比跟最新更稳妥。升级时最可能出问题的地方是 config.yaml 的结构，因为代理类型、工具和 acp 块都从同一份配置读取，键名变动会同时影响 HTTP 服务和 sgracp 两个入口。
上手前建议按顺序验证三件事。第一，用 Docker 那条命令跑通，确认 8010 端口和 /docs 可访问，这一步能暴露挂载权限和密钥问题。第二，用 sgrsh 发一次单查询，观察代理是否会触发澄清请求，这能让你判断两阶段流程在你的任务上是否真的收敛。第三，翻 benchmark/simpleqa_benchmark_results.md，看评测配置与你的使用方式差多少。这三步都不需要改代码，但任何一步失败，都说明你需要先解决集成问题，而不是先写业务逻辑。
编辑结论
如果你的团队在做深度研究类代理，并且希望把推理步骤、工具调用和澄清流程固定在一份 YAML 里，而不是散落在提示词字符串中，sgr-agent-core 值得先花半小时跑通 Docker 那一条命令。反过来，如果你只是要一个能回答问题的聊天接口，或者不想维护 config.yaml 里的 llm.api_key、tools.web_search_tool.api_key 这些键，这个框架的抽象层只会增加你的工作量。上手前先确认三件事：你的模型是否走 OpenAI 兼容接口，你的搜索工具是否用 Tavily（文档里 web_search_tool 与 extract_page_content_tool 都指向它），以及你是否接受把 logs 和 reports 目录以可写方式挂载进容器。这三点里任何一条不成立，你都需要先改配置或改工具实现，再谈部署。
社区笔记