Best Practices fuer Agent-Systeme im Daily-Use
Destilliert aus drei Jahren LLM-Markt-Erfahrung plus Anthropic-internen Patterns (Stand Mai 2026). Was unter Last traegt, nicht was im Demo aussieht. Diese Sammlung ist die Source fuer die agent-system-audit-rubric und fuer jedes neue Agent-System das im Vault entsteht.
Die zehn Prinzipien
1. Tool-Design schlaegt Prompt-Engineering
Der einzelne groesste Hebel fuer Agent-Qualitaet sind die Tool-Signaturen, nicht der System-Prompt. Tool-Namen wie Verben (create_invoice, nicht invoices), Docstrings die ein neuer Mitarbeiter sofort versteht, Fehler-Messages die dem Modell sagen was als naechstes zu tun ist ("Invoice ID not found. Try list_invoices with date filter first.").
Wenn ein Agent in 30 % der Faelle den falschen Tool aufruft: nicht den Prompt fixen, die Tool-Beschreibung fixen.
Cross-Ref: mcp-best-practices.
2. Single-Agent zuerst, Multi-Agent nur mit Beweis
Multi-Agent ist 2025-2026 over-hyped. 80 % der „Multi-Agent-Systeme” am Markt sind ein Single-Agent mit besser strukturierten Tools. Multi-Agent rechtfertigt sich nur wenn:
- klare Domain-Trennung mit eigenem Vokabular
- Parallelisierbarkeit echt nutzbar
- ein Agent darf den Kontext des anderen nicht sehen (Compliance, Mandantentrennung)
Sonst: ein Agent, viele Tools. Multi-Agent verdoppelt Failure-Modes und drittelt Debugbarkeit.
3. Context-Engineering, nicht Prompt-Engineering
Was im Kontext steht entscheidet mehr als wie es formuliert ist. Drei Regeln:
- Just-in-Time-Loading. Daten reinziehen wenn der Agent sie braucht, nicht prophylaktisch.
- Strukturierte Sektionen.
<task>,<environment>,<conventions>schlagen Markdown-Wuesten. - Kontext-Hygiene. Alte Tool-Outputs nach ihrer Nutzung kuerzen, sonst frisst Tool-Calling-Schrott Token.
Bei Sonnet 4.6 mit 200k Context heisst „viel Platz” nicht „nutze ihn auch”. Lange Prompts werden nicht durchgelesen, nur erste und letzte 500 Token wirklich gewichtet.
4. Der Loop ist das Produkt
Ein guter Agent ist nicht ein guter Prompt, sondern ein guter Loop:
plan → act → observe → reflect → repeat until done
Drei oft uebersehene Stellen:
- Vor jedem Tool-Call soll der Agent sagen warum er ihn macht — verbessert Korrektheit um 10-15 %.
- Nach jedem Tool-Call muss er das Ergebnis interpretieren, nicht blind weitermachen.
- Done-Check — explizite Bedingung, sonst loopt das Ding bis Token aus sind.
System-Prompt: „Stop and return when X. Do not continue past that.”
5. Memory ist eine Ablage, kein Magic
File-basierte Memory schlaegt Vector-DB fuer die meisten Faelle. Vector ist gut fuer „finde mir aehnliche Dokumente in 10k Files”, aber 80 % der Agents brauchen das nicht — sie brauchen „lies das richtige File”.
Konkret fuer AV-Stack: Markdown + Wikilinks + Frontmatter im Vault ist memory-architektonisch ueberlegen zu „kipp alles in pgvector”. Memory-File pro Entitaet, Index-File mit Wikilinks, Agent navigiert. Vector nur dort wo unstrukturierte Suche ueber viele Dokumente noetig ist (Belege, Emails, Transkripte).
6. Eskalations-Punkte explizit definieren
Ein perfekter Agent weiss wann er aufhoert und den Menschen fragt. Drei Trigger fest verdrahten:
- Irreversible Aktionen — Geld bewegen, Rechnung versenden, Daten loeschen.
- Mehrdeutigkeit — wenn zwei plausible Interpretationen existieren.
- Wiederholtes Scheitern — nach 3 Fehlversuchen am gleichen Subtask: stop, ask.
Wichtiger Punkt: Eskalation auf Tool-Schema-Level ist robuster als auf System-Prompt-Level. Prompt kann der LLM ignorieren oder edge-case-missverstehen. Tool-Schema-Constraint (z.B. send_mail erfordert Token aus vorigem preview_send) ist prompt-resistent.
7. Evals von Tag 1 oder gar nicht
Ohne Eval-Suite kannst du nicht iterieren — du raetst. 20 echte Inputs aus deiner Domain mit erwartetem Output, manuell oder LLM-gejudged. Bei jeder Prompt-/Tool-Aenderung: durchlaufen lassen.
Klingt nach Overhead, ist aber der Unterschied zwischen „Agent wird besser” und „Agent driftet”. Eval-Suite ist die staerkste Investition mit dem hoechsten ROI in jedem Agent-Projekt.
Minimaler Stack: Eval-Cases als YAML-Frontmatter-Files im Vault, LLM-Judge mit Rubric, eigener CLI-Runner. Tool-Stack einkaufen lohnt sich erst ab ~20 Kunden.
8. Observability zaehlt, nicht Logging
Logging ist „ich speichere alles”. Observability ist „ich kann beantworten warum dieser Lauf scheiterte”.
Pro Run minimal:
- Tool-Call-Sequence
- Token-Verbrauch
- Eskalations-Trigger
- Endzustand
Wichtigste zentrale Metrik: Tool-Call-Success-Rate. Wenn der prozentuale Anteil sinkt, hast du ein Problem bevor User es merken.
Strukturierte JSON-Logs nach S3 plus CloudWatch-Metric-Filter reicht fuer KMU-Scale. Datadog/New-Relic kostet 10x mehr.
9. Cost und Latency sind Design-Entscheidungen
Drei oft uebersehene Hebel:
- Prompt-Caching. Sonnet 4.6 + Bedrock unterstuetzt das, spart 50-90 % bei wiederholtem System-Prompt. Relevant ueberall wo grosser Prompt staendig wieder kommt (Receptionist, Friseur-Bot, Open WebUI Custom-Model).
- Parallele Tool-Calls. Wenn drei Lookups unabhaengig sind, alle gleichzeitig statt nacheinander.
- Modell-Routing. Sonnet fuer Reasoning, Haiku fuer Klassifikation auf dem Hot-Path. Pre-Klassifikator-Call vor Sonnet („braucht das Reasoning oder Routing?”) ist oft 10x guenstiger ohne Qualitaetsverlust.
10. Compound — jeder Lauf macht das System besser
Der Unterschied zwischen einem Agent und einem agentischen System ist, ob der Agent von eigenen Laeufen lernt. Konkret:
- Jeder Fehlerfall wird zu einem Eval-Case.
- Jede neue Edge-Case zu einer System-Prompt-Klausel oder einer Tool-Verbesserung.
- Run-Logs + Lessons-Learned als Pflicht-Artefakt.
Wenn dieser Loop nicht laeuft: nach 3 Monaten gleiche Bugs wie am Anfang.
Anti-Patterns
„Lass den Agenten alles selbst entscheiden”
Nein. Klare Grenzen im System-Prompt. Tools, die nur das Erlaubte erlauben. Capability via Tool ist sicherer als Capability via Anweisung.
„Ich packe alles in den System-Prompt damit der Agent es weiss”
Statt 4000 Zeilen System-Prompt: 200 Zeilen Pflicht plus Tools die kontextuelle Info ziehen wenn noetig.
„Multi-Agent klingt eleganter”
Vor dem Bauen: kannst du das gleiche Ergebnis mit einem Agent und mehr Tools erreichen? In 90 % der Faelle ja.
„Vector-DB fuer alles”
Wenn deine Antwort „lies File X” ist und du weisst welches File: vector ist Overkill.
„Wir schicken eh nur an Bedrock, also passt DSGVO”
Nein. Du brauchst region-locked Inference-Profile (kein Cross-Region), das ZDR-Addendum von Anthropic, und eine Schrems-II-TIA fuer den AWS-Sub-Processor. Drei Konfigurations-Items.
„Logging reicht”
Logging ohne Observability heisst: du hast Daten und kannst sie nicht abfragen. JSON-strukturiert, Felder-Konvention, query-bar — sonst Muelldeponie.
Stack-Empfehlung fuer den AV-Daily-Use
| Layer | Empfehlung | Cross-Ref |
|---|---|---|
| Modell (Default) | Claude Sonnet 4.6 ueber Bedrock EU + Prompt-Caching | modell-vergleich-dsgvo |
| Modell (Plans/Hard) | Claude Opus 4.7 ueber Bedrock EU, on-demand | modell-vergleich-dsgvo |
| Modell (Routing) | Haiku 4.5 (Bedrock EU) oder Gemma 4 26B MoE self-hosted | modell-vergleich-dsgvo |
| Tool-Layer | MCPs mit mcp-best-practices-Pattern | mcp-best-practices |
| Memory | Vault (Markdown + Wikilinks) als primaer | (dieses File) |
| Memory (unstrukturiert) | S3 + pgvector nur fuer Belege/Emails/Transkripte | (Sprint 3+) |
| Orchestrierung | agents-platform (Lambda + EventBridge) | agents-platform |
| Eskalation | WhatsApp/Email via notify_user Tool | receptionist |
| Observability | Strukturierte JSON-Logs → CloudWatch | (dieses File) |
| Evals | 20 Cases pro Agent, manueller Re-Run vor Deploy | agent-system-audit-rubric |
| Cron/Scheduler | EventBridge im CDK-Stack | agents-platform |
| Secrets | AWS Secrets Manager | secrets-manager |
Anwendungs-Beispiele im eigenen Stack
| System | Stand | Audit-Score | Notes |
|---|---|---|---|
| Open WebUI VF | live, Welle 1 in Planung | 6.6/10 → 8.2/10 Ziel | _index |
| Receptionist-Platform | live | nicht auditiert | receptionist |
| Friseur-im-Sueden-Bot | aktiv im Bau | nicht auditiert | _index |
| agents-platform Cron-Lambdas | mehrere live | nicht auditiert | agents-platform |
Wenn ein Agent-System >2 Wochen produktiv laeuft: audit-rubric drueber laufen lassen.
Cross-Refs
- agent-system-audit-rubric — die Rubric die aus diesen Prinzipien abgeleitet ist
- modell-vergleich-dsgvo — Modell-Wahl-Spezifika
- mcp-best-practices — Tool-Design-Detail
- open-webui-fargate-bedrock — konkretes Hosting-Pattern
- mcp-hosting-fargate-tunnel — konkretes MCP-Hosting-Pattern