How google-a2a/a2a-js works
Project Type & Purpose
• It’s a TypeScript SDK for building and interacting with “agentic” applications (A2A Servers).
• Provides:
• A2A Server framework (Express-based, JSON-RPC endpoints, SSE streaming)
• A2A Client library (JSON-RPC over HTTP, SSE support)
A. SDK Consumer (Your Application)
• Imports A2AClient or A2AExpressApp & related types.
B. A2A Client Module (src/client)
• Class: A2AClient
• Handles JSON-RPC calls (sendMessage, getTask, cancelTask)
• Supports standard responses & Server-Sent Events streams.
C. Transport Layer (Client ↔ Server)
• HTTP / JSON-RPC 2.0
• SSE channel for streaming events.
D. A2A Server Module (src/server & index)
1. Entry: A2AExpressApp
• Wraps an Express app and mounts JSON-RPC endpoints (POST /, GET /stream) and agent metadata route (/.well-known/agent.json).
2. JSONRPC Transport Handler (jsonrpc_transport_handler.ts)
• Parses JSON-RPC requests, invokes Request Handlers, serializes responses or SSE streams.
3. Request Handler Layer (default_request_handler.ts & a2a_request_handler.ts)
• DefaultRequestHandler implements handleSendMessage, handleCancelTask, delegates to AgentExecutor.
4. Agent Execution Subsystem (agent_execution/*.ts)
• Interfaces: AgentExecutor, RequestContext, TaskStore
• AgentExecutor.execute / cancelTask
• Reads RequestContext, interacts with TaskStore (InMemoryTaskStore), publishes events.
5. Event Bus & Queues (events/*.ts)
• ExecutionEventBus: publishes Task, StatusUpdate, ArtifactUpdate events.
• ExecutionEventQueue: buffers events per task.
• ExecutionEventBusManager: manages per-task buses & finishing.
6. Persistence (store.ts & InMemoryTaskStore)
• Stores the latest Task state & history.
7. Result Management (result_manager.ts)
• (Optional) Aggregates final responses.
8. Utilities (utils.ts, error.ts)
Relationships & Data Flow
1. SDK Consumer → A2AClient.sendMessage()
2. A2AClient → HTTP POST → A2A Server JSONRPC endpoint
3. JSONRPC Transport → DefaultRequestHandler.handleSendMessage()
4. Handler → AgentExecutor.execute(RequestContext, EventBus)
5. AgentExecutor → ExecutionEventBus.publish(...) → EventQueue
6. Transport layer reads from EventQueue → streams via SSE back to client
7. Client receives streamed events → delivers to SDK Consumer
For non-streaming calls, block until final event, then HTTP response with aggregated result.
Architectural Patterns & Principles
• Modular layering: Transport → Handler → Executor → Store → Event Bus
• Pluggable Executor interface for custom agent logic
• Event-driven execution with publish/subscribe
• JSON-RPC standard + SSE streaming for real-time updates
• In-memory or pluggable TaskStore for stateful tasks
Diagramming Details
• Use clear labels for each component (e.g., “A2AExpressApp”, “DefaultRequestHandler”).
• Orange for extension/plugin interfaces (AgentExecutor)