权限策略

控制托管智能体的工具行为靠两个字段：enabled 决定工具是否暴露给模型，permission_policy 决定模型调用工具时如何评估。用它们禁用写文件、执行命令、调用外部服务等可能改变外部状态的工具，或要求这些工具在执行前等待确认。

两个配置字段

字段	决定什么	取值与默认
`enabled`	工具是否暴露给模型	默认启用；设为 `false` 时禁用，模型看不到也无法调用该工具
`permission_policy`	模型调用工具时如何评估	`always_allow`：直接执行；`always_ask`：暂停并等待客户端确认。默认 `always_allow`

两个字段都适用于内置工具集（agent_toolset）和 MCP 工具集（mcp_toolset），并且都可以在两个层级上设置：

工具集级：在工具声明的 default_config 中设置，作为该工具集内所有工具的默认值；
单工具级：在 configs 中对某个具体工具设置同名字段，覆盖工具集级默认值。

两个层级都未设置时，工具默认启用，并按 always_allow 评估——模型调用该工具时会直接执行。每次工具调用的评估结果都会通过 agent.tool_use 事件的 evaluated_permission 字段下发给客户端。

处理 always_ask 确认

设为 always_ask 的工具被模型调用时，平台发送 agent.tool_use 事件后暂停执行，等待客户端通过 POST /v1/sessions/{session_id}/events 回复 user.tool_confirmation。平台收到确认结果后，再执行或跳过该工具调用。事件订阅与恢复方式见事件流。来源 agent.tool_use 事件外层的 id 就是要填写的 event_id。允许执行时，将 result 设为 allow：

curl -X POST "https://api.moonshot.cn/v1/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "data": {
          "event_id": "sevt_01h455vb4pex5vsknk084sn02s",
          "result": "allow"
        }
      }
    ]
  }'

拒绝时将 result 改为 deny，并可添加 deny_message 说明原因；允许执行时该字段必须为空。请求必须只包含工具确认事件，成功提交返回 202。

推荐实践：只读、不改变外部状态的工具保持默认放行；可能改变外部状态的工具可设为 always_ask；不希望智能体使用的工具，在工具集级或单工具级设置 enabled: false 彻底禁用。

配置工具权限

在创建智能体时，通过工具声明携带这两个字段。已有智能体也可以修改这两个配置：更新智能体时传入 tools 字段即可（tools 会整体替换当前工具声明），更新会生成新的智能体版本，无需重建。下面的示例为内置工具集设置默认自动放行，并把其中的写文件工具单独禁用：

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": "你是一个严谨的代码助手。",
    "tools": [
      {
        "type": "agent_toolset",
        "name": "default_toolset_20260901",
        "default_config": {
          "permission_policy": "always_allow"
        },
        "configs": [
          {
            "name": "write_file",
            "enabled": false
          }
        ]
      }
    ]
  }'

kha agents create --file - <<'JSON'
{
  "name": "代码助手",
  "model": {"id": "kimi-k3"},
  "system": "你是一个严谨的代码助手。",
  "tools": [
    {
      "type": "agent_toolset",
      "name": "default_toolset_20260901",
      "default_config": {
        "permission_policy": "always_allow"
      },
      "configs": [
        {
          "name": "write_file",
          "enabled": false
        }
      ]
    }
  ]
}
JSON

MCP 工具集

MCP 工具集同样在 default_config 和 configs 中设置 enabled 与 permission_policy。mcp_server_name 必须引用同一智能体 mcp_servers 中已声明的服务；configs[].name 使用该 MCP 服务实际提供的工具名。

{
  "type": "mcp_toolset",
  "mcp_server_name": "todo",
  "default_config": {
    "permission_policy": "always_allow"
  },
  "configs": [
    {
      "name": "delete_task",
      "enabled": false
    }
  ]
}

MCP 服务的声明方式、工具名来源，以及服务清单变化后 configs 的生效规则见接入 MCP。

开始使用

定义智能体

配置执行环境

运行会话

上下文与记忆

高级编排

最佳实践

常见问题

两个配置字段

处理 always_ask 确认

配置工具权限

MCP 工具集

下一步

配置工具权限策略

处理工具确认事件

​两个配置字段

​处理 always_ask 确认

​配置工具权限

​MCP 工具集

​下一步

配置工具权限策略

处理工具确认事件

两个配置字段

处理 always_ask 确认

配置工具权限

MCP 工具集

下一步