Berechtigungsrichtlinien

„Permission policies" (Berechtigungsrichtlinien) steuern, ob serverseitig ausgeführte Tools (das vorgefertigte Agent-Toolset und das MCP-Toolset) automatisch ausgeführt werden oder auf deine Genehmigung warten. Benutzerdefinierte Tools werden von deiner Anwendung ausgeführt und von dir gesteuert, daher unterliegen sie nicht den Berechtigungsrichtlinien.



Arten von Berechtigungsrichtlinien

Jede Toolset-Art hat ihren eigenen Standardwert: Das Agent-Toolset verwendet standardmäßig always_allow, und MCP-Toolsets verwenden standardmäßig always_ask.

Eine Berechtigungsrichtlinie steuert, wann ein aktiviertes Tool ausgeführt wird. Um ein Tool vollständig aus dem Agent zu entfernen, deaktiviere es stattdessen. Siehe Bestimmte Tools deaktivieren.



Eine Richtlinie für ein Toolset festlegen

Du legst Berechtigungsrichtlinien in der tools-Konfiguration des Agents fest, wenn du den Agent erstellst, und kannst sie später ändern, indem du den Agent aktualisierst. Laufende Sessions behalten die Toolset-Konfiguration, mit der sie erstellt wurden. Aktualisierungen gelten für danach erstellte Sessions.



Berechtigungen für das Agent-Toolset

Beim Erstellen eines Agents kannst du mit default_config.permission_policy eine Richtlinie auf jedes Tool in agent_toolset_20260401 anwenden:

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

default_config ist optional. Wenn du es weglässt, wird das Agent-Toolset mit der Standard-Berechtigungsrichtlinie always_allow aktiviert.



Berechtigungen für MCP-Toolsets

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

Der mcp_server_name muss mit dem name eines Servers im mcp_servers-Array übereinstimmen.

Dieses Beispiel verbindet einen GitHub-MCP-Server und erlaubt dessen Tools, ohne Bestätigung ausgeführt zu werden:

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-8
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



Eine einzelne Tool-Richtlinie überschreiben

Verwende das configs-Array, um den Standardwert für einzelne Tools zu überschreiben. Die name-Werte für das Agent-Toolset sind unter Verfügbare Tools aufgelistet. Dieses Beispiel erlaubt standardmäßig das gesamte Agent-Toolset, erfordert aber eine Bestätigung, bevor ein Bash-Befehl ausgeführt wird:

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

Übergib diese tools-Konfiguration in der Agent-Erstellungsanfrage (der CLI-Tab zeigt den vollständigen Befehl). MCP-Toolsets unterstützen dieselben Überschreibungen pro Tool, wobei name auf den vom MCP-Server gemeldeten Tool-Namen gesetzt wird. Siehe Konfigurieren, welche MCP-Tools verfügbar sind.



Auf Bestätigungsanfragen reagieren

Wenn der Agent ein Tool mit einer always_ask-Richtlinie aufruft:

1. Die Session gibt ein agent.tool_use- oder agent.mcp_tool_use-Event aus.
2. Die Session pausiert mit einem session.status_idle-Event, dessen stop_reason.type den Wert requires_action hat. Die blockierenden Event-IDs befinden sich im stop_reason.event_ids-Array. Die Session wartet unbegrenzt auf eine Antwort.
3. Sende ein user.tool_confirmation-Event für jedes blockierende Event und übergib die Event-ID im tool_use_id-Parameter. Setze result auf "allow" oder "deny". Verwende deny_message, um eine Ablehnung zu begründen. Du kannst mehrere Bestätigungen in einer einzigen events-Anfrage senden.
4. Sobald alle blockierenden Events aufgelöst sind, wechselt die Session zurück zu running. Erlaubte Tools werden ausgeführt. Abgelehnte Tools werden nicht ausgeführt, und der Agent erhält ein Tool-Ergebnis, das besagt, dass der Aufruf abgelehnt wurde, einschließlich deiner deny_message.

In den folgenden Beispielen stammen die Tool-Use-Event-IDs aus dem stop_reason.event_ids-Array des session.status_idle-Events. Erfahre mehr über das Empfangen von Events im Leitfaden Session-Event-Stream, oder abonniere Webhooks, um benachrichtigt zu werden, wenn eine Session auf Eingaben wartet.

# Erlaube die Ausführung des Tools
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# Oder lehne es mit einer Begründung ab
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{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.}"



Benutzerdefinierte Tools

Berechtigungsrichtlinien gelten nicht für benutzerdefinierte Tools. Wenn der Agent ein benutzerdefiniertes Tool aufruft, erhält deine Anwendung ein agent.custom_tool_use-Event und ist dafür verantwortlich zu entscheiden, ob es ausgeführt werden soll, bevor ein user.custom_tool_result zurückgesendet wird. Siehe Session-Event-Stream für den vollständigen Ablauf.



Nächste Schritte