CrewAI OpenAI-kompatibler Router: Ein Schlüssel für Multi-Agenten-Workflows

Ein CrewAI OpenAI-kompatibler Router ist nützlich, wenn mehrere CrewAI-Agenten eine Gateway-Grenze verwenden sollen, anstatt Anbieter-Schlüssel, Basis-URLs und Modell-Aliase über jede Rolle im Workflow zu verteilen.

Die aktuelle LLM-Dokumentation von CrewAI zeigt zwei wichtige Einrichtungswege für OpenAI-kompatible Endpunkte: Umgebungsvariablen wie OPENAI_API_BASE und explizite LLM(...)-Attribute wie model, base_url und api_key. Flatkey setzt genau an dieser Grenze an. Seine öffentliche Website verweist OpenAI-kompatible Clients auf https://router.flatkey.ai/v1, mit Nutzungs-, Kosten-, Routing- und Fehlerüberprüfung im Produkt-Dashboard.

Dieser Leitfaden zeigt ein praktisches Muster für einen CrewAI OpenAI-kompatiblen Router für Multi-Agenten-Workflows. Der Code ist eine Vorlage: Validieren Sie die genauen Modell-Aliase, das Werkzeugverhalten und die Protokolle mit Ihrem eigenen Flatkey-Schlüssel, bevor Sie Produktionsagenten routen.

Kurze Antwort für einen CrewAI OpenAI-kompatiblen Router

Verwenden Sie einen Gateway-API-Stamm und explizite Routennamen. Verstecken Sie das Routing nicht im Prompt-Text.

Das ist das Kernmuster eines CrewAI OpenAI-kompatiblen Routers: CrewAI bleibt für die Orchestrierung verantwortlich, Flatkey bleibt für die OpenAI-kompatible Gateway-Grenze verantwortlich, und die betrieblichen Prüfungen werden sichtbar gemacht.

Warum Multi-Agenten-Workflows eine Gateway-Grenze benötigen

CrewAI-Workflows beginnen oft mit einer einfachen Form: ein Manager-Agent, einige spezialisierte Agenten und eine abschließende Aufgabe. Das funktioniert, bis der Workflow von einer Demo zu einem Dienst wird, auf den sich andere Teams verlassen.

Produktionsreife Multi-Agenten-Systeme benötigen in der Regel mehr als nur eine funktionierende Antwort:

Für angrenzende Design-Steuerungen verwenden Sie den Flatkey-Leitfaden zu AI-Agenten-Gateway-Steuerungen. Ein CrewAI OpenAI-kompatibler Router sollte diese Steuerungen für jede Agentenrolle konkretisieren.

Schritt 1: Erstellen der Flatkey-Routenwerte

Erstellen Sie einen Flatkey-Schlüssel für diesen Workload und bewahren Sie die Routenwerte außerhalb der Quellcodeverwaltung auf.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_DEFAULT_MODEL=your-default-flatkey-model-alias
FLATKEY_PLANNER_MODEL=your-planner-model-alias
FLATKEY_TOOL_MODEL=your-tool-capable-model-alias
FLATKEY_VERIFIER_MODEL=your-verifier-model-alias

Halten Sie den API-Stamm vom Endpunktpfad getrennt. Das LLM-Objekt von CrewAI sollte die Basis-URL erhalten. Direkte curl-Tests fügen /chat/completions hinzu.

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_DEFAULT_MODEL"'",
    "messages": [
      { "role": "user", "content": "Antworte mit genau: flatkey route ok" }
    ]
  }'

Wenn diese direkte Anfrage fehlschlägt, korrigieren Sie zuerst den Flatkey-Schlüssel, den Modell-Alias, die Endpunktfamilie oder die Kontoroute. Ein CrewAI OpenAI-kompatibler Router kann einen Modell-Alias nicht kompensieren, den das Gateway-Konto nicht aufrufen kann.

Schritt 2: Explizites Konfigurieren der CrewAI LLM-Objekte

CrewAI unterstützt das Festlegen der Basis-API-URL für ein LLM über base_url, und seine Dokumentation zeigt die Einrichtung von OpenAI-kompatiblen LLMs entweder über Umgebungsvariablen oder LLM-Klassenattribute. Für den produktiven Einsatz sind explizite LLM-Objekte leichter zu überprüfen, da jede Agentenrolle auf eine bekannte Route verweist.

import os

from crewai import Agent, Crew, LLM, Process, Task


BASE_URL = os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1")
API_KEY = os.environ["FLATKEY_API_KEY"]


def flatkey_llm(model_env: str, temperature: float = 0.2) -> LLM:
    return LLM(
        model=os.environ[model_env],
        base_url=BASE_URL,
        api_key=API_KEY,
        temperature=temperature,
    )


planner_llm = flatkey_llm("FLATKEY_PLANNER_MODEL", temperature=0.1)
tool_llm = flatkey_llm("FLATKEY_TOOL_MODEL", temperature=0.0)
verifier_llm = flatkey_llm("FLATKEY_VERIFIER_MODEL", temperature=0.0)

Dies ist die wichtigste Einrichtungsentscheidung bei einer Migration zu einem CrewAI OpenAI-kompatiblen Router. Der Modell-Alias kann je nach Umgebung variieren, aber der CrewAI-Code behält einen OpenAI-kompatiblen API-Root und einen Gateway-Schlüssel-Besitzer bei.

Schritt 3: Routen nach Agentenverantwortung zuweisen

Geben Sie jedem CrewAI-Agenten eine LLM-Route, die seinem Risikoprofil entspricht. Beginnen Sie mit einem kleinen Satz von Routen. Sie können später immer weitere Rollen aufteilen, nachdem Protokolle die Funktionsfähigkeit der ersten Richtlinie belegen.

planner = Agent(
    role="Workflow-Planer",
    goal="Die Anfrage in einen kurzen Ausführungsplan zerlegen.",
    backstory="Du hältst den Umfang der Crew begrenzt und vermeidest unnötige Modellaufrufe.",
    llm=planner_llm,
)

researcher = Agent(
    role="Rechercheur",
    goal="Sammle nur die für die Aufgabe notwendigen Fakten.",
    backstory="Du bevorzugst quellengestützte Notizen gegenüber weitreichenden Spekulationen.",
    llm=planner_llm,
)

tool_user = Agent(
    role="Tool-Bediener",
    goal="Verwende genehmigte Tools nur, wenn die Aufgabe es erfordert.",
    backstory="Du überprüfst die Tool-Eingaben, bevor du externe Systeme aufrufst.",
    llm=tool_llm,
)

verifier = Agent(
    role="Prüfer",
    goal="Überprüfe die endgültige Antwort anhand der Anforderungen und Nachweise.",
    backstory="Du suchst nach fehlenden Nachweisen, Tool-Fehlern und Rollback-Risiken.",
    llm=verifier_llm,
)

Vermeiden Sie bei einem ersten Rollout eines CrewAI OpenAI-kompatiblen Routers, jedem Agenten ein einzigartiges Modell zuzuweisen. Zwei oder drei Routentypen sind in der Regel ausreichend: Planung, werkzeugfähige Ausführung und Überprüfung.

Schritt 4: Eine kleine Crew aufbauen und Nachweisfelder beibehalten

Die Crew kann gewöhnlich bleiben. Der Routing-Nachweis sollte es nicht. Fügen Sie einfache Felder zur Aufgabenbeschreibung, zur Ausgabe oder zu den Protokollen Ihrer umgebenden Anwendung hinzu, damit die Anfrage den Flatkey-Protokollen zugeordnet werden kann.

analysis_task = Task(
    description=(
        "Überprüfen Sie das Support-Ticket und erstellen Sie einen kurzen Lösungsplan. "
        "Rufen Sie keine Tools auf, es sei denn, eine Kontoabfrage ist erforderlich. "
        "Nachweisfelder, die außerhalb dieses Prompts aufbewahrt werden sollen: workflow=crew_support_triage, "
        "route_policy=crewai-router-v1."
    ),
    expected_output="Ein prägnanter Plan mit Risiken, Tool-Bedarf und der nächsten Aktion.",
    agent=planner,
)

verification_task = Task(
    description=(
        "Überprüfen Sie, ob der Plan die Fakten des Tickets zitiert, ungestützte Behauptungen vermeidet "
        "und alle Tool-Aufrufe benennt, die noch genehmigt werden müssen."
    ),
    expected_output="Bestanden/Nicht bestanden-Notizen mit erforderlichen Korrekturen.",
    agent=verifier,
    context=[analysis_task],
)

crew = Crew(
    agents=[planner, researcher, tool_user, verifier],
    tasks=[analysis_task, verification_task],
    process=Process.sequential,
)

result = crew.kickoff(
    inputs={
        "ticket_id": "TICKET-123",
        "request_id": "support-triage-2026-07-08-001",
    }
)
print(result)

Die request_id in dieser Vorlage ist an sich kein CrewAI-Routing-Feature. Es ist eine Gewohnheit für die Beobachtbarkeit (Observability). Ihre App sollte die Anfrage-ID, die Routenrichtlinie, den Modell-Alias, den Zeitstempel und die Schlüsselbezeichnung protokollieren, damit der Pfad des CrewAI OpenAI-kompatiblen Routers in Flatkey überprüft werden kann.

Schritt 5: Tool-Aufrufe vor dem breiten Rollout überprüfen

Die Verwendung von Tools ist der Punkt, an dem OpenAI-kompatibles Routing riskant wird. Eine einfache Chat-Route mag funktionieren, während eine stark auf Tools basierende Route bei der Schema-Validierung fehlschlägt, Tool-Argumente anders streamt oder Argumente erzeugt, die Ihr Executor ablehnt.

Führen Sie einen eng gefassten Tool-Test durch, bevor Sie einer CrewAI-Tool-Route vertrauen. Für ein breiteres Verständnis des Anbieterverhaltens kombinieren Sie diesen Leitfaden mit dem Flatkey-Artikel über OpenAI-kompatible Tool-Aufrufe.

Betrachten Sie dies nicht als optional. Ein CrewAI OpenAI-kompatibler Router ist erst dann produktionsreif, wenn die Tool-Route als separater Vertrag getestet wurde.

Schritt 6: Budget-, Wiederholungs- und Fallback-Regeln außerhalb von Prompts hinzufügen

Bitten Sie die Agenten nicht, sich jede operative Regel in natürlicher Sprache zu merken. Behalten Sie Budget- und Fallback-Regeln in Code oder Konfigurationen bei, die von Prüfern eingesehen werden können.

Wenn ein Fallback genehmigt ist, halten Sie den Fallback-Alias explizit. Die nützliche Frage ist nicht „Hat die Crew ihre Aufgabe beendet?“, sondern „Welche Route wurde abgeschlossen, warum wurde gewechselt und was hat es gekostet?“. Das ist der betriebliche Wert eines CrewAI OpenAI-kompatiblen Routers.

Schritt 7: Ein Verifizierungspaket speichern

Bevor Sie Flatkey zum Standard-Gateway für einen CrewAI-Workflow machen, speichern Sie ein kompaktes Verifizierungspaket.

1. Direkte curl-Anfrage an https://router.flatkey.ai/v1/chat/completions ist mit dem ausgewählten Modell-Alias erfolgreich.
2. Jedes CrewAI LLM-Objekt führt einen kleinen Prompt außerhalb der vollständigen Crew aus.
3. Die vollständige Crew führt einen einfachen Workflow und einen tool-intensiven Workflow aus.
4. Ein erzwungener Fehlerpfad wird sauber beendet, anstatt unendlich oft wiederholt zu werden.
5. Flatkey-Protokolle zeigen den erwarteten Schlüssel, Modell-Alias, Zeitstempel und Anforderungsbesitzer an.
6. Token- oder Nutzungsfelder sind für den Budgetverantwortlichen ausreichend sichtbar, um sie zu überprüfen.
7. Ein Rollback ist eine Umgebungs- oder Konfigurationsänderung, kein CrewAI-Refactoring.

Verwenden Sie den Leitfaden zum Flatkey-Token-Nutzungs-Dashboard, um zu entscheiden, welche Felder Ihr Betriebsteam nach dem ersten Smoke-Test überprüfen sollte. Für die Preis- und Kontenüberprüfung beginnen Sie auf der live Flatkey-Preisseite und überprüfen dann die tatsächliche Route in Ihrem Konto.

Fehlerbehebung bei einem CrewAI OpenAI-kompatiblen Router

Wenn die erste Anfrage fehlschlägt, halten Sie die Debugging-Oberfläche klein: ein Schlüssel, eine Basis-URL, ein Modell-Alias, ein CrewAI LLM, eine direkte Anfrage und eine Flatkey-Protokollabfrage.

FAQ

Ist ein CrewAI OpenAI-kompatibler Router dasselbe wie ein Modell-Fallback?

Nein. Ein CrewAI OpenAI-kompatibler Router ist das Gateway und die Konfigurationsgrenze, die CrewAI verwendet, um Modellrouten zu erreichen. Fallback ist eine Richtlinie, die ausgeführt werden kann, wenn eine gewählte Route fehlschlägt. Testen Sie Routing und Fallback separat.

Sollte jeder CrewAI-Agent ein anderes Modell erhalten?

Nein. Beginnen Sie mit einer Standardroute und bei Bedarf einer speziellen Route für tool-intensive oder verifizierende Aufgaben. Zu viele Aliase erschweren Protokolle, Kostenüberprüfungen und Rollbacks.

Kann CrewAI Umgebungsvariablen anstelle von expliziten LLM-Objekten verwenden?

Ja. Die CrewAI-Dokumentation zeigt die OpenAI-kompatible Einrichtung über Umgebungsvariablen wie OPENAI_API_BASE. Explizite LLM-Objekte sind oft einfacher für die Produktionsüberprüfung, da jede Agentenrolle model, base_url und api_key an einem Ort anzeigt.

Kann ich denselben Flatkey-Schlüssel für jeden CrewAI-Workflow verwenden?

Sie können das, aber workload-spezifische Schlüssel sind einfacher zu prüfen. Verwenden Sie separate Schlüssel oder Bezeichnungen, wenn verschiedene Teams, Umgebungen, Budgets oder Risikostufen eine separate Überprüfung erfordern.

Abschließende Checkliste

Ihre Einrichtung des CrewAI OpenAI-kompatiblen Routers ist bereit, über eine Vorlage hinauszugehen, wenn:

1. CrewAI LLM-Objekte verwenden den Flatkey-API-Stamm als base_url.
2. Modell-Aliase befinden sich in der Umgebung oder Konfiguration, nicht verstreut in den Prompts.
3. Jede Agentenrolle hat eine beabsichtigte Routenentscheidung.
4. Tool-intensive Routen bestehen Schema-, Argument-, Obergrenzen- und Fehlertests.
5. Budget-, Wiederholungs- und Fallback-Limits werden außerhalb der Agentenprosa ausgeführt.
6. Flatkey-Nutzungs- oder Anforderungsprotokolle bestätigen den erwarteten Schlüssel und Modell-Alias.
7. Ein Rollback ist eine einzige Konfigurationsänderung.

Wenn Sie bereit sind, den CrewAI-Traffic über ein Gateway zu leiten, holen Sie sich einen Flatkey-Schlüssel, testen Sie eine Crew mit geringem Risiko und erweitern Sie erst, nachdem die Protokolle beweisen, dass die Richtlinie funktioniert.