Getting Started with OpenAI Agents in TypeScript

Getting Started with OpenAI Agents in TypeScript | CodeSignal Learn

Introduction & Lesson Overview

Welcome to the first lesson of our course, Getting Started with OpenAI Agents in TypeScript . In this lesson, you’ll take your very first steps with the OpenAI Agents SDK . This course is designed for developers who want to build intelligent, task-oriented agents using TypeScript. No prior experience with the SDK is required—we’ll guide you through each concept with clear explanations and practical, hands-on examples. By the end of this lesson, you’ll understand what an OpenAI agent is, how it differs from a simple chat-based language model, and how to create and run your own agent using the OpenAI Agents SDK. This foundational knowledge will prepare you for more advanced topics and hands-on exercises in the rest of the course.

What is an Agent?

An agent, in this context, is much more than just a chatbot. While traditional chat LLMs (like early versions of ChatGPT) simply respond to prompts with text, agents are designed to perform specific tasks, follow detailed instructions, and even use tools or delegate work to other agents. For example, a chat LLM might answer, “What’s the weather like in Paris?” with a general response based on its training data. An agent, on the other hand, could be set up as a travel assistant, given instructions to always provide up-to-date information, and even use external APIs to fetch the latest weather. Agents are configurable, can be given roles, and can be equipped with tools and safety checks, making them much more powerful and reliable for real-world applications.

Overview of the OpenAI Agents SDK

The OpenAI Agents SDK is a library that helps you easily build, manage, and run AI agents powered by large language models. With this SDK, you can create agents that do much more than just chat—they can reason, use tools, interact with other agents, and perform complex, multi-step tasks in a structured way. The SDK’s simple and flexible design makes it easy to prototype and deploy agentic applications quickly. For more information, you can visit the official OpenAI Agents SDK Documentation . Throughout this course, you’ll be working in the CodeSignal environment, where everything is already set up for you—no installation or API key configuration needed. You can focus entirely on learning and experimenting with the code.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Local Setup Steps

If you’d like to run the code examples on your own machine later, you’ll need to install the SDK and set your OpenAI API key. Here’s how you can get started in a Node.js environment: Install the SDK using npm or yarn : Shell npm install @openai/agents # or yarn add @openai/agents npm install @openai/agents # or yarn add @openai/agents Set your OpenAI API key as an environment variable: You can do this in your terminal before running your code: Shell # On Linux/macOS export OPENAI_API_KEY=your_openai_api_key # On Windows (Command Prompt) set OPENAI_API_KEY=your_openai_api_key # On Windows (PowerShell) $env:OPENAI_API_KEY="your_openai_api_key" # On Linux/macOS export OPENAI_API_KEY=your_openai_api_key # On Windows (Command Prompt) set OPENAI_API_KEY=your_openai_api_key # On Windows (PowerShell) $env:OPENAI_API_KEY="your_openai_api_key" Alternatively, you can use a .env file and a package like dotenv to load environment variables automatically. Note: None of these setup steps are necessary while working through this course—the CodeSignal environment already has a valid API key configured for you.

Creating Your First Agent

Let’s see how to create a simple agent using the OpenAI Agents SDK for TypeScript . The main class you’ll use is called Agent . TypeScript import { Agent } from '@openai/agents'; // Define a simple agent const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.'}); import { Agent } from '@openai/agents'; // Define a simple agent const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.'}); In this code, we create an agent named “Travel Genie.” The instructions tell the agent to act as a travel assistant, be friendly, and give personalized suggestions. At its most basic, you need to provide two key parameters: The name property serves as a unique identifier for your agent, making it easier to reference when working with multiple agents. The instructions property acts as the system prompt, defining the agent’s role and behavior guidelines. When you create an agent with just these parameters, it will use the default language model configured in the SDK.

Specifying a Language Model

For more control over your agent’s capabilities, you can specify which language model it should use: TypeScript import { Agent } from '@openai/agents'; // Define an agent with a specific model const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', // Specify which model to use modelSettings: { reasoning: { effort: 'none' } }}); import { Agent } from '@openai/agents'; // Define an agent with a specific model const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', // Specify which model to use modelSettings: { reasoning: { effort: 'none' } }}); By default, the SDK will use models provided by OpenAI. For example, gpt-5.6-terra is a cost-effective model optimized for agentic workflows. You can also specify other OpenAI models, such as gpt-5.6-luna for cost-sensitive, high-volume workloads. Separately from the model choice, you control how much the model reasons before answering by setting reasoning.effort inside modelSettings : use low or higher for advanced reasoning and complex problem-solving, or none for the fastest responses. When you do not set it, GPT-5.6 models reason at medium effort by default. In this course, we’ll focus exclusively on using OpenAI models to keep things simple and consistent.

Tune Model Parameters

To fine-tune your agent's response behavior in TypeScript, you can adjust various model parameters using the modelSettings property. This property accepts an object where you can configure settings such as temperature and maxTokens . Here's how you can define an agent with customized model settings: TypeScript import { Agent } from '@openai/agents'; // Define an agent with customized model settings const agent = new Agent({name: 'Travel Genie', instructions: 'You are Travel Genie, a friendly and knowledgeable travel assistant. Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', modelSettings: {reasoning: { effort: 'none' }, temperature: 0.7, // Controls creativity (0-2) maxTokens: 500 // Limits response length}}); import { Agent } from '@openai/agents'; // Define an agent with customized model settings const agent = new Agent({name: 'Travel Genie', instructions: 'You are Travel Genie, a friendly and knowledgeable travel assistant. Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', modelSettings: {reasoning: { effort: 'none' }, temperature: 0.7, // Controls creativity (0-2) maxTokens: 500 // Limits response length}}); In this example: temperature : Controls randomness in responses. The valid range is 0 to 2. Lower values (e.g., 0.2) produce more focused, deterministic outputs, while higher values (e.g., 1.0 or above) generate more creative, varied responses. maxTokens : Caps the length of the agent's response to the specified number of tokens. This is primarily used to control costs, as API usage is billed per token. The model is not aware of this limit while generating its output, so if the response is cut off, it may end abruptly or mid-sentence. By adjusting these settings, you can tailor your agent's behavior to better suit your specific application requirements.

Running the Agent

Once you have defined your agent, you can run it using the run utility function provided by the SDK. The OpenAI Agents SDK for TypeScript is built on asynchronous operations, so all agent runs return promises that must be awaited. The run function is the simplest way to execute an agent and get its response. Here's how you can run the agent with a user prompt: TypeScript import { Agent, run } from '@openai/agents'; // Define the agent const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', modelSettings: { reasoning: { effort: 'none' } }}); // Run the agent with an input prompt const result = await run(agent, "What's your top recommendation for adventure seekers?"); import { Agent, run } from '@openai/agents'; // Define the agent const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', modelSettings: { reasoning: { effort: 'none' } }}); // Run the agent with an input prompt const result = await run(agent, "What's your top recommendation for adventure seekers?"); The run function takes three parameters: The agent instance to execute The user's input (as a string in this simple case) An optional configuration object (which we'll not explore in this lesson) Since run is an async function, you must use await to wait for the result. The function handles the entire agent loop internally and returns a RunResult object containing the agent's final response and other execution details.

Running the Agent with Runner

Alternatively, you can use the Runner class directly with its static run method. This approach gives you the same functionality as the run utility function: TypeScript import { Agent, Runner } from '@openai/agents'; // Define the agent const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', modelSettings: { reasoning: { effort: 'none' } }}); // Run the agent using the Runner class const result = await Runner.run(agent, "What's your top recommendation for adventure seekers?"); import { Agent, Runner } from '@openai/agents'; // Define the agent const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', modelSettings: { reasoning: { effort: 'none' } }}); // Run the agent using the Runner class const result = await Runner.run(agent, "What's your top recommendation for adventure seekers?"); The Runner.run static method works identically to the run utility function. In fact, the run function is just a convenient wrapper around Runner.run . Both approaches use a default runner instance behind the scenes.

Creating and Using a Runner Instance

For more control over the execution environment, you can create your own Runner instance. This approach is particularly useful in applications where you want to: Reuse the same runner configuration across multiple agent runs Configure global settings that apply to all agents run through that runner Manage resources more efficiently in long-running applications Here's how to create and use a Runner instance: TypeScript import { Agent, Runner } from '@openai/agents'; // Define the agent const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', modelSettings: { reasoning: { effort: 'none' } }}); // Create a Runner instance const runner = new Runner(); // Run the agent const result = await runner.run(agent, "What's your top recommendation for adventure seekers?"); import { Agent, Runner } from '@openai/agents'; // Define the agent const agent = new Agent({name: 'Travel Genie', instructions:'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +'Recommend exciting destinations and offer helpful travel tips.', model: 'gpt-5.6-terra', modelSettings: { reasoning: { effort: 'none' } }}); // Create a Runner instance const runner = new Runner(); // Run the agent const result = await runner.run(agent, "What's your top recommendation for adventure seekers?"); Creating your own Runner instance is especially beneficial in production applications where you might want to configure specific settings, manage multiple agents, or optimize resource usage. The runner can be created once and reused throughout your application's lifecycle.

Introduction & Lesson Overview

What is an Agent?

Overview of the OpenAI Agents SDK

Join the 1M+ learners on CodeSignal

Local Setup Steps

Understanding the Agent Loop

Creating Your First Agent

Specifying a Language Model

Tune Model Parameters

Running the Agent

Running the Agent with Runner

Creating and Using a Runner Instance

How Agents are Executed

Extracting and Interpreting the Final Output

Lesson Summary & Next Steps