sgr-agent-core: Schema-Guided Reasoning as a Two-Phase Agent Loop
Schema-Guided Reasoning (SGR) has agentic system design created by neuraldeep community
At a glance
- What is it?
- sgr-agent-core is an MIT-licensed Python framework that splits agent execution into a reasoning phase and a tool-calling phase, driven by YAML config and exposed through an OpenAI-compatible REST API. It is a reasonable fit if you want research agents you can self-host against any OpenAI-compatible model, and a poor fit if you need a single agent loop with no schema authoring.
- Who is it for?
- Adopt sgr-agent-core if you want a self-hosted research agent whose reasoning is constrained by a schema you control, and you are willing to run an OpenAI-compatible endpoint plus a Tavily key for search. Do not adopt it if you need a single-pass function-calling loop with no schema authoring, or if you cannot read the docs site to learn the schema format, because the README does not define it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 20 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem SGR Agent Core targets: reasoning that a schema can check
Most agent frameworks let the model decide both what to think about and which tool to call in the same completion. That works until you need to inspect why a step was taken, or until a model with weaker instruction-following starts skipping steps. sgr-agent-core takes a different position. Schema-Guided Reasoning, credited in the README to the neuraldeep community, constrains the reasoning step itself with a schema, then lets tool selection happen in a separate phase. The README describes this as a two-phase architecture implemented behind an extendable BaseAgent interface.
The audience is narrow and identifiable. You are building a research agent that queries the web, extracts page content, and produces a report. You want to run it against a local model for what the README calls fully private research, or against any OpenAI-compatible endpoint. You are comfortable editing YAML rather than writing Python for every change. The project ships three concrete agent types (SGRAgent, ToolCallingAgent, SGRToolCallingAgent) plus example research configurations, so the intended path is configure-and-run, not build-from-scratch.
If your task is a single tool call with a fixed argument shape, this is more machinery than the problem needs.
How the two-phase loop and its tools fit together
The architecture visible in the material is a core library plus agent implementations on top of it. BaseAgent is the extension point; the three named agents are the shipped implementations. The library bundles what the README calls extensible tools for search, reasoning, and clarification. Clarification matters more than it sounds: the sgrsh CLI is documented as handling clarification and dialog requests from agents, which implies an agent can pause mid-run and ask the caller a question rather than guessing.
Data flow at runtime is HTTP in, streamed HTTP out. The server exposes OpenAI-compatible REST endpoints, and streaming responses go over SSE. That choice is what makes the project a drop-in for clients already pointed at an OpenAI-style base URL. A client that speaks the chat completions shape can be repointed at localhost:8010 without a custom SDK.
There is a second transport that the README treats as a first-class entry point: Agent Client Protocol over stdio, newline-delimited JSON-RPC, via the sgracp binary. The same YAML config drives both the HTTP server and the ACP binary, which is the cleanest design decision in the repository. You configure an agent once and expose it to an editor that speaks ACP or to an HTTP client, without maintaining two configs.
What the README does not show is the schema format itself. It names Schema-Guided Reasoning as the core idea and links to a docs site, but the reasoning schema syntax, the fields it requires, and what happens when a model returns a schema-violating response are not in the README. Treat the docs site as required reading, not optional.
Getting a server running: Docker, pip, and the three binaries
The README presents Docker as the fastest path. The sequence is clone, create logs and reports directories with write permissions, copy the example config, edit it, then run the container. The config keys named explicitly are llm.api_key for the model provider, tools.web_search_tool.api_key for Tavily, and tools.extract_page_content_tool.tavily_api_key. The search and extraction keys are marked optional in the README, which suggests the agent can run without web tools, though the README does not describe what such a run produces.
The container invocation mounts the example config read-only and mounts logs and reports as writable volumes, then passes --config-file, --host and --port as arguments. The image is ghcr.io/vamplabai/sgr-agent-core:latest. Note the tag: latest, not a version. If you need reproducibility you will have to pin a digest yourself, because the README does not show a versioned tag.
For library use, pip install sgr-agent-core. For running the server from a checkout, the sgr utility takes --config-file or the short -c, and python -m sgr_agent_core.server with the same flag is documented as an equivalent. The interactive CLI is sgrsh, which takes a query, an optional --agent name such as sgr_agent or dialog_agent, and an optional -c config path. With no query argument it drops into interactive chat mode. The README states that sgrsh looks for config.yaml in the current directory automatically.
The ACP binary is sgracp --config examples/sgr_deep_research/config.yaml. Which agent it exposes is controlled by an acp block with a single key, acp.agent. If that block is omitted, the README says the first agent definition in the agents list is used. That default is worth setting explicitly, because reordering the agents list silently changes what your editor connects to.
The benchmark number and what it does not tell you
The README reports SimpleQA results on gpt-4.1-mini: 86.08% accuracy, 3,724 correct, 554 incorrect, 48 not attempted. A linked results file is said to hold more detail. Those are the project's own numbers on its own benchmark run, and they are the only quantitative performance claim in the material. There is no comparison table in the README naming which other systems were measured on the same run, so the accompanying chart is described but its contents are not reproducible from the text here.
Two things follow. First, 86.08% on SimpleQA with a specific model says nothing about how the framework behaves on a different model, and nothing about latency or token cost, neither of which appears in the material. Second, the README's claim that the project is production ready rests on the phrase comprehensive test coverage and on Docker support. No coverage figure, no CI badge detail, and no failure-rate data are given. That is a marketing sentence sitting next to a real benchmark, and the benchmark is the part worth trusting.
Where the framework is the wrong tool
The two-phase design is the product, and it is also the constraint. If your task does not benefit from an explicit reasoning step that a schema can validate, you are paying for a phase you do not need. A plain ToolCallingAgent exists in the list, which softens this, but the framework's identity and documentation are built around the SGR path.
Configuration is the second constraint. The README's own quick start requires editing YAML and supplying at least one API key before anything runs. There is no documented zero-config mode and no example of running an agent with no external credentials at all. If you want a library you import and call with a prompt, this is a heavier onboarding than that.
Third, the reasoning schema is undocumented in the README. A framework whose central mechanism is a schema, and which does not show the schema, puts a documentation dependency in front of every customization. You can run the shipped example agents from the README alone. You cannot write a custom agent from the README alone.
Finally, the Docker example uses the latest tag and the quick start instructs chmod 777 on the logs and reports directories. That is a permissions shortcut appropriate for a local trial, not something to carry into a shared host.
Compared with a plain function-calling loop
The obvious alternative is the standard approach: one model call that returns tool calls, execute them, append results, repeat. That is what ToolCallingAgent in this same repository appears to do, and it is what most OpenAI-compatible agent code does. The difference is where control sits. In a plain loop, the model's reasoning is free text inside the same completion that carries the tool call, so the only structure you get is the tool schema. In Schema-Guided Reasoning, the reasoning step is itself schema-constrained and separated from tool selection. You get a checkable intermediate artifact and a clearer place to intervene when a run goes wrong, at the cost of an extra phase and a schema to author and maintain.
A second alternative is a hosted research assistant API, where you send a question and receive a report. That removes the schema and the hosting work entirely. It also removes the ability to point the agent at a local model, which the README lists as a supported configuration and which is the main reason to self-host this project rather than call someone else's endpoint.
Maintenance surface, releases, and the MIT licence
The release history in the material shows 0.7.1 in July 2026, 0.7.0 in March 2026, and 0.6.0 in January 2026, with the repository last pushed in August 2026 and not archived. The cadence is roughly a minor release every two to three months, and the version numbers are still below 1.0. Under semantic versioning conventions that means minor releases may carry breaking changes to the Python API or to config keys, and the README gives no compatibility statement either way. If you build custom agents on BaseAgent, budget for reading release notes before each upgrade.
Upgrade cost has three parts. The Python package is a normal pip dependency. The Docker path is the awkward one, because the documented image reference is a latest tag, so an upgrade can happen without you choosing it. The config surface is the third: keys are nested under llm and tools, and the ACP selection lives under acp.agent, so a rename in any of those namespaces breaks a running deployment rather than failing loudly at import.
The licence is MIT, which is permissive and permits commercial use and modification, with the usual requirement to preserve the copyright and licence notice. That is the extent of what can be said here. Whether MIT fits your organisation's policy on attribution, or how it interacts with the licences of the models and search providers you plug in, is a question for your own legal review, not something this material can settle.
Who should run it, and what to check before you do
This fits a team that wants a self-hosted research agent, is willing to run an OpenAI-compatible endpoint (including a local model), and wants the option to expose the same agent over HTTP and over ACP stdio from one YAML file. The sgracp binary is the strongest differentiator in the material, because it means an editor integration and a service integration share configuration rather than diverging.
It does not fit someone who wants a prompt-in, answer-out library with no config file, or a team that needs documented schema syntax before they can write a custom agent.
Before you commit, verify the schema format on the docs site, since the README does not define it. Confirm that acp.agent names the agent you actually want exposed, rather than relying on the first-entry default. Pin a specific image digest instead of ghcr.io/vamplabai/sgr-agent-core:latest. And reproduce the SimpleQA setup on your own model before treating 86.08% as a property of the framework rather than of gpt-4.1-mini on that particular run.
Editorial conclusion
Adopt sgr-agent-core if you want a self-hosted research agent whose reasoning is constrained by a schema you control, and you are willing to run an OpenAI-compatible endpoint plus a Tavily key for search. Do not adopt it if you need a single-pass function-calling loop with no schema authoring, or if you cannot read the docs site to learn the schema format, because the README does not define it. Before committing, verify three things yourself: that the ACP block in config.yaml selects the agent you expect, that your model reproduces the SimpleQA accuracy reported for gpt-4.1-mini on your own data, and that the pinned ghcr.io/vamplabai/sgr-agent-core image tag you deploy is the one you reviewed.
Community notes