a2a-samples: the reference notebooks for the Agent2Agent protocol, and what they leave to you

The gap a2a-samples fills: a shared wire format between agents built on different stacks

Multi-agent systems usually break at the boundary, not inside the agent. One team ships a Python agent, another ships a Java service, a third wraps a Node.js tool, and each pair needs a bespoke adapter. The A2A protocol exists to replace those adapters with one message format. The a2a-samples repository is the official place where that format is shown in working code rather than in specification prose. The README frames the problem directly: agents need a common language to communicate, collaborate, and delegate tasks securely, and the samples demonstrate multi-agent problems solved across different languages and host applications. The audience is engineers evaluating whether to build on A2A, and engineers who already decided and now need a concrete message exchange to copy. It is not aimed at people who want a hosted agent runtime. Nothing in the material suggests the repository ships a service you deploy.

Five language trees, one protocol, and a notebook-first repository

The repository is organised by language. The README lists samples/python, samples/go, samples/dotnet, samples/java and samples/js, each described as agent implementations using the corresponding official SDK. That layout tells you the intended reading order: pick your language, read the agent, then read the client that talks to it. The primary language is listed as Jupyter Notebook, which is consistent with a repository whose purpose is explanation. A notebook holds a request, a response and the narrative between them in one file, which is exactly what a protocol sample needs. The trade-off is that notebooks diff badly and resist reuse as libraries. If you want code you can import, the SDK repositories listed under Related Repositories are the correct source; a2a-samples is where you go to understand what the SDK does on the wire. The repository also links a2a-inspector for inspecting A2A enabled agents and a2a-tck for validating protocol compliance, which are separate tools rather than parts of this repository.

Running the Helloworld agent and its test client

The README gives one complete path, and it is short. In the first terminal, from the repository root: cd samples/python/agents/helloworld, then python -m venv .venv, source .venv/bin/activate, pip install -r requirements.txt, python __main__.py. The agent server starts from __main__.py. In a second terminal, the README says to cd into the same directory, activate the same virtual environment, and run python test_client.py. That second step matters: the client is run from the agent directory, not from a separate host directory, so the sample keeps client and server side by side. Two details are worth noticing. The activation command is the POSIX form, so Windows users need the Scripts equivalent. And the README describes test_client.py as the host client for this sample, which is narrower than the phrase Python CLI host used in the Quick Start heading. For any sample beyond Helloworld, the README does not supply commands, so treat each directory as its own setup problem.

Where the samples stop and your own engineering starts

The README carries an explicit disclaimer: the sample code is provided for demonstration purposes and illustrates the mechanics of the protocol. That sentence should govern how you read every file in the repository. Demonstration code typically omits the parts that decide whether a system survives contact with users: authentication between agents, retry and timeout policy, persistence of task state, and error surfaces. The supplied material does not describe any of those for the samples, so do not assume they are present. The itk release tags (itk-v.023-alpha, itk-v.022-alpha, itk-v.021-alpha) are labelled alpha, and the README places the compatibility toolkit in a separate repository, a2a-itk. That separation is deliberate: the compatibility testing machinery is not something you get by cloning a2a-samples. If your goal is a tested, versioned client library, this repository is the wrong tool, and the per-language SDK is the right one.

a2a-samples against a general-purpose agent framework

A framework such as a general agent orchestration library and a2a-samples answer different questions. A framework asks how you compose agents inside one process or one vendor's runtime, and it usually defines its own in-memory message types. a2a-samples assumes the agents are already separate services and shows the messages that cross between them. The practical difference shows up when the two agents are written in different languages. Inside a framework, a Python agent calling a Java agent means writing a bridge. With A2A, the README's claim is that the protocol supplies the common language, and the repository demonstrates it by shipping the same interaction in five language trees. The cost of that portability is a serialisation boundary on every hop, plus the need to keep both sides on a compatible protocol revision. The README points to a2a-tck and a2a-itk for exactly that compatibility question, which is a signal that version alignment is a real operational concern rather than an afterthought.

Licence, maintenance surface and the cost of following an evolving protocol

The repository is Apache-2.0, which permits commercial use and modification, and it carries no copyleft obligation on your own code. This is a description of the licence identifier, not legal advice; read the LICENSE file and your own counsel's view before shipping. The maintenance cost of a sample repository is not the cost of the code, it is the cost of tracking the protocol. The A2A specification lives in a separate repository, and the samples must follow it. The itk tags in the release list are alpha and were published within days of each other in May 2026, while the last push to the default branch is dated 2026-09-09. That pattern suggests active movement rather than a frozen artefact. If you copy a sample into your codebase, you inherit the job of noticing when the protocol changes and the sample no longer reflects it. Pinning to a specific commit and recording which protocol revision that commit targeted is cheaper than discovering the drift in production.

Editorial conclusion

Adopt a2a-samples when you need a working reference for the A2A wire format before committing to an SDK, and start with samples/python/agents/helloworld because the README gives a complete runnable path for it. Do not adopt it as the base of a production agent: the README states the code is for demonstration purposes, the repository is Jupyter Notebook first, and the itk releases are alpha. Verify first whether your target language has an SDK you can depend on, and whether the sample you copy still matches the current protocol revision.

Official sources

1. a2aproject/a2a-samples on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases