Protocolos para agentes de IA
agents.json: os fluxos da API para agentes, sobre o OpenAPI
As APIs de CNPJ, CEP e leilões publicam /.well-known/agents.json. Cada fluxo aponta um operationId real do OpenAPI, e a prova recusa qualquer um que não exista.
· jsonW 1.3.11
O protocolo
O OpenAPI descreve cada rota de uma API. O agents.json acrescenta os fluxos: para cada objetivo (consultar um CNPJ, achar o CEP de uma rua), que operação chamar e em que ordem. O arquivo fica em /.well-known/agents.json e aponta o OpenAPI como fonte.
O perfil jsonW
É a mesma coluna fluxos que gera o agents.txt. Do item listarSocios|/cnpj/{cnpj}/socios|Listar os sócios|... sai um fluxo com uma ação:
{"id": "listarSocios_fluxo", "title": "Listar os sócios",
"actions": [{"id": "listarSocios_acao", "sourceId": "api",
"operationId": "listarSocios"}]}
A coluna openapi vira a fonte do arquivo:
"sources": [{"id": "api", "path": "https://cnpj.wortic.com/openapi.json"}]
Ida e volta
A prova baixa o OpenAPI publicado de cada API e confere que todo operationId do agents.json existe nele. É a garantia de que um agente que siga o fluxo chega a uma operação de verdade. Só as três APIs abertas ganham o arquivo, porque só elas têm OpenAPI; nas outras 6 propriedades a coluna fica vazia e o gerador não escreve nada.
O que ainda não faz
Os fluxos de hoje têm uma ação cada. O formato permite encadear ações (a resposta de uma vira o parâmetro da outra), e a coluna de texto ainda não tem como dizer isso. Quando houver um fluxo de duas etapas, a coluna vira uma tabela jsonW própria, com uma linha por ação.