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 Agent-Toolset umfasst die folgenden Tools. Alle sind standardmäßig aktiviert, wenn du das Toolset in die Agentenkonfiguration aufnimmst.

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, wenn du einen Agenten erstellst. Verwende das Array configs, um bestimmte Tools zu deaktivieren oder ihre Einstellungen zu überschreiben. Jeder Eintrag wird durch seinen name identifiziert, der einen Wert aus der Spalte „Name“ in Verfügbare Tools annimmt. Ein Eintrag akzeptiert außerdem ein optionales Feld type mit demselben Wert.

Jeder Konfigurationseintrag kann außerdem eine permission_policy festlegen. Die Richtlinie steuert, ob die Aufrufe des Tools ohne Bestätigung ausgeführt werden, eine Bestätigung erfordern oder vom Server einzeln bewertet werden. Unter Berechtigungsrichtlinien findest du die verfügbaren Richtlinientypen.

Das folgende Beispiel aktiviert das Toolset und deaktiviert web_fetch:

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 configs-Eintrag:

{
  "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 toolspezifische configs-Einträge überschreiben sie. Um mit allen Tools deaktiviert zu beginnen und nur die benötigten zu aktivieren, 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 }
  ]
}

Websuche und Web-Fetch einschränken

Die Einträge web_search und web_fetch akzeptieren außerdem Domainlisten, eine Obergrenze für abgerufene Inhalte und einen Suchstandort. Siehe Domains für Websuche und Web-Fetch einschränken.

Typen von Konfigurationseinträgen in den SDKs

Die SDKs für Python, TypeScript, Go, Java, C#, Ruby und PHP typisieren jeden configs-Eintrag pro Tool. Der Typ ist eine Union mit einem Member pro integriertem Tool, unterschieden durch type.

In Go, Java, C# und PHP erstellst du Einträge aus typisierten Werten statt aus einfachen Dictionaries oder Hashes. In diesen SDKs ist der Elementtyp von configs die Union selbst, also erstelle jeden Eintrag aus seinem toolspezifischen Member-Typ.

Du kannst type weglassen, wenn du einen Eintrag erstellst, da der Server ihn aus name ableitet. Antworten enthalten ihn immer. Diese Typisierung ändert nicht das JSON, zu dem ein Eintrag serialisiert wird. Eine Anfrage, deren Einträge nur name, enabled und permission_policy setzen, ist mit oder ohne type gültig.

Benutzerdefinierte Tools

Benutzerdefinierte Tools entsprechen den benutzerdefinierten Client-Tools in der Messages API. Du legst fest, welche Operationen verfügbar sind und was sie zurückgeben, und Claude bestimmt, wann und wie sie aufgerufen werden.

Claude führt ein benutzerdefiniertes Tool nicht selbst aus. Es gibt eine strukturierte Anfrage aus, dein Code führt die Operation aus, und du gibst das Ergebnis an die Session zurück.

Das folgende Beispiel erstellt einen Agenten mit dem integrierten Toolset und einem benutzerdefinierten Tool, get_weather:

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
---

Der Name eines benutzerdefinierten Tools darf nicht mit mcp__ oder ant__ beginnen oder mit dem Namen eines integrierten Agenten-Tools übereinstimmen. Eine Anfrage, die gegen diese Regel verstößt, gibt einen 400-Fehler zurück. Ein Agent, der bereits ein benutzerdefiniertes Tool hat, dessen Name mit ant__ beginnt, akzeptiert ein Update nur, wenn das Update tools ohne diesen Namen sendet. Benenne das Tool also in deinem nächsten Update um oder entferne es. Eine neue Session wird mit einem 400-Fehler abgelehnt, wenn sich ein solches Tool auf ihrem Agenten befindet (nach allen Überschreibungen), auf einem Agenten in der predefined_agents-Liste von subagents oder auf einem Agenten in der predefined_agents-Liste von workflows. Bereits bestehende Sessions sind nicht betroffen.

Der Agent ruft seine benutzerdefinierten Tools während einer Session auf. Wie du die Aufrufe empfängst und Ergebnisse zurückgibst, erfährst du unter Session-Event-Stream.

Für Sessions, die in einer selbst gehosteten Sandbox laufen, kann der Environment-Worker benutzerdefinierte Tools aus der Sandbox bereitstellen. Dazu können Tools gehören, die einen MCP-Server innerhalb deines Netzwerks kapseln.

Best Practices für Definitionen benutzerdefinierter Tools

• Stelle äußerst detaillierte Beschreibungen bereit. Dies ist mit Abstand der wichtigste Faktor für die Tool-Leistung. Je mehr Kontext du Claude über deine Tools gibst, desto besser kann es bestimmen, wann und wie sie verwendet werden. Strebe drei bis vier Sätze pro Tool-Beschreibung an, mehr, wenn das Tool komplex ist. Deine Beschreibungen sollten Folgendes abdecken:
  • Was das Tool tut
  • Wann es verwendet werden soll und wann nicht
  • Was jeder Parameter bedeutet und wie er das Verhalten des Tools beeinflusst
  • Alle wichtigen Einschränkungen oder Vorbehalte
• Fasse zusammengehörige Operationen in weniger Tools zusammen. Gruppiere Aktionen wie create_pr, review_pr und merge_pr in einem einzigen Tool mit einem action-Parameter. Weniger, dafür leistungsfähigere Tools verringern Mehrdeutigkeiten bei der Auswahl und machen deine Tool-Oberfläche für Claude leichter navigierbar.
• Verwende aussagekräftige Namespaces 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, während 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. Füge 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 herauszufiltern.

Nächste Schritte