Ponte A2A

MCP é o limite das ferramentas. A2A é o limite dos agentes. O pacote A2A do MCP Fusion permite que um conector participe de uma rede Agent2Agent sem reescrever suas ferramentas: o registro continua sendo a fonte das capacidades, e a ponte expõe o protocolo de tarefas voltado para agentes.

Compile um Agent Card

import { compileAgentCard, A2AHandler } from '@mcpfusion/a2a';

const card = compileAgentCard(
  {
    name: 'billing-agent',
    version: '1.0.0',
    url: 'http://localhost:3001',
  },
  registry.getBuilders(),
  promptRegistry,
  resourceRegistry,
);

O compilador deriva habilidades a partir dos nomes dos builders e dos metadados das ações. O card é servido em /.well-known/agent-card.json; o caminho legado é /.well-known/agent.json. As solicitações A2A JSON-RPC usam /a2a, e o pacote se identifica como protocolo 1.0.0.

A configuração opcional bridge descreve como o card é alcançado por outra ponte. Não mantenha manualmente uma segunda lista de capacidades: compile a partir dos mesmos builders que servem MCP e o card permanecerá alinhado ao registro real.

Handler JSON-RPC

O handler consome um executor com duas responsabilidades:

const executor = {
  execute: async (toolName: string, args: Record<string, unknown>) =>
    registry.routeCall(context, toolName, args),
  hasToolName: (name: string) => registry.has(name),
};

const handler = new A2AHandler(executor);
const response = await handler.handleRequest(jsonRpcRequest);

Os métodos compatíveis incluem message/send, message/stream, tasks/get, tasks/cancel, tasks/list, tasks/resubscribe, configuração de notificações push para definir, obter, listar e excluir, e agent/getAuthenticatedExtendedCard. A ponte valida JSON-RPC, mapeia erros de execução de ferramentas para códigos de erro A2A e mantém os nomes das ferramentas MCP atrás do limite do executor.

Ciclo de vida da tarefa

TaskManager controla o estado das tarefas usado pelo handler. Seus métodos operacionais são:

• createTask(contextId, message?)
• updateStatus(taskId, status)
• addArtifact(taskId, artifact)
• getTask(taskId)
• listTasks(request)
• cancelTask(taskId)

Configure o TTL das tarefas e a contagem máxima de tarefas. Este é um gerenciador em processo; use a ponte atrás de um modelo de processo compatível com seu ciclo de vida, ou coloque o estado durável das tarefas no limite A2A.

Transporte de streaming

StreamableHttpTransport envolve um A2AHandler e um executor de streaming opcional. message/stream emite eventos enviados pelo servidor usando formatSSEEvent, formatSSEErrorEvent e os helpers de análise do pacote. O próprio servidor MCP pode permanecer sem estado enquanto a camada de tarefas A2A controla o ciclo de vida do stream.

Modelo de erros

A ponte expõe erros tipados para JSON-RPC inválido, operações não compatíveis, tarefas ausentes, tarefas que não podem ser canceladas, notificações push não compatíveis, respostas de agente inválidas e tipos de conteúdo. Ela também exporta a tabela de códigos de erro A2A, o cabeçalho de extensão X-A2A-Extensions, cabeçalhos SSE e as constantes do protocolo, para que uma integração possa testar os mesmos valores que disponibiliza.

Limite de segurança

A ponte A2A não substitui a autenticação MCP. Coloque JWT, chave de API ou autorização do gateway na frente do executor, e faça o Agent Card refletir apenas as ferramentas que o deploy está disposto a expor. Se esta ponte estiver atrás do Swarm, o token de delegação e o isolamento de namespace acontecem antes da execução A2A. Se for pública, autentique a rota HTTP antes de analisar as mensagens de tarefas.

MCP e A2A juntos

Um único conector pode expor:

A lógica de negócio permanece nos mesmos handlers e Presenters. O que muda é o adaptador de protocolo na borda.

Próximos passos

• Federated handoff with Swarm: encaminhe uma sessão para outro agente
• Authentication: proteja as duas bordas de protocolo
• Introspection: mantenha os cards alinhados ao registro