Router compatible con OpenAI de CrewAI: una clave para flujos de trabajo multiagente

Una configuración de router compatible con OpenAI de CrewAI es útil cuando quieres que varios agentes de CrewAI usen un único límite de puerta de enlace en lugar de dispersar claves de proveedor, URL base y alias de modelos en cada rol del flujo de trabajo.

La documentación actual de LLM de CrewAI muestra dos rutas de configuración importantes para los endpoints compatibles con OpenAI: variables de entorno como OPENAI_API_BASE y atributos explícitos de LLM(...) como model, base_url y api_key. Flatkey encaja en ese límite. Su sitio público dirige a los clientes compatibles con OpenAI a https://router.flatkey.ai/v1, con revisión de uso, costos, enrutamiento y errores en el panel de control del producto.

Esta guía muestra un patrón práctico de router compatible con OpenAI de CrewAI para flujos de trabajo multiagente. El código es una plantilla: valida los alias de modelo exactos, el comportamiento de las herramientas y los registros con tu propia clave de Flatkey antes de enrutar los agentes de producción.

Respuesta rápida para un router compatible con OpenAI de CrewAI

Usa una única raíz de API de puerta de enlace y nombres de ruta explícitos. No ocultes el enrutamiento en el texto del prompt.

Ese es el patrón central del router compatible con OpenAI de CrewAI: mantener a CrewAI responsable de la orquestación, mantener a Flatkey responsable del límite de la puerta de enlace compatible con OpenAI y hacer visibles las verificaciones operativas.

Por qué los flujos de trabajo multiagente necesitan un límite de puerta de enlace

Los flujos de trabajo de CrewAI a menudo comienzan con una forma simple: un agente gestor, unos pocos agentes especialistas y una tarea final. Eso funciona hasta que el flujo de trabajo pasa de ser una demostración a un servicio del que dependen otros equipos.

Los sistemas multiagente de producción suelen necesitar más que una respuesta que funcione:

Para controles de diseño adyacentes, utiliza la guía de Flatkey sobre controles de puerta de enlace para agentes de IA. Un router compatible con OpenAI de CrewAI debería concretar esos controles para cada rol de agente.

Paso 1: Crear los valores de ruta de Flatkey

Crea una clave de Flatkey para esta carga de trabajo y mantén los valores de la ruta fuera del control de código fuente.

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

Mantén la raíz de la API separada de la ruta del endpoint. El objeto LLM de CrewAI debe recibir la URL base. Las pruebas directas con curl añaden /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": "Responde exactamente con: flatkey route ok" }
    ]
  }'

Si esta solicitud directa falla, corrige primero la clave de Flatkey, el alias del modelo, la familia de endpoints o la ruta de la cuenta. Un router compatible con OpenAI de CrewAI no puede compensar un alias de modelo que la cuenta de la puerta de enlace no puede llamar.

Paso 2: Configurar explícitamente los objetos LLM de CrewAI

CrewAI permite establecer la URL base de la API para un LLM a través de base_url, y su documentación muestra la configuración de LLM compatibles con OpenAI a través de variables de entorno o atributos de clase de LLM. Para el trabajo en producción, los objetos LLM explícitos son más fáciles de revisar porque cada rol de agente apunta a una ruta conocida.

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)

Esta es la decisión de configuración más importante en una migración de un router compatible con OpenAI de CrewAI. El alias del modelo puede cambiar según el entorno, pero el código de CrewAI mantiene una raíz de API compatible con OpenAI y un propietario de clave de puerta de enlace.

Paso 3: Asignar rutas por responsabilidad del agente

Asigna a cada agente de CrewAI una ruta de LLM que coincida con su perfil de riesgo. Comienza con un conjunto de rutas pequeño. Siempre puedes dividir más roles más tarde, después de que los registros demuestren que la primera política funciona.

planner = Agent(
    role="Planificador de flujo de trabajo",
    goal="Dividir la solicitud en un plan de ejecución corto.",
    backstory="Mantienes al equipo enfocado y evitas llamadas innecesarias al modelo.",
    llm=planner_llm,
)

researcher = Agent(
    role="Investigador",
    goal="Recopilar solo los hechos necesarios para la tarea.",
    backstory="Prefieres notas respaldadas por fuentes en lugar de especulaciones amplias.",
    llm=planner_llm,
)

tool_user = Agent(
    role="Operador de herramientas",
    goal="Usar herramientas aprobadas solo cuando la tarea lo requiera.",
    backstory="Verificas las entradas de las herramientas antes de llamar a sistemas externos.",
    llm=tool_llm,
)

verifier = Agent(
    role="Verificador",
    goal="Verificar la respuesta final contra los requisitos y la evidencia.",
    backstory="Buscas pruebas faltantes, errores de herramientas y riesgos de reversión.",
    llm=verifier_llm,
)

Para un primer despliegue de un router compatible con OpenAI de CrewAI, evita asignar un modelo único a cada agente. Dos o tres tipos de rutas suelen ser suficientes: planificación, ejecución con capacidad para herramientas y verificación.

Paso 4: Construir un equipo pequeño y mantener los campos de evidencia

El equipo puede seguir siendo ordinario. La evidencia de enrutamiento no. Agrega campos simples a la descripción de la tarea, a la salida o a los registros de tu aplicación circundante para que la solicitud pueda coincidir con los registros de Flatkey.

analysis_task = Task(
    description=(
        "Revisar el ticket de soporte y producir un plan de resolución corto. "
        "No llamar a herramientas a menos que se requiera una búsqueda de cuenta. "
        "Evidence fields to keep outside this prompt: workflow=crew_support_triage, "
        "route_policy=crewai-router-v1."
    ),
    expected_output="Un plan conciso con riesgos, necesidades de herramientas y próxima acción.",
    agent=planner,
)

verification_task = Task(
    description=(
        "Verificar si el plan cita los hechos del ticket, evita afirmaciones sin respaldo "
        "y nombra cualquier llamada a herramienta que aún necesite aprobación."
    ),
    expected_output="Notas de aprobado/reprobado con las correcciones requeridas.",
    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)

El request_id en esta plantilla no es una característica de enrutamiento de CrewAI por sí misma. Es un hábito de observabilidad. Tu aplicación debe registrar el ID de la solicitud, la política de enrutamiento, el alias del modelo, la marca de tiempo y la etiqueta de la clave para que la ruta del router compatible con OpenAI de CrewAI pueda verificarse en Flatkey.

Paso 5: Verificar las llamadas a herramientas antes de un despliegue amplio

El uso de herramientas es donde el enrutamiento compatible con OpenAI se vuelve arriesgado. Una ruta de chat simple puede funcionar, mientras que una ruta con muchas herramientas puede fallar la validación del esquema, transmitir los argumentos de las herramientas de manera diferente o producir argumentos que tu ejecutor rechace.

Usa una prueba de herramientas específica antes de confiar en una ruta de herramientas de CrewAI. Para un comportamiento más amplio del proveedor, combina esta guía con el artículo de Flatkey sobre llamadas a herramientas compatibles con OpenAI.

No trates esto como algo opcional. Un router compatible con OpenAI de CrewAI solo está listo para producción cuando la ruta de la herramienta se prueba como un contrato separado.

Paso 6: Añadir reglas de presupuesto, reintento y respaldo fuera de los prompts

No pidas a los agentes que recuerden cada regla operativa en lenguaje natural. Mantén las reglas de presupuesto y de respaldo en el código o en la configuración que los revisores puedan inspeccionar.

Cuando se aprueba el respaldo, mantén el alias de respaldo explícito. La pregunta útil no es "¿terminó el equipo?", sino "¿qué ruta terminó, por qué cambió y cuánto costó?". Ese es el valor operativo de un router compatible con OpenAI de CrewAI.

Paso 7: Guardar un paquete de verificación

Antes de hacer de Flatkey la puerta de enlace predeterminada para un flujo de trabajo de CrewAI, guarda un paquete de verificación compacto.

1. La solicitud directa de curl a https://router.flatkey.ai/v1/chat/completions tiene éxito con el alias de modelo seleccionado.
2. Cada objeto LLM de CrewAI ejecuta una pequeña instrucción fuera del equipo completo.
3. El equipo completo ejecuta un flujo de trabajo simple y un flujo de trabajo con muchas herramientas.
4. Una ruta de fallo forzado se detiene limpiamente en lugar de reintentar indefinidamente.
5. Los registros de Flatkey muestran la clave esperada, el alias del modelo, la marca de tiempo y el propietario de la solicitud.
6. Los campos de token o uso son lo suficientemente visibles para que el responsable del presupuesto los revise.
7. La reversión es un cambio de entorno o de configuración, no una refactorización de CrewAI.

Usa la guía del panel de uso de tokens de Flatkey para decidir qué campos debe inspeccionar tu equipo de operaciones después de la primera prueba de humo. Para la revisión de precios y de la cuenta, comienza desde la página de precios de Flatkey en vivo, luego verifica la ruta real en tu cuenta.

Solución de problemas de un router compatible con OpenAI de CrewAI

Si la primera solicitud falla, mantén la superficie de depuración pequeña: una clave, una URL base, un alias de modelo, un LLM de CrewAI, una solicitud directa y una consulta de registro de Flatkey.

Preguntas frecuentes

¿Es un router compatible con OpenAI de CrewAI lo mismo que un respaldo de modelo?

No. Un router compatible con OpenAI de CrewAI es la puerta de enlace y el límite de configuración que CrewAI utiliza para alcanzar las rutas del modelo. El respaldo es una política que puede ejecutarse cuando una ruta elegida falla. Prueba el enrutamiento y el respaldo por separado.

¿Debería cada agente de CrewAI tener un modelo diferente?

No. Comienza con una ruta predeterminada y una ruta especial para trabajos con muchas herramientas o de verificación si es necesario. Demasiados alias dificultan los registros, la revisión de costos y la reversión.

¿Puede CrewAI usar variables de entorno en lugar de objetos LLM explícitos?

Sí. La documentación de CrewAI muestra la configuración compatible con OpenAI a través de variables de entorno como OPENAI_API_BASE. Los objetos LLM explícitos suelen ser más fáciles para la revisión en producción porque cada rol de agente muestra model, base_url y api_key en un solo lugar.

¿Puedo usar la misma clave de Flatkey para cada flujo de trabajo de CrewAI?

Puedes, pero las claves específicas de la carga de trabajo son más fáciles de auditar. Usa claves o etiquetas separadas cuando diferentes equipos, entornos, presupuestos o niveles de riesgo necesiten una revisión por separado.

Lista de verificación final

La configuración de tu router compatible con OpenAI de CrewAI está lista para ir más allá de una plantilla cuando:

1. Los objetos LLM de CrewAI usan la raíz de la API de Flatkey como base_url.
2. Los alias de modelo residen en el entorno o la configuración, no dispersos por las instrucciones.
3. Cada rol de agente tiene una decisión de ruta intencionada.
4. Las rutas con muchas herramientas superan las pruebas de esquema, argumento, límite y fallo.
5. Los límites de presupuesto, reintento y respaldo se ejecutan fuera de la prosa del agente.
6. Los registros de uso o de solicitudes de Flatkey confirman la clave y el alias de modelo esperados.
7. La reversión es un único cambio de configuración.

Cuando esté listo para enrutar el tráfico de CrewAI a través de una única puerta de enlace, obtenga una clave Flatkey, pruebe un crew de bajo riesgo y expanda solo después de que los registros demuestren que la política funciona.