Zum Inhalt springen
LLM Engineering Course
Deutsch
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

AG02 — Native Tool-Use

← AG01 — Die Agentenschleife, von Hand · AG03 — Prompt-Injection → · Glossar

Voraussetzungen: AG01 mit seinem Bericht unter artifacts/unit0/report.json und ANTHROPIC_API_KEY in deiner Shell — der verpflichtende Weg dieser Einheit ist gehostet, auf claude-sonnet-5. Die Referenzläufe unten kosten auf diesem Modell je etwa 2–3 Cent; ein vollständiger Durchgang dieser Seite inklusive „Messen“ kostet rund einen Dollar. Der CPU-Weg ist der lokale Qwen-Weg mit dem 4B, das du für AG01 heruntergeladen hast. Plane eine Sitzung von 60–90 Minuten.

Was sich ändert und was nicht

In AG01 hast du dem Modell die Regeln in Prosa erklärt, eine CALL-Zeile selbst geparst und Ergebnisse als Text zurückgeschickt. Eine native Tool-Use-API ersetzt genau drei dieser Dinge: das Schema (ein JSON Schema pro Tool statt eines Satzes), das Parsen (die API liefert einen strukturierten tool_use-Block) und die Call-ID (jedes Ergebnis wird dem Aufruf zugeordnet, den es beantwortet). Alles andere bleibt deine Sache:

noch deine Sache warum die API es nicht übernehmen kann
das Schrittbudget die API weiß nicht, wann ein Lauf aufgeben sollte
das Kürzen der Ausgabe sie weiß nicht, wie groß ein Ergebnis sein darf
die Pfadbegrenzung sie weiß nicht, welche Dateien dem Lernenden gehören
einem Ergebnis glauben sie kann ein wahres Tool-Ergebnis nicht von einem lügenden unterscheiden

Die erste Zeile ist nicht hypothetisch. In der Referenzmessung unten endeten zwei der fünf Läufe mit dem Textprotokoll auf Claude nur, weil das Budget aufgebraucht war: fünf search_course-Aufrufe hintereinander mit umformulierten Anfragen und keine Antwort. Die API auf dem nativen Weg hätte das ebenso wenig bemerkt.

Du lässt denselben Agenten auf dieselbe Frage auf drei Wegen laufen:

Weg Schleife Modell
text / Claude AG01s Schleife, gehostet claude-sonnet-5
native / Claude die neue Schleife claude-sonnet-5
native / Qwen die neue Schleife, lokal Qwen/Qwen3-4B-Instruct-2507

Die zwei Schleifen sind src/llm_course/agent/loop.py und native.py. Vergleiche sie mit diff: Dieser Unterschied ist diese Einheit.

Vorhersagen

Lies noch einmal das Transkript aus AG01, dann dieses — das native Transkript für dieselbe Frage. Das Modell fordert beide Tools in einer Runde an:

assistant: [tool_use read_report {"path": "unit0/report.json"}]
           [tool_use search_course {"query": "boost one logit corpus loss worse transition"}]
user:      [tool_result …report…] [tool_result …section…]
assistant: It went up, from 1.695 to 1.890 (+0.194) …

Notiere drei Vorhersagen: Welcher Weg erzeugt zuerst einen fehlerhaften Aufruf? Wie viele Nachrichten enthält jede Konversation, wenn der Lauf endet? Und welche Konversation könntest du unverändert an ein anderes Modell weitergeben?

Verfolgen

python examples/run_agent.py --protocol native --preset scripted

Öffne artifacts/agent/run.json. Im Vergleich mit dem Bericht aus AG01:

  • messages — vier Einträge, nicht sieben. Finde die Assistentennachricht, deren content zwei tool_use-Blöcke mit je einer id enthält; dann die Nutzernachricht, deren zwei tool_result-Blöcke diese IDs zurücktragen. Die API besteht darauf, dass alle Ergebnisse einer Runde in einer Nachricht ankommen; die Schleife lässt das Backend sie bauen.
  • steps — zwei Schritte mit demselben index: eine Runde, zwei Aufrufe. AG01s Protokoll konnte das nicht ausdrücken.
  • Nirgends gibt es eine CALL-Zeile oder ein RESULT-Präfix. Du hast nichts geparst.

Bauen

Starte die drei Wege. Jeder schreibt seinen eigenen Bericht:

python examples/run_agent.py --protocol text   --preset anthropic --model sonnet --report artifacts/agent/text-claude.json
python examples/run_agent.py --protocol native --preset anthropic --model sonnet --report artifacts/agent/native-claude.json
python examples/run_agent.py --protocol native --preset qwen --report artifacts/agent/native-qwen.json

Lies die drei Antworten nebeneinander, dann die drei messages-Listen. Finde auf dem Qwen-Weg die Assistentennachricht: Sie ist reiner Text mit <tool_call>-Tags — Qwens Template-Format — und das Ergebnis ging als tool-Nachricht zurück. Stell dir den gerenderten Prompt vor: Qwens Template macht aus einer tool-Nachricht eine Nutzerrunde, eingehüllt in <tool_response>. AG01s „Ergebnisse gehen als Nutzernachricht zurück“ war keine Abkürzung; genau das macht das native Format darunter.

Eigenständige Übung. Schreibe list_reports noch einmal, diesmal als Schema. Das Tool, das du für AG01 geschrieben hast, hat bereits typisierte Parameter; das Schema wird daraus abgeleitet:

from pathlib import Path

from llm_course.agent import Tool, input_schema

def list_reports(artifact_root: Path) -> Tool:
    def run(arguments: dict) -> str:
        paths = sorted(p.relative_to(artifact_root) for p in artifact_root.rglob("*.json"))
        return "\n".join(str(p) for p in paths) or "No reports found."

    return Tool("list_reports", "List every JSON report under the artifact directory.", (), run)

print(input_schema(list_reports(Path("artifacts"))))

Registriere es neben den zwei Standard-Tools mit run_native_agent (dieselbe Form wie das Runner-Snippet aus AG01, mit backend=make_backend("anthropic")) und frage “Which reports do I have, and what did Unit 0 measure?”. Bewahre den Bericht auf.

Brechen

Vier absichtliche Fehler. Bewahre jeden Bericht auf.

Eine Konversation, die die API ablehnt. Kopiere artifacts/agent/native-claude.json, lösche einen tool_result-Block aus der Nutzernachricht, die zwei davon enthält, und spiele die Konversation erneut ab (ein API-Aufruf, etwa ein Cent):

python - <<'PY'
import json
from pathlib import Path
from llm_course.agent.presets import make_backend, default_tools
report = json.loads(Path("artifacts/agent/native-claude.json").read_text())
messages = report["messages"][:3]
assert len(messages[2]["content"]) == 2, "no batched turn; pick the user message with two results"
messages[2]["content"] = messages[2]["content"][:1]          # drop the second result
backend = make_backend("anthropic")
try:
    backend.call("You are an assistant with tools.", tuple(messages), default_tools(Path("content"), Path("artifacts")))
except Exception as error:
    print(type(error).__name__, error)
PY

Die API lehnt die Konversation ab: Ein tool_use ohne sein tool_result ist ein Fehler, keine Vermutung. AG01s Schleife hätte dieselbe Lücke stillschweigend akzeptiert.

Ein falscher Typ im Schema. Deklariere in deiner agent_tools.py auf einer Kopie der Parameter von search_course k als "string" und stelle eine Frage, die k braucht. Lies den Aufruf, den das Modell macht, und was search_course für "k": "3" zurückgibt.

Das Budget bleibt deine Sache.

python examples/run_agent.py --protocol native --preset anthropic --model sonnet --max-steps 1 --report artifacts/agent/native-budget.json

stopped ist budget. Die API hat nichts bemerkt. In 2 von 5 gemessenen Läufen mit dem Textprotokoll auf Claude war das Budget das Einzige, was den Lauf beendet hat — fünf umformulierte Suchen hintereinander und keine Antwort.

Qwens eigenes Format. Starte den Qwen-Weg erneut in einen eigenen Bericht, damit der Bericht aus „Bauen“ erhalten bleibt:

python examples/run_agent.py --protocol native --preset qwen --report artifacts/agent/native-qwen-format.json

Lies jeden <tool_call>-Block in den messages dieses Berichts; erscheint in seinen steps ein parse_error, lies den Block, der ihn verursacht hat. Referenzmessung: 0 von 5 — Qwens Template-Format wurde jedes Mal geparst.

Messen

python examples/run_agent.py --protocol text   --preset anthropic --model sonnet --repeat 5 --report artifacts/agent/measure-ag02/text-claude.json
python examples/run_agent.py --protocol native --preset anthropic --model sonnet --repeat 5 --report artifacts/agent/measure-ag02/native-claude.json
python examples/run_agent.py --protocol native --preset qwen --repeat 5 --report artifacts/agent/measure-ag02/native-qwen.json

Referenzmessung, Apple Silicon (MPS) für Qwen und die API für Claude, 2026-09-21 (claude-sonnet-5 mit adaptivem Thinking, Effort low). Die zwei AG01-Zeilen sind zum Vergleich von dieser Seite übernommen. In der Spalte „zwei Aufrufe in einer Runde“ bedeutet –, dass das Protokoll zwei Aufrufe in einer Runde nicht ausdrücken kann, und 0, dass es das könnte und das Modell es nie getan hat:

Weg protocol_ok (von 5) beantwortet (von 5) read_report (von 5) search_course (von 5) exakte Überschrift (von 5) zwei Aufrufe in einer Runde (von 5) Median Schritte Median Latenz (s, gesamt) Median Kosten (USD)
text / Claude sonnet-5 5 3 5 5 1 – 5 8.3 0.0257
native / Claude sonnet-5 5 5 5 5 3 5 4 9.6 0.0240
native / Qwen 4B 5 5 5 5 5 0 2 13.6 0.0000
text / Qwen 4B (AG01, 2026-09-21) 5 5 5 5 5 – 2 13.5 0.0000
text / Qwen 1.7B (AG01, 2026-09-21) 5 5 5 0 0 – 1 4.6 0.0000

Deine erste Vorhersage hat eine schlichte Antwort: Kein Weg hat einen fehlerhaften Aufruf erzeugt. protocol_ok ist auf allen dreien 5 von 5, und Qwens <tool_call>-JSON wurde jedes Mal geparst. Der interessante Fehler lag woanders. Mit dem Textprotokoll hat Claude nur 3 von 5 beantwortet: Die Läufe 1 und 3 liefen ins 6-Schritte-Budget und setzten dabei fünf search_course-Aufrufe hintereinander mit umformulierten Anfragen ab — “expected corpus loss increase after boost”, “corpus loss expected to rise after controlled change”, “why corpus loss got worse is this expected” —, weil kein Abschnitt von Einheit 0 wörtlich „expected“ enthält (grep -i expected content/unit-00.md ist leer), und das Modell nie entschieden hat, dass es genug Belege hat. Mit dem nativen Protokoll hat dasselbe Modell 5 von 5 beantwortet und in 5 von 5 Läufen mit einer Assistentenrunde begonnen, die beide Tools aufruft (messages[1].content ist thinking, tool_use, tool_use). Dasselbe Modell, dieselbe Frage, andere Verdrahtung, anderes Verhalten: Das Protokoll hat verändert, was das Modell tut, nicht nur die Buchführung.

Kosten und Tokens: Das Textprotokoll hat pro Lauf weniger Output-Tokens verbraucht (im Schnitt 236 gegenüber 527 — eine CALL-Zeile sind ein paar Tokens, eine native Runde trägt einen Thinking-Block und strukturierte tool_use-Blöcke), aber mehr Runden, die jede die wachsende Konversation erneut senden, sodass die Mediane nahe beieinander liegen: 0,0257 proLauffu¨rtextund0,0240 pro Lauf für text und 0,0240 für native. Die Fünf-Läufe-Messung beider gehosteter Wege zusammen hat 0,20 $ gekostet. Die Median-Latenz lag bei 8,3 s (text / Claude), 9,6 s (native / Claude) und 13,6 s (native / Qwen auf MPS).

Zwei Dinge in der Tabelle sind Eigenschaften des Modells, nicht des Protokolls. Qwen 4B hat nie zwei Aufrufe in einer Runde gebündelt (0 von 5), obwohl das Protokoll es erlaubt und das skriptgesteuerte Transkript es tut; Claude hat es in jedem Lauf getan. Und die Frage verlangt die exakte Überschrift, die search_course jedes Mal wörtlich geliefert hat — trotzdem hat Claude 30–42 min · Build one controlled change nur in 1 von 5 Text-Läufen und 3 von 5 nativen Läufen exakt zitiert; die übrigen haben sie zu “Build one controlled change” umformuliert und die Zeitangabe weggelassen. Qwen 4B hat sie in 5 von 5 exakt zitiert, auf beiden Protokollen. Sein nativer Weg hat außerdem in allen fünf Läufen identische Token-Zahlen erzeugt (3391 rein, 192 raus): Das lokale Backend ist hier deterministisch.

Erklären

Vervollständige in deinen Notizen:

  1. Die API garantiert jetzt … ; sie kann weiterhin nicht wissen …
  2. Alle Ergebnisse einer Runde reisen in einer Nachricht, weil …
  3. Qwens tool-Rolle unterscheidet sich von einer Nutzernachricht darin, dass … — und nicht darin, dass …
  4. Pro Lauf hat das Textprotokoll … Output-Tokens als das Schema verbraucht, aber etwa gleich viel gekostet, weil …
  5. Wenn ein Tool-Ergebnis auf dem nativen Weg löge, würde die Schleife …

Abschluss-Gate

Du bestehst AG02 mit: den drei Referenzberichten; den vier Berichten aus „Brechen“ mit je einem Satz; der Tabelle der fünf Läufe für alle drei Wege mit Kosten; deinem schemabasierten list_reports und dem Bericht einer Frage, die es beantwortet hat. Deine eigenen Worte zählen; die Worte dieser Seite zählen nicht.

Wie geht es weiter?

AG03 misst, was jede Abwehr gegen Prompt Injection tatsächlich bringt, mit demselben Agenten und R02s RAG-Pipeline. AG04 verbindet den Agenten mit dem MCP-Server des Kurses und lässt dich dann einen eigenen bauen (in Kürze). G01 macht aus der Spalte „noch deine Sache“ eine eigene Schicht.

← AG01 — Die Agentenschleife, von Hand · AG03 — Prompt-Injection → · Glossar

War diese Seite hilfreich?