O Postman State of the API 2025 traz um dado que resume bem onde a indústria está: 89% dos desenvolvedores usam ferramentas de IA generativa no dia a dia, mas apenas 24% projetam APIs pensando em agentes como consumidores. Pra mim, essa desproporção revela algo mais profundo do que um gap de adoção. A maioria dos times ainda trata APIs como interfaces entre humanos que escrevem código e servidores que processam requisições, quando o consumidor que mais cresce é um modelo de linguagem que precisa descobrir, entender e invocar endpoints de forma autônoma. O artefato que já resolve a maior parte desse problema existe há mais de uma década e se chama OpenAPI.
Quando um agente recebe acesso a ferramentas via function calling, o que ele recebe é essencialmente um subconjunto do que uma spec OpenAPI já contém: nome da função, descrição, schema JSON dos parâmetros, tipos, campos obrigatórios. A sobreposição é quase total. O que muda é o nível de detalhe nas descrições, até porque o consumidor deixou de ser um desenvolvedor lendo documentação e passou a ser um modelo que infere intenção a partir de texto.
Essa convergência está se materializando em ferramentas concretas. Projetos como openapi-mcp-generator e openapi2mcp convertem especificações OpenAPI em servidores MCP funcionais, transformando cada endpoint documentado numa ferramenta que agentes podem invocar via Model Context Protocol. O processo é direto: a spec define o contrato de onde o gerador deriva as definições de ferramenta, e o servidor MCP atua como ponte entre o agente e a API real. O que antes exigia implementação manual de cada tool definition, com descrições escritas à mão e schemas construídos caso a caso, passa a ser derivado automaticamente de um artefato que o time já deveria manter atualizado. A palavra operativa é "deveria", porque a qualidade da spec OpenAPI se torna o fator limitante da capacidade do agente de operar corretamente sobre a API.
O Moonwalk SIG, grupo de trabalho da OpenAPI Initiative pra a próxima geração da especificação, está investigando exatamente essa fronteira. O grupo, que explora o que será a versão 4.x da especificação, vem dedicando o primeiro semestre de 2026 a examinar como documentos OpenAPI podem se tornar nativamente agent-ready, com metadados adicionais pra capability discovery, agrupamento funcional de endpoints pra workflows agênticos, e otimização de descrições pra consumo por LLMs. A direção é clara: a especificação não vai apenas descrever APIs pra que humanos construam integrações. Vai descrever APIs pra que agentes descubram e usem capacidades de forma autônoma. O Arazzo, especificação complementar da OpenAPI Initiative pra workflows, define sequências de chamadas que representam jornadas completas, o que permite a um agente entender não apenas quais endpoints existem, mas em que ordem e sob quais condições eles compõem uma operação de negócio.
O efeito prático mais imediato de usar OpenAPI como spec de agentes é a eliminação de alucinação de parâmetros. Quando o agente opera com strict tool use, modo disponível tanto na API da Anthropic quanto na da OpenAI, o modelo é forçado por constrained sampling a gerar chamadas que respeitam o schema exatamente como definido. Parâmetros com tipo errado, campos inventados, nomes de ferramenta alucinados: tudo isso desaparece quando o schema é rigoroso e derivado de uma spec real. O custo de tokens pra carregar definições de ferramentas no contexto é da ordem de dezenas a poucas centenas de tokens por ferramenta, um custo que se paga na primeira chamada que não falha por erro de formação.
Tem também o problema da manutenção. Uma spec OpenAPI bem mantida é, por definição, documentação viva da API. Quando as definições de ferramentas dos agentes são derivadas dessa spec, qualquer mudança na API (um campo renomeado, um endpoint defasado, um novo parâmetro obrigatório) se propaga automaticamente pras ferramentas que os agentes utilizam. Já vimos esse filme. O cenário alternativo, onde definições de tool são mantidas manualmente em paralelo à API, é a mesma armadilha que a indústria já conhece de documentação desacoplada: funciona no primeiro mês da implementação e diverge progressivamente a partir do segundo deploy.
E a governança não fica atrás. O relatório do Postman registra que 51% dos desenvolvedores citam acesso não autorizado ou excessivo de agentes como a preocupação de segurança mais frequente em APIs. Uma spec OpenAPI inclui definições de segurança, scopes de autorização e pode ser estendida com metadados que controlam quais operações são disponibilizadas a agentes e sob quais condições. A spec funciona como contrato de governança que define o perímetro de atuação autônoma do agente, não apenas como interface técnica.
Alguém poderia chamar de trade-off o fato de que a spec mínima que funciona pra gerar um client HTTP não é a mesma spec que funciona pra orientar um agente autônomo. Descrições como "Gets a resource by ID" são suficientes pra um desenvolvedor que já entende o domínio, mas pra um modelo que precisa decidir se esse é o endpoint correto pra a tarefa que recebeu, a descrição precisa incluir contexto de negócio, pré-condições, efeitos colaterais e relação com outros endpoints. O investimento em qualidade descritiva da spec se torna investimento direto em confiabilidade do agente. Pessoalmente, me soa como mais uma vantagem do que um preço a pagar. Principalmente se o time não é composto apenas por sêniores.
Emerge daí um padrão de spec-driven development aplicado a sistemas agênticos: a especificação formal precede a implementação e documenta o contrato que serve simultaneamente como interface pra humanos, base pra geração de código e definição de capacidades pra agentes. Não à toa: o bloqueio do Fable 5 de três dias atrás, que tirou o modelo do mercado da noite pro dia, é um claro lembrete de que o modelo deve ser tratado como uma peça substituível, mas o contrato não. A resiliência da integração passa por amarrar a capacidade do agente à spec, e não a um modelo específico. Se sua organização mantém specs OpenAPI de qualidade, você já está mais perto de operar agentes confiáveis do que imagina.