How openai/openai-agents-js works
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