Implement and use ACP extension methods
mainACP supports custom JSON-RPC methods that start with an underscore (_). These allow you to add functionality without breaking compatibility with future protocol versions.
Handling inbound extensions
Implement the acp.ExtensionMethodHandler interface on your Agent or Client. The handler is invoked for any incoming method starting with _.
Calling extensions
Use CallExtension (for request/response) or NotifyExtension (for notifications) on the connection object.
Advertising extensions
Extensions are negotiated via the _meta field within capability objects:
- Client to Agent:
InitializeRequest.ClientCapabilities.Meta - Agent to Client:
InitializeResponse.AgentCapabilities.Meta
Note: traceparent, tracestate, and baggage are reserved in _meta for W3C trace context/OpenTelemetry compatibility.
// 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)
}
}
// Calling an extension
raw, err := conn.CallExtension(ctx, "_example.com/hello", map[string]any{"name": "world"})
if err != nil {
return err
}
// Notifying an extension
if err := conn.NotifyExtension(ctx, "_example.com/progress", map[string]any{"pct": 50}); err != nil {
return err
}