Berechtigungsrichtlinien

„Permission policies" (Berechtigungsrichtlinien) steuern, ob serverseitig ausgeführte Tools (das vorgefertigte Agent-Toolset und das MCP-Toolset) automatisch laufen, auf deine Genehmigung warten oder jeden Aufruf vom Server bewerten lassen. „Custom tools" (benutzerdefinierte Tools) werden von deiner Anwendung ausgeführt und von dir gesteuert, daher unterliegen sie keinen Berechtigungsrichtlinien.

Typen 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 Agenten zu entfernen, deaktiviere es stattdessen. Siehe Bestimmte Tools deaktivieren.

Eine Richtlinie für ein Toolset festlegen

Du legst Berechtigungsrichtlinien in der tools-Konfiguration des Agenten fest, wenn du den Agenten erstellst, und du kannst sie später ändern, indem du den Agenten 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 Agenten kannst du mit default_config.permission_policy eine Richtlinie auf jedes Tool in agent_toolset_20260401 anwenden:

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
---

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, dass dessen Tools ohne Bestätigung ausgeführt werden:

ant apply agent.md

---
name: Dev Assistant
model: claude-opus-5-5
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
---

Die Richtlinie eines einzelnen Tools ü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 aufgeführt. Dieses Beispiel erlaubt standardmäßig das vollständige Agent-Toolset, verlangt aber eine Bestätigung, bevor ein Bash-Befehl ausgeführt wird:

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
---

Übergib diese tools-Konfiguration in der Anfrage zum Erstellen des Agenten (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.

Den Server jeden Aufruf mit auto bewerten lassen

Mit der Berechtigungsrichtlinie auto bewertet der Server jeden Aufruf, bevor er ausgeführt wird. Da die Bewertung das Tool, die Eingabe des Aufrufs und den bisherigen Inhalt der Sitzung berücksichtigt, kann der Server zwei Aufrufe desselben Tools unterschiedlich behandeln. Jeder Aufruf hat eines von drei Ergebnissen:

• Der Aufruf wird ausgeführt. Wenn der Server feststellt, dass der Aufruf sicher ist, wird das Tool so ausgeführt, wie es unter always_allow der Fall wäre.
• Der Aufruf wird abgelehnt. Wenn der Server den Aufruf als hochriskant bewertet, wird das Tool nicht ausgeführt. Der Agent erhält ein fehlerhaftes Tool-Ergebnis mit dem Inhalt Permission to use {tool_name} has been denied. und is_error: true. Die Sitzung läuft weiter, und dein Client kann die Ablehnung nicht überschreiben.
• Der Aufruf pausiert für deine Genehmigung. Wenn der Server zu keiner Entscheidung kommt, pausiert die Sitzung wie unter always_ask. Siehe Auf Bestätigungsanfragen antworten.

Um auto zu aktivieren, setze permission_policy auf {"type": "auto"}. Es gehört an dieselben zwei Stellen wie die anderen Richtlinien: in die default_config eines Toolsets für das gesamte Toolset oder in einen configs-Eintrag für ein einzelnes Tool. Sowohl das Agent-Toolset als auch MCP-Toolsets akzeptieren es. Kein Toolset verwendet standardmäßig auto.

Das folgende Beispiel setzt auto als Standard für das Agent-Toolset und für das github-MCP-Toolset und überschreibt bash mit always_ask:

ant apply agent.md

---
name: Ops Agent
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: auto
    configs:
      - name: bash
        permission_policy:
          type: always_ask
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: auto
---

Was du in user.message-Ereignissen sendest, gilt als deine Absicht und kann dazu führen, dass der Server einen Aufruf erlaubt, den er sonst ablehnen würde. Der Server liest keine Absicht aus einem Tool-Ergebnis, einer abgerufenen Webseite, der Antwort eines MCP-Servers oder einer Nachricht zwischen Sitzungs-Threads. Er bewertet diese Inhalte, nimmt aber keine Anweisungen daraus entgegen. Manche Aufrufe bewertet der Server als hochriskant, unabhängig davon, wer sie anfordert. Wenn du nicht vertrauenswürdige Eingaben von Endnutzern in user.message-Ereignissen weiterleitest, liest der Server diese Eingaben ebenfalls als deine Absicht, und sie können dazu führen, dass ein Aufruf erlaubt wird. Konfiguriere always_ask für die Tools, die dieser Endnutzer nicht ohne Überprüfung ausführen dürfte.

Sehen, wie jeder Aufruf bewertet wurde

Unter jeder Berechtigungsrichtlinie enthält jedes agent.tool_use- und agent.mcp_tool_use-Ereignis evaluated_permission, das Ergebnis der Berechtigungsprüfung des Aufrufs: "allow", "ask" oder "deny". Die meisten Ereignisse enthalten außerdem ein evaluation-Objekt, dessen type die Richtlinie benennt, die dieses Ergebnis erzeugt hat. Unter auto hält das Objekt zusätzlich die Entscheidung des Servers fest, sowie einen reason_code, wenn das Ergebnis ask oder deny ist.

Wenn beispielsweise bash unter auto steht und der Server einen Aufruf als hochriskant bewertet, erscheint der abgelehnte Aufruf im Ereignisstream wie folgt:

{
  "type": "agent.tool_use",
  "id": "sevt_01pqr...",
  "name": "bash",
  "input": {
    "command": "rm -rf /workspace/reports"
  },
  "evaluated_permission": "deny",
  "evaluation": {
    "type": "auto",
    "evaluated_permission": {
      "type": "deny",
      "reason_code": "high_risk"
    }
  },
  "processed_at": "2026-03-25T14:05:12Z"
}

Das evaluation-Objekt nimmt eine der Formen aus der folgenden Tabelle an.

Wenn evaluation.type den Wert "auto" hat, wiederholt das verschachtelte evaluated_permission.type das evaluated_permission des Ereignisses auf oberster Ebene, sodass du das Ergebnis aus beiden Feldern lesen kannst. Ein reason_code ist ein Wert, anhand dessen dein Client verzweigen und den er in Audit-Aufzeichnungen festhalten kann, kein Text zur Anzeige für Endnutzer.

evaluation fehlt in zwei Fällen. Wenn der Agent ein Tool benennt, das in der Sitzung nicht aktiviert ist, lehnt der Server den Aufruf ab, ohne eine Richtlinie zu bewerten: Das Ereignis enthält evaluated_permission: "deny" und kein evaluation. Ereignisse, die vor der Einführung von evaluation aufgezeichnet wurden, lassen es ebenfalls weg: Interpretiere diese als always_allow, wenn evaluated_permission den Wert "allow" hat, und als always_ask, wenn es "ask" ist.

Schreibe deinen Client so, dass er einen evaluation.type oder reason_code toleriert, den er nicht kennt. agent.custom_tool_use-Ereignisse enthalten keines der beiden Felder, da Berechtigungsrichtlinien nicht für benutzerdefinierte Tools gelten.

Auf Bestätigungsanfragen antworten

Ein Tool-Aufruf wird unter einer always_ask-Richtlinie zu ask ausgewertet, oder unter auto, wenn der Server zu keiner Entscheidung kommt. Wenn das passiert:

1. Die Session gibt ein agent.tool_use- oder agent.mcp_tool_use-Ereignis aus.
2. Die Session pausiert mit einem session.status_idle-Ereignis, dessen stop_reason.type den Wert requires_action hat. Die blockierenden Ereignis-IDs befinden sich im stop_reason.event_ids-Array. Die Session wartet unbegrenzt auf eine Antwort.
3. Sende für jedes blockierende Ereignis ein user.tool_confirmation-Ereignis und übergib dabei die Ereignis-ID im Parameter tool_use_id. 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 Ereignisse 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.

Wenn du ein user.tool_confirmation für ein Ereignis sendest, dessen evaluated_permission nicht ask ist, lehnt die API es mit einem 400-Fehler ab. Das schließt Aufrufe ein, die der Server unter auto abgelehnt hat: Dein Client kann sie nicht überschreiben.

Um stattdessen interaktiv zu antworten, verwende ant beta:sessions connect. Dieser Befehl zeigt den wartenden Aufruf an und sendet dieses Ereignis, wenn du ihn erlaubst oder ablehnst. Siehe Von deinem Terminal aus eine Verbindung zu einer Managed-Agents-Sitzung herstellen.

In den folgenden Beispielen stammen die Tool-Use-Ereignis-IDs aus dem stop_reason.event_ids-Array des session.status_idle-Ereignisses. Erfahre mehr über das Empfangen von Ereignissen im Leitfaden Session-Ereignisstream, oder abonniere Webhooks, um benachrichtigt zu werden, wenn eine Session für eine Eingabe pausiert.

# Erlaube die Ausführung des Tools
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# Oder lehne sie mit einer Begründung 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.",
        },
    ],
)

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-Ereignis und ist dafür verantwortlich zu entscheiden, ob es ausgeführt wird, bevor sie ein user.custom_tool_result zurücksendet. Siehe Session-Ereignisstream für den vollständigen Ablauf.

Nächste Schritte