DOCSEARCHbyAlgolia
Submit Docs

OpenAI Agents SDK

repository·main·Indexed 25 days ago

https://github.com/openai/openai-agents-js

A lightweight, provider-agnostic framework for building multi-agent workflows in JavaScript/TypeScript. It supports text-based agents, sandbox agents for filesystem/command execution, and low-latency realtime voice agents. The SDK includes capabilities for agent orchestration (Agents-as-Tools, routing, and handoffs), human-in-the-loop patterns, guardrails, and integration with the AI SDK via the @openai/agents-extensions package.

Tokens
57.9K
Snippets
93
Records
404
Agent score
86%

What's inside openai-agents-js

  1. Overview of Agent Tool Categories

    main

    Tools allow an Agent to take actions such as fetching data, calling external APIs, executing code, or using a computer. The OpenAI Agents SDK supports seven distinct categories of tools:

    1. Hosted OpenAI tools: Tools that run on OpenAI servers alongside the model (e.g., web search, file search, code interpreter, image generation, tool search).
    2. Built-in execution tools: SDK-provided tools that execute outside the model (e.g., computer use and apply_patch run locally; shell can run locally or in hosted containers).
    3. Function tools: Local functions wrapped in a JSON schema for LLM invocation.
    4. Agents as tools: Exposing an entire Agent as a callable tool.
    5. MCP servers: Attaching a Model Context Protocol server (local or remote).
    6. Sandbox capabilities: Attaching workspace-scoped tools (shell, filesystem, skills, memory, or compaction) to a SandboxAgent.
    7. Experimental: Codex tool: Wrapping the Codex SDK as a function tool for workspace-aware tasks.

  2. Understand the Agent Loop lifecycle

    main

    When the run method is called, the Runner executes a loop with the following logic:

    1. Model Call: Calls the current agent's model with the current input.
    2. Response Inspection:
      • Final output: If the LLM produces text of the desired type and no tool calls, the loop returns the result.
      • Handoff: If a handoff occurs, the runner switches to the new agent, maintains the conversation history, and restarts the loop.
      • Tool calls: If tools are called, the runner executes them, appends the results to the conversation, and restarts the loop.
    3. Safety Limit: If the number of turns reaches maxTurns (default is 10), the runner throws a MaxTurnsExceededError (unless maxTurns is set to null).

  3. Understand Model and ModelProvider interfaces

    main

    The SDK abstracts language models using two primary interfaces:

    • Model: Handles a single request against a specific API.
    • ModelProvider: Resolves human-readable model names (e.g., 'gpt-5.6-sol') into Model instances.

    Most development tasks involve interacting with model names and ModelSettings rather than implementing these interfaces directly.

  4. Understand Sandbox Agent concepts

    main

    Sandbox Agents are specialized agents designed for workspace-centric workflows that require filesystem access, shell commands, or file manipulation. Unlike standard Agent instances, SandboxAgent provides a persistent workspace where the agent can operate on real files (e.g., GitHub repos, local directories, S3 buckets).

    Core Architecture Layers

    1. Agent Definition: Uses SandboxAgent, Manifest, and capabilities to define what the agent does and what a fresh workspace looks like.
    2. Sandbox Execution: Uses the sandbox run option and a sandbox client to determine how the agent gets a live execution environment (a "sandbox session").
    3. Saved Sandbox State: Uses RunState, sessionState, or snapshots to reconnect to prior work or seed new sessions.

    Key Components

    ComponentResponsibility
    SandboxAgentDefines the agent and its sandbox-specific defaults (e.g., defaultManifest, baseInstructions, capabilities).
    ManifestDeclares the starting files, folders, repos, and environment for a fresh workspace.
    CapabilityAttaches sandbox-native behaviors, tools, or instruction fragments to the agent.
    sandbox run optionConfigures the per-run sandbox client and determines if the run should inject, resume, or create a new session.
    RunStateRunner-managed payload used to automatically carry sandbox state forward when resuming a workflow.
    sandbox.sessionStateExplicitly serialized sandbox session state for manual resumption.
    sandbox.snapshotSaved workspace contents used to seed a fresh sandbox session.

    Note: Sandbox agents are currently in Beta. API details and supported capabilities may change.

  5. Build realtime voice assistants with the Voice Agents SDK

    main

    The Voice Agents SDK allows you to build low-latency spoken interfaces using OpenAI speech-to-speech models. It provides a TypeScript-first layer over the official Realtime API, wrapping raw event flows into higher-level abstractions like RealtimeAgent and RealtimeSession.

    Key features provided by the SDK include:

    • Browser-first WebRTC setup using ephemeral client tokens.
    • Server-side transport options including WebSocket and SIP.
    • Automatic interruption handling and local conversation history updates.
    • Multi-agent orchestration via realtime handoffs.
    • Support for function tools, hosted MCP tools, approvals, and delegation patterns.
    • Output guardrails and tracing for live spoken interactions.

  6. Core concepts of the OpenAI Agents SDK

    main

    The SDK is built on a small set of primitives:

    • Agents: LLMs equipped with instructions and tools.
    • Sandbox agents: Agents paired with isolated filesystem workspaces, shell commands, file editing, snapshots, and sandbox session state.
    • Agents as tools / Handoffs: A mechanism to allow agents to delegate tasks to other agents.
    • Guardrails: Tools to enable validation of agent inputs.

    Key features include a built-in agent loop for tool invocation, Function tools with automatic schema generation via Zod, MCP server tool calling, Sessions for persistent memory, and built-in Tracing for debugging and evaluation.

  7. Understand the Research Bot architecture

    main

    The Research Bot is composed of three main components that manage the research lifecycle:

    • main.ts: The CLI entrypoint. It accepts a user query and initiates the workflow via the ResearchManager.
    • manager.ts: The orchestration layer. It uses ResearchManager to coordinate the planning, web searching, and report writing stages.
    • agents.ts: The agent definitions. It contains three specialized agents:
      • Planner: Suggests search terms based on the query.
      • Search Agent: Summarizes web search results.
      • Writer: Generates the final research report.

  8. Use sandbox agents as tools

    main

    When exposing a sandbox agent as a tool using sandboxAgent.asTool(...), you have two primary strategies:

    1. Reuse parent sandbox: The tool-agent inspects the exact workspace the parent is using. This is fast and avoids the overhead of creating/hydrating a new sandbox.
    2. Isolated sandbox: Provide a unique runConfig via asTool(...). This gives the tool-agent its own sandbox boundary, which is necessary if the tool needs to mutate files freely, run untrusted commands, or use a different backend/image.

  9. Orchestrate agents via code

    main

    For more deterministic, predictable, and cost-effective workflows, you can orchestrate agent flows using standard programming logic instead of relying solely on LLM reasoning. Common patterns include:

    • Structured Outputs: Use structured outputs to generate well-formed data, then use your code to inspect that data and select the next agent (e.g., classifying a task category to pick a specific specialist).
    • Agent Chaining: Transform the output of one agent into the input of the next to decompose complex tasks (e.g., Research Agent $\rightarrow$ Outline Agent $\rightarrow$ Writer Agent $\rightarrow$ Critique Agent).
    • Evaluation Loops: Run a task agent in a while loop alongside an evaluator agent. The loop continues until the evaluator agent confirms the output meets specific criteria.
    • Parallel Execution: Use JavaScript primitives like Promise.all to run multiple agents in parallel when tasks are independent, improving speed.

  10. Workflow for the Credit Note Fixer skill

    main

    The credit-note-fixer skill follows a specific sequence to resolve formatting bugs in credit notes:

    1. Analyze Task: Read repo/task.md to understand the requirements.
    2. Inspect Files: Examine repo/credit_note.sh and repo/tests/test_credit_note.sh.
    3. Apply Fix: Make the minimal change necessary to ensure the output label remains credit and the amount is positive.
      • Note: If using the apply_patch tool, you must use workspace-root-relative paths (e.g., repo/credit_note.sh and repo/tests/test_credit_note.sh).
    4. Verify: Execute the command sh tests/test_credit_note.sh from within the repo/ directory.
    5. Report: Provide a final summary including the bug description, the applied fix, and the exact verification command used.

  11. Configure Modal Sandbox Extension

    main

    The Modal sandbox extension requires OPENAI_API_KEY. Authentication for Modal can be handled via a local config file (e.g., ~/.modal.toml created via modal setup) or through environment variables.

    Required Environment Variables:

    • OPENAI_API_KEY

    Optional Environment Variables:

    • MODAL_TOKEN_ID
    • MODAL_TOKEN_SECRET
    • MODAL_CONFIG_PATH (to override the default config path)

    Run Command:

    pnpm -F sandbox start:modal -- --stream
    export OPENAI_API_KEY=...
pnpm -F sandbox start:modal -- --stream

  12. Manage server-side conversations with `conversationId` or `previousResponseId`

    main

    If you are using the OpenAI Responses API, you can let the server manage conversation history. This allows you to pass only the new turn's input on each request instead of the full history.

    1. conversationId: Use this for an entire conversation. Create a conversation once using the Conversations API and reuse its ID for every turn. The SDK automatically includes only the newly generated items.
    2. previousResponseId: Use this to chain requests from one response to the next. This is the simplest continuation primitive and does not create a full conversation resource. Use result.lastResponseId from the previous run as the input for the next.

    conversationId and previousResponseId are mutually exclusive.