SGR Agent Core
用结构化推理、工具调用和可自托管 API 构建研究智能体。
README 说明了 OpenAI/Tavily 密钥、外部搜索、网络 API、日志和报告等主要数据与副作用，并明确列出项目团队及灵感来源，故来源归属充分。扣分原因是没有展示逐项用户确认机制、密钥存储或脱敏措施、完整数据流、工具权限隔离或明确恢复方案；Docker 指引要求 chmod 777、监听 0.0.0.0，并使用可变的 latest 镜像。依赖仅设宽松下限，工作流 action 也未按提交哈希固定，且未提供漏洞扫描或供应链控制证据。
README、pyproject 和 ACP 测试对命令入口、Python 环境及部分 ACP 行为基本一致，依赖也被明确声明。扣分原因是项目被标注为 Alpha，却同时宣称“Production Ready”和“battle-tested”，所给测试仅覆盖有限 ACP/配置路径，不能充分支撑该宣传；错误处理证据主要是未知配置值抛出 ValueError，未展示面向用户的诊断、重试或降级消息。
开发者与科研受众、研究代理场景、三类代理、HTTP/CLI/ACP 接口、可替换模型和配置化执行上限都较清楚。扣分原因是工具行为、安全边界、支持与不支持的任务类型及触发条件未被完整界定；环境覆盖 Python 3.11–3.13、Docker 和本地兼容模型，但平台差异、资源需求和部署加固要求未说明。
README 结构清楚，提供 Docker、pip、服务端、CLI 和 ACP 示例；包名、脚本入口、作者、问题追踪、文档和职责列表明确，MIT 正文与元数据一致。扣分原因是没有提供所给修订中的 FAQ 或实质性限制清单，Alpha 状态与免责声明只是薄弱的限制提示；版本由 git 标签生成且记录了发布方式，但没有提供 changelog；部分名称在 SGRAgent、sgr_agent、SGR Agent Core 等形式间变化。
流式响应、OpenAI 兼容 API、CLI、ACP、报告目录和多代理配置可产生可直接消费的输出；Schema-Guided Reasoning 与可扩展工具体系相对普通单轮封装具有潜在增量价值。扣分原因是所给材料未包含实现主体或完整基准文件，86.08% 准确率及“生产可用”只能视为仓库自述；除可选 Tavily、本地模型和执行次数配置外，没有延迟、令牌、费用或运维成本分析。
主要功能可在 README、pyproject 入口和 ACP 单元测试之间交叉对应，基准数字也指向具体结果文件。扣分原因是该结果文件、核心实现和完整文档未包含在证据中，无法静态追踪多数安全、性能与生产就绪声明；营销性事实、测试所得事实与推断没有被严格分层，且没有独立来源佐证。
- 不要在共享或生产主机上照搬 chmod 777；应使用最小文件权限，并在暴露 0.0.0.0 前配置认证、网络隔离和反向代理安全控制。
- 不要把 API 密钥提交到配置文件或镜像；在部署前确认密钥注入、日志脱敏、报告数据保留及 OpenAI/Tavily/Langfuse 等外部传输路径。
- 固定容器摘要和依赖版本，加入依赖漏洞及供应链扫描；不要依赖可变的 latest 镜像。
- 将“Production Ready”和 86.08% 基准视为未经本次静态材料独立验证的声明；项目元数据仍标为 Alpha。
- 启用搜索或其他工具前，应增加明确的副作用说明、敏感操作确认、超时/重试策略和可恢复机制。
这个 Agent 能做什么，适合哪些场景？
SGR Agent Core 是一个采用 Schema-Guided Reasoning 的开源研究智能体框架，核心提供可扩展的 BaseAgent 接口和两阶段架构。项目内置 SGRAgent、ToolCallingAgent 与 SGRToolCallingAgent，并提供搜索、推理和澄清工具。它既可作为 Python 库安装，也可部署成具有 OpenAI 兼容端点和 SSE 流式响应的 REST 服务。用户还可以通过 sgrsh 在终端交互，或通过 sgracp 以基于 stdio 的 Agent Client Protocol 接入编辑器和其他工具。它支持任何 OpenAI 兼容的大语言模型，包括可用于完全私有研究的本地模型；网络搜索和页面提取则可选用 Tavily。
用户在 YAML 配置的 agents 节点中选择并配置智能体、OpenAI 兼容模型以及可选工具。SGRAgent、ToolCallingAgent 或 SGRToolCallingAgent 接收研究问题，通过 BaseAgent 的两阶段架构组织 Schema-Guided Reasoning，并按配置调用搜索、页面内容提取、推理和澄清工具。运行期间可向用户发出澄清或中间结果请求，并通过 SSE 实时输出响应。最终结果可以通过 OpenAI 兼容 REST API、sgrsh 命令行会话或 sgracp 的换行分隔 JSON-RPC 流交付；Docker 示例还把日志和报告写入挂载的 logs 与 reports 目录。
- 需要在内部基础设施上部署研究服务的工程团队，可用 Docker 启动 OpenAI 兼容 API，并将日志和报告保存在宿主机目录。
- 希望把研究能力嵌入 Python 应用的开发者，可安装 sgr-agent-core，并基于可扩展的 BaseAgent 接口创建自定义智能体和工具。
- 已有 OpenAI API 客户端的团队，可将该服务作为兼容端点接入，并通过 SSE 接收实时结果。
- 处理敏感资料且不希望把查询交给托管模型的组织，可配置本地 OpenAI 兼容模型开展私有研究。
- 希望在终端连续研究并处理澄清请求的用户，可使用 sgrsh 的单次查询或交互聊天模式。
- 使用 Agent Client Protocol 编辑器或工具的开发者，可通过 sgracp 和 stdio 启动配置中的智能体。
这个 Agent 有哪些优点和局限？
- 同一项目同时提供 Python 框架、OpenAI 兼容 REST API、SSE 流式响应、交互式 CLI 和 ACP stdio 接口。
- 可在 SGRAgent、ToolCallingAgent 与混合式 SGRToolCallingAgent 之间选择，并通过 BaseAgent 扩展自定义智能体和工具。
- 支持任意 OpenAI 兼容模型，包括本地模型，因此可以设计完全私有的研究部署。
- 提供 Docker 镜像、配置示例、Swagger UI 和测试覆盖声明，降低服务化部署与验证的起步成本。
- 完整的联网研究需要另行提供模型服务和相应凭据；示例还把 Tavily 密钥列为搜索与页面提取的可选依赖。
- Docker快速开始要求创建 logs 和 reports 目录并执行
chmod 777，在严格安全环境中通常需要调整权限方案。 - OpenAI 兼容不等于原生支持 ChatGPT、Claude AI、Claude Code 或 Claude API；给定材料没有证明这些平台可直接接入。
- 公开的 SimpleQA 指标仅列出 gpt-4.1-mini 上的结果，没有给出其他模型、私有数据或生产负载下的对比证据。
如何安装或部署这个 Agent？
Python 库方式：运行 pip install sgr-agent-core。准备示例配置：运行 cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/config.yaml，然后设置 llm.api_key；若启用 Tavily 搜索或页面提取，还需设置 tools.web_search_tool.api_key 和 tools.extract_page_content_tool.tavily_api_key。
Docker 方式：先克隆仓库并进入目录：git clone https://github.com/vamplabai/sgr-agent-core.git，随后运行 cd sgr-agent-core。创建可写目录：sudo mkdir -p logs reports 和 sudo chmod 777 logs reports。复制并编辑上述配置文件后运行：docker run --rm -i --name sgr-agent -p 8010:8010 -v $(pwd)/examples/sgr_deep_research:/app/examples/sgr_deep_research:ro -v $(pwd)/logs:/app/logs -v $(pwd)/reports:/app/reports ghcr.io/vamplabai/sgr-agent-core:latest --config-file /app/examples/sgr_deep_research/config.yaml --host 0.0.0.0 --port 8010。服务随后位于 http://localhost:8010，Swagger UI 位于 http://localhost:8010/docs。
如何使用这个 Agent？
配置完成后，可运行 sgr --config-file examples/sgr_deep_research/config.yaml，或使用短参数 sgr -c examples/sgr_deep_research/config.yaml；也可执行 python -m sgr_agent_core.server --config-file examples/sgr_deep_research/config.yaml。首次命令行查询可用 sgrsh -a sgr_agent "What is AI?"；不传查询时运行 sgrsh -a sgr_agent 可进入交互模式。若需从 ACP 客户端接入，运行 sgracp --config examples/sgr_deep_research/config.yaml，并可在配置中加入 acp: {agent: sgr_agent} 选择暴露的智能体；未指定时使用第一个 agents 定义。
这个 Agent 与同类方案有什么区别？
框架内部提供三种选择：SGRAgent 面向 Schema-Guided Reasoning，ToolCallingAgent 面向工具调用，SGRToolCallingAgent 则组合两者。材料未提供三者逐项性能或适用边界，也未给出与外部框架的直接比较。
常见问题
必须使用 OpenAI 托管模型吗？
Tavily 是强制依赖吗？
研究结果可以通过哪些接口获取？
部署时需要哪些文件权限？
chmod 777，生产环境应根据自身安全策略设置满足容器写入需求的更严格权限。