Protocolos de agentes: MCP, A2A, Skills, WebMCP e ARD

Aula 1

MCP Server Card

O Model Context Protocol (MCP), criado pela Anthropic em 2024 e hoje adotado por praticamente todos os assistentes e IDEs com agente, define como um agente se conecta a um servidor que oferece ferramentas (tools), dados (resources) e modelos de prompt (prompts). Um servidor MCP remoto é um endpoint HTTP. O problema é que, sem conectar e negociar, o agente não sabe que o servidor existe nem o que ele faz.

O MCP Server Card resolve isso com um documento estático em /.well-known/mcp/server-card.json. A proposta começou como SEP-1649 em outubro de 2025, evoluiu na SEP-2127, aceita pelos mantenedores do MCP em 2026, e é acompanhada por um grupo de trabalho da comunidade. O card descreve o servidor antes de qualquer conexão.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
  "version": "1.0",
  "protocolVersion": "2025-06-18",
  "serverInfo": {
    "name": "exemplo-pedidos",
    "title": "Pedidos da Loja Exemplo",
    "version": "2.3.0"
  },
  "description": "Consulta catálogo, frete e pedidos da Loja Exemplo.",
  "documentationUrl": "https://exemplo.com.br/docs/mcp",
  "transport": { "type": "streamable-http", "endpoint": "/mcp" },
  "capabilities": { "tools": {}, "resources": {} },
  "authentication": { "required": true, "schemes": ["oauth2"] },
  "tools": "dynamic"
}

• serverInfo, transport e capabilities são os campos centrais da proposta.
• tools, resources e prompts podem listar os itens ou valer "dynamic" quando dependem do usuário.
• authentication avisa que é preciso OAuth, que segue a cadeia do módulo 5.
• O arquivo deve ser servido por HTTPS, como application/json, com Access-Control-Allow-Origin: *.
• Anuncie com Link: </.well-known/mcp/server-card.json>; rel="mcp" e, opcionalmente, com DNS-AID (_mcp._agents).

No relatório de exemplo, o scanner tenta quatro caminhos: server-card.json, server-cards.json, mcp.json e a variante sem a pasta mcp. A variedade reflete a evolução da proposta. Publique o caminho atual e, se quiser compatibilidade, redirecione os antigos.

Fontes desta aula: SEP-1649: MCP Server Cards · SEP-2127: MCP Server Cards · Especificação do MCP

Aula 2

A2A Agent Card

Se o MCP conecta um agente a ferramentas, o A2A (Agent2Agent) conecta um agente a outro agente. Proposto pelo Google em 2025 e transferido para a Linux Foundation, chegou à versão 1.0 em 2026. O caso de uso típico: o agente pessoal do usuário conversa com o agente de atendimento da loja, que tem autonomia própria e acesso a sistemas internos.

O ponto de descoberta é o Agent Card, em /.well-known/agent-card.json (versões antigas usavam agent.json).

{
  "name": "Atendimento Loja Exemplo",
  "description": "Responde dúvidas sobre produtos, frete, trocas e status de pedidos.",
  "version": "1.4.0",
  "provider": { "organization": "Loja Exemplo", "url": "https://exemplo.com.br" },
  "supportedInterfaces": [
    { "url": "https://agentes.exemplo.com.br/a2a",
      "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "capabilities": { "streaming": true, "pushNotifications": false },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    { "id": "status-pedido", "name": "Status de pedido",
      "description": "Informa a situação e a previsão de entrega de um pedido.",
      "tags": ["pedidos", "entrega"] }
  ],
  "securitySchemes": {
    "oauth": { "type": "oauth2", "description": "OAuth 2.1 com PKCE" }
  }
}

As diferenças em relação ao MCP Server Card ajudam a escolher. O Server Card descreve um conjunto de ferramentas que o agente do usuário opera diretamente. O Agent Card descreve um agente autônomo com habilidades (skills), que recebe tarefas, pode demorar, pede informações e devolve artefatos. Muitas empresas vão ter os dois: MCP para operações determinísticas (consultar estoque) e A2A para conversas abertas (resolver um problema de entrega).

Fontes desta aula: Especificação A2A · A2A: Agent Discovery

Aula 3

Índice de Agent Skills

Agent Skills são pacotes de instruções que ensinam um agente a executar um tipo de tarefa: um arquivo SKILL.md com nome, descrição e passo a passo, às vezes acompanhado de scripts. O formato foi popularizado pela Anthropic e documentado em agentskills.io. Para empresas, uma skill é uma forma de dizer "é assim que se usa o nosso produto corretamente".

A Agent Skills discovery, um RFC de comunidade liderado pela Cloudflare (versão 0.2.0, em rascunho), define onde publicar essas skills para que agentes as encontrem: um índice em /.well-known/agent-skills/index.json.

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "integrar-api-pedidos",
      "type": "skill-md",
      "description": "Como autenticar e criar pedidos pela API da Loja Exemplo, com tratamento de erros.",
      "url": "/.well-known/agent-skills/integrar-api-pedidos/SKILL.md",
      "digest": "sha256:9f2c..."
    }
  ]
}

• Campos de cada skill: name, type (skill-md ou archive), description, url e digest SHA-256, que permite ao agente verificar que o arquivo não foi alterado.
• No SKILL.md, o front matter tem name (até 64 caracteres, minúsculas e hífens) e description (até 1.024 caracteres).
• Anuncie com Link: </.well-known/agent-skills/index.json>; rel="agent-skills" e libere CORS.
• O relatório de exemplo mostra o scanner tentando primeiro o caminho da versão 0.2.0 e depois o legado /.well-known/skills/index.json.

Fontes desta aula: Cloudflare: Agent Skills Discovery RFC · agentskills.io: especificação

Aula 4

WebMCP: ferramentas dentro da página

Muitos agentes operam um navegador: leem a tela, clicam e digitam. É lento, caro e frágil, porque qualquer mudança de layout quebra o fluxo. O WebMCP propõe que a própria página declare ferramentas que o agente pode chamar diretamente, com nome, descrição e esquema de entrada, executadas pelo JavaScript da página, na sessão do usuário.

A especificação é um relatório de grupo de comunidade do W3C (Web Machine Learning Community Group), editado por pessoas da Microsoft e do Google. Não é padrão W3C, e o Chrome disponibilizou versões de teste para desenvolvedores. Nas versões recentes, a API fica em document.modelContext (rascunhos antigos usavam navigator.modelContext).

document.modelContext.registerTool({
  name: 'calcular-frete',
  description: 'Calcula prazo e preço de frete para um CEP brasileiro.',
  inputSchema: {
    type: 'object',
    properties: { cep: { type: 'string', pattern: '^[0-9]{8}$' } },
    required: ['cep']
  },
  annotations: { readOnlyHint: true },
  async execute({ cep }) {
    const r = await fetch('/api/frete?cep=' + cep);
    return await r.json();
  }
});

• A ferramenta roda no contexto da página, com os cookies e a sessão do usuário. Não é preciso criar uma API separada nem um fluxo OAuth.
• As anotações readOnlyHint e consequentialHint ajudam o navegador a decidir quando pedir confirmação ao usuário.
• Há também uma proposta declarativa, para expor formulários existentes como ferramentas com atributos no HTML.
• Tipos para TypeScript estão no pacote webmcp-types.

O scanner detecta WebMCP procurando o uso da API nos scripts da página. Como é um rascunho que já mudou de nome, use detecção de recurso (if ('modelContext' in document)) e trate a funcionalidade como melhoria progressiva.

Fontes desta aula: WebMCP: especificação · WebMCP no GitHub · Chrome: WebMCP early preview

Aula 5

ARD e o catálogo ai-catalog.json

Com tantos arquivos (Server Card, Agent Card, skills, APIs), surge a necessidade de um índice único. O ARD (Agentic Resource Discovery), projeto na Linux Foundation, sobre o formato AI Catalog, propõe um catálogo em /.well-known/ai-catalog.json que lista todos os recursos de agentes do domínio.

{
  "specVersion": "1.0",
  "host": { "name": "Loja Exemplo", "url": "https://exemplo.com.br" },
  "entries": [
    {
      "identifier": "urn:exemplo:mcp:pedidos",
      "displayName": "Servidor MCP de pedidos",
      "mediaType": "application/mcp-server-card+json",
      "type": "application/mcp-server-card+json",
      "url": "https://exemplo.com.br/.well-known/mcp/server-card.json",
      "representativeQueries": ["qual o status do meu pedido?", "quanto custa o frete para 01310-100?"]
    },
    {
      "identifier": "urn:exemplo:a2a:atendimento",
      "displayName": "Agente de atendimento",
      "mediaType": "application/a2a-agent-card+json",
      "type": "application/a2a-agent-card+json",
      "url": "https://exemplo.com.br/.well-known/agent-card.json"
    }
  ]
}

Cada entrada tem um identificador URN, um nome, o tipo de mídia do recurso e uma URL (ou o conteúdo inline). O catálogo base chama o tipo de mediaType e a camada ARD usa type e acrescenta representativeQueries, de 2 a 5 exemplos de pedidos que o recurso atende, úteis para mecanismos de busca de agentes. Emitir os dois nomes evita incompatibilidade.

Os cinco caminhos de descoberta do ARD

O relatório de exemplo mostra que o scanner tenta todos, em ordem:

1. Diretiva Agentmap: no robots.txt apontando o catálogo.
2. <link rel="ai-catalog" href="..."> no HTML da página inicial (ou o cabeçalho Link equivalente).
3. O caminho /.well-known/ai-catalog.json.
4. Registro TXT em _catalog._agents.<domínio>.
5. Registro SRV em _search._agents.<domínio>, para quem oferece um serviço de busca de agentes.

O catálogo aceita uma assinatura opcional (trustManifest, JWS sobre o JSON canonicalizado). Assinar com uma chave publicada no mesmo domínio acrescenta pouco, porque quem controla o domínio controla os dois; a assinatura ganha valor com chaves de terceiros confiáveis.

Fontes desta aula: Agentic Resource Discovery · AI Catalog no GitHub · specification.website: ARD

Aula 6

Personal Agent Protocol

O último item da categoria é o mais ambicioso. O Personal Agent Protocol, apelidado de Poppy, é um protocolo aberto (Apache 2.0, em rascunho 0.4) para que agentes pessoais e empresas trabalhem juntos: a empresa declara como agentes podem interagir com ela, e o agente do usuário usa essa declaração para entrar na conta e agir dentro dos limites que o usuário e a empresa aceitaram. Ele cobre descoberta, identidade, acesso à conta e interação por APIs, navegação web e conversas com o agente da empresa.

{
  "protocol_version": "0.4",
  "organization": {
    "name": "Loja Exemplo",
    "domain": "exemplo.com.br",
    "logo_uri": "https://exemplo.com.br/logo.png"
  },
  "auth": {
    "scopes": {
      "pedidos:ler": "Ver seus pedidos",
      "pedidos:criar": "Fazer pedidos em seu nome"
    },
    "scope_hints": {
      "pedidos:ler": { "changes": "none", "personal_data": true }
    }
  },
  "agent": {
    "protocols": [{ "type": "poppy", "endpoint": "https://api.exemplo.com.br/poppy/conversations" }]
  },
  "apis": [
    { "type": "openapi", "url": "https://api.exemplo.com.br/openapi.json", "description": "API de pedidos" },
    { "type": "mcp", "url": "https://mcp.exemplo.com.br/mcp", "description": "Servidor MCP" }
  ]
}

• protocol_version é obrigatório; é preciso declarar pelo menos um entre agent, apis e web.
• scope_hints informam se um escopo altera dados e se envolve dados pessoais, o que ajuda o agente a pedir consentimento de forma honesta.
• A autenticação se apoia nos metadados OAuth do módulo 5 (RFC 9728 e RFC 8414), e as requisições carregam um cabeçalho Poppy-Session com um JWT.
• O próprio texto avisa que qualquer parte pode mudar antes da versão estável, inclusive sem compatibilidade.

Fontes desta aula: Personal Agent Protocol · Poppy: introdução

Erros comuns

• Card apontando para endpoint que não responde. Pior que não ter card.
• Ferramentas que escrevem dados sem anotação. Marque o que é somente leitura e o que tem consequência, para o agente pedir confirmação.
• Descrições vagas. "Ferramenta de pedidos" não ajuda; "cria um pedido a partir de um carrinho e retorna o link de pagamento" ajuda.
• Esquecer CORS nos arquivos .well-known. Agentes em navegador não conseguem ler.
• Tratar rascunho como estável. Fixe $schema e versões e acompanhe as mudanças.
• Expor ferramentas internas. Tudo o que está no card é público. Ferramentas administrativas não entram.

Aplicação prática: anuncie o que um agente pode fazer

1. Liste as três tarefas mais valiosas que um agente poderia fazer no seu site (consultar, cotar, comprar, agendar).
2. Para cada uma, escolha o mecanismo: ferramenta MCP, ferramenta WebMCP na página ou habilidade de um agente A2A.
3. Publique o card correspondente e teste com um cliente real (por exemplo, adicionando o servidor MCP a um assistente).
4. Se tiver dois ou mais recursos, publique /.well-known/ai-catalog.json e o <link rel="ai-catalog">.

Siglas e termos deste módulo

MCP:

Model Context Protocol, protocolo para conectar agentes a ferramentas e dados.

SEP:

Specification Enhancement Proposal, proposta de mudança na especificação do MCP.

A2A:

Agent2Agent, protocolo de comunicação entre agentes.

ARD:

Agentic Resource Discovery, descoberta de recursos de agentes.

URN:

Uniform Resource Name, identificador persistente.

JWS:

JSON Web Signature, assinatura digital em JSON.

JWT:

JSON Web Token, token assinado com informações de sessão.

CORS:

Cross-Origin Resource Sharing, permissão para leitura entre origens no navegador.