Puente A2A

MCP es el límite de las herramientas. A2A es el límite de los agentes. El paquete A2A de MCP Fusion permite que un conector participe en una red Agent2Agent sin reescribir sus herramientas: el registro sigue siendo la fuente de capacidades y el puente expone el protocolo de tareas orientado al agente.

Compilar una 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,
);

El compilador deriva las habilidades a partir de los nombres de los builders y los metadatos de las acciones. La card se sirve en /.well-known/agent-card.json; la ruta heredada es /.well-known/agent.json. Las solicitudes A2A JSON-RPC usan /a2a y el paquete se identifica como protocolo 1.0.0.

La configuración opcional bridge describe cómo se alcanza la card a través de otro puente. No mantengas manualmente una segunda lista de capacidades: compila a partir de los mismos builders que sirven MCP para que la card se mantenga alineada con el registro real.

Handler JSON-RPC

El handler consume un executor con dos 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);

Los métodos compatibles incluyen message/send, message/stream, tasks/get, tasks/cancel, tasks/list, tasks/resubscribe, la configuración de notificaciones push para establecer, obtener, listar y eliminar, y agent/getAuthenticatedExtendedCard. El puente valida JSON-RPC, asigna los errores de ejecución de herramientas a códigos de error A2A y mantiene los nombres de herramientas MCP detrás del límite del executor.

Ciclo de vida de las tareas

TaskManager posee el estado de las tareas que usa el handler. Sus métodos operativos son:

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

Configura el TTL de las tareas y el número máximo de tareas. Este es un gestor en proceso; usa el puente detrás de un modelo de procesos que coincida con su ciclo de vida o coloca el estado duradero de las tareas en el límite A2A.

Transporte de streaming

StreamableHttpTransport envuelve un A2AHandler y un executor de streaming opcional. message/stream emite eventos enviados por el servidor usando formatSSEEvent, formatSSEErrorEvent y los helpers de análisis del paquete. El propio servidor MCP puede seguir sin estado mientras la capa de tareas A2A gestiona el ciclo de vida del stream.

Modelo de errores

El puente expone errores tipados para JSON-RPC no válido, operaciones no compatibles, tareas inexistentes, tareas que no se pueden cancelar, notificaciones push no compatibles, respuestas de agente no válidas y tipos de contenido. También exporta la tabla de códigos de error A2A, la cabecera de extensión X-A2A-Extensions, las cabeceras SSE y las constantes del protocolo, para que una integración pueda probar los mismos valores que sirve.

Límite de seguridad

El puente A2A no sustituye la autenticación MCP. Coloca JWT, una clave de API o la autorización del gateway delante del executor, y haz que la Agent Card refleje solo las herramientas que el despliegue está dispuesto a exponer. Si este puente está detrás de Swarm, el token de delegación y el aislamiento del namespace ocurren antes de la ejecución A2A. Si es público, autentica la ruta HTTP antes de analizar los mensajes de tareas.

MCP y A2A juntos

Un solo conector puede exponer:

La lógica de negocio permanece en los mismos handlers y Presenters. Lo que cambia es el adaptador de protocolo en el borde.

Próximos pasos

• Federated handoff with Swarm: dirige una sesión a otro agente
• Authentication: protege ambos extremos del protocolo
• Introspection: mantén las cards alineadas con el registro