Tools & Agents Overview

​

Agent Architecture

​

Agent Comparison

​

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

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

​

Configuration

# 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)

​

BaselineAgent (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

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

# Provider Configurations
PROVIDERS_BASELINE:
  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.baseline_agent import BaselineAgent

agent = BaselineAgent(
    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?

​

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

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

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

​

Tool Configuration

# 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

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"]

​

Tool Best Practices

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

​

MCP Protocol Integration

• 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

• 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

​

th_series_data

​

theta_ai.health_user_profile_by_system

​

Next Steps