创建与管理智能体

智能体（Agent）是托管智能体中 持久化、版本化 的配置对象：它定义了模型选择、系统提示词、可用工具等「怎么干」的内容。会话（Session）通过 agent_id 引用智能体来运行任务，并在创建时冻结当时的智能体版本。

智能体的配置每次更新都会生成一个 不可变的新版本，旧版本仍然完整保留。已经创建的会话继续使用创建时冻结的版本，不受后续更新影响——这保证了长任务中断恢复后行为完全一致。

智能体字段

字段	类型	是否必填	说明
`name`	string	必填	智能体名称，1–256 字符
`model`	object \| string	必填	模型选择：`"kimi-k3"` 直接给模型 ID 字符串，或 `{"id": "kimi-k3", "reasoning_effort": ..., "provider": ...}` 给结构化配置；`reasoning_effort`（`"low" \| "medium" \| "high" \| "max"`，是否生效取决于模型）、`provider`（留空使用平台默认）可选
`system`	string	可选	系统提示词，最长 100,000 字符
`tools`	array[object]	可选	工具声明列表，最多 128 个，内置工具集、MCP 工具集与自定义工具可自由组合，见下文「工具声明」
`mcp_servers`	array[object]	可选	MCP 服务连接信息，最多 20 个，`name` 在同一智能体内必须唯一，见下文「MCP 服务」
`skills`	array[object]	可选	挂载的技能，见下文「技能引用」
`plugins`	array[object]	可选	挂载的插件（Plugin）。官方插件只需给出 `plugin_id`；自定义插件还可指定精确版本或传入 `latest`，详见插件
`description`	string	可选	描述，最长 2,048 字符
`metadata`	object	可选	自定义键值对，最多 16 条
`multiagent`	object	可选	委派配置，`type` 必填且固定为 `"coordinator"`；`agents` 声明可委派的智能体名单（1–20 个），写入时固定引用的智能体版本，详见多智能体编排
`id`	string	输出	稳定智能体 ID（`agent_` 前缀），创建后不变
`version`	string	输出	当前不可变版本号，每次更新都会变化；更新请求可携带它做并发校验
`created_at` / `updated_at` / `archived_at`	string	输出	创建 / 最近更新 / 归档时间
`scope`	string	输出	资源归属范围，`"official"` 表示平台官方智能体

工具声明

tools 数组用来声明智能体可以使用哪些工具。通过 type 字段区分类型：

类型	`type` 值	说明
内置工具集	`"agent_toolset"`	声明平台内置工具集（文件读写、代码执行、搜索等）。`name` 必填，当前唯一取值为 `"default_toolset_20260901"`；`default_config` 设置整组默认（`enabled`、`permission_policy`、`load_mode`），`configs` 对单个工具做覆盖
MCP 工具集	`"mcp_toolset"`	暴露某个 MCP 服务的工具，`mcp_server_name` 引用同一智能体的 `mcp_servers` 中声明的名称；同样支持 `default_config` 与 `configs`
自定义工具	`"custom"`	声明由客户端执行的工具。`name`、`description` 和 `input_schema` 必填；平台通过事件流发送调用，客户端执行后回传结果，详见自定义工具

如果不声明任何 agent_toolset，默认加载 default_toolset_20260901 的全部沙箱工具。显式声明一个或多个 agent_toolset 后，只加载声明的 name，不再追加默认值。要关闭沙箱工具，请显式声明 default_toolset_20260901，并将整个工具集的 default_config.enabled 设为 false。工具的配置细节见工具。

MCP 服务

mcp_servers 保存连接元信息：type（当前仅支持 "url"）、name、url，以及可选的 headers。headers 用于自定义非敏感 HTTP 请求头（如 User-Agent 或租户路由头），最多 16 条；请求中接受，响应中不回显。更新时，mcp_servers 数组整体替换，请求中未出现的服务器不会保留。headers 的处理规则不同：缺省或为空时，若服务器的 name、type、url 均未变化，则继承原值；非空时整体替换该服务器的 headers，空字符串表示删除对应键。访问凭据不保存在智能体配置里，而是在创建会话时通过凭据库（Vault）注入，详见 MCP 与凭据库。

技能引用

skills 中的每一项包含 skill_id 与 version。创建或更新时，省略 version 会在写入时固定为当时的最新版本；指定精确版本会固定使用该版本；显式传入 "latest" 时保留该值，并在读取或唤醒时重新解析，详见技能。

官方智能体与自定义智能体

智能体分为两类：

	官方智能体	自定义智能体
来源	平台预置并维护	你通过 API 或控制台创建
`scope`	`"official"`	你的项目
读取	所有用户可见	仅你的项目可见
修改 / 归档	不允许（API 只读）	允许
创建会话	可以直接引用其 `agent_id`	可以

官方智能体可读不可改：你可以查看它的完整配置、直接用它创建会话，但更新和归档请求会被拒绝。如需调整，参照官方智能体的配置创建你自己的自定义智能体。

接口一览

操作	方法与路径
创建智能体	`POST /v1/agents`
列出智能体	`GET /v1/agents`
获取智能体	`GET /v1/agents/{id}`
更新智能体	`PATCH /v1/agents/{id}`
归档智能体	`POST /v1/agents/{id}/archive`
列出版本历史	`GET /v1/agents/{id}/versions`

列出智能体时可传 exclude_multiagent=true，只返回未配置 multiagent 的智能体；配置委派名单时可以用它过滤掉本身已配置委派的智能体。除控制台和 API 外，你也可以通过 kha CLI 创建、更新和归档托管 Agent。以下示例提供 cURL 与 kha CLI 两种写法；cURL 示例从环境变量 KIMI_API_KEY 读取 API Key。

创建智能体

创建一个最小可用的智能体只需要 name 和 model；通常还会填写系统提示词 system。创建成功后返回完整智能体对象，包含 id 与第一个 version，请保存 id 用于后续创建会话。

curl -X POST https://api.moonshot.cn/v1/agents \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "调研助手",
    "model": {"id": "kimi-k3"},
    "system": "你是一个严谨的调研助手，擅长检索、整理并引用资料。",
    "description": "面向深度调研任务的托管智能体"
  }'

kha agents create --file - <<'JSON'
{
  "name": "调研助手",
  "model": {"id": "kimi-k3"},
  "system": "你是一个严谨的调研助手，擅长检索、整理并引用资料。",
  "description": "面向深度调研任务的托管智能体"
}
JSON

kha 的 --file 同时支持 JSON 和 YAML，- 表示从标准输入读取；含嵌套结构的请求体需用 --file 整体传入，且不能再与字段选项混用，详见请求体输入方式。

更新智能体

更新采用 不可变版本机制：PATCH 不会原地修改配置，而是基于当前配置生成一个全新的不可变版本，旧版本完整保留在版本历史中。在控制台的智能体详情页，可以通过「配置」标签页编辑当前版本；保存后同样会生成新的不可变版本。通过 API 更新时注意两个要点：

可选的 version 并发控制：请求体可携带读取智能体时返回的当前 version；若智能体在此期间被修改，服务端返回 409，重新读取最新 version 后重试。不携带 version 则不做并发校验。
出现的字段即被修改：省略字段表示不修改；显式传入 null 会返回 400 invalid_parameter_error。数组字段（tools、skills 等）与 metadata 是 整体替换——传空数组或空对象即可清空该字段；mcp_servers 按数组整体替换，只有 headers 按上述规则继承或替换，详见上文「MCP 服务」。

下面的示例只更新系统提示词，其余配置不变：

curl -X PATCH https://api.moonshot.cn/v1/agents/agent_xxx \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1",
    "system": "你是一个严谨的调研助手，所有结论都必须附带来源引用。"
  }'

kha agents update agent_xxx --version 1 --system "你是一个严谨的调研助手，所有结论都必须附带来源引用。"

更新智能体不影响已经创建的会话——会话在创建时冻结了当时的智能体版本，中断恢复也会继续使用该版本。只有新建会话才会使用更新后的版本。

查看版本历史

每次更新都会留下一个不可变版本。通过版本历史接口可以回看任意历史版本的完整配置，接口分页返回，响应中的 next_page_token 用于翻页（没有更多时该字段缺席）。

curl "https://api.moonshot.cn/v1/agents/agent_xxx/versions?page_size=10" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"

kha agents versions agent_xxx --limit 10

在控制台的智能体详情页，也可以通过「配置」标签页的「智能体版本」选择器查看历史版本。选择历史版本后，表单会回填该版本的完整配置，并显示「历史版本为只读快照，仅供查看」；历史版本不能保存修改。对于未归档的自定义智能体，切回「当前版本」后可继续编辑并保存，保存会生成新的不可变版本，不会改写历史版本。

查看关联资源与运行数据

智能体详情页还提供以下标签页：

「会话」：列出会话及其固定版本，支持按版本、来源和状态筛选。更新智能体后，已有会话仍显示创建时固定的版本；未指定版本的新建会话使用当前版本。
「部署」：查看关联部署及其版本、下次运行、最近运行和创建时间。
「可观测性」：查看会话总数、会话成功率、Tool 调用和 Tokens，以及最近会话和关联部署。

归档智能体

不再使用的智能体可以归档。可以在控制台智能体列表的操作菜单中选择「归档」，或调用归档接口。归档后：

智能体变为只读，更新请求会被拒绝；
默认不再出现在智能体列表和新建会话的候选中，不能再用于创建新会话；
仍可直接读取智能体及其历史版本；
已创建的会话不受影响，可继续运行与恢复。

归档成功返回 204，无响应体，无需解析响应 JSON。

curl -X POST https://api.moonshot.cn/v1/agents/agent_xxx/archive \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"

kha agents archive agent_xxx

归档操作不可逆。请确认之后不再需要用它创建新会话，再执行归档。

下一步

用创建好的智能体启动任务

用创建好的智能体启动一次任务。

配置内置与自定义工具

了解内置工具集的配置方式。

挂载技能

为智能体挂载版本化的技能包。

接入 MCP 服务

为智能体接入 MCP 服务并注入访问凭据。

管理访问凭据

管理 MCP 等外部服务的访问凭据。

开始使用

定义智能体

配置执行环境

运行会话

上下文与记忆

高级编排

最佳实践

常见问题

智能体字段

工具声明

MCP 服务

技能引用

官方智能体与自定义智能体

接口一览

创建智能体

更新智能体

查看版本历史

查看关联资源与运行数据

归档智能体

下一步

用创建好的智能体启动任务

配置内置与自定义工具

挂载技能

接入 MCP 服务

管理访问凭据

​智能体字段

​工具声明

​MCP 服务

​技能引用

​官方智能体与自定义智能体

​接口一览

​创建智能体

​更新智能体

​查看版本历史

​查看关联资源与运行数据

​归档智能体

​下一步

用创建好的智能体启动任务

配置内置与自定义工具

挂载技能

接入 MCP 服务

管理访问凭据

智能体字段

工具声明

MCP 服务

技能引用

官方智能体与自定义智能体

接口一览

创建智能体

更新智能体

查看版本历史

查看关联资源与运行数据

归档智能体

下一步