buzzagent

buzz-agent-go

buzz-agent-go is the small Go adapter between a concrete agent and buzz-acp. It implements the Agent Client Protocol over stdin/stdout and leaves model frameworks, prompts, tools, network topology, and deployment to the consuming project.

Install

go get github.com/asmogo/buzz-agent-go@latest

Until the first release tag is created, pin the pseudo-version emitted by Go for a reviewed commit on main.

Use

package main

import (
	"context"
	"log"
	"os"

	buzzagent "github.com/asmogo/buzz-agent-go"
)

func main() {
	publisher, err := buzzagent.NewCLIPublisher("buzz")
	if err != nil {
		log.Fatal(err)
	}

	handler := buzzagent.HandlerFunc(func(ctx context.Context, turn buzzagent.Turn) (buzzagent.Response, error) {
		// Initialize and call Genkit, another model framework, or ordinary Go
		// application code here. turn.Text contains normalized user content;
		// turn.RawPrompt retains the authenticated Buzz envelope.
		return buzzagent.Response{
			Text:    "Handled: " + turn.Text,
			Publish: turn.Replyable,
		}, nil
	})

	if err := buzzagent.Serve(context.Background(), os.Stdin, os.Stdout, buzzagent.Options{
		Name:      "example-agent",
		Version:   "dev",
		Handler:   handler,
		Publisher: publisher,
	}); err != nil {
		log.Fatal(err)
	}
}

Build the program as a normal Go binary and configure buzz-acp to launch it as its ACP agent command. The consuming image must provide the buzz-acp and buzz executables when those integrations are used.

Publication is opt-in for every response. A response with Publish: true fails unless the incoming prompt contains a validated Buzz event and a Publisher was configured. Unknown reply IDs written inside untrusted message content are never accepted as targets.

MCP tools from session/new

When the ACP client (for example buzz-acp with BUZZ_ACP_MCP_COMMAND set) attaches stdio MCP servers to a session, the SDK spawns one client per server at session creation and exposes their tools on every turn:

handler := buzzagent.HandlerFunc(func(ctx context.Context, turn buzzagent.Turn) (buzzagent.Response, error) {
	for _, tool := range turn.Tools {
		// tool.Name is namespaced: "<serverName>_<toolName>"
		// tool.InputSchema is a JSON Schema object (map[string]any)
		// tool.Call(ctx, json.RawMessage(argsJSON)) invokes the MCP tool
	}
	...
})

• Tools are namespaced as <serverName>_<toolName>; consumers decide which ones to expose to their model.
• Startup is fail-soft: a server that does not start, initialize, or list tools within 30 s is skipped with a warning and never fails session/new.
• Only stdio servers are supported; other transports are skipped.
• MCP clients are disconnected on session/close and on agent shutdown.

Non-goals

This module does not include:

• Genkit or another model SDK;
• concrete agents, prompts, tools, or skills;
• a direct Buzz relay client;
• Docker or Kubernetes deployment support;
• Tailscale or dashboard management.

Those concerns belong to the consuming application and its infrastructure.

Development

go test ./...
go test -race ./...
go vet ./...
test -z "$(gofmt -l .)"

License

Apache-2.0.