APIs prontas para agentes de IA: o que o sistema precisa para que um agente o use com controle

Um cliente pede a um assistente de IA do banco que pague a conta de luz a partir da conta bancária. O assistente —um agente: um programa que, diante de uma instrução, decide por conta própria quais sistemas chamar e em que ordem— chama a API de pagamentos. A resposta demora e a conexão cai. O agente não sabe se o pagamento saiu, então faz o que qualquer programa faria: tenta de novo. Se a API não tem como reconhecer que é o mesmo pagamento, o cliente acaba com uma cobrança em dobro, uma contestação aberta e uma opinião ruim do banco.

Esse cenário não exige um agente malicioso nem um modelo ruim. Basta uma API pensada, como quase todas, para um programador que lê a documentação, conhece o negócio e sabe o que fazer quando algo falha. Um agente pode não ter esse contexto e, então, transforma cada ambiguidade do contrato em uma ação errada.

Troque o pagamento pela emissão de uma apólice, um pedido que baixa o estoque, uma transferência para uma carteira digital ou uma nota fiscal eletrônica (CFDI) que é timbrada perante o SAT, a autoridade tributária do México, e o problema é da mesma família. Este artigo é para quem responde por esses sistemas em um banco, uma fintech, uma seguradora, uma rede de varejo ou qualquer empresa regulada.

Cada vez mais APIs vão ter esse novo consumidor. Na pesquisa da Postman de 2025 —um fornecedor de ferramentas de API, com mais de 5.700 participantes—, 24% dos desenvolvedores disseram projetar as APIs pensando em agentes; 60% as projetam principalmente para pessoas [1]. Este artigo explica o que falta a uma API para que um agente a use com controle, quais dessas peças já são padrão e quais não, e como chegar lá sem reescrever os sistemas.

Conectar não é o mesmo que preparar

Hoje é fácil «conectar» uma API a um agente. O protocolo MCP, que já explicamos neste blog, e os gateways de vários fornecedores —Microsoft, AWS, Google, Kong e Cloudflare, entre outros— podem converter um contrato OpenAPI em ferramentas que um agente chama [2]. Um contrato, neste contexto, é a descrição formal, legível por uma máquina, do que cada operação de uma API faz e do que ela aceita.

Converter o contrato resolve a conexão, não o controle. Um preprint acadêmico analisou 116 servidores MCP oficiais e 80 contratos OpenAPI. Nessa amostra, 92% dos servidores apenas envolviam a API do jeito que ela estava e expunham uma mediana de 19% das operações. O interessante veio depois: quando os autores corrigiram automaticamente os contratos —descrições, parâmetros, agrupamento—, a proporção de ferramentas que funcionavam bem subiu de 76% para 94,2% [3].

A lição: o primeiro gargalo não é o conector, é a qualidade do contrato. Converter 200 operações em 200 ferramentas não dá a um agente 200 capacidades; dá 200 oportunidades de errar.

As sete propriedades de uma API que um agente consegue usar

1. Explica a si mesma

Um programador pode perguntar o que significa o parâmetro type. Um agente, no melhor caso, deduz; no pior, adivinha. Por isso cada operação precisa dizer o que faz para o negócio, e não apenas quais tipos de dados recebe: «Cancela o pagamento agendado se ele ainda não foi executado; os pagamentos já executados são estornados por outra operação». O OpenAPI 3.2, a especificação vigente para descrever APIs, oferece os lugares para escrever isso: um identificador estável por operação, descrições, exemplos e a forma de declarar os avisos que a API envia quando um processo longo termina [4]. O preprint citado acima é justamente evidência de que reparar essas descrições melhora o desempenho do agente [3].

Um detalhe que quase ninguém menciona: a própria especificação do MCP adverte que as descrições e anotações de uma ferramenta não são confiáveis, a menos que venham de um servidor de confiança [6]. Uma ferramenta que diz de si mesma «sou somente leitura» não se torna segura só por dizê-lo. A segurança fica na API, não na descrição.

2. É consistente

Se uma operação devolve datas em um formato e outra em outro, o agente precisa aprender cada exceção. E a diferença entre «não sei quem é» e «sei quem é, mas não tem permissão» importa mais do que parece: diante da primeira, o agente tenta renovar a credencial; diante da segunda, deveria parar ou pedir autorização. Uma API que as confunde manda o agente renovar credenciais em círculos, gastando cotas e enchendo registros. Essa diferença está definida no padrão HTTP (os códigos 401 e 403, no RFC 9110) [7], e o guia do IETF para construir sobre HTTP pede que não se reinventem esses significados [8].

3. Os erros ensinam a corrigir

Quando uma chamada falha, a mensagem de erro é o guia mais direto que o agente tem. «Entrada inválida» o manda testar ao acaso; «o valor deve ser maior que zero e menor que o limite diário da conta» permite que ele se corrija em uma tentativa.

Isso já tem padrão: o RFC 9457 (2023) define um formato de erro que uma máquina consegue ler —tipo de problema, título, status e detalhe, mais os campos de que cada API precisar— e substituiu o RFC 7807 [9]. Não é preciso inventar um esquema próprio; é preciso usar o que já existe, em todas as operações, e dizer em cada erro se vale a pena tentar de novo. Com equilíbrio: o erro deve ser específico sem expor o interior do sistema.

4. Tentar de novo não duplica

Os agentes tentam de novo; faz parte de como funcionam. Se uma chamada cai, eles não sabem se a operação foi aplicada. Numa consulta, não acontece nada. Num pagamento, numa apólice ou numa movimentação de estoque, uma nova tentativa pode executar a operação duas vezes.

A solução conhecida é a chave de idempotência: o cliente envia um identificador único com cada operação e, se repetir a chamada com a mesma chave, a API devolve o resultado original em vez de executá-la outra vez. Antes de implementá-la, convém saber duas coisas:

• Não é padrão. O rascunho do IETF para o cabeçalho Idempotency-Key chegou à versão 07 em outubro de 2025 e hoje consta como expirado e arquivado, sem ter se tornado RFC [10]. Por isso cada API precisa publicar regras próprias: por quanto tempo guarda a chave, como compara a requisição repetida e o que responde se a mesma chave chega com outro conteúdo ou enquanto a primeira ainda está em andamento. O rascunho distinguia esses casos com respostas diferentes [10].
• O importante é o que acontece quando algo falha. A Stripe, a referência no assunto, guarda o resultado da primeira execução mesmo que tenha sido um erro do servidor [11]. Em palavras simples: se a primeira tentativa ficou em dúvida, a nova tentativa não cobra de novo; responde ao cliente «o resultado ficou neste estado, verifique antes de tentar outra coisa».

E nem tudo deve ser repetido. O Google, no guia de design de APIs que publica, repete automaticamente os erros transitórios —indisponibilidade, prazos vencidos— e considera a cota esgotada, em geral, como, em geral, um erro que não deve ser tentado de novo, salvo casos documentados [12]. Se a API não diz o que pode ser tentado de novo, o agente vai adivinhar.

5. Responde sempre com a mesma forma

Um agente lê texto livre sem problema; o que lhe custa é uma estrutura que muda: um campo que às vezes é texto, às vezes objeto e às vezes não vem. Uma lista vazia deve ser uma lista vazia, não a ausência da lista. As operações que demoram precisam de um padrão próprio: responder de imediato que a requisição foi aceita, com um lugar onde consultar o andamento, em vez de deixar o agente esperando.

E, para uma empresa regulada, o estado de uma operação deveria distinguir pelo menos cinco desfechos: rejeitada, não iniciada, em andamento, concluída e resultado desconhecido. Este último é o que mais se esquece e o que mais problemas causa, porque é justamente o que provoca a nova tentativa do exemplo inicial.

Quando um trâmite envolve várias operações —um cadastro de cliente que passa por três sistemas, por exemplo—, a especificação Arazzo permite descrever o fluxo completo, passo a passo, para que o agente não precise deduzir a ordem [18].

6. Avisa quanto lhe resta

Um agente com um erro na lógica pode fazer milhares de chamadas em uma noite, e cada uma consome capacidade da API e, muitas vezes, também tokens do modelo, que alguém paga. Se a API informa em cada resposta quanto resta da cota e quando ela é renovada, o agente pode frear antes de bater no limite. Quando bate, a API pode responder com o código 429 («muitas requisições», RFC 6585) e incluir o cabeçalho Retry-After para indicar quando voltar [5][7]. O GitHub, por exemplo, pede que se espere esse tempo e, se ele não vier, que se alongue a espera de forma crescente; insistir pode bloquear a integração [14].

O padrão de cabeçalhos para comunicar a cota continua em rascunho no IETF, na versão 11 de maio de 2026, e a forma mudou entre versões [15]. O sensato é escolher uma convenção, documentá-la e aplicá-la da mesma forma em todas as operações.

7. Avisa antes de ser descontinuada

As APIs mudam. Um programador lê o e-mail que anuncia a descontinuação de uma versão; um agente não. Hoje isso já tem padrão: o cabeçalho Deprecation foi publicado como RFC 9745 em 2025, e o cabeçalho Sunset, que indica quando a API deixará de responder, como RFC 8594 [16][17]. Com eles, um agente pode detectar a tempo que deve migrar para a nova versão.

O que já é padrão e o que não é

Esta tabela é o que mais convém ter à mão antes de projetar. Misturar um rascunho com um padrão é a forma mais rápida de construir algo que depois será preciso mudar.

Padrão: RFC publicado pelo IETF na trilha de padrões. Rascunho: trabalho em andamento que pode mudar ou ser abandonado. RFC informativo: guia que não obriga. Nenhum deles é, por si só, uma obrigação legal.

As linhas marcadas como padrão não admitem muito debate: são a referência que convém seguir. As linhas em rascunho são decisões de design que cada empresa precisa tomar e documentar, e são as que mais variam de uma organização para outra.

Como fica em cada setor

As sete propriedades são as mesmas em toda parte; o que muda é o que quebra quando elas faltam. Cinco cenários, um por setor, ilustrativos e sem cliente:

Em todos os casos se repete o padrão: uma API com estados explícitos reduz o risco de que uma nova tentativa cause dano e trabalha junto com os controles de identidade, autorização e conciliação que veremos a seguir.

A segurança não pode ser deixada para o modelo

Aqui está o ponto que mais pesa para um banco, uma fintech, uma seguradora, uma rede de varejo com dados de milhões de clientes ou qualquer empresa regulada: um agente pode ser enganado pelos dados que lê. Um e-mail, um documento ou a resposta de outra ferramenta podem trazer instruções escondidas, e o agente pode segui-las. Isso se chama injeção indireta de instruções, e a OWASP a coloca como o primeiro risco das aplicações com modelos de linguagem [22].

O problema é que não existe detector infalível, e a própria OWASP o reconhece [22]. Um grupo de pesquisadores atacou doze defesas publicadas, várias com sucesso reportado próximo de zero, e superou 90% de sucesso contra a maioria quando adaptou os ataques [23]. O instituto de segurança de IA do NIST encontrou algo parecido em um ambiente simulado de escritório: diante do mesmo modelo, o melhor ataque conhecido teve sucesso em 11% dos casos e um ataque novo, em 81% [24]. A lição não é uma taxa geral de vulnerabilidade: é que uma defesa testada contra ataques conhecidos não está testada. E o caso EchoLeak, em um assistente corporativo de uso massivo, mostrou que um único e-mail, sem que ninguém clicasse, podia extrair dados internos [25][34].

A conclusão prática não é «não use agentes». É conter o dano na API, que é onde a empresa tem o controle, em vez de prometer que o modelo nunca vai errar. Começa-se por separar o que um agente pode fazer em três níveis:

E, sobre essa separação, quatro controles que vivem na API, não no modelo:

• Identidade própria para cada agente. Uma credencial de máquina, não a de uma pessoa. Quando o agente atua em nome de um cliente ou de um funcionário, a troca de tokens permite representar quem delegou a quem [21]; manter esse registro é uma decisão de configuração e de auditoria que é preciso exigir. E as credenciais podem ser atadas a quem as usa, para que uma credencial roubada não sirva a outra pessoa [19][20]. O incidente da integração Salesloft Drift, em 2025, foi justamente isso: credenciais de uma integração roubadas e usadas em consultas que pareciam válidas [26]. É a mesma disciplina de acessos que convém aplicar às pessoas, e a explicamos em Controlar quem entra.
• Permissões mínimas por operação. Um agente que consulta estoque não precisa poder apagar clientes.
• Valores, limites e regras de autorização na API, fora do modelo.
• Registro de auditoria de cada ação: qual agente, em nome de quem, com qual permissão, o que pediu, quem aprovou e o que aconteceu.

A especificação do MCP vai na mesma direção: quando a autorização do protocolo é usada, exige validar que a credencial foi emitida para aquele servidor e proíbe repassar a credencial do usuário a outros serviços [6].

No México, além disso, há lei

Duas normas mudam a conversa. A primeira se aplica a todos os setores; a segunda, ao setor financeiro. Não substituem a revisão da área jurídica, mas convém tê-las no radar desde o design:

• Para bancos e fintechs, a Ley Fintech (Ley para Regular las Instituciones de Tecnología Financiera, a lei mexicana que regula as instituições de tecnologia financeira) obriga, no artigo 76, a compartilhar dados por meio de APIs padronizadas, em três camadas: dados abertos, agregados e transacionais. O desenvolvimento regulatório não é uniforme: depende do tipo de entidade, do dado e da autoridade. O Banxico, por exemplo, emitiu em 2020 disposições que contemplam as três camadas para as sociedades de informação de crédito e as câmaras de compensação [13]. E o texto da lei já traz um controle que é exatamente o que um agente exige: o acesso de um terceiro é interrompido assim que o cliente retira o consentimento, são detectadas vulnerabilidades ou o terceiro descumpre, e a interrupção é notificada à autoridade em no máximo duas horas [27]. Para as interfaces sujeitas a esse artigo, poder revogar um acesso sem manobras manuais complicadas não é luxo; para as demais, é um controle que vale a pena ter.
• Para todos os setores —seguros e varejo incluídos—, a nova Ley Federal de Protección de Datos Personales en Posesión de los Particulares (LFPDPPP, a lei mexicana de proteção de dados pessoais em poder de particulares), publicada em março de 2025, dá ao titular o direito de se opor a um tratamento automatizado que, sem intervenção humana, avalie aspectos como a situação econômica ou o comportamento da pessoa e lhe cause efeitos jurídicos indesejados [28]. Se um fluxo com agentes faz esse tipo de avaliação, é preciso revisá-lo frente a essa regra. E, em qualquer caso, a lei pede medidas de segurança proporcionais ao risco: o uso de dados por um agente é parte do tratamento e entra na mesma análise de riscos e controles [28].

Na maioria dos casos, os sistemas não são reescritos: recebem uma fachada

Nenhum banco vai reescrever o core, nenhuma seguradora o sistema de apólices e nenhuma rede o ERP ou o ponto de venda para que um modelo de linguagem os use e, na maioria dos casos, não é necessário. O caminho que a literatura de modernização recomenda —e que os próprios fabricantes seguem— é uma fachada: uma camada que expõe ao agente operações de negócio claras —consultar um saldo, cotar uma apólice, registrar uma devolução, iniciar um pagamento, consultar o andamento de uma nota fiscal— e que por dentro traduz para a linguagem do sistema existente [29].

Três decisões definem se essa fachada ajuda ou atrapalha:

• O que se expõe. Operações de negócio bem delimitadas, não tabelas nem transações internas genéricas. Um agente com acesso a «executar qualquer transação» não é um agente com capacidades: é um risco.
• Quais responsabilidades ficam na fachada e quais no sistema de origem. O guia da Microsoft sobre esse padrão adverte que a camada de tradução acrescenta latência e mais um serviço para operar, e recomenda não transformá-la no lugar das regras de negócio [29]; se ela acabar decidindo o que antes o core decidia, vira outro sistema legado.
• Com que evidência. Cada operação exposta precisa poder demonstrar o que o contrato dela promete: que não duplica, que pode ser revogada, que deixa rastro.

Os fabricantes vão nessa direção: a SAP oferece uma camada de gestão de APIs para colocar autenticação, cotas e monitoramento sobre serviços existentes [30], e a IBM expõe sistemas de mainframe como APIs descritas com OpenAPI [31]. A tecnologia da fachada existe; o mais difícil —e onde mais se erra— é decidir o que expor, com quais regras e com qual evidência.

O que acontece se nada for feito

As áreas de negócio não vão esperar. Se a API não está pronta, alguém vai conectar um agente de qualquer maneira: com uma credencial pessoal, sem registro de auditoria e com mais permissões do que precisa. O resultado típico não é um ataque sofisticado; é uma cobrança duplicada que termina em uma contestação, uma cota esgotada de madrugada ou uma credencial de integração que vaza, como nos incidentes citados acima. Preparar a API antes costuma custar menos do que explicar depois.

Como saber se está funcionando

Um acerto isolado não diz nada; o que mede a confiança é a consistência. O benchmark τ-bench, de 2024, propôs medir quantas vezes um agente resolve a mesma tarefa quando ela é repetida. Nos testes, um modelo de ponta da época resolvia menos da metade das tarefas e, no domínio de comércio, menos de um quarto quando era preciso acertar oito vezes seguidas [32]. Os números daquele ano já mudaram; o método continua sendo o correto: medir tarefas completas, várias vezes, com o estado final, e medir à parte as tentativas de ataque [33].

Desconfie das metas redondas que circulam em materiais de fornecedores, como «85% de sucesso na primeira tentativa» ou «menos de 1,5 novas tentativas». Não encontramos nenhuma fonte independente que as sustente. As metas se fixam com dados próprios.

Por onde começar

1. Para o diagnóstico, priorize por risco. As operações de escrita —pagamentos, apólices, pedidos, estoque, notas fiscais— são as que mais podem causar dano se um agente as usa mal; por isso são revisadas primeiro.
2. Para o primeiro caso de uso, escolha algo delimitado. Uma consulta, ou uma operação reversível e com aprovação explícita. O agente que movimenta dinheiro vem depois, com evidência.
3. Corrija no próprio lugar o que for possível. Acrescentar descrições, erros padronizados e cabeçalhos de cota costuma ser compatível com os clientes atuais, porque a maioria ignora os campos novos; ainda assim, testa-se antes contra as integrações existentes. Para equipes que programam em TypeScript, a lição «O servidor» do nosso curso aberto pratica exatamente isso: códigos de status e contratos que não expõem dados internos.
4. Coloque uma fachada onde não for possível mexer, com operações de negócio bem delimitadas, idempotência e registro de auditoria.
5. Teste com agentes reais e meça a consistência antes de liberar o acesso à produção.

Saber qual padrão usar é a parte fácil. O difícil é saber quais operações estão prontas, quais podem ser corrigidas no próprio lugar, quais precisam de uma fachada e quais controles não podem ser delegados a um agente. É isso que revisamos em um diagnóstico: entregamos o mapa das operações críticas, os riscos de controle que encontramos e a ordem em que convém tratá-los, para que TI, segurança, risco e negócio decidam com a mesma informação, buscando sempre não reescrever os sistemas.