agents-go

OpenAI Agents SDK for Go

agents-go is a Go port of the OpenAI Agents SDK for Python (tracking v0.17.4). It lets you build agentic AI apps with a small set of primitives and very few abstractions:

• 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 SDK follows the Python design closely — same run loop, same item model, same defaults — while staying idiomatic Go: generics instead of runtime reflection magic, context.Context for cancellation, errors instead of exceptions. See Differences from the Python SDK for the complete comparison.

Installation

go get github.com/zzir/agents-go

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

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.Run(context.Background(), agent, "Write a haiku about Go.", agents.RunOptions{
		ModelProvider: provider,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(res.FinalOutputString())
}

(Set the OPENAI_API_KEY environment variable before running.)

Documentation

Topic	Page
Get started	Quickstart
Configuration	Configuration
Core concepts	Agents · Running agents · Results
Tools	Tools · Model context protocol (MCP) · Sandbox agents · Skills
Orchestration	Agent orchestration · Handoffs
Safety	Guardrails · Human-in-the-loop
State	Sessions · Context management · Usage
Streaming	Streaming
Models	Models
Observability	Tracing
Examples	Examples
Coming from Python?	Differences from the Python SDK

This site is open source. Improve this page.