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 https://agentclientprotocol.com.

Installation

go get github.com/coder/acp-go-sdk@v0.13.5

Get Started

Understand the Protocol

Start by reading the official ACP documentation to understand the core concepts and protocol specification.

Try the Examples

The examples directory 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:

• https://pkg.go.dev/github.com/coder/acp-go-sdk

If you're building an 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:

• 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 _.

// 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.

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 which exposes an ACP interface. The Go example client example/gemini demonstrates connecting to it via stdio.

Resources

• Go package docs
• Examples (Go)
• Protocol Documentation
• Agent Client Protocol GitHub Repository

License

Apache 2.0. See LICENSE.