Tools

Claude Managed Agents stellt eine Reihe integrierter Tools bereit, die Claude autonom innerhalb einer Session nutzen kann. Du steuerst, welche Tools verfügbar sind, indem du sie in der Agentenkonfiguration angibst.

Claude Managed Agents unterstützt auch benutzerdefinierte Tools. Deine Anwendung führt diese Tools separat aus und gibt die Ergebnisse an Claude zurück, der sie verwendet, um die Aufgabe fortzusetzen. Um dem Agenten Tools von einem MCP-Server bereitzustellen, verwende stattdessen den MCP-Connector.



Verfügbare Tools

Das Agenten-Toolset umfasst die folgenden Tools. Alle sind standardmäßig aktiviert, wenn du das Toolset in deine Agentenkonfiguration aufnimmst. Jeder Eintrag im configs-Array wird durch seinen name identifiziert, wobei die Werte aus der Spalte „Name" verwendet werden, und akzeptiert ein optionales type-Feld mit demselben Wert. Die Einträge web_search und web_fetch akzeptieren zusätzliche Einstellungen; siehe Domains für Websuche und Web-Fetch einschränken.

Wenn eine Tool-Ausgabe 100.000 Zeichen (etwa 25.000 Token) überschreitet, wird sie automatisch in eine Datei in der Sandbox geschrieben. Das Modell erhält eine gekürzte Vorschau mit dem Dateipfad und kann den vollständigen Inhalt von dort lesen.



Das Toolset konfigurieren

Aktiviere das vollständige Toolset mit agent_toolset_20260401 beim Erstellen eines Agenten. Verwende das configs-Array, um bestimmte Tools zu deaktivieren oder ihre Einstellungen zu überschreiben. Jeder Config-Eintrag kann auch eine permission_policy festlegen, die steuert, ob die Aufrufe des Tools automatisch genehmigt werden oder eine Bestätigung erfordern. Siehe Berechtigungsrichtlinien für die verfügbaren Richtlinientypen.

Config-Einträge für web_search und web_fetch akzeptieren auch Domain-Filter und andere Web-Einstellungen; siehe Domains für Websuche und Web-Fetch einschränken.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML



Bestimmte Tools deaktivieren

Um ein Tool zu deaktivieren, setze enabled: false in seinem Config-Eintrag im Toolset-Objekt des tools-Arrays deines Agenten:

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}



Nur bestimmte Tools aktivieren

Das default_config-Objekt legt die Basis für jedes Tool im Set fest, und die einzelnen configs-Einträge überschreiben sie. Um mit allem deaktiviert zu starten und nur das zu aktivieren, was du brauchst, setze default_config.enabled auf false:

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}



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

Um zu steuern, welche Websites die Web-Tools des Agenten erreichen können, setze allowed_domains (das Tool kann nur diese Hosts erreichen) oder blocked_domains (das Tool kann diese Hosts niemals erreichen) in den Einträgen web_search und web_fetch des configs-Arrays des Toolsets. Jedes Tool führt seine eigene Liste, sodass web_search und web_fetch unterschiedliche Einschränkungen haben können. Eine aufgelistete Domain deckt diesen Host und alle seine Subdomains ab. Zur Laufzeit gibt ein web_fetch-Aufruf für eine URL, die seine Listen nicht zulassen, ein Fehlerergebnis an den Agenten zurück (is_error: true im agent.tool_result-Event, mit Inhalt, der den Fehlercode url_not_allowed nennt), und web_search lässt Ergebnisse aus, die seine Listen nicht zulassen.

Das folgende Toolset beschränkt web_search auf zwei Websites und lokalisiert seine Ergebnisse, blockiert einen Host für web_fetch und begrenzt gleichzeitig, wie viel abgerufener Inhalt in den Kontext gelangt:

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

Die folgende Anfrage erstellt einen Agenten mit diesem Toolset und gibt das configs-Array aus der Antwort aus:

ant beta:agents create --transform tools.0.configs <<'YAML'
name: Research Agent
model: claude-opus-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
YAML

In der Claude Console legst du erlaubte oder blockierte Domains in den Zeilen web_search und web_fetch der Karte Built-in tools im Agentenformular fest; max_content_tokens und user_location setzt du in der Raw-Ansicht der Agentenkonfiguration.

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



Regeln für Domain-Listen

• Setze entweder allowed_domains oder blocked_domains in einem Eintrag, nicht beide. Ein Eintrag, der beide setzt, wird abgelehnt.
• Jede Liste enthält 1 bis 64 Domains, jede mit 1 bis 255 Zeichen. Eine leere Liste wird abgelehnt: Um keine Einschränkung anzuwenden, lass das Feld weg oder sende null.
• Jede Domain ist ein registrierbarer Domainname oder eine Subdomain davon, geschrieben als einfacher Hostname: ASCII-Buchstaben, Ziffern, Bindestriche, Unterstriche und Punkte, ohne Schema, Port, Anmeldedaten, Wildcard oder Leerzeichen, ohne Label, das mit einem Bindestrich beginnt oder endet, und ohne Pfad außer dem optionalen web_search-Pfadsuffix, das weiter unten in dieser Liste beschrieben wird. Verwende example.com, nicht https://example.com, example.com:443 oder *.example.com. Hostnamen werden ohne Berücksichtigung der Groß-/Kleinschreibung verglichen, und ein einzelnes abschließendes / wird ignoriert.
• Eine aufgelistete Domain passt auf diesen Host und seine Subdomains: 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, sodass www.example.com nicht example.com abdeckt; liste die nackte Domain auf, um beide abzudecken.
• IP-Adressen werden in keiner Form akzeptiert, weder IPv4, IPv6, in Klammern noch als numerische Kurzform wie 127.1. Liste stattdessen den Domainnamen der Website auf.
• Eine nackte Top-Level-Domain oder ein Registry-Suffix wie com, co.uk oder gov.uk wird abgelehnt, ebenso ein Name mit nur einem Label wie intranet. Liste eine vollständige Domain wie example.co.uk auf.
• localhost und Hosts, die auf .localhost, .local, .internal, .localdomain oder .invalid enden, werden abgelehnt.
• Verwende die xn---Form (Punycode) für internationalisierte Domainnamen; eine Domain, die Nicht-ASCII-Zeichen enthält, wird abgelehnt.
• Eine web_fetch-Domain kann keinen Pfad enthalten: Verwende example.com, nicht example.com/*. Eine web_search-Domain kann ein Pfadsuffix wie example.com/blog tragen, wobei der Pfad keine Leerzeichen, ?, # oder eines der Zeichen $ , | ^ ! enthalten darf. Bevorzuge auch für web_search einfache Hostnamen, da der Suchanbieter Pfadsuffixe als URL-Muster und nicht als strikte Host-Regeln abgleicht.
• Doppelte Domains innerhalb einer Liste werden abgelehnt. www.example.com und example.com zählen als unterschiedliche Domains; siehe die vorherige Matching-Regel dafür, was jede abdeckt.



Wann Einstellungen validiert werden

Format- und Limit-Verstöße werden mit einem 400 invalid_request_error abgelehnt, wenn du einen Agenten erstellst oder einen Agenten aktualisierst, und wenn du eine Session erstellst oder aktualisierst, die tools bereitstellt. Zum Beispiel enthält die Meldung für einen Eintrag, der beide Listen setzt, Only one of allowed_domains or blocked_domains may be set., und die Meldung für eine leere Liste enthält allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null. Die Meldung für eine Domain, die gegen eine Formatregel verstößt, nennt ihre Liste und nullbasierte Position, zum Beispiel allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com".

Dieselben Anfragen lehnen auch drei Einstellungen ab, die von den Such- und Fetch-Anbietern 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), und eine user_location.timezone, die kein gültiger IANA-Name ist. Die Session prüft die Konfiguration erneut, wenn sie das Tool zum ersten Mal initialisiert; wenn eine Einstellung, die zuvor akzeptiert wurde, zu diesem Zeitpunkt nicht mehr gültig ist, gibt die Session ein session.error-Event aus und kehrt ohne Wiederholungsversuch zu idle zurück. Behebe die Einstellung, indem du die Tools der Session aktualisierst, aktualisiere auch den Agenten, damit neue Sessions mit der korrigierten Konfiguration starten, und sende dann eine neue user.message, um fortzufahren.



Multiagent-Sessions, Outcomes und Updates während der Session

In einer Multiagent-Session wird jede Domain-Liste, die für einen Thread gilt, gleichzeitig durchgesetzt: Ein Agent im Roster des Koordinators ist an seine eigenen allowed_domains und blocked_domains gebunden, an die jedes Agenten, der ihn aufgerufen hat, und an die aktuellen Listen des Koordinators.

• Allowlists werden zu den Domains kombiniert, die alle von ihnen abdecken, und Blocklists werden addiert, sodass ein Roster-Agent einschränken kann, was ein Tool erreicht, aber niemals erweitern. Zum Beispiel behält ein Roster-Agent, der blocked_domains setzt, die allowed_domains des Koordinators bei und blockiert diese Hosts darin, und ein Roster-Agent, der seine eigenen allowed_domains setzt, kann nur die Hosts erreichen, die sowohl seine Liste als auch die Liste des Koordinators abdecken.
• Wenn die kombinierten Allowlists keine gemeinsame Domain haben, bleibt das Tool für diesen Agenten verfügbar, aber jeder Aufruf schlägt mit einem url_not_allowed-Fehler fehl, der besagt, dass keine Domain erlaubt ist, und die Tool-Beschreibung teilt dies dem Modell mit. Halte die Allowlist jedes Roster-Agenten innerhalb der des Koordinators, um dies zu vermeiden.
• max_content_tokens und user_location werden nicht kombiniert: Ein Thread verwendet den Wert aus seiner eigenen Tool-Konfiguration, falls gesetzt, andernfalls vom Agenten, der ihn aufgerufen hat, andernfalls aus der aktuellen Konfiguration des Koordinators.
• Ein {"type": "self"}-Roster-Eintrag hat keine eigenen Web-Einstellungen und folgt den aktuellen Einstellungen des Koordinators.
• Der Grader in ergebnisgesteuerten Sessions läuft ohne web_search und web_fetch, unabhängig von diesen Einstellungen.
• Du kannst die Listen einer Session im Zustand idle ändern, indem du ihre Tools aktualisierst. Die neuen Listen gelten für den Rest der Session; in einer Multiagent-Session wendet jeder Thread sie ab seinem nächsten Turn an, während die eigenen Listen eines Roster-Agenten so bleiben, wie seine Agentendefinition sie beim Erstellen der Session festgelegt hat.



Unterschiede zu den Messages-API-Tools

Diese Einstellungen verwenden dasselbe allowed_domains- und blocked_domains-Vokabular wie die Domain-Filterung bei den Server-Tools der Messages API, mit den folgenden Unterschieden bei Managed Agents:

• Jede Liste ist auf 64 Domains begrenzt.
• Für web_fetch aufgelistete Domains können keinen Pfad enthalten.
• max_uses, citations und cache_control sind im Toolset nicht verfügbar.



Benutzerdefinierte Tools

Zusätzlich zu den integrierten Tools kannst du benutzerdefinierte Tools definieren. Benutzerdefinierte Tools sind analog zu benutzerdefinierten Client-Tools in der Messages API.

Jedes benutzerdefinierte Tool definiert einen Vertrag: Du gibst an, welche Operationen verfügbar sind und was sie zurückgeben, und Claude bestimmt, wann und wie sie aufgerufen werden. Das Modell führt niemals selbst etwas aus. Es gibt eine strukturierte Anfrage aus, dein Code führt die Operation aus, und das Ergebnis fließt zurück in die Konversation. Siehe Session-Event-Stream, um zu erfahren, wie du während einer Session Aufrufe benutzerdefinierter Tools empfängst und Ergebnisse zurückgibst.

Wenn deine Sessions in einer selbst gehosteten Sandbox laufen, kann der Environment-Worker benutzerdefinierte Tools aus deiner Sandbox bereitstellen, einschließlich Tools, die einen MCP-Server innerhalb deines Netzwerks kapseln.

ant beta:agents create < agent.yaml

name: Weather Agent
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
  - type: custom
    name: get_weather
    description: Get current weather for a location
    input_schema:
      type: object
      properties:
        location:
          type: string
          description: City name
      required:
        - location

Sobald du benutzerdefinierte Tools für den Agenten definiert hast, ruft der Agent sie während einer Session auf.



Best Practices für Definitionen benutzerdefinierter Tools

• Liefere extrem detaillierte Beschreibungen. Dies ist bei weitem der wichtigste Faktor für die Tool-Performance. Deine Beschreibungen sollten erklären, was das Tool tut und wann es verwendet werden sollte (und wann nicht). Erkläre, was jeder Parameter bedeutet und wie er das Verhalten des Tools beeinflusst. Weise auf wichtige Vorbehalte oder Einschränkungen hin. Je mehr Kontext du Claude über deine Tools geben kannst, desto besser kann es bestimmen, wann und wie sie zu verwenden sind. Strebe drei bis vier Sätze für jede Tool-Beschreibung an, mehr, wenn das Tool komplex ist.
• Fasse verwandte Operationen in weniger Tools zusammen. Anstatt für jede Aktion ein separates Tool zu erstellen (create_pr, review_pr, merge_pr), gruppiere sie in einem einzigen Tool mit einem action-Parameter. Weniger, aber leistungsfähigere Tools reduzieren Mehrdeutigkeit bei der Auswahl und machen deine Tool-Oberfläche für Claude leichter navigierbar.
• Verwende aussagekräftiges Namespacing in Tool-Namen. Wenn deine Tools mehrere Dienste oder Ressourcen umfassen, stelle den Namen die Ressource voran (zum Beispiel db_query oder storage_read). Dies macht die Tool-Auswahl eindeutig, wenn deine Bibliothek wächst.
• Gestalte Tool-Antworten so, dass sie nur aussagekräftige Informationen zurückgeben. Gib semantische, stabile Bezeichner zurück (zum Beispiel Slugs oder UUIDs) statt undurchsichtiger interner Referenzen, und schließe nur die Felder ein, die Claude benötigt, um seinen nächsten Schritt zu bestimmen. Aufgeblähte Antworten verschwenden Kontext und erschweren es Claude, das Wesentliche zu extrahieren.



Nächste Schritte