> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scriptonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# A2A Protocol

> Agent-to-Agent (A2A) communication: message types, patterns, and implementation.

## 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

| Type             | Purpose                                                                                      |
| :--------------- | :------------------------------------------------------------------------------------------- |
| **request**      | Ask another agent for data or an action; `expectsResponse` and `correlationId` for matching. |
| **response**     | Reply to a `request`; must include `correlationId` of the request.                           |
| **notification** | Inform one or more agents; no response expected.                                             |
| **data\_share**  | Send 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`.