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

# Agent 配置

> 用模型、工具、技能与行为参数配置定制 AI Agent。

# Agent 配置

Agent 是 Myrm 的核心工作单元。每个 Agent 可独立配置模型、自定义系统提示词、工具、技能、记忆与行为参数。

## 创建 Agent

1. 进入 **Agents > 新建 Agent**
2. 填写名称与描述
3. 选择模型（或交给智能路由）
4. 配置工具、技能与权限
5. 保存即可使用

首次启动会自动创建默认通用 Agent。

## 编辑-测试零跳转

Myrm 在聊天页中直接内嵌了 Agent 配置面板，实现「修改配置 → 发送消息 → 立即看到效果」的零跳转调试体验：

* **聊天页内嵌**：点击输入框旁的 Agent 指示器按钮即可展开配置面板，修改 System Prompt、技能、MCP 工具后下一条消息即生效
* **智能折叠**：发送消息后面板自动收起，不遮挡对话区域；需要再次调整时一键展开
* **自动保存**：从编辑页点击「开始对话」时，系统自动保存未提交的配置更改后再跳转到聊天页，不会丢失编辑内容
* **全入口一致**：侧边栏、设置页、模板市场、组织市场等所有入口均在同一页面内导航，无新标签页弹出

## 单轮能力 Chips（Skill/MCP）

除了 Agent 级默认配置，Myrm 支持在输入区直接做**下一条消息生效的一次性能力覆写**：

* 为**下一条消息**临时选择 Skill/MCP 子集
* 减法优先：只能从当前 Agent 已启用能力里做子集，不会越权新增
* 队列一致性：直接发送、排队发送、busy 重排队都保持同一轮覆写语义
* Prompt Cache 友好归一化：全选会自动折叠为 no-op，不制造无意义配置抖动

### 对真实用户的价值

* **降低误调用成本**：某一轮只放开必要工具，不改长期 Agent 配置
* **协作更清晰**：同事可临时聚焦一轮能力，结束后自动回到默认配置
* **可观测可复盘**：提交/生效/noop/排队/busy/终态 + 失败原因有完整遥测口径

可通过以下接口查看汇总指标：

* `GET /api/v1/statistics/turn-capability/summary`

## 模型选择

Myrm 通过 LiteLLM 支持 100+ 模型：

| 提供商           | 模型                             |
| ------------- | ------------------------------ |
| **OpenAI**    | GPT-4o、GPT-4.1、o4-mini         |
| **Anthropic** | Claude Sonnet 4、Claude 3.5     |
| **Google**    | Gemini 2.5、Gemini 2.0          |
| **DeepSeek**  | DeepSeek V3、R1、V4 Flash、V4 Pro |
| **本地模型**      | Ollama、LM Studio、vLLM          |
| **自定义**       | 任意 OpenAI 兼容 API               |

### 智能路由

复杂度路由器自动选择最优模型档位。**默认开启，零配置即用** — 当用户未手动指定轻量/推理模型时，系统自动从已启用模型中按成本选取（最便宜 → 轻量级，最贵 → 推理级）。

| 档位            | 使用场景       | 成本 |
| ------------- | ---------- | -- |
| **SIMPLE**    | 快问、简单查询    | 最低 |
| **STANDARD**  | 一般任务、中等复杂度 | 中等 |
| **REASONING** | 复杂分析、多步规划  | 最高 |

两阶段评估（零成本规则评分 + 模糊场景 LLM 裁判）+ 会话动量 — 短跟进消息继承会话已建立档位。

**Complaint-up 自动升级**：点击 Regenerate（重新生成）且不附加修改指令时，系统将此解读为对回答质量不满，自动将路由档位提升一级（SIMPLE→STANDARD→REASONING），用更强的模型重新回答。PenaltyTracker 同步记录此反馈，影响未来同类查询的路由精度。若附加了指令（如"用更正式的语气重写"），则视为方向调整而非不满，不触发升级。

**Per-Agent 独立路由策略**：每个智能体可以拥有独立于全局的路由配置。在 Agent 能力 Tab 中可设置：

* **继承全局**（默认）：跟随全局 Smart Routing 配置
* **自定义**：为该 Agent 设置独立的轻量级和推理模型
* **禁用路由**：该 Agent 始终使用其主模型，不做任何路由分级

使用场景：绑定到消息渠道的客服 Agent 可禁用路由以始终使用便宜模型（每月节省 \$200+），研究 Agent 可禁用路由以始终使用最强模型保证质量。

### 多槽位模型架构

每个 Agent 可独立配置 11+ 个模型槽位，针对不同任务类型使用最优模型：

| 槽位                 | 用途        | 示例                |
| ------------------ | --------- | ----------------- |
| **主模型 (Main)**     | 主要对话模型    | Claude Sonnet 4   |
| **轻量 (Lite)**      | 标题生成、快速摘要 | GPT-4o-mini       |
| **极简 (Light)**     | 轻量辅助任务    | DeepSeek V4 Flash |
| **推理 (Reasoning)** | 复杂分析、规划   | o4-mini           |
| **视觉 (Vision)**    | 图片理解、视觉问答 | GPT-4o            |
| **研究 (Research)**  | 深度研究、网页浏览 | Gemini 2.5 Pro    |
| **安全 (Safety)**    | 内容审核、风险评估 | Claude Haiku      |
| **各槽位 Fallback**   | 故障时自动切换   | 可配置               |

每个槽位支持 Agent 级覆盖（继承或自定义），未设置时自动回退到主模型。模型纪律系统自动检测弱模型并注入行为约束，确保任何模型层级都能输出高质量结果。

### 思考强度

6 档推理深度，可按对话调节：

`off` → `low` → `medium` → `high` → `xhigh` → `max`

各模型通过 localStorage 记住偏好思考级别。

## 提示词模式

三种模式控制系统提示词构建：

| 模式           | 说明          | Token 成本       |
| ------------ | ----------- | -------------- |
| **Minimal**  | 仅必要指令       | \~1,765 tokens |
| **Standard** | 完整能力与工具     | \~2,200 tokens |
| **Extended** | 全功能 + 上下文注入 | 可变             |

Minimal 模式下优化系统提示词约 1,765 tokens — 比同类平台少 **86%**（Hermes \~15,520，OpenClaw \~18,000）。

## 自定义系统提示词

每个 Agent 可有自定义系统提示词定义人格、专长与行为规则，运行时与 Myrm 核心规则（安全、工具使用等）合并。

## 工具配置

Agent 可使用：

* **内置工具**：文件、终端、浏览器、搜索、代码执行、工作区 `@codebase` 概览 + grep/glob 探索
* **MCP 工具**：通过 MCP 服务连接的外部工具
* **技能**：可复用任务能力

可按 Agent 启用/禁用工具，单独配置审批策略。

### 进度平面

Agent 配置面板提供进度模式（默认关闭，不占 Turn1 Token）：

| 模式           | 内置工具         | 适用场景                                                   |
| ------------ | ------------ | ------------------------------------------------------ |
| **Planning** | `todo_write` | 多步任务分解与实时进度（类 deer-flow / Cursor TodoWrite）            |
| **Kanban**   | kanban\_\*   | 跨会话看板与 DAG 编排（chat orchestrator 3 工具；task worker 6 工具） |

启用 Planning 后，进度持久化在 chat sandbox 的 `{sandbox}/.myrm/progress/todos.json`；CompletionGuard 会在有文件写入且 todos 未完成时阻断过早结束。前端按 `step_key` 合并重复的 SSE `tasks_steps` 事件，ProgressSteps 不会因重发而重复渲染。Planning **默认关闭**（开启约 \~150 token）——简单问答零进度工具税。

### 延迟工具加载

并非所有工具都需要始终占用 LLM Prompt 空间。Myrm 将工具分为两级：

| 级别     | 行为                | 示例                                                             |
| ------ | ----------------- | -------------------------------------------------------------- |
| **即时** | 启用后始终在 Prompt 中可用 | 文件操作、终端、搜索、浏览器、**在 Agent 配置中勾选的图片/视频/TTS**（AgentDeclared 即时挂载） |
| **延迟** | 检测到意图时按需加载        | UI 渲染（`render_ui`）、**定时任务（默认）**、Computer Use、可选集成              |

**媒体工具与凭证**：在 Agent 内置工具面板勾选图片/视频/TTS 后，仅当「设置 → 模型服务」已配置对应供应商 API Key 或媒体网关时，这些工具才会出现在 Turn 1 schema 中。若缺少凭证，配置面板会显示琥珀色内联警告并链到设置页——Agent 不会崩溃，也不会暴露无效工具 schema。

对于配置了较多*延迟*工具的 Agent，每轮可节省约 4,000 Token；你明确启用的媒体工具则无需额外发现步骤即可直接调用。

### 技能热重载

通过 GUI 或 API 修改技能配置后，正在运行的 Agent 会自动检测变更并在会话内重新初始化。无需重启、无需重连——更新后的技能即时生效。

## 记忆

每个 Agent 拥有：

* **Agent 专属记忆**：仅该 Agent 的知识
* **全局共享记忆**：所有 Agent 可访问

记忆跨会话持久化，Agent 可持续学习适应。详见[记忆系统](/zh/core-concepts/memory-system)。

## 人格

16 种内置人格预设（8 专业 + 8 创意）：

* 中英文双语
* Emoji + 语气定制
* GUI 分类画廊
* 自定义人格创建

## 子 Agent 编排

复杂任务可用 7 种编排模式分解：

| 模式               | 说明                            |
| ---------------- | ----------------------------- |
| **Chain**        | 顺序执行 A → B → C，结构化接力状态传递      |
| **DAG**          | 有向无环图 + 依赖解析 + 并发限制           |
| **Batch**        | 并行独立任务，聚合结果                   |
| **Race**         | 多 Agent 竞争，最快正确结果胜出           |
| **Verified**     | Worker + 独立 Verifier 在沙箱中交叉验证 |
| **Swarm**        | 自主多 Agent 分裂合并                |
| **Alternatives** | N 个 Agent 并行生成竞争方案，用户选择最优     |

### 角色边界与工具安全隔离

每个子 Agent 均继承一个 `SubagentConfig` — 包含 21 个字段的声明式配置文件，明确定义其职责、权限和资源限制：

| 控制层       | 字段                                                                    | 效果                                                                                      |
| --------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **职责声明**  | `system_prompt`、`display_name`、`description`                          | 明确 Agent 做什么、不做什么                                                                       |
| **工具访问**  | 4 层隔离：类型准入 → 全局黑名单 → per-config 白/黑名单 → 父级约束                          | 子 Agent 永远无法超越父级工具集                                                                     |
| **数据域**   | `workspace_policy`（3 级）+ `memory_isolation`（3 级）                      | 控制每个 Agent 可访问的文件和记忆                                                                    |
| **模型策略**  | `model_selection` 三级解析链（配置 → 模型 → 父级兜底）                               | 按 Agent 分配模型，含安全兜底。工具栏临时切换为**内存 Sticky**（不自动写入 DB）；刷新回退到已保存配置；显式点击配置面板 **Update** 才持久化。 |
| **资源预算**  | `budget_tokens` + `max_cost_usd` + `max_children` + `max_descendants` | 4 维预算守卫 + 渐进响应                                                                          |
| **编排角色**  | `delegation_role`（LEAF/ORCHESTRATOR）+ `max_spawn_depth`               | 控制委派层级深度                                                                                |
| **上下文隔离** | `context_mode`（isolated/fork）+ `max_fork_tokens`                      | 防止 Agent 间上下文泄露                                                                         |

GUI 配置编辑器提供 5 个独立面板（技能 / MCP / 内置工具 / 子智能体 / 指令），支持可视化配置。集成 AI 辅助 Prompt 生成和 ActionSpace 准确率雷达图进行覆盖率分析。

### 外部 Agent 委派 (ACP)

通过 ACP 协议将任务委派给外部编程 Agent：

* **Claude Code** — Anthropic 编程 Agent
* **Codex CLI** — OpenAI 编程 Agent
* **Gemini CLI** — Google 编程 Agent
* **任意 ACP 兼容 Agent** — 通过 RuntimePool 无限扩展

`delegate_to_agent` 工具支持完整上下文注入、持久/一次性会话模式和自动重试。

**Web 聊天体验：** 同一对话内复用外部 CLI Agent 会话（`--resume`），多轮委派无需重复冷启动。单对话 turn-lock 串行化多标签/连点并发；取消操作免锁，避免运行卡死。Direct-only 路径不挂载 delegate 工具，节省 token。

**按 Agent 的 `external_cli` 开关（2026-07）：** 本地模式下 **设置 → 开发者 → 外部 Agent** 会自动检测 PATH 中的 CLI —— 若 Claude Code 已配置三方模型，**无需** Anthropic 官方订阅凭据也可委派；Settings 徽章显示「**CLI 可用**」（而非误导性的「未登录」）。仅在需要 `delegate_to_agent` 的 Agent 上开启「外部 CLI」（如 General Assistant、Code Developer）。Writer/Research 预设默认关闭，省约 216 Turn1 schema token。Settings 与内置工具面板双向交叉提示；聊天面板在 auto-detect 成功时不再误报「尚未配置 CLI 后端」。

**验收（2026-07-10）：** 108+ 项后端集成/单测全绿（含 `test_external_cli_live_e2e.py` 直连 claude-code PONG）；Chrome E2E（`:3000`）确认 Writer/Research 无 external\_cli chip、General/Developer 有；Developer → 添加 Agent → Claude Code 显示「CLI 可用」；真实 `mimo-v2.5-pro` → 委派 → Claude Code 返回 **PONG**，聊天页含任务步骤与工具执行轨迹。

**从 Hermes / AionUi 迁移：** 保留已安装的 Claude Code / Codex / Gemini CLI（Settings 自动检测），在自有 Agent 引擎与 MCP 生态之上可选委派，并额外获得 5 层审批与 SubAgent 编排。删除对话会立即释放已池化的外部 CLI 进程，不留后台僵尸任务。

### Google A2A 协议

通过标准 Google Agent-to-Agent 协议发现和集成第三方 Agent。AgentCard 解析含 SSRF 防护和 TTL 缓存。

详见[看板与编排](/zh/core-concepts/kanban-orchestration)。

## Agent Profile：精确无串扰

每个 Agent Profile 是全维度配置单元 — 远非简单技能分组。

| 维度                 |                                               可配置                                               |
| ------------------ | :---------------------------------------------------------------------------------------------: |
| **Skills**         |                                  `skill_ids[]` — 该 Agent 可用技能集                                  |
| **Model**          |                                           按 Agent 选模型                                           |
| **Built-in Tools** |    `enabled_builtin_tools[]` — 15 类 canonical 工具白名单（py↔ts 契约锁死；legacy ID 如 `image_gen` 明确拒绝）    |
| **MCP Tools**      |                                 `mcp_tool_selections{}` — 按服务选工具                                |
| **Security**       |                                 `security_overrides{}` — 独立安全策略                                 |
| **Sub-Agents**     |    `subagent_ids[]` — 按需多层协作。统一沙箱内多 Agent 天然共享文件系统和浏览器，零同步成本无缝接力。启用后 Agent 可自动将子任务委派给专业 Agent   |
| **Notifications**  | `notify_targets[]` — 主动推送；动态 running 渠道下拉 + pairing 收件人白名单 + 附件 workspace 边界；未配置时不加载工具、不占 token |
| **Browser Config** |                   4 轴：引擎（Chromium/Firefox）、来源（auto/extension/launch）、弹窗策略、会话录制                  |
| **System Prompt**  |                                            自定义人格与行为规则                                           |
| **Memory**         |                                           独立记忆 + 全局共享                                           |

### 如何防止技能串扰

技能过多时 LLM 可能调用无关技能（「串扰」）。Myrm 五层解决：

1. **Agent Profile** — 各 Agent 仅通过 `skill_ids[]` 加载指定技能
2. **Tool Condition Activation** — `requires_tools` / `fallback_for_tools` 按可用工具显隐技能
3. **Progressive Disclosure（L0–L3）** — 仅展开相关技能详情
4. **Noise Gauge** — 超噪声阈值技能自动衰减
5. **Hybrid Retrieval** — Qdrant 向量检索为每查询选最相关技能

### Built-in Tools SSOT（2026-07）

* **15 canonical IDs**：`web_search`、`memory`、**`structured_clarify`** 等 **14 项**在 UI 可切换；`file_ops`、`code_execute` 为 **Agent 基线**（服务端强制 Turn1 eager，面板不展示开关）。
* **27 预置 Agent 工具矩阵**：服务启动时 initializer 幂等同步；Agent 画廊与设置页均展示完整 27 个 built-in（`AGENT_LIST_BUILTIN_PAGE_SIZE=50` 默认；画廊 chip 来自 `enabled_builtin_tools`）。
* **写路径单入口**：`persist_enabled_builtin_tools` 校验后再落库；legacy ID 返回 422，避免 silent 失效。
* **默认 profile**：UI 默认开启 `web_search` + `memory` + **`structured_clarify`（结构化多题澄清表单）**；**文件/代码执行能力始终可用**（Agent 基线，无需用户勾选）。表单 payload 使用 **`requires_confirmation: bool`**（替代竞品常见的 5 类枚举）；`true` 时 WebUI 以琥珀色强调风险确认。
* **用户开关 ON → Turn1 直接可用**：默认或手动开启的内置工具（含 **cron（需手动开启）**、**structured\_clarify**、render\_ui、computer\_use、x\_search、delegate\_to\_agent 等）、已绑定 skill 对应工具，首轮即出现在 LLM schema，无需先调 `discover_capability`。**Cron 默认关闭（可发现加载）**——仅开启的用户承担约 827 tok eager schema；OpenClaw/Hermes 无 per-agent 开关，Turn1 始终挂载 cron。**`structured_clarify` 关闭时不暴露 `ask_question_tool` schema**——竞品多把澄清写死在常驻 Prompt 里。Harness **`ClarificationGuardMiddleware`** 保证每轮至多一次 `ask_question_tool`，且与并行工具互斥（对齐 Hermes `clarify` 单轮约束）。
* **active\_tool\_groups SSOT**：`derive_active_tool_groups()` 统一推导已启用工具组，避免 render\_ui / 媒体组已开仍误报 `capability_gap`。
* **全矩阵回归**：`CAPABILITY_GAP_REGISTRY` 覆盖 **14 个 GUI 可切换** builtin（含 web\_search、memory、cron、answer\_tool、**structured\_clarify** 及 browser/render\_ui/computer\_use/wiki/kanban/planning/三媒体）。Agent 基线 `file_ops` / `code_execute` 运行时强制，不参与 Gap 提示。可编辑白板见 [通过 MCP 绘制图表](/docs/zh/guides/diagram-via-mcp)。
* **权限缺口（Entitlement Gap）**：每条用户消息在 Agent 循环前 **preflight** 扫描（SSE 推送 `capability_gap` / `skill_gap`，不改 Turn1 schema）；`discover_capability` miss 走同一 registry。WebUI 通过 **`/api/v1/workspace/stream` 多路复用**接收预检事件（POST 前注册监听器，早到 chunk 不丢），toast **一键开启/绑定**；若在 stream loading 中点击，**`pendingGapRetry`** 于 **MESSAGE\_END / ERROR / CANCEL** 落盘后自动重发，无需再点发送。
* **会话工具面板**：聊天输入框 **wrench 图标**通过 SSE `tools_snapshot` 展示本会话 **Turn1 已绑定**工具列表（含 layer 标签），比静态配置页更准确反映「此刻 Agent 能调用什么」。
* **控制面工具（默认 0 Turn1 token）**：编排信号（Deep Research）、CompletionGuard（`_completion_check`）、Verifier（`submit_verdict`）、Workflow PTC（`spawn_subagent`/`notify`）**登记供审计，但不进入默认 Chat bind**——简单对话不为 spawn/编排工具付 schema 税。典型默认 profile 实测 **15 工具 / \~8,354 tok 工具层**（2026-07-03 SSOT）。

| 能力    |  Skill Bundles  |   Agent Profile   |
| ----- | :-------------: | :---------------: |
| 多技能分组 | YAML `skills[]` | GUI `skill_ids[]` |
| 模型选择  |        无        |      按 Agent      |
| 工具级控制 |        无        |    按 Agent 白名单    |
| 安全策略  |        无        |     按 Agent 覆盖    |
| 防串扰   |     单层（少技能）     |       5 层防御       |
| 配置方式  |    CLI + YAML   |      可视化 GUI      |

## Agent 绑定

Agent 可绑定到不同上下文：

| 上下文        | 说明                   |
| ---------- | -------------------- |
| **Web 会话** | 新对话默认 Agent          |
| **定时任务**   | Cron 执行用 Agent       |
| **渠道**     | 指定消息渠道 Agent         |
| **IM 话题**  | `/bind` 将 Agent 绑到话题 |

未绑定上下文使用默认通用 Agent。可随时在 GUI 或消息渠道 `/bind` / `/unbind` 切换。

## Slash 命令绑定

每个 Agent 可自定义 Slash 命令，一键触发一个或多个技能。

### 单技能

将 `/deploy` 映射到一个技能：

```yaml theme={null}
command_name: deploy
skill_ids: [deploy_skill]
description: 部署到生产环境
```

### 多技能组合（Bundle）

将多个技能合并为一个命令，附加可选引导词：

```yaml theme={null}
command_name: daily-report
skill_ids: [data_collector, report_generator, email_sender]
instruction: 收集今日指标，生成汇总报告，发送邮件给团队。
```

触发时，所有技能 SOP 合并注入到一次 LLM 对话中，自动 Token 预算保护（12K 字符软上限）。

### 工作流程

1. **配置** — 在 Agent 编辑器中多选技能，可选填写引导词
2. **触发** — 在 Slash 面板（WebUI）、桌面端或任意 IM 渠道输入 `/daily-report`
3. **执行** — Harness 加载所有 SOP，强制 Token 预算，协同执行

### Agent 级隔离

每个 Agent 拥有独立的命令绑定。「代码助手」的 `/review` 与「运维助手」的 `/deploy` 完全独立。

## 配置快照与回滚

每次配置变更自动创建快照，实验无风险：

| 功能        | 说明                                         |
| --------- | ------------------------------------------ |
| **自动快照**  | 每次更新自动创建版本化快照（最多保留 10 版）                   |
| **一键回滚**  | 瞬间恢复到任意历史配置状态                              |
| **回滚前保护** | 回滚前自动保存当前状态，可随时"撤销回滚"                      |
| **智能过滤**  | 仅修改头像等无关配置不会创建快照，保持时间线干净                   |
| **缓存安全**  | 回滚立即使 Profile Resolver 缓存失效，下一轮对话即使用恢复后的配置 |

在 **Agent 设置 > 版本历史** 中查看快照时间线。

<Tip>
  竞品均无自动多版本配置快照回滚能力。Hermes、OpenClaw、ChatGPT 修改前需手动备份——一次误操作即永久覆盖配置。
</Tip>

## 导出、导入与克隆

跨团队分享 Agent 配置或外部备份：

| 操作     | 说明                                    |
| ------ | ------------------------------------- |
| **导出** | 下载完整 Agent Profile 为 JSON（敏感凭据字段自动脱敏） |
| **导入** | 从任意导出的 JSON 创建新 Agent（支持单体和团队两种格式）    |
| **克隆** | 工作区内一键复制——新 UUID，相同配置                 |

团队 Agent 导出时自动打包 Leader + 所有成员配置为单一版本化包。

<Warning>
  导出时敏感字段（API Key、OAuth Token、网关凭据）自动移除，防止分享时意外泄露凭据。
</Warning>