agent-sdk-go

module

v0.5.0 Latest Latest Go to latest Published: Jul 15, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/jedwards1230/agent-sdk-go

Links

Open Source Insights

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: v0.2.0, M2 shipped. The typed Event/Op contract, the two-tier event broker, real Anthropic/OpenAI providers (API key + subscription OAuth), the agent loop, builtin tools, the runner package, and a clean-room acp (Agent Client Protocol) adapter are all in place. Next up is M3, the permission/guardrails milestone (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

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. Swap in provider: anthropic or provider: openai (API key or subscription OAuth) for a real model; the runner package is the batteries-included alternative to hand-wiring loop + session yourself.

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
`providers/`	`providers.Build` — construct a real provider (Anthropic/OpenAI) from manifest config
`auth/`	OAuth flows + on-disk token store (`auth.json`, mode 0600) for subscription auth
`loop/`	The agent loop: model calls, tool execution, hooks
`tool/`	Builtin tool registry: bash/read/edit/write/grep/glob/ls
`session/`	Session identity (UUIDv7), turn execution, event emission
`compose/`	Agent manifest (YAML) → wired session
`runner/`	Batteries-included drivable session (`New`/`Resume`/`Prompt`/`Events`/`Fold`/`Cost`) assembling provider + tools + broker + loop + journal
`acp/`	Clean-room Agent Client Protocol adapter (stdlib-only), a pure Event/Op projection

Planned: permission/, skill/, plugin/, lsp/, mcp/.

Roadmap

Stage	Ships
M0 · scaffold ✅	Event/Op types, broker, compose skeleton, faux provider, golden-file harness, CI
M1 · one good session ✅	Loop + real provider (Anthropic + OpenAI) + builtin tools + JSONL session tree + usage/cost accounting
M2 · the daemon ✅	(in the consuming application) supervisor + TUI + native ACP; SDK ships `acp/` + `runner/`
M3 · guardrails	Sandboxed/contained exec, approval messages, binary containment policy, tool-output spill files, headless exec, LSP diagnostics
M4 · ecosystem	MCP client (tool-search-first), SKILL.md skills, plugin subprocess host, session tree / subagent spawn seam, vendor settings adapters, provider breadth
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 ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
acp 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.
auth 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).
compose 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.
event 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.
exec Package exec is the SDK's headless one-shot adapter: it drives a drivable session to completion with a single prompt and emits the typed event stream as JSONL on an io.Writer (os.Stdout by default) — the SDK half of an application's `exec` verb.	Package exec is the SDK's headless one-shot adapter: it drives a drivable session to completion with a single prompt and emits the typed event stream as JSONL on an io.Writer (os.Stdout by default) — the SDK half of an application's `exec` verb.
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.
loop 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.
lsp Package lsp is the SDK's Language Server Protocol seam: a curated server registry and a stdlib-only JSON-RPC-over-stdio client, wired to a neutral diagnostics-publishing interface the consuming application maps onto its own event stream.	Package lsp is the SDK's Language Server Protocol seam: a curated server registry and a stdlib-only JSON-RPC-over-stdio client, wired to a neutral diagnostics-publishing interface the consuming application maps onto its own event stream.
permission Package permission is the SDK's format-agnostic permission rule engine: a typed []Rule + evaluator the guard consults for the deny/allow-before-sandbox step.	Package permission is the SDK's format-agnostic permission rule engine: a typed []Rule + evaluator the guard consults for the deny/allow-before-sandbox step.
provider 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.
providers 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.
runner 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.
session Package session provides session identity and single-turn execution.	Package session provides session identity and single-turn execution.
spill Package spill streams a tool call's raw output to a durable, append-only per-call file while retaining only a bounded head+tail excerpt (plus a running sha256 and byte count) in memory.	Package spill streams a tool call's raw output to a durable, append-only per-call file while retaining only a bounded head+tail excerpt (plus a running sha256 and byte count) in memory.
tool 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).