> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirobody.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 内置 Agent

> 引擎自带的唯一一个 agent：每一轮对话能使用什么、配置它的键，以及如何替换它。

export const OssVersion = ({lang = "en"}) => <p className="text-sm text-gray-500 dark:text-gray-400">
    {lang === "zh" ? "对应 mirobody " : "Written for mirobody "}
    <a href="https://github.com/thetahealth/mirobody/tree/c1aae297b4f3fad5cb87c5fc5bffc5163f7758c9">
      <code>1.5.3</code>
    </a>
  </p>;

export const OssLink = ({path = "", children}) => {
  const base = "https://github.com/thetahealth/mirobody";
  const commit = "c1aae297b4f3fad5cb87c5fc5bffc5163f7758c9";
  const href = !path ? base + "/tree/" + commit : base + (path.endsWith("/") ? "/tree/" : "/blob/") + commit + "/" + path.replace(/\/$/, "");
  return <a href={href}>{children ?? <code>{path}</code>}</a>;
};

export const Fact = ({k, code = false, sep = ", "}) => {
  const facts = {
    "version": "1.5.3",
    "commit": "c1aae297b4f3fad5cb87c5fc5bffc5163f7758c9",
    "commitShort": "c1aae29",
    "repo": "https://github.com/thetahealth/mirobody",
    "python": "3.12",
    "port": 18060,
    "url": "http://localhost:18060",
    "pgPort": 18062,
    "redisPort": null,
    "account": "you@mirobody.ai",
    "accounts": ["you@mirobody.ai", "mom@mirobody.ai"],
    "code": "111111",
    "mcpUrlTtlDays": 10,
    "llmKeys": ["OPENROUTER_API_KEY", "DASHSCOPE_API_KEY", "GOOGLE_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "DEEPSEEK_API_KEY"],
    "cli": ["serve", "dev", "worker", "doctor", "fetch", "parse", "import", "resolve", "device-bundle", "mcp", "migrate-observations", "migrate-genotypes", "recode"],
    "tools": {
      "mcp": ["query_genetic_data", "query_health_indicators", "query_medications", "query_pharmacogenomics", "resolve_indicator", "convert_unit", "normalize_unit"],
      "gated": ["query_genetic_data", "query_pharmacogenomics", "query_health_indicators", "query_medications"]
    },
    "readme": {
      "en": {
        "tagline": "Self-hosted AI health data engine: every source, one standard, answers that cite their source.",
        "stages": [{
          "mark": "①",
          "name": "Collect",
          "what": "Lab reports, wearables, phone photos, genetic files, all pulled in. The source file is kept as it was, so every indicator points back to the page it was read from."
        }, {
          "mark": "②",
          "name": "Translate",
          "what": "One name to one code, one unit to UCUM, offline and deterministic. `A1c`, `HbA1c` and `Glycated Hemoglobin` become the same test here, and `头疼` and `headache` the same complaint (ICPC-3)."
        }, {
          "mark": "③",
          "name": "Agent",
          "what": "Ask over the coded record. Trend a value by minute, hour, day, week or month; get count, min, max, avg or change over any window in one call; compare across labs and devices, because they share one code. It charts the result in its reply, reads medications and genetic variants too, and names the file every number came from."
        }]
      },
      "zh": {
        "tagline": "自托管的 AI 原生健康数据引擎：任何来源，一套标准，每个答案都有出处。",
        "stages": [{
          "mark": "①",
          "name": "收集 Collect",
          "what": "化验单、穿戴设备、手机照片、基因文件，都收进来。源文件原样留下，每一项指标都能指回它被读出来的那一页。"
        }, {
          "mark": "②",
          "name": "转译 Translate",
          "what": "一个名字解析成一个码，一个单位统一到 UCUM，全程离线、结果确定。`A1c`、`HbA1c`、`糖化血红蛋白` 在这一层变成同一项检查，`头疼` 和 `headache` 也成了同一条主诉（ICPC-3）。"
        }, {
          "mark": "③",
          "name": "智能体 Agent",
          "what": "在编码后的记录上提问。按分钟、小时、天、周、月给出趋势，一次调用就能算出计数、最小值、最大值、均值和变化量；同一个码，跨化验所、跨设备直接比较。图表画在回复里，用药记录和基因型数据也读得了，每个数字都说明出自哪份文件。"
        }]
      }
    },
    "source": {
      "cli": "mirobody/cli.py",
      "tools": "mirobody/agent/tools"
    }
  };
  const value = k.split(".").reduce((o, p) => o == null ? undefined : o[p], facts);
  if (value === undefined) return <span>{"[unknown fact " + k + "]"}</span>;
  const items = Array.isArray(value) ? value : [value];
  return <>
      {items.map((item, i) => <span key={i}>
          {i > 0 ? sep : null}
          {code ? <code>{String(item)}</code> : String(item)}
        </span>)}
    </>;
};

<OssVersion lang="zh" />

引擎自带一个 agent。它回答在 Web 客户端 `/ask` 页面和对话 API 中提出的问题，依据的是问题所涉及那个人的已编码记录。要增加能力，应当添加一个[工具](/zh/tools/adding-tools)，而不是再加一个 agent。

自带 agent 以外的所有 agent 运行时（Claude Desktop、Cursor、你自己的 agent 循环）都通过 [MCP 端点](/zh/tools/mcp-integration)读取同一份数据，不需要本页的任何内容。

## 每一轮能使用的能力

| | 说明 |
| - | - |
| 健康数据工具 | <Fact k="tools.mcp" code sep="、" />：与任何 MCP 客户端通过 `/mcp` 看到的是同一组工具，见[健康数据工具](/zh/tools/overview) |
| 虚拟文件系统 | `/uploads`、`/library` 与 `/memories`：此人文件与档案的只读视图，配有列出、读取与搜索文件的工具 |
| 代码执行 | `eval` 工具，在沙箱中运行 JavaScript，沙箱内也能调用数据工具 |
| 向用户提问 | `ask_user`：暂停本轮并向用户提一个问题，用户的下一条消息就是回答。它不会通过 MCP 暴露。 |
| 记忆 | 按会话保存的对话状态，存放在 Postgres 中 |

每个回答都以带类型的块流式返回（文本、推理、工具调用及其结果、用量），客户端因此可以展示回答背后的工具调用过程。

<h2 id="configuration">
  配置
</h2>

agent 的配置键不带 agent 名后缀。随仓库提供的值在 `config.llm.yaml` 中，请在覆盖文件里覆盖。

| 键 | 作用 |
| - | - |
| `MODELS` | 模型选择器：每个对话模型一条。`/api/models` 列出有密钥的条目，对话请求按名称选择其中之一。 |
| `DEFAULT_MODEL` | 选择器的默认模型；不设置时取第一个有密钥的条目 |
| `ALLOWED_TOOLS` / `DISALLOWED_TOOLS` | 工具白名单或黑名单，白名单优先。把 `eval` 写进 `DISALLOWED_TOOLS` 即关闭代码执行。 |
| `PROMPTS` | 系统提示词模板，写法为路径或 `path@name`；第一个是默认值 |
| `AGENT_NAME` | 提示词中使用的角色名 |
| `AGENT_CHECKPOINTER` | `true` 按会话保留对话状态；`false` 让每一轮都从头开始 |

模型的选择与密钥见[配置](/zh/configuration#the-model-key)。

<h2 id="replacing-the-agent">
  替换 agent
</h2>

agent 只有一个位置。替换来自两处：声明了 `mirobody.agents` 入口点的已安装包，或 `AGENT_DIRS` 中列出的目录；找到的第一个定义了 `generate_response` 的类，就成为该进程的 agent。无需修改代码包的任何内容。

约定只有两个方法。`generate_response` 接收本轮所涉及的用户（已经过授权，可能是关爱圈成员而不是调用者本人）、本轮的消息，以及 `language`、`session_id`、`timezone` 等关键字参数；它产出的块与自带 agent 流式返回的相同。请接受 `**kwargs`，因为对话层可能会新增参数。

```python theme={null}
class MyAgent:
    def __init__(self, **kwargs): ...

    async def generate_response(self, user_id: str, messages: list[dict], **kwargs):
        yield {"type": "text", "text": "..."}
```

如果想在自带的中间件与文件系统后端之上构建另一套 harness，请安装 `mirobody[agent]`。完整约定、块的类型定义与最小示例插件见 <OssLink path="mirobody/agent/README.md" />。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.