Skip to main content
构建Agent

权限策略

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

三种策略

Agent 尝试调用工具时，运行时会检查该工具的 permission 取值：
策略行为适用场景
allowAgent 直接执行，无需确认低风险操作（读文件、查看状态）
askAgent 暂停，等待人工审批后继续高风险操作（删除文件、网络请求）
denyAgent 无法执行该操作禁止的操作（生产部署、敏感数据）

配置方式

工具配置使用单一对象 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 策略的工具时：
  1. Agent 产生一个 Pending Action 事件
  2. Session 状态变为 idle（等待人工输入）
  3. 客户端通过 SSE 收到 pending action 通知
  4. 人工审批通过 Turn Resolve API 完成
  5. 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：当前按工具类型统一配置。更细粒度的规则（如按命令模式匹配）在规划中。
操作指南
实践教程
API参考