工具与 Agent 概览 - Theta Health

Agent 架构

Mirobody 提供三种 Agent，分别面向不同的成本 / 质量 / 延迟取舍：

DeepAgent

复杂工作流单模型的工具编排循环，支持多步规划、文件操作、子 Agent 和持久化记忆。带工具对话的默认选择。

MixAgent

成本 / 质量平衡两阶段模型融合：能力强的模型负责工具调度，便宜的模型基于收集到的上下文生成最终回答。

BaselineAgent

简单问答无工具的直接 LLM 对话，延迟最低。适合琐碎问题和基线对比。

Agent 对比

特性	DeepAgent	MixAgent	BaselineAgent
架构	单模型工具循环	Orchestrator + Responder 两阶段	直连 LLM、不调工具
规划能力	✅ 内置 TODO 系统	✅（orchestrator 阶段）	❌
文件系统	✅ 完整支持	✅（orchestrator 阶段）	❌
子 Agent	✅ 任务隔离	✅（orchestrator 阶段）	❌
MCP 工具	✅ 完整集成	✅（orchestrator 阶段）	❌
MCP 资源	❌	❌	✅ 原生支持
MCP Prompt 模板	❌	❌	✅ 原生支持
记忆能力	✅ PostgreSQL 持久化	✅ PostgreSQL 持久化	❌
流式传输	✅	✅（responder 阶段）	✅
模型支持	多提供商	两个提供商（每阶段一个）	Gemini 2.5/3.0、MiroThinker
成本结构	一个昂贵模型	昂贵 orchestrator + 便宜 responder	一个便宜模型
最适合	复杂工作流、文件操作	上下文较长、回答阶段不需要顶级推理	简单 / 轻量任务
设置复杂度	中等	中等	低

DeepAgent (推荐用于复杂任务)

功能特性

✅ 多步骤规划: 内置基于 TODO 系统的任务分解能力
✅ 文件操作: 支持读取、写入、编辑文件，支持 Glob 和 Grep
✅ 子 Agent: 生成子 Agent 以实现上下文隔离
✅ 长期记忆: 基于 PostgreSQL 的持久化记忆
✅ 完整 MCP 工具: 与 MCP 工具生态系统的完整集成

支持的提供商

DeepAgent 通过 LangChain 支持多个 LLM 提供商：

Gemini 3.0 (通过 Google GenAI SDK)
GPT-5 (通过 OpenAI API 或 OpenRouter)
Claude Sonnet (通过 OpenRouter)
DeepSeek v3.2 (通过 OpenRouter)

配置示例

config.localdb.yaml

# API 密钥
GOOGLE_API_KEY: '您的_google_api_key'        # 用于 Gemini 模型
OPENAI_API_KEY: '您的_openai_api_key'        # 用于 GPT 模型
OPENROUTER_API_KEY: '您的_openrouter_key'    # 用于 Claude, DeepSeek 等

# Provider 配置
PROVIDERS_DEEP:
  # Gemini 3.0 模型
  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 模型
  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
  
  # 通过 OpenRouter 访问 Claude
  claude-sonnet:
    llm_type: openai  # OpenAI 兼容 API
    api_key: OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1/
    model: anthropic/claude-sonnet-4.5
    temperature: 0.1

使用场景

复杂的健康数据分析工作流
多步骤的研究和报告生成
文件处理与管理
需要持久化上下文的任务
需要任务分解的项目

使用示例

from mirobody.pub.agents.deep_agent import DeepAgent

agent = DeepAgent(
    user_id="user123",
    user_name="张三",
    token="jwt_token",
    timezone="Asia/Shanghai"
)

async for event in agent.generate_response(
    user_id="user123",
    messages=[{"role": "user", "content": "请分析我的健康数据"}],
    provider="gemini-3-flash",
    session_id="session_001"
):
    print(event)

MixAgent（两阶段成本 / 质量融合）

MixAgent 把一次回复拆成两次模型调用：

Orchestrator 阶段 —— 能力强的模型（例如 Claude Sonnet 4.5）负责工具调度循环：规划、查数据、读文件，攒够上下文就停。
Responder 阶段 —— 便宜的模型（例如 Gemini 2.5 Flash）拿着 orchestrator 收集到的上下文，生成最终面向用户的回答。

Orchestrator 永远不直接对用户说话，Responder 永远不调工具。这样可以只在真正需要的地方花贵模型的钱。

什么时候选 MixAgent

工具调用密集、回答较长的对话 —— 比 DeepAgent 省钱
想让”对外口吻”由特定模型固定，工具调度让另一个模型负责
按 token 计费，且 responder 的上下文会很大

什么时候不选

简短问答 —— 两阶段开销不值，直接 DeepAgent 或 BaselineAgent
瓶颈在于最终回答的质量 —— 升回 DeepAgent，全程用一个强模型

配置

两个阶段分别通过 PROVIDERS_MIX 下的 orchestrator / responder 配置，完整 YAML 见配置文档中的 MixAgent 配置。

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

工具过滤用 ALLOWED_TOOLS_MIX / DISALLOWED_TOOLS_MIX（只有 orchestrator 阶段会接触工具）。

BaselineAgent (最适合简单任务)

功能特性

✅ 原生 MCP: 直接支持 MCP 服务器
✅ 流式传输: 快速的流式响应
✅ 直接工具配置: 工具直接配置给 LLM
✅ 轻量级: 开销极小，执行速度快
❌ 不支持文件操作
❌ 不支持子 Agent

支持的提供商

Gemini 2.5/3.0 (原生 Google GenAI)
MiroThinker (自定义模型)

配置示例

config.localdb.yaml

# 必需的 API 密钥
GOOGLE_API_KEY: '您的_google_api_key'           # 用于 Gemini 模型
MIROTHINKER_API_KEY: '您的_mirothinker_key'     # 用于 MiroThinker

# Provider 配置
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
  
  miro-thinker:
    api_key: MIROTHINKER_API_KEY
    model: miro-thinker

使用场景

简单的健康数据查询
快速对话交流
直接使用 MCP 工具
轻量级操作
原生 Gemini/MiroThinker 特性

使用示例

from mirobody.pub.agents.baseline_agent import BaselineAgent

agent = BaselineAgent(
    user_id="user123",
    user_name="张三"
)

async for event in agent.generate_response(
    user_id="user123",
    messages=[{"role": "user", "content": "我的健康状况如何？"}],
    provider="gemini-2.5-flash"
):
    print(event)

工具系统

什么是工具？

工具是 Python 函数，使 AI Agent 能够与健康数据交互、执行操作并访问外部服务。Mirobody 使得在没有复杂配置的情况下添加自定义功能变得非常容易。

工具结构

mirobody/pub/
├── tools/              # 通用工具
│   ├── chart_service.py    # 支持 25 种以上的图表类型
│   └── ...
└── tools_health/       # 领域特定的健康工具
    ├── genetic_service.py
    ├── health_indicator_service.py
    └── user_service.py

内置工具

通用工具 (mirobody/pub/tools/):

chart_service.py - 25 种以上的图表类型（折线图、柱状图、饼图、桑基图等）

健康工具 (mirobody/pub/tools_health/):

genetic_service.py - 基因数据分析
health_indicator_service.py - 健康指标追踪
user_service.py - 用户档案管理

工具配置

config.localdb.yaml

# 工具目录
MCP_TOOL_DIRS:
  - mirobody/pub/tools
  - mirobody/pub/tools_health
  - your/custom/tools  # 添加您自己的工具目录

# 资源目录
MCP_RESOURCE_DIRS:
  - mirobody/pub/resources

# Agent 目录
AGENT_DIRS:
  - mirobody/pub/agents

创建自定义工具

创建工具文件

在配置的工具目录中创建一个新的 Python 文件：

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]:
    """
    获取城市的天气信息。
    
    Args:
        city: 城市名称
        user_info: 可选的用户身份验证信息
        
    Returns:
        包含天气数据的字典
    """
    # 在此处编写您的实现逻辑
    return {
        "city": city,
        "temperature": "22°C",
        "condition": "晴朗"
    }

# 为 MCP 加载器导出
__all__ = ["get_weather"]

自动发现

服务器启动时会自动发现工具。无需手动注册！

在 Agent 中使用

DeepAgent 和 MixAgent（orchestrator 阶段）都可以自动使用您的自定义工具。BaselineAgent 按设计不接工具。

工具开发最佳实践

身份验证: 对于特定于用户的操作，请使用 user_info 参数
错误处理: 返回结构化的错误响应
类型提示: 使用适当的类型注解以便进行验证
文档说明: 包含清晰的 Docstring，并附带 Args 和 Returns
异步操作: 对于 I/O 操作，优先使用异步 (async) 函数

MCP 协议集成

Mirobody 可作为 MCP (Model Context Protocol) 服务器运行，支持与以下平台集成：

Claude Desktop - 直接集成
Cursor IDE - AI 驱动的代码助手
ChatGPT - 通过自定义 GPT 应用
自定义 MCP 客户端 - 任何兼容 MCP 的客户端

MCP 端点

http://localhost:18080/mcp

支持的标准 JSON-RPC 2.0 接口包括：

tools/list - 列出可用工具
tools/call - 执行工具函数
resources/list - 列出可用资源
resources/read - 读取资源内容

健康数据的数据库模式

工具从以下表中查询标准化的健康数据：

th_series_data

时序健康指标表：

列名	类型	描述
`id`	integer	主键
`user_id`	varchar	用户标识符
`indicator`	varchar	指标名称
`value`	text	原始值
`value_standardized`	text	标准化值
`start_time`	timestamp	开始时间
`end_time`	timestamp	结束时间
`source`	varchar	数据源
`source_table`	varchar	来源表

theta_ai.health_user_profile_by_system

用户档案存储表：

列名	类型	描述
`id`	integer	主键
`user_id`	varchar	用户标识符
`version`	integer	版本号
`name`	varchar	档案名称
`last_execute_doc_id`	integer	最后执行的文档 ID
`common_part`	varchar	档案内容 (JSON)
`create_time`	timestamp	创建时间戳
`last_update_time`	timestamp	最后更新时间戳
`is_deleted`	boolean	删除标志

下一步

内置工具

探索默认提供的健康工具

添加自定义工具

学习如何创建您自己的工具

MCP 集成

连接到 Claude、Cursor 和 ChatGPT

添加 MCP

添加外部 MCP 服务器

快速开始

核心概念

使用 Providers

Providers 示例

Tools 与 MCP

Documentation Index

​Agent 架构

DeepAgent

MixAgent

BaselineAgent

​Agent 对比

​DeepAgent (推荐用于复杂任务)

​功能特性

​支持的提供商

​配置示例

​使用场景

​使用示例

​MixAgent（两阶段成本 / 质量融合）

​什么时候选 MixAgent

​什么时候不选

​配置

​BaselineAgent (最适合简单任务)

​功能特性

​支持的提供商

​配置示例

​使用场景

​使用示例

​工具系统

​什么是工具？

​工具结构

​内置工具

​工具配置

​创建自定义工具

​工具开发最佳实践

​MCP 协议集成

​MCP 端点

​健康数据的数据库模式

​th_series_data

​theta_ai.health_user_profile_by_system

​下一步

内置工具

添加自定义工具

MCP 集成

添加 MCP

Agent 架构

Agent 对比

DeepAgent (推荐用于复杂任务)

功能特性

支持的提供商

配置示例

使用场景

使用示例

MixAgent（两阶段成本 / 质量融合）

什么时候选 MixAgent

什么时候不选

配置

BaselineAgent (最适合简单任务)

功能特性

支持的提供商

配置示例

使用场景

使用示例

工具系统

什么是工具？

工具结构

内置工具

工具配置

创建自定义工具

工具开发最佳实践

MCP 协议集成

MCP 端点

健康数据的数据库模式

th_series_data

theta_ai.health_user_profile_by_system

下一步