Routeur CrewAI compatible OpenAI : Une seule clé pour les workflows multi-agents

Une configuration de routeur CrewAI compatible OpenAI est utile lorsque vous souhaitez que plusieurs agents CrewAI utilisent une seule passerelle au lieu de disséminer les clés de fournisseur, les URL de base et les alias de modèle dans chaque rôle du workflow.

La documentation LLM actuelle de CrewAI présente deux voies de configuration importantes pour les points de terminaison compatibles OpenAI : les variables d'environnement telles que OPENAI_API_BASE, et les attributs explicites LLM(...) tels que model, base_url et api_key. Flatkey s'intègre à cette frontière. Son site public dirige les clients compatibles OpenAI vers https://router.flatkey.ai/v1, avec un suivi de l'utilisation, des coûts, du routage et des erreurs dans le tableau de bord du produit.

Ce guide présente un modèle pratique de routeur CrewAI compatible OpenAI pour les workflows multi-agents. Le code est un modèle : validez les alias de modèle exacts, le comportement des outils et les journaux avec votre propre clé Flatkey avant de router les agents de production.

Réponse rapide pour un routeur CrewAI compatible OpenAI

Utilisez une seule racine d'API de passerelle et des noms de route explicites. N'enfouissez pas le routage dans le texte du prompt.

C'est le modèle de base du routeur CrewAI compatible OpenAI : laisser CrewAI responsable de l'orchestration, laisser Flatkey responsable de la frontière de la passerelle compatible OpenAI, et rendre les vérifications opérationnelles visibles.

Pourquoi les workflows multi-agents ont besoin d'une frontière de passerelle

Les workflows CrewAI commencent souvent par une forme simple : un agent gestionnaire, quelques agents spécialistes et une tâche finale. Cela fonctionne jusqu'à ce que le workflow passe d'une démo à un service sur lequel d'autres équipes comptent.

Les systèmes multi-agents en production ont généralement besoin de plus qu'une simple réponse fonctionnelle :

Pour des contrôles de conception adjacents, utilisez le guide Flatkey sur les contrôles de passerelle pour agents IA. Un routeur CrewAI compatible OpenAI devrait concrétiser ces contrôles pour chaque rôle d'agent.

Étape 1 : Créer les valeurs de route Flatkey

Créez une clé Flatkey pour cette charge de travail et conservez les valeurs de route en dehors du contrôle de code source.

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

Gardez la racine de l'API séparée du chemin du point de terminaison. L'objet LLM de CrewAI doit recevoir l'URL de base. Les tests directs avec curl ajoutent /chat/completions.

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": "Répondez avec exactement : flatkey route ok" }
    ]
  }'

Si cette requête directe échoue, corrigez d'abord la clé Flatkey, l'alias de modèle, la famille de points de terminaison ou la route du compte. Un routeur CrewAI compatible OpenAI ne peut pas compenser un alias de modèle que le compte de la passerelle ne peut pas appeler.

Étape 2 : Configurer explicitement les objets LLM de CrewAI

CrewAI permet de définir l'URL de base de l'API pour un LLM via base_url, et sa documentation montre la configuration de LLM compatibles OpenAI soit par des variables d'environnement, soit par des attributs de classe LLM. Pour le travail en production, les objets LLM explicites sont plus faciles à examiner car chaque rôle d'agent pointe vers une route connue.

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)

C'est la décision de configuration la plus importante dans une migration de routeur compatible CrewAI OpenAI. L'alias du modèle peut changer en fonction de l'environnement, mais le code CrewAI conserve une seule racine d'API compatible OpenAI et un seul propriétaire de clé de passerelle.

Étape 3 : Attribuer les routes en fonction de la responsabilité de l'agent

Donnez à chaque agent CrewAI une route LLM qui correspond à son profil de risque. Commencez avec un petit ensemble de routes. Vous pourrez toujours diviser davantage de rôles plus tard, une fois que les journaux auront prouvé que la première politique fonctionne.

planner = Agent(
    role="Planificateur de workflow",
    goal="Décomposer la requête en un plan d'exécution court.",
    backstory="Vous gardez l'équipe concentrée sur son périmètre et évitez les appels de modèle inutiles.",
    llm=planner_llm,
)

researcher = Agent(
    role="Chercheur",
    goal="Collecter uniquement les faits nécessaires à la tâche.",
    backstory="Vous préférez les notes étayées par des sources plutôt que la spéculation générale.",
    llm=planner_llm,
)

tool_user = Agent(
    role="Opérateur d'outils",
    goal="Utiliser les outils approuvés uniquement lorsque la tâche l'exige.",
    backstory="Vous vérifiez les entrées des outils avant d'appeler des systèmes externes.",
    llm=tool_llm,
)

verifier = Agent(
    role="Vérificateur",
    goal="Vérifier la réponse finale par rapport aux exigences et aux preuves.",
    backstory="Vous recherchez les preuves manquantes, les erreurs d'outils et les risques de retour en arrière.",
    llm=verifier_llm,
)

Pour un premier déploiement de routeur compatible CrewAI OpenAI, évitez d'attribuer un modèle unique à chaque agent. Deux ou trois types de routes sont généralement suffisants : planification, exécution capable d'utiliser des outils et vérification.

Étape 4 : Constituer une petite équipe et conserver les champs de preuve

L'équipe peut rester ordinaire. Les preuves de routage, non. Ajoutez des champs simples à la description de la tâche, à la sortie ou aux journaux de votre application environnante afin que la requête puisse être mise en correspondance avec les journaux Flatkey.

analysis_task = Task(
    description=(
        "Examinez le ticket de support et produisez un plan de résolution court. "
        "N'appelez pas d'outils à moins qu'une recherche de compte ne soit nécessaire. "
        "Champs de preuve à conserver en dehors de ce prompt : workflow=crew_support_triage, "
        "route_policy=crewai-router-v1."
    ),
    expected_output="Un plan concis avec les risques, les besoins en outils et la prochaine action.",
    agent=planner,
)

verification_task = Task(
    description=(
        "Vérifiez si le plan cite les faits du ticket, évite les affirmations non étayées, "
        "et nomme tout appel d'outil qui nécessite encore une approbation."
    ),
    expected_output="Notes de réussite/échec avec les corrections requises.",
    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)

Le request_id dans ce modèle n'est pas une fonctionnalité de routage de CrewAI en soi. C'est une habitude d'observabilité. Votre application doit journaliser l'ID de la requête, la politique de routage, l'alias du modèle, l'horodatage et l'étiquette de la clé afin que le chemin du routeur compatible CrewAI OpenAI puisse être vérifié dans Flatkey.

Étape 5 : Vérifier les appels d'outils avant un déploiement à grande échelle

L'utilisation d'outils est là où le routage compatible OpenAI devient risqué. Une route de chat simple peut fonctionner alors qu'une route utilisant beaucoup d'outils échoue à la validation du schéma, diffuse les arguments des outils différemment ou produit des arguments que votre exécuteur rejette.

Effectuez un test d'outil restreint avant de faire confiance à une route d'outils CrewAI. Pour un comportement plus large des fournisseurs, associez ce guide à l'article de Flatkey sur les appels d'outils compatibles OpenAI.

Ne considérez pas cela comme facultatif. Un routeur compatible CrewAI OpenAI n'est prêt pour la production que lorsque la route d'outils est testée comme un contrat distinct.

Étape 6 : Ajouter des règles de budget, de nouvelle tentative et de repli en dehors des prompts

Ne demandez pas aux agents de se souvenir de chaque règle opérationnelle en langage naturel. Conservez les règles de budget et de repli dans le code ou la configuration que les réviseurs peuvent inspecter.

Lorsque le repli est approuvé, gardez l'alias de repli explicite. La question utile n'est pas « l'équipe a-t-elle terminé ? » mais « quelle route a terminé, pourquoi a-t-elle changé et combien cela a-t-il coûté ? ». C'est la valeur opérationnelle d'un routeur CrewAI compatible OpenAI.

Étape 7 : Enregistrer un paquet de vérification

Avant de faire de Flatkey la passerelle par défaut pour un workflow CrewAI, enregistrez un paquet de vérification compact.

1. La requête directe curl vers https://router.flatkey.ai/v1/chat/completions réussit avec l'alias de modèle sélectionné.
2. Chaque objet LLM de CrewAI exécute une petite invite en dehors de l'équipe complète.
3. L'équipe complète exécute un workflow simple et un workflow riche en outils.
4. Un chemin d'échec forcé s'arrête proprement au lieu de réessayer indéfiniment.
5. Les journaux Flatkey affichent la clé attendue, l'alias du modèle, l'horodatage et le propriétaire de la requête.
6. Les champs de jeton ou d'utilisation sont suffisamment visibles pour que le responsable du budget puisse les examiner.
7. La restauration est un changement d'environnement ou de configuration, pas une refactorisation de CrewAI.

Utilisez le guide du tableau de bord d'utilisation des jetons Flatkey pour décider quels champs votre équipe des opérations doit inspecter après le premier test de fumée. Pour la tarification et l'examen du compte, commencez par la page de tarification Flatkey en direct, puis vérifiez la route réelle dans votre compte.

Dépannage d'un routeur CrewAI compatible OpenAI

Si la première requête échoue, gardez la surface de débogage petite : une clé, une URL de base, un alias de modèle, un LLM CrewAI, une requête directe et une consultation des journaux Flatkey.

FAQ

Un routeur CrewAI compatible OpenAI est-il la même chose qu'un repli de modèle ?

Non. Un routeur CrewAI compatible OpenAI est la passerelle et la limite de configuration que CrewAI utilise pour atteindre les routes de modèle. Le repli est une politique qui peut s'exécuter lorsqu'une route choisie échoue. Testez le routage et le repli séparément.

Chaque agent CrewAI doit-il obtenir un modèle différent ?

Non. Commencez avec une route par défaut et une route spéciale pour les tâches riches en outils ou de vérification si nécessaire. Trop d'alias rendent les journaux, l'examen des coûts et la restauration plus difficiles.

CrewAI peut-il utiliser des variables d'environnement au lieu d'objets LLM explicites ?

Oui. La documentation de CrewAI montre une configuration compatible OpenAI via des variables d'environnement telles que OPENAI_API_BASE. Les objets LLM explicites sont souvent plus faciles à examiner en production car chaque rôle d'agent affiche le model, la base_url et la api_key au même endroit.

Puis-je utiliser la même clé Flatkey pour chaque workflow CrewAI ?

Vous pouvez, mais les clés spécifiques à la charge de travail sont plus faciles à auditer. Utilisez des clés ou des étiquettes distinctes lorsque différentes équipes, environnements, budgets ou niveaux de risque nécessitent un examen séparé.

Liste de contrôle finale

Votre configuration de routeur CrewAI compatible OpenAI est prête à dépasser le stade de modèle lorsque :

1. Les objets LLM de CrewAI utilisent la racine de l'API Flatkey comme base_url.
2. Les alias de modèle se trouvent dans l'environnement ou la configuration, et non dispersés dans les invites.
3. Chaque rôle d'agent a une décision de route intentionnelle.
4. Les routes riches en outils réussissent les tests de schéma, d'argument, de plafond et d'échec.
5. Les limites de budget, de nouvelle tentative et de repli s'exécutent en dehors de la prose de l'agent.
6. Les journaux d'utilisation ou de requêtes de Flatkey confirment la clé et l'alias de modèle attendus.
7. La restauration est un simple changement de configuration.

Lorsque vous êtes prêt à acheminer le trafic CrewAI via une passerelle unique, obtenez une clé Flatkey, testez un crew à faible risque, et étendez seulement après que les journaux prouvent que la politique fonctionne.