Der 12-Faktoren-AI-Agent: Effektive, skalierbare AI-Systeme bauen

Was macht einen effektiven AI-Agenten aus?

Bevor wir auf die Faktoren eingehen, wollen wir klären, was wir unter „AI-Agenten“ verstehen. Im Kern sind dies Systeme, die natürliche Sprachbefehle interpretieren, kontextbasiert Entscheidungen treffen und konkrete Aktionen über Tools oder APIs ausführen – und dabei konsistente, fortlaufende Interaktionen aufrechterhalten.

Die leistungsfähigsten Agenten verbinden die Argumentationsfähigkeiten von Sprachmodellen mit der Zuverlässigkeit deterministischen Codes. Dieses Gleichgewicht zu erreichen, erfordert jedoch durchdachtes Design – und genau darauf zielen diese Faktoren ab.

Die 12 Faktoren für den Bau robuster AI-Agenten

1. Beherrsche die Umwandlung natürlicher Sprache in Tool-Aufrufe

Die Fähigkeit, natürliche Sprachbefehle in strukturierte Tool-Aufrufe umzuwandeln, steht im Zentrum der Agentenfunktionalität. Das ermöglicht es einem Agenten, einen einfachen Befehl wie „Erstelle einen Zahlungslink für 750 $ an Terri für das Februar AI Tinkerers Meetup“ in einen korrekt formatierten API-Aufruf zu übersetzen.

Image URL

{
  "function": {
    "name": "create_payment_link",
    "parameters": {
      "amount": 750,
      "customer": "cust_128934ddasf9",
      "product": "prod_8675309",
      "price": "prc_09874329fds",
      "quantity": 1,
      "memo": "Hey Jeff - see below for the payment link for the February AI Tinkerers meetup"
    }
  }
}

Der Schlüssel für zuverlässige Funktion ist der Einsatz von deterministischem Code, um die strukturierten Ausgaben des Sprachmodells zu verarbeiten. Überprüfen Sie immer die API-Payloads vor der Ausführung, um Fehler zu vermeiden, und stellen Sie sicher, dass Ihr LLM konsistente JSON-Formate liefert, die zuverlässig geparst werden können.

2. Übernimm die vollständige Kontrolle über deine Prompts

Ihre Prompts sind die Schnittstelle zwischen Ihrer Anwendung und dem Sprachmodell – behandeln Sie sie als erstklassigen Code. Frameworks, die Prompts abstrahieren, wirken vielleicht bequem, verschleiern aber oft, wie Anweisungen an das LLM übergeben werden, was Feinabstimmungen erschwert oder unmöglich macht.

Stattdessen sollten Sie die Prompts explizit selbst schreiben:

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
  prompt #"
    {{ _.role("system") }}
    You are a helpful assistant that manages deployments for frontend and backend systems.
    ...
    {{ _.role("user") }}
    {{ thread }}
    What should the next step be?
  "#
}

Diese Vorgehensweise bietet Ihnen mehrere Vorteile:

• Volle Kontrolle, um präzise Anweisungen für Ihren speziellen Anwendungsfall zu schreiben
• Möglichkeit, Prompts wie jeden anderen Code zu testen und zu bewerten
• Transparenz darüber, was das LLM tatsächlich erhält
• Freiheit, basierend auf Leistungsmetriken zu iterieren

3. Gestalte das Kontextfenster strategisch

Das Kontextfenster dient als Input für das LLM und umfasst Prompts, Gesprächshistorie und externe Daten. Die Optimierung dieses Fensters erhöht die Performance und Token-Effizienz.

Image URL

Gehen Sie über Standard-Message-Formate hinaus und nutzen Sie eigene Strukturen, die die Informationsdichte maximieren:

<slack_message>
    From: @alex
    Channel: #deployments
    Text: Can you deploy the backend?
</slack_message>
<list_git_tags>
    intent: "list_git_tags"
</list_git_tags>
<list_git_tags_result>
    tags:
      - name: "v1.2.3"
        commit: "abc123"
        date: "2024-03-15T10:00:00Z"
</list_git_tags_result>

Das bringt mehrere Vorteile:

• Geringerer Tokenverbrauch durch kompakte Formate
• Bessere Filterung sensibler Daten vor Weitergabe an das LLM
• Flexibilität, mit Formaten zu experimentieren, die das LLM-Verständnis verbessern

4. Implementiere Tools als strukturierte Ausgaben

Im Kern sind Tools einfach JSON-Ausgaben des LLM, die in Ihrem Code deterministische Aktionen auslösen. Dadurch entsteht eine saubere Trennung zwischen AI-Entscheidung und Ausführung.

Definieren Sie Tool-Schemata klar:

class CreateIssue {
  intent: "create_issue";
  issue: {
    title: string;
    description: string;
    team_id: string;
    assignee_id: string;
  };
}

class SearchIssues {
  intent: "search_issues";
  query: string;
  what_youre_looking_for: string;
}

Bauen Sie anschließend zuverlässiges Parsen für LLM-JSON-Ausgaben, führen Sie die Aktionen deterministisch aus und geben Sie die Ergebnisse zur iterativen Verarbeitung in den Kontext zurück.

5. Vereinige Ausführungs- und Geschäftsstatus

Viele Agenten-Frameworks trennen Ausführungsstatus (z.B. aktueller Schritt im Prozess) vom Geschäftsstatus (z.B. Historie der Tool-Aufrufe und deren Ergebnisse). Diese Trennung sorgt für unnötige Komplexität.

Speichern Sie stattdessen den gesamten Status direkt im Kontextfenster und leiten Sie den Ausführungsstatus aus der Ereignisabfolge ab:

<deploy_backend>
    intent: "deploy_backend"
    tag: "v1.2.3"
    environment: "production"
</deploy_backend>
<error>
    error running deploy_backend: Failed to connect to deployment service
</error>

Dieser einheitliche Ansatz bietet:

• Einfachheit durch eine einzige Quelle für den Status
• Besseres Debugging durch vollständige Historie an einem Ort
• Leichte Wiederaufnahme, indem jeder Thread geladen werden kann

AI-Agenten produktionsreif machen

6. API-Design für Start, Pause und Fortsetzung

Produktionsreife Agenten müssen sich nahtlos in externe Systeme integrieren, bei langlaufenden Aufgaben pausieren und durch Webhooks oder andere Events fortgesetzt werden können.

Setzen Sie APIs um, die das Starten, Pausieren und Fortsetzen von Agenten ermöglichen und speichern Sie den Status robust zwischen den Vorgängen. So erreichen Sie:

• Flexible Unterstützung asynchroner Workflows
• Saubere Integration mit Webhooks und anderen Systemen
• Zuverlässige Wiederaufnahme nach Unterbrechungen ohne Neustart

7. Ermögliche Mensch-KI-Zusammenarbeit über Tool-Aufrufe

AI-Agenten benötigen häufig menschlichen Input bei kritischen Entscheidungen oder Unklarheiten. Strukturierte Tool-Aufrufe machen diese Interaktion nahtlos:

class RequestHumanInput {  
  intent: "request_human_input";  
  question: string;  
  context: string;  
  options: {  
    urgency: "low" | "medium" | "high";  
    format: "free_text" | "yes_no" | "multiple_choice";  
    choices: string[];  
  };  
}

Image URL

Dieser Ansatz bietet eine klare Spezifikation von Interaktionstyp und Dringlichkeit, unterstützt Input mehrerer Nutzer und lässt sich gut mit APIs für dauerhafte Workflows kombinieren.

8. Steuere den Ablauf deines Agenten

Eigene Ablaufsteuerung ermöglicht es, für menschliche Freigabe zu pausieren, Ergebnisse zu cachen oder Ratenbegrenzungen umzusetzen – und so das Verhalten des Agenten individuell anzupassen:

Image URL

async function handleNextStep(thread: Thread) {
  while (true) {
    const nextStep = await determineNextStep(threadToPrompt(thread));
    if (nextStep.intent === 'request_clarification') {
      await sendMessageToHuman(nextStep);
      await db.saveThread(thread);
      break;
    } else if (nextStep.intent === 'fetch_open_issues') {
      const issues = await linearClient.issues();
      thread.events.push({ type: 'fetch_open_issues_result', data: issues });
      continue;
    }
  }
}

Damit profitieren Sie von:

• Unterbrechbarkeit, um vor kritischen Aktionen menschliche Überprüfung zu ermöglichen
• Anpassungsmöglichkeiten für Logging, Caching oder Zusammenfassungen
• Zuverlässiger Bearbeitung langlaufender Aufgaben

9. Kompakte Fehler im Kontext für Selbstheilung

Fehler direkt im Kontextfenster zu speichern, ermöglicht es AI-Agenten, aus Fehlern zu lernen und ihr Vorgehen anzupassen:

try {
  const result = await handleNextStep(thread, nextStep);
  thread.events.push({ type: `${nextStep.intent}_result`, data: result });
} catch (e) {
  thread.events.push({ type: 'error', data: formatError(e) });
}

Damit das wirkungsvoll funktioniert:

• Begrenzen Sie Wiederholungen, um Endlosschleifen zu vermeiden
• Eskalieren Sie nach mehrfachen Fehlern an Menschen
• Formatieren Sie Fehler klar verständlich, damit das LLM erkennt, was schiefgelaufen ist

Architekturbest Practices

10. Baue kleine, fokussierte Agenten

Kleine Agenten, die 3–20 Schritte abdecken, behalten überschaubare Kontextfenster und erhöhen die LLM-Leistung und Zuverlässigkeit. Das sorgt für:

• Klarheit durch klar umrissenen Aufgabenbereich je Agent
• Weniger Risiko, dass der Agent den Fokus verliert
• Einfachere Tests und Validierung einzelner Funktionen

Image URL

Mit zunehmender Leistungsfähigkeit von LLMs kann der Umfang dieser kleinen Agenten wachsen, während die Qualität erhalten bleibt – das sichert langfristige Skalierbarkeit.

11. Aktiviere Auslöser aus mehreren Quellen

Stellen Sie Ihre Agenten bereit, indem Sie Auslöser aus Slack, E-Mail oder Event-Systemen ermöglichen – und so Nutzer direkt dort abholen, wo sie arbeiten.

Implementieren Sie APIs, die Agenten aus verschiedenen Kanälen starten und im gleichen Medium antworten lassen. Das führt zu:

• Besserer Zugänglichkeit durch Integration in bevorzugte Nutzerplattformen
• Unterstützung ereignisbasierter Automatisierungs- Workflows
• Menschlichen Freigabe-Workflows für kritische Vorgänge

12. Gestalte Agenten als zustandslose Reducer

Behandeln Sie Agenten als zustandslose Funktionen, die Eingabekontext in Ausgaben umwandeln. Das vereinfacht das Zustandsmanagement und macht sie vorhersehbar und leichter zu debuggen.

Image URL

Dieses Konzept sieht Agenten als pure Funktionen ohne internen Zustand:

• Vorhersehbares Verhalten bei gleichen Eingaben
• Einfachere Nachverfolgung von Problemen durch die Kontexthistorie
• Leichtere Tests und Validierung

Zukunftssicher entwickeln

Das Feld der AI-Agenten entwickelt sich rasant weiter, aber diese Kernprinzipien bleiben auch mit verbesserten Modellen relevant. Indem Sie mit kleinen, fokussierten Agenten starten, die diese Praktiken befolgen, schaffen Sie Systeme, die heute Wert liefern und sich an zukünftige Fortschritte anpassen.

Denken Sie daran: Die effektivsten AI-Agenten verbinden die Argumentationsfähigkeiten von Sprachmodellen mit der Zuverlässigkeit von deterministischem Code – und diese 12 Faktoren helfen, dieses Gleichgewicht herzustellen.

Wie FlowHunt die 12-Faktoren-Methodik angewendet hat

Bei FlowHunt haben wir diese Prinzipien umgesetzt und einen eigenen AI-Agenten entwickelt, der automatisch Workflow-Automatisierungen für unsere Kunden erstellt. So haben wir die 12-Faktoren-Methodik angewendet, um ein zuverlässiges, produktionsreifes System zu bauen