Este texto é uma releitura de um artigo que publiquei em 2016 (leia o original).
Em 2016 eu escrevi, ainda com o gosto amargo de uma retrospectiva, que tínhamos aprendido API First “da pior forma”. Frontend e backend evoluíram em paralelo a partir de uma especificação inicial, e a conta chegou nos testes integrados: comportamentos que ninguém havia combinado, telas que teriam sido mais simples se a conversa com o backend tivesse começado antes. A lição era clara: o contrato vem antes do código, os consumidores trabalham em paralelo contra esse contrato, e a documentação é um produto, não um anexo.
Dez anos depois, releio aquele texto e percebo que nada disso envelheceu. O que mudou foi quem está do outro lado da chamada.
O novo consumidor não lê a sua documentação. Ele a executa.
Em 2016, os consumidores das nossas APIs eram um aplicativo móvel e um portal web, escritos por pessoas que sentavam ao nosso lado. Hoje, uma parte crescente das chamadas que chega aos gateways que ajudo a projetar não vem de um app: vem de um agente de IA. Um modelo de linguagem recebe uma tarefa, olha a lista de ferramentas que tem à disposição, escolhe uma e chama a sua API. Isso acontece por dois caminhos principais: function calling, em que o modelo devolve um JSON estruturado indicando qual função executar e com quais argumentos, e o Model Context Protocol (MCP), que padroniza como um agente descobre e invoca ferramentas expostas por um servidor.
O detalhe que muda tudo: esse consumidor não lê a documentação com calma numa segunda-feira de manhã. Ele lê o contrato em tempo de execução, a cada chamada, e decide sozinho o que fazer. Se a sua API está bem descrita (OpenAPI completo, nomes claros, erros com significado), ela vira uma ferramenta que um agente consegue usar com confiança. Se não está, o agente vai adivinhar. E agente adivinhando em produção é um problema caro.
As três lições de 2016, revisitadas
- Contrato antes do código. Continua valendo, com um agravante: o contrato agora é literalmente a interface do agente. A especificação OpenAPI que antes servia para gerar um client e alimentar o Swagger UI hoje é convertida, quase sem intervenção, em definições de ferramenta. Cada
descriptionque você deixou em branco é uma decisão que o modelo vai tomar no seu lugar. - Consumidores em paralelo. Antes, mockávamos a API para o time mobile não ficar bloqueado. Hoje eu faço o mesmo para o agente: exponho o contrato via MCP com respostas simuladas e observo como o modelo tenta usá-lo antes de existir uma linha de implementação. É o teste de usabilidade mais barato que já fiz, e ele revela nomes ambíguos e parâmetros confusos em minutos.
- Documentação como produto. Aqui a mudança é de grau, não de natureza. A documentação deixou de ser algo que um humano consulta para virar algo que um modelo consome como entrada. Ela precisa ser correta, completa e legível por máquina, e isso inclui exemplos, restrições e o que acontece quando dá errado.
O que muda no design quando quem chama é um modelo
Alguns ajustes que passei a considerar obrigatórios em qualquer API que vá ser exposta a agentes:
- Descrições em linguagem natural, escritas para o modelo. “Retorna pedidos” não ajuda ninguém. “Lista os pedidos de um cliente nos últimos N dias, ordenados do mais recente; use quando o usuário perguntar sobre compras recentes” diz ao agente quando escolher essa ferramenta e quando não escolher. O mesmo vale para cada parâmetro.
- Idempotência por padrão. Agentes tentam de novo. Às vezes porque a resposta demorou, às vezes porque o modelo decidiu que valia reforçar. Se criar um pedido duas vezes gera dois pedidos, você tem um bug que só aparece em produção. Chaves de idempotência deixaram de ser luxo.
- Erros semânticos. Um 400 com “invalid request” força o modelo a chutar. Um 400 com um código de erro estável e uma mensagem que explique o que corrigir (“data_inicio deve ser anterior a data_fim”) permite que o agente se recupere sozinho, e ainda mostra ao usuário o que aconteceu.
- Respostas enxutas. Cada byte que você devolve vira token na janela de contexto do modelo. Aquele payload de 40 campos que o frontend filtrava com um
selectagora custa dinheiro e atenção. Projete respostas mínimas e ofereça expansão sob demanda. - Poucas ferramentas, bem definidas. Expor 80 operações de um CRUD para um agente é convidá-lo a errar. Agrupe, dê nomes orientados à intenção e esconda o que não faz sentido para aquele contexto.
Governança: o gateway virou a fronteira do agente
Em 2016, colocar um API Management na frente dos serviços era uma decisão de arquitetura sofisticada. Em 2026, com agentes chamando APIs de forma autônoma, virou requisito mínimo. Três coisas que faço questão de resolver no gateway, e não no código de cada API:
- Identidade sem chaves. Chave de API embutida na configuração de um agente é um segredo esperando para vazar. O agente se autentica com identidade gerenciada ou com um token emitido para ele, com escopo restrito e prazo curto. A API só enxerga o token; o gateway valida e propaga quem é o chamador e em nome de quem ele atua.
- Limites de custo, não só de taxa. Rate limit por segundo protege a infraestrutura. Cota de tokens e de chamadas por agente, por dia, protege o orçamento. Um agente em loop pode consumir em uma hora o que um aplicativo consome em um mês.
- Observabilidade por intenção. Não basta saber que a API foi chamada; preciso saber qual agente chamou, em qual conversa, para qual tarefa. Correlacionar a chamada ao contexto do agente é o que permite depurar quando algo sai errado.
Um exemplo conceitual
Imagine uma API de agendamento de serviços com uma única operação relevante: consultar horários disponíveis. Na versão de 2016, o endpoint se chamava GET /slots?d=2026-09-15&t=3, devolvia uma lista de objetos com quinze campos e, se a data fosse inválida, retornava um 500 genérico. Funcionava, porque o desenvolvedor do app sabia o que t significava e tratava o 500 com um “tente novamente”.
Na versão exposta a agentes, a mesma operação vira uma ferramenta chamada listar_horarios_disponiveis, com a descrição “Retorna os horários livres para um tipo de serviço em uma data específica; use quando o usuário quiser marcar ou remarcar um atendimento”. Os parâmetros são data (ISO 8601, obrigatório) e tipo_servico (enumeração com valores nomeados, não números). A resposta traz apenas início, fim e um identificador por horário. Uma data no passado devolve 400 com o código data_no_passado e a mensagem “Informe uma data igual ou posterior a hoje”. Nada disso é tecnologia nova. É o mesmo endpoint, descrito para um consumidor que precisa entender sem perguntar.
Na prática, com .NET 10 e Aspire, o servidor MCP roda como mais um projeto do AppHost, ao lado da API, e o gateway fica entre os dois. O agente, seja construído no Microsoft Foundry ou com o Microsoft Agent Framework, conversa apenas com o gateway. A API nem sabe que quem chama é um modelo. E é assim que deve ser.
O que eu diria para o Alexandre de 2016
Que ele estava certo, e que a lição ia durar mais do que ele imaginava. API First nunca foi sobre a ordem em que os arquivos são criados; era sobre tratar a interface como o produto principal e os consumidores como clientes que merecem um contrato honesto. A diferença é que agora alguns desses clientes leem o contrato em milissegundos, tomam decisões com base nele e não ligam para você quando ficam em dúvida.
E você? Já parou para olhar as suas APIs pelos olhos de um agente e se perguntar se ele conseguiria usá-las sem adivinhar nada? Conta aqui nos comentários o que encontrou.
Deixe um comentário