agents-go

A local workbench for building, running and debugging AI agents — built on a Go SDK you can also embed.

The workbench (agents-server) is one binary, one SQLite file and an embedded UI: see exactly what the model saw on each turn, replay any generation, fork any turn, approve tools in a real sandbox. Get it from Releases; the workbench manual covers flags, the REST API, the WebSocket protocol and the design invariants.

This site documents the SDK underneath. agents-go builds agentic AI apps on the OpenAI Responses API from a small set of primitives and very few abstractions. It started as a port of the OpenAI Agents SDK for Python and shares its core concepts, but it now evolves on its own: behavior is specified, not inherited.

• Agents: LLMs configured with instructions, tools, guardrails and handoffs
• Handoffs: let an agent delegate the conversation to another agent
• Guardrails: validate inputs, outputs and tool calls, in parallel with the run
• Sessions: persist conversation history across runs
• Human-in-the-loop: pause a run for tool approval and resume it later — even in another process
• Tracing: built-in spans for every model call, tool call, handoff and guardrail
• Sandboxes: run model-generated code in locked-down Docker containers

The shape is idiomatic Go: generics instead of runtime reflection magic, context.Context for cancellation, errors instead of exceptions, and iter.Seq2 for streaming — a run executes on the consumer’s goroutine, so abandoning a stream stops the run rather than leaking one. Where behavior diverges from the Python SDK it is a decision with a reason; see Differences from the Python SDK for the comparison and upstream watch for what has been reviewed and declined.

Installation

go get github.com/zzir/agents-go

The MCP client, the sandbox backends, SQL sessions and skills live in separate modules so the core stays dependency-light:

go get github.com/zzir/agents-go/mcp              # optional: MCP client + server
go get github.com/zzir/agents-go/sandbox/docker   # optional
go get github.com/zzir/agents-go/sessions         # optional: SQLite/Postgres
go get github.com/zzir/agents-go/skills           # optional: Agent Skills

Hello world

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/zzir/agents-go/agents"
	"github.com/zzir/agents-go/models/openai"
)

func main() {
	provider := openai.NewProvider() // reads OPENAI_API_KEY

	agent := &agents.Agent{
		Name:         "assistant",
		Instructions: agents.StaticInstructions("You are a concise, helpful assistant."),
	}

	res, err := agents.RunSync(context.Background(), agent, "Write a haiku about Go.", agents.RunOptions{
		Model: agents.ModelOptions{Provider: provider},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(res.FinalOutputString())
}

(Set the OPENAI_API_KEY environment variable before running.)

Documentation

Topic	Page
The workbench	Manual — flags, REST API, WebSocket protocol, design invariants
Get started	Quickstart
Configuration	Configuration
Core concepts	Agents · Running agents · Results
Tools	Tools · Model context protocol (MCP) · Sandbox agents · Skills
Orchestration	Agent orchestration · Handoffs · Background tasks
Safety	Guardrails · Human-in-the-loop
State	Sessions · Context management · Usage
Streaming	Streaming
Models	Models
Observability	Tracing · Logging and diagnostics
Testing	Testing your agents — scripted models, no API key
Examples	Examples
API index	Feature reference — every capability mapped to its API
Coming from Python?	Differences from the Python SDK
Architecture	Architecture — how the pieces compose, and where the extension points are
Behavior spec	Design spec — the invariants, and why each one is what it is
Upstream	Upstream watch — what was reviewed from the Python SDK, ported or declined

This site is open source. Improve this page.