OpenAI Agents SDK

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

const { Agent, run, tool } = require('@openai/agents');

// Realtime voice agents
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';

// Utilities
import {
  isZodObject,
  toSmartString,
  encodeUint8ArrayToBase64,
  applyDiff,
  EventEmitterDelegate
} from '@openai/agents/utils';

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

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

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

import { z } from 'zod';
import { Agent, run, tool } from '@openai/agents';

const getWeatherTool = tool({
  name: 'get_weather',
  description: 'Get the weather for a given city',
  parameters: z.object({ city: z.string() }),
  execute: async (input) => {
    return `The weather in ${input.city} is sunny`;
  },
});

const agent = new Agent({
  name: 'Weather Agent',
  instructions: 'You are a weather assistant',
  tools: [getWeatherTool],
});

const result = await run(agent, 'What is the weather in Tokyo?');
console.log(result.finalOutput);

class Agent<TContext = any, TOutput = any> {
  constructor(config: AgentConfiguration<TContext, TOutput>);
  static create<TOutput, Handoffs>(
    config: AgentConfiguration
  ): Agent<any, ResolvedAgentOutput<TOutput, Handoffs>>;
  clone(config: Partial<AgentConfiguration<TContext, TOutput>>): Agent<TContext, TOutput>;
  asTool(options?: AgentAsToolOptions): FunctionTool<TContext, Agent>;
}

interface AgentConfiguration<TContext = any, TOutput = any> {
  name: string;
  instructions?: string | ((runContext: RunContext<TContext>, agent: Agent) => string | Promise<string>);
  prompt?: Prompt | ((runContext: RunContext<TContext>, agent: Agent) => Prompt | Promise<Prompt>);
  handoffDescription?: string;
  handoffs?: (Agent | Handoff)[];
  model?: string | Model;
  modelSettings?: ModelSettings;
  tools?: Tool[];
  mcpServers?: MCPServer[];
  inputGuardrails?: InputGuardrail[];
  outputGuardrails?: OutputGuardrail<TOutput>[];
  outputType?: AgentOutputType<TOutput>;
  toolUseBehavior?: ToolUseBehavior;
  resetToolChoice?: boolean;
}

function run<TContext = any, TOutput = any>(
  agent: Agent<TContext, TOutput>,
  input: string | AgentInputItem[] | RunState,
  options?: RunOptions<TContext>
): Promise<RunResult<TOutput>> | StreamedRunResult<TOutput>;

class Runner<TContext = any> {
  constructor(config?: RunnerConfig<TContext>);
  run<TOutput = any>(
    agent: Agent<TContext, TOutput>,
    input: string | AgentInputItem[] | RunState,
    options?: RunOptions<TContext>
  ): Promise<RunResult<TOutput>> | StreamedRunResult<TOutput>;
}

interface RunResult<TOutput = any> {
  input: string | AgentInputItem[];
  output: AgentOutputItem[];
  history: AgentInputItem[];
  finalOutput?: ResolvedAgentOutput<TOutput>;
  lastAgent?: Agent;
  state: RunState;
}

interface StreamedRunResult<TOutput = any> extends RunResult<TOutput> {
  completed: Promise<void>;
  toStream(): ReadableStream<RunStreamEvent>;
  toTextStream(options?: TextStreamOptions): ReadableStream<string>;
  [Symbol.asyncIterator](): AsyncIterator<RunStreamEvent>;
}

function tool<TParameters, TContext, TResult>(config: ToolConfig<TParameters, TContext, TResult>): FunctionTool<TContext, TResult>;

interface ToolConfig<TParameters, TContext, TResult> {
  name?: string;
  description: string;
  parameters: TParameters;
  strict?: boolean;
  execute: (
    input: z.infer<TParameters>,
    context?: RunContext<TContext>,
    details?: ToolCallDetails
  ) => TResult | Promise<TResult>;
  errorFunction?: (context: RunContext<TContext>, error: any) => string;
  needsApproval?: boolean | ((runContext: RunContext<TContext>, input: any, callId?: string) => Promise<boolean>);
  isEnabled?: boolean | ((options: { runContext: RunContext<TContext>; agent: Agent }) => boolean | Promise<boolean>);
}

function computerTool(computer: Computer): ComputerTool;
function shellTool(shell: Shell): ShellTool;
function applyPatchTool(editor: Editor): ApplyPatchTool;
function hostedMcpTool(config: HostedMcpToolConfig): HostedTool;

// OpenAI-specific hosted tools
function webSearchTool(options?: WebSearchOptions): HostedTool;
function fileSearchTool(vectorStoreIds: string[], options?: FileSearchOptions): HostedTool;
function codeInterpreterTool(options?: CodeInterpreterOptions): HostedTool;
function imageGenerationTool(options?: ImageGenerationOptions): HostedTool;

function handoff<TContext, TOutput, TInputType>(
  agent: Agent<TContext, TOutput>,
  options?: HandoffOptions<TContext, TInputType>
): Handoff<TContext, TOutput>;

interface HandoffOptions<TContext, TInputType> {
  toolNameOverride?: string;
  toolDescriptionOverride?: string;
  onHandoff?: (context: RunContext<TContext>, input?: any) => void | Promise<void>;
  inputType?: TInputType;
  inputFilter?: (input: HandoffInputData) => HandoffInputData;
  isEnabled?: boolean | ((options: { runContext: RunContext<TContext>; agent: Agent }) => boolean | Promise<boolean>);
}

class Handoff<TContext = any, TOutput = any> {
  toolName: string;
  toolDescription: string;
  agent: Agent<TContext, TOutput>;
  onInvokeHandoff(
    context: RunContext<TContext>,
    args?: any
  ): Agent<TContext, TOutput> | Promise<Agent<TContext, TOutput>>;
}

interface InputGuardrail<TContext = any> {
  name: string;
  execute: (args: {
    agent: Agent;
    input: AgentInputItem[];
    context: RunContext<TContext>;
  }) => Promise<GuardrailFunctionOutput>;
  runInParallel?: boolean;
}

interface OutputGuardrail<TOutput = any, TContext = any> {
  name: string;
  execute: (args: {
    agent: Agent;
    agentOutput: TOutput;
    context: RunContext<TContext>;
    details?: { rawOutput: AgentOutputItem[] };
  }) => Promise<GuardrailFunctionOutput>;
}

interface GuardrailFunctionOutput {
  tripwireTriggered: boolean;
  outputInfo: any;
}

function defineOutputGuardrail<TOutput = any, TContext = any>(
  config: OutputGuardrailConfig<TOutput, TContext>
): OutputGuardrail<TOutput, TContext>;

class MCPServerStdio implements MCPServer {
  constructor(options: MCPServerStdioOptions);
}

class MCPServerStreamableHttp implements MCPServer {
  constructor(options: MCPServerHttpOptions);
}

class MCPServerSSE implements MCPServer {
  constructor(options: MCPServerSSEOptions);
}

interface MCPServer {
  name: string;
  connect(): Promise<void>;
  close(): Promise<void>;
  listTools(): Promise<MCPTool[]>;
  callTool(toolName: string, args: any): Promise<CallToolResultContent>;
  invalidateToolsCache(): Promise<void>;
}

interface Session {
  getSessionId(): Promise<string>;
  getItems(limit?: number): Promise<AgentInputItem[]>;
  addItems(items: AgentInputItem[]): Promise<void>;
  popItem(): Promise<AgentInputItem | undefined>;
  clearSession(): Promise<void>;
}

class MemorySession implements Session {
  constructor(options?: MemorySessionOptions);
}

class OpenAIConversationsSession implements Session {
  constructor(options?: OpenAIConversationsSessionOptions);
}

function startOpenAIConversationsSession(client?: OpenAI): Promise<string>;

class RealtimeAgent<TContext = any> {
  constructor(config: RealtimeAgentConfig<TContext>);
}

class RealtimeSession<TBaseContext = any> {
  constructor(
    initialAgent: RealtimeAgent<TBaseContext>,
    options: RealtimeSessionOptions<TBaseContext>
  );
  connect(options: RealtimeConnectOptions): Promise<void>;
  close(): void;
  updateAgent(newAgent: RealtimeAgent<TBaseContext>): Promise<RealtimeAgent<TBaseContext>>;
  sendMessage(message: string, otherEventData?: any): void;
  sendAudio(audio: ArrayBuffer | Uint8Array, options?: { commit?: boolean }): void;
}

class OpenAIRealtimeWebRTC implements RealtimeTransportLayer {
  constructor(options?: RealtimeWebRTCOptions);
}

class OpenAIRealtimeWebSocket implements RealtimeTransportLayer {
  constructor(options?: RealtimeWebSocketOptions);
}

class Trace {
  traceId: string;
  groupId?: string;
  metadata?: Record<string, any>;
}

class Span {
  spanId: string;
  name: string;
  startTime: number;
  endTime?: number;
}

function getCurrentTrace(): Trace | undefined;
function getCurrentSpan(): Span | undefined;
function getOrCreateTrace<T>(
  fn: (trace: Trace) => T | Promise<T>,
  options?: TraceOptions
): Promise<T>;

class OpenAITracingExporter {
  constructor(options?: OpenAITracingExporterOptions);
}

function setDefaultOpenAITracingExporter(): void;
function setTracingDisabled(disabled: boolean): void;

class OpenAIProvider implements ModelProvider {
  constructor(options?: OpenAIProviderOptions);
  getModel(modelName?: string): Model;
}

interface ModelProvider {
  getModel(modelName?: string): Promise<Model> | Model;
}

interface Model {
  getResponse(request: ModelRequest): Promise<ModelResponse>;
  getStreamedResponse(request: ModelRequest): AsyncIterable<StreamEvent>;
}

function setDefaultModelProvider(provider: ModelProvider): void;
function getDefaultModel(): string;
function setDefaultOpenAIClient(client: OpenAI): void;
function setDefaultOpenAIKey(apiKey: string): void;
function setOpenAIAPI(api: 'chat_completions' | 'responses'): void;

class AgentsError extends Error {
  readonly type: string;
}

class UserError extends AgentsError {}
class SystemError extends AgentsError {}
class ModelBehaviorError extends AgentsError {}
class MaxTurnsExceededError extends AgentsError {}
class ToolCallError extends AgentsError {}
class GuardrailExecutionError extends AgentsError {}
class InputGuardrailTripwireTriggered extends AgentsError {}
class OutputGuardrailTripwireTriggered extends AgentsError {}

class RunContext<TContext = any> {
  context: TContext;
  usage: Usage;
  isToolApproved(options: { toolName: string; callId: string }): boolean;
  approveTool(
    approvalItem: RunToolApprovalItem,
    options?: { alwaysApprove?: boolean }
  ): Promise<void>;
  rejectTool(
    approvalItem: RunToolApprovalItem,
    options?: { alwaysReject?: boolean }
  ): Promise<void>;
  toJSON(): any;
}

class Usage {
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  inputTokenDetails?: {
    audio?: number;
    text?: number;
    cached?: number;
  };
  outputTokenDetails?: {
    audio?: number;
    text?: number;
    reasoning?: number;
  };
  add(usage: Usage): void;
  toJSON(): object;
}

interface ModelSettings {
  temperature?: number;
  topP?: number;
  frequencyPenalty?: number;
  presencePenalty?: number;
  toolChoice?: 'auto' | 'required' | 'none' | string;
  parallelToolCalls?: boolean;
  truncation?: 'auto' | 'disabled';
  maxTokens?: number;
  store?: boolean;
  promptCacheRetention?: 'in-memory' | '24h' | null;
  reasoning?: {
    effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | null;
    summary?: 'auto' | 'concise' | 'detailed' | null;
  };
  text?: {
    verbosity?: 'low' | 'medium' | 'high' | null;
  };
  providerData?: Record<string, any>;
}

function user(
  input: string | UserContent[],
  options?: Record<string, any>
): UserMessageItem;

function assistant(
  content: string | AssistantContent[],
  options?: Record<string, any>
): AssistantMessageItem;

function system(
  input: string,
  options?: Record<string, any>
): SystemMessageItem;

class RunMessageOutputItem {
  agent: Agent;
  message: AssistantMessageItem;
}

class RunToolCallItem {
  agent: Agent;
  toolCall: FunctionCallItem | ComputerUseCallItem | ShellCallItem | ApplyPatchCallItem;
}

class RunToolCallOutputItem {
  agent: Agent;
  toolCallOutput: FunctionCallResultItem | ComputerCallResultItem | ShellCallResultItem | ApplyPatchCallResultItem;
}

class RunReasoningItem {
  agent: Agent;
  reasoning: ReasoningItem;
}

class RunHandoffCallItem {
  agent: Agent;
  handoffCall: FunctionCallItem;
}

class RunHandoffOutputItem {
  agent: Agent;
  handoffOutput: FunctionCallResultItem;
}

class RunToolApprovalItem {
  agent: Agent;
  toolCall: FunctionCallItem;
  approved: boolean | null;
}

function extractAllTextOutput(items: (AgentOutputItem | RunItem)[]): string;

/**
 * Check if a value is a Zod object schema
 * @param value - Value to check
 * @returns True if value is a Zod object schema
 */
function isZodObject(value: any): boolean;

/**
 * Convert various types to a smart string representation
 * @param value - Value to convert
 * @returns String representation
 */
function toSmartString(value: any): string;

/**
 * Encode Uint8Array to base64 string
 * @param data - Uint8Array to encode
 * @returns Base64 encoded string
 */
function encodeUint8ArrayToBase64(data: Uint8Array): string;

/**
 * Apply a unified diff patch to original text
 * @param original - Original text
 * @param diff - Unified diff string
 * @returns Patched text
 */
function applyDiff(original: string, diff: string): string;

/**
 * Base class for delegating event emitter functionality
 */
class EventEmitterDelegate<TEvents> {
  on<K extends keyof TEvents>(event: K, handler: (...args: TEvents[K]) => void): void;
  off<K extends keyof TEvents>(event: K, handler: (...args: TEvents[K]) => void): void;
  emit<K extends keyof TEvents>(event: K, ...args: TEvents[K]): void;
}

import { setDefaultOpenAIKey } from '@openai/agents';

setDefaultOpenAIKey('your-api-key');

export OPENAI_API_KEY='your-api-key'

import { setDefaultModelProvider, OpenAIProvider } from '@openai/agents';

setDefaultModelProvider(new OpenAIProvider({
  apiKey: 'your-api-key',
  baseURL: 'https://api.openai.com/v1',
}));