Conversazioni a più turni di Microsoft Agent Framework

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

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

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

// Serialize the session for storage.
JsonElement serializedSession = session.Serialize();
// Deserialize the session state after loading from storage.
AgentSession resumedSession = await agent.DeserializeSessionAsync(serializedSession);

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

Microsoft Agent Framework offre il supporto predefinito per la gestione di conversazioni a più turni con gli agenti di intelligenza artificiale. Ciò include la gestione del contesto tra più interazioni. Diversi tipi di agente e servizi sottostanti usati per compilare agenti possono supportare diversi tipi di cronologia chat e Agent Framework astrae queste differenze, fornendo un'interfaccia coerente per gli sviluppatori.

Ad esempio, quando si usa un ChatAgent oggetto basato su un agente Foundry, la cronologia delle conversazioni viene mantenuta nel servizio. Quando si usa un ChatAgent oggetto basato sul completamento della chat con gpt-4, la cronologia delle conversazioni è in memoria e gestita dall'agente.

Le differenze tra i modelli di cronologia delle chat sottostanti vengono astratte tramite il AgentSession tipo .

Relazione tra Agent e AgentSession

AIAgent le istanze sono senza stato e la stessa istanza dell'agente può essere usata con più AgentSession istanze.

Non tutti gli agenti supportano però tutti i AgentSession tipi. Ad esempio, se si utilizza un ChatClientAgent con il servizio di risposte, le istanze AgentSession create da questo agente non funzioneranno con un ChatClientAgent utilizzando il servizio Foundry Agent. Questo perché questi servizi supportano il salvataggio della cronologia delle conversazioni nel servizio e mentre le due AgentSession istanze avranno riferimenti a ogni conversazione archiviata del servizio, l'ID del servizio risposte non può essere usato con il servizio Foundry Agent e viceversa.

È quindi considerato non sicuro usare un'istanza AgentSession creata da un agente con un'istanza dell'agente diversa, a meno che non si sia a conoscenza del modello di cronologia delle chat sottostanti e delle relative implicazioni.

Supporto della cronologia chat per servizio/protocollo

Creazione di AgentThread

AgentThread Le istanze possono essere create in due modi:

1. get_new_thread() Chiamando l'agente.
2. Eseguendo l'agente e non fornendo un oggetto AgentThread. In questo caso, l'agente creerà un oggetto usa e getta AgentThread con un thread sottostante che verrà usato solo per la durata del ciclo dell'esecuzione.

Alcuni servizi sottostanti potrebbero memorizzare conversazioni, thread o risposte in modo persistente, laddove il servizio lo richiede, come ad esempio per gli agenti AI di Azure o per le risposte OpenAI. Qualsiasi pulizia o eliminazione di questi elementi è responsabilità dell'utente.

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

Archiviazione di AgentThread

AgentThread Le istanze possono essere serializzate e archiviate per un uso successivo. In questo modo è possibile conservare il contesto della conversazione tra sessioni o chiamate di servizio diverse.

Nei casi in cui la cronologia delle conversazioni viene archiviata in un servizio, il serializzato AgentThread conterrà un ID che punta alla cronologia delle conversazioni nel servizio. Nei casi in cui la cronologia delle conversazioni viene gestita in memoria, il serializzato AgentThread conterrà i messaggi stessi.

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

Archivi personalizzati dei messaggi

Per i thread in memoria, è possibile fornire un'implementazione personalizzata dell'archivio messaggi per controllare la modalità di archiviazione e recupero dei messaggi:

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

Relazione Agent/AgentThread

Agents sono senza stato e la stessa istanza dell'agente può essere usata con più AgentThread istanze.

Non tutti gli agenti supportano però tutti i AgentThread tipi. Ad esempio, se si usa un ChatAgent con il servizio Risposte OpenAI e store=True, AgentThread le istanze usate da questo agente non funzioneranno con un ChatAgent usando il servizio Azure AI Agent. Ciò è dovuto al fatto che questi servizi supportano il salvataggio della cronologia delle conversazioni nel servizio e mentre le due AgentThread istanze avranno riferimenti a ogni conversazione archiviata del servizio, l'ID del servizio Risposte OpenAI non può essere usato con il servizio Foundry Agent e viceversa.

È pertanto considerato non sicuro usare un'istanza AgentThread creata da un agente con un'istanza dell'agente diversa, a meno che non si sia a conoscenza del modello di threading sottostante e delle relative implicazioni.

Esempio pratico a più turni

Ecco un esempio completo che illustra come mantenere il contesto tra più interazioni:

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