12 Factor Agents – 12 Prinzipien für den Aufbau zuverlässiger LLM-Anwendungen

Überblick

12 Factor Agents ist eine prinzipienbasierte Methodik für den Aufbau produktionsreifer LLM-gesteuerter Software, entwickelt von Dex Horthy und dem HumanLayer-Team.

Hintergrund und Motivation

Warum diese Prinzipien?

Nach Gesprächen mit über 100 SaaS-Entwicklern (hauptsächlich technischen Gründern) stellten die Autoren fest, dass die meisten AI-Agent-Entwicklungen auf einen „70-80%-Qualitätsengpass“ stoßen:

1. Schneller Anfangsfortschritt: Schnelles Erreichen von 70-80% der Funktionalität mit bestehenden Frameworks
2. Qualitätsengpass: Feststellung, dass 80% für kundenorientierte Funktionen nicht gut genug sind
3. Framework-Einschränkungen: Um die 80% zu überwinden, ist Reverse Engineering von Frameworks, Prompts, Prozessen usw. erforderlich
4. Neuanfang: Letztendlich muss das Framework verworfen und von Grund auf neu begonnen werden

Kernerkenntnisse

• Die meisten erfolgreichen „AI Agents“ auf Produktionsebene sind tatsächlich nicht so „agentenhaft“
• Es handelt sich hauptsächlich um sorgfältig entwickelte Softwaresysteme, die LLMs an entscheidenden Stellen geschickt einsetzen
• Der schnellste Weg, Kunden hochwertige KI-Software zur Verfügung zu stellen, besteht darin, kleine, modulare Konzepte zu übernehmen und diese in bestehende Produkte zu integrieren

12 Kernprinzipien

Faktor 1: Natürliche Sprache zu Tool-Aufrufen

Natürliche Sprache in Tool-Aufrufe umwandeln

Die Kern-Superkraft von LLMs ist die Umwandlung natürlicher Sprache in strukturierte Daten (JSON). Jede Agent-Operation sollte mit dieser grundlegenden Umwandlung beginnen.

// Kernmuster
const response = await llm.generateToolCall(userMessage, availableTools);
// response ist strukturiertes JSON, kein Freitext

Faktor 2: Eigene Prompts verwalten

Eigene Prompts verwalten

Betrachten Sie Prompts als kritische, versionskontrollierte Code-Assets und nicht als einmalige Eingaben.

• Prompts im Anwendungscode verwalten
• Systematisches Testen, Bereitstellen und Zurücksetzen unterstützen
• Konsistenz, Reproduzierbarkeit und kontrollierte Weiterentwicklung gewährleisten

Faktor 3: Eigenes Kontextfenster verwalten

Eigenes Kontextfenster verwalten

Das Kontextfenster des LLM proaktiv und bewusst verwalten.

• Sicherstellen, dass das Kontextfenster nur Informationen enthält, die direkt mit der aktuellen Aufgabe zusammenhängen
• Unnötige Daten kürzen, um „Kontextdrift“ zu verhindern
• LLM-Leistung verbessern, Token-Nutzung reduzieren

Faktor 4: Tools sind nur strukturierte Ausgaben

Tools sind nur strukturierte Ausgaben

„Tools“ als strukturierte JSON-Ausgaben des LLM betrachten und validieren.

// Tool-Aufrufe sind nur JSON-Schema-Validierung
const toolCall = validateToolCall(llmOutput, toolSchema);
const result = await executeValidatedTool(toolCall);

Faktor 5: Ausführungszustand und Geschäftszustand vereinheitlichen

Ausführungszustand und Geschäftszustand vereinheitlichen

Sicherstellen, dass der interne „Ausführungszustand“ des LLM mit dem tatsächlichen „Geschäftszustand“ der Anwendung übereinstimmt.

• Verhindern, dass das LLM auf veralteten oder falschen Informationen basiert
• Halluzinationen oder ungültige Operationen vermeiden
• Ausführungszustand neben dem Geschäftszustand persistieren

Faktor 6: Starten/Pausieren/Fortsetzen mit einfachen APIs

Starten/Pausieren/Fortsetzen über einfache APIs

LLM-Agenten mit klaren Programmierschnittstellen entwerfen, die das Lebenszyklusmanagement unterstützen.

interface AgentControl {
  launch(config: AgentConfig): Promise<AgentInstance>;
  pause(instanceId: string): Promise<void>;
  resume(instanceId: string): Promise<void>;
}

Faktor 7: Menschen über Tool-Aufrufe kontaktieren

Menschen über Tool-Aufrufe kontaktieren

Menschliche Interaktionen als erstklassige Tool-Aufrufe behandeln.

• Schritte mit hohem Risiko zur menschlichen Überprüfung weiterleiten
• Menschliches Feedback als strukturierte Eingabe an das System zurückgeben
• Nahtlose Mensch-Maschine-Kollaborationsprozesse

Faktor 8: Eigenen Kontrollfluss verwalten

Eigenen Kontrollfluss verwalten

Den Kontrollfluss im regulären Code oder in einer eigenen Workflow-Engine halten.

• Explizite OODA-Schleifen (Observe-Orient-Decide-Act) ausführen
• Konvergente Heuristiken anstelle von verschachtelten Prompts verwenden
• Vermeiden, dass das LLM komplexe Kontrollflüsse verwaltet

Faktor 9: Fehler in das Kontextfenster komprimieren

Fehler in das Kontextfenster komprimieren

Fehlerinformationen in den nächsten Prompt komprimieren, um den Feedback-Loop zu schließen.

• Dem LLM ermöglichen, aus Fehlern zu lernen und sich zu erholen
• Strukturierte Fehlerinformationen bereitstellen
• Selbstheilungsfähigkeiten unterstützen

Faktor 10: Kleine, fokussierte Agenten

Kleine und fokussierte Agenten

Kleine, auf einen einzigen Zweck ausgerichtete Agenten bauen, anstatt große, monolithische Chatbots.

// Gute Praxis: Fokussierte kleine Agenten
class EmailSummaryAgent {
  async summarize(email: Email): Promise<Summary> { /* ... */ }
}

class PriorityClassificationAgent {
  async classify(email: Email): Promise<Priority> { /* ... */ }
}

Faktor 11: Von überall aus triggern, Nutzer dort abholen, wo sie sind

Von überall aus triggern, Nutzer dort abholen, wo sie sind

Agenten von dort aus triggern, wo Benutzer bereits arbeiten: CLI, Webhook, Cron usw.

• In bestehende Workflows integrieren
• Mehrere Trigger-Mechanismen
• Benutzerfreundliche Zugangspunkte

Faktor 12: Agenten als zustandslose Reducer gestalten

Agenten als zustandslose Reducer gestalten

Die Anwendung verwaltet den Zustand, der Agent bleibt zustandslos.

// Zustandsloses Agentenmuster
class StatelessAgent {
  step(state: State): Promise<State> {
 
  }
}

Technische Architekturmuster

Vereinfachung des Kern-Loops

Jeder Agent läuft im Wesentlichen auf Folgendes hinaus:

const prompt = "Instructions for next step selection";
const switchFunction = (json) => routeToFunction(json);
const context = manageWhatLLMSees();
const loop = whileNotDone();

Unterschied zu traditionellen DAGs

• Traditioneller DAG: Softwareentwickler kodieren jeden Schritt und jede Randbedingung
• Agent-Ansatz: Dem Agenten ein Ziel und eine Reihe von Transformationen geben, damit das LLM den Pfad in Echtzeit entscheidet
• Praxis: Die erfolgreichsten Implementierungen nutzen das Agent-Muster geschickt innerhalb größerer deterministischer DAGs

Anwendungsfälle

Am besten geeignet für

• Strukturierte Aufgaben, die natürliches Sprachverständnis erfordern
• Workflows, die Mensch-Maschine-Kollaboration erfordern
• Komplexe mehrstufige Geschäftsprozesse
• Produktionsumgebungen, die hohe Zuverlässigkeit erfordern

Nicht geeignet für

• Einfache deterministische Aufgaben (direktes Kodieren ist besser)
• Kritische Aufgaben, die 100%ige Genauigkeit erfordern
• Umgebungen mit extrem begrenzten Ressourcen

Implementierungsempfehlungen

Progressive Einführung

1. Klein anfangen: Ein Prinzip wählen, das zu einer aktuellen Herausforderung passt
2. Implementieren und beobachten: Verbesserungen feststellen
3. Schrittweise hinzufügen: Dann ein weiteres Prinzip hinzufügen
4. Kontinuierliche Optimierung: Ständig verfeinern und anpassen

Empfohlener Tech-Stack

• Sprache: TypeScript (vom Autor empfohlen, unterstützt aber auch andere Sprachen wie Python)
• Schlüsselbibliothek: BAML (für Schema-Alignment-Parsing)
• Bereitstellung: Unterstützt Cloud-native und Kubernetes

Verwandte Ressourcen

Offizielle Ressourcen

• GitHub-Repository
• HumanLayer-Website
• Der Outer Loop Blog

Weiterführende Lektüre

• Building Effective Agents (Anthropic)
• Originale 12 Factor Apps Methodik
• Function Calling vs Structured Outputs vs JSON Mode

Zusammenfassung

12 Factor Agents bietet einen systematischen Ansatz zum Aufbau wirklich produktionsreifer LLM-Anwendungen. Es betont nicht den Aufbau magischerer Frameworks, sondern die Anwendung besserer Software-Engineering-Praktiken auf LLM-Fähigkeiten. Merken Sie sich das Kernkonzept: Agenten sind Software, behandeln Sie sie wie Software, und sie werden Sie mit Zuverlässigkeit, Wartbarkeit und Fähigkeiten belohnen, die Ihre Konkurrenten nicht erreichen können.