Runnable examples live in examples/. Each is a standalone main package:
export OPENAI_API_KEY=sk-...
go run ./examples/hello
| Example | Shows |
|---|---|
examples/hello |
The minimal agent: provider, instructions, one Run |
examples/testing |
Testing an agent with agentstest: scripted model, no API key (Testing) |
examples/tools |
Typed function tools via NewTool |
examples/toolimage |
A tool returning image content (ToolOutputImage) |
examples/handoffs |
A triage agent delegating to specialists with HandoffTo |
examples/streaming |
Ranging a RunStream |
examples/hitl |
Human-in-the-loop: interrupt, approve/reject, resume |
examples/errorhandlers |
RunOptions.Exec.ErrorHandlers: fallback final outputs for max-turns and invalid structured output |
examples/tracing |
The tracing pipeline: tracer → batch processor → console exporter, plus TraceGroupID/TraceMetadata |
examples/fallback |
Retry + fallback model decorators, with WithShouldFallback classification |
examples/anthropic |
Streaming an agent on Claude via the Anthropic Messages provider — tool loop plus token deltas (separate module) |
examples/compaction |
openai.CompactionSession: server-side history compaction via responses.compact |
examples/toolstream |
ToolContext.Emit: a running tool’s progress on the stream, and why it is not the answer |
examples/steering |
RunControl’s three queues: steer, next-turn, follow-up |
examples/branching |
A session is a tree: branch from an earlier point without deleting the attempt |
examples/projector |
EntryProjector: deciding what the model gets to read |
examples/mcpserver |
Serving SDK tools over MCP to an editor or another agent (separate module) |
examples/tasks |
Background sub-agents: spawn, the wake-up debt, and the parent woken with the result |
examples/middleware |
Run middleware: Retry + Approval policy + evaluator-driven Loop, stacked |
examples/planmode |
Plan mode + todo list: read-only exploration, a submit_plan approval pause, then execution in the same run |
examples/runcompaction |
Run-level compaction: a compaction.Strategy folding tool results mid-run, at the turn boundary |
examples/conversations |
openai.ConversationsSession: history stored server-side via the Conversations API |
examples/prompt |
Binding an OpenAI stored prompt via Agent.Prompt |
examples/bravesearch |
The Brave web-search tool (tools/bravesearch) |
examples/sandbox |
An agent that writes and runs code in a local sandbox |
sandbox/docker/example |
The Docker sandbox backend (separate module) |
sandbox/ssh/example |
The SSH sandbox backend (separate module) |
sessions/example |
SQLite-backed session persistence (separate module) |
skills/example |
Loading SKILL.md skills into an agent (separate module) |
Most examples only need OPENAI_API_KEY. The exceptions:
examples/prompt — a stored prompt ID: OPENAI_PROMPT_ID=pmpt_... go run ./examples/promptexamples/anthropic — ANTHROPIC_API_KEY=... go run . (from its directory; separate module)examples/mcpserver — go run . (from its directory; separate module, no API key)examples/bravesearch — BRAVE_API_KEY=... go run ./examples/bravesearchexamples/sandbox — the host needs python3(cd sessions && go run ./example) # SQLite-backed session
(cd skills && go run ./example) # Agent Skills (SKILL.md)
(cd sandbox/docker && go run ./example) # needs a running Docker daemon
(cd sandbox/ssh && SSH_HOST=host SSH_USER=user SSH_KEY=~/.ssh/id_ed25519 \
go run ./example) # needs a reachable SSH host
The test suites are also worth reading as usage references — agents/run_test.go shows how to script a fake model (Agent.ModelImpl) for offline tests of your own agents.