A maior parte das APIs modernas ainda opera como se o cliente fosse obrigado a falar exatamente a língua do servidor.
Se a rota estiver errada, retorna 404.
Se o método HTTP estiver errado, retorna 405.
Se o payload vier com um campo diferente do schema esperado, retorna 400.
Se a versão da API não existir, retorna erro.
Se o cliente enviar mail em vez de email, a API simplesmente falha.
Esse comportamento é tecnicamente correto, mas arquiteturalmente pobre.
Ele parte da premissa de que toda divergência entre cliente e servidor é um erro definitivo. Mas, em sistemas reais, muitas falhas não são falhas de intenção. São falhas de tradução.
O cliente sabe o que quer fazer. O sistema também tem uma rota, entidade ou comportamento capaz de atender aquela intenção. O problema está no meio: na forma como a intenção foi codificada em HTTP, JSON, rota, método, versão, campo ou tipo.
É nesse espaço que entra o conceito de Intent-based Healing, ou I-bH.
O que é Intent-based Healing?
Intent-based Healing é uma abordagem arquitetural em que o sistema tenta recuperar a intenção original por trás de uma requisição imperfeita antes de rejeitá-la.
Em vez de tratar todo desvio como erro terminal, o runtime executa um ciclo de interpretação, correção, validação e auditoria.
A ideia não é aceitar qualquer coisa. Também não é esconder erros do cliente. O objetivo é separar três coisas que normalmente são confundidas:
- erro de intenção;
- erro de tradução;
- erro de permissão ou segurança.
Um erro de intenção acontece quando o cliente realmente pediu algo impossível ou proibido.
Um erro de tradução acontece quando o cliente pediu algo válido, mas expressou isso com uma rota errada, um campo diferente, uma versão incompatível ou um verbo HTTP inadequado.
Um erro de permissão acontece quando a intenção pode até ser clara, mas o cliente não tem direito de executá-la.
O Intent-based Healing atua apenas no segundo caso: quando a intenção é recuperável, validável e segura.
De APIs determinísticas para APIs orientadas por intenção
Roteadores tradicionais funcionam como tabelas de decisão binárias.
A requisição bate exatamente com a rota registrada? Executa.
Não bate? Erro.
O método HTTP é o esperado? Executa.
Não é? Erro.
O payload passa no schema? Executa.
Não passa? Erro.
Esse modelo é simples, previsível e eficiente. Mas ele também é frágil, principalmente quando sistemas precisam lidar com clientes heterogêneos, versões antigas, SDKs incompletos, integrações externas, automações, agentes e interfaces conversacionais.
Em uma arquitetura orientada por intenção, a API deixa de ser apenas uma superfície sintática e passa a ser uma camada de negociação semântica.
O servidor não pergunta apenas:
“Essa requisição está perfeita?”
Ele também pergunta:
“Essa requisição representa uma intenção conhecida, segura e recuperável?”
Essa mudança é pequena na superfície, mas profunda na arquitetura.
Intent-based Healing não é gambiarra
Existe um risco óbvio nesse tipo de ideia: transformar a API em um sistema permissivo demais, imprevisível e difícil de auditar.
Por isso, Intent-based Healing precisa seguir algumas regras.
Primeiro, toda cura deve ser explícita. Se o sistema corrigiu uma rota, renomeou um campo ou inferiu um método HTTP, isso precisa gerar telemetria.
Segundo, toda cura precisa ser validada novamente. O sistema não deve corrigir e executar diretamente. Ele corrige em memória, reexecuta a validação e só então chama o handler final.
Terceiro, toda cura precisa ter limite. Nem todo erro deve ser recuperado. Se a similaridade for baixa, se houver ambiguidade, se a intenção exigir autorização adicional ou se a correção puder gerar efeito colateral perigoso, a requisição deve falhar.
Quarto, toda cura precisa ser idempotente quando envolver escrita. Um retry ou uma correção automática não pode duplicar transações, pedidos, pagamentos ou mutações.
Quinto, toda cura deve ser observável. O sistema precisa saber quais clientes estão errando, quais rotas são mais corrigidas, quais campos são mais mapeados e quais integrações precisam ser atualizadas.
Sem isso, Intent-based Healing vira mágica perigosa.
Com isso, ele vira uma camada de robustez semântica.
O Intent-Based Router como exemplo de I-bH
Um exemplo prático de Intent-based Healing é o Intent-Based Router, especificado no contexto do AllasCode Institute / FullAgenticStack, no pacote experimental @allascodeintitute/routes2gateway.
O Intent-Based Router é um motor de execução de APIs que prioriza a intenção do cliente sobre a precisão sintática da requisição.
Ele não substitui validação, schema, autorização ou roteamento determinístico. Ele adiciona uma camada anterior de autocorreção controlada.
A função dele é interceptar falhas comuns de rota, método, versão, payload e protocolo, tentando recuperar a intenção provável do cliente antes de retornar erro.
Em vez de operar apenas com a lógica:
request -> router -> handler | 404
ele opera com uma lógica mais próxima de:
request
-> exact route match
-> if fail: intent recovery
-> route healing
-> payload healing
-> protocol healing
-> validation
-> handler
-> telemetry
O erro deixa de ser o primeiro resultado. Ele passa a ser o último recurso.
Route Healing: corrigindo a intenção de navegação
A primeira camada do Intent-Based Router é o Route Healing.
Ela atua quando a API não encontra uma rota exata ou quando o método HTTP não corresponde ao handler registrado.
Um exemplo simples é um typo:
POST /api/v1/usres
Um roteador tradicional responderia 404 Not Found.
O Intent-Based Router calcula a similaridade entre /api/v1/usres e as rotas registradas. Se encontrar /api/v1/users com alta confiança, ele pode redirecionar internamente a requisição para o handler correto.
A execução não é silenciosa. O sistema adiciona metadados de correção, como:
X-Intent-Correction: redirected-from-typo
E gera um evento de telemetria:
intent.route_corrected: "Redirected from /usres to /users"
Isso preserva duas coisas ao mesmo tempo: a experiência do cliente e a auditabilidade do sistema.
Outro caso é a inferência de método.
Imagine que o cliente envie:
GET /users/create
Content-Type: application/json
{
"name": "Ana",
"email": "ana@example.com"
}
Tecnicamente, isso está errado. Um GET não deveria carregar um corpo semântico de criação.
Mas a intenção é clara: criar um usuário.
Se existir uma rota POST /users, se o payload for compatível e se a política permitir esse tipo de correção, o roteador pode transmutar a requisição internamente para o método correto.
Isso não significa que o protocolo perdeu importância. Significa que o protocolo virou uma camada corrigível quando a intenção é inequívoca.
Semantic Version Fallback: evitando quebra desnecessária
Outro problema comum em APIs é versionamento.
Um cliente pode solicitar:
GET /api/v3/products
Mas a versão v3 ainda não existe.
Um roteador tradicional retornaria erro. O Intent-Based Router pode verificar se existe uma versão estável compatível, como:
GET /api/v2/products
Se o contrato for compatível, ele serve a resposta da versão anterior com aviso de incompatibilidade ou fallback:
X-Intent-Correction: version-fallback
X-Served-Version: v2
X-Requested-Version: v3
Esse comportamento é importante porque, em sistemas distribuídos, nem sempre todos os clientes atualizam ao mesmo tempo. Um sistema orientado por intenção não precisa quebrar imediatamente quando consegue cumprir a intenção de forma segura com uma versão equivalente.
Payload Healing: corrigindo a intenção dos dados
A segunda camada é o Data Self-Healing, ou Payload Healing.
Aqui, o sistema não corrige a rota, mas o corpo da requisição.
Um exemplo clássico:
{
"name": "Ana",
"mail": "ana@example.com"
}
Se o schema espera email, um validador comum retorna erro:
missing field: email
O Intent-Based Router pode usar um dicionário semântico reverso para procurar campos equivalentes, como:
mail
e_mail
emailAddress
userEmail
contact_email
Se encontrar um equivalente confiável, ele renomeia o campo em memória:
{
"name": "Ana",
"email": "ana@example.com"
}
Depois, reexecuta a validação.
O ponto essencial é este: a cura não ignora o schema. Ela tenta transformar o payload recebido em um payload compatível com o schema e, só então, valida novamente.
Isso permite que a API seja robusta sem se tornar frouxa.
Structural Flattening e Hoisting
Outro tipo comum de erro é o aninhamento excessivo.
A API espera:
{
"userId": 123
}
Mas o cliente envia:
{
"data": {
"user": {
"id": 123
}
}
}
O roteador pode detectar que existe um campo profundo semanticamente compatível com userId e içar esse valor para o nível esperado pelo schema.
Isso é especialmente útil em integrações com ferramentas low-code, SDKs automáticos, agentes de IA e sistemas que empacotam dados dentro de objetos genéricos como data, payload, body, result ou attributes.
O sistema não precisa aceitar qualquer estrutura. Ele precisa apenas reconhecer estruturas recuperáveis.
Type Coercion Inteligente
A coerção de tipos tradicional converte strings para números, números para strings ou strings "true" e "false" para booleanos.
O Intent-based Healing pode ir além disso.
Se um campo booleano isActive recebe:
{
"isActive": "sim"
}
ou:
{
"isActive": "enabled"
}
o sistema pode mapear semanticamente esses valores para true.
Da mesma forma, valores como "não", "disabled", "off" ou "inactive" podem ser interpretados como false.
Isso parece simples, mas é poderoso em sistemas multilíngues, WhatsApp-first, formulários conversacionais e APIs consumidas por agentes.
A intenção do usuário não é enviar uma string. A intenção é afirmar um estado.
Protocol Healing: autocura na camada HTTP
A terceira camada é o Protocol Healing.
Aqui, o roteador atua quase como um proxy reverso inteligente para si mesmo.
Um exemplo é o tratamento de 429 Too Many Requests.
Se um serviço upstream retorna:
429 Too Many Requests
Retry-After: 1
um sistema tradicional repassa o erro ao cliente.
O Intent-Based Router pode verificar se o tempo de espera está dentro do SLA configurado. Se estiver, ele pode segurar temporariamente a requisição em buffer, emitir um status intermediário como 102 Processing em modos compatíveis, aguardar o tempo indicado e tentar novamente.
Isso não é apenas retry. É retry orientado por intenção, porque o sistema considera que a intenção do cliente ainda é válida, apenas temporariamente bloqueada por uma condição operacional.
Idempotency Assurance
Protocol Healing só é seguro se houver garantia de idempotência.
Se o roteador corrigir e reenviar uma requisição POST, ele precisa garantir que essa cura não gere duplicidade.
Por isso, o Intent-Based Router pode gerar e gerenciar automaticamente uma chave:
Idempotency-Key: generated-or-derived-key
Essa chave garante que uma operação de criação, pagamento, pedido ou transação não seja executada duas vezes por causa de retries internos.
Sem idempotência, autocura em APIs de escrita é perigosa.
Com idempotência, ela se torna uma estratégia controlada de resiliência.
Intent Telemetry: toda cura precisa deixar rastro
O Intent-based Healing só faz sentido se for observável.
Cada correção precisa gerar eventos.
Exemplos:
intent.route_corrected
intent.data_healed
intent.protocol_fixed
intent.version_fallback
intent.method_inferred
intent.payload_hoisted
Esses eventos não são apenas logs técnicos. Eles são sinais de desalinhamento entre clientes e contratos.
Se muitos clientes enviam /usres, talvez exista documentação ruim, SDK quebrado ou exemplo errado.
Se muitos payloads enviam mail em vez de email, talvez a API precise aceitar oficialmente esse alias ou melhorar o contrato público.
Se muitos clientes chamam v3 quando só existe v2, talvez exista comunicação prematura de versão.
A telemetria transforma autocura em aprendizado arquitetural.
Esse é o ponto onde o Intent-Based Router se conecta com Adaptive Observability Negotiation, ou AON.
A API não apenas corrige. Ela negocia observabilidade, registra a correção, mede recorrência e permite que o sistema evolua com base nos desvios reais.
Intent-based Healing dentro do FullAgenticStack
No FullAgenticStack, Intent-based Healing não é apenas uma técnica de roteamento. Ele é uma peça de uma arquitetura maior.
Uma intenção pode nascer em linguagem natural, em um payload JSON, em uma mensagem de WhatsApp, em um evento de sistema, em uma chamada HTTP ou em um agente.
O papel do runtime é traduzir essa intenção em execução verificável.
Nesse contexto, o Intent-Based Router é uma aplicação específica do ciclo maior:
Intent
-> Interpretation
-> Binding
-> Healing
-> Validation
-> Execution
-> Telemetry
-> Proof
O roteador trabalha na fronteira entre cliente e sistema. Ele tenta descobrir se uma requisição imperfeita ainda carrega uma intenção válida.
Se carregar, ele cura.
Se não carregar, ele rejeita.
Se houver risco, ele bloqueia.
Se houver ambiguidade, ele pede negociação.
Esse comportamento é diferente de uma API tradicional porque o foco deixa de ser apenas “a requisição está correta?” e passa a ser “a intenção pode ser cumprida com segurança?”.
O limite ético e técnico da autocura
Intent-based Healing precisa ter limites claros.
O sistema não deve corrigir intenção financeira sensível sem validação forte.
Não deve trocar destinatários, valores, permissões ou identidades baseado apenas em heurística.
Não deve converter ações destrutivas de forma automática.
Não deve esconder incompatibilidades críticas.
Não deve substituir autenticação, autorização, consentimento ou auditoria.
Uma boa regra é:
Cure syntax.
Negotiate ambiguity.
Reject unsafe intent.
Audit everything.
Essa regra impede que a autocura vire um sistema imprevisível.
De APIs rígidas para contratos vivos
O Intent-Based Router mostra uma mudança importante no design de APIs.
APIs tradicionais são contratos rígidos.
APIs orientadas por intenção são contratos vivos, capazes de interpretar, corrigir, adaptar e aprender com os desvios.
Isso não elimina schemas. Pelo contrário: torna schemas ainda mais importantes.
O schema deixa de ser apenas uma barreira de entrada e passa a ser o alvo de convergência da cura.
A rota deixa de ser apenas um caminho fixo e passa a ser uma hipótese de intenção.
O protocolo deixa de ser apenas transporte e passa a carregar sinais semânticos.
A observabilidade deixa de ser apenas diagnóstico e passa a ser mecanismo de evolução.
Conclusão
Intent-based Healing é a ideia de que sistemas modernos não devem quebrar imediatamente quando conseguem recuperar a intenção real do usuário ou cliente de forma segura.
O Intent-Based Router é um exemplo concreto dessa ideia aplicado ao mundo das APIs.
Ele corrige rotas com fuzzy matching, infere métodos HTTP, faz fallback semântico de versão, cura payloads, corrige tipos, negocia rate limits, garante idempotência e emite telemetria para cada ação de autocura.
Isso representa uma mudança de paradigma.
A API deixa de ser uma parede rígida entre cliente e servidor.
Ela vira uma membrana semântica: validável, observável, autocurável e orientada por intenção.
Em um mundo de agentes, integrações automáticas, interfaces conversacionais e sistemas distribuídos, essa camada deixa de ser conveniência.
Ela se torna infraestrutura.
O futuro das APIs não é apenas REST, GraphQL, gRPC ou eventos.
O futuro é intenção executável, autocura controlada e prova observável de comportamento.
Esse é o papel do Intent-based Healing dentro do FullAgenticStack.
