SGR Agent Core — 首个基于模式引导推理的开源智能体框架

SGR Agent Core 是一个开源智能体框架，用于构建基于模式引导推理的智能研究代理。该项目提供了一个核心库，其中包含可扩展的 BaseAgent 接口，实现了两阶段架构，并在此基础上构建了多个开箱即用的研究代理实现。

该库包括用于搜索、推理和澄清的可扩展工具、实时流式响应以及与 OpenAI 兼容的 REST API。它可与任何兼容 OpenAI 的大语言模型一起使用，包括本地模型，以实现完全私密的研究。

为什么选择 SGR Agent Core？

• 模式引导推理 — SGR 将结构化推理与灵活的工具选择相结合
• 多种代理类型 — 可选择 SGRAgent、ToolCallingAgent 或 SGRToolCallingAgent
• 可扩展架构 — 轻松创建自定义代理和工具
• OpenAI 兼容 API — 可直接替换 OpenAI API 端点
• 实时流式传输 — 内置对通过 SSE 进行流式响应的支持
• 生产就绪 — 经过实战检验，拥有全面的测试覆盖率和 Docker 支持

文档

请参阅我们的文档快速入门：

• 项目文档 - 完整的项目文档
• 框架快速入门指南 - 几分钟内即可上手运行
• DeepSearch 服务文档 - 带有示例的 REST API 参考

快速入门

使用 Docker 运行

最快捷的入门方式是使用 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

# 复制并编辑配置文件
cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/config.yaml
# 编辑 examples/sgr_deep_research/config.yaml 并设置您的 API 密钥：
# - llm.api_key: 您的 OpenAI API 密钥
# - tools.web_search_tool.api_key: 您的 Tavily API 密钥（可选）
# - tools.extract_page_content_tool.tavily_api_key: 您的 Tavily API 密钥（可选）

# 运行容器
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

API 服务器将在 http://localhost:8010 上可用，提供与 OpenAI 兼容的 API 端点。交互式 API 文档（Swagger UI）可在 http://localhost:8010/docs 访问。

安装

如果您想将 SGR Agent Core 作为 Python 库（框架）使用：

pip install sgr-agent-core

请参阅 安装指南 获取详细说明，并参考 作为库使用指南 开始使用。

运行研究代理

该项目在 examples/ 目录中包含了示例研究代理配置。要开始使用深度研究代理：

1. 复制并配置配置文件：

cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/config.yaml
# 编辑 examples/sgr_deep_research/config.yaml 并设置您的 API 密钥：
# - llm.api_key: 您的 OpenAI API 密钥
# - tools.web_search_tool.api_key: 您的 Tavily API 密钥（可选）
# - tools.extract_page_content_tool.tavily_api_key: 您的 Tavily API 密钥（可选）

2. 使用 sgr 工具运行 API 服务器：

sgr --config-file examples/sgr_deep_research/config.yaml
# 或使用简短选项
sgr -c examples/sgr_deep_research/config.yaml

注意： 您也可以直接使用 Python 运行服务器：

python -m sgr_agent_core.server --config-file examples/sgr_deep_research/config.yaml

使用 CLI 工具 (sgrsh)

对于交互式的命令行使用，您可以使用 sgrsh 工具：

# 单次查询模式
sgrsh "查找比特币价格"

# 选择代理（例如 sgr_agent、dialog_agent）
sgrsh --agent sgr_agent "什么是 AI？"

# 使用自定义配置文件
sgrsh -c config.yaml -a sgr_agent "您的查询"

# 交互式聊天模式（无需查询参数）
sgrsh
sgrsh -a sgr_agent

sgrsh 命令：

• 自动在当前目录中查找 config.yaml
• 支持多轮查询的交互式聊天模式
• 处理来自代理的澄清和对话请求（中间结果）
• 可与您配置中的任何代理配合使用（例如 sgr_agent、dialog_agent）

更多示例和详细的使用说明，请参阅 examples/ 目录。

基准测试

gpt-4.1-mini 上的性能指标：

• 准确率: 86.08%
• 正确: 3,724 个答案
• 错误: 554 个答案
• 未尝试: 48 个答案

更详细的基准测试结果请参见 这里。

开源开发团队

所有开发工作均由纯粹的热情和开源社区协作驱动。我们欢迎各技能水平的贡献者！

• SGR 概念创造者 // @abdullin
• 项目协调员及愿景提出者 // @VaKovaLskii
• 核心开发负责人 // @virrius
• API 开发 // @EvilFreelancer
• DevOps 和部署 // @mixaill76
• Hybrid FC 研究 // @Shadekss

如果您有任何问题，请随时加入我们的 社区聊天↗️ 或联系 Valerii Kovalskii↗️。

特别致谢：

本项目由 neuraldeep 社区开发。它受到“LLM Under the Hood”社区和 TIMETOACT GROUP Österreich↗️ 的 AI 研发中心所发布的模式引导推理（SGR）工作及 SGR 代理演示↗️ 的启发。

本项目得到了 red_mad_robot 的 AI 研发团队的支持，他们提供了研究能力、工程专业知识、基础设施和运营支持。

了解更多关于 red_mad_robot 的信息：redmadrobot.ai↗️ habr↗️ telegram↗️

星标历史

SGR Agent Core 快速上手指南

SGR Agent Core 是一个基于“模式引导推理”（Schema-Guided Reasoning, SGR）的开源智能体框架，专为构建智能研究助手设计。它支持结构化推理、灵活的工具调用、实时流式响应，并提供兼容 OpenAI 的 REST API。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (推荐 WSL2)
• Python 版本：Python 3.9 或更高版本
• 依赖项：
  • 方案 A (Docker)：已安装 Docker 和 Docker Compose（推荐用于快速部署）。
  • 方案 B (Python 库)：已安装 pip 包管理工具。
• API Keys：
  • LLM Key：OpenAI API Key（或任何兼容 OpenAI 接口的本地/云端模型 Key）。
  • 搜索工具 Key（可选）：Tavily API Key（用于网页搜索和内容提取）。

安装步骤

您可以选择通过 Docker 快速运行服务，或作为 Python 库集成到项目中。

方式一：使用 Docker 运行（推荐）

这是最快启动服务的方式，无需配置本地 Python 环境。

1. 克隆仓库并准备目录：

   git clone https://github.com/vamplabAI/sgr-agent-core.git
   cd sgr-agent-core
   
   # 创建日志和报告目录并赋予权限
   sudo mkdir -p logs reports
   sudo chmod 777 logs reports
   

2. 配置 API Keys：

   cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/config.yaml
   

   编辑 examples/sgr_deep_research/config.yaml 文件，填入您的密钥：

   • llm.api_key: 您的 OpenAI API Key
   • tools.web_search_tool.api_key: 您的 Tavily API Key (可选)

3. 启动容器：

   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
   

   启动后，API 服务将运行在 http://localhost:8010，Swagger 文档地址为 http://localhost:8010/docs。

方式二：作为 Python 库安装

如果您希望将其集成到自己的代码中：

pip install sgr-agent-core

提示：国内用户若遇到下载缓慢，可添加国内镜像源加速： pip install sgr-agent-core -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

安装完成后，您可以通过命令行工具直接与研究代理交互，或启动 API 服务。

1. 配置研究代理

在使用前，需先复制并配置示例配置文件（如果尚未配置）：

cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/config.yaml
# 请编辑 config.yaml 填入 llm.api_key 和 tavily api_key

2. 使用 CLI 工具 (sgrsh) 进行交互

sg rsh 是最简单的交互式命令行工具，支持单次查询和对话模式。

• 单次查询模式：

  sgrsh "Find the price of Bitcoin"
  

• 指定代理类型（如 sgr_agent 或 dialog_agent）：

  sgrsh --agent sgr_agent "What is AI?"
  

• 使用自定义配置文件：

  sgrsh -c config.yaml -a sgr_agent "Your query"
  

• 进入交互式聊天模式（不传参数即可进入多轮对话）：

  sgrsh
  # 或者指定代理
  sgrsh -a sgr_agent
  

3. 启动 API 服务器

如果您需要通过 HTTP API 调用（例如集成到其他应用）：

# 使用 sgr 工具启动
sgr --config-file examples/sgr_deep_research/config.yaml

# 或者直接使用 Python 模块启动
python -m sgr_agent_core.server --config-file examples/sgr_deep_research/config.yaml

服务启动后，您可以通过 http://localhost:8010 访问兼容 OpenAI 格式的 API 端点。