PromptMaster

Posted on Jul 18

Build Your First A2A Agent in 8 Steps

#ai #agents #python #tutorial

Making an agent speak A2A is roughly a day's work with an official SDK. Here's the path from nothing to a discoverable, secured, interoperable agent.

Making an existing agent speak A2A takes eight steps: install the SDK, define an Agent Card, implement an executor, wire the server, handle the task lifecycle, enable discovery, secure the endpoint, and test interoperability.

You rarely implement the wire protocol by hand. Official SDKs ship for Python, JavaScript, Java, Go, and .NET, and they handle JSON-RPC parsing, the task state machine, card serving, and SSE streaming.

What you write is the executor — the code that receives a task's Message, does the actual work, reports progress, and returns Artifacts.

What you're actually building

A2A adoption isn't a rewrite. You are giving an agent you already have a front door: a card that describes it, an endpoint that accepts tasks, and honest lifecycle reporting. Its model, framework, prompts, and tools stay exactly as they are.

That's worth internalizing before you start, because it changes how much you attempt on day one. The goal is not a multi-agent architecture. The goal is one agent that any compliant client can discover and drive.

Step 1 — Install the SDK

# Python example
pip install a2a-sdk

# the SDK provides server scaffolding, the Agent Card model,
# an executor interface, and the JSON-RPC + SSE plumbing

SDKs exist for Python, JavaScript, Java, Go, and .NET. Pick the one your agent already lives in — there's no benefit to introducing a new language at the protocol boundary.

Step 2 — Define your Agent Card

Describe your agent's identity and skills. This is the contract every client plans against, so write the skills the way you'd write public API docs — a stable id, a plain-language description, expected inputs, and the shape of what comes back.

{
  "name": "Research Agent",
  "description": "Gathers and summarizes sources on a topic",
  "version": "1.0.0",
  "url": "https://agent.example.com/a2a",
  "skills": [
    { "id": "research",
      "description": "Research a topic and return a sourced summary" }
  ],
  "capabilities": { "streaming": true }
}

A skill described as "processing" tells a caller nothing. Be specific here or your agent is invisible in practice.

Step 3 — Implement an executor

This is where your real logic lives, and it's the only part of the protocol you genuinely own. The executor receives a task's incoming Message, does the work — often by calling your model and your MCP tools — reports progress, and returns Artifacts.

Keep your capability inside a clean executor rather than scattered across handler code. It makes the agent easy to reason about, easy to test directly, and unaffected when the protocol layer changes underneath it.

Step 4 — Wire the request handler and server

The SDK gives you server scaffolding; you connect your executor to it and start listening for A2A calls. There's little to invent here, which is the point — the plumbing is the same for everyone, and that's what makes agents interchangeable.

Step 5 — Handle the task lifecycle

Emit working when you start, and always reach a terminal state — completed, failed, or canceled — on every path.

This is the single most common bug in first implementations: the work finishes internally, no terminal state is reported, and the caller hangs forever. If your agent might need more information, use input-required to pause and ask rather than guessing or failing.

If a client of yours hangs, check the terminal state first.*It's the answer nine times out of ten.*

Step 6 — Enable discovery

Serve the Agent Card at the well-known path. Then prove it, before you wire up anything else:

curl https://your-agent.example.com/.well-known/agent-card.json

A running agent that doesn't serve its card cannot be discovered. It doesn't matter how well it works — if clients look at the well-known path and find nothing, the agent doesn't exist as far as the ecosystem is concerned.

Step 7 — Secure the endpoint

You just opened a door. Wire the endpoint to your existing identity provider, require a scoped token on every request, and validate it before any work happens.

Because it's standard OAuth 2.0 and JWT, you inherit rotation, revocation, and auditing from infrastructure you already run — you're not inventing a private trust scheme. Validate every incoming Part, rate-limit, and never trust input just because it arrived from another agent.

Step 8 — Test interoperability

The whole point of A2A is that any compliant client can talk to your agent. So test with one as soon as it runs:

Fetch the card.
Send a message and open a task.
Watch the task move through its states.
Confirm you get a well-formed Artifact back.

If a generic A2A client can drive your agent end to end without special knowledge, you've built something that plugs into the entire ecosystem — not just your own code. That's the difference between an agent that works and an agent that's interoperable.

What the SDK handles, and what you own

	The SDK	You
Protocol	JSON-RPC parsing, task state machine, card serving, SSE streaming, transport	—
Substance	—	Skills you declare, executor logic, tools it calls, auth policy you enforce

Keeping that division clean means protocol changes rarely touch your logic, and your logic rarely has to think about the protocol.

From hello-world to useful

A first agent that echoes a message proves the plumbing. A useful one does real work behind the same interface.

The step between them is almost entirely in the executor: wire it to your model, give it the MCP tools it needs, and have it report honest progress and return well-formed Artifacts. Keep the protocol surface unchanged as you add capability, so the agent stays interoperable while it grows more capable.

Frequently asked questions

How long does it take to make an agent speak A2A?
Roughly a day with an official SDK for an agent you already have. The SDK handles the protocol; you write the executor and the card. The first hello-world server comes together in well under an hour.

Which languages have A2A SDKs?
Official SDKs ship for Python, JavaScript, Java, Go, and .NET. Use whichever your agent already lives in.

Do I need to rewrite my agent to adopt A2A?
No. A2A is a messaging layer, not a framework. You give your existing agent an Agent Card and an A2A endpoint; its model, framework, prompts, and internal logic stay exactly as they are.

What is an A2A executor?
The function that handles an incoming task: it receives the task's Message, does the actual work (often calling your model and MCP tools), reports progress, and returns Artifacts. It's the part you write — the SDK handles everything around it.

How do I know my agent is actually interoperable?
Drive it with a generic A2A client, not your own harness. Fetch the card, open a task, watch the states, and confirm a well-formed Artifact comes back. If a client that knows nothing about your code can complete a task, you're interoperable.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

A2A: The Complete Guide — 42 pages. 15 chapters, 5 appendices. Discovery, security, building your first agent with the SDK, orchestration patterns, extensions and AP2, production and scaling — plus a full worked example of two agents talking and a 30-day adoption path.

Independent educational content. Not affiliated with, endorsed by, or sponsored by Google, the Linux Foundation, Anthropic, or any vendor named. A2A and MCP are evolving specifications — confirm details against the official specification for your target version.

DEV Community