Getting Started with OpenAI Agents

Welcome to the first lesson in your journey to mastering the Model Context Protocol (MCP) and its use with the OpenAI Agents SDK in TypeScript. MCP is an open standard designed to enable large language models (LLMs) to securely and efficiently connect with external applications, tools, and data sources through a unified protocol. By providing a standardized way for AI models to access and interact with real-time information, MCP makes it possible to build more capable, context-aware agents that can perform complex tasks and integrate seamlessly with a wide range of systems.

Before we dive into MCP and tool integration, it's important to first build a solid foundation in how agents work using the OpenAI Agents SDK. In this lesson, you will learn how to create a simple agent and understand the basics of agent execution. This foundational knowledge will prepare you for more advanced topics in future lessons, including developing and integrating your own MCP server. Get ready to take your first step toward building intelligent, tool-empowered agents!

The OpenAI Agents SDK is a TypeScript/Node.js package that makes it easy to build, manage, and run AI agents powered by large language models. With this SDK, you can create agents that reason, use tools, interact with other agents, and perform complex tasks in a structured way. Its simple and flexible design lets you quickly prototype and deploy agentic applications. For more details, you can check out the OpenAI Agents SDK Documentation.

If you're working in your own local environment, you'll need to install the package and set your OpenAI API key before you can start building agents. To install the SDK, you can use either npm or yarn:

# Using npm
npm install @openai/agents

# Using yarn
yarn add @openai/agents

After installing, set your OpenAI API key as an environment variable. The command you use depends on your operating system:

# Linux/macOS
export OPENAI_API_KEY=your_openai_api_key

# Windows (Command Prompt)
set OPENAI_API_KEY=your_openai_api_key

# Windows (PowerShell)
$env:OPENAI_API_KEY="your_openai_api_key"

While using the CodeSignal coding environment in this course, you don't need to worry about installation or API keys — everything is already set up for you. You can jump right in and start running the code examples as you learn.

A key feature of the OpenAI Agents SDK is the agent loop. This loop is what sets an agent apart from a simple chat model.

A simple chat model, like gpt-5.6-luna in a basic chat interface, takes your input and generates a single response — there's no memory of previous steps, no ability to call tools, and no way to interact with other systems. It's a one-shot exchange: you ask a question, and the model answers.

An agent, on the other hand, can perform much more complex tasks thanks to the agent loop. Here's how the agent loop works and why it's different:

1. Input Reception: The agent receives an input (such as a user query).
2. Reasoning and Planning: The agent uses the language model (LLM) to decide what to do next. This could be generating a direct answer, calling an external tool, or handing off the task to another agent.
3. Action Execution:
   • If the agent needs to use a tool (like a calculator, web search, or database), the loop executes the tool call, collects the result, and feeds it back into the agent.
   • If the agent needs to delegate, the loop can pass control to another agent.
4. Iterative Processing: The agent loop repeats this process — reasoning, acting, and updating — until a final answer is produced or a maximum number of steps is reached.
5. Final Output: Once the agent determines it has enough information, it produces a final output and the loop ends.

This iterative, multi-step process allows agents to break down complex problems, use external resources, and coordinate with other agents — all automatically managed by the SDK. The agent loop is what enables agents to go beyond simple Q&A and handle real-world tasks that require reasoning, tool use, and multi-step workflows.

Now that you understand the agent loop and how agents differ from simple chat models, let's see how to put this into practice by creating a basic agent. Here is an example of how to create a simple agent to provide creative, healthy recipes:

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

// Create a simple agent with a name, instructions and model
const agent = new Agent({
  name: 'Recipe Chef',
  instructions: 'You are a creative chef. Provide a simple, healthy recipe with clear steps and ingredients.',
  model: 'gpt-5.6-terra',
  modelSettings: { providerData: { reasoning: { effort: 'none' } } },
});

In the OpenAI Agents SDK, you define an agent by creating a new Agent instance with an object literal containing the following properties:

• name: A label to identify your agent (e.g., "Recipe Chef").
• instructions: Guidance that shapes the agent's behavior and responses (for example, asking the agent to provide clear steps and healthy ingredients).
• model (optional): Specifies which language model the agent will use to generate answers. For example, "gpt-5.6-terra" is a balanced model well suited to general agentic workflows and strong instruction following. If you do not specify a model, the SDK will use a default model for the agent.

By clearly defining these parameters, you ensure your agent behaves as intended and leverages the right language model for your specific use case. This flexibility allows you to tailor agents for a wide range of applications and performance needs.

After creating an agent, you need to execute it to perform a task. The OpenAI Agents SDK provides several ways to do this, each with different levels of control and flexibility. Understanding the difference between the run helper function, the static Runner.run method, and creating your own Runner instance will help you choose the best approach for your application.

The simplest way to execute an agent is with the run helper function. This function is a convenient wrapper that handles the entire agent loop for you:

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

// Run the agent asynchronously
const result = await run(
  agent,
  'Give me a quick recipe for a healthy smoothie'
);

• When to use: For quick prototyping, scripts, or when you don't need to customize the execution environment.
• How it works: Internally, run uses a default runner instance to execute the agent.

The SDK also exposes a Runner class with a static run method. This method works identically to the run helper function and is useful if you prefer a class-based API:

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

// Run the agent using the Runner class
const result = await Runner.run(
  agent,
  'Give me a quick recipe for a healthy smoothie'
);

• When to use: If you want to be explicit about using the class-based API, or if you plan to later switch to a custom runner instance.

For more advanced scenarios, you can create your own Runner instance. This is especially useful if you want to:

• Reuse the same runner configuration across multiple agent runs
• Set global options or hooks for all runs
• Manage resources efficiently in long-running applications

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

// Create a Runner instance
const runner = new Runner();

// Run the agent using the runner instance
const result = await runner.run(
  agent,
  'Give me a quick recipe for a healthy smoothie'
);

• When to use: In production applications, when you need to manage multiple agents, customize execution, or optimize resource usage.

All three approaches execute the same agent loop under the hood, so you can choose the one that best fits your needs.

When you run an agent using any of the three approaches, you receive a result object containing the agent's response and execution details. The most important property is finalOutput, which contains the agent's complete answer:

const result = await run(
  agent,
  'Give me a quick recipe for a healthy smoothie'
);

// Print the final output from the agent
console.log(result.finalOutput);

When you run the agent with the input 'Give me a quick recipe for a healthy smoothie', you might receive an output like this:

**Green Energy Smoothie**

**Ingredients:**
- 1 cup spinach (fresh or frozen)
- 1 small banana
- 1/2 cup frozen mango chunks
- 1 tablespoon chia seeds (optional)
- 1 cup unsweetened almond milk (or any milk of your choice)
- 1/2 cup ice (optional)

**Steps:**
1. Add the spinach, banana, mango, and chia seeds to a blender.
2. Pour in the almond milk.
3. Add ice if you want it extra cold and thick.
4. Blend on high until smooth.
5. Taste and add a splash more milk if needed to reach your desired consistency.
6. Pour into a glass and enjoy immediately!

**Tip:** For extra protein, add a scoop of your favorite protein powder before blending.

If you're working in a Node.js environment that doesn't support top-level await, you can wrap your code in an async function:

async function main() {
  const result = await run(
    agent,
    'Give me a quick recipe for a healthy smoothie'
  );
  
  console.log(result.finalOutput);
}

main().catch(console.error);

This asynchronous approach is recommended for all applications, as it prevents your program from blocking while the agent processes requests and allows for efficient handling of multiple concurrent operations.

Streaming execution enables real-time processing and delivery of the agent's outputs. Instead of waiting for the complete response, you can process partial results as they become available. This is useful for applications that require immediate feedback or progress updates, such as live chat interfaces or interactive tools.

Here is how to use streaming execution:

// Start streaming the run
const streamedResult = await run(
  agent,
  'Give me a quick recipe for a healthy smoothie',
  { stream: true }
);

// Stream the text output to console as it arrives
streamedResult.toTextStream({ compatibleWithNodeStreams: true })
  .pipe(process.stdout);

// Wait for streaming to complete
await streamedResult.completed;

// Print the final output after streaming is complete
console.log('\n\nFinal Output:', streamedResult.finalOutput);

In this example, the run function is called with a third parameter { stream: true } to enable streaming mode. This returns a streaming result object that provides several useful methods:

• toTextStream({ compatibleWithNodeStreams: true }) creates a Node.js-compatible readable stream that you can pipe to other streams, such as process.stdout for console output
• completed is a Promise that resolves when the streaming is finished
• finalOutput contains the complete response after streaming completes

When you run this code, you'll see the agent's response appear in real time as it's generated, character by character. This provides immediate feedback to users and creates a more interactive experience. Even when using streaming mode, you can still access the complete final output after streaming completes, giving you the flexibility to both monitor the process in real time and easily extract the final result when needed.

In this lesson, you built a solid foundation for working with the OpenAI Agents SDK in TypeScript. You learned how agents differ from simple chat models by exploring the agent loop — a process that allows agents to reason, plan, and act in multiple steps. You saw how to create a basic agent using object literal syntax, and then discovered three different ways to execute your agent: using the run helper function for simplicity, the static Runner.run method for class-based APIs, and creating your own Runner instance for advanced control and customization. You also learned how to handle streaming execution for real-time responses.

With these fundamentals in place, you're ready to move on to more advanced topics, where you'll get hands-on practice applying what you've learned and start extending your agents' capabilities. Dive into the practice exercises ahead — they're designed to help you solidify your understanding and gain confidence with the OpenAI Agents SDK.