agents-go docs

Go agents. Local first.

The documentation for both halves of the project: the workbench — agents-server, the local agent workbench you run yourself — and the SDK it is built on, the agents package, embeddable on its own. One core, two consumers (scope §1.1).

New here? Running the workbench goes from a binary to a first session with the Inspector open; nothing on that path needs Docker. Embedding the SDK in your own program starts at the Quickstart.

The SDK's shape is idiomatic Go — generics instead of reflection magic, context.Context, errors, and iter.Seq2 streams that run on the consumer's goroutine (Streaming) — and its behavior is specified, not inherited. Arriving from the OpenAI Agents SDK for Python? Start at Differences from the Python SDK.

---

Documentation

The pages are sorted by what you came for.

Tutorial — learn by doing

Page
Running the workbench	Start here. From a binary to a first session with the Inspector open; a sandbox is the optional second chapter
Quickstart	The SDK: build and run your first agent in Go
Examples	Runnable SDK programs, one per capability, and which need more than OPENAI_API_KEY

How-to — solve one problem

Area	Pages
Core	Agents · Running agents · Results
Tools	Tools — an argument struct becomes the JSON schema, an agent becomes a tool · MCP · Sandbox agents · Skills
Orchestration	Agent orchestration · Handoffs · Background tasks
Safety	Guardrails · Human-in-the-loop — a paused run serializes to JSON and resumes in another process
State	Sessions — memory, SQLite/Postgres, or the provider's own store
Streaming	Streaming — a run is a range-able iterator you can steer mid-flight
Models	Models — configuring the SDK, providers, settings, retry and fallback
Observability	Tracing · Logging and diagnostics
Testing	Testing your agents — scripted models, no API key
Workbench, power user	None of these are needed for the first session. Deploying · Authentication · Workflows · Image input · MCP OAuth in the workbench

Reference — look something up

Page
Design spec	The behavioral invariants — what is always true
pkg.go.dev	Every exported symbol, always in sync with the code
The wire surface	What each workbench REST call means, and the WebSocket protocol
Configuration	The workbench's flags, environment variables and runtime settings

Explanation — understand why

Page
Architecture	How the pieces compose, and where the extension points are; one small core module, heavy capabilities as opt-in submodules
Design decisions	Settled decisions, each with the reason — read before reopening one
Scope	What this is, what it deliberately is not, and the roadmap
Differences from the Python SDK	For readers arriving from openai-agents-python
Upstream watch	What was reviewed from the Python SDK, ported or declined
Workbench design invariants	The rules every workbench panel/handler pair follows