Skip to main content

​
Agent-to-Agent Protocol

A2A in lib/a2a.ts enables agents to send and receive messages during a workflow. It is used in tests (/api/test/a2a) and can be wired into execution for richer coordination.

​
Message Types

TypePurpose
requestAsk another agent for data or an action; expectsResponse and correlationId for matching.
responseReply to a request; must include correlationId of the request.
notificationInform one or more agents; no response expected.
data_shareSend structured data with a dataType to one or more agents.

​
A2AMessage

interface A2AMessage {
  id: string;
  from: AgentName;
  to: AgentName | AgentName[];
  type: 'request' | 'response' | 'notification' | 'data_share';
  payload: any;
  timestamp: Date;
  sessionId: string;
  correlationId?: string;
}
  • A2ARequest: type: 'request', expectsResponse: boolean.
  • A2AResponse: type: 'response', correlationId: string.
  • A2ADataShare: type: 'data_share', dataType: string, data: any.

​
Communication Patterns

​
Request–Response

  • sendA2ARequest(from, to, payload, sessionId, timeout?) — Sends a request, subscribes for a response with matching correlationId, resolves with payload or rejects on timeout (default 30s).
  • sendA2AResponse(from, to, payload, sessionId, correlationId) — Sends a response; the request’s from is typically the to of the response.

​
One-way

  • sendA2ANotification(from, to, notification, sessionId, metadata?) — to can be one agent or an array.
  • shareA2AData(from, to, dataType, data, sessionId) — Same for to; data is arbitrary.

​
Helpers

  • createA2AMessage(from, to, type, payload, sessionId, correlationId?) — Builds a message with id and timestamp.
  • getAgentCommunicationFlows(agentName) — From AGENT_ROLES[agentName].communication_flows.
  • canCommunicate(from, to) — Whether to is in from’s communication_flows.
  • getAgentMessages(sessionId, agentName) — Messages where agentName is in to.
  • clearA2AMessages(sessionId) — Removes all messages for that session.

​
Implementation Details

​
Message Bus

  • A2AMessageBus — In-memory: Map<sessionId, A2AMessage[]> and Map<agentName, Set<callback>>.
  • send(message) — Appends to the session’s list and invokes subscribers for each recipient in to.
  • subscribe(agentName, callback) — Registers a callback; returns an unsubscribe function.
  • getMessages(sessionId), getMessagesBetween(sessionId, from, to), clear(sessionId) — Query and cleanup.
A singleton messageBus is exported. For production, this could be replaced with Redis, RabbitMQ, or similar.

​
A2AWorkflowIntegration

  • new A2AWorkflowIntegration(sessionId)
  • initialize() — Clears A2A messages for that sessionId.
  • registerAgentHandler(agentName, handler) — Subscribes to the bus for agentName and sessionId:
    • On request from another agent: runs handler(message); if expectsResponse, sends a response (or an error payload on exception).
    • On data_share or notification: runs handler(message).
  • getCommunicationHistory() — Returns getMessages(sessionId).

​
Agent Names

AgentName in a2a.ts includes: CEO, X402Agent, IdeaProcessor, IntentAnalyzer, PlatformSelector, PaymentValidator, ProductManager, FrontendDev, BackendDev, AIEngineer, DevOpsEngineer, ToolManager. getAgentCommunicationFlows and canCommunicate use AGENT_ROLES from lib/x402.ts.