Domains für Websuche und Web-Fetch einschränken

Um zu steuern, welche Websites die Web-Tools des Agenten erreichen können, lege eine Domainliste für die Einträge web_search und web_fetch des Agent-Toolsets fest. Jeder dieser configs-Einträge akzeptiert eine von zwei Listen:

• allowed_domains: Das Tool kann nur diese Hosts erreichen.
• blocked_domains: Das Tool kann diese Hosts niemals erreichen.

Jedes Tool hat seine eigene Liste, sodass web_search und web_fetch unterschiedliche Einschränkungen haben können.

Domainlisten für einen Agenten festlegen

Das folgende Beispiel erstellt einen Agenten, der web_search auf zwei Websites beschränkt und einen Host für web_fetch blockiert. Außerdem setzt es user_location und max_content_tokens, die unter Einstellungen beschrieben werden. Anschließend gibt das Beispiel das configs-Array aus der Antwort aus.

ant apply agent.md

---
name: Research Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - type: web_search
        name: web_search
        allowed_domains: [docs.example.com, arxiv.org]
        user_location:
          type: approximate
          country: US
          timezone: America/Los_Angeles
      - type: web_fetch
        name: web_fetch
        blocked_domains: [ads.example.com]
        max_content_tokens: 50000
---

In einer Cloud-Umgebung mit limited Networking gelten die allowed_hosts der Umgebung auch für web_search und web_fetch. Das Erstellen einer Session schlägt mit einem 400-Fehler fehl, wenn die allowed_domains eines aktivierten Web-Tools einen Eintrag enthalten, der nicht innerhalb von allowed_hosts liegt. Dasselbe gilt für ein Session-Update, das einen solchen Eintrag hinzufügt. Um das zu beheben, füge den Host zu allowed_hosts hinzu oder entferne den Eintrag aus allowed_domains. Zur Laufzeit gibt ein web_fetch-Aufruf für eine URL auf einem Host, auf den allowed_hosts nicht zutrifft, ein url_not_allowed-Fehlerergebnis zurück. web_search lässt Ergebnisse von solchen Hosts weg. Die beiden Listen werden unterschiedlich abgeglichen: Ein Eintrag eines Tools deckt seine Subdomains ab, ein allowed_hosts-Eintrag hingegen trifft auf genau einen Host zu, es sei denn, er beginnt mit *.. Zum Beispiel liegt der Tool-Eintrag docs.example.com nicht innerhalb von allowed_hosts mit ["example.com"], wohl aber innerhalb von ["docs.example.com"] oder ["*.example.com"].

Lege in der Claude Console erlaubte oder blockierte Domains in den Zeilen web_search und web_fetch der Karte Built-in tools im Agentenformular fest. Setze max_content_tokens und user_location in der Raw-Ansicht der Agentenkonfiguration.

Einstellungen

Zusätzlich zu enabled und permission_policy akzeptieren die Web-Tool-Einträge die folgenden Einstellungen:

Wie die SDKs diese Einträge typisieren, erfährst du unter Typen von Konfigurationseinträgen in den SDKs.

Wenn eine Domain nicht erlaubt ist

web_search lässt Ergebnisse weg, die seine Domainliste nicht erlaubt. Ein web_fetch-Aufruf für eine URL, die seine Domainliste nicht erlaubt, gibt ein Fehlerergebnis an den Agenten zurück. Das agent.tool_result-Event hat is_error: true, und sein Inhalt nennt den Fehlercode url_not_allowed.

Regeln für Domainlisten

Diese Regeln gelten gleichermaßen für allowed_domains und blocked_domains. Eine Anfrage, die gegen eine davon verstößt, wird abgelehnt, wie unter Validierungsfehler beschrieben.

• Eine Liste pro Eintrag: Setze für einen Eintrag entweder allowed_domains oder blocked_domains, nicht beide.
• Listengröße: Jede Liste enthält 1 bis 64 Domains mit jeweils 1 bis 255 Zeichen.
• Keine leeren Listen: Um keine Einschränkung anzuwenden, lass das Feld weg oder sende null.
• Keine Duplikate: Eine Domain darf nur einmal in einer Liste vorkommen. www.example.com und example.com gelten als unterschiedliche Domains.

Worauf eine gelistete Domain zutrifft

Eine gelistete Domain trifft auf diesen Host und alle seine Subdomains zu. example.com deckt docs.example.com ab, aber docs.example.com deckt weder example.com noch api.example.com ab.

Ein führendes www. ist eine Subdomain wie jede andere, daher deckt www.example.com nicht example.com ab. Führe die reine Domain auf, um beide abzudecken.

Hostnamen werden ohne Berücksichtigung der Groß- und Kleinschreibung verglichen.

Domainformat

Jede Domain ist ein registrierbarer Domainname oder eine Subdomain davon, geschrieben als einfacher Hostname. Sie kann ASCII-Buchstaben, Ziffern, Bindestriche, Unterstriche und Punkte enthalten. Ein einzelnes abschließendes / wird ignoriert.

Eine Domain wird außerdem abgelehnt, wenn sie Anmeldedaten oder Leerzeichen enthält oder wenn eines ihrer Labels mit einem Bindestrich beginnt oder endet. localhost und Hosts, die auf .localhost, .local, .internal, .localdomain oder .invalid enden, werden ebenfalls abgelehnt.

Pfadsuffixe bei Websuche-Domains

Eine web_search-Domain kann ein Pfadsuffix tragen, etwa example.com/blog. Der Pfad darf keine Leerzeichen, ?, # oder eines der Zeichen $ , | ^ ! enthalten.

Bevorzuge auch für web_search einfache Hostnamen. Der Suchanbieter gleicht Pfadsuffixe als URL-Muster ab statt als strikte Host-Regeln.

Validierungsfehler

Die API validiert diese Einstellungen, wenn du einen Agenten erstellst oder einen Agenten aktualisierst. Sie validiert sie auch, wenn du eine Session erstellst oder aktualisierst, die tools angibt.

Format- und Limitverstöße werden mit einem 400-Fehler invalid_request_error abgelehnt:

Bei denselben Anfragen lehnt die API außerdem drei Einstellungen ab, die von den Such- und Abrufanbietern abhängen:

• Eine Domain in allowed_domains, auf die der Crawler von Anthropic nicht zugreifen darf.
• Ein user_location.country, das der Suchanbieter nicht unterstützt. Die Meldung endet mit user_location.country: not a country the search provider supports.
• Eine user_location.timezone, die kein gültiger IANA-Name ist.

In einer Cloud-Umgebung mit limited Networking prüfen das Erstellen und Aktualisieren von Sessions außerdem allowed_domains gegen die allowed_hosts der Umgebung. Siehe die Regel unter Domainlisten für einen Agenten festlegen.

Wenn eine akzeptierte Einstellung nicht mehr gültig ist

Die Session prüft die Konfiguration erneut, wenn sie das Tool zum ersten Mal initialisiert. Ist eine zuvor akzeptierte Einstellung zu diesem Zeitpunkt nicht mehr gültig, gibt die Session ein session.error-Event aus. Anschließend kehrt sie ohne erneuten Versuch zu idle zurück.

Um die Session fortzusetzen:

1. Korrigiere die Einstellung, indem du die Tools der Session aktualisierst.
2. Aktualisiere auch den Agenten, damit neue Sessions mit der korrigierten Konfiguration starten.
3. Sende eine neue user.message.

Multiagenten- und ergebnisorientierte Sessions

In einer Multiagenten-Session wird jede Domainliste, die für einen Thread gilt, gleichzeitig durchgesetzt. Ein Agent im Roster des Koordinators ist an drei Gruppen von Listen gebunden:

• Seine eigenen allowed_domains und blocked_domains
• Die Listen jedes Agenten, der ihn aufgerufen hat
• Die aktuellen Listen des Koordinators

Die Einstellungen werden wie folgt kombiniert:

Ein Roster-Agent kann daher einschränken, was ein Tool erreicht, es aber nie erweitern:

• Ein Roster-Agent, der blocked_domains setzt, behält die allowed_domains des Koordinators und blockiert diese Hosts darin.
• Ein Roster-Agent, der eigene allowed_domains setzt, kann nur die Hosts erreichen, die sowohl seine Liste als auch die Liste des Koordinators abdecken.

Ein {"type": "self"}-Roster-Eintrag hat keine eigenen Web-Einstellungen und folgt den aktuellen Einstellungen des Koordinators.

Wenn die kombinierten allowed_domains-Listen keine gemeinsame Domain haben, bleibt das Tool für diesen Agenten verfügbar, aber jeder Aufruf schlägt fehl. Jeder Aufruf gibt einen url_not_allowed-Fehler zurück, der besagt, dass keine Domain erlaubt ist. Die Tool-Beschreibung teilt dem Modell dasselbe mit. Um dies zu vermeiden, halte die allowed_domains jedes Roster-Agenten innerhalb derer des Koordinators.

Der Grader in ergebnisorientierten Sessions läuft unabhängig von diesen Einstellungen ohne web_search und web_fetch.

Listen während einer Session ändern

Du kannst die Listen einer inaktiven Session ändern, indem du ihre Tools aktualisierst. Die neuen Listen gelten für den Rest der Session.

In einer Multiagenten-Session wendet jeder Thread die neuen Listen ab seinem nächsten Turn an. Das Update ändert nicht die eigenen Listen eines Roster-Agenten. Diese bleiben so, wie die Definition des Agenten sie beim Erstellen der Session festgelegt hat.

Unterschiede zu den Tools der Messages API

Diese Einstellungen verwenden dieselben Felder allowed_domains und blocked_domains wie die Domainfilterung bei den Server-Tools der Messages API. Managed Agents unterscheidet sich in vier Punkten:

• Jede Liste ist auf 64 Domains begrenzt.
• Für web_fetch gelistete Domains dürfen keinen Pfad enthalten.
• Domains müssen ASCII sein. Die Messages API akzeptiert Unicode-Einträge, rät jedoch davon ab.
• max_uses, citations und cache_control sind im Toolset nicht verfügbar.

Nächste Schritte