Core Protocol Specification

This document explains the core of A2A from a practical implementation perspective.

Scope

Use this guide when you need to:

  • design A2A-compatible client/server behavior,
  • align implementation with current v1.0 release-candidate semantics,
  • plan migration from pre-v1 behavior.

Normative source of truth

For current A2A versions, the canonical protocol definition is the protobuf model:

  • specification/a2a.proto is the normative source.
  • Generated JSON artifacts are convenience outputs for tooling and documentation.
  • SDK bindings and schemas should be generated from proto, not edited manually.

Three-layer model

Layer 1: Canonical data model

Core entities include:

  • AgentCard
  • Task
  • Message
  • Artifact
  • Part

Layer 2: Abstract operations

The core operation set includes:

  • SendMessage
  • SendStreamingMessage
  • GetTask
  • ListTasks
  • CancelTask
  • SubscribeToTask
  • push notification config operations
  • GetExtendedAgentCard

Layer 3: Protocol bindings

A2A maps these operations to concrete transports:

  • JSON-RPC over HTTP
  • gRPC
  • HTTP+JSON/REST

Key v1.0 updates to account for

  • Streaming completion should be detected via task state and stream closure, not a final status field.
  • Terminology is standardized to canceled in protocol text.
  • Service parameters such as A2A-Version and A2A-Extensions are explicit and should be handled consistently.
  • Task identifiers are server-generated; clients should not invent new task IDs for creation.

Implementation guidance by audience

Decision makers

  • Prioritize protocol-version governance and compatibility policy.
  • Define discovery and trust boundaries before large-scale rollout.

Beginners

  • Start with AgentCard discovery, then SendMessage, then task polling and streaming.
  • Learn task lifecycle states before adding extensions.

Developers

  • Build around Task as the durable work unit.
  • Treat Message as interaction payload and Artifact as output payload.
  • Validate media types, auth requirements, and capability flags early.

Advanced users

  • Add version negotiation and migration tests across bindings.
  • Use push notifications and subscription recovery for resilient long tasks.
  • Build extension contracts with strict schema validation and explicit versioning.

Related pages