Pular para o conteúdo
jsonW Paper GitHub

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.

agents.json (Wildcard, GitHub) →