Overview

Relevant source files

• .release-please-manifest.json
• CHANGELOG.md
• README.md
• a2a/core.go
• a2asrv/jsonrpc.go
• a2asrv/reqmeta.go

This document provides a high-level overview of the a2a-go SDK, a Go library for building and interacting with agents that implement the Agent-to-Agent (A2A) Protocol. The SDK provides both server-side and client-side components, supporting multiple transport protocols and offering a transport-agnostic architecture for building agentic applications.

For details on specific subsystems, see:

• Core protocol data structures: Core Protocol Concepts
• Building servers: Server Implementation Guide
• Building clients: Client Implementation Guide
• Transport protocols: Transport Implementations

Sources: README.md1-117 a2a/core.go1-769

---

Purpose and Scope

The a2a-go SDK enables developers to:

• Build A2A Servers: Implement agent logic that processes tasks, generates responses, and manages stateful conversations
• Build A2A Clients: Connect to A2A-compliant agents and send messages programmatically
• Support Multiple Transports: Use gRPC or JSON-RPC (with HTTP/SSE) protocols interchangeably
• Manage Task Lifecycle: Handle task states, artifacts, event streaming, and push notifications

The SDK is designed with extensibility in mind, allowing custom storage backends, middleware, and transport implementations.

Sources: README.md20-26 CHANGELOG.md1-91

---

Repository Structure

The a2a-go repository is organized into the following key packages:

Package	Purpose
a2a	Core protocol types (Task, Message, Event, Artifact, etc.)
a2asrv	Server-side components including RequestHandler and AgentExecutor interface
a2aclient	Client-side API for connecting to A2A agents
a2agrpc	gRPC transport implementation for both server and client
internal/jsonrpc	JSON-RPC protocol utilities
internal/sse	Server-Sent Events streaming support
internal/taskexec	Task execution and event processing engine
internal/taskstore	Task persistence layer
internal/taskupdate	Task state transition management
internal/eventqueue	Event distribution and pub-sub system
internal/pbconv	Protocol Buffer conversion utilities
agentcard	Agent discovery and capability resolution
log	Logging utilities

Sources: README.md44-96 a2asrv/jsonrpc.go1-309

---

Core Domain Model

The A2A protocol is built around a set of core types defined in the a2a package. These types flow through all layers of the system.

Primary Types

Event Types: The Event interface unifies multiple event types that can be streamed during task execution: Message, Task, TaskStatusUpdateEvent, and TaskArtifactUpdateEvent.

Sources: a2a/core.go26-314 a2a/core.go413-464

Content Parts

Messages and Artifacts are composed of Part implementations, supporting polymorphic content:

Part Type	Purpose	Key Fields
TextPart	Plain text content	Text: string
DataPart	Structured data (JSON)	Data: map[string]any
FilePart	File references or bytes	File: FilePartContent (union of FileURI or FileBytes)

Sources: a2a/core.go520-670

---

Three-Tier Architecture

The a2a-go SDK follows a three-tier architecture that separates concerns across client, server, and transport layers:

Key Architectural Principles:

1. Transport Agnostic Core: The RequestHandler and AgentExecutor interfaces are independent of any specific transport protocol
2. Pluggable Components: Storage (via Saver interface), transports, and middleware can be customized
3. Event-Driven Processing: Task execution generates events that flow through a pub-sub system
4. Concurrent Execution: Tasks execute concurrently with configurable limits

Sources: README.md44-96 a2asrv/jsonrpc.go47-309

---

Server Components

The server side consists of several coordinated subsystems:

Request Handler

The RequestHandler interface defines the contract for handling A2A protocol requests. The default implementation is defaultRequestHandler in the a2asrv package.

Key Methods:

• OnSendMessage(ctx, params) (SendMessageResult, error)
• OnSendMessageStream(ctx, params) iter.Seq2[Event, error]
• OnGetTask(ctx, params) (*Task, error)
• OnCancelTask(ctx, params) (*Task, error)
• OnResubscribeToTask(ctx, params) iter.Seq2[Event, error]
• Push notification management methods
• OnGetExtendedAgentCard(ctx) (*AgentCard, error)

Sources: a2asrv/jsonrpc.go88-296

Task Execution Pipeline

Execution Flow:

1. Request Reception: Transport handler receives request and delegates to RequestHandler
2. Task Creation/Loading: Handler creates new task or loads existing from TaskStore
3. Execution Scheduling: LocalManager creates executor and processor via factory pattern
4. Event Generation: AgentExecutor generates events (messages, status updates, artifacts)
5. Event Processing: Processor consumes events, applies state transitions, persists to storage
6. Event Distribution: Events broadcast to multiple subscribers via eventqueue.Manager

Sources: a2asrv/jsonrpc.go223-260

---

Client Components

The client side provides a unified API for interacting with A2A agents:

Client Creation Flow

Creation Steps:

1. Resolve AgentCard to discover agent capabilities and endpoints
2. Create transport-agnostic Client using a2aclient.NewFromCard()
3. Send messages and receive responses/streams

Client Methods:

• SendMessage(ctx, params) (SendMessageResult, error) - Send message, wait for completion
• SendMessageStream(ctx, params) iter.Seq2[Event, error] - Send message, stream events
• GetTask(ctx, params) (*Task, error) - Retrieve task state
• CancelTask(ctx, params) (*Task, error) - Cancel running task
• ResubscribeToTask(ctx, params) iter.Seq2[Event, error] - Subscribe to task events
• Push configuration methods

Sources: README.md74-96

---

Transport Layer

The SDK supports two transport protocols with identical functionality:

Transport	Package	Server Handler	Client Implementation
gRPC	a2agrpc	a2agrpc.Handler implementing A2AServiceServer	gRPC client transport
JSON-RPC	a2asrv, internal/jsonrpc	jsonrpcHandler implementing http.Handler	JSON-RPC client with SSE

JSON-RPC Method Mapping

The jsonrpcHandler maps JSON-RPC methods to handler operations:

JSON-RPC Method	Handler Method	Streaming
tasks.get	OnGetTask	No
message.send	OnSendMessage	No
message.stream	OnSendMessageStream	Yes (SSE)
tasks.cancel	OnCancelTask	No
tasks.resubscribe	OnResubscribeToTask	Yes (SSE)
pushConfig.get	OnGetTaskPushConfig	No
pushConfig.set	OnSetTaskPushConfig	No
pushConfig.delete	OnDeleteTaskPushConfig	No
pushConfig.list	OnListTaskPushConfig	No
agentCard.get	OnGetExtendedAgentCard	No

Streaming: JSON-RPC uses Server-Sent Events (SSE) for streaming responses, while gRPC uses native streaming.

Sources: a2asrv/jsonrpc.go88-296

---

State Management

Tasks transition through a defined state machine with optimistic locking:

Task States

Terminal States: completed, failed, canceled, rejected - tasks in these states are immutable

Pausable States: input-required, auth-required - execution pauses waiting for additional input

State Transitions: Managed by taskupdate.Manager which applies events to tasks and persists changes with version checking for optimistic concurrency control.

Sources: a2a/core.go207-240

---

Request Metadata

The RequestMeta structure provides access to transport-level metadata such as authentication headers:

Usage: Custom transport implementations can use WithCallContext() to attach RequestMeta to the request context, making headers and signatures accessible during request processing.

Key Methods:

• Get(key) ([]string, bool) - Case-insensitive lookup
• List() iter.Seq2[string, []string] - Iterate all metadata
• With(additional) *RequestMeta - Create extended metadata

Sources: a2asrv/reqmeta.go1-77

---

Version and Protocol Compliance

• Current Version: 0.3.3
• Go Requirement: 1.24.4 or newer
• Protocol: Implements the Agent2Agent (A2A) Protocol
• License: Apache 2.0

Sources: .release-please-manifest.json1-3 README.md30-34 CHANGELOG.md3-17