Microsoft Agent Framework-konversationer med flera turer och konversationstrådning

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

Microsoft Agent Framework har inbyggt stöd för att hantera konversationer med flera turer med AI-agenter. Detta inkluderar att upprätthålla kontext över flera interaktioner. Olika agenttyper och underliggande tjänster som används för att skapa agenter kan ha stöd för olika trådtyper, och Agent Framework abstraherar bort dessa skillnader, vilket ger ett konsekvent gränssnitt för utvecklare.

När du till exempel använder en ChatAgent baserad på en Foundry-agent sparas konversationshistoriken i tjänsten. När du använder en ChatAgent baserad på chattkomplettering med gpt-4 lagras konversationshistoriken i minnet och hanteras av agenten.

Skillnaderna mellan de underliggande trådmodellerna abstraheras bort via AgentThread typen .

Agent-/AgentTrådrelation

AIAgent instanser är tillståndslösa och samma agentinstans kan användas med flera AgentThread instanser.

Alla agenter stöder dock inte alla trådtyper. Om du till exempel använder en ChatClientAgent tillsammans med svarstjänsten, kommer AgentThread instanser som skapats av den här agenten inte att fungera med en ChatClientAgent som använder Foundry Agent-tjänsten. Det beror på att båda tjänsterna stöder att spara konversationshistoriken inom tjänsten, och har bara en referens till den här tjänsthanterade tråden.

Det anses därför vara osäkert att använda en AgentThread instans som har skapats av en agent med en annan agentinstans, såvida du inte känner till den underliggande trådningsmodellen och dess konsekvenser.

Trådstöd per tjänst/protokoll

AgentThread-skapelse

AgentThread instanser kan skapas på två sätt:

1. Genom att anropa agenten med get_new_thread().
2. Genom att köra agenten och inte ange en AgentThread. I det här fallet skapar agenten en tillfällig AgentThread med en underliggande tråd som endast kommer att användas under körningen.

Vissa underliggande trådar kan skapas beständigt i en underliggande tjänst, där tjänsten kräver detta, t.ex. Azure AI-agenter eller OpenAI-svar. Alla rensningar eller borttagningar av dessa trådar är användarens ansvar.

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

AgentThread Storage

AgentThread instanser kan serialiseras och lagras för senare användning. Detta gör det möjligt att bevara konversationskontexten mellan olika sessioner eller tjänstanrop.

För fall där konversationshistoriken lagras i en tjänst innehåller serialiserade AgentThread ett ID för tråden i tjänsten. För de fall där konversationshistoriken hanteras i minnet, kommer den serialiserade AgentThread att innehålla själva meddelandena.

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

Anpassade meddelandelager

För minnesinterna trådar kan du tillhandahålla en anpassad implementering av meddelandearkivet för att styra hur meddelanden lagras och hämtas:

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

Agent-/AgentTrådrelation

Agents är tillståndslösa och samma agentinstans kan användas med flera AgentThread instanser.

Alla agenter stöder dock inte alla trådtyper. Om du till exempel använder en ChatAgent med tjänsten OpenAI Responses, kommer store=True och AgentThread-instanser som utnyttjas av denna agent inte att fungera korrekt med en ChatAgent som använder Azure AI Agent-tjänsten, eftersom thread_ids inte är kompatibla.

Det anses därför vara osäkert att använda en AgentThread instans som har skapats av en agent med en annan agentinstans, såvida du inte känner till den underliggande trådningsmodellen och dess konsekvenser.

Praktiskt exempel med flera omgångar

Här är ett fullständigt exempel som visar hur du underhåller kontext över flera interaktioner:

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