跳转到主要内容

​
Agent 架构

Mirobody Health 提供两种类型的 AI Agent，每种都针对不同的用例进行了优化：

DeepAgent

推荐用于复杂任务基于 LangChain 的 Agent，具有文件操作、多步骤规划和复杂工作流的高级能力。

BaselineAgent

最适合简单任务原生 Gemini/MiroThinker Agent，针对轻量级操作和直接 MCP 集成进行了优化。

​
Agent 对比

特性DeepAgentBaselineAgent
框架LangChain DeepAgentsGemini/MiroThinker MCP
规划能力✅ 内置 TODO 系统❌
文件系统✅ 完整支持❌
子 Agent✅ 任务隔离❌
MCP 工具✅ 完整集成✅ 原生支持
MCP 资源❌✅ 原生支持
MCP Prompt 模板❌✅ 原生支持
记忆能力✅ PostgreSQL 持久化❌
流式传输✅✅
模型支持多提供商支持Gemini 2.5/3.0, MiroThinker
最适合复杂工作流、文件操作简单任务、原生 MCP
设置复杂度中等低

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

​
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 Health 使得在没有复杂配置的情况下添加自定义功能变得非常容易。

​
工具结构

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

​
创建自定义工具

1

创建工具文件

在配置的工具目录中创建一个新的 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"]
2

自动发现

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

在 Agent 中使用

DeepAgent 和 BaselineAgent 都可以自动使用您的自定义工具。

​
工具开发最佳实践

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

​
MCP 协议集成

Mirobody Health 可作为 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

时序健康指标表：
列名类型描述
idinteger主键
user_idvarchar用户标识符
indicatorvarchar指标名称
valuetext原始值
value_standardizedtext标准化值
start_timetimestamp开始时间
end_timetimestamp结束时间
sourcevarchar数据源
source_tablevarchar来源表

​
theta_ai.health_user_profile_by_system

用户档案存储表：
列名类型描述
idinteger主键
user_idvarchar用户标识符
versioninteger版本号
namevarchar档案名称
last_execute_doc_idinteger最后执行的文档 ID
common_partvarchar档案内容 (JSON)
create_timetimestamp创建时间戳
last_update_timetimestamp最后更新时间戳
is_deletedboolean删除标志

​
下一步

内置工具

探索默认提供的健康工具

添加自定义工具

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

MCP 集成

连接到 Claude、Cursor 和 ChatGPT

添加 MCP

添加外部 MCP 服务器