README
¶
agent-sdk-go
An importable, provider-agnostic agent framework for Go: an owned, auditable agent loop with sessions, permissions, tools, skills, MCP, ACP, plugins, and declarative agent manifests.
Status: M0 scaffold. The typed Event/Op contract, the two-tier event broker, and
compose.Load()streaming a faux provider are in place. The real loop, providers, and tools land next (see the roadmap).
Why
Today's coding agents force a trade: genuinely hackable loops exist mostly in
TypeScript ecosystems, while the Go implementations are either unimportable
monoliths (internal/ everything) or LLM-app graph frameworks — the wrong
shape for an interactive agent. agent-sdk-go is the missing piece: a small,
importable loop you can read end-to-end, embed in your own product, and trust
because everything in the model's context went through code you own.
Design tenets
- Own the loop — small, injectable, never-throw callbacks. Trust in what's in context is the product.
- Stream from day one — the core loop emits incremental typed events; accumulate-then-send is a design bug, not a mode.
- Everything is a client — one typed Event/Op contract above the loop. TUIs, ACP, headless exec, and HTTP are projections; none is privileged.
- Structural permissions — deny lives in an engine, not a prompt.
- Declarative agents, code as escape hatch — an agent is a manifest;
compose.Load()wires it. - Out-of-process extensibility — plugins are subprocesses over JSON-RPC; nothing untrusted runs in your process.
Quickstart (M0)
sess, err := compose.Load(ctx, "agent.yaml") // manifest → wired session
if err != nil { ... }
sub := sess.Subscribe(event.FilterAll)
defer sub.Close()
go func() { _ = sess.Prompt(ctx, "hello") }()
for ev := range sub.C {
switch e := ev.(type) {
case event.MessageFinished:
fmt.Println(e.Content)
case event.TurnFinished:
return
}
}
With provider: faux in the manifest this runs entirely offline — the same
harness the golden-file tests use.
Packages
| Package | Role |
|---|---|
event/ |
Typed Event/Op contract · two-tier broker (lossy deltas, must-deliver terminals, drop counters) |
provider/ |
LLM provider interface + normalized stream · faux scripted provider |
session/ |
Session identity (UUIDv7), turn execution, event emission |
compose/ |
Agent manifest (YAML) → wired session |
Planned: loop/, permission/, tool/, skill/, plugin/, lsp/, mcp/,
adapters/ (acp · httpapi+sse · exec).
Roadmap
| Stage | Ships |
|---|---|
| M0 · scaffold ✅ | Event/Op types, broker, compose skeleton, faux provider, golden-file harness, CI |
| M1 · one good session | Loop + real provider + builtin tools + JSONL session tree + usage/cost accounting |
| M2 · the daemon | (in gofer) supervisor + TUI + native ACP |
| M3 · guardrails | Permission engine, approval messages, sandboxed exec, LSP diagnostics |
| M4 · ecosystem | MCP client, SKILL.md skills, plugin subprocess host |
| M5 · auto + polish | Reviewer pipeline, WASM plugin tier, asset import |
The SDK must always build and test green with zero application code present — the embedder is a CI gate, not a hope.
License
Apache-2.0. See NOTICE for attribution requirements.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package acp models the Agent Client Protocol (ACP) v1 wire types and the pure projection functions between them and this SDK's typed event.Event / event.Op contract.
|
Package acp models the Agent Client Protocol (ACP) v1 wire types and the pure projection functions between them and this SDK's typed event.Event / event.Op contract. |
|
Package auth persists provider credentials and drives the OAuth login flows for subscription auth (Anthropic Claude Pro/Max, OpenAI ChatGPT).
|
Package auth persists provider credentials and drives the OAuth login flows for subscription auth (Anthropic Claude Pro/Max, OpenAI ChatGPT). |
|
Package compose turns a declarative agent manifest into a wired session or a wired agent loop.
|
Package compose turns a declarative agent manifest into a wired session or a wired agent loop. |
|
Package event defines the typed Event/Op contract that sits above the agent loop, plus the two-tier broker that delivers events to subscribers.
|
Package event defines the typed Event/Op contract that sits above the agent loop, plus the two-tier broker that delivers events to subscribers. |
|
internal
|
|
|
goldenio
Package goldenio is a test helper for golden-file event-stream assertions.
|
Package goldenio is a test helper for golden-file event-stream assertions. |
|
Package loop owns the agent loop: it drives a provider through one or more model calls, converts the provider's normalized stream into the typed event contract, executes tool calls between calls, and stops at an end-of-turn stop reason or an iteration cap.
|
Package loop owns the agent loop: it drives a provider through one or more model calls, converts the provider's normalized stream into the typed event contract, executes tool calls between calls, and stops at an end-of-turn stop reason or an iteration cap. |
|
Package provider defines the LLM provider interface and the normalized event stream the agent loop consumes.
|
Package provider defines the LLM provider interface and the normalized event stream the agent loop consumes. |
|
anthropic
Package anthropic implements the provider.Provider interface against the Anthropic Messages API.
|
Package anthropic implements the provider.Provider interface against the Anthropic Messages API. |
|
faux
Package faux provides a deterministic, scripted provider.Provider for tests and demos.
|
Package faux provides a deterministic, scripted provider.Provider for tests and demos. |
|
openai
Package openai implements a provider.Provider for OpenAI models over the Responses API (POST /responses with stream:true), not the older Chat Completions API.
|
Package openai implements a provider.Provider for OpenAI models over the Responses API (POST /responses with stream:true), not the older Chat Completions API. |
|
Package providers is the factory apps use to construct a provider.Provider from a model id, so embedders stop importing the vendor adapter packages directly.
|
Package providers is the factory apps use to construct a provider.Provider from a model id, so embedders stop importing the vendor adapter packages directly. |
|
Package runner is the SDK's composable session runner: it builds a provider and tool registry, drives the SDK's agent loop, and streams the loop's typed events into a durable session journal as each model-call turn settles.
|
Package runner is the SDK's composable session runner: it builds a provider and tool registry, drives the SDK's agent loop, and streams the loop's typed events into a durable session journal as each model-call turn settles. |
|
Package session provides session identity and single-turn execution.
|
Package session provides session identity and single-turn execution. |
|
Package tool provides the Tool interface, a Registry, and a set of importable builtin coding tools (bash, read, edit, write, grep, glob, ls).
|
Package tool provides the Tool interface, a Registry, and a set of importable builtin coding tools (bash, read, edit, write, grep, glob, ls). |
Click to show internal directories.
Click to hide internal directories.