agentleFS
mckinseymckinsey/agents-at-scale-ark/.claude/skills/a2a-protocol/SKILL.md

a2a-protocol

Skill438 starsChanged 7 months agoApache-2.0View on GitHub

Reference documentation for the Agent2Agent (A2A) protocol. Use when building A2A servers or clients, configuring Ark A2AServer resources, debugging A2A communication, or answering questions about the A2A specification, Agent Cards, task lifecycle, streaming, extensions, or protocol bindings.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Only consult v1.0 content when:

    line 167

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

ElementPurpose
Agent CardJSON metadata: identity, capabilities, endpoint, auth
TaskStateful unit of work with unique ID and lifecycle
MessageSingle communication turn (role: "user" or "agent")
PartContent container: text, file reference, or structured data
ArtifactTangible output generated during a task

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/:

FileContents
spec-01-introduction.mdGoals, principles, design
spec-02-core-concepts.mdCore concepts summary
spec-03-transport.mdTransport layer: JSON-RPC 2.0 over HTTP, SSE streaming
spec-04-authentication.mdAuthentication and authorization
spec-05-agent-card.mdAgent Card structure, discovery, extended cards
spec-06-data-objects.mdTask, Message, Part, Artifact, TaskStatus, streaming events
spec-07-rpc-methods.mdAll JSON-RPC methods (send, stream, get, cancel, push, resubscribe)
spec-08-error-handling.mdError codes and handling
spec-09-workflows.mdCommon workflows and examples
spec-10-appendices.mdAppendices
spec-11-compliance.mdA2A compliance requirements

Topic guides (v0.3)

Conceptual guides from the A2A documentation:

FileContents
topic-what-is-a2a.mdOverview of A2A purpose and benefits
topic-key-concepts.mdCore concepts: actors, elements, interactions
topic-agent-discovery.mdAgent Card discovery mechanisms
topic-life-of-a-task.mdTask lifecycle and state transitions
topic-streaming-and-async.mdSSE streaming and async patterns
topic-extensions.mdA2A extension mechanism
topic-enterprise-ready.mdEnterprise features: auth, security, tracing
topic-a2a-and-mcp.mdA2A vs MCP comparison

Key JSON-RPC methods (v0.3)

MethodDescription
message/sendSend a message, get a response (or initiate a task)
message/streamSend a message and stream response via SSE
tasks/getGet current state of a task
tasks/cancelCancel a running task
tasks/resubscribeRe-subscribe to a task's SSE stream
tasks/pushNotificationConfig/setConfigure push notification webhook
tasks/pushNotificationConfig/getGet push notification config
tasks/pushNotificationConfig/listList push notification configs
tasks/pushNotificationConfig/deleteDelete push notification config
agent/getAuthenticatedExtendedCardGet extended Agent Card (authenticated)

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.