OpenAI Agents JS

https://openai.github.io/openai-agents-js
Admin
The OpenAI Agents SDK for JavaScript and TypeScript allows developers to build and orchestrate AI...
Tokens:392,544
Snippets:3,657
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Create project and initialize npm

Source: https://openai.github.io/openai-agents-js/guides/quickstart

Initializes a new npm project in a directory named `my_project`. Run these commands once at the start of the quickstart.

```bash
mkdir my_project
cd my_project
npm init -y
```

--------------------------------

### Install @openai/agents-openai and openai packages

Source: https://openai.github.io/openai-agents-js/guides/models

Install the provider package and OpenAI client as direct dependencies because the example imports both packages directly.

```bash
npm install @openai/agents-openai openai
```

--------------------------------

### start()

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/trace

Starts the trace.

```APIDOC
## start()

### Description
Starts the trace.

### Method
```typescript
start(): Promise<void>;
```

### Returns
`Promise<void>`
```

--------------------------------

### Scaffold a new Vite project with vanilla-ts template

Source: https://openai.github.io/openai-agents-js/guides/voice-agents/quickstart

Use this command to create a new Vite project with the vanilla-ts template, which is a starting point for the voice agent quickstart.

```bash
npm create vite@latest my-project -- --template vanilla-ts
```

--------------------------------

### Install a model package from Vercel AI SDK

Source: https://openai.github.io/openai-agents-js/extensions/ai-sdk

Install the desired model package, for example @ai-sdk/openai, to use with the adapter.

```bash
npm install @ai-sdk/openai

```

--------------------------------

### once() with prependOnceListener example

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/realtimesession

Example showing the order of listeners when using once() and prependOnceListener() together.

```javascript
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

--------------------------------

### start(): void

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/span

Starts the span.

```APIDOC
## Method: start()

### Description
Starts the span.

### Signature
```typescript
start(): void;
```

### Returns
`void`
```

--------------------------------

### on() usage example

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/realtimesession

Example showing how to use the on() method to listen for the 'connection' event on a server.

```javascript
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

--------------------------------

### start()

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/batchtraceprocessor

Called when the trace processor should start processing traces. Only available if the processor is performing tasks like exporting traces in a loop to start the loop.

```APIDOC
## Method: start()

### Description
Called when the trace processor should start processing traces. Only available if the processor is performing tasks like exporting traces in a loop to start the loop.

### Returns
`void`
```

--------------------------------

### Install the extensions package

Source: https://openai.github.io/openai-agents-js/extensions/cloudflare

Install the @openai/agents-extensions package using npm.

```bash
npm install @openai/agents-extensions
```

--------------------------------

### Install the AI SDK adapter package

Source: https://openai.github.io/openai-agents-js/extensions/ai-sdk

Install the @openai/agents-extensions package, which includes the AI SDK adapter.

```bash
npm install @openai/agents-extensions

```

--------------------------------

### once() usage example

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/realtimesession

Example of using once() to listen for a 'connection' event and log a message.

```javascript
server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});
```

--------------------------------

### Install the OpenAI Agents SDK

Source: https://openai.github.io/openai-agents-js/guides/sandbox-agents

Install the SDK using npm. Requires Node.js 22 or higher. For Docker-backed sandboxes, also install Docker locally and use DockerSandboxClient from @openai/agents/sandbox/local.

```bash
npm install @openai/agents
```

--------------------------------

### clone() example with new instructions

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/agent

Example usage of clone() to change the agent's instructions.

```typescript
const newAgent = agent.clone({ instructions: 'New instructions' })

```

--------------------------------

### on() with prependListener example

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/realtimesession

Example demonstrating the order of event listener invocation and the use of prependListener() to add a listener to the beginning of the array.

```javascript
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

--------------------------------

### get startedAt(): string | null

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/span

Returns the timestamp when the span started, or null if not started.

```APIDOC
## Accessor: startedAt

### Description
Returns the timestamp when the span started, or null if not started.

### Get Signature
```typescript
get startedAt(): string | null;
```

### Returns
`string` | `null`
```

--------------------------------

### Complete example: create and run an agent with a custom model

Source: https://openai.github.io/openai-agents-js/extensions/ai-sdk

Full example showing how to import the necessary packages, create a model instance with the adapter, define an agent with that model, and run it.

```typescript
import { Agent, run } from '@openai/agents';


// Import the model package you installed
import { openai } from '@ai-sdk/openai';


// Import the adapter
import { aisdk } from '@openai/agents-extensions/ai-sdk';


// Create a model instance to be used by the agent
const model = aisdk(openai('gpt-5.4'));


// Create an agent with the model
const agent = new Agent({
  name: 'My Agent',
  instructions: 'You are a helpful assistant.',
  model,
});


// Run the agent with the new model
run(agent, 'What is the capital of Germany?');

```

--------------------------------

### get interruptions(): RunToolApprovalItem[]

Source: https://openai.github.io/openai-agents-js/openai/agents-core/classes/runresult

Returns any interruptions that occurred during the agent run, for example for tool approvals.

```APIDOC
## Accessor: interruptions

### Get Signature
```
get interruptions(): RunToolApprovalItem[];
```

### Description
Any interruptions that occurred during the agent run for example for tool approvals.

### Returns
- `RunToolApprovalItem[]`

### Inherited from
- `RunResultBase.interruptions`
```

--------------------------------

### Start the development server

Source: https://openai.github.io/openai-agents-js/guides/voice-agents/quickstart

Runs the development server to launch the web app containing the voice agent code. After starting, the browser will request microphone permission.

```bash
npm run dev
```

--------------------------------

### Lifecycle hooks with agent.on()

Source: https://openai.github.io/openai-agents-js/guides/agents

Observe the agent lifecycle by listening on events emitted by the Agent instance. The example listens for 'agent_start' and 'agent_end' events, logging when the agent starts and its output. Runner emits the same event names as a single stream across the whole run.

```typescript
import { Agent } from '@openai/agents';


const agent = new Agent({
  name: 'Verbose agent',
  instructions: 'Explain things thoroughly.',
});


agent.on('agent_start', (ctx, agent) => {
  console.log(`[${agent.name}] started`);
});
agent.on('agent_end', (ctx, output) => {
  console.log(`[agent] produced:`, output);
});
```

--------------------------------

### Configure memory generation with memory({ generate: ... })

Source: https://openai.github.io/openai-agents-js/guides/sandbox-agents/memory

Configures memory generation with a two-phase model setup. It sets limits for raw memories, assigns separate models for each phase, and includes an extra prompt to guide memory generation toward relevant signals.

```javascript
import { memory } from '@openai/agents/sandbox';


const memoryCapability = memory({
  generate: {
    maxRawMemoriesForConsolidation: 128,
    phaseOneModel: 'gpt-5.4-mini',
    phaseTwoModel: 'gpt-5.4',
    extraPrompt:
      'Prioritize workflow corrections, verification commands, and user preferences.',
  },
});

```

--------------------------------

### instructions

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/agent

The instructions for the agent. Will be used as the 'system prompt' when this agent is invoked. Describes what the agent should do, and how it responds. Can either be a string, or a function that dynamically generates instructions for the agent.

```APIDOC
## instructions

### Description
The instructions for the agent. Will be used as the 'system prompt' when this agent is invoked. Describes what the agent should do, and how it responds.
Can either be a string, or a function that dynamically generates instructions for the agent. If you provide a function, it will be called with the context and the agent instance. It must return a string.

### Type
`string | ((runContext, agent) => string | Promise<string>)`

### Implementation of
`AgentConfiguration.instructions`
```

--------------------------------

### Use a Standard Schema library with Valibot

Source: https://openai.github.io/openai-agents-js/guides/schemas

Install `valibot` and `@valibot/to-json-schema` in an application that already uses `@openai/agents`. The example defines a tool, an agent, an agent tool, and a handoff, all using Standard Schema converted to JSON Schema. The SDK validates tool calls locally, applies defaults, and passes inferred types to `execute`, `inputBuilder`, `onHandoff`, and `result.finalOutput`.

```typescript
import { Agent, handoff, tool } from '@openai/agents';
import { toStandardJsonSchema } from '@valibot/to-json-schema';
import * as v from 'valibot';


const LookupOrderParameters = toStandardJsonSchema(
  v.object({
    orderId: v.pipe(v.string(), v.minLength(1)),
    includeHistory: v.optional(v.boolean(), false),
  }),
);


const lookupOrder = tool({
  name: 'lookup_order',
  description: 'Look up an order by ID.',
  parameters: LookupOrderParameters,
  // The argument type is inferred after Valibot validation and defaults run.
  execute: async ({ orderId, includeHistory }) => ({
    orderId,
    status: 'shipped',
    history: includeHistory ? ['placed', 'shipped'] : undefined,
  }),
});


const Resolution = toStandardJsonSchema(
  v.object({
    orderId: v.string(),
    message: v.string(),
  }),
);


const supportAgent = new Agent({
  name: 'Order support',
  instructions: 'Resolve order questions and return a structured summary.',
  tools: [lookupOrder],
  // The final output is converted to JSON Schema, then validated by Valibot.
  outputType: Resolution,
});


const supportAgentTool = supportAgent.asTool({
  toolName: 'resolve_order',
  toolDescription: 'Resolve an order question with the support specialist.',
  parameters: LookupOrderParameters,
  // inputBuilder receives the same validated and inferred parameter type.
  inputBuilder: ({ params }) =>
    `Resolve order ${params.orderId}. Include history: ${params.includeHistory}.`,
});


const EscalationDetails = toStandardJsonSchema(
  v.object({
    reason: v.pipe(v.string(), v.minLength(1)),
    priority: v.optional(v.picklist(['normal', 'urgent']), 'normal'),
  }),
);


const billingAgent = new Agent({
  name: 'Billing specialist',
  instructions: 'Resolve billing questions.',
});


const billingHandoff = handoff(billingAgent, {
  inputType: EscalationDetails,
  // The callback receives the validated value, including Valibot defaults.
  onHandoff: async (_context, details) => {
    if (details) {
      await recordEscalation(details.reason, details.priority);
    }
  },
});


async function recordEscalation(_reason: string, _priority: string) {}


export { billingHandoff, supportAgent, supportAgentTool };
```

--------------------------------

### Complete RealtimeAgent setup and connection

Source: https://openai.github.io/openai-agents-js/guides/voice-agents/quickstart

Sets up a RealtimeAgent with instructions and a RealtimeSession using the gpt-realtime-2.1 model. Connects via WebRTC with an ephemeral API key (ek_...) and logs success or error. The comment shows the curl command to obtain the ephemeral key.

```javascript
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';


async function main() {
  const agent = new RealtimeAgent({
    name: 'Assistant',
    instructions: 'You are a helpful assistant.',
  });
  const session = new RealtimeSession(agent, {
    model: 'gpt-realtime-2.1',
  });
  // Automatically connects your microphone and audio output in the browser via WebRTC.
  try {
    await session.connect({
      // To get this ephemeral key string, you can run the following command or implement the equivalent on the server side:
      // curl -s -X POST https://api.openai.com/v1/realtime/client_secrets -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"session": {"type": "realtime", "model": "gpt-realtime-2.1"}}' | jq .value
      apiKey: 'ek_...(put your own key here)',
    });
    console.log('You are connected!');
  } catch (e) {
    console.error(e);
  }
}


main().catch(console.error);
```

--------------------------------

### connect()

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/mcpserverstreamablehttp

Establishes a connection to the server.

```APIDOC
## connect()

### Description
Establishes a connection to the server.

### Method
connect

### Signature
```
connect(): Promise<void>;
```

### Returns
`Promise<void>`
```

--------------------------------

### Session configuration with model and config options

Source: https://openai.github.io/openai-agents-js/guides/voice-agents/build

Shows how to configure a RealtimeSession at creation time using the model option and config object. The example sets output modalities, reasoning effort, parallel tool calls, and audio input/output formats with transcription settings.

```typescript
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';


const agent = new RealtimeAgent({
  name: 'Greeter',
  instructions: 'Greet the user with cheer and answer questions.',
});


const session = new RealtimeSession(agent, {
  model: 'gpt-realtime-2.1',
  config: {
    outputModalities: ['audio'],
    reasoning: {
      effort: 'low',
    },
    parallelToolCalls: true,
    audio: {
      input: {
        format: 'pcm16',
        transcription: {
          model: 'gpt-live-transcribe',
          delay: 'low',
          prompt:
            'A software support conversation about the OpenAI Agents SDK.',
          keywords: ['OpenAI Agents SDK', 'RealtimeSession'],
          languages: ['en', 'ja'],
        },
      },
      output: {
        format: 'pcm16',
      },
    },
  },
});
```

--------------------------------

### captureStackTrace example

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/agentserror

Example usage of Error.captureStackTrace.

```javascript
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

--------------------------------

### MCPServers.open()

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/mcpservers

Static method to create an MCPServers instance with a list of servers and optional options.

```APIDOC
## MCPServers.open()

### Description
Creates a new MCPServers instance with the given servers and options.

### Method
static open

### Signature
```typescript
static open(servers: MCPServer[], options?: MCPServersOptions): Promise<MCPServers>;
```

### Parameters
- **servers** (MCPServer[]) - Required - The list of MCP servers to manage.
- **options** (MCPServersOptions) - Optional - Configuration options for the MCPServers instance.

### Returns
`Promise<MCPServers>`
```

--------------------------------

### get muted()

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/openairealtimewebrtc

Gets whether the session is muted.

```APIDOC
## Accessor: muted (get)

### get muted(): boolean

Gets whether the session is muted.

#### Returns
- `boolean` - Whether the input audio track is currently muted. Returns null if muting is not handled by the transport layer.

#### Implementation of
- `RealtimeTransportLayer.muted`

#### Overrides
- `OpenAIRealtimeBase.muted`
```

--------------------------------

### MCPServerStdio Constructor

Source: https://openai.github.io/openai-agents-js/guides/mcp

Instantiate a stdio MCP server with a full command string, connect it, and use it with an agent. The example demonstrates reading files from a local directory.

```APIDOC
## MCPServerStdio Constructor

### Description
Creates a new stdio MCP server instance that can be connected to an agent. The server runs a command that communicates over standard I/O.

### Constructor
`new MCPServerStdio(options)`

### Parameters
#### Options
- **name** (string) - Optional label for the server.
- **command** (string) - Command for stdio servers.
- **args** (string[]) - Arguments for the command.
- **fullCommand** (string) - Full command string alternative to `command` + `args`.
- **env** (Record<string, string>) - Environment variables for the server process.
- **cwd** (string) - Working directory for the server process.
- **cacheToolsList** (boolean) - Cache tools list to reduce latency.
- **clientSessionTimeoutSeconds** (number) - Timeout for MCP client sessions.
- **encoding** (string) - Encoding for stdio streams.
- **encodingErrorHandler** ('strict' | 'ignore' | 'replace') - Encoding error strategy.
- **toolFilter** (MCPToolFilterCallable | MCPToolFilterStatic) - Filter available tools.
- **toolMetaResolver** (MCPToolMetaResolver) - Inject per-call MCP `_meta` request fields.
- **toolInputGuardrails** (ToolInputGuardrailDefinition[]) - Run these guardrails before every tool call converted from this server.
- **toolOutputGuardrails** (ToolOutputGuardrailDefinition[]) - Run these guardrails after every tool call converted from this server.
- **useStructuredContent** (boolean) - Use JSON-serialized MCP `structuredContent` as the model-visible output when available and the result is not an error. Defaults to `false`.
- **customDataExtractor** (MCPToolCustomDataExtractor) - Attach SDK-only JSON metadata to emitted local MCP tool output items.
- **errorFunction** (MCPToolErrorFunction | null) - Map MCP call failures to model-visible text.
- **timeout** (number) - Per-request timeout (milliseconds).
- **logger** (Logger) - Custom logger.

### Example
```typescript
import { Agent, run, MCPServerStdio } from '@openai/agents';
import * as path from 'node:path';

async function main() {
  const samplesDir = path.join(__dirname, 'sample_files');
  const mcpServer = new MCPServerStdio({
    name: 'Filesystem MCP Server, via local package',
    fullCommand: `pnpm exec mcp-server-filesystem ${samplesDir}`,
  });
  await mcpServer.connect();
  try {
    const agent = new Agent({
      name: 'FS MCP Assistant',
      instructions: 'Use the tools to read the filesystem and answer questions based on those files. If you are unable to find any files, you can say so instead of assuming they exist.',
      mcpServers: [mcpServer],
    });
    const result = await run(agent, 'Read the files and list them.');
    console.log(result.finalOutput);
  } finally {
    await mcpServer.close();
  }
}

main().catch(console.error);
```
```

--------------------------------

### get status()

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/openairealtimesip

Gets the current status of the WebSocket connection.

```APIDOC
## Accessor: status (get)

### get status(): "connecting" | "connected" | "disconnected"

Returns the current status of the WebSocket connection.

#### Returns
- `"connecting"` | `"connected"` | `"disconnected"` - The current status.

#### Inherited from
- `OpenAIRealtimeWebSocket.status`
```

--------------------------------

### Using RECOMMENDED_PROMPT_PREFIX in agent instructions

Source: https://openai.github.io/openai-agents-js/guides/handoffs

Imports Agent from '@openai/agents' and RECOMMENDED_PROMPT_PREFIX from '@openai/agents-core/extensions'. Creates a billing agent with instructions that include the recommended prompt prefix to improve LLM reliability when handoffs are mentioned.

```typescript
import { Agent } from '@openai/agents';
import { RECOMMENDED_PROMPT_PREFIX } from '@openai/agents-core/extensions';


const billingAgent = new Agent({
  name: 'Billing agent',
  instructions: `${RECOMMENDED_PROMPT_PREFIX}
Fill in the rest of your prompt here.`,
});

```

--------------------------------

### get status()

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/openairealtimewebrtc

Gets the current status of the WebRTC connection.

```APIDOC
## Accessor: status (get)

### get status(): "connecting" | "connected" | "disconnected"

Gets the current status of the WebRTC connection.

#### Returns
- `"connecting" | "connected" | "disconnected"` - The current connection status.

#### Implementation of
- `RealtimeTransportLayer.status`

#### Overrides
- `OpenAIRealtimeBase.status`
```

--------------------------------

### get currentModel()

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/openairealtimesip

Gets the current model being used by the transport layer.

```APIDOC
## Accessor: currentModel (get)

### get currentModel(): OpenAIRealtimeModels

Returns the current model being used by the transport layer.

#### Returns
- `OpenAIRealtimeModels` - The current model.

#### Inherited from
- `OpenAIRealtimeWebSocket.currentModel`
```

--------------------------------

### get connectionState()

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/openairealtimesip

Gets the current connection state of the WebSocket connection.

```APIDOC
## Accessor: connectionState (get)

### get connectionState(): WebSocketState

Returns the current connection state of the WebSocket connection.

#### Returns
- `WebSocketState` - The current connection state.

#### Inherited from
- `OpenAIRealtimeWebSocket.connectionState`
```

--------------------------------

### get callId()

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/openairealtimewebrtc

Gets the current call ID of the WebRTC connection.

```APIDOC
## Accessor: callId (get)

### get callId(): string | undefined

Gets the current call ID of the WebRTC connection.

#### Returns
- `string | undefined` - The current call ID, or undefined if not set.
```

--------------------------------

### Create a RealtimeAgent and RealtimeSession

Source: https://openai.github.io/openai-agents-js/openai/agents/openai/namespaces/realtime/classes/realtimeagent

Shows how to instantiate a RealtimeAgent with a name and instructions, then create a RealtimeSession with that agent.

```typescript
const agent = new RealtimeAgent({
  name: 'my-agent',
  instructions: 'You are a helpful assistant that can answer questions and help with tasks.',
})


const session = new RealtimeSession(agent);
```

--------------------------------

### Create a defaultManifest with file, gitRepo, and environment

Source: https://openai.github.io/openai-agents-js/guides/sandbox-agents/concepts

Shows how to construct a Manifest instance for defaultManifest, including a file entry, a git repo entry, and environment variables. Pass either a Manifest instance or the same init object you would pass to new Manifest(...).

```typescript
import { file, gitRepo, Manifest } from '@openai/agents/sandbox';


const manifest = new Manifest({
  root: '/workspace',
  entries: {
    'task.md': file({
      content: 'Fix the failing test and summarize the change.',
    }),
    repo: gitRepo({
      repo: 'openai/openai-agents-js',
      ref: 'main',
    }),
  },
  environment: {
    NODE_ENV: 'test',
  },
});
```

--------------------------------

### dispatchSpanStart()

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/traceprovider

Dispatches a span start event to all registered processors. Useful when an integration receives a span start outside this process and needs to fan out the start without mutating the span state.

```APIDOC
## dispatchSpanStart()

### Description
Dispatches a span start event to all registered processors. This is useful when an integration receives a span start outside this process and needs to fan out the start without mutating the span state.

### Method
`dispatchSpanStart<TSpanData>(span): Promise<void>`

### Type Parameters
- **TSpanData** extends `SpanData`

### Parameters
- **span** (Span<TSpanData>) - Required - The span whose start event is dispatched.

### Returns
`Promise<void>`
```

--------------------------------

### Set up local tools agent with computer, shell, and apply patch tools

Source: https://openai.github.io/openai-agents-js/guides/tools

Imports the necessary classes and functions from '@openai/agents', defines local implementations of the Computer, Shell, and Editor interfaces, and creates an Agent with computerTool, shellTool, and applyPatchTool. The shell and apply patch tools are configured with needsApproval: true.

```typescript
import {
  Agent,
  applyPatchTool,
  computerTool,
  shellTool,
  Computer,
  Editor,
  Shell,
} from '@openai/agents';


const computer: Computer = {
  environment: 'browser',
  dimensions: [1024, 768],
  screenshot: async () => '',
  click: async () => {},
  doubleClick: async () => {},
  scroll: async () => {},
  type: async () => {},
  wait: async () => {},
  move: async () => {},
  keypress: async () => {},
  drag: async () => {},
};


const shell: Shell = {
  run: async () => ({
    output: [
      {
        stdout: '',
        stderr: '',
        outcome: { type: 'exit', exitCode: 0 },
      },
    ],
  }),
};


const editor: Editor = {
  createFile: async () => ({ status: 'completed' }),
  updateFile: async () => ({ status: 'completed' }),
  deleteFile: async () => ({ status: 'completed' }),
};


const agent = new Agent({
  name: 'Local tools agent',
  model: 'gpt-5.4',
  tools: [
    computerTool({ computer }),
    shellTool({ shell, needsApproval: true }),
    applyPatchTool({ editor, needsApproval: true }),
  ],
});
```

--------------------------------

### onTraceStart(trace)

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/batchtraceprocessor

Called when a trace is started. Processes the trace start event.

```APIDOC
## Method: onTraceStart(trace)

### Description
Called when a trace is started.

### Parameters
- **trace** (`Trace`) - Required - The trace that started.

### Returns
`Promise<void>`
```

--------------------------------

### onSpanStart(_span)

Source: https://openai.github.io/openai-agents-js/openai/agents/classes/batchtraceprocessor

Called when a span is started. Processes the span start event.

```APIDOC
## Method: onSpanStart(_span)

### Description
Called when a span is started.

### Parameters
- **_span** (`Span`) - Required - The span that started.

### Returns
`Promise<void>`
```

--------------------------------

### Create and connect a RealtimeSession

Source: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/realtimesession

Shows how to instantiate a RealtimeAgent and a RealtimeSession, then connect with an API key. The session automatically uses WebRTC in browsers or WebSockets on the server.

```javascript
const agent = new RealtimeAgent({
  name: 'my-agent',
  instructions: 'You are a helpful assistant that can answer questions and help with tasks.',
})


const session = new RealtimeSession(agent);
session.connect({
  apiKey: 'your-api-key',
});
```

--------------------------------

### Text Agent Hello World

Source: https://openai.github.io/openai-agents-js

Create a basic text agent using the Agent class and run it with a prompt. The example prints the final output, which is a haiku about recursion.

```javascript
import { Agent, run } from '@openai/agents';


const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant',
});


const result = await run(
  agent,
  'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);


// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.
```

--------------------------------

### status (abstract get)

Source: https://openai.github.io/openai-agents-js/openai/agents-realtime/classes/openairealtimebase

Gets the current status of the transport layer connection.

```APIDOC
## Accessor: status (get)

### Description
Gets the current status of the transport layer connection.

### Get Signature
```typescript
get abstract status(): "connecting" | "connected" | "disconnected" | "disconnecting";
```

### Returns
`"connecting"` | `"connected"` | `"disconnected"` | `"disconnecting"` - The current connection status.

### Implementation of
`RealtimeTransportLayer`.`status`
```

--------------------------------

### onTraceStart()

Source: https://openai.github.io/openai-agents-js/openai/agents-core/interfaces/tracingprocessor

Called when a trace is started. This method should be implemented to handle trace start events.

```APIDOC
## onTraceStart(trace)

### Description
Called when a trace is started.

### Method
onTraceStart

### Signature
`onTraceStart(trace): Promise<void>;`

### Parameters
- **trace** (`Trace`) - Required - The trace that started.

### Returns
`Promise<void>`
```

--------------------------------

### Create your first agent

Source: https://openai.github.io/openai-agents-js/guides/quickstart

Defines an agent named 'History Tutor' with instructions for handling historical queries. This is the minimal setup for an agent.

```javascript
import { Agent } from '@openai/agents';


const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});
```
Tokens:
Raw