Pular para o conteúdo
jsonW Paper GitHub

Protocolos para agentes de IA

agents.txt: as capacidades de um site para agentes, geradas do jsonW

Cada fluxo do catálogo jsonW vira um bloco Capability do /.well-known/agents.txt, com rota, protocolo, autenticação e limite, conferido contra o OpenAPI publicado.

· jsonW 1.3.11

O protocolo

O rascunho draft-car-agents-txt-wellknown define um arquivo de texto em /.well-known/agents.txt. Nele o site diz a um agente de IA o que oferece, por qual endereço, com qual protocolo e com qual limite, sem que o agente precise ler as páginas.

O perfil jsonW

Os fluxos ficam numa coluna de texto do catálogo, um por item, separados por ponto e vírgula: operationId|rota|título|descrição. A linha do CNPJ tem três:

fluxos:"consultarCnpj|/cnpj/{cnpj}|Consultar um CNPJ|A ficha pública...;
        listarSocios|/cnpj/{cnpj}/socios|Listar os sócios|...;
        buscarEmpresas|/empresas|Buscar empresas pelo nome|...",
limite:"60 pedidos por minuto por IP sem chave",mcp:"https://cnpj.wortic.com/mcp"

Cada fluxo vira um bloco Capability, e a coluna mcp vira mais um:

Capability: consultar-cnpj
  Endpoint: https://cnpj.wortic.com/cnpj/{cnpj}
  Protocol: REST
  Auth: none
  Rate-Limit: 60/minute
  OpenAPI: https://cnpj.wortic.com/openapi.json

Capability: mcp
  Endpoint: https://cnpj.wortic.com/mcp
  Protocol: MCP
  Auth: none

Ida e volta

A prova lê o arquivo gerado, separa os blocos e confere cada Endpoint contra o OpenAPI que a API publica de fato: as 9 rotas declaradas nas três APIs abertas (CNPJ, CEP e leilões) existem no OpenAPI. Se uma rota sumir da API, a prova falha antes da publicação.

A medida

A linha do CNPJ no catálogo tem 824 bytes. Dela saem 4.620 bytes em seis arquivos para agentes: o agents.txt (1.373 bytes), o agents.json, o agent-permissions.json, o trecho do robots, o valor do Content-Usage e o llms.txt.

O que ainda não faz

O agents.txt é um rascunho individual, ainda sem grupo de trabalho na IETF. O formato pode mudar; quando mudar, muda um arquivo do gerador, e as 9 propriedades saem certas de novo.

AGENTS.TXT: Capability Declarations for Web Agents (IETF Datatracker) →