Praktische Hinweise: Harness Engineering: Der „Naked Agent“ – Warum Ihr Framework hilft

Nutzen Sie dies als für Operator zugängliche Neuformulierung der Ideen aus „Harness Engineering: The Naked Agent: Why Your Framework Hands You a Loop, Not a Harness — I“: klare Phasen, geordnete Codeblöcke sowie Wiederherstellungshinweise, die auch bei Übergaben erhalten bleiben.

Teil 1: Ein reiner Agentenloop wirkt mächtig – bis echter Traffic darauf trifft. Hier ist der Grund, warum Produktionsfehler in der Regel auf das fehlende Harness um das Modell zurückzuführen sind und nicht auf das Modell selbst.

In Teil 1 funktioniert eine reine Phase am besten, wenn sie als messbare Ebene behandelt wird. Erfassen Sie vor der Erweiterung des Umfangs ein „goldenes“ Transkript, einen Fehlerfall sowie die Notizen zur Rücksetzung. Dokumentieren Sie gemeinsam den erfolgreichen Ablauf sowie den Wiederherstellungsprozess. Wiederholversuche, menschliche Kontrollen und die Handhabung von Fehlern gehören zum Produkt selbst, nicht zu späteren Optimierungen. Legen Sie Budgets für Tokens pro Turnus und pro Sitzung fest – agierende Tools erweitern den Kontext stark; feste Obergrenzen verhindern, dass Demonstrationen zu unerwarteten Rechnungen werden.

Die meisten Fehler von Agenten liegen nicht am Modell selbst. Sie entstehen durch das fehlende Disziplinierungslevel drumherum. So sieht ein KI-Agent ohne Kontrollmechanismen im Claude Agent SDK und LangChain Deep Agents aus – sowie auf welche drei spezifischen Arten er unter echtem Betriebsdruck versagt.

Die meisten Agentenfehler lassen sich am besten als messbare Phänomene betrachten. Erfassen Sie zunächst ein gutes Beispiel für eine erfolgreiche Ausführung, einen Fehlerfall sowie eine Notiz zur Rücksetzung, bevor Sie den Umfang erweitern. Wählen Sie kleine, testbare Einheiten statt umfangreicher Skripte – so weist ein fehlgeschlagener Schritt auf eine klare Verantwortungsbereichsabgrenzung statt auf ein verworrenes Ablaufschema hin. Legen Sie Budgets für Tokens pro Turnus und pro Sitzung fest; Agentenwerkzeuge erweitern den Kontext oft stark – feste Obergrenzen verhindern, dass Demonstrationen zu unerwarteten Rechnungen werden.

Das Modell ist nicht die Variable

Das Modell funktioniert am besten, wenn es als messbare Oberfläche betrachtet wird. Erfassen Sie vor Erweiterung des Umfangs ein erfolgreiches Beispiel, einen Fehlfall sowie eine Notiz zur Rücksetzung. Behandeln Sie diese Phase als Vertrag zwischen Eingaben und validierten Ausgaben. Benennen Sie die Erzeugnisse, definieren Sie Erfolgskontrollen und lehnen Sie stille, unvollständige Abschlüsse ab. Legen Sie Budgetgrenzen pro Turnus und pro Sitzung fest. Agierende Tools erweitern den Kontext oft übermäßig; feste Obergrenzen verhindern, dass Demonstrationen zu unerwarteten Rechnungen werden.

Was „nackt“ tatsächlich bedeutet

Der Begriff „nackt“ bezieht sich auf die Stufe, die am besten als messbare Oberfläche betrachtet werden kann. Erfassen Sie einen erfolgreichen Fall, einen Fehlerfall sowie die Rollback-Anmerkung, bevor Sie den Umfang erweitern. Notieren Sie außerdem die Laufzeiten sowie die Kosten für Tokens oder Abfragen neben den funktionalen Ergebnissen. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn sich der Einsatzbereich von einer Demo auf gemeinsam genutzte Umgebungen verschiebt. Stellen Sie Tools mit engen Schemata sowie klaren Kennzeichnungen für Nebeneffekte bereit. Die Hosts müssen wissen, welche Aufrufe den Zustand verändern, bevor sie automatisch zustimmen.

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
TOOLS = [
    {"name": "search_flights",
     "description": "Search flights between two cities for a date.",
     "input_schema": {"type": "object", "properties": {
         "origin": {"type": "string"}, "destination": {"type": "string"},
         "date": {"type": "string", "description": "YYYY-MM-DD"}},
         "required": ["origin", "destination", "date"]}},
    {"name": "book_flight",
     "description": "Book a specific flight.",
     "input_schema": {"type": "object", "properties": {
         "flight_id": {"type": "string"}, "passenger_name": {"type": "string"}},
         "required": ["flight_id", "passenger_name"]}},
]
def run_naked(user_msg: str) -> str:
    messages = [{"role": "user", "content": user_msg}]
    while True:                                   # ① no iteration cap
        resp = client.messages.create(
            model="claude-sonnet-4-6", max_tokens=1024,
            tools=TOOLS, messages=messages,
        )
        if resp.stop_reason != "tool_use":
            return resp.content[0].text
        call = next(b for b in resp.content if b.type == "tool_use")
        result = dispatch(call.name, call.input)
                                             # ② direct side effect, no check
        messages.extend([
                                             # ③ whole history, every turn
            {"role": "assistant", "content": resp.content},
            {"role": "user", "content": [{"type": "tool_result",
                "tool_use_id": call.id, "content": result}]},
        ])

Der „nackte“ Agent im Claude Agent SDK

Der „Naked Agent“ im Testumfeld funktioniert am besten, wenn er als messbare Oberfläche betrachtet wird. Erfassen Sie ein „goldenes Transkript“, einen Fehlerfall sowie eine Rollback-Anmerkung, bevor Sie den Umfang erweitern. Bewahren Sie Konfigurationen außerhalb des Anwendungscode auf. Umgebungsdateien, Geheimdatenspeicher und Feature-Flags sollten an einem Ort gesammelt sein, den Betreuer ohne Durchsicht des gesamten Systems prüfen können. Stellen Sie Tools mit eng definierten Schemata sowie klaren Kennzeichnungen für Nebeneffekte bereit. Die Hosts müssen wissen, welche Aufrufe den Zustand verändern, bevor sie automatisch zustimmen. Der „Naked Agent“ im Testumfeld funktioniert am besten, wenn er als messbare Oberfläche betrachtet wird. Erfassen Sie ein „goldenes Transkript“, einen Fehlerfall sowie eine Rollback-Anmerkung, bevor Sie den Umfang erweitern. Ziehen Sie kleine, testbare Einheiten vor großen, komplexen Skripten vor. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf einen verworrenen Ablauf.

import asyncio
from claude_agent_sdk import (
    query, ClaudeAgentOptions, tool,
    create_sdk_mcp_server, AssistantMessage, ResultMessage,
)

@tool("search_flights", "Search flights between two cities for a date.",
      {"origin": str, "destination": str, "date": str})
async def search_flights(args):
                                              # ① no check that date exists
    hits = flights_api.search(**args)
    return {"content": [{"type": "text", "text": str(hits)}]}
@tool("book_flight", "Book a specific flight.",
      {"flight_id": str, "passenger_name": str})
async def book_flight(args):
                                               # ② destructive, ungated
    confirmation = flights_api.book(**args)
    return {"content": [{"type": "text", "text": confirmation}]}
server = create_sdk_mcp_server("travel", tools=[search_flights, book_flight])
async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"travel": server},
        allowed_tools=["mcp__travel__search_flights",
                       "mcp__travel__book_flight"],
    )
    async for msg in query(prompt="Rebook this customer for March 32nd.",
                           options=options):
        if isinstance(msg, AssistantMessage):
            for b in msg.content:
                if hasattr(b, "text"):
                    print(b.text)
        elif isinstance(msg, ResultMessage):
            print("done:", msg.subtype)
                                              # ③ no state survives this run

Der „Naked Agent“ in LangChain Deep Agents

Für den „The naked agent in stage“ sollten die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien vor dem Ändern des Codes definiert werden. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Betrachten Sie diese Phase als Vertrag zwischen den Eingaben und den validierten Ausgaben. Benennen Sie die Artefakte, definieren Sie Erfolgskontrollen und lehnen Sie stille, unvollständige Abschlüsse ab. Authentifizieren Sie am Gateway und erteilen Sie erneut Berechtigungen auf der Datenebene. Ein alleiniges Trägertoken stellt keine Trennlinie zwischen Berechtigungsgebieten dar.

from langchain.tools import tool
from deepagents import create_deep_agent

@tool
def search_flights(origin: str, destination: str, date: str) -> str:
    """Search flights between two cities for a date (YYYY-MM-DD)."""
    return str(flights_api.search(origin, destination, date))
                                                # ① no date check
@tool
def book_flight(flight_id: str, passenger_name: str) -> str:
    """Book a specific flight."""
    return flights_api.book(flight_id, passenger_name)
                                                 # ② ungated side effect
agent = create_deep_agent(
                                                 # ③ the loop, no controls
    model="anthropic:claude-sonnet-4-6",
    tools=[search_flights, book_flight],
)
result = agent.invoke({"messages": [{"role": "user",
    "content": "Rebook this customer for March 32nd."}]})
print(result["messages"][-1].content)
# Ask a follow-up in a second invoke, and it starts from zero: no thread,
# no memory.

Beobachten Sie, wie es auf drei Arten versagt

Für das Überwachen des Ablaufs sollte man in drei Schritten vorgehen: Zunächst die Eingabedaten, danach den Verantwortlichen für jeweiligen Schritt sowie schließlich die Abbruchkriterien definieren, bevor der Code geändert wird. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Neben den funktionalen Ergebnissen sollten auch die Ausführungsdauer sowie die Kosten für Token oder Abfragen aufgezeichnet werden. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn der Ablauf von einer Demo-Umgebung in eine gemeinsam genutzte Umgebung wechselt. Die Authentifizierung sollte am Gateway erfolgen, während die erneute Autorisierung auf der Datenebene stattfindet. Ein alleiniges Trägertoken stellt keine Grenze zwischen verschiedenen Nutzergruppen dar.

Fehler 1: Ein fehlerhaft formatierter Parameter erreicht eine zerstörerische Aufruffunktion

Für den Fehler „Fehler 1: fehlerhaftes Stadium“ sollten die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien vor dem Codeändern definiert werden. Die Betreiber sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Die Konfiguration sollte außerhalb des Anwendungscode gespeichert werden. Umgebungsdateien, Geheimdatenspeicher und Feature-Flags sollten an einem Ort zusammengefasst sein, den die Betreiber überprüfen können, ohne den gesamten Ablauf durchzulesen. Authentifizieren Sie sich am Gateway und erteilen Sie erneut Berechtigungen auf der Datenebene. Ein alleinigesBearer-Token stellt keine Trennlinie zwischen verschiedenen Bereichen dar. Für den Fehler „Fehler 1: fehlerhaftes Stadium“ sollten die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien vor dem Codeändern definiert werden. Die Betreiber sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Ziehen Sie kleine, testbare Einheiten vor großen, komplexen Skripten. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf einen verworrenen Ablauf.

book_flight(flight_id=”AC-PHANTOM”, passenger_name=”J. Moffatt”)
# -> “Booked.” The action fired. Nothing in the loop asked whether it should.

Fehler 2: Der Kontext kollabiert und die Qualität verschlechtert sich unbemerkt

Wenn Sie mit dem Stadium „Kontext kollabiert“ beim Fehler 2 arbeiten, notieren Sie zunächst den Vertrag: erforderliche Eingaben, Erfolgsignal sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Betrachten Sie dieses Stadium als Vertrag zwischen Eingaben und validierten Ausgaben. Benennen Sie die Artefakte, definieren Sie Erfolgsprüfungen und lehnen Sie stille, teilweise abgeschlossene Abläufe ab. Protokollieren Sie den Namen der Tool, den Hash der Argumente, die Latenz sowie das Ergebnis jeder Aufruf. Ohne diese Aufzeichnungen verschwenden Debugging-Agenten Stunden mit sinnlosem Herumprobieren.

Fehler 3: Ein Tool fehlschlägt, der Agent meldet Erfolg

Wenn Sie die Fehlerbehandlung für Phase 3 eines Tools durchgehen, notieren Sie zunächst den Vertrag: erforderliche Eingaben, Erfolgsignal sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Tragen Sie die Laufzeiten sowie die Kosten für Tokens oder Abfragen neben den funktionalen Ergebnissen ein. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn der Weg von einer Demo-Umgebung in gemeinsam genutzte Umgebungen wechselt. Protokollieren Sie für jeden Aufruf den Namen des Tools, den Hash der Argumente, die Latenzzeit sowie das Ergebnis. Ohne diese Aufzeichnungen verschwenden Debugging-Agenten Stunden mit sinnlosem Herumprobieren.

Die Struktur, der jede Komponente folgen muss

Beim Bearbeiten der Phase „The shape every part“ sollten Sie zunächst den Vertrag aufschreiben: erforderliche Eingaben, Erfolgsignal sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Bewahren Sie die Konfiguration außerhalb des Anwendungscode auf. Umgebungsdateien, Geheimdatenspeicher und Feature-Flags sollten an einem Ort gesammelt sein, den Betreuer ohne das Durchlesen des gesamten Systems überprüfen können. Protokollieren Sie für jeden Aufruf den Namen des Tools, den Hash der Argumente, die Latenzzeit sowie das Ergebnis. Ohne diese Aufzeichnungen verschwenden Debugging-Agenten Stunden damit, im Kreis zu laufen. Beim Bearbeiten der Phase „The shape every part“ sollten Sie zunächst den Vertrag aufschreiben: erforderliche Eingaben, Erfolgssignal sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Ziehen Sie kleine, testbare Einheiten vor großen, komplexen Skripten. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf ein verworrenes Ablaufschema.

Machen Sie das noch heute

Die Phase „Machen Sie das heute“ funktioniert am besten, wenn sie als messbarer Rahmen betrachtet wird. Erfassen Sie ein gelungenes Beispiel, einen Fehlfall sowie eine Notiz zur Rücksetzung, bevor Sie den Umfang erweitern. Betrachten Sie diese Phase als Vertrag zwischen Eingaben und validierten Ausgaben. Benennen Sie die Ergebnisdokumente, definieren Sie Erfolgskontrollen und lehnen Sie stille, unvollständige Abschlüsse ab. Stellen Sie Tools mit engen Schemata sowie klaren Angaben zu Nebeneffekten bereit. Die Hosts müssen wissen, welche Aufrufe den Zustand verändern, bevor sie automatisch zustimmen.

Das Modell ist der einfachere Teil

Das Modell funktioniert am besten, wenn es als messbare Oberfläche betrachtet wird. Erfassen Sie vor Erweiterung des Umfangs einen erfolgreichen Fall, einen Fehlerfall sowie die Notizen zur Rücksetzung. Erfassen Sie außerdem die Laufzeiten sowie die Kosten für Tokens oder Abfragen neben den funktionalen Ergebnissen. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn der Einsatzbereich von einer Demo in gemeinsame Umgebungen wechselt. Legen Sie Budgets für Tokens pro Turnus und pro Sitzung fest. Agierende Tools erweitern den Kontext stark; feste Obergrenzen verhindern, dass Demos zu überraschenden Rechnungen werden.

Operative Checkliste

Während der Bearbeitung der operativen Checkliste sollten Sie zunächst den Vertrag aufschreiben: erforderliche Eingaben, Signal für Erfolg sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben.

Dokumentieren Sie sowohl den erfolgreichen Ablauf als auch den Wiederherstellungsprozess gemeinsam. Wiederholversuche, menschliche Kontrollen sowie die Handhabung von Fehlern gehören zum Produkt selbst und nicht zu späteren Optimierungen.

Protokollieren Sie den Namen des Tools, den Hash der Argumente, die Latenz sowie das Ergebnis jeder Aufruf. Ohne diese Aufzeichnungen verschwenden Debugging-Agenten Stunden damit, im Kreis zu laufen.

Halten Sie den Zustand des Graphen strukturiert und typisiert. Verschachtelte Datenstrukturen verbergen, welcher Knoten welches Feld geschrieben hat, und führen dazu, dass die Fortsetzung nach Unterbrechungen nicht möglich ist.

Fügen Sie immer dann, wenn das Budget es zulässt, einen Smoke-Test hinzu, der den kritischen Pfad in CI mit Fixtures und nicht mit live genutzten, kostenpflichtigen APIs testet.

Erhalten Sie neben den funktionalen Ergebnissen auch Aufzeichnungen der Laufzeiten sowie der Kosten für Tokens oder Abfragen. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn der Pfad von einer Demo in gemeinsam genutzte Umgebungen wechselt.

Vor der Einführung des gesamten Stacks sollten Sie die Versionen einfrieren, ein „goldenes“ Protokoll des kritischen Pfades anfertigen und die Schritte zum Rollback überprüfen. Gemeinsam genutzte Umgebungen erfordern Rate-Limits, Überprüfungen der Nutzerrechte sowie einen klaren Verantwortlichen für die Rotation von Geheimnissen. Wählen Sie langweilige Zuverlässigkeit statt cleverer, einmaliger Demos.

Batch-Hinweis für 765280e2df21: Halten Sie die Anbieter-Schlüssel außerhalb des Repositories, legen Sie eine Obergrenze für Tokens pro Sitzung fest und speichern Sie die Transkripte neben den Evaluierungs-Dateien, damit spätere Modellwechsel vergleichbar bleiben.