Conversas multiturno e encadeamento de threads do Microsoft Agent Framework

O Microsoft Agent Framework fornece suporte interno para gerenciar conversas de vários turnos com agentes de IA. Isso inclui manter o contexto em várias interações. Diferentes tipos de agente e serviços subjacentes que são usados para criar agentes podem oferecer suporte a diferentes tipos de threading, e a estrutura do agente abstrai essas diferenças, fornecendo uma interface consistente para os desenvolvedores.

Por exemplo, ao usar um ChatClientAgent com base em um agente de fundição, o histórico de conversas é mantido no serviço. Ao usar um ChatClientAgent baseado na conclusão de bate-papo com o gpt-4.1, o histórico de conversas é mantido na memória e gerido pelo agente.

O tipo AgentThread é a abstração que representa um tópico de conversa com um agente. AIAgent As instâncias são sem estado e a mesma instância de agente pode ser utilizada com várias instâncias de AgentThread. Todo o estado é, portanto, preservado no AgentThread. Pode representar tanto o histórico de chat AgentThread como qualquer outro estado que o agente precise de preservar em múltiplas interações. O histórico da conversa pode ser armazenado na própria thread ou remotamente, com o AgentThread contendo apenas uma referência ao histórico de chat remoto. O AgentThread estado pode também incluir memórias ou referências a memórias armazenadas remotamente.

Sugestão

Para saber mais sobre o Histórico e a Memória do Chat no Quadro do Agente, consulte Histórico e Memória do Chat do Agente.

Criação do AgentThread

AgentThread As instâncias podem ser criadas de duas maneiras:

1. Ao chamar GetNewThread ao agente.
2. Executando o agente e não fornecendo um AgentThread arquivo. Neste caso, o agente criará um descartável AgentThread com um thread subjacente que só será usado durante a execução.

Alguns threads subjacentes podem ser criados persistentemente em um serviço subjacente, onde o serviço requer isso, por exemplo, Foundry Agents ou OpenAI Responses. Qualquer limpeza ou exclusão desses tópicos é de responsabilidade do usuário.

// Create a new thread.
AgentThread thread = agent.GetNewThread();
// Run the agent with the thread.
var response = await agent.RunAsync("Hello, how are you?", thread);

// Run an agent with a temporary thread.
response = await agent.RunAsync("Hello, how are you?");

Armazenamento de AgentThread

AgentThread As instâncias podem ser serializadas e armazenadas para uso posterior. Isso permite a preservação do contexto da conversa em diferentes sessões ou chamadas de serviço.

Para casos em que o histórico de conversas é armazenado num serviço, o serializado AgentThread conterá um ID do tópico no serviço. Em casos em que o histórico de conversas é gerido em memória, o objeto serializado AgentThread conterá as mensagens propriamente ditas.

// Create a new thread.
AgentThread thread = agent.GetNewThread();
// Run the agent with the thread.
var response = await agent.RunAsync("Hello, how are you?", thread);

// Serialize the thread for storage.
JsonElement serializedThread = await thread.SerializeAsync();
// Deserialize the thread state after loading from storage.
AgentThread resumedThread = await agent.DeserializeThreadAsync(serializedThread);

// Run the agent with the resumed thread.
var response = await agent.RunAsync("Hello, how are you?", resumedThread);

O Microsoft Agent Framework fornece suporte interno para gerenciar conversas de vários turnos com agentes de IA. Isso inclui manter o contexto em várias interações. Diferentes tipos de agente e serviços subjacentes que são usados para criar agentes podem oferecer suporte a diferentes tipos de threading, e o Agent Framework abstrai essas diferenças, fornecendo uma interface consistente para desenvolvedores.

Por exemplo, ao usar um ChatAgent baseado num agente Foundry, o histórico de comunicação é persistido no serviço. Ao utilizar um ChatAgent baseado na conclusão do bate-papo com gpt-4, o histórico de conversas é mantido na memória e gerenciado pelo agente.

As diferenças entre os modelos de threading subjacentes são abstraídas por meio do AgentThread tipo.

Relação Agente/AgentThread

AIAgent As instâncias são sem estado e a mesma instância de agente pode ser utilizada com várias instâncias de AgentThread.

No entanto, nem todos os agentes suportam todos os tipos de thread. Por exemplo, se estiveres a usar um ChatClientAgent com o serviço de respostas, as instâncias AgentThread criadas por esse agente não funcionarão com um ChatClientAgent usando o serviço Foundry Agent. Isso ocorre porque esses serviços suportam salvar o histórico de conversas no serviço, e o AgentThread tem apenas uma referência a este thread gerido pelo serviço.

Portanto, é considerado inseguro usar uma AgentThread instância que foi criada por um agente com uma instância de agente diferente, a menos que você esteja ciente do modelo de threading subjacente e suas implicações.

Suporte de threading por serviço/protocolo

Serviço	Suporte a multithreading
Agentes de Fundição	Threads persistentes gerenciados pelo serviço
Respostas OpenAI	Threads persistentes geridas pelo serviço OU threads em memória
OpenAI Conclusão de Chat	Threads em memória
Assistentes OpenAI	Threads gerenciados por serviço
A2A	Threads gerenciados por serviço

Criação do AgentThread

AgentThread As instâncias podem ser criadas de duas maneiras:

1. Ao chamar get_new_thread() ao agente.
2. Executando o agente e não fornecendo um AgentThread arquivo. Neste caso, o agente criará um descartável AgentThread com um thread subjacente que só será usado durante a execução.

Alguns threads subjacentes podem ser criados persistentemente em serviço subjacente, quando o serviço o requer, por exemplo, Agentes de IA do Azure ou Respostas OpenAI. Qualquer limpeza ou exclusão desses tópicos é de responsabilidade do usuário.

# Create a new thread.
thread = agent.get_new_thread()
# Run the agent with the thread.
response = await agent.run("Hello, how are you?", thread=thread)

# Run an agent with a temporary thread.
response = await agent.run("Hello, how are you?")

Armazenamento de AgentThread

AgentThread As instâncias podem ser serializadas e armazenadas para uso posterior. Isso permite a preservação do contexto da conversa em diferentes sessões ou chamadas de serviço.

Para casos em que o histórico de conversas é armazenado num serviço, o serializado AgentThread conterá um ID do tópico no serviço. Em casos em que o histórico de conversas é gerido em memória, o objeto serializado AgentThread conterá as mensagens propriamente ditas.

# Create a new thread.
thread = agent.get_new_thread()
# Run the agent with the thread.
response = await agent.run("Hello, how are you?", thread=thread)

# Serialize the thread for storage.
serialized_thread = await thread.serialize()
# Deserialize the thread state after loading from storage.
resumed_thread = await agent.deserialize_thread(serialized_thread)

# Run the agent with the resumed thread.
response = await agent.run("Hello, how are you?", thread=resumed_thread)

Armazenamentos de mensagens personalizadas

Para threads na memória, você pode fornecer uma implementação de armazenamento de mensagens personalizada para controlar como as mensagens são armazenadas e recuperadas:

from agent_framework import AgentThread, ChatMessageStore, ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

class CustomStore(ChatMessageStore):
    # Implement custom storage logic here
    pass

# You can also provide a custom message store factory when creating the agent
def custom_message_store_factory():
    return CustomStore()  # or your custom implementation

async with AzureCliCredential() as credential:
    agent = ChatAgent(
        chat_client=AzureAIAgentClient(async_credential=credential),
        instructions="You are a helpful assistant",
        chat_message_store_factory=custom_message_store_factory
    )
    # Or let the agent create one automatically
    thread = agent.get_new_thread()
    # thread.message_store is not a instance of CustomStore

Relação Agente/AgentThread

Agents são sem estado e a mesma instância do agente pode ser utilizada com várias instâncias de AgentThread.

No entanto, nem todos os agentes suportam todos os tipos de thread. Por exemplo, se tu estiveres a usar um ChatAgent com o serviço OpenAI Responses e as instâncias store=True e AgentThread usadas por este agente, não funcionarão com um ChatAgent usando o serviço Azure AI Agent, porque os thread_ids não são compatíveis.

Portanto, é considerado inseguro usar uma AgentThread instância que foi criada por um agente com uma instância de agente diferente, a menos que você esteja ciente do modelo de threading subjacente e suas implicações.

Exemplo prático de várias voltas

Aqui está um exemplo completo mostrando como manter o contexto em várias interações:

from agent_framework import ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def multi_turn_example():
    async with (
        AzureCliCredential() as credential,
        ChatAgent(
            chat_client=AzureAIAgentClient(async_credential=credential),
            instructions="You are a helpful assistant"
        ) as agent
    ):
        # Create a thread for persistent conversation
        thread = agent.get_new_thread()

        # First interaction
        response1 = await agent.run("My name is Alice", thread=thread)
        print(f"Agent: {response1.text}")

        # Second interaction - agent remembers the name
        response2 = await agent.run("What's my name?", thread=thread)
        print(f"Agent: {response2.text}")  # Should mention "Alice"

        # Serialize thread for storage
        serialized = await thread.serialize()

        # Later, deserialize and continue conversation
        new_thread = await agent.deserialize_thread(serialized)
        response3 = await agent.run("What did we talk about?", thread=new_thread)
        print(f"Agent: {response3.text}")  # Should remember previous context

Próximos passos

Memória do agente