Skip to content

v0.2.0 — independent evolution

Choose a tag to compare

View all tags
@github-actions github-actions released this 28 Jul 12:57
· 168 commits to main since this release
v0.2.0
67515a4
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

🚀 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

Assets 9
Loading