sgr-agent-core

用 Schema 约束推理，让 Agent 工具调用不再乱输出

sgr-agent-core 是 neuraldeep 社区提出的 Schema-Guided Reasoning（SGR）智能体系统设计框架，用 Python 实现。它要解决的核心问题是：传统 function calling 依赖模型自由生成参数，容易格式出错、字段缺失、推理跳步，导致工具调用不稳定。SGR 的做法是先用 JSON Schema 明确约束每一步推理的结构，让模型按 schema 逐层填充，把「想清楚」和「调工具」拆成可校验的步骤。核心能力包括：基于 schema 的推理链生成、结构化输出校验、与 OpenAI API 等 LLM 的函数调用集成，以及面向 deep research 类任务的多步检索与工具编排。项目提供可复用的 agent 骨架，开发者只需定义 schema 和工具，就能搭建出输出可控、便于调试的智能体，适合需要稳定结构化推理的研究型与生产型场景。

开源 free 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1118

维护状态活跃

是否开源是

定价模式 free

项目数据

分类智能体

开发团队vamplabAI

所属国家

官网地址https://vamplabai.github.io/sgr-agent-core

GitHubhttps://github.com/vamplabAI/sgr-agent-core

定价模式free

价格说明开源免费，无在线服务

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型agent,deep-research,function-calling,llm,openai-api,research,sgr,so,structured-output

GitHub 星标★ 1118

30天Star增速

HF 下载量

上线时间2025-08-26 00:00:00

最近更新2026-09-16 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-09-16

浏览次数0

使用教程

难度：入门约 10 分钟部署方式：Docker 4 步

环境要求

已安装 Docker（用于容器方式启动服务）
获取到项目仓库（Docker 命令依赖仓库中的 examples/ 目录）
一个 OpenAI 兼容的 LLM 服务凭据或本地模型（README 未给出具体配置字段）
Python 环境（仅在使用 pip 安装库时需�要）

安装与启动步骤

1获取项目代码

克隆官方仓库，后续命令都在项目根目录执行，因为配置示例文件位于 examples/ 目录下。
```
git clone https://github.com/vamplabAI/sgr-agent-core.git
cd sgr-agent-core
```
2准备配置文件

从示例文件复制出 config.yaml，再按自己的 LLM 情况编辑其中的模型与密钥等配置。
```
cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/config.yaml
```

3启动 Docker 服务

映射 8010 端口，挂载配置目录（只读）以及 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

4按需安装 Python 库

若只想把 sgr-agent-core 作为库/框架使用，可不跑容器，直接用 pip 安装。
```
pip install sgr-agent-core
```

关键配置

配置项	必填	说明	示例
`config-file`	是	容器启动时指定的智能体配置文件路径，需先由 .example 复制并编辑。	`/app/examples/sgr_deep_research/config.yaml`
`--host`	是	API 服务监听地址，容器内需设为 0.0.0.0 才能被外部访问。	`0.0.0.0`
`--port`	是	API 服务监听端口，与 docker -p 映射的端口保持一致。	`8010`

如何确认成功

浏览器访问 http://localhost:8010/docs 能看到 Swagger UI，或访问 http://localhost:8010 得到 OpenAI 兼容接口响应，即启动成功。

常见问题

Q：服务启动后在哪里看接口文档？

A：访问 http://localhost:8010/docs，README 说明这里提供交互式 Swagger UI；OpenAI 兼容接口基地址为 http://localhost:8010。

Q：8010 端口被占用怎么办？

A：需同时修改 docker run 的 -p 映射和启动参数 --port，例如 -p 8020:8020 搭配 --port 8020，两者必须一致。

Q：想用本地模型做完全私有化研究可以吗？

A：可以。README 说明支持任意 OpenAI 兼容的 LLM，包括本地模型，只需在配置文件中改成对应的地址与凭据。

Q：几种智能体该选哪个？

A：README 提供 SGRAgent、ToolCallingAgent 和 SGRToolCallingAgent 三种可选类型，可按是否需要严格 schema 约束推理链来选择。

Q：生成的报告和日志在哪？

A：容器把宿主机当前目录的 logs 和 reports 挂载到容器内 /app/logs 与 /app/reports，直接在项目根目录下查看即可。

注意事项

Docker 命令需在项目根目录执行，因为挂载路径使用了相对路径 examples/sgr_deep_research 与 $(pwd)。
examples 目录以只读方式（:ro）挂载，修改配置要在宿主机上改，容器内改无效。
README 未列出 config.yaml 的具体字段，需参考官方文档 https://vamplabai.github.io/sgr-agent-core/ 完成配置。
更多细节见框架快速上手文档 https://vamplabai.github.io/sgr-agent-core/framework/first-steps/。

核心亮点

用 JSON Schema 约束每步推理，工具调用参数可校验、可回放，显著降低格式错误
把推理与函数调用解耦成可调试的中间步骤，便于定位 agent 在哪一步出错
面向 deep research 场景设计，天然支持多步检索与结构化结果汇总

不足之处

项目较新、星标约 1.1k，生态与第三方集成尚不丰富
强依赖 schema 设计质量，schema 写得差会限制推理灵活性

适用场景

搭建需要稳定结构化输出的研究型 agent
把 LLM 工具调用接入生产系统并做参数校验
多步检索、信息汇总类 deep research 任务

替代项目

LangChain、LlamaIndex、DSPy

项目介绍

sgr-agent-core 是一个智能体领域的开源项目，官方简介：Schema-Guided Reasoning (SGR) has agentic system design created by neuraldeep community。项目使用 Python 开发，在 GitHub 上获得 1118 星标。

上一篇：evolving-agents

下一篇：openloomi