Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Rota automática

Status: Ativo Escopo: estado atual Última revisão: 2026-10-10 Responsável: ax-code runtime

A rota automática controla dois comportamentos independentes de roteamento no ax-code:

Roteamento por palavra-chave — ativo por padrão. Troca o agente quando uma mensagem casa com as palavras-chave ou os padrões de um especialista. Dispara em menos de 1 ms e não exige chamada de LLM. É pulado quando o roteamento está desativado de forma explícita, quando o usuário nomeia um agente de forma explícita, ou quando a mensagem é uma continuação sintética que preserva o agente atual.
Roteamento por complexidade — opcional, ligado pelo interruptor de rota automática. Uma chamada leve de LLM classifica cada mensagem como complexidade low, medium ou high. Mensagens de complexidade low são atendidas de forma automática pelo small_model configurado de forma explícita, reduzindo a latência de perguntas simples.

Por padrão, a rota automática está desligada — o roteamento por complexidade fica desativado. O roteamento por palavra-chave é separado deste interruptor e permanece ativo por padrão, a menos que a configuração o desative ou que uma escolha explícita de agente o contorne.

Início rápido

Alterne pela TUI:

Digite /smart-llm no prompt, ou
Pressione Ctrl+P e busque “auto-route”, ou
Clique no indicador Rota automática ligada/desligada na barra de status

A barra de status mostra o estado atual:

Rota automática ligada (texto roxo) — o roteamento por complexidade está ativo
Rota automática desligada (texto branco) — roteamento por complexidade desativado (padrão)

O ajuste persiste entre sessões em ax-code.json.

Como funciona

Fonte da verdade

Esta página resume o comportamento visto pelo usuário. Quando o comportamento mudar, confira a documentação contra:

packages/ax-code/src/agent/router.ts para as regras de roteamento por palavra-chave e classifyComplexity().
packages/ax-code/src/session/prompt.ts para quando o roteamento por palavra-chave é pulado e quando a classificação de complexidade executa.
packages/ax-code/src/server/routes/smart-llm.ts para o comportamento padrão, de ambiente, de configuração e de persistência.
packages/ax-code/src/config/schema.ts para os campos de configuração de roteamento e as notas de descontinuação.
packages/ax-code/src/cli/tui/app.tsx para nomes de comando de barra, apelidos, rótulos e ações da barra de status.
packages/ax-code/test/agent/router.test.ts e os testes de sincronização da TUI para o comportamento esperado de ativação.

Evite descrever o roteamento por palavra-chave e o roteamento de complexidade para modelo rápido como um só recurso. Eles são separados de propósito.

Roteamento por palavra-chave (ativo por padrão, <1 ms)

As mensagens do usuário são comparadas com padrões de palavra-chave e de expressão regular de cada agente especialista (security, architect, debug, perf, devops, test). Se uma correspondência pontuar confiança ≥ 0.4, o agente pode trocar na hora — nenhuma chamada de LLM é feita. Este caminho é independente do interruptor de rota automática, mas é pulado quando o roteamento está desativado, quando o usuário nomeia um agente de forma explícita, ou quando o turno atual preserva um agente existente para continuação sintética.

Roteamento por complexidade (somente rota automática, ~200-500 ms)

Quando a rota automática está ligada, cada mensagem é enviada a um modelo rápido e barato por classifyComplexity(). Essa chamada de LLM devolve uma estimativa de complexidade (low / medium / high):

Mensagens de complexidade low usam de forma automática o small_model configurado de forma explícita
Mensagens medium e high usam o modelo padrão, como de costume
Pulado se small_model estiver ausente ou indisponível
Tempo limite de 1.5 segundo — recua em silêncio se o LLM estiver lento ou indisponível
Todos os erros são capturados em silêncio — nunca bloqueiam o usuário

O roteamento por complexidade é independente do roteamento de agente. Ele não classifica qual agente especialista usar — isso fica inteiramente com o roteamento por palavra-chave.

Com o que a rota automática ajuda

Cenário	Sem rota automática	Com rota automática
“o que esta variável faz?”	Modelo completo usado	complexidade `low` → modelo rápido
“liste todas as exportações deste arquivo”	Modelo completo usado	complexidade `low` → modelo rápido
“procure vulnerabilidades”	A palavra-chave encaminha para security	Igual — o roteamento por palavra-chave sempre dispara
“refatore o módulo de autenticação em 8 arquivos”	Modelo padrão	complexidade `high` → modelo padrão
“esta função está lenta”	Sem correspondência de palavra-chave, sem rota	`low`/`medium` → nível correto de modelo

O roteamento por palavra-chave trata a seleção do agente especialista para palavras-chave técnicas. O roteamento por complexidade seleciona o nível adequado de modelo conforme o quanto de raciocínio a resposta precisa.

Limitações e considerações

Latência

O roteamento por complexidade acrescenta 200-500 ms às mensagens que disparam a chamada de classificação. O roteamento por palavra-chave (sempre ativo) não é afetado — ele retorna em <1 ms de qualquer forma.

Exige um modelo pequeno

O roteamento por complexidade exige uma configuração explícita de small_model. O AX Code não infere um ajudante a partir de nomes de modelo nem move uma fixação indisponível para outro provedor. Sem um ajudante utilizável, a classificação é pulada e o modelo principal selecionado é preservado. Veja Recuperação de modelo.

Uso de tokens

Cada chamada de classificação usa cerca de 100-200 tokens de entrada e 10-20 tokens de saída — desprezível perto da chamada principal de LLM que vem depois.

Não substitui a seleção explícita

A rota automática melhora a seleção automática do nível de modelo, mas não consegue encaminhar para agentes especialistas só com linguagem natural. Para tarefas críticas em que o especialista certo importa, selecionar o agente de forma explícita pelo seletor de agente ou pela menção @agent é mais confiável.

Configuração

Alternar pela TUI

Use /smart-llm ou a paleta de comandos (Ctrl+P → “Ligar ou desligar a rota automática”). A mudança vale na hora e é salva no ax-code.json do projeto.

Arquivo de configuração

{
  "routing": {
    "llm": true
  }
}

Variável de ambiente

AX_CODE_SMART_LLM=true ax-code

A variável de ambiente substitui o ajuste do arquivo de configuração.

Rota automática e outros ajustes

Ajuste	Interação
Modo autônomo	A rota automática funciona de forma independente. O roteamento de agente e a classificação de complexidade acontecem antes das checagens de permissão.
Modo sandbox	Sem interação. A rota automática só afeta qual agente e qual nível de modelo são selecionados, não o que o agente pode fazer.
Seleção de modelo	Mensagens de complexidade `low` usam o `small_model` configurado de forma explícita quando a rota automática está ligada e nenhum modelo está fixado de forma explícita.
Modos de execução	A colocação híbrida (`modes.default: "hybrid"`) é separada: ela escolhe local ou nuvem. Veja Modos de execução.

Quando ligar a rota automática

Ligue se:

Você quer que perguntas simples sejam encaminhadas sozinhas para um modelo mais barato e mais rápido
Você quer reduzir o custo de tokens em trocas de baixa complexidade
Você trabalha com um provedor que tem um modelo pequeno ou flash confiável

Mantenha desligada se:

Você prefere latência zero acrescentada em cada mensagem
Você trabalha offline ou com rede instável
Você quer minimizar o uso de tokens
Você sempre fixa um modelo de forma explícita