lockstep
4 min readNaman Jain

A2A protocol example: Agent Cards, discovery, and tasks

An A2A protocol walkthrough from the spec: an example Agent Card, discovery via the well-known URI, sending a message, and how tasks move to completion.

A team builds a support agent that needs refund decisions from a finance agent another team owns. They don't want to share code, prompts, or tools; they want the finance agent to take a request and send back an answer. That's the job A2A, the Agent2Agent protocol, was designed for.

This walkthrough follows the A2A project's docs on agent discovery and the life of a task, checked on 16 November 2026. For how A2A compares with MCP and ACP, see MCP vs A2A vs ACP.

Step 1: publish an Agent Card

Every A2A server describes itself with an Agent Card, a JSON document. Per the docs, it includes:

  • Identity: name, description, provider
  • Service endpoint: the url of the A2A service
  • Capabilities: supported features such as streaming or pushNotifications
  • Authentication: the required schemes, such as Bearer or OAuth2
  • Skills: each with an id, name, description, inputModes, outputModes, and examples

An illustrative card for the finance agent, using those fields:

{
  "name": "Refund Approvals Agent",
  "description": "Decides whether a customer refund can be approved.",
  "provider": { "organization": "Acme Finance" },
  "url": "https://finance-agent.acme.example/a2a",
  "capabilities": { "streaming": true, "pushNotifications": false },
  "skills": [
    {
      "id": "approve-refund",
      "name": "Approve refund",
      "description": "Checks a refund request against policy and returns approve or deny with a reason.",
      "inputModes": ["text", "application/json"],
      "outputModes": ["application/json"],
      "examples": ["Can order 1042 get a $120 refund?"]
    }
  ]
}

Check the specification for exact field names and the authentication structure before implementing.

Step 2: discovery

The docs describe two common strategies:

  • Well-known URI: the server hosts its card at https://{domain}/.well-known/agent-card.json. A client that knows the domain fetches it with an HTTP GET. Good for public or domain-wide discovery; protect the endpoint if the card has sensitive details.
  • Curated registries: a central service stores Agent Cards, and clients search by skill, tag, or capability. Suited to enterprises and marketplaces that need governance and access control.

Step 3: send a message

A2A uses JSON-RPC 2.0 over HTTPS. The client sends a message to the agent's endpoint; the current specification names the methods SendMessage, SendStreamingMessage for streaming, and GetTask to check on a task.

The first response includes a new contextId. The client sends that contextId on later messages to continue the same interaction, and can include a taskId to continue a specific task.

Step 4: Message or Task

The agent replies in one of two ways:

  • A Message: a stateless, self-contained answer for quick interactions.
  • A Task: stateful work with a lifecycle. The agent reports progress and asks for input as needed, until the task reaches an interrupted state, such as input-required or auth-required, or a terminal state: completed, canceled, rejected, or failed.

The docs describe three agent styles: message-only agents, task-generating agents that always return Tasks, and hybrids that do both.

Step 5: artifacts

Results come back as artifacts: tangible outputs such as a document, an image, or structured data, each with an artifactId, a name, and one or more parts. For the refund example, the artifact would be the JSON decision with its reason.

Where to go next

The A2A project publishes the full specification, SDKs, and samples, and a short course built with Google Cloud and IBM Research on DeepLearning.AI. Start with one agent, one skill, and the well-known URI before adding registries or push notifications.

What agents still need from each other

A2A moves requests and results between agents without sharing internals. It doesn't define what the organization has decided, such as the refund policy change approved last week, that both agents should follow. That has to come from a source each agent can check.

Where Lockstep fits

Lockstep is that kind of source for engineering and product decisions. It captures them from PRDs, Slack, and pull requests, routes each to its owner for approval, and serves them over MCP to any client. Claude Code sessions also get a briefing automatically.

See how it works.

Sources checked 16 November 2026

For building an MCP server, see how to build an MCP server. For the agent terms behind it, see agentic AI vs AI agents.

Frequently asked questions

What is an A2A Agent Card?
A JSON document that acts as a business card for an A2A server. It includes identity (name, description, provider), the service endpoint url, capabilities such as streaming or push notifications, authentication requirements, and skills, each with an id, name, description, input and output modes, and examples.
Where is the A2A Agent Card hosted?
For public or domain-wide discovery, at the well-known path https://{agent-server-domain}/.well-known/agent-card.json. Enterprises and marketplaces can also use curated registries that store Agent Cards and let clients search by skill or capability.
What is the difference between an A2A Message and a Task?
A Message is a single, self-contained turn, good for quick interactions. A Task is stateful work that moves through a lifecycle, reporting progress and asking for input as needed, until it reaches an interrupted state such as input-required or a terminal state such as completed, canceled, rejected, or failed.
What is a contextId in A2A?
An identifier that groups related Tasks and Messages. The agent returns a new contextId on the first message; the client sends it on later messages to continue the interaction, and can add a taskId to continue a specific task.
How does A2A relate to MCP?
They complement each other. MCP connects an agent to tools and data. A2A connects independent agents so they can delegate work to each other without exposing their internal memory or tools.

Keep reading