Open-source agentic framework for building intelligent research agents using Schema-Guided Reasoning. The project provides a core library with a extendable BaseAgent interface implementing a two-phase architecture and multiple ready-to-use research agent implementations built on top of it.
The library includes extensible tools for search, reasoning, and clarification, real-time streaming responses, OpenAI-compatible REST API. Works with any OpenAI-compatible LLM, including local models for fully private research.
- Schema-Guided Reasoning — SGR combines structured reasoning with flexible tool selection
- Multiple Agent Types — Choose from
SGRAgent,ToolCallingAgent, orSGRToolCallingAgent - Extensible Architecture — Easy to create custom agents and tools
- OpenAI-Compatible API — Drop-in replacement for OpenAI API endpoints
- Real-time Streaming — Built-in support for streaming responses via SSE
- Production Ready — Battle-tested with comprehensive test coverage and Docker support
Get started quickly with our documentation:
- Project Docs - Complete project documentation
- Framework Quick Start Guide - Get up and running in minutes
- DeepSearch Service Documentation - REST API reference with examples
The fastest way to get started is using Docker:
# Clone the repository
git clone https://github.com/vamplabai/sgr-agent-core.git
cd sgr-agent-core
# Create directories with write permissions for all
sudo mkdir -p logs reports
sudo chmod 777 logs reports
# Copy and edit the configuration file
cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/config.yaml
# Edit examples/sgr_deep_research/config.yaml and set your API keys:
# - llm.api_key: Your OpenAI API key
# - tools.web_search_tool.api_key: Your Tavily API key (optional)
# - tools.extract_page_content_tool.tavily_api_key: Your Tavily API key (optional)
# Run the container
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 8010The API server will be available at http://localhost:8010 with OpenAI-compatible API endpoints. Interactive API documentation (Swagger UI) is available at http://localhost:8010/docs.
If you want to use SGR Agent Core as a Python library (framework):
pip install sgr-agent-coreThe core install is small on purpose — pydantic, PyYAML, openai, httpx —
enough to define agents and tools and run them through sgrsh. Integrations are
opt-in extras: mcp, search (Tavily), server (the sgr HTTP API), acp,
langfuse. To get the full set:
pip install "sgr-agent-core[all]"See the Installation Guide for detailed instructions and the Using as Library guide to get started.
The project includes example research agent configurations in the examples/ directory. To get started with deep research agents:
- Copy and configure the config file:
cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/config.yaml
# Edit examples/sgr_deep_research/config.yaml and set your API keys:
# - llm.api_key: Your OpenAI API key
# - tools.web_search_tool.api_key: Your Tavily API key (optional)
# - tools.extract_page_content_tool.tavily_api_key: Your Tavily API key (optional)- Run the API server using the
sgrutility (needs theserverextra, plussearchfor the Tavily-backed research tools):
sgr --config-file examples/sgr_deep_research/config.yaml
# or use short option
sgr -c examples/sgr_deep_research/config.yamlNote: You can also run the server directly with Python:
python -m sgr_agent_core.server --config-file examples/sgr_deep_research/config.yaml
For interactive command-line usage, you can use the sgrsh utility:
# Single query mode
sgrsh "Найди цену биткоина"
# With agent selection (e.g. sgr_agent, dialog_agent)
sgrsh --agent sgr_agent "What is AI?"
# With custom config file
sgrsh -c config.yaml -a sgr_agent "Your query"
# Interactive chat mode (no query argument)
sgrsh
sgrsh -a sgr_agentThe sgrsh command:
- Automatically looks for
config.yamlin the current directory - Supports interactive chat mode for multiple queries
- Handles clarification and dialog (intermediate results) requests from agents
- Works with any agent defined in your configuration (e.g.
sgr_agent,dialog_agent)
For more examples and detailed usage instructions, see the examples/ directory.
Editors and tools that speak the Agent Client Protocol can run SGR agents over stdio (newline-delimited JSON-RPC), using the same YAML configuration as the HTTP server.
sgracp --config examples/sgr_deep_research/config.yamlOptional acp block in config.yaml selects which agents: entry to expose (if omitted, the first agent definition is used):
acp:
agent: sgr_agentProtocol details follow the official ACP specification, the Python SDK, and the agent-client-protocol package used by this binary.
Performance Metrics on gpt-4.1-mini:
- Accuracy: 86.08%
- Correct: 3,724 answers
- Incorrect: 554 answers
- Not Attempted: 48 answers
More detailed benchmark results are available here.
All development is driven by pure enthusiasm and open-source community collaboration. We welcome contributors of all skill levels!
- SGR Concept Creator // @abdullin
- Project Coordinator & Vision // @VaKovaLskii
- Lead Core Developer // @virrius
- API Development // @EvilFreelancer
- DevOps & Deployment // @mixaill76
- Hybrid FC research // @Shadekss
If you have any questions - feel free to join our community chat
This project is developed by the neuraldeep community. It is inspired by the Schema-Guided Reasoning (SGR) work and SGR Agent Demo
This project is supported by the AI R&D team at red_mad_robot, providing research capacity, engineering expertise, infrastructure, and operational support.
Learn more about red_mad_robot: redmadrobot.ai