Was sind programmatische Tool-Aufrufe?
Programmatische Tool-Aufrufe ermöglichen es einem KI-Agenten, Code zu schreiben, der Tools in einer Sandbox-Umgebung aufruft — anstatt für jeden Tool-Aufruf einen separaten Modell-Roundtrip zu benötigen. Der Agent schreibt ein Skript, die Laufzeitumgebung führt es aus, und Tool-Aufrufe erfolgen direkt aus dem Code. Nur das Endergebnis wird in das Kontextfenster des Modells zurückgegeben.
Warum es wichtig ist
Traditionelle Tool-Nutzung erfordert, dass das Modell einen Tool-Aufruf generiert, auf das Ergebnis wartet und dann den nächsten Schritt entscheidet — ein Roundtrip nach dem anderen. Programmatische Tool-Aufrufe eliminieren diesen Overhead für mehrstufige Workflows.
Weniger Roundtrips
Mehrere Tools in einer einzigen Code-Ausführung aufrufen statt ein Modell-Turn pro Tool.
Geringerer Token-Verbrauch
Zwischenergebnisse bleiben in der Sandbox — nur die Zusammenfassung gelangt ins Kontextfenster.
Datenfilterung
Große Tool-Ausgaben im Code verarbeiten und filtern, bevor sie das Modell erreichen.
Nativer Kontrollfluss
Schleifen, Bedingungen und Fehlerbehandlung nutzen — das Modell schreibt echten Code, nicht nur JSON-Aufrufe.
Wie es funktioniert
Der Ablauf umfasst vier Schritte zwischen Agent, Sandbox und deinem Tool-Server.
Agent schreibt Code
Das Modell generiert ein Python-Skript, das deine Tools als asynchrone Funktionen aufruft.
Sandbox führt aus
Der Code läuft in einem Sandbox-Container. Wenn eine Tool-Funktion aufgerufen wird, pausiert die Ausführung.
Tool wird extern ausgeführt
Dein Server empfängt den Tool-Aufruf, führt ihn aus und gibt das Ergebnis an die Sandbox zurück.
Ergebnis ans Modell
Sobald das Skript fertig ist, wird nur die finale Ausgabe dem Kontext des Modells hinzugefügt.
Traditionell vs. Programmatisch
So unterscheiden sich die beiden Ansätze bei einer Aufgabe, die drei Datenbankregionen abfragt.
Traditionelle Tool-Nutzung
Jeder Tool-Aufruf erfordert einen vollen Modell-Roundtrip. Für N Tools sind das N Inferenz-Durchläufe.
Modell → Tool-Aufruf → Ergebnis → Modell → Tool-Aufruf → Ergebnis → Modell → Tool-Aufruf → Ergebnis → Modell → Antwort
7 Modell-Turns
Programmatische Tool-Aufrufe
Agent schreibt ein Skript, das N Tools aufruft. Nur 1 Inferenz-Durchlauf nötig.
Modell → Code (3 Tool-Aufrufe + Aggregation) → Antwort
2 Modell-Turns
Beispiel: Programmatische Datenbankabfrage
Der Agent schreibt Python, das über Regionen iteriert, ein Datenbank-Tool aufruft und Ergebnisse aggregiert — alles in einer Ausführung.
regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
data = await query_database(
f"SELECT SUM(revenue) as total FROM sales WHERE region='{region}'"
)
results[region] = data[0]["total"]
# Aggregate in code — only the summary reaches the model
top_region = max(results, key=results.get)
print(f"Top region: {top_region} ({results[top_region]:,.0f})")
print(f"All regions total: {sum(results.values()):,.0f}")Anwendungsfälle
Programmatische Tool-Aufrufe glänzen, wenn Agenten mehr als einzelne Tool-Aufrufe benötigen.
Batch-Verarbeitung
Eine Datenbank für 50 Regionen in einer Schleife abfragen, Ergebnisse aggregieren und eine Zusammenfassung zurückgeben — alles in einer Ausführung.
Bedingte Logik
Zürst die Dateigröße prüfen, dann entscheiden, ob die ganze Datei oder nur eine Zusammenfassung gelesen wird. Keine verschwendeten Roundtrips.
Datenfilterung
10.000 Log-Einträge abrufen, nur Fehler filtern und die letzten 10 zurückgeben — das Kontextfenster bleibt sauber.
Frühzeitiger Abbruch
Endpunkte der Reihe nach prüfen und stoppen, sobald ein funktionierender gefunden wird. Nicht alle müssen geprüft werden.
Das allowed_callers-Konzept
Bei der Tool-Definition gibst du an, welche Kontexte das Tool aufrufen können. So steürst du, ob ein Tool nur direkt vom Modell, nur aus der Code-Ausführung oder beides aufgerufen werden kann.
Für Klarheit ist es am besten, pro Tool einen Modus zu wählen, anstatt beide zu aktivieren. Das gibt dem Modell klarere Hinweise zur Nutzung jedes Tools.
Nur Direkt
Das Modell ruft das Tool direkt über den Standard-Tool-Use-Flow auf. Das ist die Standardeinstellung.
"allowed_callers": ["direct"]
Nur Code-Ausführung
Das Tool kann nur aus einer Sandbox-Code-Ausführungsumgebung heraus aufgerufen werden.
"allowed_callers": ["code_execution"]
Beide Modi
Das Tool kann entweder direkt oder aus Code aufgerufen werden. Sparsam verwenden — kann die Tool-Auswahl verwirren.
"allowed_callers": ["direct", "code_execution"]
Wichtige Erkenntnisse
- 1Programmatische Tool-Aufrufe lassen Agenten Code schreiben, der Tools aufruft — ohne Roundtrips pro Tool.
- 2Zwischenergebnisse bleiben in der Sandbox und gelangen nie ins Kontextfenster des Modells — spart Tokens.
- 3Mit allowed_callers steürst du, ob Tools direkt, aus Code oder beides aufgerufen werden.
- 4Ideal für Batch-Verarbeitung, bedingte Workflows, Datenfilterung und mehrstufige Tool-Ketten.
- 5Mehrere KI-Anbieter implementieren dieses Muster, um Agenten schneller und effizienter zu machen.