# openai/openai-agents-js architecture

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

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

## Overview

##### Project type and purpose
- Project type: A monorepo open-source JavaScript/TypeScript SDK for building multi-agent workflows (provider-agnostic)
- Purpose: Expose a core “Agent” abstraction plus extensions (OpenAI, real-time, third-party transports), tooling (guardrails, tracing, handoffs), docs website, examples, tests, and CI/CD pipelines.

##### File structure
Top-level directories:
– packages/agents-core: Core SDK logic (agent loop, lifecycle, tools, guardrails, tracing)
– packages/agents-openai: OpenAI-specific provider implementation
– packages/agents-realtime: Browser & Node real-time transports (WebSocket, WebRTC)
– packages/agents-extensions: Additional transports & SDK integrations (e.g., Twilio, Vercel AI SDK adapter)
– packages/agents: A convenience bundle combining core + realtime + basic metadata
– examples/: Reference applications for basic, connector, Next.js, realtime demos, etc.
– docs/: Static site (built with Astro + Tailwind + Starlight) for user documentation
– integration-tests/: End-to-end tests across Node, Deno, Bun, Workers, React/Vite
– helpers/: Shared test utilities
– .github/, CI workflows: Automated test, release, docs-build pipelines
– root config files: pnpm-workspace, tsconfig, Vitest (unit & integration), linting, formatting.

##### README for additional insights
- Key concepts: Agents, Handoffs, Guardrails, Tracing
- Supported environments: Node.js, Deno, Bun, Cloudflare Workers
- Features: Multi-agent orchestration, streaming, parallelization, human-in-the-loop, voice agents
- Usage patterns: Agent loop sequence, tool calls, structured outputs, handoffs
- Examples invoked via `pnpm examples:<name>`

4.a Core components
– Agent Core (packages/agents-core)
– Providers: OpenAI provider (packages/agents-openai), Realtime provider (packages/agents-realtime), Extensions (agents-extensions)
– Runner/Executor: The loop orchestrating LLM calls, tool invocations, guardrails, and handoffs
– Tools & Handoffs subsystem (built into core)
– Guardrails & Validation layer
– Tracing & Telemetry store (context, spans, processors, exporters)
4.b Auxiliary components
– Monorepo orchestration (pnpm, workspace)
– Build & Test (Vitest unit/integration, helpers, CI workflows)
– Documentation site (docs/ Astro project)
– Example apps (Next.js, plain TS, React/Vite, Twilio voice demos, etc.)
4.c External services & flows
– OpenAI API (HTTP calls for completions, chat, streaming)
– WebSocket / WebRTC endpoints for realtime voice agents
– Local MCP server for tool hosting
– Browser environment (for realtime & examples)
– CI/CD (GitHub Actions triggering tests, docs deploy, release tagging)

##### Relationships and data flows
– Agent Core → Provider adapters → External LLM API
– Agent Core → Tools/Handoffs → External service or internal function
– Runner loop invoking: model call → parse response → guardrails check → tool exec/handoff → loop continuation
– Tracing subsystem listening to each step and exporting to spans/store
– Realtime Session: Bi-directional audio/video stream → Realtime provider → Agent Core
– Examples & Docs: Consume built SDK packages via import, exercise core and providers
– CI pipelines operating on root: test, build, lint, docs:build, release

##### Architectural patterns & principles
- Plugin architecture: Core agnostic of provider, extensions register via well-defined interfaces
- Modular monorepo: Each package with its own build/test, shared typings & helpers
- Adapter pattern: Provider packages implement a common “Provider” interface
- Event-driven loop: Agent loop emits events (tool calls, handoffs, completion) consumed by runner/tracing
- Separation of concerns: Core logic vs. transport vs. examples vs. docs vs. CI

##### Detailed layering
- Top layer: Developer/Consumer – imports SDK, runs examples
- Core layer: Agent Runner, Tools, Guardrails, Tracing
- Provider layer: OpenAI, Realtime, Extensions
- External layer: LLM APIs, WebRTC servers, MCP server
- Support layer: CI/CD workflows, Docs site, Examples

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer
    Developer["Developer / Consumer"]:::external

    %% Monorepo Workspace
    subgraph "Monorepo Workspace"
        direction TB
        PNPM["pnpm-workspace.yaml"]:::monorepo
        TSConfig["tsconfig.json"]:::monorepo
        RootPkg["package.json"]:::monorepo
        subgraph "Packages"
            direction TB
            %% Core Packages
            subgraph "Core Packages" 
                direction TB
                AgentCore["agents-core"]:::core
                subgraph "Runner / Executor"
                    direction TB
                    RunTS["run.ts"]:::core
                    RunImpl["runImplementation.ts"]:::core
                end
                subgraph "Tools & Handoffs"
                    direction TB
                    ToolDef["tool.ts"]:::core
                    HandoffLogic["handoff.ts"]:::core
                    HandoffExt["extensions/"]:::core
                end
                Guardrail["guardrail.ts"]:::core
                subgraph "Tracing & Telemetry"
                    direction TB
                    TracingDir["tracing/"]:::core
                end
            end
            %% Provider / Extensions
            subgraph "Provider & Extensions Packages"
                direction TB
                OpenAI["agents-openai"]:::provider
                OAITracingExp["openaiTracingExporter.ts"]:::provider
                Realtime["agents-realtime"]:::provider
                Extensions["agents-extensions"]:::provider
                Bundle["agents"]:::provider
            end
        end
        Examples["examples/"]:::docs
        DocsSite["docs/"]:::docs
        subgraph "CI/CD Pipelines"
            direction TB
            Workflows[".github/workflows/"]:::ci
        end
        subgraph "Testing & Build"
            direction TB
            VitestUnit["vitest.config.ts"]:::monorepo
            VitestInt["vitest.integration.config.ts"]:::monorepo
            Helpers["helpers/"]:::monorepo
            IntTests["integration-tests/"]:::monorepo
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAIAPI["OpenAI API"]:::external
        WebRTCServer["WebSocket/WebRTC Server"]:::external
        MCPServer["Local MCP Server"]:::external
        BrowserEnv["Browser Environment"]:::external
    end

    %% Relationships - Runtime Flow
    AgentCore -->|"invokes"| RunTS
    RunTS -->|"calls"| OpenAI
    RunImpl -->|"calls"| OpenAIAPI
    OpenAI -->|"chat.completions request"| OpenAIAPI
    RunTS -->|"executes"| ToolDef
    ToolDef -->|"tool.execute"| MCPServer
    RunTS -->|"emits events"| HandoffLogic
    HandoffLogic -->|"handoff"| MCPServer
    RunTS -->|"validates via"| Guardrail
    RunTS -->|"traces via"| TracingDir
    TracingDir -->|"span.export"| OpenAIAPI

    %% Realtime Flow
    BrowserEnv <-->|"audio/video stream"| Realtime
    Realtime -->|"adapter"| AgentCore

    %% Consumer Usage
    Developer -->|"imports"| Bundle
    Developer -->|"runs"| Examples
    Examples -->|"imports core & providers"| AgentCore
    Examples -->|"imports OpenAI adapter"| OpenAI
    Examples -->|"imports Realtime adapter"| Realtime

    %% Docs Site Flow
    DocsSite -->|"built with Astro/Tailwind"| DocsSite

    %% CI/CD & Testing
    Workflows -.->|"triggers"| VitestUnit
    Workflows -.->|"triggers"| VitestInt
    Workflows -.->|"deploy docs"| DocsSite
    Workflows -.->|"release tagging"| Bundle

    %% Click Events
    click AgentCore "https://github.com/openai/openai-agents-js/tree/main/packages/agents-core/"
    click RunTS "https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/run.ts"
    click RunImpl "https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/runImplementation.ts"
    click ToolDef "https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/tool.ts"
    click HandoffLogic "https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/handoff.ts"
    click HandoffExt "https://github.com/openai/openai-agents-js/tree/main/packages/agents-core/src/extensions/"
    click Guardrail "https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/guardrail.ts"
    click TracingDir "https://github.com/openai/openai-agents-js/tree/main/packages/agents-core/src/tracing/"
    click OpenAI "https://github.com/openai/openai-agents-js/tree/main/packages/agents-openai/"
    click OAITracingExp "https://github.com/openai/openai-agents-js/blob/main/packages/agents-openai/src/openaiTracingExporter.ts"
    click Realtime "https://github.com/openai/openai-agents-js/tree/main/packages/agents-realtime/"
    click Extensions "https://github.com/openai/openai-agents-js/tree/main/packages/agents-extensions/"
    click Bundle "https://github.com/openai/openai-agents-js/tree/main/packages/agents/"
    click PNPM "https://github.com/openai/openai-agents-js/blob/main/pnpm-workspace.yaml"
    click TSConfig "https://github.com/openai/openai-agents-js/blob/main/tsconfig.json"
    click RootPkg "https://github.com/openai/openai-agents-js/blob/main/package.json"
    click VitestUnit "https://github.com/openai/openai-agents-js/blob/main/vitest.config.ts"
    click VitestInt "https://github.com/openai/openai-agents-js/blob/main/vitest.integration.config.ts"
    click Helpers "https://github.com/openai/openai-agents-js/tree/main/helpers/"
    click IntTests "https://github.com/openai/openai-agents-js/tree/main/integration-tests/"
    click DocsSite "https://github.com/openai/openai-agents-js/tree/main/docs/"
    click Examples "https://github.com/openai/openai-agents-js/tree/main/examples/"
    click Workflows "https://github.com/openai/openai-agents-js/tree/main/.github/workflows/"

    %% Styling
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef provider fill:#d4edda,stroke:#155724,color:#155724
    classDef docs fill:#fff3cd,stroke:#856404,color:#856404
    classDef ci fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef monorepo fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef external fill:#e2e2e2,stroke:#666666,color:#333333
```
