Descoberta de acesso para agentes: spec 0.1

1. Estado e escopo

Versão 0.1, publicada em 7 de outubro de 2026. Esta é uma proposta independente da Wendelmaques. Não é a spec oficial do PAP nem uma extensão aprovada pela Sierra, Meta ou Decagon. O texto e o schema deste perfil podem ser reutilizados sob CC BY 4.0, com atribuição à Wendelmaques.

O perfil descreve somente interfaces implementadas. Não cria sessão, autentica agente, emite credencial, registra consentimento ou executa pagamento. Autorização delegada exige outro contrato e uma nova revisão de segurança.

• Licença CC BY 4.0

2. Publicação e descoberta

• Sirva o manifesto em GET /.well-known/agent-access.json, com Content-Type application/json.
• Sirva o schema em GET /.well-known/agent-access.schema.json. Use JSON Schema 2020-12.
• Em produção, use HTTPS. Não inclua credenciais, saldo, dados pessoais ou configuração privada.
• Permita leitura pública com Access-Control-Allow-Origin: *. Limite o cache a 300 segundos.
• No cabeçalho Link, use rel=describedby para apontar esta spec. Quando houver catálogo de APIs, cartão do agente ou índice documental, inclua neles o manifesto.

• Manifesto deste site
• Schema JSON

3. Identidade e versão

• $schema: URL absoluta do schema servido pelo serviço.
• profile: https://wendelmaques.com/en/artigos/especificacao-acesso-agentes/.
• version: string 0.1. status: string draft.
• name: nome público do serviço, com 1 a 200 caracteres.
• service: origem absoluta do serviço, sem caminho, consulta ou fragmento.

4. Interfaces implementadas

interfaces é uma lista com 1 a 3 objetos. Cada objeto tem somente transport e url. transport aceita website, openapi ou mcp. url é absoluta e tem a mesma origem de service. Não repita um transporte. Não anuncie uma interface que o serviço não oferece.

website aponta a página inicial. openapi aponta a descrição OpenAPI. mcp aponta o endpoint MCP com transporte Streamable HTTP. Um site editorial pode anunciar somente website. A indicação de MCP não implica acesso anônimo a cada ferramenta.

5. Limites de autorização

• authorization.discovery_grants_access: false. Ler o manifesto não concede autoridade.
• authorization.delegated_oauth: false. Esta versão não anuncia OAuth delegado.
• authorization.enforcement: per-operation. Cada operação aplica suas regras de autenticação, recurso e autorização.
• authorization.documentation: URL absoluta do guia de acesso do serviço.
• protocols.pap e protocols.pact: not-implemented. Esta versão não anuncia compatibilidade com eles.

6. Oferta e pagamento

commerce tem uma de duas formas. Para uma API comercial, pricing e billing são URLs absolutas dos preços e da descoberta de pagamento. Para um serviço sob proposta, pricing é by-proposal e contact é a URL absoluta da oferta. Não misture os dois formatos.

A cotação e a resposta da operação prevalecem sobre o manifesto. Antes de pagar, confira preço e condições. Pagamento não substitui autorização por recurso. O manifesto não contém cartão, carteira privada ou token de crédito.

7. Leitura segura e evolução

Antes de seguir um link, o cliente deve validar versão, schema, origem e HTTPS. Deve limitar o documento a 16 KiB e o tempo de leitura a 5 segundos. Deve recusar versão desconhecida para execução automática. Após redirecionamento, deve validar a URL novamente. Não deve encaminhar credenciais para outra origem.

Todos os campos descritos são obrigatórios. Campos desconhecidos são inválidos na versão 0.1. Mudança incompatível exige outra versão e outro schema. Validação estrutural não prova que destinos existam, permissões funcionem ou o serviço seja confiável. Confira os fluxos publicados.