Tools & Agents Overview

Agent Architecture

Mirobody provides three agent types, each optimized for a different cost/quality/latency point:

DeepAgent

Complex workflowsSingle-model tool orchestration. Multi-step planning, file ops, subagents, persistent memory. The default for tool-assisted conversations.

MixAgent

Cost/quality balanceTwo-phase model fusion: a capable model orchestrates tool calls, a cheaper model writes the final reply with the collected context.

BaseAgent

Simple Q&ADirect LLM conversation without tools. Lowest latency. Good for trivial questions and benchmarking.

Agent Comparison

Feature	DeepAgent	MixAgent	BaseAgent
Architecture	Single-model tool loop	Orchestrator + Responder (two-phase)	Direct LLM, no tools
Planning	✅ Built-in todos	✅ (orchestrator phase)	❌
File System	✅ Full support	✅ (orchestrator phase)	❌
Subagents	✅ Task isolation	✅ (orchestrator phase)	❌
MCP Tools	✅ Full integration	✅ (orchestrator phase)	❌
MCP Resources	❌	❌	✅ Native
MCP Prompt Templates	❌	❌	✅ Native
Memory	✅ PostgreSQL	✅ PostgreSQL	❌
Streaming	✅	✅ (responder phase)	✅
Model Support	Multi-provider	Two providers (one per phase)	Gemini 2.5/3.0, MiroThinker
Cost Profile	One expensive model	Expensive orchestrator + cheap responder	One cheap model
Best For	Complex workflows, file ops	Long contexts where reply phase doesn’t need top-tier reasoning	Simple/lightweight tasks
Setup Complexity	Medium	Medium	Low

DeepAgent (Recommended for Complex Tasks)

Features

✅ Multi-step Planning: Built-in task decomposition with TODO system
✅ File Operations: Read, write, edit files with glob and grep support
✅ Subagents: Spawn subagents for context isolation
✅ Long-term Memory: PostgreSQL-backed persistent memory
✅ Full MCP Tools: Complete integration with MCP tool ecosystem

Supported Providers

DeepAgent supports multiple LLM providers via LangChain:

Gemini 3.0 (via Google GenAI SDK)
GPT-5 (via OpenAI API or OpenRouter)
Claude Sonnet (via OpenRouter)
DeepSeek v3.2 (via OpenRouter)

Configuration

config.localdb.yaml

# API Keys
GOOGLE_API_KEY: 'your_google_api_key'        # For Gemini models
OPENAI_API_KEY: 'your_openai_api_key'        # For GPT models
OPENROUTER_API_KEY: 'your_openrouter_key'    # For Claude, DeepSeek, etc.

# Provider Configurations
PROVIDERS_DEEP:
  # Gemini 3.0 models
  gemini-3-pro:
    llm_type: google-genai
    api_key: GOOGLE_API_KEY
    model: gemini-3-pro-preview
    temperature: 1.0
  
  gemini-3-flash:
    llm_type: google-genai
    api_key: GOOGLE_API_KEY
    model: gemini-3-flash-preview
    temperature: 1.0
  
  # OpenAI GPT models
  gpt-5.1:
    llm_type: openai
    api_key: OPENAI_API_KEY
    base_url: https://api.openai.com/v1/
    model: gpt-5.1
    temperature: 0.1
  
  # Claude via OpenRouter
  claude-sonnet:
    llm_type: openai  # OpenAI-compatible API
    api_key: OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1
    model: anthropic/claude-sonnet-4.5
    temperature: 0.1
  
  # DeepSeek via OpenRouter
  deepseek-v3.2:
    llm_type: openai
    api_key: OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1
    model: deepseek/deepseek-v3.2
    temperature: 0.1

# Optional: Custom prompts
PROMPTS_DEEP:
  - mirobody/pub/agents/deep/prompts/theta_health.jinja

# Optional: Tool filtering
ALLOWED_TOOLS_DEEP: []     # Leave empty to allow all tools
DISALLOWED_TOOLS_DEEP: []  # Specify tools to disable

Use Cases

Complex health data analysis workflows
Multi-step research and reporting
File processing and management
Tasks requiring persistent context
Projects needing task decomposition

Usage Example

from mirobody.pub.agents.deep_agent import DeepAgent

agent = DeepAgent(
    user_id="user123",
    user_name="John Doe",
    token="jwt_token",
    timezone="America/Los_Angeles"
)

async for event in agent.generate_response(
    user_id="user123",
    messages=[{"role": "user", "content": "Analyze my health data"}],
    provider="gemini-3-flash",
    session_id="session_001"
):
    print(event)

MixAgent (Two-Phase Cost/Quality Fusion)

MixAgent splits a single response into two model calls:

Orchestrator phase — a capable model (e.g. Claude Sonnet 4.5) handles the tool-calling loop. It plans, searches data, reads files, and stops when it has enough context.
Responder phase — a cheaper model (e.g. Gemini 2.5 Flash) consumes the orchestrator’s collected context and writes the final user-facing reply.

The orchestrator never speaks to the user directly; the responder never calls tools. This lets you put expensive intelligence only where you need it.

When to choose MixAgent

Long, tool-heavy conversations where the final summary doesn’t need top-tier reasoning (cost saver vs. DeepAgent).
You want consistent voice/tone from a single model for the final reply while letting a different model handle tool dispatch.
You’re billing by token and the responder’s context will be large.

When NOT to choose MixAgent

Short Q&A — the two-pass overhead isn’t worth it; use DeepAgent or BaseAgent.
The final reply quality is the bottleneck — promote it to DeepAgent with one strong model.

Configuration

The two phases are configured via the orchestrator / responder keys under PROVIDERS_MIX. See Agent Providers in Configuration for the full YAML.

PROVIDERS_MIX:
  orchestrator:
    llm_type: openai
    api_key: OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1
    model: anthropic/claude-sonnet-4.5
  responder:
    llm_type: google-genai
    api_key: GOOGLE_API_KEY
    model: gemini-2.5-flash

Tool filtering uses ALLOWED_TOOLS_MIX / DISALLOWED_TOOLS_MIX (only the orchestrator phase touches tools).

BaseAgent (Best for Simple Tasks)

Features

✅ Native MCP: Direct MCP server support
✅ Streaming: Fast streaming responses
✅ Direct Tool Config: Tools configured directly to LLM
✅ Lightweight: Minimal overhead, fast execution
❌ No file operations
❌ No subagents

Supported Providers

Gemini 2.5/3.0 (native Google GenAI)
MiroThinker (custom model)

Configuration

config.localdb.yaml

# Required API Keys
GOOGLE_API_KEY: 'your_google_api_key'           # For Gemini models
MIROTHINKER_API_KEY: 'your_mirothinker_key'     # For MiroThinker

# Provider Configurations
PROVIDERS_BASE:
  gemini-3-pro:
    api_key: GOOGLE_API_KEY
    model: gemini-3-pro-preview
  
  gemini-3-flash:
    api_key: GOOGLE_API_KEY
    model: gemini-3-flash-preview
  
  gemini-2.5-flash:
    api_key: GOOGLE_API_KEY
    model: gemini-2.5-flash
  
  miro-thinker:
    api_key: MIROTHINKER_API_KEY
    model: miro-thinker

Use Cases

Simple health data queries
Quick conversations
Direct MCP tool usage
Lightweight operations
Native Gemini/MiroThinker features

Usage Example

from mirobody.pub.agents.base_agent import BaseAgent

agent = BaseAgent(
    user_id="user123",
    user_name="John Doe"
)

async for event in agent.generate_response(
    user_id="user123",
    messages=[{"role": "user", "content": "What's my health status?"}],
    provider="gemini-2.5-flash"
):
    print(event)

Tools System

What are Tools?

Tools are Python functions that enable AI agents to interact with health data, perform actions, and access external services. Mirobody makes it easy to add custom functionality without complex configuration.

Tool Structure

mirobody/pub/
├── tools/              # General-purpose tools
│   ├── chart_service.py    # 25+ chart types
│   └── ...
└── tools_health/       # Domain-specific health tools
    ├── genetic_service.py
    ├── health_indicator_service.py
    └── user_service.py

Built-in Tools

General Tools (mirobody/pub/tools/):

chart_service.py - 25+ chart types (line, bar, pie, sankey, etc.)

Health Tools (mirobody/pub/tools_health/):

genetic_service.py - Genetic data analysis
health_indicator_service.py - Health metrics tracking
user_service.py - User profile management

Tool Configuration

config.localdb.yaml

# Tool Directories
MCP_TOOL_DIRS:
  - mirobody/pub/tools
  - mirobody/pub/tools_health
  - your/custom/tools  # Add your own

# Resource Directories
MCP_RESOURCE_DIRS:
  - mirobody/pub/resources

# Agent Directories
AGENT_DIRS:
  - mirobody/pub/agents

Creating Custom Tools

Create tool file

Create a new Python file in a configured tool directory:

mirobody/pub/tools/weather_service.py

from typing import Dict, Any, Optional

async def get_weather(
    city: str,
    user_info: Optional[Dict[str, Any]] = None,
    **kwargs
) -> Dict[str, Any]:
    """
    Get weather information for a city.
    
    Args:
        city: City name
        user_info: Optional user authentication info
        
    Returns:
        Weather data dictionary
    """
    # Your implementation here
    return {
        "city": city,
        "temperature": "22°C",
        "condition": "Sunny"
    }

# Export for MCP loader
__all__ = ["get_weather"]

Auto-discovery

Tools are automatically discovered when the server starts. No manual registration required!

Use in agents

Both DeepAgent and MixAgent (orchestrator phase) can use your custom tools automatically. BaseAgent runs without tools by design.

Tool Best Practices

Authentication: Use user_info parameter for user-specific operations
Error Handling: Return structured error responses
Type Hints: Use proper type annotations for validation
Documentation: Include clear docstrings with Args and Returns
Async Operations: Prefer async functions for I/O operations

MCP Protocol Integration

Mirobody functions as an MCP (Model Context Protocol) server, enabling integration with:

Claude Desktop - Direct integration
Cursor IDE - AI-powered coding assistant
ChatGPT - Via custom GPT apps
Custom MCP Clients - Any MCP-compatible client

MCP Endpoints

http://localhost:18080/mcp

Standard JSON-RPC 2.0 interface supporting:

tools/list - List available tools
tools/call - Execute tool functions
resources/list - List available resources
resources/read - Read resource content

Database Schema for Health Data

Tools query standardized health data from these tables:

th_series_data

Time-series health indicators:

Column	Type	Description
`id`	integer	Primary key
`user_id`	varchar	User identifier
`indicator`	varchar	Indicator name
`value`	text	Original value
`value_standardized`	text	Standardized value
`start_time`	timestamp	Start time
`end_time`	timestamp	End time
`source`	varchar	Data source
`source_table`	varchar	Source table

theta_ai.health_user_profile_by_system

User profile storage:

Column	Type	Description
`id`	integer	Primary key
`user_id`	varchar	User identifier
`version`	integer	Version number
`name`	varchar	Profile name
`last_execute_doc_id`	integer	Last executed document ID
`common_part`	varchar	Profile content (JSON)
`create_time`	timestamp	Creation timestamp
`last_update_time`	timestamp	Last update timestamp
`is_deleted`	boolean	Deletion flag

Next Steps

Built-in Tools

Explore the default health tools

Adding Custom Tools

Learn how to create your own tools

MCP Integration

Connect to Claude, Cursor, and ChatGPT

Adding MCPs

Add external MCP servers

​Agent Architecture

DeepAgent

MixAgent

BaseAgent

​Agent Comparison

​DeepAgent (Recommended for Complex Tasks)

​Features

​Supported Providers

​Configuration

​Use Cases

​Usage Example

​MixAgent (Two-Phase Cost/Quality Fusion)

​When to choose MixAgent

​When NOT to choose MixAgent

​Configuration

​BaseAgent (Best for Simple Tasks)

​Features

​Supported Providers

​Configuration

​Use Cases

​Usage Example

​Tools System

​What are Tools?

​Tool Structure

​Built-in Tools

​Tool Configuration

​Creating Custom Tools

​Tool Best Practices

​MCP Protocol Integration

​MCP Endpoints

​Database Schema for Health Data

​th_series_data

​theta_ai.health_user_profile_by_system

​Next Steps

Built-in Tools

Adding Custom Tools

MCP Integration

Adding MCPs

Agent Architecture

Agent Comparison

DeepAgent (Recommended for Complex Tasks)

Features

Supported Providers

Configuration

Use Cases

Usage Example

MixAgent (Two-Phase Cost/Quality Fusion)

When to choose MixAgent

When NOT to choose MixAgent

Configuration

BaseAgent (Best for Simple Tasks)

Features

Supported Providers

Configuration

Use Cases

Usage Example

Tools System

What are Tools?

Tool Structure

Built-in Tools

Tool Configuration

Creating Custom Tools

Tool Best Practices

MCP Protocol Integration

MCP Endpoints

Database Schema for Health Data

th_series_data

theta_ai.health_user_profile_by_system

Next Steps