a2a-protocol

A2A Protocol Reference

Reference skill for the Agent2Agent (A2A) Protocol, an open standard by Google / the A2A Project (Linux Foundation) for communication between independent AI agent systems.

Attribution: All specification and topic content in references/ is sourced from the official A2A repository under the Apache-2.0 license. Each file includes source attribution in its YAML frontmatter.

IMPORTANT — Use v0.3 by default. The primary references in references/v0.3/ are v0.3.0, the version currently supported by the official Go and Python SDKs and most implementations. The v1.0 RC spec is in references/v1.0-rc/ and should only be consulted when explicitly working on v1.0 features or migration planning.

When to use this skill

• Building or debugging an A2A server or client
• Configuring Ark A2AServer custom resources
• Understanding Agent Cards, task lifecycle, or message formats
• Implementing streaming (SSE) or push notifications
• Working with A2A extensions
• Comparing A2A with MCP

Protocol overview

A2A enables agents built on different frameworks to discover capabilities, negotiate interaction modes, manage collaborative tasks, and exchange information — without exposing internal state, memory, or tools.

Core actors:

• User — human or automated service initiating a request
• A2A Client — application or agent acting on behalf of the user
• A2A Server — agent exposing an HTTP endpoint implementing A2A

Core elements:

Interaction patterns:

• Request/Response — synchronous with polling for long-running tasks
• Streaming (SSE) — real-time incremental updates over open connection
• Push Notifications — async webhooks for disconnected/long-running tasks

Task lifecycle: submitted → working → input-required → completed / failed / canceled

Agent discovery: Clients find agents via /.well-known/agent.json

Specification reference (v0.3)

The primary A2A specification (v0.3.0) is split into sections in references/v0.3/:

Topic guides (v0.3)

Conceptual guides from the A2A documentation:

Key JSON-RPC methods (v0.3)

Agent Card example

{
  "name": "My Agent",
  "description": "An agent that does useful things",
  "url": "https://myagent.example.com/a2a",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true
  },
  "skills": [
    {
      "id": "summarize",
      "name": "Summarize Text",
      "description": "Summarizes long text into key points"
    }
  ],
  "securitySchemes": {
    "bearer": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "security": [{ "bearer": [] }]
}

Discovered at: https://myagent.example.com/.well-known/agent.json

Quick lookup guide

• "How do I discover agents?" → topic-agent-discovery.md, spec-05-agent-card.md
• "What are the task states?" → topic-life-of-a-task.md, spec-06-data-objects.md
• "How does streaming work?" → topic-streaming-and-async.md, spec-07-rpc-methods.md
• "What's the difference between A2A and MCP?" → topic-a2a-and-mcp.md
• "How do extensions work?" → topic-extensions.md
• "What security/auth is needed?" → spec-04-authentication.md, topic-enterprise-ready.md
• "What are the error codes?" → spec-08-error-handling.md
• "Show me workflow examples" → spec-09-workflows.md

v1.0 RC reference (use only when needed)

The v1.0 Release Candidate spec is available in references/v1.0-rc/ for forward-looking work. Key differences from v0.3 are documented in v1.0-rc/topic-whats-new-v1.md.

Only consult v1.0 content when:

• Explicitly planning migration from v0.3 to v1.0
• Working on features that require v1.0-specific capabilities
• The user specifically asks about v1.0