---
title: "AG01 — Die Agentenschleife, von Hand"
sidebar:
  label: "AG01 — Die Agentenschleife, von Hand"
---

<span id="ag01-die-agentenschleife-von-hand" />


[← Lernleitfaden](/de/learning-guide) · [AG02 — Native Tool-Use →](/de/agent-native) · [Glossar](/de/glossary)

Voraussetzungen: [Einrichtung](/de/setup), [Einheit 0](/de/unit-00) mit
gespeichertem Bericht (der erste Befehl unten erzeugt ihn in Sekunden neu, falls
du ihn nicht aufgehoben hast) und ein lokales Modell. Das Standard-Preset `qwen`
lädt beim ersten Start `Qwen/Qwen3-4B-Instruct-2507`, rund 8 GB in bfloat16. Das
kleinere Preset `qwen-small` (`Qwen/Qwen3-1.7B`, rund 3,4 GB) hält das Protokoll
auch auf Rechnern mit 16 GB ein, erfindet aber — wie unten gemessen — die
Kursquelle, statt danach zu suchen. Diese Einheit setzt es genau einmal
absichtlich ein, in „Brechen“. `ANTHROPIC_API_KEY` schaltet das optionale Preset
`anthropic` frei; nichts Verpflichtendes hängt davon ab. Plane eine Sitzung von
60–90 Minuten.

## Was „Agent“ hier bedeutet [#was-agent-hier-bedeutet]

Ein Agent ist ein Modell, ein paar Tools und eine Schleife, die *du* geschrieben
hast. Sonst nichts. Die Schleife fragt das Modell, was zu tun ist, führt das
gewünschte Tool aus, gibt das Ergebnis zurück und fragt erneut — bis das Modell
antwortet, statt zu fragen.

Warum überhaupt eine Schleife? Ein einzelner Modellaufruf kann nicht gleichzeitig
etwas nachschlagen und das Gefundene verwenden. Deinen Bericht lesen und prüfen,
was der Kurs dazu sagt, sind zwei Schritte mit einer Abhängigkeit: Der zweite
braucht die Ausgabe des ersten.

In dieser Einheit bekommt das Modell keine besondere Tool-Calling-API. Es bekommt
eine Regel im System-Prompt: Antworte **entweder** mit genau einer Zeile

```
CALL <tool_name>({"parameter": value})
```

**oder** mit einer endgültigen Antwort. Diese Zeile parst du selbst. Wenn ein Tool
gelaufen ist, geht seine Ausgabe als gewöhnliche Nachricht zurück ans Modell:

```
RESULT <tool_name>:
<output>
```

Der System-Prompt zeigt dem Modell außerdem eine konkrete Beispielzeile `CALL`
und sagt ihm unmissverständlich: Es kann deine Dateien und den Kurstext nicht
sehen und darf nie eine Zahl nennen oder einen Abschnitt zitieren, den es nicht
aus einem `RESULT` gelesen hat. Du wirst zusehen, wie ein Modell diese Regel
trotzdem bricht.

Das Modell erfährt nie, dass ein Tool gelaufen ist. Es sieht immer nur Text.
Behalte das im Kopf — es erklärt das meiste, was du beobachten wirst.

Die zwei Tools:

- `read_report(path)` — liest einen *deiner eigenen* JSON-Berichte unter `artifacts/`;
- `search_course(query, k)` — findet die Kursabschnitte, die die meisten Wörter
  deiner Anfrage enthalten. Es lässt diese Seite absichtlich aus: Sonst fände der
  Agent die Antwort in der Seite, die die Frage stellt — [E02](/de/data-quality)
  nennt das Kontamination.

Die Referenzfrage braucht beide, in dieser Reihenfolge — erst die Zahlen aus
deinem Bericht, dann die Abschnittsüberschrift, die nur die Suche liefern kann:

> My Unit 0 report is at unit0/report.json. After the boost, did the corpus loss
> go up or down, and by how much? Then find the Unit 0 section that says whether
> that is expected and give its exact heading.

(Die Frage bleibt englisch, weil das Modell den englischen Kurstext durchsucht.)

## Vorhersagen [#vorhersagen]

Unten steht das Transkript, das ein gut funktionierendes Modell auf diese Frage
erzeugt. Lies es, **bevor** du etwas ausführst, und notiere drei Dinge: wie viele
Schritte es braucht, welches Tool zuerst aufgerufen wird und was die Antwort am
Ende zitiert.

```
CALL read_report({"path": "unit0/report.json"})
CALL search_course({"query": "boost one logit corpus loss worse transition"})
It went up, from 1.695 to 1.890 (+0.194): baseline.corpus_loss to
controlled_change.corpus_loss in your report. The section is "30–42 min ·
Build one controlled change" in unit-00: the boost changes exactly one cell
in the [V,V] matrix, so it can help one transition while harming the overall
corpus loss. The rise is the expected effect, not a mistake.
```

Sage noch etwas voraus: Wenn im Bericht der Loss **gesunken** wäre — würde das
skriptgesteuerte Transkript das bemerken?

## Verfolgen [#verfolgen]

Starte den Referenzlauf aus Einheit 0 noch einmal; er speichert seinen
vollständigen Bericht unter `artifacts/unit0/report.json`, wo das Tool ihn findet.
Spiele danach das Transkript ab:

```
python examples/run_unit0.py
python examples/run_agent.py --preset scripted
```

Das Preset `scripted` startet kein Modell. Es spielt genau die drei Antworten von
oben ab, sodass die Form eines Laufs sichtbar wird, ohne etwas herunterzuladen.
Öffne `artifacts/agent/run.json` und finde:

- `history` — sieben Nachrichten: `system`, deine Frage, das erste `CALL`, die
  Nachricht `RESULT read_report:`, das zweite `CALL`, dessen `RESULT`, die
  Antwort. Zähle die Rollen. Nirgends gibt es eine Rolle „tool“;
- `steps[0].call` — der geparste Tool-Aufruf: ein Name und ein JSON-Objekt;
- `steps[0].result` — der Anfang deines Berichts, genau so, wie das Modell ihn sah;
- `steps[1].result` — die Abschnitte, die `search_course` geliefert hat. Der erste
  sollte `unit-00 · 30–42 min · Build one controlled change` sein;
- `stopped` — `answer`.

Prüfe deine erste Vorhersage. Dann die Zusatzfrage: Das Transkript zitiert `1.695`
und `1.890`, egal was in deinem Bericht steht — es ist ein Skript. Nur ein echtes
Modell liest das `RESULT`.

## Bauen [#bauen]

Jetzt echt. Das 4B-Qwen braucht auf Apple Silicon ein paar Sekunden pro Schritt,
auf der CPU deutlich länger:

```
python examples/run_agent.py --preset qwen
```

Lies die ausgegebene Antwort, dann den Bericht. Vergleiche `steps[0].result` mit
den Zahlen in der Antwort: Hat das Modell *deine* Loss-Werte zitiert? Vergleiche
`steps[1].result` mit der Überschrift, die die Antwort zitiert.

<details>
<summary>Das Modell hat geantwortet, ohne search_course aufzurufen</summary>

Mit dem Standard-Preset ist das selten — die Messung unten zeigt, dass es in
5 von 5 Läufen gesucht hat —, aber es kommt vor. Frag noch einmal, oder stelle
eine Frage, die sich aus dem Bericht allein nicht beantworten lässt: *"Which
unit explains why boosting one logit changes the corpus loss?"* Die Schleife
führt nur aus, was ihr gesagt wird; ein Modell, das ein Tool auslässt, ist
kein Fehler in deiner Schleife.


</details>

**Eigenständige Übung.** Schreibe ein drittes Tool. In
`artifacts/my-work/agent_tools.py`:

```python
from pathlib import Path

from llm_course.agent import Tool


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

Registriere es neben den zwei Standard-Tools und stelle eine Frage, die es
braucht — *"Which reports do I have, and what did Unit 0 measure?"* — direkt mit
`run_agent`. Speichere das als `artifacts/my-work/run_list_reports.py` neben
`agent_tools.py` und starte `python artifacts/my-work/run_list_reports.py` aus
dem Repository-Wurzelverzeichnis; die `sys.path`-Zeile sorgt dafür, dass der
Import der Nachbardatei funktioniert, egal von wo du startest:

```python
from pathlib import Path
import sys

sys.path.insert(0, str(Path(__file__).parent))

from llm_course.agent import run_agent, write_report
from llm_course.agent.presets import default_tools, make_model

from agent_tools import list_reports

tools = (*default_tools(Path("content"), Path("artifacts")), list_reports(Path("artifacts")))
run = run_agent("Which reports do I have, and what did Unit 0 measure?",
                tools=tools, model=make_model("qwen"))
write_report(run, Path("artifacts/agent/list-reports.json"))
print(run.answer)
```

Bewahre den Bericht auf. Das Gate fragt danach.

## Brechen [#brechen]

Fünf absichtliche Fehler. Bewahre jeden Bericht als Nachweis auf.

**Ein Tool, das lügt.** Kopiere deinen Bericht und ändere
`controlled_change.corpus_loss` auf `1.2`:

```
python - <<'PY'
import json, pathlib
p = pathlib.Path("artifacts/unit0/report.json")
d = json.loads(p.read_text()); d["controlled_change"]["corpus_loss"] = 1.2
pathlib.Path("artifacts/unit0/lying.json").write_text(json.dumps(d, indent=2))
PY
python examples/run_agent.py --preset qwen \
    --question "My Unit 0 report is at unit0/lying.json. After the boost, did the corpus loss go up or down?" \
    --report artifacts/agent/lying.json
```

Das Modell glaubt dem Tool. Es kann gar nicht anders: Das `RESULT` ist nur Text,
und nichts in der Schleife prüft ihn. Notiere, was die Antwort behauptet hat.

**Das Budget.** `python examples/run_agent.py --preset qwen --max-steps 1 --report artifacts/agent/budget.json`. Lies
`stopped`: `budget`, und `answer`: `null`. Die Schleife ist nicht gescheitert — sie
hat aufgehört, und genau dafür ist ein Budget da.

**Eine Frage, die die Tools nicht beantworten können.** Frage *"What is the
capital of France?"* mit `--report artifacts/agent/offtopic.json`. Lies die
Schritte. Hat das Modell einen Tool-Namen erfunden? Falls ja, finde die Nachricht
`RESULT … ERROR: unknown tool` und die Antwort danach. Diese Nachricht ist die
einzige Verteidigung der Schleife gegen Erfindungen — und sie ist eine
*Reparaturchance*, keine Ablehnung.

**Abschneiden.** Starte die Referenzfrage erneut, diesmal mit gekürzter
Tool-Ausgabe:

```
python examples/run_agent.py --preset qwen --max-output-chars 500 --report artifacts/agent/truncated.json
```

Der Bericht wird vor `controlled_change` abgeschnitten. Lies, was die Antwort mit
einem halben Bericht macht.

**Ein Modell, das sich eine Quelle ausdenkt.** Starte die Referenzfrage auf dem
kleineren Modell:

```
python examples/run_agent.py --preset qwen-small --report artifacts/agent/bluff.json
```

Lies die Abschnittsüberschrift, die die Antwort nennt. Dann prüfe sie selbst:

```
python - <<'PY'
from pathlib import Path
from llm_course.agent import search_course
print(search_course(Path("content")).run({"query": "Corpus Loss Analysis", "k": 3}))
PY
```

Lies die drei Überschriften, die zurückkommen: Keine davon lautet „Corpus Loss
Analysis“. Die Überschrift existiert nicht; die Wörter darin schon — genau
deshalb liefert eine Suche nach einem erfundenen Titel trotzdem *etwas*, und
genau deshalb ist die Überschrift der Test, nicht die Trefferzahl. In der
Referenzmessung hat das 1.7B
jede Regel des Protokolls befolgt, den Bericht richtig gelesen, die richtigen
Zahlen zitiert und die Quelle erfunden: `"Unit 0: Corpus Loss Analysis"`, in
allen fünf Läufen. Die Regel im System-Prompt hat es nicht aufgehalten; nichts in
der Schleife *kann* es aufhalten, denn die Schleife sieht nur Text. Deshalb ist
das Standard-Preset das größere Modell, und deshalb gibt es überhaupt eine
Guardrails-Einheit (G01, folgt später). (Gemessen am 2026-09-21; dein Lauf kann
abweichen — auch diese Abweichung ist es wert, notiert zu werden.)

## Messen [#messen]

Starte die Referenzfrage fünfmal und lies die Tabelle:

```
python examples/run_agent.py --preset qwen --repeat 5 --report artifacts/agent/measure/run.json
```

`protocol_ok` ist `yes`, wenn jeder Schritt beim ersten Versuch geparst wurde.
Referenzmessung, Apple Silicon (MPS), 2026-09-21:

| Preset | protocol_ok (von 5) | stopped=answer (von 5) | read_report aufgerufen (von 5) | search_course aufgerufen (von 5) | Median Schritte | Median Latenz (s, gesamt) | Kosten gesamt (USD) |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `qwen-small` | 5 | 5 | 5 | 0 | 1 | 4.6 | 0.0000 |
| `qwen` | 5 | 5 | 5 | 5 | 2 | 13.5 | 0.0000 |

Das 1.7B hat in 5 von 5 Läufen das Protokoll eingehalten und den Bericht gelesen,
aber in 0 von 5 `search_course` aufgerufen und stattdessen eine Überschrift
erfunden. Deshalb ist das 4B der Standard.

Ist `ANTHROPIC_API_KEY` gesetzt, starte dieselben fünf Läufe mit
`--preset anthropic` und ergänze die Zeile. Deine Zahlen weichen von der Referenz
ab; die Tabelle ist dazu da, dass du sagen kannst, *um wie viel*.

## Erklären [#erklaren]

Vervollständige in deinen Notizen:

1. Die Schleife hält an, weil …
2. Nachdem ein Tool gelaufen ist, sieht das Modell …
3. Der falsche Loss-Wert hat die Antwort erreicht, weil …
4. Ein kleines Modell kann diesem Protokoll folgen, weil …
5. `max_steps` schützt vor …, aber nicht vor …

## Abschluss-Gate [#abschluss-gate]

Du bestehst AG01 mit: dem Referenzlauf (`run.json`), dessen Trace beide Tools
verwendet; den fünf Berichten aus „Brechen“ mit je einem Satz dazu, was passiert
ist; der Tabelle der fünf Läufe; deinem Tool `list_reports` und dem Bericht einer
Frage, die es beantwortet hat. Eine Erklärung in eigenen Worten zählt; die Worte
dieser Seite zählen nicht.

## Wie geht es weiter? [#wie-geht-es-weiter]

[AG02](/de/agent-native) setzt denselben Agenten auf eine native Tool-Use-API und
fragt, was die API dir abgenommen hat. [AG03](/de/agent-injection) misst, was jede
Abwehr gegen Prompt Injection tatsächlich bringt, mit demselben Agenten und R02s
RAG-Pipeline. AG04 verbindet ihn mit dem MCP-Server des Kurses und lässt dich dann
einen eigenen bauen *(in Kürze)*. Der [Track „Angewandt: RAG“](/de/rag-build) zeigt,
was aus `search_course` mit echtem Retrieval dahinter wird.

[← Lernleitfaden](/de/learning-guide) · [AG02 — Native Tool-Use →](/de/agent-native) · [Glossar](/de/glossary)
