SpyBara
Go Premium

agent-sdk/tool-search.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 28 additions and 42 deletions.

2026
Sat 3 23:57 Wed 14 22:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59

Mit Tool-Suche zu vielen Tools skalieren

Skalieren Sie Ihren Agenten auf Tausende von Tools, indem Sie nur das Nötigste entdecken und bei Bedarf laden.

Die Tool-Suche ermöglicht es Ihrem Agenten, mit Hunderten oder Tausenden von Tools zu arbeiten, indem er sie dynamisch entdeckt und bei Bedarf lädt. Anstatt alle Tool-Definitionen vorab in das Kontextfenster zu laden, durchsucht der Agent Ihren Tool-Katalog und lädt nur die Tools, die er benötigt.

Dieser Ansatz löst zwei Herausforderungen, wenn Tool-Bibliotheken skalieren:

  • Kontexteffizienz: Tool-Definitionen können große Teile des Kontextfensters verbrauchen (50 Tools können 10–20 K Token verwenden), was weniger Platz für tatsächliche Arbeit lässt.
  • Genauigkeit der Tool-Auswahl: Die Genauigkeit der Tool-Auswahl verschlechtert sich, wenn mehr als 30–50 Tools gleichzeitig geladen sind.

Wie die Tool-Suche funktioniert

Die Tool-Suche ist standardmäßig aktiviert, mit Ausnahmen, die unter Tool-Suche konfigurieren aufgelistet sind.

Wenn sie aktiv ist, werden Tool-Definitionen aus dem Kontextfenster zurückgehalten. Der Agent erhält eine Zusammenfassung der verfügbaren Tools und sucht nach relevanten, wenn die Aufgabe eine Fähigkeit erfordert, die nicht bereits geladen ist. Bis zu fünf der relevantesten Tools werden standardmäßig in den Kontext geladen, wo sie für nachfolgende Durchläufe verfügbar bleiben, bis das SDK die Nachrichten komprimiert, in denen der Agent sie entdeckt hat. Nach dieser Komprimierung sucht der Agent diese Tools erneut, wenn er sie benötigt.

Die Tool-Suche fügt jedes Mal, wenn Claude nach Tools sucht, einen zusätzlichen Roundtrip hinzu, aber bei großen Tool-Sets wird dies durch einen kleineren Kontext bei jedem Durchlauf ausgeglichen. Mit weniger als etwa 10 Tools, deren Definitionen bequem in das Kontextfenster passen, ist das Laden von allem vorab normalerweise schneller.

Weitere Informationen zum zugrunde liegenden API-Mechanismus finden Sie unter Tool-Suche in der API.

[!NOTE]

Die Tool-Suche wird auf Microsoft Foundry-Bereitstellungen, die auf Azure gehostet werden, nicht unterstützt, da diese sie serverseitig ablehnen: Das SDK erkennt die Ablehnung und lädt stattdessen Tool-Definitionen vorab für diese Bereitstellung. ENABLE_TOOL_SEARCH kann dies nicht überschreiben, da die Ablehnung von der Bereitstellung selbst kommt.

Tool-Suche konfigurieren

Die Tool-Suche ist standardmäßig aktiviert. Bei Modellen auf der Liste der nicht unterstützten Modelle des SDK lädt das SDK Tool-Definitionen stattdessen vorab, und kein ENABLE_TOOL_SEARCH-Wert überschreibt das. Auf Google Cloud's Agent Platform entscheidet das SDK nach Modellgeneration:

  • Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 und später: Tool-Suche ist standardmäßig aktiviert.
  • Frühere Agent Platform-Modelle: Das SDK lädt Tool-Definitionen vorab, da ihre Serving-Stacks den erforderlichen Beta-Header ablehnen. ENABLE_TOOL_SEARCH kann dies nicht überschreiben.

Vor Claude Code v2.1.221 deaktivierte das SDK die Tool-Suche für alle Modelle auf Google Cloud's Agent Platform, es sei denn, Sie haben ENABLE_TOOL_SEARCH gesetzt.

Das SDK deaktiviert auch die Tool-Suche, wenn ANTHROPIC_BASE_URL auf einen Host eines Drittanbieters verweist, da die meisten Proxys tool_reference-Blöcke nicht weiterleiten. Sie können diesen Standard mit der Umgebungsvariablen ENABLE_TOOL_SEARCH überschreiben:

Wert Verhalten
(nicht gesetzt) Die Tool-Suche ist aktiviert. Tool-Definitionen werden aufgeschoben und bei Bedarf entdeckt. Fällt auf das Laden vorab zurück bei Modellen, die älter als Opus 4 und Sonnet 4 sind, bei Google Cloud's Agent Platform-Modellen, die älter als Opus 4.5, Sonnet 4.5 und Haiku 4.5 sind, bei einer ANTHROPIC_BASE_URL eines Drittanbieters oder bei einer auf Azure gehosteten Microsoft Foundry-Bereitstellung.
true Die Tool-Suche bleibt bei einer ANTHROPIC_BASE_URL eines Drittanbieters aktiviert. Die übrigen Fallbacks von (nicht gesetzt) gelten weiterhin. Das SDK sendet den Beta-Header durch Proxys, und Anfragen schlagen auf Proxys fehl, die tool_reference-Blöcke nicht unterstützen.
auto Zählt die Token in den Tool-Definitionen, die die Tool-Suche aufschieben kann, und vergleicht die Summe mit dem Kontextfenster des Modells. Wenn die Summe 10 % des Fensters erreicht, wird die Tool-Suche aktiviert. Darunter lädt das SDK jede Tool-Definition vorab in den Kontext.
auto:N Wie auto mit einem benutzerdefinierten Prozentsatz. auto:5 wird aktiviert, wenn diese Definitionen 5 % des Kontextfensters erreichen. Niedrigere Werte werden früher aktiviert.
false Die Tool-Suche ist deaktiviert. Alle Tool-Definitionen werden bei jedem Durchlauf in den Kontext geladen.

Das Setzen von CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS hält die Tool-Suche aus. Sie können es nicht durch das Setzen von ENABLE_TOOL_SEARCH selbst überschreiben. Ab Claude Code v2.1.227 kann Ihre Organisation die Tool-Suche unter dieser Variablen über verwaltete Einstellungen aktiviert halten. In einer Sitzung, die die HIPAA-Konfiguration erhält, ist die Tool-Suche deaktiviert, und weder ENABLE_TOOL_SEARCH noch verwaltete Einstellungen schalten sie wieder ein. Deaktivieren Sie Pre-Release-Funktionen behandelt, wo die Überschreibung gilt und was die Variable entfernt.

Die Tool-Suche gilt für alle registrierten Tools, unabhängig davon, ob sie von Remote-MCP-Servern oder benutzerdefinierten SDK-MCP-Servern stammen. Wenn Sie auto verwenden, zählt das SDK jede Definition, die die Tool-Suche aufschieben kann, gegen einen kombinierten Schwellenwert: jedes MCP-Tool, das nicht als alwaysLoad markiert ist, von jedem Server, plus die integrierten Tools, die bei Bedarf geladen werden. Das SDK lädt Core-Built-in-Tools wie Bash, Read und Edit vorab und zählt sie nicht zum Schwellenwert. Ein Mod in einem Ihrer Plugins kann ein Tool außerdem aufschieben oder vorab laden, wodurch sich diese Zählung ändert.

Legen Sie den Wert in der env-Option auf query() fest. In TypeScript ersetzt env die Subprocess-Umgebung, daher sollten Sie ...process.env verteilen, um vererbte Variablen beizubehalten. In Python wird env auf die vererbte Umgebung zusammengeführt. Dieses Beispiel verbindet sich mit einem Remote-MCP-Server, der viele Tools bereitstellt, genehmigt alle vorab mit einem Platzhalter und verwendet auto:5, sodass die Tool-Suche aktiviert wird, wenn die Definitionen, die sie aufschieben kann, 5 % des Kontextfensters erreichen:

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({
    prompt: "Find and run the appropriate database query",
    options: {
      mcpServers: {
        "enterprise-tools": {
          // Connect to a remote MCP server
          type: "http",
          url: "https://tools.example.com/mcp"
        }
      },
      allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
      env: {
        ...process.env, // env replaces the subprocess environment, so keep inherited variables
        ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when deferrable definitions reach 5% of context
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result
  console.log(`Session ended with an error: ${error}`);
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "enterprise-tools": {
                "type": "http",
                "url": "https://tools.example.com/mcp",
            }
        },
        allowed_tools=[
            "mcp__enterprise-tools__*"
        ],  # Wildcard pre-approves all tools from this server
        env={
            "ENABLE_TOOL_SEARCH": "auto:5"  # Activate tool search when deferrable definitions reach 5% of context
        },
    )

    try:
        async for message in query(
            prompt="Find and run the appropriate database query",
            options=options,
        ):
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(message.result)
    except Exception as error:
        # A single-shot query() raises after yielding an error result
        print(f"Session ended with an error: {error}")


asyncio.run(main())

Um dieses Beispiel auszuführen, ersetzen Sie https://tools.example.com/mcp durch die URL Ihres eigenen MCP-Servers. Bei Erfolg wird der Ergebnistext auf der Konsole ausgegeben.

Da dies ein einmaliger query()-Aufruf ist, löst das SDK nach dem Ausgeben eines Fehlerergebnisses eine Ausnahme aus, daher umhüllt das Beispiel die Schleife in einen Try-Block. Um zu sehen, warum eine Ausführung fehlgeschlagen ist, überprüfen Sie den subtype der Ergebnismeldung, z. B. error_during_execution, innerhalb der Schleife. Weitere Informationen zu Ergebnismeldungen finden Sie unter Behandeln Sie das Ergebnis.

Tool-Entdeckung optimieren

Der Suchmechanismus gleicht Abfragen mit Tool-Namen und Beschreibungen ab. Namen wie search_slack_messages erscheinen für eine breitere Palette von Anfragen als query_slack. Beschreibungen mit spezifischen Schlüsselwörtern („Slack-Nachrichten nach Schlüsselwort, Kanal oder Datumsbereich durchsuchen“) entsprechen mehr Abfragen als generische („Slack abfragen“).

Sie können auch einen Systemaufforderungsabschnitt hinzufügen, der verfügbare Tool-Kategorien auflistet. Dies gibt dem Agenten Kontext darüber, welche Arten von Tools verfügbar sind, um danach zu suchen. Übergeben Sie den Text über die Option systemPrompt in TypeScript oder system_prompt in Python, wobei Sie die Voreinstellung claude_code mit append verwenden, die Ihren Text zur Voreinstellung hinzufügt, anstatt sie zu ersetzen:

options: {
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "You can search for tools to interact with Slack, GitHub, and Jira."
  }
}

options = ClaudeAgentOptions(
    system_prompt={
        "type": "preset",
        "preset": "claude_code",
        "append": "You can search for tools to interact with Slack, GitHub, and Jira.",
    }
)

Den vollständigen Satz von Systemaufforderungsoptionen finden Sie unter Systemaufforderungen ändern.

Limits

  • Maximale Tools: 10.000 Tools in Ihrem Katalog
  • Suchergebnisse: Gibt bis zu fünf relevanteste Tools pro Suche standardmäßig zurück
  • Modellunterstützung: Opus 4, Sonnet 4, Haiku 4.5 und spätere Modelle bzw. Opus 4.5, Sonnet 4.5, Haiku 4.5 und spätere Modelle auf Google Clouds Agent Platform. Bei früheren Modellen lädt das SDK Tool-Definitionen vorab, wie unter Tool-Suche konfigurieren beschrieben.

Zugehörige Dokumentation