How the A2A Protocol Works: Architecture, Methods, and Message Flow

The Client-Server Model

Every A2A interaction involves two roles: a client agent that initiates work and a server agent that performs it. The client is the agent that needs something done. The server is the agent that has the capability to do it. These roles are per-interaction, not permanent. An agent that serves requests from one client might itself be a client to a different agent for a different subtask, creating chains and hierarchies of delegation.

The server agent runs an HTTP server that accepts A2A requests at a specific endpoint URL. The client agent sends HTTP POST requests to that endpoint containing JSON-RPC 2.0 messages. The server processes each request and returns a JSON-RPC response. For streaming interactions, the server keeps the connection open and sends Server-Sent Events (SSE) as work progresses.

This model maps naturally to existing web infrastructure. A2A servers can sit behind load balancers, API gateways, and reverse proxies without any special configuration. They can be deployed as containers, serverless functions, or traditional web services. The HTTP foundation means that all existing tooling for monitoring, logging, rate limiting, and authentication works with A2A out of the box.

The Six Core Methods

A2A defines a deliberately small set of JSON-RPC methods. Each method maps to a specific operation in the task collaboration lifecycle. The small method surface keeps the protocol easy to implement while covering every interaction pattern agents need.

tasks/send is the primary method for submitting work. The client sends a task with an ID, a message containing the instructions, and optional metadata. If the task ID is new, the server creates a fresh task. If the task ID matches an existing task (for example, one in the input-required state), the server appends the new message to the existing task and resumes processing. The response includes the updated task object with its current state, messages, and any artifacts produced.

tasks/sendSubscribe works like tasks/send but opens a streaming connection. Instead of returning a single response, the server keeps the HTTP connection open and emits SSE events as the task progresses. Events include task status changes (submitted to working to completed), new messages from the server agent, and artifacts as they are generated. The client receives a real-time stream of the server's work rather than waiting for the final result.

tasks/get retrieves the current state of an existing task by its ID. The response includes the task's status, full message history, and any artifacts. This method is useful for polling-based clients, for checking on tasks that were submitted asynchronously, and for retrieving results after a push notification indicates completion.

tasks/cancel requests cancellation of a running task. The server transitions the task to the canceled state and stops processing. Cancellation is cooperative, the server acknowledges the request and halts work, but it may complete any in-flight operations before stopping. Tasks that are already in a terminal state (completed, failed, canceled) cannot be canceled.

tasks/pushNotification/set configures a webhook URL where the server should send notifications about task progress. The client provides the URL and authentication credentials for the webhook endpoint. The server stores this configuration and sends HTTP POST requests to the URL whenever the task state changes or new artifacts are produced. This mechanism is designed for long-running tasks where maintaining an open connection is impractical.

tasks/pushNotification/get retrieves the current push notification configuration for a task. The client can use this to verify that notifications are configured correctly or to check the webhook URL before updating it.

The Complete Request Flow

A full A2A interaction follows a specific sequence. Understanding this sequence clarifies how the protocol methods work together in practice.

Step one is discovery. The client agent sends an HTTP GET request to the server's well-known URL (https://server-host/.well-known/agent.json). The server responds with its Agent Card, a JSON document describing its name, description, available skills, supported content types, authentication requirements, and endpoint URL. The client examines this card to determine whether the server can handle the desired task.

Step two is authentication. Based on the Agent Card's authentication section, the client acquires the necessary credentials. For OAuth 2.0, this means obtaining an access token from the specified token endpoint. For API key authentication, the client includes the key in the request headers. Some development or demo agents accept unauthenticated requests.

Step three is task submission. The client constructs a JSON-RPC request with the tasks/send or tasks/sendSubscribe method. The request parameters include a task ID (generated by the client), a message containing the task instructions, and any additional metadata. The message includes one or more parts: text parts for natural language instructions, data parts for structured parameters, and file parts for attachments.

Step four is processing and communication. The server agent receives the task and begins working. During processing, the server may generate intermediate messages (status updates, partial results, progress indicators) and may transition the task to input-required if it needs clarification from the client. If the client used sendSubscribe, these updates stream back in real time. If the client configured push notifications, updates are delivered via webhook.

Step five is completion. When the server finishes, it transitions the task to completed and attaches artifacts containing the results. The client retrieves the artifacts either through the streaming connection, the push notification, or by calling tasks/get. The task's message history contains the complete record of the collaboration.

Message Structure and Content Types

Every message in A2A contains a role identifier (either "user" for client messages or "agent" for server messages) and an array of parts. Parts are the atomic content units of the protocol, and A2A defines three types.

TextPart contains a plain text string. This is the most common part type, used for natural language instructions, explanations, questions, and status updates. A client sending a research task might include a TextPart with the query "Analyze market trends for autonomous vehicle insurance in North America, focusing on premium pricing models and loss ratios from 2023 through 2026."

DataPart contains a structured JSON object. This is used for machine-readable parameters, configuration values, and structured results. A client might include a DataPart specifying {"format": "csv", "date_range": {"start": "2023-01", "end": "2026-06"}, "regions": ["US", "CA"]} alongside a TextPart with natural language context. DataParts let agents exchange precise, parseable information alongside free-form text.

FilePart contains a file, either as inline base64-encoded data or as a URI pointing to a downloadable resource. FileParts include a MIME type so the receiving agent knows how to interpret the content. A data analysis agent might return a FilePart containing a PNG chart, a FilePart containing a CSV data export, and a TextPart summarizing the key findings.

Artifacts use the same part types as messages but represent the deliverable outputs of a completed task rather than the conversation that produced them. When a task completes, the server attaches one or more artifacts containing the final results. Each artifact has a name, description, and array of parts. The separation between messages (the conversation) and artifacts (the deliverables) lets client agents handle intermediate communication differently from final outputs.

Task States and Transitions

Every task exists in exactly one state at any time, and the valid transitions between states follow a defined graph. The protocol enforces these transitions, preventing invalid state changes that could leave tasks in inconsistent conditions.

The submitted state is the entry point. A task enters this state when the server receives it but has not yet started processing. From submitted, the task can transition to working (the server begins execution), canceled (the client cancels before processing starts), or failed (the server rejects the task due to validation errors or resource constraints).

The working state indicates active processing. From working, the task can transition to completed (work finished successfully), input-required (the server needs more information), canceled (either party terminates), or failed (an unrecoverable error occurs).

The input-required state pauses the task and signals to the client that a response is needed. The server includes a message explaining what information it needs. The client responds by calling tasks/send with the same task ID and a new message containing the requested information. The task then transitions back to working. Multiple rounds of input-required are allowed, enabling complex, multi-turn negotiations between agents.

The three terminal states, completed, canceled, and failed, are final. Once a task reaches a terminal state, it cannot transition to any other state. Completed tasks include artifacts with the results. Failed tasks include an error message explaining what went wrong. Canceled tasks may include partial results if any work was completed before cancellation.

Streaming with Server-Sent Events

When a client uses tasks/sendSubscribe, the server responds with a stream of SSE events rather than a single JSON-RPC response. Each event has a type that tells the client what happened. TaskStatusUpdateEvent fires when the task's state changes, carrying the new status and any associated message. TaskArtifactUpdateEvent fires when a new artifact or artifact part is produced, carrying the artifact data. The stream closes when the task reaches a terminal state.

SSE was chosen over WebSockets because it is simpler to implement, works with standard HTTP infrastructure (proxies, load balancers, CDNs), and provides automatic reconnection in most client libraries. The unidirectional nature of SSE matches A2A's interaction model: the server sends updates to the client, and if the client needs to send additional information, it makes a new HTTP request using tasks/send.

For tasks where streaming is important but the task might also run for a long time, clients can configure push notifications as a fallback. If the SSE connection drops, the server continues processing and delivers updates via the registered webhook. The client can then reconnect with tasks/sendSubscribe or poll with tasks/get to catch up on missed events.

Error Handling

A2A leverages JSON-RPC's built-in error format. When an error occurs, the response includes an error object with a numeric code, a human-readable message, and optional structured data. The protocol defines standard error codes for common scenarios: task not found (returned when tasks/get or tasks/cancel references an unknown task ID), invalid request (returned when the request parameters are malformed), and method not found (returned when the client calls a method the server does not support).

Server agents can also fail tasks gracefully by transitioning them to the failed state with a descriptive error message. This is different from a protocol-level error. A protocol error means the request itself was invalid. A task failure means the request was valid but the server could not complete the work. Understanding this distinction matters for building robust client agents that can retry protocol errors but surface task failures to the user or orchestrator.