DOCSEARCHbyAlgolia
Submit Docs

SGR Agent Core

repository·main·Indexed 22 days ago

https://github.com/vamplabai/sgr-agent-core

An open-source agentic framework for Schema-Guided Reasoning (SGR) used to build intelligent research agents. It features a two-phase architecture combining structured reasoning with flexible tool selection, supporting OpenAI-compatible REST APIs, real-time streaming, and multimodal messages (text and images). Key capabilities include Progressive Tool Discovery to prevent LLM context bloat via the ProgressiveDiscoveryAgent, SearchToolsTool, and ToolFilterService.

Tokens
55.9K
Snippets
174
Records
228
Agent score
77%

What's inside sgr-agent-core

  1. Overview of SGR Deep Research Tools

    main

    Tools in the SGR Deep Research framework are categorized into two types:

    1. System Tools: Essential tools required for the research agent to function. Without these, the agent cannot perform core reasoning or task completion.
    2. Auxiliary Tools: Optional tools that extend the agent's capabilities (e.g., web searching, command execution).
    ItemCategoryDescription
    ReasoningToolSystemDetermines the next reasoning step for Schema-Guided Reasoning agents
    FinalAnswerToolSystemCompletes the research task and updates agent state
    CreateReportToolSystemGenerates a detailed research report with inline citations and saves it to disk
    ClarificationToolSystemAsks clarification questions and pauses execution until a user responds
    GeneratePlanToolSystemCreates an initial research plan and breaks requests into steps
    AdaptPlanToolSystemUpdates an existing research plan based on new information
    WebSearchToolAuxiliaryWeb search powered by Tavily Search API
    ExtractPageContentToolAuxiliaryExtracts full content from web pages using Tavily Extract API
    RunCommandToolAuxiliaryExecutes shell commands in safe or unsafe mode within a workspace boundary

  2. SGR Agent Core API Overview

    main

    SGR Agent Core provides a REST API that is fully compatible with the OpenAI API format. This allows for easy integration with existing LLM-based applications.

    Base URL: http://localhost:8010

    Interactive Documentation: You can access the Swagger UI for exploring endpoints and testing requests at http://localhost:8010/docs.

    Authentication: The API does not support built-in authentication. For production environments, it is recommended to use a reverse proxy to handle authentication.

  3. What is an Agent Skill and how to structure it

    main

    An Agent Skill is a directory containing a SKILL.md file that follows the Anthropic model for progressive disclosure. This allows the agent to know a skill exists (Level 1) without bloating the context, only loading the full instructions (Level 2) when the skill is actually invoked.

    Skill Directory Structure

    skills/
  pdf-processing/
    SKILL.md            # Required: contains YAML frontmatter and Markdown body
    scripts/            # Optional: bundled resources (Level 3)
    references/         # Optional: reference files

    SKILL.md Frontmatter (YAML)

    The SKILL.md must include a YAML frontmatter block. The following fields are supported:

    FieldRequiredNotes
    nameYes$\le$ 64 chars; lowercase letters, digits, hyphens only; no XML tags; cannot be "anthropic" or "claude"
    descriptionYesNon-empty; $\le$ 1024 chars; no XML tags; written in third person; describes what it does and when to use
    licenseNoSPDX id or text
    allowed-toolsNoAdvisory allowlist of tool names the skill uses
    metadataNoFree-form dictionary (e.g., version, author)

    Progressive Disclosure Levels

    1. Level 1 (Metadata): name and description are injected into the system prompt so the LLM can decide to use the skill.
    2. Level 2 (Body): The Markdown body of SKILL.md is loaded into the conversation context only upon invocation.
    3. Level 3 (Bundled Files): Scripts or resources in the skill directory, referenced in the body and loaded on demand.
    # Example SKILL.md
---
name: pdf-summarizer
description: Summarizes long PDF documents into concise bullet points. Use this when the user provides a PDF file.
license: MIT
allowed-tools:
  - file_reader
---

# Instructions
To summarize a PDF, first use the `file_reader` tool to get the text, then...

  4. What is SGR Agent Core and its core concepts?

    main

    SGR Agent Core is an open-source agentic framework designed for Schema-Guided Reasoning (SGR). It combines structured reasoning with flexible tool selection to build intelligent research agents.

    Key Concepts:

    • Three-Phase Architecture: The core BaseAgent interface implements a structured three-phase reasoning process.
    • Agent Types: The framework provides different agent implementations, including SGRAgent, ToolCallingAgent, and SGRToolCallingAgent.
    • Extensibility: Developers can create custom agents by subclassing BaseAgent and custom tools to expand agent capabilities.
    • OpenAI Compatibility: The framework provides an OpenAI-compatible REST API and supports any OpenAI-compatible LLM (including local models).
    • Real-time Streaming: Built-in support for streaming responses via Server-Sent Events (SSE).

  5. Configure agent base_class with relative imports

    main

    In your agent configuration, the base_class field supports relative imports. If the config file is in the same directory as your agent classes, you can use a relative path instead of an absolute path. The system resolves these relative to the config.yaml location.

    agents:
  sgr_agent:
    base_class: "agents.ResearchSGRAgent"  # Relative to config.yaml location

  6. How the Agent execution cycle works

    main

    In the SGR framework, an Agent follows a ReAct (Reasoning + Action) execution cycle. The core logic is driven by the BaseAgent class, which implements a two-phase (or three-phase) loop:

    1. Reasoning Phase: The agent evaluates the current context and plans the next steps.
    2. Select Action Phase: The agent selects the most suitable tool based on the reasoning.
    3. Call Action Phase: The agent executes the selected tool.

    The loop continues until the agent reaches a terminal state (FINISH_STATES).

    while agent.state not in FINISH_STATES:
    reasoning = await agent._reasoning_phase()
    action_tool = await agent._select_action_phase(reasoning)
    await agent._action_phase(action_tool)

  7. How autonomous skill invocation works

    main

    The agent uses a tool called use_skill to perform autonomous invocation. This process follows these steps:

    1. Catalog Injection: The agent's system prompt includes an <AVAILABLE_SKILLS> block containing a numbered list of name: description for all discovered skills.
    2. Decision: The LLM identifies a task that matches a skill's description.
    3. Invocation: The LLM calls the use_skill tool, passing the skill_name as an argument.
    4. Context Loading: The SkillTool looks up the skill in the SkillRegistry, retrieves the Level-2 Markdown body from the SKILL.md file, and returns it as a tool result. This body is then appended to the conversation context for the remainder of the session.

    Note: If an unknown skill name is provided, the tool returns a helpful error message listing the currently available skills.

    // Example tool call from the LLM
{
  "tool": "use_skill",
  "arguments": {
    "skill_name": "pdf-summarizer"
  }
}

  8. How tool resolution works

    main

    When an agent references a tool by name in a configuration file, the system resolves it using the following order:

    1. Tools section: Tools explicitly defined in the tools: section of the configuration.
    2. ToolRegistry: Tools registered in the ToolRegistry (by name or PascalCase class name).
    3. Auto-conversion: Automatic conversion from snake_case to PascalCase (e.g., web_search_tool becomes WebSearchTool).

    Note: If you are using custom agents or tools, ensure they are imported/located within the project so they are added to the ToolRegistry. Failure to do so results in: ValueError: Agent base class 'YourOwnAgent' not found in registry.

  9. How tool display components are routed in the chat interface

    main
    The chat interface uses a router-based architecture for displaying tool outputs. ChatMessageStep.vue serves as the central router component. It inspects the tool type of a given step and delegates the actual rendering to a specialized component (e.g., WebSearchToolDisplay.vue for searches or ReasoningToolDisplay.vue for planning). This modular approach ensures that each tool's unique data structure is handled by a component with a single responsibility.

  10. Use IronAgent for models without tool-calling support

    main
    If you are using a model that does not support native tool calling or structured output, use the IronAgent base class. IronAgent is designed to work with raw model responses by manually extracting tool names and parameters and handling retries on failure.

  11. What are Agents with Disabled Reporting?

    main

    Agents with disabled reporting are specialized versions of research agents that exclude the CreateReportTool from their toolkit.

    Key Characteristics:

    • No Report Generation: They do not generate report files in the reports_dir.
    • Tooling: They still use standard tools like WebSearchTool, ExtractPageContentTool, and FinalAnswerTool.
    • Termination: When max_iterations is reached, only FinalAnswerTool is available (standard agents would also have CreateReportTool).
    • Configuration: The reports_dir setting in your config is ignored by these agents.

    Available Agents in this category:

    • ResearchSGRAgentNoReporting
    • ResearchToolCallingAgentNoReporting
    • ResearchSGRToolCallingAgentNoReporting

  12. Security considerations for Skills

    main

    Skills are treated as trusted content, similar to config.yaml or custom tool code. When a skill is invoked, its body is injected verbatim into the model context.

    Warning: Because the agent automatically scans ./.agent/skills and ~/.agent/skills, opening a repository that contains a .agent/skills/ directory will automatically load those instructions. Only run skills from sources you trust and review SKILL.md files before use.