SGR Agent Core
Build research agents with structured reasoning, tool use, and a self-hosted API.
The README identifies principal inputs and effects such as OpenAI/Tavily keys, external search, a network API, logs, and reports, while the team and conceptual inspirations are attributed clearly. Deductions apply because no per-action confirmation, credential-storage or redaction controls, complete data-flow account, tool permission isolation, or robust recovery design is shown. The Docker instructions use chmod 777, bind to 0.0.0.0, and reference a mutable latest image. Dependencies have broad lower bounds, workflow actions are not commit-pinned, and no vulnerability scanning or other supply-chain control is evidenced.
The README, pyproject, and ACP tests agree on entry points, supported Python environments, and several ACP configuration behaviors, and dependencies are explicitly declared. Deductions apply because the package is classified Alpha while the README calls it production-ready and battle-tested; the supplied tests cover only limited ACP/configuration paths and cannot substantiate that broader claim. Failure evidence is largely limited to ValueError rejection of unknown options, without demonstrated user-facing diagnostics, retries, or graceful degradation.
Developer and research audiences, research-agent scenarios, three agent variants, HTTP/CLI/ACP interfaces, replaceable models, and configurable execution limits are described well. Deductions apply because tool safety boundaries, supported versus unsupported tasks, and complete activation conditions are not defined. Python 3.11–3.13, Docker, and local compatible models provide useful environment coverage, but platform differences, resource needs, and deployment-hardening requirements are absent.
The README is well organized and provides Docker, pip, server, CLI, and ACP examples. Package names, command entry points, authors, issue tracking, documentation, and team roles are explicit, and the full MIT license agrees with package metadata. Deductions apply because the supplied revision has no FAQ or substantive limitations section; Alpha classification and the license disclaimer provide only thin limitation disclosure. Git-tag-derived versioning and a release command are documented, but no changelog is supplied, and naming varies among forms such as SGRAgent, sgr_agent, and SGR Agent Core.
Streaming, an OpenAI-compatible API, CLI and ACP access, report output, and configurable agent variants support usable integration outputs. Schema-guided reasoning and extensible tools plausibly add value beyond a basic single-turn wrapper. Deductions apply because the supplied evidence omits the core implementation and referenced benchmark report, leaving the 86.08% accuracy and production-readiness statements as repository assertions. Apart from optional Tavily use, local-model support, and execution limits, latency, token, monetary, and operational costs are not analyzed.
Core feature descriptions are partially cross-checked among the README, pyproject entry points, and ACP unit tests, and the benchmark claim names a specific results file. Deductions apply because that results file, the core implementation, and the complete documentation are absent from the supplied evidence, preventing static tracing of most safety, performance, and production-readiness claims. Marketing assertions, directly tested facts, and inference are not consistently separated, and no independent corroboration is present.
- Do not copy the chmod 777 instruction onto shared or production hosts; use minimal filesystem permissions and add authentication, network isolation, and reverse-proxy controls before exposing 0.0.0.0.
- Do not commit API keys to configuration or images. Before deployment, verify secret injection, log redaction, report retention, and external transmission paths involving services such as OpenAI, Tavily, and Langfuse.
- Pin container digests and dependency versions and add dependency vulnerability and supply-chain scanning; do not rely on the mutable latest image.
- Treat the production-ready statement and 86.08% benchmark as unverified by the supplied static material; package metadata still classifies the project as Alpha.
- Before enabling search or other tools, add explicit effect disclosure, confirmation for sensitive actions, timeout and retry policies, and recoverable operation paths.
What does this agent do, and when should you use it?
SGR Agent Core is an open-source research-agent framework built around Schema-Guided Reasoning, an extensible BaseAgent interface, and a two-phase architecture. It includes SGRAgent, ToolCallingAgent, and SGRToolCallingAgent, along with tools for search, reasoning, and clarification. The project can be installed as a Python library or deployed as a REST service with OpenAI-compatible endpoints and SSE streaming. Users can also interact through the sgrsh terminal client or expose an agent to editors and tools through sgracp and the stdio-based Agent Client Protocol. It works with OpenAI-compatible LLMs, including local models for private research, while Tavily can optionally supply web search and page extraction.
The user selects an agent under the YAML agents: configuration and supplies an OpenAI-compatible model plus any optional tools. SGRAgent, ToolCallingAgent, or SGRToolCallingAgent accepts a research query, organizes Schema-Guided Reasoning through BaseAgent's two-phase architecture, and invokes configured search, page-extraction, reasoning, or clarification tools. During execution, it can request clarification or return intermediate dialog results, while SSE provides real-time response delivery. The completed output is exposed through an OpenAI-compatible REST API, an sgrsh session, or newline-delimited JSON-RPC over stdio with sgracp; the Docker example also persists logs and reports in mounted directories.
- An engineering team that needs an internally hosted research service can run the Docker image, expose an OpenAI-compatible API, and persist logs and reports on the host.
- A Python developer embedding research workflows in an application can install sgr-agent-core and extend BaseAgent with custom agents and tools.
- A team with an existing OpenAI API client can point it at the compatible service endpoints and consume streamed results over SSE.
- An organization handling sensitive queries can pair the framework with a local OpenAI-compatible model for fully private research.
- A terminal user conducting iterative investigations can use sgrsh for one-off questions or interactive chat with clarification handling.
- A developer using an Agent Client Protocol editor or tool can launch a configured SGR agent over stdio with sgracp.
What are this agent's strengths and limitations?
- One project supplies a Python framework, OpenAI-compatible REST service, SSE streaming, interactive CLI, and ACP-over-stdio interface.
- Teams can choose SGRAgent, ToolCallingAgent, or the combined SGRToolCallingAgent and extend BaseAgent with their own agents and tools.
- Support for OpenAI-compatible models includes local models, enabling a fully private research deployment path.
- A published Docker image, sample configuration, Swagger UI, and stated comprehensive test coverage reduce initial deployment and evaluation work.
- End-to-end online research still requires a model service and its credentials; the example also needs separate Tavily credentials when its search or extraction tools are enabled.
- The Docker quick start grants mode 777 to the logs and reports directories, which security-conscious deployments will likely need to replace with tighter ownership and permissions.
- OpenAI API compatibility does not establish native integration with ChatGPT, Claude AI, Claude Code, or the Claude API; none is documented in the supplied material.
- The published SimpleQA result covers only gpt-4.1-mini and does not provide comparative evidence for other models, private datasets, or production workloads.
How do you install or deploy this agent?
For the Python library, run pip install sgr-agent-core. Prepare the research configuration with cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/config.yaml, then set llm.api_key. If Tavily-backed search or page extraction is enabled, also set tools.web_search_tool.api_key and tools.extract_page_content_tool.tavily_api_key.
For Docker, run git clone https://github.com/vamplabai/sgr-agent-core.git, followed by cd sgr-agent-core. Create writable locations with sudo mkdir -p logs reports and sudo chmod 777 logs reports. After copying and editing the configuration, run 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. The service is then available at http://localhost:8010, with Swagger UI at http://localhost:8010/docs.
How do you use this agent?
After configuration, start the server with sgr --config-file examples/sgr_deep_research/config.yaml or sgr -c examples/sgr_deep_research/config.yaml. The documented Python entry point is python -m sgr_agent_core.server --config-file examples/sgr_deep_research/config.yaml. For a first CLI request, run sgrsh -a sgr_agent "What is AI?"; running sgrsh -a sgr_agent without a query starts interactive mode. For ACP clients, run sgracp --config examples/sgr_deep_research/config.yaml. An optional acp: {agent: sgr_agent} configuration selects the exposed agent; otherwise, the first definition under agents: is used.
How does this agent compare with similar options?
The framework offers three internal approaches: SGRAgent for Schema-Guided Reasoning, ToolCallingAgent for tool-calling behavior, and SGRToolCallingAgent for a hybrid of the two. The supplied material does not provide a detailed performance or suitability comparison among them, nor a direct comparison with external frameworks.
FAQ
Must I use an OpenAI-hosted model?
Is Tavily mandatory?
How can clients receive research results?
What filesystem permissions does the deployment need?
chmod 777; production operators should substitute permissions appropriate to their container and security policy.