Roteador Compatível com OpenAI da CrewAI: Uma Chave para Fluxos de Trabalho Multi-Agente

Uma configuração de roteador compatível com OpenAI da CrewAI é útil quando você deseja que vários agentes da CrewAI usem um limite de gateway único em vez de espalhar chaves de provedor, URLs base e aliases de modelo em cada função no fluxo de trabalho.

A documentação atual de LLM da CrewAI mostra dois caminhos de configuração importantes para endpoints compatíveis com OpenAI: variáveis de ambiente como OPENAI_API_BASE e atributos explícitos de LLM(...) como model, base_url e api_key. O Flatkey se encaixa nesse limite. Seu site público direciona clientes compatíveis com OpenAI para https://router.flatkey.ai/v1, com revisão de uso, custo, roteamento e erros no painel do produto.

Este guia mostra um padrão prático de roteador compatível com OpenAI da CrewAI para fluxos de trabalho multi-agente. O código é um modelo: valide os aliases de modelo exatos, o comportamento da ferramenta e os logs com sua própria chave Flatkey antes de rotear agentes de produção.

Resposta rápida para um roteador compatível com OpenAI da CrewAI

Use uma raiz de API de gateway e nomes de rota explícitos. Não oculte o roteamento no texto do prompt.

Esse é o padrão central do roteador compatível com OpenAI da CrewAI: mantenha a CrewAI responsável pela orquestração, mantenha o Flatkey responsável pelo limite do gateway compatível com OpenAI e torne as verificações operacionais visíveis.

Por que os fluxos de trabalho multi-agente precisam de um limite de gateway

Os fluxos de trabalho da CrewAI geralmente começam com uma forma simples: um agente gerente, alguns agentes especialistas e uma tarefa final. Isso funciona até que o fluxo de trabalho passe de uma demonstração para um serviço do qual outras equipes dependem.

Sistemas multi-agente de produção geralmente precisam de mais do que uma resposta funcional:

Para controles de design adjacentes, use o guia do Flatkey para controles de gateway de agente de IA. Um roteador compatível com OpenAI da CrewAI deve tornar esses controles concretos para cada função de agente.

Passo 1: Crie os valores de rota do Flatkey

Crie uma chave Flatkey para esta carga de trabalho e mantenha os valores de rota fora do controle de versão.

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

Mantenha a raiz da API separada do caminho do endpoint. O objeto LLM da CrewAI deve receber a URL base. Testes diretos com curl adicionam /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": "Responda com exatamente: rota flatkey ok" }
    ]
  }'

Se esta solicitação direta falhar, corrija primeiro a chave Flatkey, o alias do modelo, a família do endpoint ou a rota da conta. Um roteador compatível com OpenAI da CrewAI não pode compensar um alias de modelo que a conta do gateway não pode chamar.

Passo 2: Configure os objetos LLM da CrewAI explicitamente

A CrewAI suporta a configuração da URL base da API para um LLM através de base_url, e sua documentação mostra a configuração de LLM compatível com OpenAI por meio de variáveis de ambiente ou atributos de classe LLM. Para trabalho em produção, objetos LLM explícitos são mais fáceis de revisar porque cada função de agente aponta para uma rota conhecida.

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 é a decisão de configuração mais importante em uma migração do roteador compatível com OpenAI da CrewAI. O alias do modelo pode mudar por ambiente, mas o código da CrewAI mantém uma raiz de API compatível com OpenAI e um proprietário de chave de gateway.

Passo 3: Atribua rotas por responsabilidade do agente

Dê a cada agente da CrewAI uma rota de LLM que corresponda ao seu perfil de risco. Comece com um pequeno conjunto de rotas. Você sempre pode dividir mais funções posteriormente, depois que os logs provarem que a primeira política funciona.

planner = Agent(
    role="Planejador de fluxo de trabalho",
    goal="Dividir a solicitação em um plano de execução curto.",
    backstory="Você mantém a equipe focada e evita chamadas de modelo desnecessárias.",
    llm=planner_llm,
)

researcher = Agent(
    role="Pesquisador",
    goal="Coletar apenas os fatos necessários para a tarefa.",
    backstory="Você prefere anotações com fontes a especulações amplas.",
    llm=planner_llm,
)

tool_user = Agent(
    role="Operador de ferramentas",
    goal="Usar ferramentas aprovadas apenas quando a tarefa as exigir.",
    backstory="Você verifica as entradas das ferramentas antes de chamar sistemas externos.",
    llm=tool_llm,
)

verifier = Agent(
    role="Verificador",
    goal="Verificar a resposta final em relação aos requisitos e evidências.",
    backstory="Você procura por provas ausentes, erros de ferramentas e riscos de reversão.",
    llm=verifier_llm,
)

Para uma primeira implementação do roteador compatível com OpenAI da CrewAI, evite atribuir um modelo único a cada agente. Dois ou três tipos de rota geralmente são suficientes: planejamento, execução com capacidade de ferramenta e verificação.

Passo 4: Crie uma equipe pequena e mantenha os campos de evidência

A equipe pode permanecer comum. A evidência de roteamento não. Adicione campos simples à descrição da tarefa, à saída ou aos logs da sua aplicação para que a solicitação possa ser correspondida aos logs da Flatkey.

analysis_task = Task(
    description=(
        "Revise o ticket de suporte e produza um plano de resolução curto. "
        "Não chame ferramentas a menos que uma consulta de conta seja necessária. "
        "Campos de evidência a serem mantidos fora deste prompt: workflow=crew_support_triage, "
        "route_policy=crewai-router-v1."
    ),
    expected_output="Um plano conciso com riscos, necessidades de ferramentas e próxima ação.",
    agent=planner,
)

verification_task = Task(
    description=(
        "Verifique se o plano cita os fatos do ticket, evita alegações não suportadas, "
        "e nomeia qualquer chamada de ferramenta que ainda precise de aprovação."
    ),
    expected_output="Notas de aprovação/reprovação com as correções necessárias.",
    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)

O request_id neste modelo não é um recurso de roteamento da CrewAI por si só. É um hábito de observabilidade. Seu aplicativo deve registrar o ID da solicitação, a política de rota, o alias do modelo, o carimbo de data/hora e o rótulo da chave para que o caminho do roteador compatível com OpenAI da CrewAI possa ser verificado na Flatkey.

Passo 5: Verifique as chamadas de ferramentas antes da implementação em larga escala

O uso de ferramentas é onde o roteamento compatível com OpenAI se torna arriscado. Uma rota de chat simples pode funcionar, enquanto uma rota com muitas ferramentas falha na validação do esquema, transmite os argumentos da ferramenta de forma diferente ou produz argumentos que seu executor rejeita.

Use um teste de ferramenta restrito antes de confiar em uma rota de ferramenta da CrewAI. Para um comportamento mais amplo do provedor, combine este guia com o artigo da Flatkey sobre chamada de ferramenta compatível com OpenAI.

Não trate isso como opcional. Um roteador compatível com OpenAI da CrewAI só está pronto para produção quando a rota da ferramenta é testada como um contrato separado.

Passo 6: Adicione regras de orçamento, nova tentativa e fallback fora dos prompts

Não peça aos agentes para se lembrarem de todas as regras operacionais em linguagem natural. Mantenha as regras de orçamento e fallback no código ou na configuração que os revisores possam inspecionar.

Quando o fallback for aprovado, mantenha o alias de fallback explícito. A pergunta útil não é "a equipe terminou?", mas "qual rota terminou, por que mudou e quanto custou?". Esse é o valor operacional de um roteador compatível com OpenAI da CrewAI.

Passo 7: Salve um pacote de verificação

Antes de tornar o Flatkey o gateway padrão para um fluxo de trabalho da CrewAI, salve um pacote de verificação compacto.

1. A solicitação direta via curl para https://router.flatkey.ai/v1/chat/completions é bem-sucedida com o alias do modelo selecionado.
2. Cada objeto LLM da CrewAI executa um pequeno prompt fora da equipe completa.
3. A equipe completa executa um fluxo de trabalho simples e um fluxo de trabalho com muitas ferramentas.
4. Um caminho de falha forçada para de forma limpa em vez de tentar novamente para sempre.
5. Os logs do Flatkey mostram a chave esperada, o alias do modelo, o carimbo de data/hora e o proprietário da solicitação.
6. Os campos de token ou uso são visíveis o suficiente para o proprietário do orçamento revisar.
7. A reversão é uma alteração de ambiente ou configuração, não uma refatoração da CrewAI.

Use o guia do painel de uso de tokens do Flatkey para decidir quais campos sua equipe de operações deve inspecionar após o primeiro teste de fumaça. Para revisão de preços e contas, comece na página de preços do Flatkey ao vivo e, em seguida, verifique a rota real em sua conta.

Solução de problemas de um roteador compatível com OpenAI da CrewAI

Se a primeira solicitação falhar, mantenha a superfície de depuração pequena: uma chave, uma URL base, um alias de modelo, um LLM da CrewAI, uma solicitação direta e uma consulta de log do Flatkey.

Perguntas Frequentes

Um roteador compatível com OpenAI da CrewAI é o mesmo que fallback de modelo?

Não. Um roteador compatível com OpenAI da CrewAI é o gateway e o limite de configuração que a CrewAI usa para alcançar as rotas do modelo. Fallback é uma política que pode ser executada quando uma rota escolhida falha. Teste o roteamento e o fallback separadamente.

Cada agente da CrewAI deve ter um modelo diferente?

Não. Comece com uma rota padrão e uma rota especial para trabalhos com muitas ferramentas ou de verificação, se necessário. Muitos aliases dificultam os logs, a revisão de custos e a reversão.

A CrewAI pode usar variáveis de ambiente em vez de objetos LLM explícitos?

Sim. A documentação da CrewAI mostra a configuração compatível com OpenAI por meio de variáveis de ambiente, como OPENAI_API_BASE. Objetos LLM explícitos são frequentemente mais fáceis para revisão em produção porque cada função de agente mostra model, base_url e api_key em um só lugar.

Posso usar a mesma chave Flatkey para cada fluxo de trabalho da CrewAI?

Você pode, mas chaves específicas para a carga de trabalho são mais fáceis de auditar. Use chaves ou rótulos separados quando diferentes equipes, ambientes, orçamentos ou níveis de risco precisarem de revisão separada.

Lista de verificação final

A configuração do seu roteador compatível com OpenAI da CrewAI está pronta para ir além de um modelo quando:

1. Os objetos LLM da CrewAI usam a raiz da API do Flatkey como base_url.
2. Os aliases do modelo residem no ambiente ou na configuração, não espalhados pelos prompts.
3. Cada função de agente tem uma decisão de rota intencional.
4. As rotas com muitas ferramentas passam nos testes de esquema, argumento, limite e falha.
5. Os limites de orçamento, nova tentativa e fallback são executados fora da prosa do agente.
6. Os logs de uso ou solicitação do Flatkey confirmam a chave e o alias do modelo esperados.
7. A reversão é uma única alteração de configuração.

Quando estiver pronto para rotear o tráfego do CrewAI através de um único gateway, obtenha uma chave Flatkey, teste um crew de baixo risco e expanda somente depois que os logs provarem que a política funciona.