Managing Multi-Turn Agentic Conversations

Welcome back! In the last lesson, you explored the details of the agent result object and learned how to chain agents together. You saw how to extract important information from an agent’s run and how to use the history property to pass context between agents. This knowledge is essential for building more advanced workflows.

In this lesson, we’ll focus on a key feature of interactive agents: multi-turn conversations. Many real-world applications — such as chatbots, virtual assistants, and customer support agents — require the ability to remember and build upon previous exchanges. This is what makes interactions feel natural and coherent. By the end of this lesson, you’ll know how to manage and update conversation history using the history property, enabling your agents to handle seamless, multi-turn interactions in TypeScript.

Let’s briefly review what you learned about the agent result object. When you run an agent, the SDK returns a result object that contains several useful properties: the original input, a list of new items (such as messages or tool calls), the final output, and the conversation history.

The history property is designed to make managing conversation history easy. When you access this property on the result object, it returns an array of message objects. Each object has a role (either "user" or "assistant") and a content field containing the text of the message. This format matches what the agent expects as input for the next turn. The history property gives you the full conversation history in a format that the agent can understand for the next turn.

Preserving conversation history is crucial in multi-turn interactions. Without it, the agent would treat each message as a brand-new conversation, forgetting everything that happened before. By keeping track of both user and assistant messages, you ensure that the agent can respond in a way that makes sense, referencing earlier parts of the conversation as needed.

Let’s walk through a practical example that demonstrates how to manage a multi-turn conversation using the history property in TypeScript.

To begin, import the necessary modules and create your agent. In this example, we’ll make a comedian agent that tells jokes on a given topic.

import { Agent, run, user, AgentInputItem } from '@openai/agents';

// Create an agent
const agent = new Agent({
  name: 'Comedian',
  instructions: 'You are a comedian that tells jokes on a given topic',
  model: 'gpt-5.6-terra',
  modelSettings: { providerData: { reasoning: { effort: 'none' } } },
});

Start the conversation by initializing an empty conversation history as an array of AgentInputItem. Add the first user message using the user() helper.

// Initialize conversation history as an empty array
let conversationHistory: AgentInputItem[] = [];

// Define the first user message
const firstMessage = 'Tell me a joke about AI';

// Add the first user message to the conversation history
conversationHistory.push(user(firstMessage));

Pass the conversation history to the agent using the run function, then print both the user’s message and the agent’s response.

// Run the agent passing the first message in the conversation history
const result = await run(agent, conversationHistory);

// Print the user's message
console.log(`User: ${firstMessage}\n`);

// Print the final output from the agent
console.log(`Assistant: ${result.finalOutput}\n`);

When you run this code, you'll see the user's message and the assistant's reply printed out:

User: Tell me a joke about AI

Assistant: Why did the AI get kicked out of art class?

Because every time it tried to paint, it just kept drawing a blank!

After the agent responds, update the conversation history using the history property from the result object. This ensures the history now includes both the user’s message and the assistant’s reply.

// Update the conversation history from the agent's output
conversationHistory = result.history;

Now, add a second user message to the conversation history and repeat the process to keep the conversation going.

// Define a second user message
const secondMessage = 'Tell me another one on the same topic';

// Add the new user message to the conversation history
conversationHistory.push(user(secondMessage));

// Run the agent passing the updated conversation history
const secondResult = await run(
  agent,
  conversationHistory
);

// Print the user's message
console.log(`User: ${secondMessage}\n`);

// Print the final output from the agent
console.log(`Assistant: ${secondResult.finalOutput}\n`);

If you try this next bit, you'll get the second user message and the assistant's new response — notice how the agent keeps up with the conversation and already knows the topic:

User: Tell me another one on the same topic

Assistant: Why did the AI break up with its laptop?

Because it found it too *space*-y and not enough *person*-ality!

Update the conversation history again with the latest result, then print the entire conversation to see how it has evolved.

// Update the conversation history with the new result
conversationHistory = secondResult.history;

// Print the conversation history
console.log(`Conversation history:\n${JSON.stringify(conversationHistory, null, 2)}`);

Once you update and print the conversation history, you'll see the full back-and-forth so far:

[
  {
    "type": "message",
    "role": "user",
    "content": "Tell me a joke about AI"
  },
  {
    "type": "message",
    "id": "msg_686be328f50c819899eb3774db4970ed06fd8c2f95622754",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "Why did the AI get kicked out of art class?\n\nBecause every time it tried to paint, it just kept drawing a blank!",
        "annotations": [],
        "logprobs": []
      }
    ],
    "status": "completed",
    "providerData": {}
  },
  {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Tell me another one on the same topic"
      }
    ]
  },
  {
    "type": "message",
    "id": "msg_686be32a27608198af91d2390f7dfd1a06fd8c2f95622754",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "Why did the AI break up with its laptop?\n\nBecause it found it too *space*-y and not enough *person*-ality!",
        "annotations": [],
        "logprobs": []
      }
    ],
    "status": "completed",
    "providerData": {}
  }
]

By following these steps, you can build a natural, back-and-forth conversation with your agent, where each turn builds on the previous ones and the context is preserved throughout.

In this lesson, you learned how to manage and update conversation history using the history property, enabling your agents to handle seamless multi-turn interactions in TypeScript. You saw how to initialize a conversation, update it with each new message, and pass the evolving history back to the agent. This approach is essential for building interactive applications where context matters.

By following best practices — such as managing token limits and keeping your conversation history well-structured — you can create agents that feel natural and engaging. You are now ready to practice these skills in the upcoming exercises. Keep up the great work, and get ready to build even more powerful and interactive agent experiences!