ki-buch/teil-02-agenten-mcp/kapitel-04-einfuehrung-ki-agenten-mcp.md

Kapitel 4: Einführung in KI-Agenten und das Model Context Protocol (MCP)

Teil II · Von LLMs zu autonomen Agenten – MCP als zentrale Schicht

---

Ein Chat, der gut klingt, ist noch kein Agent. Sobald ein System mehrere Schritte plant, Tools ausführt, Beobachtungen einarbeitet und unter Policies stoppt, brauchst du mehr als ein starkes Modell: eine Harness (Loop, State, Permissions, Verify) und eine klare Antwort, wo Capabilities leben – host-native, Framework-intern oder portabel (häufig MCP). Ohne diese Trennung wird Autonomie zu Demo-Theater: beeindruckend in der Aufnahme, unsteuerbar im Repo.

These: Agent = Model + Harness. Das Modell entscheidet probabilistisch; Harness und Capability-Schicht tragen Loop, Kontext, Rechte und Verifikation. MCP standardisiert Anschluss – es ist nicht automatisch die erste Wahl für jeden Editor-Pixel oder jede Orchestrierung.

Leitfrage: Was ist ein Agent operational – und wie koppelt er sich an die Außenwelt, ohne Architektur und Security zu verwässern?

Dieses Kapitel ist der kanonische Kern des Buchs: Agent-Definition und Perceive–Reason–Act, Runtime-Anatomie, Harness-Landschaft 2026, System-Prompts und ihre Grenzen, der einzige MCP-Deep-Dive (Host–Client–Server, Tools/Resources/Prompts, Lifecycle, wann nicht). 4.0 liefert die Entscheidungslandkarte; 4.8 ordnet die Spec-Revision 2026-07-28 ein. Kapitel 2 lieferte nur die Bridge „warum Window + RAG nicht reichen“ – Details stehen hier. Praxis ab Kapitel 7; Security in Kapitel 11.

Lernziele

Nach diesem Kapitel kannst du:

• einen KI-Agenten operational definieren und von Chatbots sowie einfachen Tool-Assistenten abgrenzen,
• die Schleifen Perceive – Reason – Act sowie Muster wie ReAct und Plan-and-Execute erklären,
• typische Bausteine einer Agent-Runtime (State, Tools, Memory, Policies, Evals) skizzieren,
• erklären, warum Agent = Model + Harness gilt und was zu einem modernen Coding Harness (2026) gehört,
• wichtige Harnesses (Claude Code, Cursor, Copilot, Grok Build, Codex, Aider & Co.) vergleichen und einordnen,
• System Prompts modular und praxisnah entwerfen – und ihre Grenzen gegenüber Skills/Policies kennen,
• das Model Context Protocol in Architektur und Lifecycle beschreiben (Host, Client, Server),
• Tools, Resources und Prompts korrekt einordnen und gegen Function Calling abgrenzen,
• begründen, warum MCP Context-Bloat reduziert und dynamische Tool-Discovery für Coding Agents ermöglicht,
• einen minimalen Agenten-Flow mit MCP-Tools in Python skizzieren,
• Host-first vs. MCP-first vs. Framework vs. Custom-Harness begründen (4.0) und sagen, wann MCP nicht erste Wahl ist (4.7.5),
• die Revision 2026-07-28 als beobachtbaren Bruch einordnen und eine Migrate-vs-Pin-Entscheidung begründen (4.8).

---

4.0 Architektur-Entscheidungslandkarte: wo lebt die Capability?

Ziel: in 15 Minuten eine Default-Strategie wählen – nicht das „beste Framework“.

Vier Grundmuster

Muster	Kernidee	Stärken	Schwächen	Typische Nutzung
Host-first	IDE/CLI-Produkt + native Tools/Plugins	UX, Latenz, Diff-Flow, geringe Ops	Portabilität↓, Vendor-Pfad	Alltag einzelner Devs, Inline-Edit
MCP-first	Capabilities als Server (Tools/Resources/Prompts)	N+M, Katalog, Wiederverwendung, klare Trust Boundary	IPC/HTTP-Overhead, Server-Ops	Git/Issues/CI/Memory/Graph über mehrere Hosts
Framework-orchestrated	Graph/State-Machine/Crew orchestriert Steps	kontrollierte Flows, CI-Agenten, komplexe DAGs	Lock-in, wenn Tools im Framework leben	interne Automationen, Batch, Multi-Step Jobs
Custom Harness	eigener Loop + Policies + Verify	volle Kontrolle, Org-Passform	Bau- und Pflegekosten	Platform-Team, regulierte Umgebungen

Faustregel: Default 2026 (pragmatisch): Host-first für Editor-UX plus MCP-first für domänige, geteilte Capabilities plus schlanke Orchestrierung nur dort, wo State-Maschinen echten Mehrwert haben. Custom Harness, wenn Compliance/Control den Bau rechtfertigt. [E4]

Entscheidungsfragen (in Reihenfolge)

1. Muss die Fähigkeit in mehr als einem Host oder Team landen? → ja: MCP-Kandidat.
2. Ist es primär Editor-State (Buffer, Cursor, Inline-Diff)? → Host-native.
3. Braucht ihr auditierbare, versionierte Server-Grenzen (Auth, Allowlist)? → MCP + Gateway-Option.
4. Ist der Flow ein langlebiger, verzweigter Job mit explizitem State? → Framework-Graph über MCP-Tools, nicht statt.
5. Reicht ein reifer Single-Host-Stack und Portabilität ist 12+ Monate irrelevant? → Host-first bewusst, MCP-Schuld dokumentieren.
6. Ist das Problem Orchestrierung zwischen Agents? → Shared Context/Contracts (Kap. 5, 8), nicht „mehr MCP“.

Kombinationsmatrix (erlaubt und üblich)

Szenario	Host-UX	MCP-Server	Graph-Runtime
Dev-Alltag	primär	geladen für Repo/Issues/Tests	selten
CI-/Nightly-Agent	nein/Headless	ja	oft ja
Enterprise-Katalog	viele Hosts	ja + Gateway	optional
Spike / PoC	ja	LocalBus/in-process ok	nein

Anti-Muster

Anti-Muster	Warum teuer
Alles über MCP inklusive Cursor-Position	Latenz, Komplexität, kein Portabilitätsgewinn
Alles nur im Framework-Tooling	N×M, sobald zweiter Host kommt
Custom Harness ohne Eval und Threat Model	Platform-Theater
Multi-Agent vor Single-Agent-Evals	Fehler multiplizieren

Mini-ADR-Template

Titel: Capability <X> – Host-native | MCP | Framework-only | Hybrid
Kontext: Hosts = {…}; Teams = {…}; Datenklasse = {public|internal|secret}
Entscheidung: …
Begründung: Portabilität / Latenz / UX / Compliance
Folgen: Ops-Owner, Spec-Pin, Eval-Case-IDs, Review-Gate
Review-bis: YYYY-MM

Querverweise: Framework-Wahl Kap. 6.6 · Host-Plugins Kap. 9 · Wann MCP nicht 4.7.5 · Risiko Kap. 11.

---

4.1 Was ist ein KI-Agent? – Eine operative Definition

Es gibt inflationäre Marketing-Definitionen. Für Engineering brauchst du eine testbare:

Ein KI-Agent ist ein System, das ein Ziel über mehrere Schritte verfolgt, dabei Umweltzustand wahrnimmt (Lesen, Tools, Events), mit einem Modell (oder mehreren) Entscheidungen trifft und Aktionen ausführt, deren Ergebnisse wieder in den Entscheidungsprozess einfließen – bis ein Stopp-Kriterium greift (Erfolg, Budget, Eskalation, Fehler).

Abgrenzung

System	Zielverfolgung	Wahrnehmung	Aktion	Autonomie
Chatbot	meist 1 Turn	nur Prompt	Text	niedrig
Autocomplete	lokal, implizit	Editor-Kontext	Vorschlag	niedrig
Tool-Assistent	kurz, user-getrieben	Tools ad hoc	Host führt 1–n Calls	mittel
Agent	explizites Ziel, Multi-Step	fortlaufend	Schleife mit State	hoch (policy-begrenzt)
Multi-Agent	Ziele + Delegation	geteilt/privat	koordiniert	variabel

Analogie: Ein Chatbot ist ein Auskunftsschalter. Ein Tool-Assistent ist ein Schalter mit Telefon zu drei Abteilungen. Ein Agent ist ein Sachbearbeiter mit Akte, Checkliste, Frist und Eskalationsweg – idealerweise mit standardisierten Schnittstellen zu Fachsystemen (MCP).

Autonomie ist ein Spektrum, kein Binärschalter. Produktionsagenten sind oft „semi-autonom“: lesen und patchen frei, mergen und deployen nur mit HITL.

---

4.2 Perceive – Reason – Act: der Grundzyklus

Konzept-Plate: Perceive · Reason · Act

{ width=100% }

Perceive (Wahrnehmen)

Quellen:

• User-Nachricht und Spec,
• Dateisystem / Repo (Resources),
• Tool-Results (Tests, Logs, HTTP),
• Memory (ADRs, TODOs),
• Events (CI Webhook, Issue-Update).

Wahrnehmung ohne Struktur ist Rauschen. Deshalb: komprimieren, labeln, Provenance mitgeben (Kap. 3).

Reason (Schließen / Planen)

Das LLM (oder ein Router aus mehreren Modellen) erzeugt:

• Hypothesen („Flaky wegen Zeitzone“),
• nächste Aktionen,
• ggf. strukturierte Pläne,
• Entscheidung: weiter, nachfragen, abbrechen.

Act (Handeln)

Der Host führt aus – nie „das Modell selbst“ im Sinne von OS-Privilegien. Act umfasst:

• MCP tools/call,
• interne Functions,
• UI-Vorschläge (Diff zeigen),
• menschliche Freigabe-Requests.

---

4.3 Kernmuster: ReAct, Plan-and-Execute und Tool-Loops

ReAct (Reason + Act)

Klassisches Muster: abwechselnd kurze Überlegung und Tool-Aufruf.

Thought: Ich brauche den failing test.
Action: read_file(path="tests/test_billing.py")
Observation: assert total == 42 …
Thought: Ich prüfe die Implementation.
Action: read_file(path="src/billing/total.py")
…

Stärken: einfach, flexibel, gut für Exploration. Schwächen: Planlosigkeit, Wiederholungen, schweres Budget-Management.

Plan-and-Execute

1. Erzeuge einen Plan (Liste von Schritten).
2. Führe Schritte aus (ggf. mit eigenem Worker-Prompt).
3. Re-plane bei Blockern.

{ width=100% }

Reflexion und Self-Check

Nach Act: „Haben Tests bestanden? Entspricht der Diff der Spec?“ – ideal als harte Tools (nicht nur Selbstlob im Text).

Router-Agenten

Ein kleines/cheapes Modell klassifiziert Intent und routet an Spezialisten (Review-Agent, Test-Agent). MCP hält die Tool-Schicht dabei stabil.

---

4.4 Anatomie einer Agent-Runtime

Ein produktiver Coding Agent ist kein einzelner Prompt, sondern ein Zusammenspiel von Bausteinen: Wer den Loop steuert, wo State lebt, wer das Window baut, wer Tools erlaubt und wer Spuren schreibt. Die Tabelle ist eine Checkliste für Architektur-Reviews – wenn ein Baustein fehlt, debuggst du später Symptome statt Ursachen.

{ width=100% }

Baustein	Aufgabe
Orchestrator	Loop, Transitions, Timeouts
State	Plan, TODOs, Datei-Locks, Attempt-Zähler
Context Engineer	Window bauen (Kap. 3.7)
Policy Engine	Allowlist Tools, Pfade, Netz, HITL-Gates
Model Router	Modellwahl nach Taskklasse
MCP Clients	standardisierte Außenwelt
Tracing	Spans für jeden Tool-Call und Context-Snapshot-Hash

Ohne Tracing debuggst du Geister. Ohne Policy baust du eine Remote-Shell mit Poetry.

---

4.5 Der Agent Harness – Agent = Model + Harness

Dieser Abschnitt verschiebt den Blick vom Modell-Marketing auf den Betriebsrahmen: Loop, Tools, Context Pipeline, Permissions, Hooks, Sandbox, Verification, Observability und UX. Dieselbe Frontier-Qualität liefert in einem schwachen Harness Chaos und in einem starken messbare Task Success [E4]. Nutze den Vergleich der Coding Harnesses 2026 als Entscheidungs- und Audit-Raster – und trenne Produkt-Harness (Host) von Org-Harness (Rules, Skills, MCP-Katalog, Policies). Produktnamen und Feature-Listen sind volatil (Stand 2026-07); die Schichten bleiben das stabile Raster.

4.5.1 Die zentrale Gleichung

In Produktdemos dominiert oft das Modell. In der Praxis der Softwareentwicklung gilt:

Leitsatz: Agent = Model + Harness. [E4]

Das Model liefert probabilistische Entscheidungen (nächster Schritt, Tool-Wahl, Patch-Vorschlag). Der Harness (Geschirr, Laufgestell, Betriebsrahmen) liefert alles, was aus einem Chat ein steuerbares, sicheres, wiederholbares Arbeitssystem macht.

Konzept-Plate: Agent = Model + Harness

{ width=100% }

Analogie: Das Modell ist der Motor. Der Harness ist Fahrwerk, Getriebe, Instrumente, Sicherheitsgurt und Navigationssystem. Ein stärkerer Motor in einem Auto ohne Bremsen macht Unfälle nur teurer – nicht Fahrten sicherer.

Harness ist eng verwandt mit dem, was wir in 4.4 Agent-Runtime genannt haben. Der Begriff betont den Produkt- und DX-Blick 2025/26: Claude Code, Cursor, Copilot Workspace, CLI-Agenten – das sind Harnesses, die Modelle einspannen.

4.5.2 Was gehört in einen modernen Coding Harness (2026)?

Ein moderner Coding Harness ist kein einzelnes Feature, sondern ein Schichtenstapel. Du kannst ihn von außen (UX, Diff-Ansicht) oder von innen (Permissions, Verification) betrachten – entscheidend ist: Jede Schicht beantwortet eine andere Frage. Fehlt eine Schicht, wandert das Risiko ins Modell („sei bitte vorsichtig“) oder in den Menschen (manuelles Aufräumen).

Die folgende Tabelle listet die Schichten, die 2026 in praxistauglichen Coding-Harnesses wiederkehren. Nutze sie als Audit-Raster: Hake ab, was euer Host oder eure Runtime wirklich abdeckt – und wo ihr noch auf Prompt-Hoffnung setzt.

Schicht	Inhalt	Ohne sie …
Core System Prompt	Rolle, harte Regeln, Ausgabeformate, DoD-Disziplin	driftendes Verhalten
Skills / Playbooks	modulare, on-demand Fähigkeiten (Kap. 5)	Riesenprompts, Context Rot
Tool-Schicht	Shell (eng), Edit, Search, MCP-Server	reiner Text ohne Wirkung
Context Pipeline	Working Set, Rules-Dateien, Memory, Diff-first	Repo-Dump oder Blindflug
Permissions	allow/deny, path scopes, network, HITL	Sicherheitsvorfälle
Hooks	pre/post tool, session start, stop	keine Team-Gates
Sandbox / Isolation	Workspace-Jail, Container, Timeouts	Blast Radius unkontrolliert
Loop & State	max steps, plan, todos, cancel	Endlosschleifen
Verification	tests, lint, typecheck als Pflicht-Schleife	„fertig“ ohne Beweis
Checkpoints	Snapshots, undo, branch-disziplin	irreversibler Schaden
Observability	traces, token cost, tool audit	undebuggbar
UX Surface	Terminal, IDE, PR-Comments	Adoption im Team scheitert

Nicht jeder Harness implementiert jede Schicht gleich – aber fehlende Schichten erklären die meisten „das Modell ist dumm“-Tickets.

Zwei Lesarten helfen im Team-Gespräch: (1) Produkt-Harness – was Cursor, Claude Code, Copilot & Co. mitbringen; (2) Org-Harness – Rules, Skills, MCP-Katalog, Policies und Evals, die ihr versioniert. Viele „das Modell ist dumm“-Tickets sitzen genau in der Lücke zwischen beiden.

4.5.3 Harness-Landschaft 2026 im Vergleich

{ width=100% } Die folgenden Profile sind Orientierung, kein Ranking. Features und Namen ändern sich; die Vergleichsachse bleibt: Surface (IDE vs. CLI), Autonomie-Tendenz, wie stark ihr Policies und MCP selbst pflegen müsst. Lies mit der Frage: Welcher Harness passt zu unserem Arbeitsalltag – und was müssen wir portabel daneben bauen?

Claude Code (terminal-native)

Profil	CLI-first Coding Agent, stark in langen, tool-lastigen Sessions
Stärken	autonome Multi-Step-Workflows, Repo-Exploration, MCP-Anbindung, klare Tool-Loop-Kultur
Schwächen	weniger „visuelle IDE“; Governance/Team-Standards musst du selbst disziplinieren
Use-Cases	Feature-Implementierung, Refactors, Incident-Triage auf der Shell, Server-SSH-Sessions
Harness-Charakter	schlanker, mächtiger Loop + Tools; Skills/Rules je nach Setup und Team-Konvention

Cursor (IDE-Harness)

Profil	AI-native IDE mit Chat, Composer/Agent, Index, Rules, Skills, Hooks
Stärken	Diff-UX, Editor-Kontext (Selektion, Lints), teamfähige Rules, hoher DX-Alltag
Schwächen	Lock-in-Gefühl an Produkt-Features; Context aus Index + MCP muss sauber orchestriert werden
Use-Cases	tägliches Entwickeln, multi-file edits, Review im Diff, Onboarding im Editor
Harness-Charakter	reich an UX- und Policy-Flächen; Harness Engineering = Rules/Skills/Hooks/MCP pflegen

GitHub Copilot (CLI / Workspace / IDE)

Profil	Ökosystem aus Inline-Completion, Chat, Agent- und Workspace-Modi, CLI – eng an GitHub
Stärken	Integration PR/Issues/Actions, Enterprise-Verfügbarkeit, breite Adoption
Schwächen	Harness-Tiefe und Agent-Autonomie variieren je Produktfläche; portable MCP-Strategie parallel denken
Use-Cases	GitHub-zentrierte Teams, PR-Flows, „gut genug“-Agenten im bekannten Ecosystem
Harness-Charakter	Plattform-Harness: Stärke = Integration, nicht maximale Custom-Orchestration

Grok Build (und vergleichbare xAI-/Build-Modi)

Profil	Build-/Agent-Modi im Grok-/xAI-Umfeld: softwareorientierte Loops, Tool-Use, Workspace-Arbeit (Begriffe und Surfaces entwickeln sich weiter)
Stärken	enge Kopplung an leistungsfähige Modelle, praxisnahe Build-Workflows, oft stark bei iterativem Implementieren
Schwächen	Ökosystem- und Host-Reife je nach Zeitpunkt; Enterprise-Controls und MCP-Parität mit etablierten IDEs prüfen
Use-Cases	feature builds, exploratives Coding, Teams im xAI/Grok-Stack
Harness-Charakter	modellnaher Build-Harness – Policies, Skills und portable MCP-Server bleiben euer Differenzierungspfad

Codex CLI und verwandte OpenAI-Coding-CLIs

Profil	Terminal-Agenten im OpenAI-Ökosystem (Codex-Linie und Nachfolger/Varianten)
Stärken	CLI-Autonomie, gute Passung zu OpenAI-Models und Tool-Calling
Schwächen	Team-Standards und IDE-UX separat; Feature-Set im Wandel
Use-Cases	Scriptable agents, CI-nah, Power-User in der Shell

OpenCode, Aider und weitere Open-/Community-Harnesses

Harness	Typische Stärke	Typische Grenze
Aider	Git-natives Pairing, klare Edit-Loops, modellagnostisch	weniger „Full Product IDE“
OpenCode / offene Agent-CLIs	Kontrolle, Self-Host, Anpassbarkeit	Ops- und Polish-Aufwand
Continue.dev	offener IDE-Stack, model-flexibel	mehr Eigenintegration
Eigene Graph-Runtime (LangGraph + MCP)	volle Kontrolle, CI-Parität	Bau- und Wartungskosten

4.5.4 Vergleichstabelle (Entscheidungshilfe)

Die Tabelle verdichtet die Profile auf Entscheidungskriterien. Wenn zwei Harnesses „hoch“ bei Autonomie liegen, entscheide über Team-DX und Governance-Flächen, nicht über Marketing-Demos. Die Faustregel darunter bleibt die eigentliche Architektur-Aussage des Abschnitts.

Harness	Surface	Autonomie-Tendenz	Stärke	MCP / Extensibility	Bester Fit
Claude Code	Terminal	hoch	lange tool-Loops	stark relevant	Deep work in Repo/SSH
Cursor	IDE	mittel–hoch	Rules/Skills/Hooks + Diff-UX	stark	Daily driver IDE
Copilot Workspace/CLI	IDE + GitHub + CLI	mittel–hoch	Plattform-Integration	je nach Fläche	GitHub-zentrierte Orgs
Grok Build	Build/Agent-Modi	hoch	modellnahe Iteration	prüfen/ergänzen	xAI-affine Workflows
Codex CLI	Terminal	hoch	OpenAI-Stack	je Release	CLI-Automation
Aider	Terminal	mittel–hoch	Git-first edits	begrenzt/nativ anders	Fokussierte Edit-Sessions
Custom (LangGraph+MCP)	headless/CI	konfigurierbar	Governance & Evals	first-class	Plattform-Teams

Faustregel: Wähle den Harness nach Surface und Team-DX, baue Capabilities portabel (MCP) und halte Rules/Skills/Policies versioniert im Repo – dann bist du nicht an einen Host verheiratet. [E4]

4.5.5 System Prompt – immer noch wichtig, aber nicht mehr alles

Warum monolithische System-Prompts scheitern

Teams packten früher „alles“ in einen System-Prompt: Style Guide, Architektur, Security, Git-Workflow, Review-Checklisten, 40 Edge Cases.

Problem	Wirkung
Context Rot	Regeln verwässern sich in der Länge; das Modell „vergisst“ die Mitte
Token-Verschwendung	Jeder Turn zahlt den vollen Regelberg – auch für rename variable
Inflexibilität	Task A braucht Security-Tiefe, Task B nicht – beides liegt immer im Window
Wartungs-Albtraum	niemand reviewed 800 Zeilen Prompt; Widersprüche entstehen
Fehlende Durchsetzung	Prompt sagt „nie .env lesen“ – ohne Permission Layer passiert es trotzdem

{ width=100% }

Was der Core-System-Prompt noch leisten muss

Der Core-Prompt ist die Verfassung, nicht das Gesetzbuch:

1. Rolle und Qualitätsanspruch
2. Harte Verhaltensregeln (Tests vor „fertig“, keine Secret-Exfil, ehrliche Unsicherheit)
3. Arbeitsmodus (Working Set, minimale Diffs, nachfragen bei Ambiguität)
4. Ausgabe- und Tool-Disziplin
5. Eskalation / Stopp-Kriterien

Alles Domänenspezifische → Skills, Rules-Dateien, MCP-Prompts/Resources.

Best Practices für System Prompts in Agenten

1. Kurz und stabil – ideal messbar (z. B. < ~1–2k Tokens Core)
2. Struktur mit klaren Überschriften / XML- oder Markdown-Sektionen
3. Negativregeln sparsam, aber scharf („Never …“)
4. Verifikation erzwingen in Worten und im Harness (Tool-Pflicht)
5. Keine wechselnden Fakten (API-Namen eures Services) – die gehören in Memory/Resources
6. Versionieren (system-prompt.md + Changelog) wie Code
7. Eval-Gates bei Änderungen (Kap. 6, Anhang C)

Beispiel: Core-System-Prompt (Skizze)

# Rolle
Du bist ein sorgfältiger Coding Agent in einem Git-Repository.

# Harte Regeln
1. Behaupte keine Testergebnisse ohne ausgeführtes Test-Tool.
2. Lies oder exfiltriere keine Secrets (.env, keys, credentials).
3. Bevorzuge minimale Diffs; keine Scope-Creep-Refactors.
4. Bei unklarer Spec: stelle gezielte Fragen statt zu raten.
5. Stoppe bei Budget- oder Policy-Grenzen und erkläre den Blocker.

# Arbeitsweise
- Baue ein Working Set (Issue/AC, betroffene Dateien, Tests).
- Ändere → verifiziere (tests/lint/types) → erst dann „fertig“.
- Nutze verfügbare Skills und MCP-Tools; erfinde keine internen APIs.

# Ausgabe
- Kurze Status-Updates in Schritten.
- Am Ende: Summary, geänderte Pfade, verbleibende Risiken.

Dieser Core bleibt über Tasks gleich. Security-Review, Migration-Playbook oder „Flaky-Test-Jagd“ kommen als Skill (Kap. 5) hinzu.

4.5.6 Harness vs. MCP vs. Model – Arbeitsteilung

Schicht	Owner-Frage	Beispiel
Model	Welches Reasoning/Coding-Niveau?	Frontier vs. cheap router
Harness	Wie läuft der Loop sicher und nützlich?	Cursor Rules, Claude Code tools, budgets
MCP	Welche portablen Capabilities?	memory, git, ci server
Context Engineering	Was kommt wann ins Window?	Working Set Policy

Don’t blame the model first: Scheitert der Agent an fehlenden Tests im Loop, an zu vielen Tools oder an einem 10-kB-Systemprompt voller Widersprüche, ist das ein Harness- und Context-Problem.

Querverweise: Schichten und Produktlandschaft hier (4.5). Methoden (Hooks, Permissions, Verify-Loops, Audit-Checkliste): Kap. 5.11. Production Control Plane: Kap. 11.10.

---

4.6 Coding Agents: spezielle Anforderungen

Softwareentwicklung ist ein hartes Agent-Domain:

• Zustand ist riesig (Monorepos),
• Wahrheit ist ausführbar (Tests, Types),
• Nebenwirkungen sind teuer (Prod, Daten),
• Teams brauchen Nachvollziehbarkeit (PR, Review),
• Kontext wechselt mit Branch und Environment.

Typischer Coding-Agent-Flow

1. Issue/Spec lesen (Resource/Tool)
2. Reproduzieren (Tests, Repro-Skript)
3. Lokalisieren (Search, Graph, blame)
4. Patchen (edit tools)
5. Verifizieren (test, lint, typecheck)
6. Erklären (PR-Body, Risiko)
7. Optional: Review-Agent, Security-Pass

Definition of Done für Agenten-Tasks

Ein Coding Agent „ist fertig“, wenn objektive Checks grün sind – nicht wenn er „fertig“ schreibt.

@dataclass
class StopCriteria:
    tests_passed: bool
    lint_clean: bool
    max_steps: int
    steps_used: int
    user_aborted: bool

    def done(self) -> bool:
        if self.user_aborted:
            return True
        if self.steps_used >= self.max_steps:
            return True
        return self.tests_passed and self.lint_clean

---

4.7 Das Model Context Protocol (MCP) – Die universelle Sprache für Agenten-Tool-Interaktion

MCP wird hier kanonisch als Agenten-Infrastruktur vertieft: Host–Client–Server, Lifecycle und die first-class Primitives Tools, Resources und Prompts. (Kapitel 2 liefert nur die Bridge, warum Window und RAG allein nicht reichen.) Der Harness nutzt MCP; er ist nicht MCP. Lies den Abschnitt als stabiles Architekturfundament gegen N×M-Integrationen und Context-Bloat – inklusive klarer Grenzen in 4.7.5.

Analogie: MCP ist das USB-C der Agent-Capabilities: ein gemeinsamer Stecker für Anschluss, Discovery und den Austausch von Tools, Resources und Prompts. Der Stecker standardisiert den Kontakt – nicht Intelligenz, Sicherheit oder guten Prozess. Wann der Stecker die falsche Investition ist: 4.7.5.

Schicht	In diesem Abschnitt	Stand
Stabil	Host–Client–Server, Primitives, Trust Boundaries	MCP Spec 2025-11-25
Mittelstabil	Agent-Loop mit Tools/Resources, Stop-Kriterien	Muster
Volatil / Übergang	Lifecycle-Details (Session/Handshake) laut 2025-11-25; Übergang → 4.8; FastMCP-/Host-Snippets	Juli 2026 / Companion

Normativ: MCP Spec 2025-11-25 · Lifecycle · Tools · Resources · Prompts.

4.7.1 Architektur: Host – Client – Server

MCP trennt bewusst drei Rollen, die in Demos oft in einem Prozess verschwimmen. Für Architektur und Security ist die Trennung zentral: Wer orchestriert und baut Kontext? (Host) Wer hält die Protokollsession? (Client) Wer besitzt Domänenfähigkeit und Daten? (Server). Verwechselst du die Rollen, landen Policies im falschen Layer – oder Secrets im falschen Prozess.

Host

Die AI-Anwendung: Claude Code, Cursor, Windsurf, Continue, eigene Runtime, CI-Bot. Der Host ist die Steuerzentrale des Agenten:

• besitzt UX und Agent-Loop,
• verwaltet Clients,
• spricht mit dem LLM,
• erzwingt Policies,
• baut das Context Window.

Client

Pro verbundenem Server ein Client (1:1). Der Client ist der Adapter zum Server, nicht die Domänenlogik:

• initialisiert die Session,
• verhandelt Protokollversion und Capabilities,
• leitet tools/list, resources/read, prompts/get, tools/call weiter,
• empfängt Notifications (z. B. Resource-Updates, je nach Spec/Support).

Server

Eigenständiger Prozess oder Remote-Dienst. Der Server ist die portable Capability – idealerweise so schlank, dass mehrere Hosts ihn wiederverwenden:

• implementiert Domänenlogik (GitHub, Postgres, interner ADR-Store),
• exponiert Primitives,
• bleibt idealerweise fokussiert (Single Responsibility).

{ width=100% }

Transport und Data Layer

Host, Client und Server sprechen über zwei Schichten: was ausgetauscht wird (Data Layer) und wie die Bytes fließen (Transport). Für den Alltag reicht: lokal oft STDIO (Kindprozess), remote Streamable HTTP – beides mit demselben JSON-RPC-Lebenszyklus.

Schicht	Inhalt	Spec-Anker
Data Layer	JSON-RPC 2.0 Messages, Lifecycle, Primitives, Errors	MCP Spec 2025-11-25
Transport	STDIO (lokaler Kindprozess), Streamable HTTP (remote, multi-client)	Spec → Transports

Capability Negotiation und Session-Start folgen dem Lifecycle (initialize → capabilities/serverInfo → notifications/initialized) – siehe Lifecycle.

{ width=100% }

Lifecycle-Pitfalls

• Capabilities nur nach erfolgreichem Handshake nutzen (Lifecycle)
• Timeouts und Cancel bei hängenden Tools
• Server-Absturz ≠ Modellfehler – Runtime muss re-connecten oder degradieren
• Version-Skew: Server und Host auf kompatiblen Spec-Stand halten (Buch-Pin: 2025-11-25)

---

4.7.2 Tools, Resources und Prompts als erste Klasse

Tools – model-controlled actions

Semantik: Side-effect-behaftete oder berechnende Operationen, die das Modell anstoßen darf (nach Policy).

Gute Tool-Design-Regeln:

1. Eng und benannt nach Outcome – run_unit_tests statt exec
2. JSON-Schema mit strengen Types – enums für modes
3. Idempotenz wo möglich – sichere Retries
4. Strukturierte Results – {ok, exit_code, summary, artifacts[]}
5. Fehler als Daten – stderr + code, nicht nur Exception-String
6. Least Privilege – getrennte read/write Tools

Muster (stabil): enges Tool, strukturiertes Result, Fehler als Daten.

Beispielimplementierung (Stand Juli 2026, FastMCP). Die konkrete API kann sich ändern – das zugrundeliegende Muster bleibt übertragbar.

from fastmcp import FastMCP

mcp = FastMCP("coding-tools")


@mcp.tool
def run_unit_tests(path: str = "tests") -> dict:
    """Führt Unit-Tests aus und liefert eine kompakte Zusammenfassung."""
    # subprocess, timeout, sandbox – Details in Kap. 10/11
    return {
        "ok": False,
        "exit_code": 1,
        "failed": ["tests/test_billing.py::test_invoice"],
        "summary": "1 failed, 12 passed",
    }

Resources – application-controlled context

Semantik: Lesbare Kontextstücke, adressiert über URIs. Der Host entscheidet (mit UI/Policy), wann sie geladen und ins Window gelegt werden – nicht jedes Resource ist automatisch im Prompt.

Beispiele für Softwareteams:

URI (illustrativ)	Inhalt
repo:///src/app/main.ts	Dateiinhalt @ revision
git:///diff/HEAD	Working tree diff
ci://billing/runs/latest	Letzter Pipeline-Status
memory://adr/2026-01-event-bus	Architekturentscheidung
issues://PROJ-123	Ticket inkl. Kommentare

Ein Resource-Handler liefert den Inhalt hinter der URI (z. B. memory://project/conventions → CONTRIBUTING.md); der Host entscheidet, ob und wann der Text ins Window wandert.

Warum Resources nicht einfach Tools sind: read_file als Tool zwingt jedes Lesen durch den Model-Tool-Loop (Latenz, Schema-Bloat, unklare Caching-Semantik). Resources erlauben Hosts, Kontext explizit und UI-gestützt zu laden, zu pinnen und zu budgetieren.

Prompts – user-controlled templates

Kuratierte Workflows:

• „Security Review für Diff“
• „Migration Plan Postgres → …“
• „Incident Postmortem Draft“

Sie standardisieren Team-Praxis und reduzieren Prompt-Drift – etwa „PR-Beschreibung mit Summary, Test Plan, Risk, Rollback“ als kuratierter Workflow statt freier Prompt-Wildwuchs.

Zusammenspiel

{ width=100% }

---

4.7.3 MCP vs. klassische Function Calling und Custom-Integrationen

{ width=100% }

Kriterium	Function Calling	Custom Integration	MCP
Standardisiert zwischen Apps	nein	nein	ja
Dynamische Discovery	begrenzt	plugin-spezifisch	ja
Resources first-class	selten	ad hoc	ja
Prompts/Workflows	proprietär	proprietär	ja
Lokale Stdio-Server	untypisch	manchmal	first-class
Remote multi-tenant	über eigene API	über eigene API	Streamable HTTP + Auth
Passend für	enge App-Features	einmalige IDE-Power	Plattform-Capabilities

Pragmatische Wahrheit 2026: Hosts übersetzen MCP-Tools intern oft in das Function-Calling-Format des jeweiligen Modell-Vendors. Für dich als Builder zählt: implementiere Capabilities einmal als MCP-Server, statt dreimal als Plugin.

Wann kein MCP?

• Extrem eng gekoppelte, host-interne Mikro-Funktionen ohne Wiederverwendung
• Hard-Realtime unterhalb sinnvoller RPC-Kosten (selten in SE-Agenten)
• Domänen, in denen euer Unternehmen bereits einen stabilen internen Capability-Bus hat – dann ggf. Adapter-Server von Bus → MCP

---

4.7.4 Vorteile für Softwareentwicklungs-Agenten

Dynamische Tool-Discovery

Neue Fähigkeit (z. B. interner Feature-Flag-Server) = neuer MCP-Server in der Host-Config. Agent-Code muss nicht neu gebaut werden; Context Engineering muss ggf. Routing-Regeln lernen.

Reduzierte Context-Bloat

Statt 50 Tool-Schemas und 20 Docs-Dumps:

• liste Tools, filtere auf Task-Klasse,
• lade Resources selektiv,
• nutze Prompts nur wenn User/Workflow sie anstößt.

Multi-Host-Wiederverwendung

Derselbe project-memory-Server speist:

• IDE-Agent am Schreibtisch,
• CLI-Agent in SSH,
• CI-Agent im Pipeline-Job (read-mostly + kommentierende Tools).

Sauberere Sicherheitsgrenzen

Server-Prozess mit eigenem Token-Scope, eingeschränktem FS-Root, Netzwerk-Policy – vom Host isolierbar. Kapitel 11: OAuth, Sandboxing, Injection.

Observability

Standardisierte Call-Grenzen erleichtern Tracing: server=ci tool=rerun_job duration=….

Beispiel: Agent-Schritt mit MCP-Client (skizzenhaft)

"""
Illustrativer Pseudocode: Agent-Schritt + MCP-Tool-Aufruf.
Konkrete SDK-APIs variieren – Muster bleibt stabil.
"""

from dataclasses import dataclass


@dataclass
class AgentState:
    goal: str
    steps: int = 0
    max_steps: int = 20
    notes: list[str] | None = None

    def __post_init__(self) -> None:
        self.notes = self.notes or []


def build_messages(state: AgentState, resource_texts: list[str], tools: list[dict]) -> list[dict]:
    system = (
        "Du bist ein Coding-Agent. Nutze Tools für Tests und Dateizugriff. "
        "Behaupte keine Testergebnisse ohne Tool."
    )
    ctx = "\n\n".join(resource_texts)
    return [
        {"role": "system", "content": system},
        {"role": "user", "content": f"Ziel: {state.goal}\n\nKontext:\n{ctx}"},
        # tools dem Model-API-Aufruf separat übergeben
    ]


def run_agent(goal: str, mcp_session, llm) -> str:
    state = AgentState(goal=goal)
    # Resources on-demand
    conventions = mcp_session.read_resource("memory://project/conventions")
    tools = mcp_session.list_tools()

    while state.steps < state.max_steps:
        state.steps += 1
        messages = build_messages(state, [conventions], tools)
        decision = llm.complete(messages, tools=tools)

        if decision.type == "final":
            return decision.content

        if decision.type == "tool_call":
            result = mcp_session.call_tool(decision.name, decision.arguments)
            state.notes.append(f"{decision.name}: {result.get('summary', result)}")
            # Observation in nächste Iteration einspeisen (Message-Historie)
            continue

    return "Abbruch: max_steps erreicht. Bitte Budget oder Ziel anpassen."

Tool-Results gehören vor dem nächsten Turn als kompakte Observations in den State (ok/summary, nicht der Roh-Dump) – Details zur Kompression in Kap. 3.

4.7.5 Wann MCP (noch) nicht die beste Wahl ist

MCP ist ein Capability- und Kontext-Bus, kein universelles Agent-OS. Glaubwürdige Architektur wählt das Protokoll – und lehnt es ab.

Schnellregel

Wenn …	Dann …
Portabilität über Hosts/Teams der Hauptnutzen ist	MCP ja
UX-Latenz im Editor der Hauptnutzen ist	Host-native ja
Orchestrierung/Delegation zwischen Agents das Problem ist	Shared Context/Contracts, MCP nur für Tools
Ein einziger Host, 12 Monate, kein zweites Team	MCP optional (Schuld dokumentieren)
Datenklasse secret + unklarer Server-Supply-Chain	MCP erst nach Threat Model & Pinning

Entscheidungstabelle

Situation	MCP?	Bessere Alternative	Harte Begründung	Review in
Editor-Buffer, Cursor, Inline-Diff, Selection-UX	Nein	Host-Plugin / native API	IPC löst kein UX-Problem; Millisekunden + Pixel	–
Sehr enge Tool-Loops, Offline, Air-Gap, extreme Latenz	Eher nein	In-process / LocalBus (Kap. 10)	Discovery+STDIO/HTTP kosten Zyklen	6 Mon.
Reifer proprietärer Plugin-Stack, ein Host dominiert	Später	Stack behalten; MCP an Team-Grenze	Migrationskosten > Nutzen	12 Mon.
Agent-to-Agent Handoff, Verhandlung, Delegation	Nicht primär	Contracts, Shared Store, Supervisor (Kap. 5, 8)	MCP = Capability-Zugriff, nicht Multi-Agent-Protokoll	–
Einmal-Skript, persönlicher Spike	Nein	CLI + Function Calling	Protokoll-Overhead ohne Wiederverwendung	–
Hochprivilegierte Prod-Mutation (Billing, IAM, Deploy prod)	Nur mit Gates	getrennte Server, HITL, Break-Glass	Protokoll ersetzt keine Policy	vor Go-Live
Ungepinte Community-Server ohne Owner	Nein	interner Fork/Wrapper oder Verzicht	Supply Chain = euer Incident	sofort
Streaming-Binary/große Artefakte als „Kontext“	Vorsicht	Object Store + Metadaten-Resource	Window-Bloat, Kosten	Design-Review
Vendor-API mit stabilem SDK und einem Consumer	Optional	native SDK hinter Adapter-Interface	MCP lohnt bei 2. Consumer/Host	bei 2. Host

Gegenprobe (wenn jemand „MCP everywhere“ will)

Beantworte mit Ja/Nein:

1. Gibt es heute oder in 6 Monaten einen zweiten Host oder ein zweites Team?
2. Kann ein Owner den Server versionieren, monitoren und patchen?
3. Ist die Trust Boundary im Threat Model (Kap. 11) gezeichnet?
4. Existiert mindestens ein Eval-Case mit must_call_tools / Success-Orakel?

≤2× Ja: MCP ist vorerst die falsche Investition.
≥3× Ja: MCP-first für diese Capability ist gerechtfertigt.

Faustregel: MCP dort, wo Capabilities portabel und regierbar sein sollen. Host-native dort, wo Pixel und Millisekunden zählen. Shared Context dort, wo mehrere Agents am selben Arbeitsstand arbeiten. Security-Gates dort, wo Wirkung real ist. [E4]

MCP ist 2025/26 der prominenteste offene Ansatz für Host–Client–Server-Tool-Integration (Spec-Pin des Buchs: 2025-11-25; Einordnung Stand 2026-07) [E4]. Feld-Adoptionsraten als Branchenmittel sind öffentlich nur bruchstückhaft belegt [E2]/[E5]. Ob MCP bei euch der richtige Schnitt ist, hängt von Host-Reife, Auth und Alternativen ab – siehe 4.7.5.

Querverweise: Landkarte 4.0 · Framework-Wahl Kap. 6 · Host-Plugins Kap. 9 · Risiko Kap. 11 · LocalBus-Demo Kap. 10 · Spec-Übergang 4.8.

---

4.8 Die Revision 2026-07-28 – was wirklich ändert sich (und was nicht)

Am 28. Juli 2026 erscheint die größte MCP-Revision seit dem Start: 2026-07-28. Sie betrifft vor allem Protokollzustand und Request-Form, nicht die Idee portabler Capabilities. Dieser Abschnitt ist Übergangs-Dokumentation: das Buch bleibt normativ auf 2025-11-25 (4.7); Teams brauchen eine klare Entscheidung, ob und wann sie migrieren.

Schicht	Aussage für 2026/2027
Primitiven (relativ stabil)	Tools, Resources, Prompts; Host–Client–Server; JSON-RPC-Grundlage
Protokollkern (Übergangsphase)	Sessions, initialize/initialized, Request-Self-Containment
Betrieb / Platform (volatil bis mittel)	Gateway-Routing, Auth-Hardening, Observability-Korrelation
SDK / Host-Config	weiter volatil – Companion bleibt auf 2025-11-25

Was bricht (beobachtbarer Bruch)

Unter 2025-11-25 beginnt eine Verbindung typischerweise mit initialize → Capability-Aushandlung → notifications/initialized; über Streamable HTTP trägt der Client oft ein Mcp-Session-Id, und Server-seitiger Zustand hängt am Session-Affinitätspfad (Sticky Routing, Session-Store). Abbildung k4-06 und Abschnitt 4.7.1 beschreiben genau dieses Modell.

Unter 2026-07-28 entfallen protocol-level Sessions und der initialize-Handshake. Jede Request soll self-contained sein: Protokollversion, Client-Info und Capabilities wandern in Request-_meta (bzw. äquivalente Header-Konventionen); Server-Capabilities holt der Client bei Bedarf über Discovery (z. B. server/discover) statt einmaligem Handshake. Horizontale Deployments brauchen dafür keine sticky Session mehr auf Protokoll-Ebene.

Konsequenz: Code und Gateways, die Session-Header, Reconnect-Semantik oder „Capabilities nur nach Handshake“ hart verdrahten, müssen angepasst werden. Das ist Migrationsaufwand an der Transport-/Client-Schicht, nicht automatisch an eurer Domänen-Tool-Logik.

Was stabil bleibt

• Tools / Resources / Prompts als first-class Primitiven und die Arbeitsteilung model- vs. application- vs. user-controlled (4.7.2).
• Host–Client–Server: Host orchestriert und baut Kontext; Client ist Adapter; Server besitzt Domänenfähigkeit.
• JSON-RPC als Message-Grundlage und die Capability-Idee (was angeboten wird, wird verhandelt bzw. deklariert – nur der Ort der Deklaration ändert sich).
• Harness- und Context-Engineering-Prinzipien: Working Set, Context Policy, Trust Boundaries, Verify-Orakel – unabhängig vom Session-Header.

Kurz: Es ändert sich die Kontaktanordnung am Protokoll (Session/Handshake), nicht die Idee portabler Capabilities – analog zur Stecker-Metapher in 4.7: Geräteklassen und Harness bleiben die haltbarere Schicht.

Wichtige neue Konzepte (knapp)

1. Stateless Requests. Jeder Aufruf trägt, was der Server zur Bearbeitung braucht. Anwendungszustand (Warenkorb, Browser-Session, Agent-Run) ist kein Protokoll-Session-Feld mehr, sondern ein explizites Handle in Tool-Argumenten – sichtbar für Modell und Audit. Das verschiebt State aus der Transport-Metadaten-Ebene in die Capability-Ebene (oft ein Gewinn für Debuggability).

2. Multi Round-Trip Requests (MRTR) / InputRequiredResult. Statt einer dauerhaft offenen SSE-Rückkanal-Session für Server-initiierte Nachfragen (Elicitation u. Ä.) kann der Server mit InputRequiredResult antworten: inputRequests + opaker requestState. Der Client erfüllt die Inputs und wiederholt den Original-Call mit inputResponses und demselben requestState. Jede Server-Instanz kann den Retry bedienen – Voraussetzung für stateless Scale-out.

3. Authorization und Betrieb. Die Revision härtet Authorization in Richtung praxisnaher OAuth/OIDC-Deployments (u. a. Issuer-Validierung, DCR-Klarheit) und verbessert Routing/Caching/Tracing (u. a. methodenbezogene Header, Cache-Hinweise, Trace-Context in _meta). Für Platform-Teams ist das oft der eigentliche ROI der Migration – nicht die Umbenennung einzelner JSON-Felder.

4. Formale Deprecation-Policy. Features wie Roots, Sampling und Logging werden unter Lifecycle-Policy deprecated (mit Mindestfenster, typischerweise 12 Monate), nicht „über Nacht entfernt“. Extensions (z. B. Tasks, MCP Apps) wandern stärker in ein opt-in Extensions-Modell. Für Architekturplanung heißt das: Kern stabilisieren, Zusatzfähigkeit als Extension budgetieren.

Entscheidungshilfe: wann migrieren – wann bleiben

Situation	Empfehlung	Begründung
Viele remote MCP-Server hinter LB/Gateway, Sticky-Session-Schmerz, multi-tenant Scale	Zeitnah planen (Pilot → Staffel)	Stateless ist hier der Plattform-Gewinn
Starke Abhängigkeit von Session-affinem Client-Code, wenig remote Scale	2025-11-25 bewusst behalten, Migrationsfenster nutzen	Aufwand > Nutzen, solange Hosts stabil den Pin sprechen
Primär lokales STDIO, Lab, Companion-Lehre, Single-Host	Pin behalten	Bruch trifft euch spät; Muster aus 4.7/10 bleiben lehrbar
Security/Compliance verlangt aktuelle Auth-Profile und Trace-Korrelation end-to-end	Migration priorisieren (Auth + Observability zuerst)	Weniger Feature-Druck, mehr Kontrollierbarkeit
Ökosystem/Host X spricht nur noch 2026-07-28	Host-getrieben migrieren	Spec folgt dem, was eure Surfaces erzwingen – nicht umgekehrt

Faustregel: Migriert, wenn Gateway-, Auth- oder Scale-Out-Architektur den Session-Bruch ohnehin erzwingen – nicht, weil die Spec-Nummer neuer ist. Bleibt auf 2025-11-25, solange euer Host-Ökosystem und eure Threat Boundaries damit regierbar und supportet sind. [E4]

Bedeutung für Gateway, Auth, Observability, Platform

• Gateway / LB: Weg von Session-Affinity als Protokoll-Notwendigkeit; hin zu routingfähigen Metadaten (Methode/Name), Idempotenz und Retry-Semantik für MRTR.
• Auth: Token- und Issuer-Bindung, DCR und Step-up explizit modellieren; „einmal initialize, dann implizit vertrauen“ ist kein Ersatz für Request-scoped Autorisierung.
• Observability: Trace-Context durch Host → Client → Server durchreichen; requestState-Retries als dieselbe logische Operation korrelieren, nicht als unabhängige Calls.
• Platform-Katalog: Server-Version und unterstützte Spec-Version im Katalog führen (analog Capability-Allowlist); Dual-Stack-Phase budgetieren.
• Harness: Autonomy-Level, Permissions und Working Set ändern sich nicht durch den Spec-Sprung – nur die Client-Adapter-Schicht und ggf. HITL-Pfade (Elicitation via MRTR).

Einordnung in die Haltbarkeits-Matrix

Schicht	Einstufung Übergangsphase 2026/2027	Lesart
Tools / Resources / Prompts, Host–Client–Server, Context/Harness-Prinzipien	Stabil bis relativ stabil	Primärer Buchfokus; bleibt Entscheidungswährung
MCP-Protokollkern (Session, Handshake, Request-Envelope)	Volatil / Übergangsphase	4.8; nicht als „ewiges API“ zitieren
Server-Schnitt, Verify, Skills, Hybrid-KB	Mittelstabil	unberührt vom Session-Bruch
SDK-Syntax, Host-JSON, konkrete Header-Namen	Volatil	Companion + Vendor-Docs

Best Practice: Architektur und Muster lehren wir auf 2025-11-25. Die Revision 2026-07-28 ist ein kontrollierter Errata- und Entscheidungspfad, keine stillschweigende Basisverschiebung. Companion und Config-Beispiele folgen dem Pin, bis eine spätere Auflage oder ein neuer Buch-Tag den Freeze hebt.

Best Practices (Übergang)

1. Spec-Version explizit im Platform-Katalog und in Server-Metadaten führen.
2. Domänen-Tools von Transport-Clients trennen – dann ist der Spec-Sprung ein Adapter-Swap, kein Rewrite der Capability.
3. Anwendungsstate als Handle in Tool-Args designen, auch schon unter 2025-11-25 – erleichtert späteren Stateless-Betrieb.
4. MRTR/HITL im Harness vorsehen (Timeouts, User-Cancel, Audit des requestState), bevor ihr remote scale-out erzwingt.
5. Dual-Stack nur mit klaren Sunset-Daten und Eval-Gates (must_call_tools bleibt orakelstabil).

Pitfalls

Pitfall	Folge	Gegenmaßnahme
„Alles ist obsolet“-Rewrite von Kap. 4.7-Mustern	Verlust der haltbaren Architektur	Primitiven & Harness behalten; nur Client/Gateway anfassen
Session-State still in Server-RAM ohne Handle	Brüche hinter LB	explizite IDs in Tool-Args
Auth nur am Handshake	Lücken bei self-contained Requests	request-/token-scoped Checks
Traces ohne Korrelation über MRTR-Retries	blinde Ops	stabile operation_id + traceparent
Companion und Prod auf unterschiedlicher Spec ohne Katalog	„wirkt lokal, stirbt remote“	Pin dokumentieren (COMPATIBILITY.md)

Migrations-Checkliste (Platform-Teams)

1. Inventar: welche Hosts/SDKs sprechen 2025-11-25 vs. 2026-07-28?
2. Katalog: Spec-Version pro Server + Owner + Sunset-Datum.
3. Gateway: Session-Affinity-Annahmen entfernen; Routing-/Auth-Policies testen.
4. Client-Adapter: Handshake-Pfade isolieren; _meta/Discovery/MRTR vorbereiten.
5. State: impliziten Session-State → explizite Handles in Tool-Args.
6. HITL: Elicitation-Pfade auf InputRequiredResult + Retry-Semantik prüfen.
7. Auth: Issuer-Validierung, DCR, Token-Bindung an Resource/AS verifizieren.
8. Observability: Trace-Context und Retry-Korrelation (eine logische Tool-OP).
9. Evals: Golden Paths und must_call_tools unter Dual-Stack grün halten.
10. Freeze: Prod-Pin dokumentieren; Companion/Lehre erst mit neuem Buch-Tag heben.

Querverweise: 4.7 (Kern 2025-11-25) · 4.7.5 (wann MCP nicht) · Kap. 9 (Host-Config) · Kap. 10 (Companion-Pin) · Kap. 11 (Trust Boundaries) · Anhang D (Matrix & Links).

---

Praxis-Szenario: Von der Issue zum grünen Test

1. Prompt fix_from_issue (MCP) lädt Workflow-Text.
2. Host liest Resource issues://PROJ-442.
3. Agent sucht mit Tool code_search.
4. Liest betroffene Dateien als Resources.
5. Edits via apply_patch.
6. run_unit_tests → fail → refine.
7. tests grün → draft_pr Tool.
8. Memory-Tool schreibt memory://decisions/PROJ-442 (was war die Ursache).

Ohne MCP: dieselben Schritte, aber an drei IDEs und zwei CI-Bot-Varianten jeweils neu verdrahtet.

---

Best Practices

1. Definiere Agenten über Ziel, Stopp-Kriterien, Budget, Escalation – nicht über Modellnamen.
2. Denke Agent = Model + Harness; optimiere den Harness, bevor du das Modell austauschst.
3. Halte den Core-System-Prompt kurz; auslagern in Skills, Rules und MCP.
4. Halte den Loop observation-grounded: keine Erfolgsbehauptung ohne Tool.
5. Ein MCP-Server = eine klare Domäne (Git, Issues, Memory) – keine God-Server.
6. Bevorzuge Resources zum Lesen, Tools zum Wirken und Prüfen.
7. Mappe MCP-Tools auf Policy-Klassen: read, write_local, write_remote, destructive.
8. Trace jeden Schritt mit stable IDs (goal_id, step, server, tool).

---

Pitfalls

Pitfall	Folge	Gegenmaßnahme	Kapitel-Querverweis
Agent ohne Stopp-Kriterium	Token-Brand, Chaos-Commits	max_steps + objektive Checks	Kap. 4
Monolith-System-Prompt	Context Rot, Kosten, Widersprüche	Core + Skills + Policies	Kap. 4
„Modell ist schuld“ bei Harness-Lücken	falsche Optimierung	Verification, Permissions, Context	Kap. 4
Ein shell-Tool für alles	Security + Undebuggability	enge Tools	Kap. 4
Alle Server-Tools immer injizieren	Context-Bloat, falsche Calls	Just-in-Time Toolsets	Kap. 4
Resources nie aktualisieren	veralteter Kontext	revisionierte URIs, invalidation	Kap. 4
Host-Logik in Server hardcoden	Portabilität weg	Server domänenrein, Host orchestriert	Kap. 4
Multi-Agent ohne Shared Contracts	Widersprüche	Kap. 5.10 / 8; Memory als Source of Truth	Kap. 4

---

Key Takeaways

• 4.0: Capability-Ort wählen – Host-first, MCP-first, Framework-orchestrated oder Custom-Harness (Default: Hybrid).
• Agenten verfolgen Ziele in Perceive–Reason–Act-Schleifen mit State und Stopp-Kriterien.
• Agent = Model + Harness (kanonisch hier): Loop, Tools, Context, Permissions, Verify, UX; Engineering-Disziplin in 5.11, Production in 11.10.
• System Prompts bleiben die Verfassung – Skills und MCP tragen Details.
• MCP standardisiert portable Capabilities: Host – Client – Server; Tools / Resources / Prompts first-class (USB-C-Analogie einmal in 4.7 – Anschluss, nicht Intelligenz).
• 4.7.5: MCP bewusst ablehnen, wo UX-Latenz, Single-Host-Schuld oder Agent-Orchestrierung das eigentliche Problem ist.
• 4.8: 2026-07-28 ändert Session/Request-Envelope; Primitiven und Harness bleiben die haltbarere Schicht – Pin 2025-11-25, Migration bewusst.
• Portable Capabilities + versionierte Rules/Skills entkoppeln euch vom einzelnen Host – nicht vom Threat Model.

---

Was als Nächstes kommt

Kapitel 5 vertieft fortgeschrittene Architekturen: Skills und Progressive Disclosure, Harness Engineering, hierarchische Agenten, Context-Aware MCP (CA-MCP), Shared Context Stores, Memory, Multi-Agenten-Koordination und die Verwaltung von Projekt-Informationen (AGENTS.md, Knowledge Graph, Hybrid, Context-Lifecycle).

---

Übungsanregungen

1. Aufgabe: Formuliere für euren häufigsten Dev-Task Ziel, Perceive-Quellen, erlaubte Tools, Stopp-Kriterien. Zeit: ~25 Min · DoD: ☐ Stopp-Kriterien objektiv ☐ mind. 1 Verify-Tool

2. Aufgabe: Zeichne euren Stack als Model + Harness + MCP und markiere Lücken. Zeit: ~20 Min · DoD: ☐ Diagramm ☐ 3 Lücken priorisiert

3. Aufgabe: Kürze Rules auf Core (< ~50 Zeilen); liste Skills-Kandidaten. Zeit: ~30 Min · DoD: ☐ Core-Datei ☐ Skill-Liste mit Namen

4. Aufgabe: Vergleiche zwei Harnesses (Tabelle 4.5.4). Zeit: ~20 Min · DoD: ☐ Use-Case-Match, kein Feature-Bingo

5. Aufgabe: 5 Resource-URIs + 5 Tools für billing (siehe Demo DEMO-1). Bezug: code/05-coding-agent/demo_workspace · DoD: ☐ URI-Schema konsistent ☐ Least Privilege

6. Aufgabe: Begründe eine Integration, bei der MCP nicht erste Wahl ist (4.7.5). DoD: ☐ Situation + Alternative in 5 Sätzen