a2a-go: the Go SDK for A2A agents, from handler to gRPC server

What a2a-go is for, and who should reach for it

The Agent2Agent protocol defines how one agent calls another: how it discovers what the other agent can do, how it sends a message, and how it follows a long-running task. a2a-go is the Go SDK for that protocol. The README describes it as "A Go library for running agentic applications as A2A Servers", and it also ships the client side, so the same module covers both ends of a conversation.

The audience is narrower than the topic list suggests. This is for teams whose agents are already Go programs and who want the wire protocol handled by a library instead of by hand-written JSON. If your agent is a Python service, the Go SDK does not help you; if your agent is a shell script, the CLI's serve command is the only relevant part.

The SDK version and the protocol version are tracked separately. The README states this explicitly and notes that the supported protocol version is exported in the codebase as a2a.Version. That distinction matters when you file an issue or compare against another implementation: v2.5.0 is a release of the Go package, not a claim about which specification revision you are speaking.

The handler, the transport, and why they are separate

The architecture in the README is a three-layer arrangement. At the bottom is an AgentExecutor, which is your code. Above it sits a transport-agnostic request handler created by a2asrv.NewHandler, which takes the executor plus options. Above that sit transport wrappers: a2agrpc.NewHandler, a2asrv.NewJSONRPCHandler, or a2asrv.NewRESTHandler.

The consequence is that the same executor can be served over gRPC, REST or JSON-RPC without rewriting the agent logic. The README lists multi-transport support as a feature and describes extension points for bringing your own transport implementations, authentication middlewares, and messaging or database backends. Those extension points are the reason the option types exist: newCustomOptions returns a slice of a2asrv.RequestHandlerOption, and the client side has an equivalent a2aclient.FactoryOption.

On the client side the flow starts with an AgentCard, which the README calls the information about how an agent is exposed. agentcard.DefaultResolver.Resolve returns a card, and a2aclient.NewFromCard turns that card into a client. The client is transport-agnostic, which means the card, not your code, decides whether the subsequent calls go over gRPC or HTTP. That is a clean design, but it also means a malformed or stale card produces failures at call time rather than at construction time.

Installing a2a-go and sending a first message

The module path carries a /v2 suffix, and the README requires Go 1.25.0 or newer. The repository's go.mod confirms the module is github.com/a2aproject/a2a-go/v2 with a go directive of 1.25.0.

go get github.com/a2aproject/a2a-go/v2

After that, the README's client example resolves a card and opens a client. The options argument is optional in the sense that the example passes a variable named options, but a caller with no customisation can pass none.

card, err := agentcard.DefaultResolver.Resolve(ctx)
client, err := a2aclient.NewFromCard(ctx, card, options...)

Sending a message uses a2a.NewMessage with a role and a text part. The README's snippet is a single call to SendMessage with a SendMessageRequest wrapping the message.

msg := a2a.NewMessage(a2a.MessageRoleUser, a2a.NewTextPart("..."))
resp, err := client.SendMessage(ctx, &a2a.SendMessageRequest{Message: msg})

If you would rather not write Go to try the protocol, the CLI is the shorter path. The README gives three commands: discover, send, and serve. The discover command takes a URL and prints what the agent exposes; the send command takes a URL and a message string.

go install github.com/a2aproject/a2a-go/v2/cmd/a2a@latest
a2a discover https://agent.example.com
a2a send https://agent.example.com "Hello, what can you do?"

The serve command takes an --exec flag pointing at a script and a --port flag, and exposes that script as an A2A agent. The README does not document what the script receives on stdin or must write to stdout, so treat that as something to check in cmd/README.md before relying on it.

Where a2a-go stops short

This SDK does not implement an agent. The README's server example starts with newCustomAgentExecutor(), a function the reader is expected to write. Everything about planning, tool use, model calls and state belongs to your code. If you were hoping for a framework that takes a prompt and returns an answer, this is the wrong layer.

The examples directory is thin relative to the package list. The repository contains a2a, a2aclient, a2acompat, a2aevent, a2aext, a2agrpc, a2apb, a2asrv, errordetails, log and cmd, but the README points only at examples/helloworld for a simple case and mentions examples/clustermode and examples/observability without describing them. The README also redirects to the separate a2a-samples repository for more detailed examples, which means the learning path leaves this repository early.

The go.mod pins a dependency on github.com/a2aproject/a2a-go v0.3.15 alongside the v2 module itself, which is the kind of detail worth noting if you vendor dependencies or audit a build. It is not a problem in itself, but it is a sign that the v2 line still carries the v1 module for compatibility purposes. The a2acompat package in the repository layout points the same way.

a2a-go compared with a generic RPC layer such as tRPC

People searching for this project sometimes pair it with tRPC, and the comparison is instructive because the two solve different problems. tRPC gives you end-to-end type safety between a TypeScript client and a TypeScript server, generated from your router definition. The contract is your own procedure signatures.

a2a-go gives you a contract someone else defined: the A2A protocol. The value is not type safety between your own services, it is interoperability with agents you did not write. That is why the AgentCard exists at all. A tRPC client knows the server's shape at compile time; an A2A client discovers it at runtime from a card, then picks a transport from what the card advertises.

If both ends of your system are Go services you control, a2a-go is heavier than you need. If one end is an agent built by another team or another vendor, the card-and-transport indirection is the whole point. The trade-off is that runtime discovery moves failures from compile time to call time, which is a real cost you should accept deliberately.

Maintenance, releases and the Apache 2.0 licence

The repository is not archived, and the last push was on 2026-09-09, days before this writing. Releases are frequent: v2.5.0 on 2026-08-18, v2.4.0 on 2026-07-28, and v2.3.1 on 2026-05-13. The presence of .release-please-manifest.json and .goreleaser.yaml in the repository root indicates an automated release pipeline rather than manual tagging.

That cadence has a cost. A dependency that ships minor releases roughly monthly will require you to read CHANGELOG.md before each bump, and the /v2 module path means the project has already gone through one major-version break. If you pin aggressively, you will fall behind the protocol; if you track latest, you own the upgrade work. There is no LTS branch documented in the README.

The licence is Apache-2.0, stated in the README and present as a LICENSE file. Apache 2.0 is permissive and includes an explicit patent grant, which is the usual reason teams prefer it over MIT for protocol implementations. This is a description of the licence text, not legal advice; if your organisation has a policy on patent clauses or attribution, run it past whoever handles that.

Editorial conclusion

Adopt a2a-go if your agents are Go services and you want the A2A protocol handled by a library rather than hand-rolled JSON-RPC. Do not adopt it if you need a language-neutral gateway or a framework that runs the agent loop for you; this SDK only handles the protocol surface. Verify first that the A2A specification version you need matches what a2a.Version reports, and that your transport choice (gRPC, REST or JSON-RPC) is the one your counterpart agents actually expose.

Frequently asked questions

Official sources

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