code

OpenAI Realtime Agent API - TypeScript Examples

Basic Setup

import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
import { tool } from "@openai/agents";
import { z } from "zod";

Creating an Agent

const agent = new RealtimeAgent({
  name: "AgentName",
  instructions: "Your agent instructions here",
  voice: "alloy", // or "echo", "fable", "onyx", "nova", "shimmer"
  tools: [/* array of tools */],
});

Creating a Session

Basic Session

const session = new RealtimeSession(agent, {
  model: "gpt-realtime-mini",
});

Session with Custom Audio Configuration

const session = new RealtimeSession(agent, {
  model: "gpt-realtime-mini",
  config: {
    audio: {
      input: {
        turnDetection: {
          type: "semantic_vad",
          eagerness: "low",
          create_response: false,
          interrupt_response: false,
        },
      },
    },
  },
});

Connecting to Session

// Connect with API key
await session.connect({ apiKey: "your-api-key" });

// Or with ephemeral token
await session.connect({ apiKey: ephemeralToken });

Sending Messages

// Send a text message
await session.sendMessage("Hello, agent!");

// Send a message after connection
session.connect({ apiKey: token })
  .then(() => session.sendMessage("Initial message"));

Interrupting Agent

session.interrupt();

Closing Session

session.close();

Defining Tools

const myTool = tool({
  name: "toolName",
  description: "What this tool does",
  parameters: z.object({
    param1: z.string().describe("Parameter description"),
    param2: z.number().optional(),
  }),
  execute: async ({ param1, param2 }) => {
    // Tool logic here
    return "Result string";
  },
});

Tool with Array Parameters

const arrayTool = tool({
  name: "arrayTool",
  description: "Tool with array parameter",
  parameters: z.object({
    items: z.array(z.string()),
  }),
  execute: async ({ items }) => {
    console.log(items);
    return "Processed";
  },
});

Tool with No Parameters

const noParamTool = tool({
  name: "noParamTool",
  description: "Tool without parameters",
  parameters: z.object({}),
  execute: async () => {
    // Logic here
    return "Result";
  },
});

This site is open source. Improve this page.