权限策略

控制工具调用是允许、询问还是拒绝。

权限策略控制 Agent 想调用工具时会发生什么。内置工具和 MCP 工具会被评估为 allow、ask 或 deny；client-side 自定义工具始终暂停，由你的应用执行后回传结果。

​

运行时行为

工具调用进入事件流时，会投影为：

事件	含义	关键字段
agent.tool_use	内置工具调用	id, name, input, evaluated_permission
agent.mcp_tool_use	MCP 工具调用	id, name, input, mcp_server_name, evaluated_permission
agent.custom_tool_use	Client-side 自定义工具请求	id, name, input

evaluated_permission 可能为：

值	行为
allow	平台直接执行工具
ask	当前 turn 暂停，等待 user.tool_confirmation
deny	平台向 Agent 返回被拒绝的工具结果

自定义工具不支持 permission_policy；它们由客户端执行，并通过 user.custom_tool_result 恢复。

​

在 Agent 中配置权限

内置工具和 MCP 工具的权限配置写在 Agent 的 tools 数组里：

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write"],
      "configs": [
        {"name": "Read", "permission_policy": {"type": "always_allow"}},
        {"name": "Write", "permission_policy": {"type": "always_ask"}},
        {"name": "Bash", "permission_policy": {"type": "always_deny"}}
      ]
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "weather-service",
      "configs": [
        {"name": "get_forecast", "permission_policy": {"type": "always_ask"}}
      ]
    }
  ]
}

位置	作用范围	说明
tools[].configs[].permission_policy	一个具名工具	单工具权限覆盖。内置工具的 name 使用 Read 等内置工具名；MCP 工具的 name 使用该 MCP server 暴露的原始工具名
tools[].configs[].enabled	一个具名工具	设为 false 时会禁用并拒绝该工具。如果同时使用 enabled_tools 白名单，不要把已禁用工具放进白名单

permission_policy.type 可选值：

值	运行时结果
always_allow	evaluated_permission: "allow"
always_ask	evaluated_permission: "ask"，当前 turn 等待 user.tool_confirmation
always_deny	evaluated_permission: "deny"

​

Pending Action 流程

当工具调用需要人工或客户端输入时：

1. 事件流先发送 agent.tool_use 或 agent.custom_tool_use
2. 事件流再发送 session.status_idle，其中 stop_reason.type 为 "requires_action"
3. stop_reason.event_ids 列出需要响应的事件 ID
4. 客户端向 POST /api/v1/cloud/sessions/{session_id}/events 发送响应事件
5. Agent 继续同一个 turn

{
  "type": "session.status_idle",
  "status": "idle",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["evt_01JZ6Q3FB6SG8F7J1M2N"]
  }
}

Pending action 不会自动超时。它会一直保持 pending，直到客户端解决，或 session/turn 被取消。

​

确认工具调用

使用 agent.tool_use 事件的 id 作为 tool_use_id。这里传的是 evt_... 事件 ID，不是模型供应商内部的 tool-use ID。

批准

curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
        "result": "allow"
      }
    ]
  }'

拒绝

curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
        "result": "deny",
        "deny_message": "只允许检查文件，不要删除。"
      }
    ]
  }'

​

完成自定义工具

自定义工具通过 Agent 的 type: "custom" 配置，详见 Agent 工具配置。当 Agent 请求自定义工具时，你的应用执行该工具，然后使用 agent.custom_tool_use 事件 ID 回传：

curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.custom_tool_result",
        "custom_tool_use_id": "evt_01JZ6R1V9Z8K2M3N4P5Q",
        "content": [{"type": "text", "text": "订单状态：已发货"}]
      }
    ]
  }'

content 可以是字符串、单个 text block 或 text block 数组。返回事件会以 content block 结构保存。

​

常见问题

Q：一个 turn 可以有多个待响应操作吗？ A：可以。stop_reason.event_ids 可能包含多个事件 ID，需要逐个响应。

Q：pending action 会超时吗？ A：不会。它会保持 pending，直到被解决，或 session/turn 被取消。

Q：自定义工具能使用 permission_policy 吗？ A：不能。自定义工具是 client-side 工具，是否执行或拒绝由客户端负责。

​

下一步

Agent 工具

为 Agent 配备内置、MCP 和自定义工具。

Session 事件流

通过 SSE 实时获取 Agent 的思考、消息、工具调用与状态。

启动 Session

管理会话生命周期。

定义 Agent

回顾 Agent 配置。