https://github.com/coder/acp-go-sdk
Go SDK for the Agent Client Protocol (ACP), offering typed requests, responses, and helpers so Go applications can build ACP-compliant agents, clients, and integrations
https://github.com/coder/acp-go-sdk
acp agent-client-protocol
Last synced: about 1 month ago
JSON representation
Go SDK for the Agent Client Protocol (ACP), offering typed requests, responses, and helpers so Go applications can build ACP-compliant agents, clients, and integrations
- Host: GitHub
- URL: https://github.com/coder/acp-go-sdk
- Owner: coder
- License: apache-2.0
- Created: 2025-09-26T12:37:32.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-02-19T16:07:16.000Z (2 months ago)
- Last Synced: 2026-02-19T16:36:33.674Z (2 months ago)
- Topics: acp, agent-client-protocol
- Language: Go
- Homepage:
- Size: 209 KB
- Stars: 78
- Watchers: 1
- Forks: 16
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# ACP Go SDK
Go library for the Agent Client Protocol (ACP) - a standardized communication protocol
between code editors and AI‑powered coding agents.
Learn more about the protocol itself at .
## Installation
```bash
go get github.com/coder/acp-go-sdk@v0.10.8
```
## Get Started
### Understand the Protocol
Start by reading the [official ACP documentation](https://agentclientprotocol.com)
to understand the core concepts and protocol specification.
### Try the Examples
The [examples directory](https://github.com/coder/acp-go-sdk/tree/main/example)
contains simple implementations of both Agents and Clients in Go.
You can run them from your terminal or connect to external ACP agents.
- `go run ./example/agent` starts a minimal ACP agent over stdio.
- `go run ./example/claude-code` demonstrates bridging to Claude Code.
- `go run ./example/client` connects to a running agent and streams a sample turn.
- `go run ./example/gemini` bridges to the Gemini CLI in ACP mode (flags: -model, -sandbox, -debug, -gemini /path/to/gemini).
You can watch the interaction by running `go run ./example/client` locally.
### Explore the API
Browse the Go package docs on pkg.go.dev for detailed API documentation:
-
If you're building an [Agent](https://agentclientprotocol.com/protocol/overview#agent):
- Implement the `acp.Agent` interface (and optionally `acp.AgentLoader` for `session/load`).
- Create a connection with `acp.NewAgentSideConnection(agent, os.Stdout, os.Stdin)`.
- Send updates and make client requests using the returned connection.
If you're building a [Client](https://agentclientprotocol.com/protocol/overview#client):
- Implement the `acp.Client` interface (and optionally `acp.ClientTerminal` for
terminal features).
- Launch or connect to your Agent process (stdio), then create a connection with
`acp.NewClientSideConnection(client, stdin, stdout)`.
- Call `Initialize`, `NewSession`, and `Prompt` to run a turn and stream updates.
Helper constructors are provided to reduce boilerplate when working with union types:
- Content blocks: `acp.TextBlock`, `acp.ImageBlock`, `acp.AudioBlock`,
`acp.ResourceLinkBlock`, `acp.ResourceBlock`.
- Tool content: `acp.ToolContent`, `acp.ToolDiffContent`, `acp.ToolTerminalRef`.
- Utility: `acp.Ptr[T]` for pointer fields in request/update structs.
### Extension methods
ACP supports **extension methods** for custom JSON-RPC methods whose names start with `_`.
Use them to add functionality without conflicting with future ACP versions.
#### Handling inbound extension methods
Implement `acp.ExtensionMethodHandler` on your Agent or Client. Your handler will be
invoked for any incoming method starting with `_`.
```go
// HandleExtensionMethod handles ACP extension methods (names starting with "_").
func (a MyAgent) HandleExtensionMethod(ctx context.Context, method string, params json.RawMessage) (any, error) {
switch method {
case "_example.com/hello":
var p struct {
Name string `json:"name"`
}
if err := json.Unmarshal(params, &p); err != nil {
return nil, err
}
return map[string]any{"greeting": "hello " + p.Name}, nil
default:
return nil, acp.NewMethodNotFound(method)
}
}
```
> Note: Per the ACP spec, unknown extension notifications should be ignored.
> This SDK suppresses noisy logs for unhandled extension notifications that return
> “Method not found”.
#### Calling extension methods
From either side, use `CallExtension` / `NotifyExtension` on the connection.
```go
raw, err := conn.CallExtension(ctx, "_example.com/hello", map[string]any{"name": "world"})
if err != nil {
return err
}
var resp struct {
Greeting string `json:"greeting"`
}
if err := json.Unmarshal(raw, &resp); err != nil {
return err
}
if err := conn.NotifyExtension(ctx, "_example.com/progress", map[string]any{"pct": 50}); err != nil {
return err
}
```
#### Advertising extension support via `_meta`
ACP uses the `_meta` field inside capability objects as the negotiation/advertising
surface for extensions.
- Client -> Agent: `InitializeRequest.ClientCapabilities.Meta`
- Agent -> Client: `InitializeResponse.AgentCapabilities.Meta`
Keys `traceparent`, `tracestate`, and `baggage` are reserved in `_meta` for W3C trace
context/OpenTelemetry compatibility.
### Study a Production Implementation
For a complete, production‑ready integration, see the
[Gemini CLI Agent](https://github.com/google-gemini/gemini-cli) which exposes an
ACP interface. The Go example client `example/gemini` demonstrates connecting
to it via stdio.
## Resources
- [Go package docs](https://pkg.go.dev/github.com/coder/acp-go-sdk)
- [Examples (Go)](https://github.com/coder/acp-go-sdk/tree/main/example)
- [Protocol Documentation](https://agentclientprotocol.com)
- [Agent Client Protocol GitHub Repository](https://github.com/agentclientprotocol/agent-client-protocol)
## License
Apache 2.0. See [LICENSE](./LICENSE).