Zum Hauptinhalt springen

Managed Agents Domain-Beschränkungen

Experte
What you'll learn
  • Verstehen, welche Bedrohungen eine Allow-/Block-Domainliste pro Tool in Managed Agents tatsächlich stoppt — und welche nicht
  • web_search und web_fetch mit dem configs-Array von agent_toolset_20260401 auf bestimmte Hosts festnageln
  • Die zehn Domain-Formatregeln lesen, die Anthropic beim Erstellen validiert, damit ein 400 deinen Bug nicht in die Produktion trägt
  • Die Multiagent-Semantik durchdenken — warum sich Allowlists schneiden und Blocklists über Koordinator und Roster hinweg addieren
  • Das url_not_allowed-tool_result und session.error-Events zur Laufzeit behandeln und wissen, wann die Re-Validierung stattfindet
  • Diese Einstellungen vom Domainfilter der Messages-API-Server-Tools und von der Sandbox-Netzwerkrichtlinie unterscheiden

Eine autonome Managed-Agents-Session, die web_search und web_fetch mitführt, ist ein Request-Fälscher mit Suchmaschine. Jeder String, den man ihr als "hilfreiche Referenz-URL" unterschieben kann — eine Prompt-Injection-Nutzlast in einer abgerufenen Seite, ein Link in einem Memory Store, eine reine Modell-Halluzination — wird zu einer ausgehenden Anfrage, die Anthropics Crawler in deinem Namen stellt. Bis zu dieser Beta war die einzige Möglichkeit, das zu verhindern, die Tools abzuschalten und sie als selbst validierte Custom Tools wieder einzuführen.

Die Beta vom 26. August fügt erstklassige allowed_domains- und blocked_domains-Listen pro Tool hinzu — plus max_content_tokens bei Fetches und user_location bei Suchen — durchgesetzt auf Anthropics Servern, bevor die ausgehende Anfrage gestellt wird. Zwei Dinge an dieser Formulierung sind wichtig:

  • Die Durchsetzung erfolgt auf Anthropics Servern, nicht in deiner Sandbox. Die Sandbox-networking-Richtlinie (die steuert, was Code innerhalb der Sandbox erreichen kann) hat also nichts damit zu tun. Wenn du das Toolset ohne Domainlisten lässt, aber das Sandbox-Netzwerk abriegelst, erreicht das web_fetch des Agents trotzdem, was es will — der Fetch läuft außerhalb der Sandbox.
  • Organisationsweite Webfilter in der Claude Console gelten nur für die Messages API. Sie hängen sich nicht an Managed-Agents-Sessions. Wenn deine Organisation eine Console-Regel "ads.example.com blockieren" hat und du sie nie ins Toolset spiegelst, wird eine Agent-Session sie abrufen.

Wo die Einstellung lebt​

Jedes eingebaute Tool sitzt im Toolset-Objekt agent_toolset_20260401 im tools-Array des Agents, und jedes Tool wird über einen Eintrag im configs-Array dieses Toolsets konfiguriert. Einträge werden über name identifiziert (web_search, web_fetch, bash, read, write, edit, glob, grep), über ein optionales type-Feld mit demselben Wert typisiert und akzeptieren — für die beiden Web-Tools — allowed_domains, blocked_domains, max_content_tokens und user_location neben den üblichen enabled und permission_policy.

Die minimale Form:

web_search und web_fetch auf zwei Hosts festnageln, abgerufenen Inhalt deckeln

{
"type": "agent_toolset_20260401",
"configs": [
  {
    "name": "web_search",
    "allowed_domains": ["docs.example.com", "arxiv.org"],
    "user_location": {
      "type": "approximate",
      "country": "US",
      "timezone": "America/Los_Angeles"
    }
  },
  {
    "name": "web_fetch",
    "blocked_domains": ["ads.example.com"],
    "max_content_tokens": 50000
  }
]
}

Jedes Tool trägt seine eigene Liste — eine Such-Allowlist beschränkt keine Fetches und umgekehrt. Wenn die beiden Listen gemeinsam laufen sollen, musst du sie selbst spiegeln.

Ein vollständiger Agent-Create​

POST /v1/agents — der ganze Request

curl -fsSL https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
  "name": "Research Agent",
  "model": "claude-opus-5",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "configs": [
        {
          "name": "web_search",
          "allowed_domains": ["docs.example.com", "arxiv.org"],
          "user_location": {
            "type": "approximate",
            "country": "US",
            "timezone": "America/Los_Angeles"
          }
        },
        {
          "name": "web_fetch",
          "blocked_domains": ["ads.example.com"],
          "max_content_tokens": 50000
        }
      ]
    }
  ]
}'

In den SDKs für Python, TypeScript, Go, Java, C#, Ruby und PHP ist jeder configs-Eintrag pro Tool als Discriminated Union typisiert (BetaManagedAgentsWebSearchToolConfigParams, BetaManagedAgentsWebFetchToolConfigParams und so weiter). type ist beim Erstellen optional, weil der Server es aus name ableitet, kommt aber in Antworten immer zurück. Requests, die nur name, enabled und permission_policy setzen, bleiben mit oder ohne type gültig — alter Code muss für diese Beta nicht umgeschrieben werden.

Die zehn Domain-Formatregeln​

Anthropic validiert jede gelistete Domain beim Erstellen/Aktualisieren des Agents und beim Erstellen/Aktualisieren der Session und gibt einen 400 invalid_request_error zurück, dessen Meldung die Liste und die nullbasierte Position des fehlerhaften Eintrags nennt (allowed_domains.0: IP addresses are not supported…). Die Regeln sind strenger als das, was die Messages API akzeptiert, und jede einzelne ist in der Praxis eine Stolperfalle:

Guided walkthrough1 of 10
  1. Setze auf einem Eintrag entweder allowed_domains oder blocked_domains — nie beides. Ein Eintrag mit beiden wird abgelehnt: "Only one of allowed_domains or blocked_domains may be set."

Zwei zusätzliche Prüfungen hängen von den zugrunde liegenden Anbietern ab und werden ebenfalls beim Erstellen/Aktualisieren durchgesetzt: Eine Domain, auf die Anthropics Crawler nicht zugreifen kann, wird für allowed_domains verweigert, ein nicht unterstütztes user_location.country liefert eine Meldung, die auf user_location.country: not a country the search provider supports endet, und user_location.timezone muss ein gültiger IANA-Name sein.

Multiagent-Sessions — wie sich die Listen kombinieren​

Eine Multiagent-Session kann drei Listensätze auf einen einzigen Tool-Aufruf schichten: die aktuellen Listen des Koordinators, die Listen jedes Agents, der diesen aufgerufen hat, und die eigenen Listen des Roster-Agents. Jede Liste, die für den Thread gilt, wird gleichzeitig durchgesetzt.

  • Allowlists schneiden sich. Die wirksame Menge sind die Domains, die alle anwendbaren Allowlists abdecken. Ein Roster-Agent kann einengen, was ein Tool erreicht, aber nie erweitern — setze auf einem Roster-Agent eine Allowlist, die nicht in der Allowlist des Koordinators liegt, und jeder Aufruf kommt mit einem url_not_allowed-Fehler zurück, dessen Meldung besagt, dass keine Domain erlaubt ist. Die Tool-Beschreibung sagt das dem Modell von vornherein.
  • Blocklists addieren sich. Jede anwendbare Blocklist wird gemeinsam durchgesetzt, sodass jeder Host auf der Blocklist irgendeiner Ebene für diesen Thread unerreichbar ist.
  • max_content_tokens und user_location kombinieren sich nicht. Ein Thread liest zuerst seine eigene Tool-Konfiguration, dann die des aufrufenden Agents, dann die aktuelle Konfiguration des Koordinators — der erste Nicht-Null-Wert gewinnt.
  • Roster-Einträge mit {"type": "self"} haben keine eigenen Web-Einstellungen und folgen der aktuellen Konfiguration des Koordinators.
  • Der Grader in Outcome-getriebenen Sessions läuft ganz ohne Web-Tools — keine Allow- oder Blocklist spielt eine Rolle, weil der Grader weder web_search noch web_fetch ausführen kann.

Die Konsequenz: Wenn die Allowlist des Koordinators [docs.example.com, arxiv.org] ist und die eines Roster-Agents [github.com], hat der Roster-Agent null erreichbare Hosts. Entwirf die Allowlists der Roster-Agents als Teilmengen der Koordinator-Allowlist oder setze sie gar nicht.

Updates mitten in der Session und die zweite Validierung​

Du kannst die Tools einer inaktiven Session aktualisieren, um die Domainlisten zu ändern — die neuen Listen gelten ab diesem Zeitpunkt. In einer Multiagent-Session übernimmt jeder Thread die neuen Listen bei seinem nächsten Zug, aber die eigenen Listen eines Roster-Agents sind beim Erstellen der Session eingefroren (sie leben auf der Agent-Definition, nicht auf der Session).

Eine zweite Validierung findet statt, wenn die Session das Tool erstmals initialisiert. Eine Domain, die beim Erstellen die synchrone Prüfung bestanden hat, kann später trotzdem scheitern (ein erlaubter Host könnte in der Zwischenzeit den Crawler-Zugang verloren haben). Scheitert die Laufzeitprüfung, sendet die Session ein session.error-Event, kehrt zu idle zurück und versucht es nicht erneut. Die Lösung: die Tools der Session aktualisieren, zusätzlich den Agent aktualisieren, damit neue Sessions sauber starten, und dann eine frische user.message senden.

Der Laufzeit-Fehlerpfad​

Zur Session-Laufzeit verhalten sich die beiden Tools unterschiedlich, wenn sie auf eine URL stoßen, die ihre Listen verbieten.

  • web_fetch gibt dem Agent ein Fehlerergebnis zurück: is_error: true auf dem agent.tool_result-Event, mit einem Content-Block, der den Fehlercode url_not_allowed nennt. Das Modell sieht ihn und kann sich anpassen (eine andere Quelle wählen, den Nutzer fragen oder aufhören) — das ist ein normaler Tool-Fehlschlag, kein Session-Fehlschlag.
  • web_search lässt stillschweigend jedes Ergebnis weg, dessen Host die Listen nicht erlauben. Das Modell sieht sie überhaupt nicht. Das ist der richtige Standard für die Suche — die Alternative würde die URLs gefilterter Ergebnisse ins Transkript durchsickern lassen —, bedeutet aber, dass eine Suche, die für eine eigentlich gute Anfrage "keine Ergebnisse" liefert, ein Signal ist, die Allowlist zu erweitern, nicht nur erneut zu versuchen.

Beide Signale gehören in deinen Session-Event-Handler. session.error für den Fehlschlag bei der Initialisierung, agent.tool_result mit is_error: true und url_not_allowed für den Fehlschlag pro Aufruf und — als Raten-Signal — jeder Suchzug, dessen Ergebnisanzahl auf null fällt, wenn die Allowlist klein ist.

Unterschiede zum Domainfilter der Messages-API-Server-Tools​

Managed Agents fährt bewusst ein strengeres Regime als die web_search- und web_fetch-Filter der server_tools in der Messages API. Das Vokabular ist dasselbe, aber vier Dinge sind enger und eines fehlt ganz:

  • Die Listenobergrenze liegt bei 64 Domains, gegenüber der größeren Obergrenze der Messages API. Große Allowlists lassen sich nicht übertragen — teile sie auf mehrere Agents auf.
  • web_fetch-Domains dürfen keinen Pfad enthalten. Die Messages API akzeptiert Pfade bei beiden Tools. Wandle beim Portieren alle Messages-API-artigen example.com/blog-Einträge in reine Hostnamen um.
  • Nur ASCII — Punycode für internationalisierte Namen erforderlich. Die Messages API erlaubt Unicode-Einträge (rät aber davon ab).
  • max_uses, citations und cache_control sind im Toolset nicht verfügbar. Das sind reine Messages-API-Stellschrauben, die das Toolset bewusst nicht anbietet. Plane stattdessen mit der Preisgestaltung pro Session und dem response_inclusion-Parameter.

Wenn du einen bestehenden Messages-API-Agent zu Managed Agents portierst, lassen sich die meisten vorhandenen Filter sauber übertragen. Nackte example.com-Einträge, Subdomain-inklusives Matching und die Regel "eine Liste pro Eintrag" sind alle identisch.

Häufige Fallen — fünf, über die echte Teams stolpern​

  1. www.example.com ist nicht example.com. Nur www.example.com zu listen erlaubt nicht das nackte Apex example.com, und nur example.com zu listen deckt trotzdem www.example.com ab (weil www. eine Subdomain wie jede andere ist). Liste die nackte Domain, um beides zu bekommen.
  2. Die Sandbox-networking-Richtlinie beeinflusst diese Tools nicht. web_search und web_fetch laufen auf Anthropics Servern, also ruft eine Umgebung, die jeglichen Egress aus der Sandbox verweigert, trotzdem munter alles ab, was das Toolset erlaubt. Wenn du Defense in Depth willst, spiegle die beiden Richtlinien.
  3. Console-seitige Org-Filter hängen sich nicht an. Die organisationsweiten Webfilter in der Console gelten nur für die Messages API. Eine in der Console gesetzte Regel "ads.example.com blockieren" berührt Managed Agents nie.
  4. Ein Session-Budget impliziert keine Domain-Beschränkung. Session-Budgets deckeln Dollar, nicht Ziele. Eine budgetierte Session kann ihr Limit mit dem Abruf einer einzigen feindlichen Seite verbrennen. Nutze beides.
  5. Ein web_search-Pfadsuffix ist ein URL-Muster, keine Host-Regel. Bevorzuge reine Hostnamen — Pfadfilter bei der Suche haben nur beratende Stärke, und der Anbieter kann sie lockerer matchen, als du erwartest.

Was das tatsächlich abmildert​

Sei präzise beim Bedrohungsmodell — Übertreibung an dieser Stelle rächt sich bei Teams, die annehmen, das sei eine vollständige SSRF-Lösung. Das ist es nicht. Die drei konkreten Risiken, die es tatsächlich adressiert:

  • Prompt-Injection-Navigation. Eine vergiftete Seite oder ein Memory-Store-Eintrag, der den Agent anweist, "diese URL abzurufen, um fortzufahren", scheitert mit url_not_allowed, wenn der Host nicht erlaubt ist, und das Modell sieht den Fehler und hört (meistens) auf.
  • Werbe- und Telemetrie-Ziele. Eine Blocklist hält die Fetches des Agents von Tracking-Domains fern, zu denen eine Zielseite den Agent weiterleiten will.
  • Datenexfiltration per Fetch. Ein Agent, der dazu gebracht wird, eine web_fetch-URL mit sensiblen Query-String-Parametern (?leaked=<memory>) zu bauen, kann keinen feindlichen Empfänger erreichen, dessen Host nicht erlaubt ist.

Was es nicht stoppt: ausgehende Anfragen von Custom Tools, die du definierst, von MCP-Server-Tools, von Code, den deine Sandbox ausführt, oder von jedem Tool, das nicht web_search/web_fetch ist. Jedes davon hat seine eigene Stellschraube (Sandbox-networking, MCP-Server-Allowlists, Custom-Tool-Code). Diese eine Einstellung ist eine Schicht in einer vielschichtigen Geschichte.

Key takeaways
  • allowed_domains und blocked_domains leben pro Tool im configs-Array von agent_toolset_20260401; jedes Tool trägt seine eigene Liste, und sie laufen nicht automatisch gemeinsam
  • Zehn Formatregeln — kein Schema, kein Port, keine Wildcard, kein Pfad bei web_fetch, keine nackten TLDs, kein localhost oder .local, Punycode für IDNs, 1-64 Domains, keine Duplikate, Subdomain-Match nur nach unten
  • Multiagent-Semantik: Allowlists schneiden sich, Blocklists addieren sich. Ein Roster-Agent kann die Reichweite des Koordinators einengen, aber nie erweitern
  • Laufzeit: web_fetch scheitert an einer verbotenen URL mit is_error und url_not_allowed; web_search lässt verbotene Ergebnisse stillschweigend weg
  • Das gilt nur für Managed Agents. Console-Org-Filter hängen sich nicht an, und die Sandbox-Netzwerkrichtlinie beeinflusst diese Tools nicht — spiegle Regeln, wenn du Defense in Depth willst
  • Nicht dasselbe wie der Messages-API-Server-Tools-Filter: strenger (64er-Obergrenze, keine Pfade bei web_fetch, nur ASCII) und ohne max_uses, citations, cache_control

Prüfe dich selbst​

Prüfe dich selbst

0/5
  1. Du setzt allowed_domains: ["example.com"] auf dem web_fetch-Eintrag. Welche dieser URLs darf der Agent abrufen?
  2. Die web_fetch-Allowlist eines Koordinators ist ["docs.example.com", "arxiv.org"]. Ein Roster-Agent setzt seine eigene web_fetch-Allowlist auf ["github.com"]. Was passiert, wenn der Roster-Agent versucht, https://github.com/anthropic-ai/sdk abzurufen?
  3. Dein Team blockiert per Richtlinie ads.example.com auf Org-Ebene in der Claude Console. Du startest eine Managed-Agents-Session mit aktiviertem web_fetch und ohne Domainlisten. Der Agent ruft https://ads.example.com ab. Was passiert?
  4. Du reichst einen Agent mit allowed_domains: ["https://docs.example.com", "127.0.0.1", "co.uk"] ein. Was gibt die API zurück?
  5. Was macht ein web_fetch-Aufruf für eine URL, die seine Liste nicht erlaubt?

Quellen und weiterführende Lektüre​

Weiter​

  • Managed Agents — das mentale Modell aus Koordinator + Session, in dem diese Domainlisten mitfahren
  • Managed Agents Session-Budgets — die harte Dollar-Obergrenze, die sich mit Domainlisten als zweite Leitplanke kombinieren lässt
  • Prompt Injection — die Angriffsklasse, die eine gut abgegrenzte Allowlist tatsächlich abmildert
  • Autonome Läufe absichern — das dreischichtige Leitplankenmodell, in das sich das einfügt