O agents.json é uma proposta aberta da empresa Wildcard para descrever, a agentes de IA, como usar uma API. Ele não substitui o OpenAPI, a descrição técnica padrão das rotas: ele se apoia nele e acrescenta os fluxos, isto é, que operação chamar para cada objetivo. Este guia é para quem já tem uma API, como uma ferramenta, um diagnóstico ou um sistema que os alunos usam.
Passo 1: confira o OpenAPI
Cada operação do seu OpenAPI precisa de um operationId único, por exemplo gerarDiagnostico. É por ele que o agents.json aponta a operação. Sem operationId, não há onde o fluxo apontar.
Passo 2: o cabeçalho e a fonte
{
"agentsJson": "0.1.0",
"info": {
"title": "Diagnóstico Exemplo",
"version": "1.0.0"
},
"sources": [{
"id": "api",
"path": "/openapi.json"
}],
"flows": []
}Passo 3: um fluxo por objetivo
{
"id": "diagnostico_fluxo",
"title": "Gerar o diagnóstico",
"actions": [{
"id": "diagnostico_acao",
"sourceId": "api",
"operationId":
"gerarDiagnostico"
}]
}Um fluxo pode ter mais de uma ação, quando a resposta de uma vira o parâmetro da seguinte. Comece pelos fluxos de uma ação só.
Passo 4: publique e confira
Salve em /.well-known/agents.json. Depois confira, um por um, que todo operationId citado existe no seu OpenAPI publicado. Um fluxo que aponta para uma operação inexistente faz o agente errar. Um exemplo real no ar: cnpj.wortic.com/.well-known/agents.json.
O que esperar
O agents.json é uma proposta aberta, não um padrão, e cada agente decide se o lê. Se o seu negócio não tem API, este arquivo ainda não é para você; comece pelo llms.txt e pelo agents.txt.
Fonte: agents.json (Wildcard, GitHub).
