Conversas e execução paralela de múltiplos turnos do Microsoft Agent Framework

// 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?");

// 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 com vários turnos com agentes de IA. Isso inclui a manutenção do contexto em várias interações. Diferentes tipos de agente e serviços subjacentes que são usados para criar agentes podem dar 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 ChatAgent baseado em um agente do Foundry, o histórico de conversas é mantido no serviço. Ao usar uma ChatAgent conclusão de chat com base no gpt-4, o histórico de conversas é na memória e gerenciado pelo agente.

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

Relação Agent/AgentThread

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

No entanto, nem todos os agentes dão suporte a todos os tipos de thread. Por exemplo, se você estiver usando um ChatClientAgent com o serviço de respostas, as instâncias AgentThread criadas por esse agente não funcionarão com um serviço ChatClientAgent que usa o Foundry Agent. Isso ocorre porque esses serviços oferecem suporte para salvar o histórico de conversas no serviço, e o AgentThread possui apenas uma referência para esse thread gerenciado pelo serviço.

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

Suporte ao threading por serviço/protocolo

Criação do AgentThread

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

1. Chamando o agente com get_new_thread().
2. Ao executar o agente sem fornecer um AgentThread. Nesse caso, o agente criará um throwaway AgentThread com um thread subjacente que será usado apenas durante a execução.

Alguns threads subjacentes podem ser criados de forma persistente em um serviço subjacente quando o serviço assim requer; por exemplo, nos agentes de IA do Azure ou nas respostas do OpenAI. Qualquer limpeza ou exclusão desses threads é 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 do AgentThread

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

Para casos em que o histórico de conversas é armazenado em um serviço, o serializado AgentThread conterá uma ID do thread no serviço. Para casos em que o histórico de conversas é gerenciado na memória, o serializado AgentThread conterá as próprias mensagens.

# 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)

Repositórios de Mensagens Personalizados

Para threads na memória, você pode fornecer uma implementação personalizada do repositório de mensagens 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 Agent/AgentThread

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

No entanto, nem todos os agentes dão suporte a todos os tipos de thread. Por exemplo, se você estiver usando um ChatAgent com o serviço OpenAI Responses e as instâncias store=True, AgentThread utilizadas por esse agente, isso não funcionará com um serviço ChatAgent que utiliza o Agente de IA do Azure, pois os thread_ids não são compatíveis.

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

Exemplo prático de vários turnos

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