A2A Go SDK A2A SDK

A2A Go SDK

<!-- markdownlint-disable no-inline-html --> <div align="center"> <img src="https://raw.githubusercontent.com/a2aproject/A2A/refs/heads/main/docs/assets/a2a_logo/color/SVG/a2a_color.svg" width="256" alt="A2A Logo"/> <h3> A Go library for running agentic applications as A2A Servers, following the <a href="https://a2a-protocol.org">Agent2Agent&nbsp;(A2A)&nbsp;Protocol</a>. </h3> </div> <!-- markdownlint-enable no-inline-html -->

---

✨ Features

• A2A Protocol Compliance: Build agentic applications that adhere to the Agent2Agent (A2A) v1.0 Protocol Specification.
• Client & Server SDKs: High-level APIs for both serving agentic functionality (a2asrv) and consuming it (a2aclient).
• Multi-Transport Support: Protocol bindings for gRPC, REST, and JSON-RPC.
• Extensible & Pluggable: Extension points for bringing your own transport implementations, authentication middlewares, messaging and database backends.

Note: The SDK version is distinct from the A2A specification version. The supported protocol version is exported in the codebase as a2a.Version

---

🚀 Getting Started

Requires Go 1.26.0 or newer, as specified in go.mod:

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

Visit pkg.go for a full documentation.

💡 Examples

For a simple example refer to the helloworld example.

Server

For a full documentation visit pkg.go.dev/a2asrv.

1. Create a transport-agnostic A2A request handler:

   var options []a2asrv.RequestHandlerOption = newCustomOptions()
   var agentExecutor a2asrv.AgentExecutor = newCustomAgentExecutor()
   requestHandler := a2asrv.NewHandler(agentExecutor, options...)
   

2. Wrap the handler into a transport implementation:

   grpcHandler := a2agrpc.NewHandler(requestHandler)
   
   // or
   
   jsonrpcHandler := a2asrv.NewJSONRPCHandler(requestHandler)
   
   // or
   
   restHandler := a2asrv.NewRESTHandler(requestHandler)
   

3. Register handler with a server, for example:

   import "google.golang.org/grpc"
   ...
   server := grpc.NewServer()
   grpcHandler.RegisterWith(server)
   err := server.Serve(listener)
   
   // or
   
   http.Handle("/", restOrJSONRPCHandler)
   err := http.ListenAndServe(":8080", nil)
   

Client

For a full documentation visit pkg.go.dev/a2aclient.

1. Resolve an AgentCard to get an information about how an agent is exposed.

   card, err := agentcard.DefaultResolver.Resolve(ctx, "https://a2a.example.com")
   

2. Create a transport-agnostic client from the AgentCard:

   var options a2aclient.FactoryOption = newCustomClientOptions()
   client, err := a2aclient.NewFromCard(ctx, card, options...)
   

3. The connection is now open and can be used to send requests to a server:

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

---

🔧 CLI

A companion command-line tool for working with A2A agents - send messages, inspect tasks, resolve agent cards, or setup simple a2a servers - lives in its own repository: a2aproject/a2a-cli.

# Install
go install github.com/a2aproject/a2a-cli@latest

# Discover an agent
a2a discover https://agent.example.com

# Send a message
a2a send https://agent.example.com "Hello, what can you do?"

# Expose a local script as an A2A agent
a2a serve --exec "./my-script.sh" --port 8080

See the a2a-cli README or run a2a help for the full command reference.

---

🌐 More Examples

You can find a variety of more detailed examples in the a2a-samples repository.

---

🤝 Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines on how to get involved.

Before starting work on a new feature or significant change, please open an issue to discuss your proposed approach with the maintainers. This helps ensure your contribution aligns with the project's goals and prevents duplicated effort or wasted work.

---

📄 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.