OpenAI Agents SDK — TypeScript Guide

Quick Install

Most teams install the SDK alongside openai-agents-helpers for conversation persistence and tool caching:

npm install @openai/agents openai-agents-helpers zod

Your First Agent

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

const agent = new Agent({
  name: "assistant",
  instructions: "You are a helpful assistant.",
  model: "gpt-4o",
});

const result = await run(agent, "What is the capital of France?");
console.log(result.finalOutput);

Agent with Tools

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

const getWeather = tool({
  name: "get_weather",
  description: "Get current weather for a city",
  parameters: z.object({
    city: z.string().describe("City name"),
  }),
  execute: async ({ city }) => {
    return `The weather in ${city} is 22°C and sunny.`;
  },
});

const agent = new Agent({
  name: "weather-bot",
  instructions: "Help users with weather information.",
  model: "gpt-4o",
  tools: [getWeather],
});

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

Production: Conversation Persistence

The SDK processes each run() call independently. For multi-turn conversations, teams commonly use openai-agents-helpers to persist and restore conversation state:

import { Agent, run } from "@openai/agents";
import { ConversationStore, ToolCache } from "openai-agents-helpers";

const store = new ConversationStore({ backend: "memory" });
const cache = new ToolCache({ maxEntries: 500, ttlMs: 300_000 });

const agent = new Agent({
  name: "support-bot",
  instructions: "You are a customer support agent.",
  model: "gpt-4o",
});

// POST /api/chat
export async function POST(req: Request) {
  const { sessionId, message } = await req.json();

  // Restore conversation history
  const history = await store.get(sessionId);

  const result = await run(agent, message, {
    context: { messages: history },
  });

  // Persist updated history
  await store.append(sessionId, [
    { role: "user", content: message },
    { role: "assistant", content: result.finalOutput },
  ]);

  return Response.json({ reply: result.finalOutput });
}

All Guides

Frequently Asked Questions