Build Your First A2A Agent in 8 Steps

Building an A2A agent takes eight steps: install the SDK, define an Agent Card, implement an executor, wire the server, handle the task lifecycle, enable discovery at the well-known path, secure the endpoint, and test interoperability with a generic client.

Official SDKs ship for Python, JavaScript, Java, Go, and .NET, so you rarely implement the wire protocol by hand. The SDK owns the protocol; you own the logic.

The eight steps

• 1. Install the SDK for your language.
• 2. Define an Agent Card describing your agent's identity and skills.
• 3. Implement an executor — the function that handles an incoming task.
• 4. Wire the request handler and server so the agent listens for A2A calls.
• 5. Handle the task lifecycle, emitting working and terminal states.
• 6. Enable discovery by serving the Agent Card at the well-known path.
• 7. Secure the endpoint with authentication.
• 8. Test interoperability against a generic client or another agent.

Step 1 — Install

# Python example
pip install a2a-sdk

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

Step 2 — Define the Agent Card

Describe your agent as carefully as you would document a public API. The skills list is what other agents read to decide whether to call you:

{
  "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 }
}

Step 3 — The executor is where your logic lives

This is the important conceptual step. Most of the protocol — parsing JSON-RPC, managing the task state machine, streaming events — is handled by the SDK. What you write is the executor: the code that receives a task's incoming Message, does the actual work (often by calling your model and your MCP tools), reports progress, and returns Artifacts.

Keeping your real capability inside a clean executor is what makes the agent easy to reason about and test.

What the SDK owns, and what you own

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

Steps 4–5 — Server and lifecycle

The SDK gives you server scaffolding; you wire your executor into it. Then make sure your executor advances the task honestly: move it to working when you start, to input-required if you need something, and always to a terminal state — completed, failed, or canceled — when you finish.

That last part is not optional. A task that never reaches a terminal state leaves every caller hanging.

Step 6 — Serve the card, or you are invisible

A running agent that does not serve its Agent Card at the well-known path cannot be discovered. Confirm you can fetch it back before wiring up any client:

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

It is the single most common first-run mistake.

Step 7 — Secure the endpoint

When you make an agent callable over A2A, you are opening a door. Point your agent at your existing identity provider, require a scoped OAuth 2.0 token on every request, and validate it before any work happens.

Because it is standard OAuth and JWT, you inherit rotation, revocation, and auditing for free rather than inventing a private trust scheme.

Step 8 — Verify interoperability early

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, watch the task move through its states, and confirm you get an Artifact back.

If a generic A2A client can drive your agent end to end, you have built something that plugs into the entire ecosystem — not just your own code.

An agent that only your code can call
is not an A2A agent. It's an API with extra steps.

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 mostly 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.