Feingranulares Tool-Calling

Wenn du Tool-Nutzung mit Streaming in Claude kombinierst, erhältst du Echtzeit-Updates, während die KI Tool-Argumente generiert. Das schafft eine reaktionsschnellere Nutzererfahrung, aber es gibt einige wichtige Details zu verstehen, wie das im Hintergrund funktioniert.

Grundlegendes Tool-Streaming

Mit aktiviertem Streaming sendet Claude verschiedene Arten von Events zurück, während es deine Anfrage verarbeitet. Du bist bereits mit Events wie ContentBlockDelta für die reguläre Textgenerierung vertraut. Für die Tool-Nutzung musst du zusätzlich einen neuen Event-Typ namens InputJsonEvent behandeln.

Jedes InputJsonEvent enthält zwei Schlüsseleigenschaften:

partial_json - Ein Chunk von JSON, der einen Teil der Tool-Argumente darstellt
snapshot - Das kumulative JSON, das aus allen bisher empfangenen Chunks aufgebaut wurde

So behandelst du diese Events in deiner Streaming-Pipeline:

python

for chunk in stream:
    if chunk.type == "input_json":
        # Verarbeite den partiellen JSON-Chunk
        print(chunk.partial_json)
        # Oder verwende den bisherigen vollständigen Snapshot
        current_args = chunk.snapshot

Wie die JSON-Validierung funktioniert

Hier wird es interessant. Die Anthropic API sendet dir nicht sofort jeden Chunk, sobald Claude ihn generiert. Stattdessen puffert sie Chunks und validiert sie zuerst.

Die API wartet auf vollständige Schlüssel-Wert-Paare auf oberster Ebene, bevor sie etwas sendet. Wenn dein Tool beispielsweise diese Struktur erwartet:

json

{
  "abstract": "This paper presents a novel...",
  "meta": {
    "word_count": 847,
    "review": "This paper introduces QuanNet..."
  }
}

Die API wird:

Warten, bis der gesamte abstract-Wert vollständig ist
Dieses Schlüssel-Wert-Paar gegen dein Schema validieren
Alle gepufferten Chunks für abstract auf einmal senden
Den Prozess für das meta-Objekt wiederholen

Dieser Validierungsprozess erklärt, warum du Verzögerungen gefolgt von Textschüben siehst, selbst bei aktiviertem Streaming. Die Chunks werden zurückgehalten, bis ein vollständiges, gültiges Schlüssel-Wert-Paar auf oberster Ebene bereit ist.

Wenn du schnelleres, granulareres Streaming benötigst - vielleicht um Nutzern sofortige Updates zu zeigen oder um schnell mit der Verarbeitung von Teilergebnissen zu beginnen - kannst du feingranulares Tool-Calling aktivieren.

Feingranulares Tool-Calling macht im Wesentlichen eine Sache: Es deaktiviert die JSON-Validierung auf der API-Seite. Das bedeutet:

Du erhältst Chunks, sobald Claude sie generiert
Keine Pufferungsverzögerungen zwischen Schlüsseln auf oberster Ebene
Traditionelleres Streaming-Verhalten
Wichtig: Die JSON-Validierung ist deaktiviert - dein Code muss ungültiges JSON behandeln

Aktiviere es, indem du fine_grained=True zu deinem API-Aufruf hinzufügst:

python

run_conversation(
    messages, 
    tools=[save_article_schema], 
    fine_grained=True
)

Mit feingranularem Tool-Calling erhältst du möglicherweise einen word_count-Wert viel früher im Stream, ohne darauf zu warten, dass das gesamte meta-Objekt vollständig ist.

Umgang mit ungültigem JSON

Bei der Verwendung von feingranularem Tool-Calling kann Claude ungültiges JSON generieren, wie "word_count": undefined anstelle einer korrekten Zahl. Deine Anwendung muss diese Fälle elegant behandeln:

python

try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    # Ungültiges JSON angemessen behandeln
    print("Received invalid JSON, continuing...")

Ohne feingranulares Tool-Calling würde die Validierung der API diesen Fehler abfangen und problematische Werte möglicherweise in Strings einschließen, was nicht deinem erwarteten Schema entsprechen könnte.

Wann feingranulares Tool-Calling verwendet werden sollte

Erwäge die Aktivierung von feingranularem Tool-Calling, wenn:

Du Nutzern Echtzeit-Fortschritt bei der Generierung von Tool-Argumenten zeigen musst
Du so schnell wie möglich mit der Verarbeitung von Teil-Tool-Ergebnissen beginnen möchtest
Die Pufferungsverzögerungen deine Nutzererfahrung negativ beeinflussen
Du dich mit der Implementierung einer robusten JSON-Fehlerbehandlung wohlfühlst

Für die meisten Anwendungen ist das Standardverhalten mit Validierung völlig ausreichend. Aber wenn du diese zusätzliche Reaktionsschnelligkeit benötigst, gibt dir feingranulares Tool-Calling die Kontrolle, um Chunks so schnell zu erhalten, wie Claude sie generieren kann.

Grundlegendes Tool-Streaming

Wie die JSON-Validierung funktioniert