Berechtigungsrichtlinien

Berechtigungsrichtlinien steuern, ob vom Server ausgeführte Tools (der vordefinierte Agent-Toolset und MCP-Toolset) automatisch ausgeführt werden oder auf Ihre Genehmigung warten. Benutzerdefinierte Tools werden von Ihrer Anwendung ausgeführt und von Ihnen kontrolliert, daher unterliegen sie nicht den Berechtigungsrichtlinien.

Alle Managed Agents API-Anfragen erfordern den managed-agents-2026-04-01 Beta-Header. Das SDK setzt den Beta-Header automatisch.

Berechtigungsrichtlinien-Typen

Richtlinie	Verhalten
`always_allow`	Das Tool wird automatisch ohne Bestätigung ausgeführt.
`always_ask`	Die Sitzung sendet ein `session.status_idle` Ereignis und wartet auf ein `user.tool_confirmation` Ereignis, bevor es ausgeführt wird.

Legen Sie eine Richtlinie für einen Toolset fest

Berechtigungen für Agent-Toolset

Beim Erstellen eines Agenten können Sie optional eine Richtlinie auf alle Tools in agent_toolset_20260401 anwenden, indem Sie default_config.permission_policy verwenden:

default_config ist eine optionale Einstellung. Wenn Sie sie weglassen, wird der Agent-Toolset mit der Standard-Berechtigungsrichtlinie always_allow aktiviert.

Berechtigungen für MCP-Toolset

MCP-Toolsets verwenden standardmäßig always_ask. Dies stellt sicher, dass neue Tools, die einem MCP-Server hinzugefügt werden, nicht ohne Genehmigung in Ihrer Anwendung ausgeführt werden. Um Tools von einem vertrauenswürdigen MCP-Server automatisch zu genehmigen, legen Sie permission_policy im mcp_toolset Eintrag fest.

Der mcp_server_name muss dem name entsprechen, auf den in dem mcp_servers Array verwiesen wird.

Dieses Beispiel verbindet einen GitHub MCP-Server und ermöglicht es seinen Tools, ohne Bestätigung ausgeführt zu werden:

Überschreiben Sie eine einzelne Tool-Richtlinie

Verwenden Sie das configs Array, um die Standardeinstellung für einzelne Tools zu überschreiben. Dieses Beispiel erlaubt den vollständigen Agent-Toolset standardmäßig, erfordert aber eine Bestätigung, bevor ein Bash-Befehl ausgeführt wird:

Reagieren Sie auf Bestätigungsanfragen

Wenn der Agent ein Tool mit einer always_ask Richtlinie aufruft:

Die Sitzung sendet ein agent.tool_use oder agent.mcp_tool_use Ereignis.
Die Sitzung pausiert mit einem session.status_idle Ereignis, das stop_reason: requires_action enthält. Die blockierenden Ereignis-IDs befinden sich im stop_reason.requires_action.event_ids Array.
Senden Sie ein user.tool_confirmation Ereignis für jedes, und übergeben Sie die Ereignis-ID im tool_use_id Parameter. Setzen Sie result auf "allow" oder "deny". Verwenden Sie deny_message, um eine Ablehnung zu erklären.
Sobald alle blockierenden Ereignisse gelöst sind, wechselt die Sitzung zurück zu running.

Weitere Informationen zur Ereignisbehandlung finden Sie im Leitfaden Sitzungs-Ereignisstrom.

Benutzerdefinierte Tools

Berechtigungsrichtlinien gelten nicht für benutzerdefinierte Tools. Wenn der Agent ein benutzerdefiniertes Tool aufruft, erhält Ihre Anwendung ein agent.custom_tool_use Ereignis und ist verantwortlich für die Entscheidung, ob es ausgeführt werden soll, bevor ein user.custom_tool_result zurückgesendet wird. Siehe Sitzungs-Ereignisstrom für den vollständigen Ablauf.

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

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"},
            },
        ],
    },
]

# Tool ausführen erlauben
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# Oder lehnen Sie es mit einer Erklärung ab
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.",
        },
    ],
)