Tools

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

Claude Managed Agents unterstützt außerdem „custom tools" (benutzerdefinierte Tools), also von dir selbst definierte Tools. Deine Anwendung führt diese Tools separat aus und gibt die Ergebnisse an Claude zurück, das sie verwendet, um die Aufgabe fortzusetzen. Um dem Agenten Tools von einem MCP-Server bereitzustellen, verwende stattdessen den MCP-Connector.

Verfügbare Tools

Das „toolset" (Tool-Set) des Agenten enthält die folgenden Tools. Alle sind standardmäßig aktiviert, wenn du das Toolset in deine Agentenkonfiguration aufnimmst. Jeder Eintrag im Array configs wird über seinen name identifiziert, wobei die Werte aus der Spalte „Name" verwendet werden. Jeder Eintrag akzeptiert außerdem ein optionales Feld type mit demselben Wert. Die Einträge web_search und web_fetch akzeptieren zusätzliche Einstellungen; siehe Domains für Web-Suche 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" (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, wenn du einen Agenten erstellst. Verwende das Array configs, um bestimmte Tools zu deaktivieren oder ihre Einstellungen zu überschreiben. Jeder Konfigurationseintrag kann außerdem eine permission_policy festlegen, die steuert, ob die Aufrufe des Tools ohne Bestätigung ausgeführt werden, eine Bestätigung erfordern oder vom Server einzeln bewertet werden. Die verfügbaren Richtlinientypen findest du unter Berechtigungsrichtlinien.

Konfigurationseinträge für web_search und web_fetch akzeptieren außerdem Domainfilter und weitere Web-Einstellungen; siehe Domains für Websuche und Web-Fetch einschränken.

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
---

Bestimmte Tools deaktivieren

Um ein Tool zu deaktivieren, setze enabled: false in seinem Konfigurationseintrag. Dieser Eintrag steht im Toolset-Objekt im Array tools deines Agenten:

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

Nur bestimmte Tools aktivieren

Das Objekt default_config legt die Grundeinstellung für jedes Tool im Set fest, und die configs-Einträge der einzelnen Tools überschreiben sie. Wenn du mit allen Tools deaktiviert beginnen und nur die benötigten aktivieren möchtest, 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 hat seine eigene Liste, sodass web_search und web_fetch unterschiedliche Einschränkungen haben können. Eine aufgeführte Domain umfasst diesen Host und alle seine Subdomains. 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 Event agent.tool_result, mit einem Inhalt, der den Fehlercode url_not_allowed nennt), und web_search lässt Ergebnisse weg, die seine Listen nicht zulassen.

Das folgende Toolset beschränkt web_search auf zwei Websites und lokalisiert dessen 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 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
---

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.

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

Regeln für Domainlisten

• Setze in einem Eintrag entweder allowed_domains oder blocked_domains, nicht beides. Ein Eintrag, der beide setzt, wird abgelehnt.

• Jede Liste enthält 1 bis 64 Domains mit jeweils 1 bis 255 Zeichen. Eine leere Liste wird abgelehnt. Wenn du keine Einschränkung anwenden möchtest, lass das Feld weg oder sende null.

• Jede Domain ist ein registrierbarer Domainname oder eine Subdomain davon, geschrieben als einfacher Hostname. Dabei gilt:

  • Erlaubt sind ASCII-Buchstaben, Ziffern, Bindestriche, Unterstriche und Punkte.
  • Nicht erlaubt sind Schema, Port, Anmeldedaten, Platzhalter und Leerzeichen.
  • Kein Label darf mit einem Bindestrich beginnen oder enden.
  • Ein Pfad ist nur als optionales web_search-Pfadsuffix erlaubt, das weiter unten in dieser Liste beschrieben wird.

  Verwende example.com, nicht https://example.com, example.com:443 oder *.example.com. Bei Hostnamen wird die Groß-/Kleinschreibung nicht beachtet, und ein einzelner abschließender / wird ignoriert.

• Eine aufgeführte Domain umfasst den jeweiligen Host und seine Subdomains. example.com umfasst also docs.example.com, aber docs.example.com umfasst weder example.com noch api.example.com. Ein vorangestelltes www. ist eine Subdomain wie jede andere, daher umfasst www.example.com nicht example.com. Führe die reine Domain auf, um beide abzudecken.

• IP-Adressen werden in keiner Form akzeptiert, weder als IPv4 oder IPv6 noch in eckigen Klammern oder als numerische Kurzform wie 127.1. Führe stattdessen den Domainnamen der Website auf.

• Eine reine 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. Führe eine vollständige Domain wie example.co.uk auf.

• localhost sowie Hosts, die auf .localhost, .local, .internal, .localdomain oder .invalid enden, werden abgelehnt.

• Verwende für internationalisierte Domainnamen die xn---Form (Punycode). Eine Domain mit Nicht-ASCII-Zeichen wird abgelehnt.

• Eine web_fetch-Domain darf keinen Pfad enthalten: Verwende example.com, nicht example.com/*.

• Eine web_search-Domain kann ein Pfadsuffix wie example.com/blog enthalten. Der Pfad darf keine Leerzeichen, kein ?, kein # und keines der Zeichen $ , | ^ ! enthalten. Verwende auch für web_search bevorzugt 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 gelten als unterschiedliche Domains. Was jede davon umfasst, beschreibt die Abgleichsregel weiter oben.

Wann Einstellungen validiert werden

Verstöße gegen Format und Grenzwerte werden mit einem 400-Fehler invalid_request_error abgelehnt. Das geschieht, wenn du einen Agenten erstellst oder einen Agenten aktualisierst, und wenn du eine Session erstellst oder aktualisierst, die tools angibt. Beispiele für Fehlermeldungen:

• Ein Eintrag, der beide Listen setzt: Die Meldung enthält Only one of allowed_domains or blocked_domains may be set.
• Eine leere Liste: Die Meldung enthält allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null.
• Eine Domain, die gegen eine Formatregel verstößt: Die Meldung nennt die Liste und die nullbasierte Position, zum Beispiel allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com".

Dieselben Anfragen lehnen 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.

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, sendet die Session ein session.error-Ereignis und kehrt ohne erneuten Versuch zu idle zurück. So behebst du das Problem:

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, um fortzufahren.

Multiagenten-Sessions, Outcomes und Aktualisierungen während einer Session

In einer Multiagenten-Session werden alle Domainlisten, die für einen Thread gelten, gleichzeitig durchgesetzt. Ein Agent im Roster des Koordinators ist an folgende Listen gebunden:

• seine eigenen allowed_domains und blocked_domains,
• die Listen jedes Agenten, der ihn aufgerufen hat,
• die aktuellen Listen des Koordinators.

Dabei gelten diese Regeln:

• „Allowlists" (Zulassungslisten) werden zu den Domains kombiniert, die alle gemeinsam abdecken. „Blocklists" (Sperrlisten) werden addiert. Ein Roster-Agent kann also einschränken, was ein Tool erreicht, es aber nie erweitern. Zwei Beispiele:
  • Ein Roster-Agent, der blocked_domains setzt, behält die allowed_domains des Koordinators und blockiert die aufgeführten Hosts innerhalb davon.
  • Ein Roster-Agent, der eigene allowed_domains setzt, kann nur die Hosts erreichen, die sowohl seine Liste als auch die Liste des Koordinators abdecken.
• Haben die kombinierten Allowlists keine gemeinsame Domain, 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 zulässig ist. Die Tool-Beschreibung teilt dies auch dem Modell mit. Um das zu vermeiden, halte die Allowlist jedes Roster-Agenten innerhalb der Allowlist des Koordinators.
• max_content_tokens und user_location werden nicht kombiniert. Ein Thread verwendet den Wert aus seiner eigenen Tool-Konfiguration, falls gesetzt. Andernfalls verwendet er den Wert des Agenten, der ihn aufgerufen hat, und sonst den Wert aus der aktuellen Konfiguration des Koordinators.
• Ein Roster-Eintrag {"type": "self"} hat keine eigenen Web-Einstellungen und folgt den aktuellen Einstellungen des Koordinators.
• Der Grader in ergebnisorientierten Sessions läuft unabhängig von diesen Einstellungen ohne web_search und web_fetch.
• 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 sie ab seinem nächsten Zug an. Die eigenen Listen eines Roster-Agenten bleiben jedoch so, wie seine Agentendefinition sie beim Erstellen der Session festgelegt hat.

Unterschiede zu den Tools der Messages API

Diese Einstellungen verwenden dieselben Begriffe allowed_domains und blocked_domains wie das Domainfiltern bei den Server-Tools der Messages API. Bei Managed Agents gibt es jedoch folgende Unterschiede:

• Jede Liste ist auf 64 Domains begrenzt.
• Für web_fetch aufgeführte Domains dürfen keinen Pfad enthalten.
• Domains müssen ASCII sein: Verwende für internationalisierte Domainnamen die xn---Form (Punycode). Die Messages API akzeptiert Unicode-Einträge, rät aber davon ab.
• 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 entsprechen den benutzerdefinierten Client-Tools in der Messages API.

Jedes benutzerdefinierte Tool definiert einen Vertrag: Du legst fest, 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. Unter Session-Event-Stream erfährst du, 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 Umgebungs-Worker benutzerdefinierte Tools aus deiner Sandbox bereitstellen, einschließlich Tools, die einen MCP-Server innerhalb deines Netzwerks kapseln.

ant apply agent.md

---
name: Weather Agent
model: claude-opus-5-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 die Definition benutzerdefinierter Tools

• Schreibe äußerst detaillierte Beschreibungen. Das ist mit Abstand der wichtigste Faktor für die Leistung eines Tools. Deine Beschreibungen sollten Folgendes erklären:

  • was das Tool tut und wann es verwendet werden soll (und wann nicht),
  • was jeder Parameter bedeutet und wie er das Verhalten des Tools beeinflusst,
  • wichtige Vorbehalte oder Einschränkungen.

  Je mehr Kontext du Claude zu deinen Tools gibst, desto besser kann Claude entscheiden, wann und wie es sie verwendet. Strebe drei bis vier Sätze pro Tool-Beschreibung an, bei komplexen Tools auch mehr.

• Fasse zusammengehörige Operationen in weniger Tools zusammen. Statt für jede Aktion ein eigenes Tool zu erstellen (create_pr, review_pr, merge_pr), gruppiere sie in einem einzigen Tool mit einem Parameter action. Weniger, dafür leistungsfähigere Tools verringern Mehrdeutigkeiten bei der Auswahl und machen es Claude leichter, sich in deinen Tools zurechtzufinden.

• Verwende aussagekräftige Namensräume in Tool-Namen. Wenn sich deine Tools über mehrere Dienste oder Ressourcen erstrecken, stelle den Namen die Ressource voran (zum Beispiel db_query oder storage_read). So bleibt die Tool-Auswahl eindeutig, auch 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. Nimm nur die Felder auf, die Claude für den nächsten Schritt braucht. Aufgeblähte Antworten verschwenden Kontext und erschweren es Claude, das Wesentliche herauszufiltern.

Nächste Schritte