From 79fe6cc917ea45e6301a2ac42d3d65ff99128011 Mon Sep 17 00:00:00 2001 From: star Date: Fri, 26 Jun 2026 20:27:25 +0800 Subject: [PATCH] docs: clarify subagent delegation boundaries --- docs/en/customization/agents.md | 6 ++++++ docs/en/reference/kimi-acp.md | 4 ++++ docs/en/reference/tools.md | 2 ++ docs/zh/customization/agents.md | 6 ++++++ docs/zh/reference/kimi-acp.md | 4 ++++ docs/zh/reference/tools.md | 2 ++ 6 files changed, 24 insertions(+) diff --git a/docs/en/customization/agents.md b/docs/en/customization/agents.md index 4eb0b753b..0605aca63 100644 --- a/docs/en/customization/agents.md +++ b/docs/en/customization/agents.md @@ -12,6 +12,12 @@ Kimi Code CLI includes three built-in sub-agents, ready to use out of the box, e - **`explore`**: Dedicated to codebase exploration; performs read-only operations only and does not modify any files. Ideal for quickly searching, reading, and summarizing a repository without touching files. - **`plan`**: Dedicated to implementation planning and architecture design; even shell commands are not available, keeping the focus on "figuring out how to do something" rather than "actually doing it." +## Runtime boundary + +Sub-agents are Kimi Code runtime agents. They use the current session's configured model/provider and the selected Kimi sub-agent profile; they are not separate Claude Code, Codex, or IDE-agent processes. + +If a sub-agent profile exposes MCP tools, those tools still run as tool calls inside that sub-agent. For example, an MCP server may wrap another local CLI, but that does not give the wrapped process the `Agent` / `AgentSwarm` lifecycle, resume ID, or TUI progress semantics unless Kimi Code implements that integration explicitly. + ## How to Invoke Sub-agents are scheduled automatically by the main Agent — based on task complexity, context consumption, and sub-task independence, they are dispatched at the right moment without the user having to specify one. diff --git a/docs/en/reference/kimi-acp.md b/docs/en/reference/kimi-acp.md index 30f078765..4939bd5cf 100644 --- a/docs/en/reference/kimi-acp.md +++ b/docs/en/reference/kimi-acp.md @@ -12,6 +12,8 @@ Once started, the command prints no banner and immediately waits for the ACP cli You typically do not need to run `kimi acp` manually — this command is the subprocess entry point for IDEs. For IDE-side configuration, see [Using in IDEs](../guides/ides.md). ::: +`kimi acp` makes Kimi Code the ACP agent process that an IDE or ACP client drives. It does not make Kimi Code an ACP client for dispatching prompts to other ACP agents. + ## Capability Matrix The table below lists the capabilities declared by the current ACP adapter layer. The `agentCapabilities` field is returned in full in the `initialize` response, so the IDE can adjust its UI accordingly. @@ -77,6 +79,8 @@ When an ACP client provides `mcpServers` in `session/new` or `session/load`, the - `sse` → kimi's `transport: 'sse'` configuration - `acp` → discarded with a warn log entry +Forwarded MCP servers are exposed to Kimi Code as tools inside the session. They are not promoted into `Agent` / `AgentSwarm` sub-agents, even when an MCP tool wraps another local agent or CLI. + ## Next steps - [Using in IDEs](../guides/ides.md) — Zed / JetBrains configuration steps and troubleshooting diff --git a/docs/en/reference/tools.md b/docs/en/reference/tools.md index 37ed1018f..014d1d0df 100644 --- a/docs/en/reference/tools.md +++ b/docs/en/reference/tools.md @@ -93,6 +93,8 @@ Collaboration tools handle inter-Agent coordination, user interaction, and Skill **`AgentSwarm`** launches subagents from a shared `prompt_template` and an `items` array, resumes existing subagents through `resume_agent_ids`, or combines both in one call. The template must contain the `{{item}}` placeholder; each item replaces that placeholder and launches one new subagent. Pass `subagent_type` to choose the profile used by every spawned subagent in the swarm, or omit it to use `coder`. Without `resume_agent_ids`, the tool requires at least 2 items; with `resume_agent_ids`, it can resume one or more existing subagents. The tool supports up to 128 total subagents, waits for all subagents to finish, and returns an aggregated report. In the TUI, foreground swarms show a live `Agent swarm` progress panel above the input box. If a model response calls `AgentSwarm`, that call must be the only tool call in the response; to run multiple swarms, call one `AgentSwarm`, wait for its result, then call the next, or combine the work into one swarm when a single template can cover it. In `manual` permission mode, `AgentSwarm` calls outside active swarm mode request approval unless a permission rule allows them; while swarm mode is active, `AgentSwarm` itself is auto-approved. Permission rules match `AgentSwarm` by tool name only — argument patterns such as `AgentSwarm(swarm)` are not supported. By default the tool ramps up concurrency without an upper limit (5 subagents start immediately, then 1 more every 700 ms); set `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` to a positive integer to cap how many subagents run at the same time during that ramp, or leave it unset for no cap. If it is set to a value that is not a positive integer, the AgentSwarm call fails fast. +`Agent` and `AgentSwarm` manage Kimi Code sub-agents only. If an MCP server exposes another local agent or CLI, Kimi Code can call that server as a tool when the active profile allows it, but the call is not scheduled or resumed as a Kimi sub-agent. + **`AskUserQuestion`** asks the user a structured multiple-choice question — useful for disambiguation or option selection. The `questions` parameter accepts 1–4 questions; each question requires `question` (ending with `?`), `options` (2–4 choices, each with a `label` and `description`), and optional `header` (max 12 characters) and `multi_select` (defaults to false). An "Other" option is appended automatically. Setting `background` to true starts a background question task and returns a task ID immediately. When the host does not support interactive questioning, a failure message is returned and the Agent should ask the user directly in a text reply instead. **`Skill`** allows the Agent to actively invoke a registered inline-type Skill. Accepts `skill` (the Skill name) and optional `args` (additional argument text). Only `type = "inline"` Skills can be called via this tool; Skills with `disableModelInvocation: true` are rejected. Maximum nesting depth is 3 levels. See [Agent Skills](../customization/skills.md) for details. diff --git a/docs/zh/customization/agents.md b/docs/zh/customization/agents.md index 5b754ada1..42f2000b1 100644 --- a/docs/zh/customization/agents.md +++ b/docs/zh/customization/agents.md @@ -12,6 +12,12 @@ Kimi Code CLI 内置三种子 Agent，开箱即用，分别面向不同任务形 - **`explore`**：代码库探索专用，只做只读操作，不修改任何文件。适合在不改动文件的前提下快速搜索、阅读和总结仓库。 - **`plan`**：实现规划与架构设计专用，连 Shell 命令都不提供，专注于"想清楚怎么做"而不是"动手做"。 +## 运行时边界 + +子 Agent 是 Kimi Code 运行时内的 Agent 实例，会使用当前会话配置的模型/供应商和所选 Kimi 子 Agent profile；它们不是单独启动的 Claude Code、Codex 或 IDE Agent 进程。 + +如果某个子 Agent profile 暴露了 MCP 工具，这些工具仍然是在该子 Agent 内部发起的工具调用。例如，MCP server 可以包装另一个本地 CLI，但这不会让被包装的进程自动获得 `Agent` / `AgentSwarm` 的生命周期、resume ID 或 TUI 进度语义，除非 Kimi Code 显式实现了这类集成。 + ## 调用方式 子 Agent 由主 Agent 自动调度——根据任务复杂度、上下文消耗和子任务的独立性，在适当时机派发，无需用户手动指定。 diff --git a/docs/zh/reference/kimi-acp.md b/docs/zh/reference/kimi-acp.md index d58c4460a..80aa92a67 100644 --- a/docs/zh/reference/kimi-acp.md +++ b/docs/zh/reference/kimi-acp.md @@ -12,6 +12,8 @@ kimi acp 你通常不需要手动跑 `kimi acp`——这个命令是给 IDE 的子进程入口准备的。IDE 端的配置见[在 IDE 中使用](../guides/ides.md)。 ::: +`kimi acp` 会让 Kimi Code 成为 IDE 或 ACP 客户端驱动的 ACP Agent 进程。它不会让 Kimi Code 变成一个用于向其他 ACP Agent 派发提示词的 ACP 客户端。 + ## 能力矩阵 下表列出当前 ACP 适配层声明的能力。`agentCapabilities` 字段在 `initialize` 响应里完整返回，IDE 端可据此调整 UI。 @@ -77,6 +79,8 @@ ACP 客户端在 `session/new` 或 `session/load` 中提供 `mcpServers` 时， - `sse` → kimi 的 `transport: 'sse'` 配置 - `acp` → 丢弃并写一条 warn 日志 +转发过来的 MCP server 会在会话内作为工具暴露给 Kimi Code。即使某个 MCP 工具包装了另一个本地 Agent 或 CLI，它也不会被提升成 `Agent` / `AgentSwarm` 子 Agent。 + ## 下一步 - [在 IDE 中使用](../guides/ides.md) — Zed / JetBrains 配置步骤和故障排查 diff --git a/docs/zh/reference/tools.md b/docs/zh/reference/tools.md index 9584bcf6e..770697489 100644 --- a/docs/zh/reference/tools.md +++ b/docs/zh/reference/tools.md @@ -93,6 +93,8 @@ Plan 模式是一种受约束的工作状态：进入后 `Write` 与 `Edit` 只 **`AgentSwarm`** 可以从共享的 `prompt_template` 和 `items` 数组启动子 Agent，也可以通过 `resume_agent_ids` 恢复已有子 Agent，或在一次调用中同时使用两者。模板必须包含 `{{item}}` 占位符；每个 item 会替换该占位符，并启动一个新的子 Agent。传入 `subagent_type` 可以指定整个 swarm 中所有新启动的子 Agent 使用的 profile；省略时默认使用 `coder`。不传 `resume_agent_ids` 时，本工具要求至少 2 个 item；传入 `resume_agent_ids` 时，可以恢复 1 个或多个已有子 Agent。本工具最多支持 128 个子 Agent，会等待全部子 Agent 完成，并返回聚合报告。在 TUI 中，前台 swarm 会在输入框上方显示实时 `Agent swarm` 进度面板。若一次模型响应调用 `AgentSwarm`，该调用必须是该响应中的唯一工具调用；如需运行多个 swarm，应先调用一个 `AgentSwarm` 并等待结果，再调用下一个，若单个模板可以覆盖这些工作，也可以合并为一个 swarm。在 `manual` 权限模式下，未处于 swarm mode 时调用 `AgentSwarm` 会触发审批，除非已有权限规则允许；swarm mode 已开启时，`AgentSwarm` 本身会自动放行。权限规则只能按工具名 `AgentSwarm` 匹配，不支持 `AgentSwarm(swarm)` 这类参数模式。默认情况下，本工具会逐步提升并发且不设上限（立即启动 5 个子 Agent，之后每 700 毫秒再启动 1 个）；将 `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` 设为正整数可限制该阶段同时运行的子 Agent 数量，不设置则表示不限制。若设置为非正整数的值，本次 AgentSwarm 调用会立即失败。 +`Agent` 和 `AgentSwarm` 只管理 Kimi Code 子 Agent。如果某个 MCP server 暴露了其他本地 Agent 或 CLI，Kimi Code 可以在当前 profile 允许时把它作为工具调用，但该调用不会被当作 Kimi 子 Agent 调度或恢复。 + **`AskUserQuestion`** 以结构化多选题的形式向用户提问，适用于需要消歧或选择方案的场景。`questions` 参数接受 1–4 道题，每道题需提供 `question`（以 `?` 结尾）、`options`（2–4 个选项，每项含 `label` 和 `description`）以及可选的 `header`（最多 12 字符）和 `multi_select`（默认 false）。系统自动附加"其他"选项。`background` 为 true 时启动后台问题任务并立即返回任务 ID。宿主未实现交互式提问能力时返回失败提示，Agent 应改为在文本回复中直接提问。 **`Skill`** 允许 Agent 主动调用已注册的 inline 类型 Skill。接受 `skill`（Skill 名称）和可选的 `args`（附加参数文本）。只有 `type = "inline"` 的 Skill 能通过此工具调用；`disableModelInvocation: true` 的 Skill 会被拒绝。嵌套调用深度上限 3 层。Skill 体系细节见 [Agent Skills](../customization/skills.md)。