The README says production ready, the manifest says alpha

Two status claims, one file each, no agreement

The feature list ends with a claim that production ready software gets: battle tested, with a test suite and Docker support.

The project manifest says something else. Its development status classifier is level three, Alpha.

Both can be true in a narrow sense, since an alpha can have good tests and a working container build, but a reader deciding whether to depend on this will read one or the other and act on it. Nothing in the repository reconciles the two.

The rest of the positioning is more precise. There is a core library with an extendable base agent interface implementing a two-phase architecture, and several ready-made research agent implementations on top of it. The agent types are named in the README: an SGR agent, a tool calling agent, and a third that combines both. The framework also provides extensible tools for search, reasoning and clarification, streaming responses over server sent events, and an HTTP API that is presented as a drop-in replacement for OpenAI endpoints, which is what lets it point at a local model instead of a hosted one.

The concept behind the name is one sentence: Schema-Guided Reasoning combines structured reasoning with flexible tool selection. The claims about what that buys you are in the marketing line rather than in a design document.

A secret key file sits at the repository root

The root of the repository contains a file named .webui_secret_key, and it is tracked, not ignored.

Next to it are the files you would expect: .env.example, which is a template full of placeholders for API keys, .dockerignore, .gitignore, and a pre-commit configuration. The contrast is the problem. The environment template is careful to hold nothing real, and one file above it holds something with key in the name.

Nothing in the visible documentation says what that file is for. There is a separate web interface project in the tree, a directory with a frontend in its name, so there is a plausible use for a signing secret in a session cookie or a token, but the repository does not connect the two.

The practical advice is narrow and obvious: if that file is a signing secret rather than a generated placeholder, it is already in the history for every clone, and rotating it is the only fix. If it is regenerated on every start, then its presence in the tree is untidy rather than dangerous, which is also worth knowing before someone assumes either way.

Either way it is the one file in the root a reviewer should ask about.

Four core dependencies, and a missing extra that explains itself

The core install is small on purpose, and the manifest says so in a comment rather than leaving you to infer it:

pip install sgr-agent-core
pip install "sgr-agent-core[all]"

The runtime dependencies are PyYAML, pydantic, pydantic settings, the openai client and httpx with the SOCKS extra enabled. That is enough to define an agent, give it tools, and point it at any OpenAI-compatible endpoint.

Everything else is an extra, and the comment explains the mechanism: the integrations are imported lazily, so a missing one surfaces as an actionable message at the point of use rather than as an import error at start-up. There is a module in the package whose job is that behaviour.

The extras the README names are the MCP protocol, search through Tavily, the server that provides the HTTP API, the agent client protocol, and Langfuse, with an all group covering the set. The container build uses a sixth one the README does not list: it installs the examples extra, and the Dockerfile comment says that group chains to all and adds what the bundled examples need. So a user reading the documentation sees five integrations and a user building the image gets six.

The SOCKS extra on httpx is not accidental either. The environment template ships a commented proxy line pointing at a local SOCKS address, so running the whole stack through a local proxy is an anticipated setup rather than an accident.

Two configuration surfaces with two naming conventions

The same settings can be expressed two ways, and the two do not use the same key names.

The example configuration the quick start asks you to copy is nested YAML: an LLM section with an API key, a web search tool section with its own API key, and a page content extraction tool section with a Tavily key of its own. Two different tools each take the same Tavily credential under different names, which is the first sign that these sections are written by tool rather than by service.

The environment template uses a flat convention instead, a prefix, a section and a field, so an LLM API key and a search Tavily key sit side by side. It documents the convention at the top with two examples, which is the kind of detail that saves an afternoon.

What both surfaces agree on is the execution budget, and that is the most useful block in the template. Maximum steps is six, maximum clarifications is three, maximum iterations is ten, maximum searches is four, and there is a context limit for MCP output. The search block adds a result cap of ten, a page cap of five and a content limit of 1,500 characters. An agent that can clarify with you three times and search four times is a research agent with a short leash, deliberately.

One small inconsistency: the template's default model is one mini variant, and the published benchmark was run on a different one.

The Docker quick start stops before the compose command

The section that claims to be the fastest way in starts with four steps, and none of them is the one you expect.

It clones the repository, changes into it, creates a logs directory and a reports directory with a recursive permission change to 777, and copies an example configuration file to be edited with your API keys. Then the fence closes.

There is no compose invocation in that block, and no image build. The compose file is in the repository, named for a distribution build, and the Dockerfile beside it is a two stage build, so both routes exist. What the visible quick start does not do is show you which of them to run.

The permission change is worth a second look. Creating those two directories as world writable is the documented first step, and the container is then expected to write reports into them. A named volume or a directory owned by the container's own user would be tidier, and 777 is a habit from running as root in development.

After the block, the documentation does say where things end up: the API server on port 8010 with OpenAI-compatible endpoints, and interactive documentation at the docs path on the same port.

The runner image ships bubblewrap and a user with no shell

Two details in the container build describe what the agent is allowed to do.

The runtime stage installs bubblewrap alongside curl and the certificate bundle, and the comment names the reason: a run command tool has a safe mode. So the framework can execute shell commands, and when it does, the container provides the sandbox. That is a reasonable design, and putting the sandbox in the image rather than requiring it on the host means a containerised deployment inherits it.

The second detail is the user. The build creates a group and then a system account with uid 1000, no home directory, and /bin/false as the login shell. A false shell is the standard way to make an account that exists only to own files and cannot be logged into, which is right for a service image.

The builder stage does the opposite and then cleans up: it installs a compiler toolchain to build the package, installs the package with the examples extra, and then purges the build dependencies and the package cache. The version needs its own trick, because the build context has no git directory, so the build takes the version as an argument and hands it to the versioning tool as a pretend value, with a zero fallback that keeps local builds without a tag working.

Together those three details describe an image meant to run untrusted generated code, which is the honest requirement for a research agent.

The accuracy figure is arithmetically sound, on 4,326 answers

The benchmark section is four numbers, and they add up. Accuracy is given as 86.08 percent, with 3,724 answers correct, 554 incorrect and 48 not attempted. Those four add to 4,326, and 3,724 divided by 4,326 is 86.08 percent, so the accuracy is computed over everything including the questions the agent declined.

That is a stricter denominator than excluding unattempted answers would be, and publishing the not attempted count separately makes the choice visible. The benchmark is a well known question answering set, and the detailed results live in a document in the repository. The model used is a small variant, and it is not the one in the environment template, so the two numbers are not directly comparable.

The rest of the README is about the people. Six roles are listed with names and contact handles: the concept creator, the project coordinator, the lead core developer, API development, DevOps and deployment, and research. The framing is that all development is community driven, and the acknowledgements credit the community the project came out of and the earlier work it was inspired by.

Two small things a reader will notice. The example query in the CLI section is in Russian, inside an English document. And the build file uninstalls two distributions, the package and one literally named UNKNOWN, which is the fingerprint of a stray build artefact directory that was never cleaned up.

Editorial conclusion

sgr-agent-core is a coherent framework if you are building a research agent that needs to search, ask clarifying questions and stream results, because the two-phase base interface, the three agent types and the three runtimes cover the same agents from a server, a terminal and an editor. What to check first is the status, since the manifest calls it alpha and the feature list calls it production ready, and that gap should decide how much you depend on it. Second, the committed secret key file at the repository root, whose purpose is undocumented and which, if it is a signing secret, is already public. Third, the agent's own limits, which are the real design decision here: six steps, three clarifications, ten iterations and four searches, with a 1,500 character content cap per page, mean this is a tool for bounded questions rather than open-ended research. On the positive side, the optional dependency handling is the best engineering in the repository, with a lazy import that fails with a message pointing at the extra to install.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vamplabAI/sgr-agent-core on GitHub