v0.3.0 — reshaped in Go, grown into a workbench

🛠️ agents-go v0.3.0 — reshaped in Go, grown into a workbench

v0.2.0 declared independence; v0.3.0 spends it. 153 commits since v0.2.0; 598 files changed, +52k/−19k lines. Three arcs run through this release: the SDK's public surface is reshaped around Go rather than around its Python ancestry (the batched breaking changes below are the price, paid once), Anthropic becomes a first-class second backend behind the same canonical Responses format, and agents-server grows from a demo into a workbench — providers, deterministic workflows, plan mode, and a context panel that shows where your window actually went.

Breaking changes

Batched per spec §5.8 — public API compatibility begins at v1.0.0; old spelling beside new.

• A tool is a struct. The Tool interface and FunctionTool collapse into one concrete Tool struct — there is nothing left for a hosted tool to implement, which is the point. Optional capabilities remain side interfaces discovered with ToolAs.
• An item is a struct. The RunItem interface collapses into one struct with a Kind.
• Stored history moves to agents/session — Storage, Session, Projector, entries and their value types live there now (aliased in agents); the JSONL store is renamed filesession (its old package name, memory, was its opposite).
• mcp is its own module — the go-sdk dependency leaves the core; the import path is unchanged.
• Handoffs declare their graph statically — Handoff.Target replaces runtime discovery.
• The naming batch aligns the model surface (Respond / StreamResponse, InputItem, …) and drops zero-consumer exports across the SDK.
• Instructions and PromptProvider are func types; compaction.PreserveSystem *bool becomes DropSystem bool; errors carry one classification and a failed run still carries its RunResult.
• tasks.Store shrinks: the notify state machine (ConsumeNotify, MarkNotifyDelivered, ListPendingNotify, PendingNotifyParents), Config.Guard and NotifyFormatter are gone — the Manager reports endings (OnFinished / OnResultDelivered) and delivery is the host's, with the durable-host obligations recorded in the spec.
• agents-server: credentials move off agent configs into first-class provider rows; agents and routes reference a provider_id.

Highlights

A second backend, one canonical format

• models/anthropic — the Messages API as a full Model implementation, translated inside the adapter to the same canonical Responses format everything else speaks (spec §5.10). Extended thinking, tool use, prompt caching.
• models/modelkit — the dependency-free adapter toolkit, plus modelkit/conformancetest: a golden matrix every Model implementation must pass, so a third backend starts from a test suite instead of a guess.
• ChatGPT (Codex) subscriptions served through a stream-only Model decorator — blocking calls ride a stream underneath.

agents-server becomes a workbench

• Providers — one masked credential surface; ChatGPT OAuth login lives per provider; prefix routes and fallbacks resolve through the same rows.
• Workflows — fixed step sequences (plan → exec → verify, each step its own agent and model) running on a hidden child session, advanced by compare-and-set from run teardown, with on_success/on_failure edges, retry-from-the-failed-step, and dismissal. Started only by the agent (start_workflow) — the brief has to be written by something that read the conversation.
• One wake-up debt — tasks and workflows share a wakeups table; the debt lands in the same transaction as each terminal state, so a crash can never leave finished work whose conversation is never told.
• Plan mode — a session-level restraint the person toggles with the message; gated tools stay visible and refuse while planning (backed by the new Tool.ReadOnly), and the refusal outranks approval.
• The Context panel — one window bar with the compaction threshold as a tick on it, the window's composition as honest same-ruler shares (prompt layers, tool schemas, the conversation), per-call growth, cache hits, and a Compact-now button.
• Sandboxes as facts — a session's sandbox binding is a stored, versioned fact bound by CAS at run start; persistent exec_command shells on terminal-capable backends; a real web terminal.

Background work grows up

• Task retry-in-place — failed → working is a store-level compare-and-set with the attempt ceiling enforced by the database; every attempt-scoped write names its attempt.
• Replay, traced — the replay dialog reruns a call with schema/handoffs fidelity, SSE streaming, diffs and attempts.

Hardening, everywhere

• Severed model streams recover mid-turn; truncation classifies retryably.
• MCP shared connections survive one run's cancellation and redial themselves from the config that made them.
• Injected input is transactional against the turn that holds it; overflow recovery accounts for every item, on-chain or off.
• The session lifecycle, run-state resume window (spec §5.18), and the task state machine each took a dedicated audit-and-fix pass — the Fixes list below is that work.

---

Changelog

Fixes

• 6819ef8 fix(agents): commit injections only against a home that holds them; seed resume backlog eagerly
• cd0d846 fix(agents): injection transaction, usage snapshots, RunState wire completeness, abandonment cancellation
• cc841c3 fix(agents,models): recover severed streams — hold back pre-commit events, classify truncation retryably
• 55cd2d2 fix(agents-server): render a failed run's partial text as prose, not a chip
• 664f925 fix(compaction): summary prompt asks for plain prose over a transcript
• eab897f fix(handoff): validate the whole input schema, not root-level required
• e6ca8ed fix(mcp): a request on the shared connection never carries a caller's cancellation
• b80785a fix(mcp): pass multi-block tool results through as native content parts
• 94ea481 fix(mcp,toolchain): boundary fixes across mcp, tracing, tasks and the dev tools
• d5c0623 fix(models,session): record a committed fallback break, and align InMemoryRepo.List
• d578024 fix(models/openai): guard the server-side compaction rewrite with a last-seq check
• c00a32b fix(otel): stamp workflow attributes on every root span of a trace
• d0dac77 fix(run)!: injected input gets a real stream event name
• fde6166 fix(run): ResumeRun adopts a copy of the pause state's usage
• 2c10823 fix(run): a chain-built rewrite no longer deletes what the chain never saw
• b521036 fix(run): a projector that withholds an item puts it off the chain too
• e07d86e fix(run): a windowed read and a handoff filter also put items off the chain
• 5855cbd fix(run): overflow recovery keeps injected input the run had not stored yet
• 6ae8e6a fix(run): overflow recovery writes the turn on the side of the pass it survives
• cd6a515 fix(run): the forced pass on overflow reports off-chain items too
• 9514a6b fix(runstate): resume starts like a fresh run, and the decode window promises only what it can keep
• 3bcd000 fix(sandbox): a malformed exec_command call costs the call, not the run
• 5596023 fix(sandbox): advertise session_id in exec_command schema only when Sessions is on
• 1b24e47 fix(sandbox): give file tools exec's path view instead of a workdir chroot
• 5d2e26a fix(sandbox): make Policy compilation concurrency-safe
• 7a7fefa fix(sandbox): only null, 0 and false read as "none"; other scalars are refused as text
• 3ada563 fix(server): a cancelled run says so, and the bridge stops reaching past the store
• b37f50e fix(server): a tool result's display reaches the live card
• f531ae3 fix(server): restore per-method BeforeAppendModel doc comments required by revive
• 9cbe2b6 fix(server): test sinks count atomically; detach does not join the delivery goroutine
• 99a9b88 fix(session): equalDisplay compares Title and Summary too
• a0bb14e fix(tasks): a run cannot outlive the task that started it
• abd007d fix(tasks): a stop says what it did, and a fast finish is not a cancellation
• af221c1 fix(tasks): a stop that hears "already finished" looks again
• 657dcdb fix(tasks): stamp the spawning run's id on spawned tasks
• f543f80 fix(tasks): tell the model the result, or owe it — never neither
• 390a498 fix(tasks): the debt of a failed retry follows who was told
• 74b3242 fix(tasks,agents-server,web): a stop waits out a late outcome, and claims a lost one
• 89f4d75 fix(tools)!: AsTool's default input goes through...

v0.2.1

Changelog

Fixes

• cfc62a6 fix(agents-server): regenerating keeps the Inspector open
• ee48f15 fix(agents-server/web): regenerated turns no longer leave stale content

Changes

• 361330b build(deps): go-sdk v1.7.0 — protocol 2026-07-28, and RFC 9207 makes iss load-bearing
• 4ac9451 feat(agents): overflow recovery asks the storage to compact itself
• 5fa78df feat(agents-server): MCP OAuth refreshes as one mechanism, restarts included
• 18cc9aa feat(agents-server): provider registry, workflow wiring, run-plane hardening
• d20f90f feat(agents-server): replay streaming and an agent tool-surface endpoint
• f0959a1 feat(agents-server/web): replay dialog rework, workflow cards, agent form
• f48a35f feat(agents/middleware): Plan and Todo workflow middlewares
• 7cdb725 feat(models): Anthropic Messages backend via a shared modelkit
• 3e98f9b update screenshot

Full Changelog: v0.2.0...v0.2.1

v0.2.0 — independent evolution

🚀 agents-go v0.2.0 — independent evolution

v0.1.0 introduced agents-go as a faithful port of the OpenAI Agents SDK. v0.2.0 is the release where it becomes its own SDK: behavior is now specified in docs/spec.md — 61 sections of invariants, each recorded with the reason it is what it is — not inherited from upstream. 151 commits since v0.1.1; 415 files changed, +47k/−8.9k lines.

And a promise starts here: from v0.2.0 onward, breaking changes to exported identifiers go through a deprecation cycle (spec §5.8). This release spends its last pre-promise freedom deliberately — nine breaking changes that reshape the SDK around Go rather than around Python.

Breaking changes

• A run is an iterator. Run returns (RunStream, RunControl); the run executes on your goroutine — ranging the stream advances the loop, abandoning it stops the run where it stands. No producer goroutine to leak, no context you must remember to cancel. RunSync keeps its shape.
• RunOptions is grouped by what it configures: Model, Conversation, Exec, Compaction, Observe, Log.
• Middleware replaces the lifecycle hook interfaces. Wrapping a whole run — retrying it, gating it on approvals, logging it — is a RunMiddleware; agents/middleware ships Loop, Approval, Retry and Logging.
• A tool returns a contract, not a value (ToolResult), and optional tool capabilities are side interfaces discovered with ToolAs, which walks decorator stacks the way errors.As walks error chains — stacking a timeout around an approval no longer loses the approval.
• Sessions store entries, not bare items — provenance, display, usage and diagnostics ride along — and a session is a tree: retrying abandons a branch instead of deleting history, which is what makes "show me the other answer" possible.
• The session API is three layers: SessionStorage (reads and writes entries), Session (turns them into model input), EntryProjector (decides what the model gets to read).
• One Guardrail type across four stages — input, output, tool input, tool output; one value can serve several.
• ToolUseBehavior is gone — stopping early is a tool's own result, or a run-level ShouldStopAfterTurn predicate.

migration_from_python.md maps the two APIs for Python arrivals; every area below has its own doc page.

Highlights

Core runtime

• Steer a live run — RunControl.Steer / NextTurn / FollowUp inject input mid-run, each landing at a well-defined point; nothing a caller types can silently vanish.
• Turn snapshots and one save point — PrepareNextTurn reshapes the next turn (swap in a cheaper model, withdraw a used tool, tighten instructions) without mutating the Agent a concurrent run may be reading.
• Error handlers and safety valves — per-error-kind fallback completions; consecutive-failure and final-turn-without-tools policies; a truncated response never executes its tool calls.
• Failures are classified with a stable ErrorCode, and a run's Diagnostics records the trouble it survived — retries, fallbacks, tool panics — instead of losing it.

Context management

• Compaction is a run-level concern with three trigger points, one of them mid-run. Checkpoints are appended, never rewrites — folded history stays recorded and expandable.
• A context overflow compacts and retries the turn instead of failing the run.
• Crash recovery — history persists per turn and RecoverSession repairs what a crashed process left; a crash costs at most the in-flight turn.

Tools — whole-schema argument validation (not just root-level required), progressive disclosure (a tool can stay hidden until another tool's result names it), and streaming partial results from a running tool.

Background tasks — agents/tasks: sub-agents that outlive the turn that spawned them, with a persisted state machine, approval bubbling, and completion wake-ups.

Sandbox — Codex-style apply_patch editing through the Sandbox abstraction, persistent shell sessions, and a command policy that filters what runs before the approval gate.

MCP, both directions — consume stdio / streamable-HTTP servers as before; now also serve, exposing your tools or a whole agent over MCP.

Observability — vendor-neutral tracing with spans reached through the context (retry, MCP and sandbox spans included); the new tracing/otel module maps them to OpenTelemetry; structured slog logging, silent by default, with conversation content behind a second opt-in.

Testing — agentstest is public: script the model, run the agent offline, assert what it did.

agents-server — the bundled web app grew up with the SDK: session branching with in-place regenerate, backwards history paging, streaming tool cards, interactive sandbox terminals over WebSocket, a background-task plane, durable approvals with once/same/all trust scopes, and a versioned /api/v1 with an OpenAPI document.

Design notes

• Responses API only; no hosted tools — unchanged, and now recorded with reasons (spec §1.2, §3) rather than implied.
• The docs are compiled. cmd/verifydocs checks that doc snippets, godoc links, and every markdown link and anchor still name things that exist; every example runs in CI against a fake Responses API.
• Dependency-light core — the root module has four direct dependencies; Docker/SSH sandboxes, SQL sessions, Skills and OTel are opt-in submodules.

Get started

go get github.com/zzir/agents-go@v0.2.0
export OPENAI_API_KEY=sk-...
go run ./examples/hello

25 runnable examples under examples/, documentation under docs/, and the full capability → API map in features.md.

Upgrading from v0.1.x: start with the breaking list above — the docs show each new shape, and running_agents.md is the right first page. Issues and feedback are hugely welcome. Here's to v0.2.0! 🚀

Full Changelog: v0.1.1...v0.2.0

v0.1.1

Changelog

Fixes

• 27c6526 fix(frontend): anchor session row-state selectors to .session-row
• b95e4be fix(frontend): scope margin/padding reset to html,body only
• 5fc6673 fix(run): skip failed MCP servers instead of aborting the run

Changes

• e035913 Update agents-server port from 8080 to 9527
• 113758a feat(agents-server): add --host flag to configure bind address
• b0fbb84 feat(agents-server): serve interactive sandbox terminals over /ws/terminal
• 34fd8b2 feat(frontend): MCP tool arg summary and header layout alignment
• 836a794 feat(frontend): add global terminal panel with tabs and chat quoting
• b6eeada feat(frontend): encode inspector panel state in URL hash
• ee17610 feat(frontend): persist session drafts and preferences in localStorage
• ba11ea1 feat(frontend): widen side panel default and max width
• 8708dec feat(sandbox): add interactive Terminal support to ssh and docker backends
• 5f8613f refactor(agents-server): precompress static assets with gzip instead of brotli
• ad06202 rename agents-server to agents-go in CLI usage and OAuth client
• e121259 rename frontend title and manifest to agents-go

Full Changelog: v0.1.0...v0.1.1

v0.1.0

🎉 The first tagged release of agents-go — build production AI agents in Go.

agents-go is a faithful Go port of the OpenAI Agents SDK (tracking upstream v0.18.2): the same run loop, the same item model, the same defaults — type-safe by construction and idiomatic in Go. It has tracked upstream feature-for-feature, and today it gets its first tag. 🥳

Highlights

Core SDK

• Agents & a faithful run loop — same semantics as the Python SDK; streaming shares the exact same loop, so behavior is written once.
• Type-safe tools — a tool is a plain generic Go function; argument schemas and structured outputs are reflected from your structs, not runtime maps.
• Handoffs — triage and delegate between agents.
• Guardrails — input, output, and tool-level checks; a tripwire halts the run.
• Durable human-in-the-loop — pause a run for approval, serialize its state to JSON, and resume later — even in another process.
• Sessions — in-memory, JSONL file, SQLite/Postgres, or OpenAI server-side history with automatic compaction.
• Streaming — token and item events as a range-able Go iterator.
• Production plumbing — retry, fallback, and multi-provider routing as composable model decorators.
• Tracing — spans for every model call, tool call, handoff, and guardrail.

Batteries included

• MCP client — stdio and streamable-HTTP tool servers.
• Code sandboxes — run model-written code in Docker, SSH, or local backends; edit files via apply_patch.
• Agent Skills — load SKILL.md skills.
• agents-server — a full web app over the SDK: a versioned REST API, WebSocket streaming, and an embedded browser UI, with tool approval, tracing, and background spawn_task subagents.

Two ways to use it

As a library:

go get github.com/zzir/agents-go

As an app — download a prebuilt agents-server binary for your platform from the Assets below (Linux / macOS / Windows, amd64 / arm64), then run:

./agents-server --port 9527

Verify your download against checksums.txt.

Design notes

• Responses API only — internal item types are OpenAI Responses types; Chat Completions is intentionally not modeled.
• Dependency-light core — one small module; Docker/SSH sandboxes, SQL sessions, and Skills are opt-in submodules.
• Every intentional divergence from the Python SDK is documented.

Get started

Every feature ships with a runnable example:

export OPENAI_API_KEY=sk-...
go run ./examples/hello      # minimal agent
go run ./examples/handoffs   # triage → specialists
go run ./examples/hitl       # pause, approve, resume

Docs: Documentation · Feature reference · Examples

---

This is the very first release — issues and feedback are hugely welcome. Here's to v0.1.0! 🚀