跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
三种策略

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

​
配置方式

通过 tools 数组中每个工具对象的 permission 字段设置： 
{
  "tools": [
    {"type": "bash_20250124", "permission": "allow"},
    {"type": "text_editor_20250124", "permission": "allow"},
    {"type": "computer_20250124", "permission": "ask"}
  ]
}
创建 Agent 时指定： 
curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cautious-agent",
    "model": "qoder-best",
    "instructions": "谨慎执行任务",
    "tools": [
      {"type": "bash_20250124", "permission": "ask"},
      {"type": "text_editor_20250124", "permission": "allow"},
      {"type": "computer_20250124", "permission": "deny"}
    ]
  }'

​
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://openapi.qoder.sh/api/v1/cloud/sessions/{session_id}/turns/{turn_id}/resolve
请求体： 
{
  "action": "approve"
}
或拒绝： 
{
  "action": "deny",
  "reason": "该操作不在本次任务范围内"
}

​
完整流程示例

​
1. 创建带 ask 策略的 Agent

curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "safe-dev",
    "model": "qoder-best",
    "instructions": "开发助手",
    "tools": [
      {"type": "bash_20250124", "permission": "ask"},
      {"type": "text_editor_20250124", "permission": "allow"}
    ]
  }'

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

curl -X POST https://openapi.qoder.sh/api/v1/cloud/sessions/ses_abc123/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": "删除 /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://openapi.qoder.sh/api/v1/cloud/sessions/ses_abc123/turns/turn_01/resolve \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve"}'

​
5. 或者拒绝

curl -X POST https://openapi.qoder.sh/api/v1/cloud/sessions/ses_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：当前按工具类型统一配置。更细粒度的规则（如按命令模式匹配）在规划中。