メインコンテンツへスキップ

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 の自律実行と人間による監督のバランスを取れます。

​
3 つのポリシー

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: 1 つの turn に複数の pending action が存在できますか? A: 現在、turn ごとに最大 1 つの pending action です。Agent は段階的に確認をリクエストします。 Q: コマンド内容に応じて動的に ask 判定できますか? A: 現在はツールタイプ単位で一律に構成します。より細粒度なルール (コマンドパターンマッチなど) は計画中です。