Encaminhamento entre modelos em agentes de programação

O que o encaminhamento entre vários modelos faz a um agente de programação

O encaminhamento entre vários modelos envia cada pedido para o modelo mais barato capaz de o processar. No tráfego de chat, funciona bem. Num agente de programação, normalmente custa mais do que poupa, porque a fatura do agente é dominada por um prefixo do prompt colocado em cache por modelo, e mudar de modelo elimina essa cache.

A regra defendida neste artigo é a seguinte: encaminhe entre fornecedores para garantir disponibilidade, encaminhe entre níveis de preço apenas nos limites entre tarefas e fixe um modelo por sessão para qualquer utilização agentic. O raciocínio é apresentado abaixo.

Quatro termos, definidos uma vez. Um router escolhe um modelo por pedido. Um gateway é o proxy pelo qual o pedido passa e que também pode, ou não, fazer o encaminhamento. Uma prompt cache é o armazenamento, pelo fornecedor, do prefixo processado do seu prompt, para que um pedido posterior que repita esse prefixo seja faturado por uma fração do preço dos tokens de entrada. Uma KV cache (key value cache) aplica a mesma ideia internamente num servidor que gere.

Por que o tráfego de chat é bem encaminhado e o tráfego de agentes não

Uma solicitação de chat corresponde a um turno. Ela chega, é classificada, é enviada para um modelo e retorna. Nada é mantido para a solicitação seguinte. Um roteador pode enviar esta pergunta para um modelo pequeno e a próxima para um modelo grande, sem que nenhuma das solicitações saiba que a outra existiu. É esse o tipo de carga que quase todos os benchmarks de roteamento medem, e os bons roteadores são realmente eficazes nesse cenário.

Um turno de agente não corresponde a uma única solicitação. Uma instrução como "corrija o teste que está falhando" transforma-se em vinte a sessenta chamadas de API. Cada chamada reenvia toda a conversa: o prompt do sistema, cada definição de ferramenta, cada ficheiro que o agente leu e cada saída de comando que observou. O contexto apenas aumenta. Na chamada trinta, o prefixo repetido pode ter dezenas de milhares de tokens, enquanto o conteúdo efetivamente novo de cada chamada tem algumas centenas.

Essa estrutura altera o significado de "caro". No chat, o custo é aproximadamente o preço do modelo multiplicado pela solicitação. Num loop de agente, o custo está no prefixo, que é faturado novamente em cada chamada. Todo o restante deste artigo decorre desse único facto.

O cache do prompt é específico do modelo, e o agente vive dentro dele

A Anthropic cobra uma leitura do cache a 0.1 vezes o preço base dos tokens de entrada e uma gravação no cache por cinco minutos a 1.25 vezes esse preço. Estes são os preços de tabela publicados em agosto de 2026.

[
  {
    "label": "Opus 5",
    "uncached_input_usd": "5.00",
    "cache_read_usd": "0.50"
  },
  {
    "label": "Sonnet 5",
    "uncached_input_usd": "2.00",
    "cache_read_usd": "0.20"
  },
  {
    "label": "Haiku 4.5",
    "uncached_input_usd": "1.00",
    "cache_read_usd": "0.10"
  }
]

Compare a segunda série com a primeira, entre linhas, e não ao longo das colunas. Uma leitura do cache no Opus 5 custa 0.50 dólares por milhão de tokens. A entrada sem cache no Haiku 4.5, o modelo mais barato da lista, custa 1.00 dólares. Portanto, voltar a ler um prefixo em cache no modelo mais caro custa menos por token de entrada do que ler esse mesmo prefixo sem cache no modelo mais barato.

Esta única comparação invalida a maioria dos planos de encaminhamento. Um router que transfere trabalho "para baixo" numa categoria está a comparar preços de tabela. Mas um agente a meio de uma sessão não paga o preço de tabela do modelo que já está a utilizar. Paga o preço de leitura do cache, que já é inferior à tarifa de entrada sem cache do modelo barato.

Os caches usam como chave um hash do prefixo do prompt e são específicos de cada modelo. Um pedido para outro modelo é comparado com um armazenamento que nunca o viu, não encontra nada e paga o preço total. O cache também é hierárquico: primeiro as ferramentas, depois o sistema e, por fim, as mensagens. Uma alteração em qualquer nível invalida esse nível e tudo o que vem depois, o que significa que editar uma definição de ferramenta descarta o cache do prompt de sistema que está atrás dela. Os agentes que registam ferramentas em tempo de execução deparam-se com este problema sem sequer alterar o router.

O custo real de uma única mudança durante a sessão

Considere uma sessão com um prefixo estável de 40,000 tokens, um tamanho normal depois de um agente ler vários ficheiros. Abaixo está o custo do prefixo de uma única interação, calculado a partir dos preços de tabela acima.

[
  {
    "label": "Opus 5, cache warm",
    "prefix_cost_usd": "0.020"
  },
  {
    "label": "Sonnet 5, turn after switch",
    "prefix_cost_usd": "0.100"
  },
  {
    "label": "Opus 5, cache re-warmed",
    "prefix_cost_usd": "0.250"
  }
]

Continuar no Opus 5 com uma cache aquecida custa 0.020 dólares pelo prefixo dessa interação. A primeira interação depois de mudar para o Sonnet 5 custa 0.100 dólares, porque o Sonnet não tem uma entrada para este prefixo e precisa de criar uma. Voltar ao Opus 5 custa 0.250 dólares, porque a entrada original expirou enquanto a sessão estava noutro modelo.

Assim, a ida e volta paga duas gravações de cache para evitar duas leituras de cache. Em contrapartida, a mudança obteve uma interação de saída ao preço do Sonnet, em vez do preço do Opus. O bloco de detalhes apresenta todo o cálculo: a poupança fica em frações de cêntimo, enquanto a penalização da cache chega a dezenas de cêntimos. A penalização é mais de uma ordem de grandeza superior e aumenta com o tamanho do prefixo, enquanto a poupança não aumenta.

Opus 5, warm read     40,000 x $0.50 / 1e6  = $0.020
Sonnet 5, cache write 40,000 x $2.50 / 1e6  = $0.100   (1.25 x $2 base)
Opus 5, cache write   40,000 x $6.25 / 1e6  = $0.250   (1.25 x $5 base)

800 x ($25 - $10) / 1e6 = $0.012

Os formatos de chamadas de ferramentas não são iguais entre fornecedores

Um agente funciona num ciclo de chamadas de ferramentas, por isso o formato da chamada é importante de uma forma que nunca é relevante no chat. A Messages API da Anthropic devolve um bloco de conteúdo tool_use e espera receber de volta um bloco tool_result. As APIs compatíveis com OpenAI devolvem um array tool_calls em que function.arguments é uma string codificada em JSON, e não um objeto aninhado. Um gateway faz a conversão entre os dois formatos, e, para chamadas comuns, a conversão é simples.

Os problemas surgem nos casos limite. As chamadas de ferramentas paralelas, em que um modelo emite várias chamadas numa única resposta, são representadas de forma diferente e não têm o mesmo nível de suporte em todos os serviços. A aplicação estrita do esquema é uma funcionalidade específica de cada fornecedor. Por isso, um modelo que garante argumentos válidos segundo o esquema num endpoint apenas tende a produzir argumentos válidos noutro. O agente vê a diferença como um resultado de ferramenta que contém um erro de análise e tenta corrigi-lo fazendo outra iteração. Essas iterações de correção são faturadas ao preço total do prefixo. Assim, uma incompatibilidade de formato aparece tanto na fatura como na transcrição.

Os endpoints autoalojados precisam de uma configuração explícita. O servidor compatível com OpenAI do vLLM requer --enable-auto-tool-choice juntamente com um --tool-call-parser correspondente à família do modelo (hermes, mistral, llama3_json e outras), além de um modelo de chat que processe mensagens com a função de ferramenta. A documentação do vLLM é clara quanto às limitações deste caminho: com tool_choice="auto" e sem uma restrição de esquema estrita, o vLLM extrai as chamadas de ferramentas a partir de texto bruto. Por isso, os argumentos podem ocasionalmente estar malformados ou violar o esquema de parâmetros da função. Escolher o parser errado para o seu modelo é um erro de configuração que se manifesta como um agente incapaz de chamar ferramentas. É importante saber isto antes de encaminhar tráfego para esse endpoint. A diferença entre Ollama e vLLM para servir modelos por conta própria é relevante neste caso, porque os dois expõem as chamadas de ferramentas com condições diferentes.

Um fallback no meio da tarefa altera o comportamento sem gerar erro

O encaminhamento de fallback é a funcionalidade que mais provavelmente é ativada por engano. Um gateway é configurado para tentar outro modelo quando o primeiro devolve um limite de taxa ou um erro 5xx e, em seguida, coloca o modelo que falhou em cooldown durante alguns segundos. Para tráfego de chat, isto é exatamente o comportamento esperado. Numa tarefa longa de um agente, significa que a segunda metade da tarefa foi executada por um modelo que não escolheu.

Nada indica que isso aconteceu. A tarefa não falha, o agente não avisa e o status de saída é de sucesso. O resultado é uma tarefa cujo plano foi escrito por um modelo e cujas alterações foram feitas por outro, com um tom e um conjunto de hábitos que mudam a meio. O único sinal fiável é o campo model no log de pedidos do gateway ou nos metadados da resposta. Por isso, se utilizar fallbacks, registe esse campo em cada pedido e consulte-o quando um resultado causar surpresa. Depurar o comportamento sem saber qual modelo o produziu consome mais tempo do que o fallback poupou.

A compressão de contexto contém a mesma armadilha. Muitos agentes resumem o histórico longo chamando um modelo pequeno. Se essa chamada utilizar um modelo diferente ou um prompt de sistema diferente, escreverá a sua própria entrada de cache e não atualizará a entrada da sessão principal. Assim, o turno completo seguinte terá de processar novamente um prefixo que não está em cache. A compressão poupou tokens, mas eliminou o cache.

O custo do encaminhamento existe, mas não é na latência que ele pesa

Os routers acrescentam trabalho por pedido, e é importante ser rigoroso quanto à dimensão desse custo. A DigitalOcean informa que o seu modelo Arch-Router resolve a intenção de encaminhamento em cerca de 51 milissegundos, com uma precisão de encaminhamento de 93.17% na sua própria avaliação. Esses são os valores da DigitalOcean, obtidos nas suas medições e no seu benchmark, não os nossos nem um resultado universal. Aceitando-os como estão, a conclusão é tranquilizadora: 51 milissegundos em quarenta chamadas de agentes representam cerca de dois segundos acrescentados a uma tarefa que decorre durante vários minutos.

Não são esses dois segundos que tornam o encaminhamento dispendioso neste caso. O custo relevante é um router que classifica através de uma chamada completa ao modelo, porque isso acrescenta uma segunda inferência a cada pedido, faturada e colocada em fila como qualquer outra. Por baixo de ambos está a aritmética da cache apresentada acima, que não é custo adicional. É o custo daquilo que o encaminhamento deveria otimizar.

Num servidor que gere pessoalmente, aplica-se a mesma regra, mas com menos margem de manobra. O equivalente local da cache de prompts é o caching de prefixos na KV cache, que reside na memória da GPU. Alojar dois modelos numa GPU divide essa memória entre ambos, pelo que cada modelo mantém uma KV cache menor e expulsa os prefixos mais cedo. Por isso, encaminhar pedidos entre dois modelos locais pode reduzir simultaneamente a taxa de acerto da cache de ambos. Se estiver a dimensionar o hardware para este cenário, a memória e o CPU de que um agente de programação realmente precisa numa VPS é um ponto de partida mais útil do que um router.

A regra de decisão

• Encaminhe entre fornecedores para garantir disponibilidade. Quando a alternativa é um pedido falhado, qualquer custo é aceitável. Fixe o fallback num modelo com o mesmo formato de chamadas de ferramentas, para que o ciclo do agente continue a funcionar, e registe qual modelo atendeu cada chamada.
• Encaminhe entre níveis de custo apenas nos limites das tarefas. Escolher Haiku para uma renomeação e Opus para uma refatoração é uma boa decisão tomada uma vez, antes de a sessão começar. É uma má decisão tomada no turno trinta dessa sessão.
• Fixe um modelo por sessão para qualquer fluxo agentic. O valor de uma sessão está na sua cache aquecida. Trate a troca de modelo como trataria a limpeza dessa cache, porque é isso que acontece.
• Encaminhe subagentes livremente. Um subagente que começa com um contexto pequeno e novo não tem uma cache aquecida a perder, por isso pode ser executado no modelo mais adequado à sua tarefa. Este é o único ponto dentro de um agente em que o encaminhamento tem um custo praticamente nulo.

Para implementar isto, o gateway trata do trabalho: aliases de modelos e listas de fallback explícitas. Uma configuração mínima de proxy LiteLLM é semelhante a esta.

model_list:
  - model_name: agent-primary
    litellm_params:
      model: anthropic/claude-opus-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: agent-standby
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  fallbacks: [{"agent-primary": ["agent-standby"]}]
  num_retries: 2
  cooldown_time: 30

Aponte o agente para agent-primary e ele permanece num único modelo até esse modelo ficar inacessível. As duas entradas usam o mesmo fornecedor, por isso o formato das chamadas de ferramentas não muda quando o fallback é ativado. Ainda assim, aceita uma mudança de nível nesse momento. Essa é uma troca que só vale a pena porque a alternativa é um pedido falhado. Este é o encaminhamento por disponibilidade sem encaminhamento por custo associado, que é a combinação pretendida pela maioria dos agentes de programação. A implementação completa, incluindo chaves e orçamentos, é apresentada em como executar um gateway LiteLLM auto-hospedado no seu próprio VPS, e este artigo não a repete deliberadamente.

Quando um modelo bem escolhido supera qualquer router

O routing é uma solução para a variação na dificuldade dos pedidos. Um agente de programação tem menos variação do que parece, porque a parte dispendiosa de cada chamada é o mesmo prefixo, independentemente do pedido. Quando o prefixo domina, a diferença entre o seu tier mais barato e o mais caro aproxima-se da diferença entre os preços dos respetivos outputs, e o output representa uma pequena parte dos tokens de um agente.

Por isso, a escolha padrão mais sólida é usar um único modelo, escolhido uma vez, com o caching ativado e um TTL (time to live) suficientemente longo para cobrir as pausas enquanto lê um diff. A Anthropic disponibiliza uma escrita de cache de uma hora por 2 vezes o preço base do input. Esta opção compensa-se depois de duas leituras e, muitas vezes, é uma alavanca melhor do que qualquer router. Escolha deliberadamente o tier usando uma comparação direta entre Opus, Sonnet e Haiku e, se o custo continuar a ser o problema, reduza-o com budgets e contextos mais pequenos, como em controlar os custos de agentes de IA num VPS, em vez de trocar de modelo a meio da sessão.

Faça routing quando os pedidos forem independentes e curtos, ou quando os subagentes começarem com contextos novos. Fixe o modelo quando tiver uma sessão longa dedicada a uma única tarefa. A maior parte do trabalho de um agente de programação pertence ao segundo tipo. Por isso, o router que reduz os custos no seu produto de chat pode aumentar silenciosamente os custos neste caso. Se ainda não tiver escolhido o próprio agente, a comparação entre Claude Code, Cursor, Codex e Copilot explica como cada um trata a seleção do modelo. Alguns deles tomam esta decisão por si.

FAQ

Mudar de modelo a meio da sessão faz mesmo perder a cache do prompt?

Sim. As caches de prompts são indexadas por um hash do prefixo do prompt e são armazenadas por modelo. Por isso, um pedido enviado para outro modelo é comparado com um repositório que nunca viu esse prefixo. Não encontra nada e paga o preço total da entrada sem cache. Se o caching estiver ativado, paga também uma escrita na cache. Voltar ao modelo anterior também não recupera a entrada original, porque o tempo de vida predefinido de cinco minutos normalmente já expirou. Verifique os campos cache_read_input_tokens e cache_creation_input_tokens no objeto de utilização da resposta. Numa sessão longa, ler zero tokens em cache é o sintoma.

Encaminhar para um modelo mais barato é alguma vez mais económico para um agente?

Apenas quando não há uma cache aquecida a perder. Uma leitura da cache na Anthropic custa 0.1 vezes o preço base da entrada. Assim, uma leitura de uma cache aquecida no Opus 5 custa menos do que a entrada sem cache no Haiku 4.5. Quando uma sessão tem um prefixo grande em cache, o modelo atual já é a opção mais barata para a entrada. O encaminhamento compensa quando o contexto é novo e pequeno: no início de uma tarefa ou num subagente que transporta apenas o contexto de que precisa.

Por que motivo o meu agente se comportou de forma diferente a meio de uma tarefa?

Verifique se foi ativado um fallback no gateway. Um limite de taxa ou uma resposta 5xx do modelo principal faz com que o gateway tente novamente no modelo de reserva e coloque o modelo principal em cooldown durante alguns segundos. O resto da tarefa passa então a ser executado noutro local. Isto não produz nenhum erro nem aviso, e a tarefa continua a indicar sucesso. O campo model no log do pedido do gateway ou nos metadados da resposta é o único registo fiável. Por isso, registe-o em cada pedido se utilizar fallbacks.

As chamadas de ferramentas funcionam da mesma forma em todos os fornecedores?

Não exatamente. A API Messages da Anthropic usa blocos de conteúdo tool_use e tool_result, enquanto as APIs compatíveis com OpenAI usam um array tool_calls cujo function.arguments é uma string codificada em JSON. Um gateway traduz corretamente os casos comuns, mas as chamadas de ferramentas em paralelo e a aplicação rigorosa do schema variam conforme o fornecedor. No vLLM alojado localmente, tem de definir --enable-auto-tool-choice e um --tool-call-parser compatível com a família do seu modelo. A documentação do vLLM indica que, sem uma restrição de schema rigorosa, o servidor extrai as chamadas de ferramentas do texto não processado. Por isso, os argumentos podem ocasionalmente ficar malformados.

Quanto tempo devo definir para o TTL da cache numa sessão de programação?

Use o tempo de vida predefinido de cinco minutos para trabalho contínuo e a opção de uma hora quando uma pessoa lê os diffs entre turnos. A Anthropic cobra a escrita de cinco minutos a 1.25 vezes o preço base da entrada e a escrita de uma hora a 2 vezes. A leitura custa 0.1 vezes. A escrita de cinco minutos é amortizada por uma única leitura, e a escrita de uma hora por duas. Assim, numa sessão que espera retomar mais tarde, o tempo de vida mais longo normalmente custa menos do que pagar por um prefixo sem cache.