権限ポリシー

権限ポリシーは、サーバー実行ツール（事前構築されたエージェントツールセットとMCPツールセット）が自動的に実行されるか、承認を待つかを制御します。カスタムツールはアプリケーションによって実行され、ユーザーによって制御されるため、権限ポリシーの対象ではありません。

すべてのManaged Agents APIリクエストには、managed-agents-2026-04-01ベータヘッダーが必要です。SDKはベータヘッダーを自動的に設定します。

権限ポリシーの種類

ポリシー	動作
`always_allow`	ツールは確認なしで自動的に実行されます。
`always_ask`	セッションは`session.status_idle`イベントを発行し、実行前に`user.tool_confirmation`イベントを待ちます。

ツールセットのポリシーを設定する

エージェントツールセットの権限

エージェントを作成する際、default_config.permission_policyを使用して、agent_toolset_20260401内のすべてのツールにポリシーを適用することができます。

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-7
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
YAML

default_configはオプション設定です。これを省略した場合、エージェントツールセットはデフォルトの権限ポリシーであるalways_allowで有効になります。

MCPツールセットの権限

MCPツールセットはデフォルトでalways_askです。これにより、MCPサーバーに追加された新しいツールがアプリケーションで承認なしに実行されないようになります。信頼できるMCPサーバーからのツールを自動承認するには、mcp_toolsetエントリでpermission_policyを設定します。

mcp_server_nameは、mcp_servers配列で参照されるnameと一致する必要があります。

この例は、GitHub MCPサーバーを接続し、そのツールが確認なしで実行されるようにします。

個別ツールのポリシーをオーバーライドする

configs配列を使用して、個別ツールのデフォルトをオーバーライドします。この例では、エージェントツールセット全体をデフォルトで許可しますが、bashコマンドが実行される前に確認が必要です。

確認リクエストに応答する

エージェントがalways_askポリシーでツールを呼び出す場合：

セッションはagent.tool_useまたはagent.mcp_tool_useイベントを発行します。
セッションはsession.status_idleイベントで一時停止し、stop_reason: requires_actionが含まれます。ブロッキングイベントIDはstop_reason.requires_action.event_ids配列にあります。
各イベントに対してuser.tool_confirmationイベントを送信し、tool_use_idパラメータでイベントIDを渡します。resultを"allow"または"deny"に設定します。deny_messageを使用して拒否の理由を説明します。
すべてのブロッキングイベントが解決されると、セッションはrunningに戻ります。

イベント処理の詳細については、セッションイベントストリームガイドを参照してください。

カスタムツール

権限ポリシーはカスタムツールには適用されません。エージェントがカスタムツールを呼び出すと、アプリケーションはagent.custom_tool_useイベントを受け取り、user.custom_tool_resultを送信する前に実行するかどうかを決定する責任があります。完全なフローについては、セッションイベントストリームを参照してください。

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-7
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: always_allow
YAML

tools = [
    {
        "type": "agent_toolset_20260401",
        "default_config": {
            "permission_policy": {"type": "always_allow"},
        },
        "configs": [
            {
                "name": "bash",
                "permission_policy": {"type": "always_ask"},
            },
        ],
    },
]

# ツールの実行を許可する
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# または説明付きで拒否する
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": mcp_tool_use_event.id,
            "result": "deny",
            "deny_message": "Don't create issues in the production project. Use the staging project.",
        },
    ],
)