Skip to content

OpenAI Agents Go SDK

CI Go Report Card GoDoc License: MIT

A production-ready, type-safe Go framework for building intelligent multi-agent workflows with comprehensive security guardrails, persistent sessions, and enterprise-grade observability.

Community Project

This is an unofficial community-maintained SDK inspired by the official OpenAI Agents Python SDK and OpenAI Agents JavaScript SDK, but is not affiliated with or endorsed by OpenAI.

Why Use the Agents SDK?

🔒 Security First

The SDK provides comprehensive security guardrails to protect your applications:

  • PII Detection & Protection: Automatically detect and mask 10+ types of sensitive data including SSNs, credit cards, emails, phone numbers, and more
  • 9+ Built-in Guardrails: Rate limiting, profanity filtering, prompt injection detection, URL validation, secret scanning
  • Content Moderation: OpenAI Moderation API integration with 13 safety categories
  • Tool Approvals: Human-in-the-loop safety workflows for dangerous operations
  • Input/Output Validation: Protect both incoming requests and agent responses

Learn about Guardrails

🚀 Production Ready

Built for enterprise deployment with battle-tested features:

  • Zero Dependencies: Core SDK has no external dependencies beyond the official OpenAI Go SDK
  • Type Safety: Full compile-time type checking with Go generics for reliable code
  • Session Management: Persistent conversations with multiple backends (memory, file, SQLite, PostgreSQL, Redis)
  • Observability: OpenTelemetry tracing for monitoring agent behavior and performance
  • Error Handling: Comprehensive error types with built-in retry strategies
  • High Test Coverage: Extensively tested with >85% code coverage

⚡ Developer Experience

Designed for Go developers who value clean, maintainable code:

  • Idiomatic Go: Clean patterns following Go best practices
  • Rich Examples: 25+ working examples covering all features
  • Comprehensive Docs: Full documentation site with guides, tutorials, and API reference
  • Multi-Agent Workflows: Seamless agent handoffs and composition
  • Streaming Support: Real-time token-by-token and event-based streaming
  • Flexible Architecture: Model provider abstraction for multi-LLM support

Quick Example

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    agents "github.com/MitulShah1/openai-agents-go"
    "github.com/openai/openai-go"
    "github.com/openai/openai-go/option"
)

func main() {
    // Initialize OpenAI client
    client := openai.NewClient(option.WithAPIKey(os.Getenv("OPENAI_API_KEY")))
    runner := agents.NewRunner(&client)

    // Create an agent
    agent := agents.NewAgent("Assistant")
    agent.Instructions = "You are a helpful assistant"

    // Run the agent
    messages := []openai.ChatCompletionMessageParamUnion{
        openai.UserMessage("Write a haiku about Go programming"),
    }

    result, err := runner.Run(context.Background(), agent, messages, nil, nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.FinalOutput)
}

Installation

go get github.com/MitulShah1/openai-agents-go@latest

Requirements: Go 1.24 or higher

Comprehensive Feature Set

Feature Status Description
Multi-Agent Workflows ✅ Complete Compose and orchestrate multiple specialized agents
Tool Integration ✅ Complete Seamlessly call Go functions from agent responses
Runtime Agent Skills ✅ Complete Reusable capability bundles (instructions + tools + guardrails)
Handoffs ✅ Complete Dynamic agent-to-agent transfers during execution
Structured Outputs ✅ Complete Schema-validated JSON responses with fluent API
Lifecycle Hooks ✅ Complete Execute code before/after agent runs
Context Variables ✅ Complete Pass state between agents and tools
Usage Tracking ✅ Complete Monitor token consumption and costs
Error Handling ✅ Enhanced Comprehensive error types for robust applications
🛡️ Security & Safety
Guardrails Framework ✅ Complete Extensible input/output validation system
PII Detection ✅ Complete 10+ detector types for sensitive data protection
Content Moderation ✅ Complete OpenAI Moderation API (13 categories)
Rate Limiting ✅ Complete Token bucket algorithm with burst support
Profanity Filtering ✅ Complete Customizable word list filtering
Prompt Injection Detection ✅ Complete Protect against malicious prompts
URL Validation ✅ Complete Domain allowlists and blocklists
Secret Detection ✅ Complete Find API keys, tokens, passwords
Regex Filtering ✅ Complete Custom pattern-based validation
Guardrail Composition ✅ Complete Chain guardrails sequentially or in parallel
Tool Approvals ✅ Complete Human-in-the-loop approval workflows
💾 Data & Persistence
Sessions Framework ✅ Complete Persistent conversation history
Memory Sessions ✅ Complete In-memory storage for development
File Sessions ✅ Complete File-based persistence
SQLite Sessions ✅ Complete Embedded database backend
PostgreSQL Sessions ✅ Complete Production database backend (build tag)
Redis Sessions ✅ Complete Distributed cache backend (build tag)
Cloud Sessions ✅ Complete OpenAI Conversations API integration
Session Encryption ✅ Complete Secure sensitive data at rest
Message Compaction ✅ Complete Automatic history pruning
⚡ Performance & Scale
Streaming ✅ Complete Token-by-token and object-based streaming
Parallel Tools ✅ Complete Concurrent tool execution
Tracing & Observability ✅ Complete OpenTelemetry integration
Multimodal Support ✅ Complete Images, files, and rich content
Model Abstraction ✅ Complete Pluggable LLM providers
Prompts API ✅ Complete Static and dynamic prompt management
🔮 Advanced Integrations
MCP Support ✅ Complete Model Context Protocol integration
Computer Use ✅ Complete Browser/desktop automation interface
Diff Tool ✅ Complete Structured code change application

See the CHANGELOG for detailed release history.

Core Concepts

Agents

LLMs configured with instructions, tools, and behavior settings. Each agent is a specialized worker optimized for specific tasks.

Learn about Agents

Tools

Go functions that agents can call to perform actions, fetch data, or interact with external systems. Type-safe and easy to define.

Learn about Tools

Guardrails

Input/output validation for safety and compliance. Protect against PII leaks, harmful content, rate abuse, and policy violations.

Learn about Guardrails

Sessions

Persistent conversation history and memory management. Support multiple storage backends for different deployment scenarios.

Learn about Sessions

Handoffs

Transfer control between specialized agents dynamically based on task requirements or user requests.

Learn about Handoffs

Structured Outputs

Schema-validated JSON responses for reliable parsing. Define expected output format and get compile-time safety.

Learn about Structured Outputs

Streaming

Real-time token-by-token or event-based streaming for responsive user experiences.

Learn about Streaming

Tracing

OpenTelemetry integration for monitoring, debugging, and performance analysis.

Learn about Tracing

Next Steps

  • Quickstart

    Get started quickly with our comprehensive quickstart guide

    Get Started

  • Guardrails Guide

    Learn how to protect your applications with PII detection and security guardrails

    Secure Your Agents

  • Core Concepts

    Deep dive into agents, tools, handoffs, and more

    Learn Concepts

  • API Reference

    Detailed API documentation for all types and functions

    API Docs

  • Examples

    Browse 25+ working examples on GitHub

    View Examples

  • Sessions

    Persist conversation history with flexible storage backends

    Manage Sessions

Comparison with Official SDKs

Feature Python SDK JavaScript SDK Go SDK (This)
Agents ✅ ✅ ✅
Tools ✅ ✅ ✅
Handoffs ✅ ✅ ✅
Structured Outputs ✅ ✅ ✅
Streaming ✅ ✅ ✅
Guardrails ✅ ✅ ✅ 9+ types
PII Detection ✅ ✅ ✅ 10+ detectors
Tracing ✅ ✅ ✅ OpenTelemetry
MCP Support ✅ ✅ ✅
Computer Use ✅ ✅ ✅
Tool Approvals ✅ ❌ ✅
Prompts API ✅ ❌ ✅
Model Abstraction ❌ ❌ ✅
Voice Agents ❌ ✅ 🔮 Planned
Type Safety ⚠️ Runtime ⚠️ TypeScript ✅ Compile-time
Zero Dependencies ❌ ❌ ✅ (core only)
Performance ~ ~ ✅ Native Go

Community & Support

Made with ❤️ by the Go community