Construindo Agentes de IA com Múltiplos Modelos: Um Guia Prático de Arquitetura

A maioria dos agentes de IA depende de um único modelo para lidar com todas as fases da execução. A etapa de planejamento, as chamadas de ferramentas, a extração de dados, o resumo e a recuperação de erros passam pelo mesmo LLM. Embora essa abordagem seja direta para protótipos iniciais, ela introduz ineficiências significativas em ambientes de produção.

Uma etapa de planejamento que exige raciocínio profundo não precisa do mesmo modelo que uma etapa básica de extração de JSON. Uma tarefa de geração de código tem requisitos diferentes de uma tarefa de classificação. Usar um modelo de raciocínio de alto nível, como o Claude Fable 5 ou o Claude Opus 4.8, para formatar uma string de data é uma alocação indevida e cara de recursos.

Construir agentes de IA com múltiplos modelos permite que você direcione cada etapa de um fluxo de trabalho para o modelo mais adequado àquela tarefa específica. Este guia explora como projetar, implementar e gerenciar essas arquiteturas de múltiplos modelos.

Se você está trabalhando na camada de API em vez da camada de orquestração de agentes, consulte Agent-First API Design e Why Teams Switch from Direct Model APIs to a Unified AI API juntamente com este guia. Agentes de múltiplos modelos operam de forma mais confiável quando a superfície da API subjacente é estável o suficiente para trocar modelos sem reescrever o código de orquestração.

:::info

Principais Aprendizados

1. Combine o Modelo com a Complexidade da Tarefa: Use modelos pequenos e rápidos para roteamento, extração e formatação, reservando modelos de raciocínio maiores para planejamento e análises complexas.
2. Padronize Schemas: Implemente validação de saída rigorosa (como Pydantic) em cada transferência para evitar o desvio de contrato ao alternar entre diferentes provedores de modelos.
3. Projete para Fallbacks: Crie caminhos de fallback automatizados para lidar com limites de taxa (rate limits), quedas de provedores ou picos de latência sem interromper o fluxo de trabalho do agente.
4. Centralize a Telemetria: Rastreie a latência, contagens de tokens de entrada/saída e custo por etapa para otimizar continuamente sua lógica de roteamento. :::

---

A Arquitetura de Agente de Múltiplos Modelos

Uma arquitetura de agente de múltiplos modelos distribui tarefas entre modelos especializados com base em requisitos de complexidade, custo e latência.

Solicitação do Usuário
    │
    ▼
┌─────────────┐
│   Roteador   │  ← Classifica a complexidade da tarefa
│ (modelo rápido)│
└──────┬──────┘
       │
   ┌───┴───┐
   ▼       ▼
┌──────┐ ┌──────┐
│Modelo│ │Modelo│
│Simples│ │Complexo│
└──┬───┘ └──┬───┘
   │        │
   ▼        ▼
┌─────────────┐
│  Agregador   │  ← Combina os resultados
│ (modelo rápido)│
└─────────────┘

A arquitetura central consiste em cinco componentes principais:

1. O Roteador: Um modelo rápido e de baixo custo que classifica as tarefas recebidas por complexidade e intenção.
2. O Pool de Modelos: Uma coleção de modelos combinados com diferentes tipos de tarefas (como raciocínio, extração ou geração de código).
3. O Agregador: Um modelo rápido que combina resultados de etapas paralelas em uma resposta final.
4. A Política de Fallback: Regras que ditam qual modelo usar se a escolha principal falhar, atingir o tempo limite ou encontrar limites de taxa.
5. A Camada de Telemetria: Um sistema de log que registra as escolhas de modelo, latência e custos exatos de tokens por etapa.

Sem políticas de fallback e telemetria, um agente de múltiplos modelos pode se tornar difícil de depurar, com perfis de latência e custo imprevisíveis.

---

Implementação com o SDK da OpenAI

Usar um gateway de API unificado permite que você acesse modelos de diferentes provedores usando um único SDK e chave de API. Isso simplifica a troca de modelos e o roteamento.

O exemplo a seguir demonstra uma implementação básica de roteamento. A disponibilidade e o preço dos modelos devem ser verificados no diretório de modelos da TokenLab.

from openai import OpenAI

client = OpenAI(
    api_key="sk-tokenlab-xxx",
    base_url="https://api.tokenlab.sh/v1"
)

# Pool de modelos com níveis de custo e capacidade
MODELS = {
    "router": "deepseek-v4-flash",        # Classificação rápida
    "simple": "deepseek-v4-flash",        # Extração, formatação
    "reasoning": "claude-sonnet-5",       # Planejamento, análise
    "complex": "gpt-5.5",                 # Geração de código, lógica complexa
    "budget": "deepseek-v4-flash",        # Processamento em lote
}

def route_task(task: str) -> str:
    """Use um modelo de menor custo para classificar a complexidade da tarefa."""
    response = client.chat.completions.create(
        model=MODELS["router"],
        messages=[
            {"role": "system", "content": """Classifique esta tarefa em exatamente uma categoria:
- simple: extração de dados, formatação, tradução
- reasoning: análise, planejamento, comparação
- complex: geração de código, resolução de problemas em várias etapas
- budget: processamento em lote, tarefas não críticas
Responda apenas com o nome da categoria em letras minúsculas."""},
            {"role": "user", "content": task}
        ],
        max_tokens=10
    )
    category = response.choices[0].message.content.strip().lower()
    return MODELS.get(category, MODELS["simple"])

def execute_task(task: str, context: str = "") -> str:
    """Direcione a tarefa para o modelo selecionado e execute-a."""
    model = route_task(task)
    messages = []
    if context:
        messages.append({"role": "system", "content": context})
    messages.append({"role": "user", "content": task})

    response = client.chat.completions.create(
        model=model,
        messages=messages
    )
    return response.choices[0].message.content

---

Agente do Mundo Real: Pipeline de Revisão de Código

Para ver o impacto prático de construir agentes de IA com múltiplos modelos, considere um pipeline projetado para revisar pull requests. Este fluxo de trabalho divide a revisão em etapas especializadas em vez de enviar todo o diff de código para um único modelo caro.

def review_pr(diff: str) -> dict:
    """Pipeline de revisão de PR com múltiplos modelos."""

    # Etapa 1: Classificar alterações usando um modelo rápido e de baixo custo
    classification = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=[{
            "role": "user",
            "content": f"Classifique estas alterações de código: {diff[:2000]}\n"
                       "Categorias: bugfix, feature, refactor, docs, test"
        }],
        max_tokens=20
    ).choices[0].message.content

    # Etapa 2: Realizar uma varredura de segurança usando um modelo de raciocínio forte
    security = client.chat.completions.create(
        model="claude-sonnet-5",
        messages=[{
            "role": "system",
            "content": "Você é um revisor de segurança. Verifique por: "
                       "SQL injection, XSS, auth bypass, segredos no código, "
                       "desserialização insegura. Seja específico sobre os números das linhas."
        }, {
            "role": "user",
            "content": f"Revise este diff em busca de problemas de segurança:\n{diff}"
        }]
    ).choices[0].message.content

    # Etapa 3: Analisar a qualidade do código usando um modelo de propósito geral
    quality = client.chat.completions.create(
        model="gpt-5.5",
        messages=[{
            "role": "user",
            "content": f"Revise a qualidade do código: nomenclatura, estrutura, "
                       f"tratamento de erros, cobertura de testes.\n{diff}"
        }]
    ).choices[0].message.content

    # Etapa 4: Gerar um resumo usando um modelo rápido e de baixo custo
    summary = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=[{
            "role": "user",
            "content": f"Resuma esta revisão de PR em 3 tópicos:\n"
                       f"Tipo: {classification}\n"
                       f"Segurança: {security[:500]}\n"
                       f"Qualidade: {quality[:500]}"
        }]
    ).choices[0].message.content

    return {
        "classification": classification,
        "security": security,
        "quality": quality,
        "summary": summary
    }

Otimização de Custo e Eficiência

A tabela abaixo descreve a alocação de modelos para este pipeline. O preço exato varia de acordo com o provedor e o volume; verifique as taxas atuais no diretório de modelos da TokenLab.

Etapa	Modelo	Tokens de Entrada	Função / Especialização
1. Classificar	DeepSeek V4 Flash	~2.100	Classificação rápida, roteamento de baixo custo
2. Segurança	Claude Sonnet 5	~2.500	Raciocínio profundo, análise de segurança
3. Qualidade	GPT-5.5	~2.500	Qualidade de código avançada e revisão estrutural
4. Resumo	DeepSeek V4 Flash	~1.200	Agregação de texto rápida e de baixo custo

Executar todas as quatro etapas através de um modelo de raciocínio de ponta como o Claude Sonnet 5 ou GPT-5.5 aumentaria significativamente os custos. Ao direcionar tarefas mais simples para modelos de menor custo como o DeepSeek V4 Flash, o pipeline de múltiplos modelos reduz o gasto total de tokens enquanto preserva o raciocínio profundo para a etapa crítica de análise de segurança.

---

Roteamento por Capacidade, Não Apenas por Preço

Embora a redução de custos seja um objetivo comum, as decisões de roteamento também devem levar em conta capacidades específicas do modelo. Uma política de roteamento robusta avalia modelos em quatro dimensões principais:

• Profundidade de Raciocínio: Lógica complexa, planejamento e dedução em várias etapas.
• Janela de Contexto: O volume de informações de fundo ou código necessário para a tarefa.
• Confiabilidade no Uso de Ferramentas: A precisão da chamada de função e geração de saída estruturada.
• Sensibilidade à Latência: Os requisitos de velocidade da aplicação voltada para o usuário.

Essas dimensões ajudam a estabelecer regras de roteamento claras:

• Tarefas de decomposição e planejamento são direcionadas para modelos com alto poder de raciocínio.
• Tarefas de extração de dados e formatação são direcionadas para modelos rápidos e de baixo custo.
• Geração de código e análise de sintaxe são direcionadas para modelos otimizados para tarefas de codificação.
• Tarefas de análise de repositório completo são direcionadas para modelos com grandes janelas de contexto.

Para alinhar seu roteador com esses requisitos, consulte a comparação de modelos de codificação e a comparação de preços para combinar suas etapas de fluxo de trabalho com os benchmarks atuais dos modelos.

---

Integração com LangChain

Você também pode implementar o roteamento de múltiplos modelos dentro de frameworks de orquestração como o LangChain. O exemplo a seguir configura diferentes modelos usando uma URL base de API unificada:

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# Inicializar modelos com configurações distintas
fast_model = ChatOpenAI(
    model="deepseek-v4-flash",
    api_key="sk-tokenlab-xxx",
    base_url="https://api.tokenlab.sh/v1"
)

reasoning_model = ChatOpenAI(
    model="claude-sonnet-5",
    api_key="sk-tokenlab-xxx",
    base_url="https://api.tokenlab.sh/v1"
)

# Definir cadeias especializadas
classify_chain = ChatPromptTemplate.from_template(
    "Classifique a intenção desta solicitação: {input}"
) | fast_model

analyze_chain = ChatPromptTemplate.from_template(
    "Realize uma análise detalhada deste problema: {input}"
) | reasoning_model

---

Quando Usar Agentes de Múltiplos Modelos

Introduzir múltiplos modelos adiciona complexidade arquitetural. Essa abordagem é geralmente mais benéfica quando:

• Requisitos de Tarefas Diversos: O agente lida com uma mistura de tarefas simples (como classificação ou formatação) e tarefas complexas (como planejamento estratégico ou geração de código).
• Alto Volume e Custo: Os gastos mensais com API são altos o suficiente para que a otimização gere economias significativas.
• Pontos Fortes de Modelos Especializados: O fluxo de trabalho se beneficia de pontos fortes específicos do provedor, como a janela de contexto do Gemini, as capacidades de codificação do Claude ou a velocidade de uso de ferramentas do GPT.
• Necessidades de Latência Assimétricas: Certas partes do fluxo de trabalho devem retornar resultados instantaneamente, enquanto outras etapas em segundo plano podem levar mais tempo.

Para agentes de propósito único ou interfaces de chat simples, um único modelo geralmente é mais fácil de manter. A sobrecarga operacional do roteamento pode não se justificar se cada solicitação exigir o mesmo nível de capacidade.

---

Modos de Falha Comuns

Arquiteturas de múltiplos modelos introduzem modos de falha específicos que exigem mitigação:

1. Roteadores Superdimensionados

Se o prompt do roteador se tornar excessivamente complexo, a etapa de classificação em si pode se tornar lenta e cara. Mantenha os prompts de roteamento concisos e as categorias de classificação amplas.

2. Desvio de Contrato de Saída

Modelos diferentes podem formatar saídas de maneira diferente, mesmo quando instruídos a retornar JSON. Um modelo pode retornar JSON bruto, enquanto outro o envolve em blocos de markdown. Para evitar falhas de parser downstream, aplique esquemas rigorosos usando bibliotecas de validação como Pydantic em cada transferência de etapa.

3. Degradação Silenciosa de Qualidade

Se uma política de fallback direcionar uma solicitação para um modelo de nível inferior durante uma queda do provedor principal, o agente pode retornar respostas de qualidade inferior sem gerar um erro. Implementar uma estratégia de limitação de taxa clara e um sistema de alerta ajuda a rastrear quando os fallbacks estão ativos.

4. Telemetria Fragmentada

Quando o uso do modelo é dividido entre várias APIs de provedores diretos, agregar métricas de custo e desempenho torna-se difícil. Centralizar solicitações através de um único gateway simplifica o registro e o rastreamento de custos.

---

Um Loop de Avaliação Mínimo

Para manter um agente de múltiplos modelos, estabeleça um loop de avaliação básico para rastrear o desempenho. Você pode registrar as seguintes métricas para cada execução em uma tabela de banco de dados:

• Categoria da Tarefa: A classificação atribuída pelo roteador.
• Modelo Selecionado: O modelo escolhido para cada etapa.
• Latência da Etapa: O tempo necessário para concluir cada etapa.
• Uso de Tokens: As contagens exatas de tokens de entrada e saída.
• Status de Fallback: Se um modelo de fallback foi acionado.
• Feedback do Usuário: Um indicador binário de se a saída final foi bem-sucedida.

Analisar esses dados ajuda a determinar se o roteador está selecionando os modelos corretos, quais etapas estão impulsionando a maioria dos seus custos e se os modelos de fallback estão mantendo uma qualidade aceitável.

---

FAQ

Como você lida com diferentes formatos de prompt em diferentes modelos?

Modelos diferentes respondem melhor a diferentes estruturas de prompt. Por exemplo, alguns modelos funcionam melhor com prompts de sistema, enquanto outros preferem instruções incorporadas no prompt do usuário. Para lidar com isso, abstraia seus prompts em modelos que se adaptam com base no modelo de destino, em vez de enviar strings brutas idênticas para todos os modelos em seu pool.

O roteamento adiciona muita latência a aplicações voltadas para o usuário?

O roteamento introduz uma pequena quantidade de latência para a etapa de classificação. Você pode minimizar isso usando modelos de baixa latência e altamente otimizados para o roteador, mantendo os limites máximos de tokens baixos (abaixo de 10 tokens) ou paralelizando etapas quando a classificação puder ser inferida a partir do estado da aplicação ou ponto de entrada do usuário.

Como você evita erros de parsing de JSON ao alternar entre modelos?

Para evitar erros de parsing, use recursos de saída estruturada (como modo JSON ou chamada de ferramenta) suportados pelos provedores de modelos. Além disso, envolva todas as saídas de modelo em uma camada de validação usando Pydantic ou bibliotecas similares para analisar, validar e reparar o payload antes de passá-lo para a próxima etapa em seu pipeline.

---

Acesse todos os modelos através de uma única API: Comece com a TokenLab para acessar mais de 300 modelos com uma única chave de API. Construa agentes de múltiplos modelos sem gerenciar várias contas de provedores ou reescrever a lógica de roteamento para diferentes APIs.