Introduction & Overview

Welcome to the first lesson of this course on coordinating OpenAI agent workflows in TypeScript. In this course, you'll learn how to build conversational AI applications that can handle multi-turn conversations — that is, dialogues in which the user and the agent exchange several messages back and forth, rather than just a single question and answer.

A key challenge in building these applications is maintaining context: making sure the agent remembers what was said earlier in the conversation so its responses stay relevant and coherent. This is especially important for real-world use cases like travel assistants, customer support bots, or tutoring systems.

In this lesson, you'll see how to use the OpenAI Agents SDK for TypeScript to manage conversation history using the history property returned by the run function. You'll learn how to pass this history back into the agent for each new turn, enabling your agent to respond in a way that feels natural and context-aware.

By the end of this lesson, you'll know how to build stateful, multi-turn conversations in TypeScript using the OpenAI Agents SDK.

Understanding Multi-Turn Conversations

A multi-turn conversation is a dialogue in which the user and the agent exchange several messages, building up a conversation history. For example, a user might ask for a travel recommendation, then follow up with questions about the best time to visit or what to pack. The agent needs to remember previous messages to provide relevant and accurate responses.

A typical conversation history might look like this:

The main challenge is maintaining the context. If the agent forgets what was said earlier, its answers may become confusing or repetitive. By keeping track of the entire conversation history and providing it to the agent each time, you ensure the agent can generate answers that make sense in the context of the ongoing dialogue.

Using the history Property to Manage Conversation State

In the OpenAI Agents SDK for TypeScript, every time you call the run function, it returns a result object that includes a history property. This history array contains all the messages exchanged so far — both from the user and the agent.

To continue a conversation, you simply append new user messages to this history array and pass the updated array back into the next run call. This way, the agent always has access to the full conversation context, allowing it to generate coherent, context-aware responses.

Let's walk through a practical example to see how this works in code.

Step 1: Getting the First Answer

Suppose you're building a travel assistant agent. To enable the agent to answer follow-up questions naturally, it needs to remember the ongoing conversation. Let's start by initializing the agent and running it with an initial user question.

When you run this code, the agent responds to the user's initial question. Here's an example of what the output might look like:

Step 2: Inspecting the Conversation History

After receiving the agent's response, you can inspect the conversation history so far by accessing the history property on the result object. This property is an array of message objects representing the full dialogue up to this point.

You can print the conversation history using JSON.stringify() to get a nicely formatted output:

This will display the current state of the conversation history in a nicely formatted JSON structure:

This array contains both the user's original question and the agent's detailed response. Note that the assistant's content is structured as an array containing an object with type: "output_text" and the actual text content. By preserving this structure, you ensure that the agent can reference previous turns in the conversation.

Step 3: Adding a Follow-Up Message

To continue the conversation, you'll want to add a new user message to the conversation history. In the OpenAI Agents SDK for TypeScript, you can use the user() helper function to create a new user message and then concatenate it to the existing history array.

For example:

Now, the history array includes the new user question:

Notice that the new user message has a content array containing an object with type: "input_text" and the actual text. By appending the new message, you're preparing the agent to answer in the context of the entire conversation, not just the latest question.

Step 4: Running the Agent with the Updated Conversation

With the updated history — which consists of the previous conversation plus the new user message — you can now run the agent again. This time, instead of passing a single string as input, you pass the entire history array to the run function. This ensures the agent has access to the full conversation history, including the new user message, allowing it to provide a contextually relevant answer to the follow-up question.

Here's an example of the agent's response to the follow-up:

Because the agent receives the full conversation history, it can answer the follow-up question in a way that feels natural and informed, maintaining the flow and context of the dialogue.

Summary & Preparation For Practice

In this lesson, you learned how to maintain and pass dialogue history to an agent using the history property in the OpenAI Agents SDK for TypeScript. This technique allows you to build stateful, multi-turn conversations in which the agent can remember and respond to previous messages, making your applications more natural and engaging.

You saw how to use the history array to collect the conversation so far, append new user inputs with the user() helper, and continue the dialogue seamlessly by passing the updated history back into the run function. You are now ready to practice these skills in hands-on exercises. Mastering multi-turn conversations is a key step toward building powerful, context-aware AI applications!

Sign up
Join the 1M+ learners on CodeSignal
Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal