# a2a-samples: a working tour of the Agent2Agent protocol samples

> The official sample repository for the Agent2Agent protocol ships runnable agents and hosts in five languages. It is a teaching kit, not a framework, and the disclaimer at the bottom of the README says so plainly.

**a2aproject/a2a-samples** — Samples using the Agent2Agent (A2A) Protocol

- Repository: https://github.com/a2aproject/a2a-samples
- Website: https://a2a-protocol.org
- Stars: 1,785 · Forks: 763
- Language: Jupyter Notebook
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/a2aproject-a2a-samples

## What a2a-samples is for, and who should read it

Agent2Agent is a protocol for one agent to talk to another agent that was built with a different framework, in a different language, or hosted by a different team. The a2a-samples repository is the official set of demonstrations for that protocol. It is not the protocol specification (that lives in a2aproject/A2A) and it is not an SDK (those live in a2a-python, a2a-go, a2a-java, a2a-js, a2a-dotnet and a2a-rs, all listed in the README's related repositories table).

The audience is narrower than the README's welcome paragraph suggests. If you are evaluating whether A2A fits your architecture, the samples answer a concrete question: what does an agent card look like, what does a task request look like on the wire, and how does a host discover and call a remote agent. If you already decided to adopt A2A and want a production runtime, this repository will not give you one. The README closes with a disclaimer that the sample code is for demonstration purposes and illustrates the mechanics of the protocol. That sentence is the most important line on the page, and it should govern how you use everything below it.

## How the samples are organised across Python, Go, Java, .NET and JavaScript

The repository is a language-indexed sample collection. The README's structure table lists samples/python, samples/go, samples/dotnet, samples/java and samples/js, each demonstrating agent implementations against the corresponding official SDK. The primary language of the repository is Jupyter Notebook, which reflects the notebooks/ directory at the top level, but the runnable agents and hosts are ordinary Python, Go, C#, Java and Node.js projects.

The Python side is the most developed and the only one wired into a workspace. The root pyproject.toml declares a uv workspace named a2a-samples-workspace with requires-python >=3.12, and lists fifteen members: agents for crewai, adk_expense_reimbursement, marvin, airbnb_planner_multiagent, llama_index_file_chat, semantickernel, mindsdb, extended_agent_card_adk, veo_video_gen, dice_agent_grpc, dice_agent_rest and ag2, plus hosts for cli, extended_agent_card_cli and multiagent, and the demo/ui application. That membership list is the clearest signal of what is kept in working order: members share a lockfile and a dependency graph, while samples outside the list are standalone directories with their own requirements.txt.

The naming is informative. dice_agent_grpc and dice_agent_rest are the same trivial agent exposed over two transports, which is the fastest way to see how transport choice affects the agent card and the client. extended_agent_card_adk and extended_agent_card_cli pair an agent that publishes an extended card with a host that consumes one. airbnb_planner_multiagent is the multi-hop case, where one agent delegates to others. Reading those four pairs covers most of the protocol surface the samples exercise.

## Running the Helloworld agent and the Python CLI host

The README's Quick Start is the shortest path to a working A2A conversation. It uses two terminals. In the first, you set up a virtual environment inside the Helloworld agent directory, install that sample's requirements, and start the agent server:

```bash
cd samples/python/agents/helloworld
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python __main__.py
```

Running python __main__.py starts the agent process. The README does not state which port it binds to, so read the sample's own source or its requirements file before writing a client that targets a fixed address. In the second terminal you activate the same virtual environment and run the bundled test client:

```bash
cd samples/python/agents/helloworld
source .venv/bin/activate
python test_client.py
```

The client is the part worth studying. It is a host in A2A terms: it fetches the agent's card, finds the endpoint, and sends a task. If you are writing your own host, diffing test_client.py against the multiagent host under samples/python/hosts/multiagent shows what changes when the host has to choose between several agents rather than one. Note that the Quick Start uses pip install -r requirements.txt per sample, while the workspace members are managed with uv from the repository root. Both paths exist, and mixing them in one environment is the most common way to get conflicting SDK versions.

## The demonstration-only disclaimer and other limits you will hit

The README's final section states that the sample code is for demonstration purposes. That is not boilerplate. It means no sample in this repository carries a support commitment, and the ones outside the uv workspace may drift from the current SDK without anyone noticing. If you copy an agent from samples/python/agents into a service, you are adopting code whose maintenance is tied to whether a contributor updates that directory.

The second limit is structural. A sample repository cannot tell you what the protocol guarantees, only what one implementation does with it. When two samples disagree about a field name or a transport detail, the repository does not arbitrate; the specification in a2aproject/A2A does. Similarly, the samples are deliberately small. Helloworld and the dice agents do not exercise authentication, long-running task resumption, or error paths in any depth, and the README does not document rollback, versioning policy or a compatibility matrix for the samples themselves.

The third limit is release cadence. The repository's recent releases are all alpha-tagged itk builds (itk-v.021-alpha, itk-v.022-alpha, itk-v.023-alpha, the latest dated 2026-05-12), which are artifacts of the interoperability toolkit rather than versioned releases of the samples. There is no tagged release you can pin a sample to. The last push to the default branch was on 2026-09-09, so the code is moving, but movement is not the same as a stable interface.

## Where a2a-samples sits next to MCP and the testing tools

The most common comparison is MCP. The two protocols address different seams. MCP connects a model or agent to tools and data sources; A2A connects agents to other agents, which may themselves be built on MCP or on anything else. The a2a-mcp topic on this repository signals that samples exist at that boundary, and the practical difference shows up in the artifact each side produces: an MCP integration exposes tools to one agent, while an A2A sample exposes an agent card and a task endpoint to another agent.

Within the A2A project itself, the meaningful alternative to reading samples is running the conformance tooling. The README lists a2a-tck as a test suite for validating A2A protocol compliance and a2a-itk as a toolkit that verifies compatibility across SDK implementations and versions using a multi-hop traversal model and varied transport protocols. That is a different approach to the same goal: instead of reading a worked example and adapting it, you point a validator at your agent and let it find the gaps. The itk-v.023-alpha release in this repository's release feed comes from that line of work. If your goal is to ship a compliant agent, the TCK and ITK give you a pass or fail signal that no sample can. Use the samples to learn the shape of the protocol, then use the tooling to check that your implementation matches it.

The a2a-inspector repository is the third option: a UI tool for inspecting A2A enabled agents, which is useful when a hand-written client fails and you need to see what the agent actually advertises.

## Licence, workspace tooling and what upgrading actually costs

The repository is Apache-2.0. For samples, that is a permissive licence: you can copy a sample into your own codebase, modify it, and ship it, provided you keep the licence and attribution notices intact. The samples import the official SDKs, which are separate repositories with their own licences, so the terms that matter for a deployed agent come from the SDK you actually depend on, not from this repository. This is a description of the licence text, not legal advice; check LICENSE and the SDK licences yourself.

Upgrade cost is dominated by the workspace layout. The root pyproject.toml pins requires-python >=3.12 and groups the dev dependencies as mypy>=1.19.1, pyright>=1.1.409 and pytest>=9.0.2. If you work from the repository root with uv, updating the workspace lockfile updates all fifteen members together, which is convenient until one sample's SDK constraint conflicts with another's. Samples outside the members list are isolated, so they are cheaper to keep pinned and more likely to be stale. There is no migration guide for moving a sample across SDK versions, and the alpha-tagged releases in this repository do not serve as one. Budget for reading the SDK changelog of whichever language you copied from.

## Conclusion

Adopt a2a-samples if you need to understand the Agent2Agent wire format before committing to an SDK, or if you want a reference agent to test a client against. Skip it if you need a supported runtime: the README states the code is for demonstration purposes, and the repository is a workspace of independent samples rather than a library. Before building on any sample, check which SDK package it imports, whether that sample is listed in the pyproject.toml workspace members, and whether the agent card it serves matches the transport you intend to use. The repository's own disclaimer is the boundary to take seriously.

## FAQ

### What does A2A stand for?

Agent2Agent. The repository is the official set of samples for the Agent2Agent protocol, which the README describes as a standardized, open standard for multi-agent interoperability.

### What is the difference between A2A and MCP?

The repository carries an a2a-mcp topic and its samples demonstrate agents communicating with other agents, while the README frames A2A as a common language for agents to communicate, collaborate and delegate tasks. MCP is not described in the README, so the repository does not draw the comparison for you.

### Is P2P the same as A2A?

The README does not mention P2P. It describes A2A as a protocol for interoperability between agents built in different frameworks and languages, and lists the SDKs and testing tools that implement it.

### What is the difference between A2A and B2B?

The README does not discuss B2B. Its subject is agent-to-agent communication, and the related repositories it lists are the specification, five SDKs, an inspector and two testing toolkits.

## Sources

- [a2aproject/a2a-samples on GitHub](https://github.com/a2aproject/a2a-samples)
- [License: Apache-2.0](https://github.com/a2aproject/a2a-samples/blob/main/LICENSE)
- [Project website](https://a2a-protocol.org)
- [README](https://github.com/a2aproject/a2a-samples/blob/main/README.md)
- [Releases](https://github.com/a2aproject/a2a-samples/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/a2aproject-a2a-samples