Multi-turn conversations with an agent

This tutorial step shows you how to have a multi-turn conversation with an agent, where the agent is built on the Azure OpenAI Chat Completion service.

Important

Agent Framework supports many different types of agents. This tutorial uses an agent based on a Chat Completion service, but all other agent types are run in the same way. For more information on other agent types and how to construct them, see the Agent Framework user guide.

Prerequisites

For prerequisites and creating the agent, see the Create and run a simple agent step in this tutorial.

Running the agent with a multi-turn conversation

Agents are stateless and do not maintain any state internally between calls. To have a multi-turn conversation with an agent, you need to create an object to hold the conversation state and pass this object to the agent when running it.

To create the conversation state object, call the GetNewSessionAsync method on the agent instance.

AgentSession session = await agent.GetNewSessionAsync();

You can then pass this session object to the RunAsync and RunStreamingAsync methods on the agent instance, along with the user input.

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
Console.WriteLine(await agent.RunAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", session));

This will maintain the conversation state between the calls, and the agent will be able to refer to previous input and response messages in the conversation when responding to new input.

Important

The type of service that is used by the AIAgent will determine how chat history is stored. For example, when using a ChatCompletion service, like in this example, the chat history is stored in the AgentSession object and sent to the service on each call. When using the Azure AI Agent service on the other hand, the chat history is stored in the Azure AI Agent service and only a reference to the chat history is sent to the service on each call.

Single agent with multiple conversations

It is possible to have multiple, independent conversations with the same agent instance, by creating multiple AgentSession objects. These sessions can then be used to maintain separate conversation states for each conversation. The conversations will be fully independent of each other, since the agent does not maintain any state internally.

AgentSession session1 = await agent.GetNewSessionAsync();
AgentSession session2 = await agent.GetNewSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session1));
Console.WriteLine(await agent.RunAsync("Tell me a joke about a robot.", session2));
Console.WriteLine(await agent.RunAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", session1));
Console.WriteLine(await agent.RunAsync("Now add some emojis to the joke and tell it in the voice of a robot.", session2));

Running the agent with a multi-turn conversation

Agents are stateless and do not maintain any state internally between calls. To have a multi-turn conversation with an agent, you need to create an object to hold the conversation state and pass this object to the agent when running it.

To create the conversation state object, call the get_new_thread() method on the agent instance.

thread = agent.get_new_thread()

You can then pass this thread object to the run and run_stream methods on the agent instance, along with the user input.

async def main():
    result1 = await agent.run("Tell me a joke about a pirate.", thread=thread)
    print(result1.text)

    result2 = await agent.run("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", thread=thread)
    print(result2.text)

asyncio.run(main())

This will maintain the conversation state between the calls, and the agent will be able to refer to previous input and response messages in the conversation when responding to new input.

Important

The type of service that is used by the agent will determine how conversation history is stored. For example, when using a Chat Completion service, like in this example, the conversation history is stored in the AgentThread object and sent to the service on each call. When using the Azure AI Agent service on the other hand, the conversation history is stored in the Azure AI Agent service and only a reference to the conversation is sent to the service on each call.

Single agent with multiple conversations

It is possible to have multiple, independent conversations with the same agent instance, by creating multiple AgentThread objects. These threads can then be used to maintain separate conversation states for each conversation. The conversations will be fully independent of each other, since the agent does not maintain any state internally.

async def main():
    thread1 = agent.get_new_thread()
    thread2 = agent.get_new_thread()

    result1 = await agent.run("Tell me a joke about a pirate.", thread=thread1)
    print(result1.text)

    result2 = await agent.run("Tell me a joke about a robot.", thread=thread2)
    print(result2.text)

    result3 = await agent.run("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", thread=thread1)
    print(result3.text)

    result4 = await agent.run("Now add some emojis to the joke and tell it in the voice of a robot.", thread=thread2)
    print(result4.text)

asyncio.run(main())

Next steps

Using function tools with an agent