# nlpodyssey/openai-agents-go architecture

> Architecture diagram of the GitHub repository nlpodyssey/openai-agents-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nlpodyssey/openai-agents-go
- Repository: https://github.com/nlpodyssey/openai-agents-go

## Overview

This is a Go SDK for constructing and running multi-agent LLM workflows, including tools, handoffs, guardrails, persistent sessions, tracing, and voice pipelines. The main path is an application invoking the agent runner, which repeatedly calls a configured model, handles tool or handoff responses, and returns final output. Workflow configuration and voice are distinct runtime entry points. The README describes broader capabilities; sampled source directly supports the voice and session wiring noted here, while some subsystem links are omitted where implementation excerpts were unavailable.

Main entry points: [`agents/run_impl.go`](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/run_impl.go) (Run loop), [`agents/voice_pipeline.go`](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/voice_pipeline.go) (Voice pipeline), [`agents/run.go`](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/run.go) (Agent runner), [`agents/models_multi_provider.go`](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/models_multi_provider.go) (Provider selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Agent execution"]
  node_runner["Agent runner<br/>[run.go]"]
  node_loop["Run loop<br/>[run_impl.go]"]
  node_agent["Agent configuration<br/>[agent.go]"]
  node_guardrails["Guardrails<br/>[guardrail.go]"]
  node_handoffs["Handoffs<br/>[handoffs.go]"]
  node_result["Run result<br/>[result.go]"]
end

subgraph group_models["Model integration"]
  node_model_interface["Model interface"]
  node_provider["Provider selection"]
  node_openai_model["OpenAI models"]
  node_chat_model["Chat completions"]
end

subgraph group_extensions["Tools and extensions"]
  node_tools["Tool implementations<br/>[tool.go]"]
  node_mcp["MCP tools<br/>[tool_mcp.go]"]
end

subgraph group_workflow["Workflow and voice"]
  node_workflow_builder["Workflow builder<br/>[builder.go]"]
  node_workflow_runner["Workflow runner<br/>[runner.go]"]
  node_voice_pipeline["Voice pipeline<br/>[voice_pipeline.go]"]
  node_voice_models["Speech models"]
end

subgraph group_state["State and observability"]
  node_session["Session interface<br/>[session.go]"]
  node_sqlite_session[("SQLite session<br/>[sqlite_session.go]")]
  node_postgres_session[("PostgreSQL session<br/>[psql_session.go]")]
  node_tracing["Tracing<br/>[tracing.go]"]
  node_trace_processor["Trace processors<br/>[processors.go]"]
end

node_application(("Application"))
node_openai_service(("OpenAI API"))
node_mcp_service(("MCP servers"))
node_audio(("Audio input/output"))
node_database_service[("SQL database")]

node_application -->|"invokes"| node_runner
node_runner -->|"runs"| node_loop
node_loop -->|"reads config"| node_agent
node_loop -->|"requests response"| node_model_interface
node_model_interface -->|"selects provider"| node_provider
node_provider -->|"routes request"| node_openai_model
node_provider -->|"routes request"| node_chat_model
node_openai_model -->|"calls API"| node_openai_service
node_chat_model -->|"calls API"| node_openai_service
node_loop -->|"dispatches calls"| node_tools
node_tools -.->|"uses MCP tool"| node_mcp
node_mcp -.->|"calls server"| node_mcp_service
node_loop -->|"transfers control"| node_handoffs
node_loop -->|"checks safety"| node_guardrails
node_loop -->|"returns output"| node_result
node_application -->|"configures workflow"| node_workflow_builder
node_workflow_builder -->|"builds workflow"| node_workflow_runner
node_workflow_runner -->|"runs agents"| node_runner
node_application -->|"starts pipeline"| node_voice_pipeline
node_voice_pipeline -->|"creates speech models"| node_voice_models
node_voice_pipeline -->|"accepts and emits"| node_audio
node_voice_pipeline -->|"runs workflow"| node_workflow_runner
node_runner -->|"uses session"| node_session
node_session -->|"implemented by"| node_sqlite_session
node_session -->|"implemented by"| node_postgres_session
node_sqlite_session -->|"reads and writes"| node_database_service
node_postgres_session -->|"reads and writes"| node_database_service
node_runner -->|"records execution"| node_tracing
node_voice_pipeline -->|"records pipeline"| node_tracing
node_tracing -->|"dispatches spans"| node_trace_processor

click node_runner "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/run.go"
click node_loop "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/run_impl.go"
click node_agent "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/agent.go"
click node_guardrails "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/guardrail.go"
click node_handoffs "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/handoffs.go"
click node_result "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/result.go"
click node_model_interface "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/models_interface.go"
click node_provider "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/models_multi_provider.go"
click node_openai_model "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/models_openai_responses.go"
click node_chat_model "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/models_openai_chatcompletions.go"
click node_tools "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/tool.go"
click node_mcp "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/tool_mcp.go"
click node_workflow_builder "https://github.com/nlpodyssey/openai-agents-go/blob/main/workflowrunner/builder.go"
click node_workflow_runner "https://github.com/nlpodyssey/openai-agents-go/blob/main/workflowrunner/runner.go"
click node_voice_pipeline "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/voice_pipeline.go"
click node_voice_models "https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/voice_models_openai_model_provider.go"
click node_session "https://github.com/nlpodyssey/openai-agents-go/blob/main/memory/session.go"
click node_sqlite_session "https://github.com/nlpodyssey/openai-agents-go/blob/main/memory/sqlite_session.go"
click node_postgres_session "https://github.com/nlpodyssey/openai-agents-go/blob/main/memory/psql_session.go"
click node_tracing "https://github.com/nlpodyssey/openai-agents-go/blob/main/tracing/tracing.go"
click node_trace_processor "https://github.com/nlpodyssey/openai-agents-go/blob/main/tracing/processors.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_loop,node_agent,node_guardrails,node_handoffs,node_result toneBlue
class node_model_interface,node_provider,node_openai_model,node_chat_model,node_database_service toneAmber
class node_tools,node_mcp,node_openai_service,node_mcp_service toneMint
class node_workflow_builder,node_workflow_runner,node_voice_pipeline,node_voice_models toneRose
class node_session,node_sqlite_session,node_postgres_session,node_tracing,node_trace_processor,node_application,node_audio toneIndigo
```

## Components

### Agent execution

- [Agent runner](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/run.go): `agents/run.go`
- [Run loop](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/run_impl.go): `agents/run_impl.go`
- [Agent configuration](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/agent.go): `agents/agent.go`
- [Guardrails](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/guardrail.go): `agents/guardrail.go`
- [Handoffs](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/handoffs.go): `agents/handoffs.go`
- [Run result](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/result.go): `agents/result.go`

### Model integration

- [Model interface](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/models_interface.go): `agents/models_interface.go`
- [Provider selection](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/models_multi_provider.go): `agents/models_multi_provider.go`
- [OpenAI models](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/models_openai_responses.go): `agents/models_openai_responses.go`
- [Chat completions](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/models_openai_chatcompletions.go): `agents/models_openai_chatcompletions.go`

### Tools and extensions

- [Tool implementations](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/tool.go): `agents/tool.go`
- [MCP tools](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/tool_mcp.go): `agents/tool_mcp.go`

### Workflow and voice

- [Workflow builder](https://github.com/nlpodyssey/openai-agents-go/blob/main/workflowrunner/builder.go): `workflowrunner/builder.go`
- [Workflow runner](https://github.com/nlpodyssey/openai-agents-go/blob/main/workflowrunner/runner.go): `workflowrunner/runner.go`
- [Voice pipeline](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/voice_pipeline.go): `agents/voice_pipeline.go`
- [Speech models](https://github.com/nlpodyssey/openai-agents-go/blob/main/agents/voice_models_openai_model_provider.go): `agents/voice_models_openai_model_provider.go`

### State and observability

- [Session interface](https://github.com/nlpodyssey/openai-agents-go/blob/main/memory/session.go): `memory/session.go`
- [SQLite session](https://github.com/nlpodyssey/openai-agents-go/blob/main/memory/sqlite_session.go): `memory/sqlite_session.go`
- [PostgreSQL session](https://github.com/nlpodyssey/openai-agents-go/blob/main/memory/psql_session.go): `memory/psql_session.go`
- [Tracing](https://github.com/nlpodyssey/openai-agents-go/blob/main/tracing/tracing.go): `tracing/tracing.go`
- [Trace processors](https://github.com/nlpodyssey/openai-agents-go/blob/main/tracing/processors.go): `tracing/processors.go`

### Other components

- **Application**
- **OpenAI API**
- **MCP servers**
- **Audio input/output**
- **SQL database**

## Connections

- Application → Agent runner: invokes
- Agent runner → Run loop: runs
- Run loop → Agent configuration: reads config
- Run loop → Model interface: requests response
- Model interface → Provider selection: selects provider
- Provider selection → OpenAI models: routes request
- Provider selection → Chat completions: routes request
- OpenAI models → OpenAI API: calls API
- Chat completions → OpenAI API: calls API
- Run loop → Tool implementations: dispatches calls
- Tool implementations → MCP tools: uses MCP tool
- MCP tools → MCP servers: calls server
- Run loop → Handoffs: transfers control
- Run loop → Guardrails: checks safety
- Run loop → Run result: returns output
- Application → Workflow builder: configures workflow
- Workflow builder → Workflow runner: builds workflow
- Workflow runner → Agent runner: runs agents
- Application → Voice pipeline: starts pipeline
- Voice pipeline → Speech models: creates speech models
- Voice pipeline → Audio input/output: accepts and emits
- Voice pipeline → Workflow runner: runs workflow
- Agent runner → Session interface: uses session
- Session interface → SQLite session: implemented by
- Session interface → PostgreSQL session: implemented by
- SQLite session → SQL database: reads and writes
- PostgreSQL session → SQL database: reads and writes
- Agent runner → Tracing: records execution
- Voice pipeline → Tracing: records pipeline
- Tracing → Trace processors: dispatches spans