权限策略-阿里云帮助中心

重要

Qoder CN 系列全新文档站点现已上线。当前站点的文档内容可能无法反映产品的最新功能与变化，请访问 docs.qoder.cn获取最新产品文档。

权限策略控制 Agent 在执行工具操作前是否需要人工审批。这是实现 Human-in-the-Loop 的核心机制——让你在 Agent 自主执行和人工监管之间找到平衡。

三种策略

Agent 尝试调用工具时，运行时会检查该工具的 permission 取值：

策略	行为	适用场景
`allow`	Agent 直接执行，无需确认	低风险操作（读文件、查看状态）
`ask`	Agent 暂停，等待人工审批后继续	高风险操作（删除文件、网络请求）
`deny`	Agent 无法执行该操作	禁止的操作（生产部署、敏感数据）

配置方式

工具配置使用单一对象 agent_toolset_20260401，通过 enabled_tools 数组开启原子工具（旧的每工具一对象 schema 已废弃）：

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit"]
    }
  ]
}

说明新 schema 下 permission 字段（allow / ask / deny）如何挂载有待进一步验证。本节描述的 Pending Action 流程仍然适用，但精确配置方式可能调整。

创建 Agent 时指定：

curl -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cautious-agent",
    "model": "ultimate",
    "instructions": "谨慎执行任务",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit"]
      }
    ]
  }'

Pending Action 机制

当 Agent 触发 ask 策略的工具时：

Agent 产生一个 Pending Action 事件
Session 状态变为 idle（等待人工输入）
客户端通过 SSE 收到 pending action 通知
人工审批通过 Turn Resolve API 完成
Agent 继续执行

Turn Resolve API

POST https://api.qoder.com.cn/api/v1/cloud/sessions/{session_id}/turns/{turn_id}/resolve

请求体：

{
  "action": "approve"
}

或拒绝：

{
  "action": "deny",
  "reason": "该操作不在本次任务范围内"
}

完整流程示例

1. 创建带 ask 策略的 Agent

curl -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "safe-dev",
    "model": "ultimate",
    "instructions": "开发助手",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit"]
      }
    ]
  }'

2. 发送任务触发工具调用

curl -X POST https://api.qoder.com.cn/api/v1/cloud/sessions/sess_abc123/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "删除 /tmp 下所有日志文件"}]}
    ]
  }'

3. 监听 SSE 收到 pending action

id: evt_02xyz
event: agent.message
data: {"content":"我需要执行 rm /tmp/*.log，请确认。","pending_action":{"turn_id":"turn_01","tool":"bash","command":"rm /tmp/*.log"}}

4. 审批执行

curl -X POST https://api.qoder.com.cn/api/v1/cloud/sessions/sess_abc123/turns/turn_01/resolve \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve"}'

5. 或者拒绝

curl -X POST https://api.qoder.com.cn/api/v1/cloud/sessions/sess_abc123/turns/turn_01/resolve \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"action": "deny", "reason": "请只删除 7 天前的日志"}'

说明拒绝时附带 reason，Agent 会根据原因调整行为并重新尝试。

策略设计建议

场景	推荐配置
内部开发环境	全部 `allow`，最大效率
生产运维	bash `ask`，text_editor `allow`
演示/评估	全部 `ask`，完全可控
只读分析	bash `deny`，text_editor `deny`

常见问题

Q：不设 permission 字段默认是什么？ A：默认为 allow，Agent 直接执行。

Q：pending action 有超时吗？ A：取决于 Session 的 idle timeout 配置。超时后 Session 可能被回收。

Q：一个 turn 可以有多个 pending action 吗？ A：当前每个 turn 最多一个 pending action。Agent 会逐步请求确认。

Q：能否按命令内容动态决定是否 ask？ A：当前按工具类型统一配置。更细粒度的规则（如按命令模式匹配）在规划中。