メインコンテンツへスキップ
権限ポリシーは、Agent がツールを呼び出す際の挙動を制御します。組み込みツールと MCP ツールの呼び出しは allow、ask、deny のいずれかとして評価されます。クライアントサイドのカスタムツールは常に一時停止し、アプリケーションが実行して結果を返します。

​
ランタイムの挙動

ツール呼び出しがイベントストリームに送出される際の挙動:
イベント意味主要フィールド
agent.tool_use組み込みツール呼び出しid, name, input, evaluated_permission
agent.mcp_tool_useMCP ツール呼び出しid, name, input, mcp_server_name, evaluated_permission
agent.custom_tool_useクライアントサイドのカスタムツールリクエストid, name, input
evaluated_permission の値:
値挙動
allowプラットフォームがツールを直接実行
askターンが一時停止し、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 ツールの場合は MCP サーバーが公開するツール名
tools[].configs[].enabled個別のツールfalse に設定してツールを無効化・拒否。enabled_tools を使用している場合は、無効化するツールをホワイトリストから除外
permission_policy.type の値:
値ランタイム結果
always_allowevaluated_permission: "allow"
always_askevaluated_permission: "ask" となり、ターンは user.tool_confirmation を待機
always_denyevaluated_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 /v1/sessions/{session_id}/events に応答イベントを送信
  5. Agent が同じターンを続行
{
  "type": "session.status_idle",
  "status": "idle",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["evt_01JZ6Q3FB6SG8F7J1M2N"]
  }
}
Pending Action は自動的にタイムアウトしません。クライアントが応答するか、セッション/ターンがキャンセルされるまで保留状態が維持されます。

​
ツール呼び出しの確認

agent.tool_use イベントの id を tool_use_id として使用します。これは evt_... 形式のイベント ID であり、モデルプロバイダー内部のツール使用 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"
      }
    ]
  }'

​
カスタムツールの完了

カスタムツールは 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 の値は文字列、単一のテキストブロック、またはテキストブロックの配列で指定できます。返されたイベントはコンテンツブロック形式で格納されます。

​
よくある質問

Q: 1 つのターンで複数の応答が必要になることはありますか? A: あります。stop_reason.event_ids に複数のイベント ID が含まれる場合があります。保留中の各ツールリクエストに応答してください。 Q: Pending Action にタイムアウトはありますか? A: ありません。応答されるか、セッション/ターンがキャンセルされるまで保留状態が維持されます。 Q: カスタムツールに permission_policy を使用できますか? A: できません。カスタムツールはクライアントサイドで実行されるため、実行の可否はクライアントが判断します。

​
次のステップ

Agent ツール

組み込み、MCP、カスタムツールを構成する。

Session イベントストリーム

agent.tool_use と確認イベントを購読する。

Session の開始

実行中のターンでツール確認を行う。

Agent の定義

tools と configs を含む Agent 構成全体のおさらい。