strato-sdk

README

Strato SDK

English | 中文

Strato SDK is a ready-to-use deep research (DeepResearch) solution designed to address the lack of unified research tools in current software development. Based on the "Master Agent + Domain Agent" pattern, it provides capabilities such as task decomposition, streaming result merging, and multi-tool invocation, aiming to help developers quickly integrate deep research and DeepResearch Agent capabilities. The framework is organized from four levels: tasks, planning, execution strategies, and specific implementation. By default, it provides multiple predefined APIs to quickly respond to user's search agent development needs, and users can also.

Core Features

1. Host Multi-Agent Architecture

Strato adopts an advanced Host Multi-Agent architecture. When receiving complex user requests, the MasterAgent acts as the central command, coordinating multiple DomainAgents with different domain expertise for processing:

• Task Analyzer: Uses Large Language Models (LLM) to deeply analyze and decompose user requests, breaking them down into a series of subtasks.
• Intelligent Routing: Based on the characteristics of subtasks, precisely assigns them to the most suitable DomainAgent (e.g., database query tasks are assigned to DataAgent, network research tasks to ResearchAgent).
• Stream Merger: Real-time collection of all thought streams and intermediate results generated by DomainAgents during execution, outputting through a unified streaming channel.
• Result Merger: After all tasks are completed, aggregates the final outputs of all DomainAgents, and generates a comprehensive, coherent final report through LLM.

2. MCP Tool Auto-Discovery and Automatic Management

Strato supports Model Context Protocol (MCP), greatly simplifying tool usage.

• Automatic Lifecycle Management: Developers only need to declare required MCP services (such as databases, APIs, etc.) in the configuration file, and the SDK will automatically manage the startup, health checks, and shutdown of these services without manually writing process management code.

• Seamless Tool Invocation: DomainAgents can interact with external tools through MCP like calling local functions, with the SDK handling underlying communication protocols and data conversion.

3. Unified Streaming Processing Architecture

Whether it's Agent thinking processes, tool invocations, or final result generation, Strato adopts streaming design throughout.

• Real-time Feedback: Through Go Channels, every step of the application (task start, strategy selection, error messages, final results) is pushed to the caller in real-time.
• Non-blocking Concurrency: Fully utilizes Go's concurrency features, allowing multiple DomainAgents to execute tasks in parallel for maximum processing efficiency.

4. Domain Expertise and Extensibility

Strato's core design philosophy is "professional division of labor". We encourage developers to build DomainAgents dedicated to solving specific domain problems.

• Pre-built Domain Agents: The SDK includes built-in DataAgent for data analysis and ResearchAgent for deep network research.
• Standard Interface: All DomainAgents follow unified interface standards, allowing developers to easily create and register custom Agents to extend system capabilities, such as code generation, image understanding, etc.

5. Plugin-based Adapters and Strategy-Driven

The system's high configurability is achieved through its decoupled adapter and strategy patterns.

• Multi-layer Adapters: External services such as LLM, search engines, and web content extraction are all integrated through adapters. Replacing or adding services only requires implementing the corresponding interface.
• Execution Strategy-Driven: Whether it's breadth-first network search, hybrid engine strategies, or step planning for data analysis, all can be precisely controlled through strategies.

Architecture Design

Host Agent Framework

Strato SDK adopts a layered architecture design of Master Agent and Agent Pools. At the code level, it still uses registration methods to facilitate user extension of custom functionality. The overall DeepSearch data processing flow is as follows:

1. Task Decomposition Process:

   • User Input: The system receives user research query requests
   • Analysis Task: Master Agent performs deep analysis of user requests to understand research intent
   • Decompose Task: Intelligently decomposes complex research tasks into multiple subtasks that can be executed in parallel
   • Assign Sub Task: Based on task characteristics and agent capabilities, assigns subtasks to appropriate execution agents

2. Execution Strategy Layer:

   • Execute Agent: Selects or creates specialized execution agents from the agent pool
   • Custom Execute Strategy: Supports customized execution strategies for different types of tasks
   • Execute Tools: Execution agents can invoke predefined tool sets, including:
     • Custom: Custom tools supporting extension of specific domain capabilities
     • Retrieve: Information retrieval tools including search engines, database queries, etc.
     • Data Process: Data processing tools supporting data cleaning, analysis, transformation, etc.

3. Result Aggregation Process:

   • Execute Result: Intermediate results produced by various execution agents
   • Aggregate Result: Master Agent intelligently aggregates all subtask results to generate the final research report

The advantages of this architectural design:

• Parallel Processing Capability: Multiple subtasks can be executed simultaneously by different agents, greatly improving research efficiency
• Flexible Extensibility: Agent pool supports dynamic registration of new agents, tool set supports plugin-based extension
• Intelligent Scheduling: Master Agent can perform intelligent task assignment based on task characteristics and agent capabilities
• Fault Tolerance Mechanism: Individual agent failures don't affect the overall task, supports automatic retry and degradation strategies

Core Component Relationships

User Query
    ↓
MasterAgent (Master Control Agent)
    ├── TaskAnalyzer (Task Analyzer)
    │   └── LLM (Task decomposition and routing)
    ├── StreamMerger (Stream Merger)
    ├── ResultMerger (Result Merger)
    └── DomainAgents (Domain Agent Pool)
        ├── DataAgent (Data Agent)
        │   ├── MCPAgentBase (MCP Base Framework)
        │   │   ├── MCP Tool Pool (PostgreSQL, API, etc.)
        │   │   ├── Strategy Manager (Three-tier strategy selection)
        │   │   └── Execution Engine (Concurrent execution)
        │   └── Streaming Output → StreamMerger
        └── ResearchAgent (Research Agent)
            ├── StreamingResearchAgent (Streaming Research Engine)
            │   ├── LLM (Question generation and analysis)
            │   └── Multi-round iteration control
            ├── SearchTool (Search Tool)
            │   ├── SearchStrategy (Search Strategy)
            │   │   ├── MixedStrategy (Mixed Search)
            │   │   └── FallbackStrategy (Fallback Search)
            │   └── SearchAdapters (Firecrawl, SearxNG, Twitter)
            ├── WebProcessTool (Content Processing Tool)
            │   ├── WebStrategy (Processing Strategy)
            │   └── WebAdapters (Jina, Firecrawl)
            └── Streaming Output → StreamMerger

Research Process State Machine

START 
  → checkCompletion (Check completion conditions)
      ├→ generateQuestions (Generate sub-questions)
      │    └→ incrementIteration → checkCompletion
      ├→ selectQuestion (Select question)
      │    └→ searchQuestion → scrapeWebContent → analyzeQuestion → checkCompletion
      └→ synthesizeFinalAnswer (Synthesize answer) → END

Core Components

ResearchAgent

Intelligent Multi-round Iterative Research

• Adaptive Question Generation: LLM-based intelligent sub-question generation with deduplication and similarity detection
• Priority-driven Scheduling: Intelligent research order selection based on question priority (1-10)
• Dynamic Iteration Control: Support for maximum iterations, minimum question count, step allocation and other fine-grained controls
• Early Termination Judgment: LLM intelligently determines if information is sufficient to avoid over-research

Plugin-based Adapter Architecture

• Factory Pattern + Registry Pattern: True plugin design supporting dynamic loading at runtime
• Multi-layer Adapter System: MCP execution, search adapters, Web processing adapters, and LLM adapters are completely decoupled
• Unified Interface Standards: All adapters implement standard interfaces, easy to extend to new platforms

Execution Strategy-Driven

• Strategy Pool Management: Support for multiple strategies coexisting, dynamic selection of optimal strategies
• Hybrid Search Strategy: Concurrent calls to multiple search engines and execution tools, intelligent deduplication and result aggregation
• Intelligent Degradation Mechanism: Support for automatic fallback when engines fail
• MCP Protocol Support: Native support for Model Context Protocol, enabling standardized tool invocation

DomainAgent

1. MCP Tool Registration and Signature Auto-Discovery

DataAgent Registration Process

• DataAgent inherits from MCPAgentBase and automatically reads MCP services (such as PostgreSQL) from the configuration file during initialization.

• During initialization, DataAgent automatically registers and obtains all available MCP tools (such as databases, APIs, etc.) through the global MCP connection pool.

• Each MCP tool (such as database) is managed through MCPClientWrapper, automatically obtaining its tool signatures (i.e., all supported operations/functions) without manual maintenance.

2. MCP Tool Invocation Strategy Auto-Planning

The process provides user-defined strategies and can also automatically plan strategies in specified formats through tool signatures provided by MCP.

Intelligent Strategy Auto-Planning

• Each MCP tool can be configured with dedicated execution strategies (such as intelligent data analysis, SQL generation, etc.).

• If not specified, the Agent will automatically assign "auto-generated strategy" for each MCP tool, where LLM automatically plans invocation steps based on tool signatures and task content.

• Strategy instances are registered to InstanceManager, with each MCP tool having independent strategy instances.

3. MCP Three-tier Strategy Selection Mechanism

Three-tier Priority

1. MCP-level Strategy: Prioritize using strategies configured by the MCP service itself (e.g., a specific database specifies using "intelligent analysis" strategy).

2. Agent Default Strategy: If MCP doesn't specify, use Agent-level default strategy (e.g., DataAgent defaults to "data analysis" strategy).

3. Auto-generated Strategy: If neither is specified, automatically adopt "auto_generated" strategy, where LLM dynamically plans invocation steps based on tool signatures and task content.

Automatic Degradation and Fallback Mechanism

• If a strategy execution fails, the Agent will automatically try other available strategies or backup MCP tools, implementing intelligent degradation (Fallback).

• Multiple MCP tools can execute concurrently with automatic result aggregation, improving robustness and efficiency.

4. Tool Signatures and Automatic Reasoning

• All signatures of MCP tools (such as all tables in a database, all methods of an API) are automatically pulled and cached during registration.

• When LLM automatically plans strategies, it combines tool signatures, task content, and historical context to intelligently generate optimal invocation chains (such as first querying table structure, then generating SQL, then executing analysis).

• For example, when DataAgent receives a task to "analyze sales data from the past two years", it will automatically:

  1. Get database table structure (tool signatures)
  2. Generate appropriate SQL
  3. Execute query and get results
  4. Analyze results and generate report

Supported Search Platforms

Platform	Type	Status
Firecrawl	Web Search & Content Extraction	✅
Jina AI	Web Content Extraction	✅
Twitter/X	Social Media Search	✅
SearxNG	Self-hosted Aggregated Search	✅
Xiaohongshu	Social Media	🚧
Bing	Search Engine	🚧
Google	Search Engine	🚧

Quick Start

Installation

go get github.com/anboat/strato-sdk@latest

Project Usage

func main() {
	// --- 1. Initialization ---
	cfg := config.LoadConfig("resources/config/config.yaml")
	if cfg == nil {
		fmt.Println("Failed to load configuration")
		return
	}
	logging.InitLoggerFromConfig(&cfg.Log)
	ctx := context.Background()

	// --- 2. Initialize Global MCP Pool ---
	err := mcp.InitGlobalMCPPool(ctx)
	if err != nil {
		logging.Fatal("Failed to initialize global MCP pool", zap.Error(err))
	}
	logging.Infof("Global MCP pool initialized successfully")

	// --- 3. Initialize MasterAgent and its components ---
	masterAgent, err := master.NewMasterAgentFromConfig(ctx, &cfg.Agents)
	if err != nil {
		logging.Fatal("Failed to create MasterAgent", zap.Error(err))
	}
	logging.Infof("MasterAgent created successfully")

	// --- 4. Initialize and Register Domain Agents ---
	// The LLM Wrapper is needed for the individual agents
	llmWrapper, err := llm.GetDefaultChatModelWrapper(ctx)
	if err != nil {
		logging.Fatal("Failed to get default LLM wrapper", zap.Error(err))
	}

	// Initialize DataAgent if enabled
	if cfg.Agents.DataAgent.Enabled {
		dataAgent := data.NewDataAgent()
		// Use the new Initialize method that automatically gets global MCP pool
		if err := dataAgent.Initialize(ctx, &cfg.Agents.DataAgent); err != nil {
			logging.Fatal("Failed to initialize DataAgent", zap.Error(err))
		}
		// Set the LLM client for the agent
		if err := dataAgent.SetLLM(llmWrapper); err != nil {
			logging.Fatal("Failed to set LLM for DataAgent", zap.Error(err))
		}
		masterAgent.RegisterAgent(dataAgent)
		logging.Infof("DataAgent registered successfully")
	}

	// Initialize ResearchAgent if enabled
	if cfg.Agents.ResearchAgent.Enabled {
		researchAgent := research.NewResearchAgentAdapter()
		if err := researchAgent.Initialize(ctx, &cfg.Agents.ResearchAgent); err != nil {
			logging.Fatal("Failed to initialize ResearchAgent", zap.Error(err))
		}
		// Set the LLM client for the agent
		if err := researchAgent.SetLLM(llmWrapper); err != nil {
			logging.Fatal("Failed to set LLM for ResearchAgent", zap.Error(err))
		}
		masterAgent.RegisterAgent(researchAgent)
		logging.Infof("ResearchAgent registered successfully")
	}

	// --- 5. Create and Process a Complex Mixed Task ---
	complexQuery := `I want to understand what tables are in the database, then analyze and query sales and order-related data from the past two years, and generate a sales analysis report based on online sales report formats`

	// Create task using the simplified Task structure (no Type field)
	task := types.NewStreamingTask(complexQuery)

	logging.Infof("Processing complex mixed task: %s", task.Query)
	displayHeader("Master Agent", "Task Analysis & Decomposition")

	// Process the task
	handle, err := masterAgent.ProcessTask(ctx, task)
	if err != nil {
		logging.Fatal("Failed to process task", zap.Error(err))
    }
}

Please refer to example_main.go for details

Configuration Guide

1. Custom MCP Configuration

mcp:
  # Global MCP settings
  global:
    default_timeout: "30s"                 # Default timeout for MCP servers
    max_retries: 3                         # Maximum retries when MCP operations fail
    retry_delay: "1s"                      # Delay between retries
    health_check_enabled: true             # Whether to enable MCP server health checks

  # Centralized MCP server definitions - Complete configuration for all MCP servers
  servers:
    # PostgreSQL database MCP server
    postgresql:
      type: "postgresql"                     # Server type
      description: "PostgreSQL database operation server"
      command: [ "npx" ]  # Startup command
      args:
        - "-y"
        - "@modelcontextprotocol/server-postgres"
        - "postgresql://username:password@localhost:5432/database"
      env:
        DATABASE_URI: "postgresql://username:password@localhost:5432/database"
      timeout: "30s"             

agents:
   data_agent:
    enabled: true                        # Whether to enable Data Agent
    name: "data_agent"                   # Data Agent name identifier
    domain: "data"                       # Agent domain: data (data operations)
    description: "Data operation domain Agent"      # Agent functionality description
    default_strategy: "default_database_strategy"  # Default strategy for this Agent, used if MCP server doesn't specify strategy
    capabilities:
      - "Data query"
      - "Database operations"
      - "File processing"
      - "Excel operations"
      - "SQL query"
      - "Data analysis"
      - "Data export"
      - "File system operations"
      - "database query"
      - "file processing"
      - "SQL query"
      - "data analysis"
    
    # MCP server reference configuration - Reference globally defined MCP servers and specify Agent-specific strategies
    mcp_servers:
      # PostgreSQL database server reference
      postgresql:
        enabled: true                   # Temporarily disabled, enable when needed
        server_ref: "postgresql"         # Reference to postgresql server in global MCP config
        strategy: "intelligent_analysis"  # Specific strategy when this Agent uses this MCP server

2. Configure Mixed Search Strategy

# config.yaml
search:
  strategy:
    breadth: 5                     # Each engine returns 5 results
    mixed_engines:                 # Use multiple search engines concurrently
      - "firecrawl"
      - "searxng"
      - "twitter"
    enable_fallback: true          # Enable intelligent degradation
    fail_fast: false              # Continue trying other engines

3. Custom Prompt Templates

// Load custom Prompt templates
prompts.LoadPrompts("./custom_prompts.yaml")

// custom_prompts.yaml example
auto_strategy_planner: |
  You are a professional research strategy planner...
  
sql_constraints_for_planner: |
  Please follow these constraints when generating SQL...

4. Configuration Examples

For complete configuration, please refer to resources/config/config.example.yaml

# Research configuration
execution:
  research:
    max_iterations: 3        # Maximum research rounds
    min_questions: 2         # Minimum research questions
    max_steps: 100          # Maximum execution steps
    max_content_length: 8000 # Content length limit
    channel_buffer: 100      # Streaming channel buffer size

# Search strategy
search:
  strategy:
    mixed_engines: ["firecrawl", "searxng"]  # Mixed search engines
    enable_fallback: true                     # Enable fallback
    breadth: 5                                # Search breadth

# MCP configuration
mcp:
  servers:
    postgres:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-postgres"]
      env:
        POSTGRES_CONNECTION_STRING: "postgresql://username:password@localhost:5432/database"

Technology Stack & Design Patterns

Technology Stack

• Go 1.21+: Primary development language, fully utilizing concurrency features like Channels and Goroutines
• Eino Framework: CloudWeGo's Agent framework for process orchestration and state management
• MCP SDK: Official Model Context Protocol SDK for standardized tool invocation
• Viper: Configuration file management, supporting YAML format and environment variables
• Zap: High-performance structured logging

Design Patterns

1. Factory Pattern + Registry Pattern

// Automatic registration
func init() {
search.RegisterAdapter("searxng", NewSearxNGAdapter)
}

// Runtime creation
adapter, err := search.CreateSearchAdapter("searxng")

2. Strategy Pattern

// Define strategy interface
type SearchStrategy interface {
Execute(ctx context.Context, request *SearchRequest) (*SearchResponse, error)
}

// Mixed search strategy - concurrent execution
type MixedSearchStrategy struct { ... }

// Fallback search strategy - sequential execution
type FallbackSearchStrategy struct { ... }

3. Adapter Pattern

// Unified interface
type SearchAdapter interface {
Search(ctx context.Context, request *SearchRequest) (*SearchResponse, error)
}

// Different implementations
type SearxNGAdapter struct { ... }
type FirecrawlAdapter struct { ... }
type TwitterAdapter struct { ... }

Project Structure

strato-sdk/
├── adapters/              # Adapter layer - Plugin-based external service integration
│   ├── llm/              # LLM adapters (supporting multiple large models)
│   ├── search/           # Search adapters (unified interface, multi-engine implementation)
│   │   ├── registry.go   # Global registry
│   │   ├── strategy.go   # Search strategy implementation
│   │   └── */           # Various search engine adapters
│   └── web/              # Web content processing adapters
├── config/               # Configuration management (YAML loader and type definitions)
├── core/                 # Core business logic
│   └── research/         # Research scenario implementation
│       ├── agent/        # Streaming research agents
│       │   ├── streaming_research_agent.go  # Core agent implementation
│       │   ├── constants.go                 # State and action constant definitions
│       │   └── prompts.go                   # Agent-specific prompts
│       └── tools/        # Research tool set
├── pkg/                  # Common utility packages
│   ├── mcp/             # MCP protocol client implementation
│   ├── strategy/        # Strategy engine (supporting intelligent data analysis, etc.)
│   ├── prompts/         # Prompt template management system
│   └── logging/         # Structured logging
├── resources/           # Resource files
│   ├── config/          # Configuration templates
│   └── prompts/         # Default prompt templates
└── example_main.go      # Complete usage example

Development Guide

Adding New MCP to Agent

Refer to Custom MCP Configuration.

1. Add global MCP configuration
2. Add MCP reference under mcp_servers in the agent configuration that needs to reference MCP

Adding New Search Engine

1. Create new adapter directory adapters/search/yourengine/
2. Implement SearchAdapter interface
3. Register adapter in init() function
4. Add engine configuration in config file

Adding New Strategy

1. Create strategy file in pkg/strategy/strategies/
2. Implement Strategy interface
3. Register strategy using factory pattern
4. Strategy will be automatically managed by strategy pool

License

This project is open sourced under MIT License.

Contact Us

Anboat - Innovation team focused on AI Agent technology

• 📧 Email: coder@anboat.cn
• 🐙 GitHub: https://github.com/anboat
• 🐦 Twitter: @Anboat240326

Acknowledgments

Thanks to the Eino Team and MCP Protocol for their contributions to the AI Agent development ecosystem.

Documentation

Overview

Package main provides an example of how to use the Strato SDK for streaming research.