Agentminne

Minnestyper

Agent Framework stöder flera typer av minne för olika användningsfall, inklusive hantering av chatthistorik som en del av kortsiktigt minne och tillhandahålla tilläggspunkter för att extrahera, lagra och mata in långsiktiga minnen i agenter.

Chatthistorik (korttidsminne)

Olika lagringsalternativ för chatthistorik stöds av Agent Framework. De tillgängliga alternativen varierar beroende på agenttyp och de underliggande tjänster som används för att skapa agenten.

Till exempel när en agent skapas med hjälp av en tjänst som endast stöder lagring av chatthistorik i tjänsten, måste Agent Framework respektera vad tjänsten kräver.

Lagring av minnesintern chatthistorik

När du använder en tjänst som inte stöder lagring i tjänsten av chatthistorik lagrar Agent Framework chatthistorik i minnet i AgentThread objektet som standard. I det här fallet kommer den fullständiga chatthistoriken som lagras i trådobjektet, plus eventuella nya meddelanden, att tillhandahållas till den underliggande tjänsten på varje agentkörning.

När du till exempel använder OpenAI Chat Completion som underliggande tjänst för agenter resulterar följande kod i trådobjektet som innehåller chatthistoriken från agentkörningen.

AIAgent agent = new OpenAIClient("<your_api_key>")
     .GetChatClient(modelName)
     .CreateAIAgent(JokerInstructions, JokerName);
AgentThread thread = agent.GetNewThread();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", thread));

När meddelanden lagras i minnet är det möjligt att hämta listan över meddelanden från tråden och ändra meddelandena direkt om det behövs.

IList<ChatMessage>? messages = thread.GetService<IList<ChatMessage>>();

Minskning av chatthistorik med In-Memory lagring

Den inbyggda InMemoryChatMessageStore som används som standard när den underliggande tjänsten inte stöder lagring i tjänsten kan konfigureras med en reducer för att hantera storleken på chatthistoriken. Detta är användbart för att undvika att överskrida kontextstorleksgränserna för den underliggande tjänsten.

InMemoryChatMessageStore Kan ta en valfri implementering Microsoft.Extensions.AI.IChatReducer för att minska storleken på chatthistoriken. Du kan också konfigurera händelsen under vilken reducern anropas, antingen efter att ett meddelande har lagts till i chatthistoriken eller innan chatthistoriken returneras för nästa anrop.

Om du vill konfigurera InMemoryChatMessageStore med en reducer kan du tillhandahålla en fabrik för att konstruera en ny InMemoryChatMessageStore för varje ny AgentThread och skicka den till valfri reducer. InMemoryChatMessageStore Kan också skickas en valfri utlösarhändelse som kan anges till antingen InMemoryChatMessageStore.ChatReducerTriggerEvent.AfterMessageAdded eller InMemoryChatMessageStore.ChatReducerTriggerEvent.BeforeMessagesRetrieval.

AIAgent agent = new OpenAIClient("<your_api_key>")
    .GetChatClient(modelName)
    .CreateAIAgent(new ChatClientAgentOptions
    {
        Name = JokerName,
        Instructions = JokerInstructions,
        ChatMessageStoreFactory = ctx => new InMemoryChatMessageStore(
            new MessageCountingChatReducer(2),
            ctx.SerializedState,
            ctx.JsonSerializerOptions,
            InMemoryChatMessageStore.ChatReducerTriggerEvent.AfterMessageAdded)
    });

Lagring av inferenstjänstchatthistorik

När du använder en tjänst som kräver lagring i tjänsten av chatthistorik kommer Agent Framework att lagra ID:t för fjärrchatthistoriken AgentThread i objektet.

T.ex. när du använder OpenAI-svar med store=true som den underliggande tjänsten för agenter resulterar följande kod i trådobjektet som innehåller det senaste svars-ID som returnerades av tjänsten.

AIAgent agent = new OpenAIClient("<your_api_key>")
     .GetOpenAIResponseClient(modelName)
     .CreateAIAgent(JokerInstructions, JokerName);
AgentThread thread = agent.GetNewThread();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", thread));

Lagring av chatthistorik från tredje part

När du använder en tjänst som inte stöder lagring i tjänsten av chatthistorik tillåter Agent Framework utvecklare att ersätta standardlagringen i minnet av chatthistoriken med lagring av chatthistorik från tredje part. Utvecklaren måste tillhandahålla en underklass av den grundläggande abstrakta ChatMessageStore klassen.

Klassen ChatMessageStore definierar gränssnittet för att lagra och hämta chattmeddelanden. Utvecklare måste implementera AddMessagesAsync metoderna och GetMessagesAsync för att lägga till meddelanden i fjärrarkivet när de genereras och hämta meddelanden från fjärrarkivet innan de anropar den underliggande tjänsten.

Agenten använder alla meddelanden som returneras av GetMessagesAsync när en användarfråga bearbetas. Det är upp till implementeraren att ChatMessageStore se till att storleken på chatthistoriken inte överskrider kontextfönstret för den underliggande tjänsten.

När du implementerar en anpassad ChatMessageStore som lagrar chatthistorik i en fjärrbutik bör chatthistoriken för den tråden lagras under en nyckel som är unik för den tråden. Implementeringen ChatMessageStore bör generera den här nyckeln och behålla den i sitt tillstånd. ChatMessageStore har en Serialize metod som kan åsidosättas för att serialisera dess tillstånd när tråden serialiseras. ChatMessageStore Bör också tillhandahålla en konstruktor som tar en JsonElement som indata för att stödja deserialisering av dess tillstånd.

Om du vill ange en anpassad ChatMessageStore till en ChatClientAgentkan du använda ChatMessageStoreFactory alternativet när du skapar agenten. Här är ett exempel som visar hur du skickar den anpassade implementeringen av till en ChatMessageStore som baseras på Slutförande av ChatClientAgent Azure OpenAI-chatt.

AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
         Name = JokerName,
         Instructions = JokerInstructions,
         ChatMessageStoreFactory = ctx =>
         {
             // Create a new chat message store for this agent that stores the messages in a custom store.
             // Each thread must get its own copy of the CustomMessageStore, since the store
             // also contains the id that the thread is stored under.
             return new CustomMessageStore(vectorStore, ctx.SerializedState, ctx.JsonSerializerOptions);
         }
     });

Långtidsminne

Med Agent Framework kan utvecklare tillhandahålla anpassade komponenter som kan extrahera minnen eller tillhandahålla minnen till en agent.

För att implementera en sådan minneskomponent måste utvecklaren underklassa den AIContextProvider abstrakta basklassen. Den här klassen har två kärnmetoder och InvokingAsyncInvokedAsync. När de är åsidosatta InvokedAsync kan utvecklare inspektera alla meddelanden som tillhandahålls av användare eller genereras av agenten. InvokingAsync gör att utvecklare kan mata in ytterligare kontext för en specifik agentkörning. Systeminstruktioner, ytterligare meddelanden och ytterligare funktioner kan tillhandahållas.

AgentThread Serialization

Det är viktigt att kunna bevara ett AgentThread objekt mellan agentanrop. Detta möjliggör situationer där en användare kan ställa en fråga till agenten och ta lång tid på sig att ställa uppföljningsfrågor. På så AgentThread sätt kan tillståndet överleva att tjänsten eller appen startas om.

Även om chatthistoriken lagras i ett fjärrarkiv AgentThread innehåller objektet fortfarande ett ID som refererar till fjärrchatthistoriken. Om du AgentThread förlorar tillståndet förlorar du därför även ID:t för fjärrchatthistoriken.

Förutom AgentThread alla objekt som är kopplade till den tillhandahåller SerializeAsync alla därför metoden för att serialisera deras tillstånd. Innehåller AIAgent också en DeserializeThread metod som återskapar en tråd från det serialiserade tillståndet. Metoden DeserializeThread återskapar tråden ChatMessageStore med och AIContextProvider konfigurerad på agenten.

// Serialize the thread state to a JsonElement, so it can be stored for later use.
JsonElement serializedThreadState = thread.Serialize();

// Re-create the thread from the JsonElement.
AgentThread resumedThread = AIAgent.DeserializeThread(serializedThreadState);

Minnestyper

Agent Framework stöder flera typer av minne för olika användningsfall, inklusive hantering av chatthistorik som en del av kortsiktigt minne och tillhandahålla tilläggspunkter för att extrahera, lagra och mata in långsiktiga minnen i agenter.

In-Memory Storage (standard)

Den enklaste formen av minne där konversationshistorik lagras i minnet under programkörningen. Detta är standardbeteendet och kräver ingen ytterligare konfiguration.

from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient

# Default behavior - uses in-memory storage
agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant."
)

# Conversation history is maintained in memory for this thread
thread = agent.get_new_thread()

response = await agent.run("Hello, my name is Alice", thread=thread)

Beständiga meddelandelager

För program som behöver bevara konversationshistoriken mellan sessioner tillhandahåller ChatMessageStore ramverket implementeringar:

Inbyggd ChatMessageStore

Standardimplementeringen i minnet som kan serialiseras:

from agent_framework import ChatMessageStore

# Create a custom message store
def create_message_store():
    return ChatMessageStore()

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant.",
    chat_message_store_factory=create_message_store
)

Redis-meddelandearkiv

För produktionsprogram som kräver beständig lagring:

from agent_framework.redis import RedisChatMessageStore

def create_redis_store():
    return RedisChatMessageStore(
        redis_url="redis://localhost:6379",
        thread_id="user_session_123",
        max_messages=100  # Keep last 100 messages
    )

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant.",
    chat_message_store_factory=create_redis_store
)

Anpassat meddelandearkiv

Du kan implementera din egen lagringsserverdel genom att ChatMessageStoreProtocolimplementera :

from agent_framework import ChatMessage, ChatMessageStoreProtocol
from typing import Any
from collections.abc import Sequence

class DatabaseMessageStore(ChatMessageStoreProtocol):
    def __init__(self, connection_string: str):
        self.connection_string = connection_string
        self._messages: list[ChatMessage] = []

    async def add_messages(self, messages: Sequence[ChatMessage]) -> None:
        """Add messages to database."""
        # Implement database insertion logic
        self._messages.extend(messages)

    async def list_messages(self) -> list[ChatMessage]:
        """Retrieve messages from database."""
        # Implement database query logic
        return self._messages

    async def serialize(self, **kwargs: Any) -> Any:
        """Serialize store state for persistence."""
        return {"connection_string": self.connection_string}

    async def update_from_state(self, serialized_store_state: Any, **kwargs: Any) -> None:
        """Update store from serialized state."""
        if serialized_store_state:
            self.connection_string = serialized_store_state["connection_string"]

Kontextprovidrar (dynamiskt minne)

Kontextprovidrar möjliggör avancerade minnesmönster genom att mata in relevant kontext före varje agentanrop:

Grundläggande kontextprovider

from agent_framework import ContextProvider, Context, ChatMessage
from collections.abc import MutableSequence
from typing import Any

class UserPreferencesMemory(ContextProvider):
    def __init__(self):
        self.preferences = {}

    async def invoking(self, messages: ChatMessage | MutableSequence[ChatMessage], **kwargs: Any) -> Context:
        """Provide user preferences before each invocation."""
        if self.preferences:
            preferences_text = ", ".join([f"{k}: {v}" for k, v in self.preferences.items()])
            instructions = f"User preferences: {preferences_text}"
            return Context(instructions=instructions)
        return Context()

    async def invoked(
        self,
        request_messages: ChatMessage | Sequence[ChatMessage],
        response_messages: ChatMessage | Sequence[ChatMessage] | None = None,
        invoke_exception: Exception | None = None,
        **kwargs: Any,
    ) -> None:
        """Extract and store user preferences from the conversation."""
        # Implement preference extraction logic
        pass

Externa minnestjänster

Ramverket stöder integrering med specialiserade minnestjänster som Mem0:

from agent_framework.mem0 import Mem0Provider

# Using Mem0 for advanced memory capabilities
memory_provider = Mem0Provider(
    api_key="your-mem0-api-key",
    user_id="user_123",
    application_id="my_app"
)

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant with memory.",
    context_providers=memory_provider
)

Trådserialisering och beständighet

Ramverket stöder serialisering av hela trådtillstånd för beständighet mellan programomstarter:

import json

# Create agent and thread
agent = ChatAgent(chat_client=OpenAIChatClient())
thread = agent.get_new_thread()

# Have conversation
await agent.run("Hello, my name is Alice", thread=thread)

# Serialize thread state
serialized_thread = await thread.serialize()
# Save to file/database
with open("thread_state.json", "w") as f:
    json.dump(serialized_thread, f)

# Later, restore the thread
with open("thread_state.json", "r") as f:
    thread_data = json.load(f)

restored_thread = await agent.deserialize_thread(thread_data)
# Continue conversation with full context
await agent.run("What's my name?", thread=restored_thread)