Paměť agenta

Paměť agenta je zásadní schopnost, která umožňuje agentům udržovat kontext napříč konverzacemi, pamatovat si uživatelské předvolby a poskytovat přizpůsobené prostředí. Rozhraní Agent Framework poskytuje několik mechanismů paměti, které vyhovují různým případům použití, od jednoduchého úložiště v paměti až po trvalé databáze a specializované paměťové služby.

Agent Framework podporuje několik typů paměti pro různé případy použití, včetně správy historie chatu v rámci krátkodobé paměti a poskytování rozšiřujících bodů pro extrakci, ukládání a vkládání dlouhodobých pamětí do agentů.

Historie chatu (krátkodobá paměť)

Rozhraní agenta podporuje různé možnosti úložiště historie chatu. Dostupné možnosti se liší podle typu agenta a podkladových služeb použitých k sestavení agenta.

Tady jsou podporované dva hlavní scénáře:

Úložiště v paměti: Agent je založený na službě, která nepodporuje ukládání historie chatu ve službě (např. Dokončení chatu OpenAI). Agent Framework ve výchozím nastavení uloží úplnou historii chatu do paměti objektu AgentThread , ale vývojáři můžou poskytnout vlastní ChatMessageStore implementaci pro ukládání historie chatu do úložiště třetích stran v případě potřeby.
Úložiště ve službě: Agent je založený na službě, která vyžaduje ukládání historie chatu v provozu (např. trvalé agenty Azure AI Foundry). Rozhraní Agent Framework uloží ID historie vzdáleného chatu v objektu a nebudou AgentThread podporovány žádné další možnosti úložiště historie chatu.

Úložiště historie chatu v paměti

Pokud používáte službu, která nepodporuje ukládání historie chatu v rámci služby, rozhraní Agent Framework ve výchozím nastavení uloží historii chatu do paměti objektu AgentThread . V tomto případě se základní službě při každém spuštění agenta poskytne úplná historie chatu uložená v objektu vlákna a všechny nové zprávy. To umožňuje přirozené konverzační prostředí s agentem, kde volající jenom poskytuje novou zprávu uživatele a agent vrací jenom nové odpovědi, ale agent má přístup k celé historii konverzací a použije ho při generování odpovědi.

Při použití dokončování chatu OpenAI jako podkladové služby pro agenty způsobí následující kód objekt vlákna obsahující historii chatu ze spuštění agenta.

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

Pokud jsou zprávy uloženy v paměti, je možné načíst seznam zpráv z vlákna a manipulovat se zprávami přímo v případě potřeby.

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

Poznámka:

Načítání zpráv z objektu AgentThread tímto způsobem bude fungovat pouze v případě, že se používá úložiště v paměti.

Snížení historie chatu s úložištěm In-Memory

Integrovaná služba InMemoryChatMessageStore , která se ve výchozím nastavení používá v případě, že podkladová služba nepodporuje úložiště v rámci služby, je možné nakonfigurovat s redukčním nástrojem pro správu velikosti historie chatu. To je užitečné, abyste se vyhnuli překročení limitů velikosti kontextu základní služby.

Volitelná InMemoryChatMessageStoreMicrosoft.Extensions.AI.IChatReducer implementace může snížit velikost historie chatu. Umožňuje také nakonfigurovat událost, během které se reduktor vyvolá, a to buď po přidání zprávy do historie chatu, nebo před vrácením historie chatu pro další vyvolání.

Pokud chcete nakonfigurovat InMemoryChatMessageStore redukční nástroj, můžete poskytnout továrnu pro vytvoření nového pro každý nový InMemoryChatMessageStoreAgentThread a předat ho redukčnímu nástroji podle vašeho výběru. Lze InMemoryChatMessageStore také předat volitelnou aktivační událost, která může být nastavena na buď InMemoryChatMessageStore.ChatReducerTriggerEvent.AfterMessageAdded nebo 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)
    });

Poznámka:

Tato funkce je podporována pouze při použití funkce InMemoryChatMessageStore. Pokud má služba úložiště historie chatu v rámci služby, je na samotné službě, aby spravovala velikost historie chatu. Podobně platí, že pokud používáte úložiště třetích stran (viz níže), je to řešení úložiště třetí strany, které spravuje velikost historie chatu. Pokud zadáte ChatMessageStoreFactory úložiště zpráv, ale použijete službu s integrovaným úložištěm historie chatu, továrna se nepoužije.

Úložiště historie chatu služby odvození

Pokud používáte službu, která vyžaduje ukládání historie chatu v rámci služby, rozhraní Agent Framework uloží ID historie vzdáleného chatu v objektu AgentThread .

Například při použití odpovědí OpenAI s úložištěm =true jako podkladovou službou pro agenty způsobí následující kód objekt vlákna obsahující poslední ID odpovědi vrácené službou.

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

Poznámka:

Některé služby, například odpovědi OpenAI, podporují buď úložiště historie chatu ve službě (store=true), nebo poskytují úplnou historii chatu při každém vyvolání (store=false). Proto v závislosti na režimu, ve které se služba používá, rozhraní Agent Framework buď ve výchozím nastavení uloží úplnou historii chatu do paměti, nebo uloží id odkaz na uloženou historii chatu služby.

Úložiště historie chatů třetích stran

Při použití služby, která nepodporuje ukládání historie chatu v rámci služby, umožňuje rozhraní Agent Framework vývojářům nahradit výchozí úložiště historie chatu v paměti úložištěm historie chatu třetí strany. Vývojář musí poskytnout podtřídu základní abstraktní ChatMessageStore třídy.

Třída ChatMessageStore definuje rozhraní pro ukládání a načítání chatových zpráv. Vývojáři musí implementovat a AddMessagesAsyncGetMessagesAsync metody pro přidání zpráv do vzdáleného úložiště při jejich generování a načtení zpráv ze vzdáleného úložiště před vyvoláním základní služby.

Agent použije všechny zprávy vrácené GetMessagesAsync při zpracování uživatelského dotazu. Je na implementátoru ChatMessageStore zajistit, aby velikost historie chatu nepřekračovala kontextové okno podkladové služby.

Při implementaci vlastního ChatMessageStore úložiště, který ukládá historii chatu ve vzdáleném úložišti, by se historie chatu pro toto vlákno měla uložit pod klíčem, který je pro toto vlákno jedinečný. Implementace ChatMessageStore by měla tento klíč generovat a udržovat ho ve svém stavu. ChatMessageStore má metodu Serialize , která lze přepsat k serializaci jeho stavu při serializaci vlákna. Měl ChatMessageStore by také poskytnout konstruktor, který jako vstup podporuje JsonElement deserializaci jeho stavu.

Chcete-li zadat vlastní ChatMessageStoreChatClientAgentobjekt , můžete použít ChatMessageStoreFactory možnost při vytváření agenta. Tady je příklad ukazující, jak předat vlastní implementaci do ChatMessageStore chatu založeného na dokončení chatu ChatClientAgent Azure OpenAI.

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

Návod

Podrobný příklad vytvoření vlastního úložiště zpráv najdete v kurzu Ukládání historie chatu v úložišti třetích stran .

Dlouhodobá paměť

Agent Framework umožňuje vývojářům poskytovat vlastní komponenty, které můžou extrahovat vzpomínky nebo poskytovat paměti agentům.

Aby vývojář takovou součást paměti implementoval, musí podtřídu abstraktní základní třídy podtřídy AIContextProvider . Tato třída má dvě základní metody a InvokingAsyncInvokedAsync. Při přepsání InvokedAsync umožňuje vývojářům kontrolovat všechny zprávy poskytované uživateli nebo generované agentem. InvokingAsync umožňuje vývojářům vložit další kontext pro konkrétní spuštění agenta. Můžete zadat systémové pokyny, další zprávy a další funkce.

Návod

Podrobný příklad vytvoření vlastní součásti paměti najdete v kurzu Přidání paměti do agenta .

Serializace AgentThread

Je důležité mít možnost zachovat AgentThread objekt mezi vyvoláním agenta. To umožňuje situace, kdy se uživatel může zeptat agenta, a trvat dlouhou dobu, než se zeptá na další otázky. To umožňuje AgentThread , aby stav přežil služby nebo restartování aplikace.

I když je historie chatu uložená ve vzdáleném úložišti, AgentThread objekt stále obsahuje ID odkazující na historii vzdáleného chatu. AgentThread Ztráta stavu proto způsobí ztrátu ID historie vzdáleného chatu.

Stejně AgentThread jako všechny objekty, které jsou k němu připojeny, proto poskytují metodu SerializeAsync serializace jejich stavu. Poskytuje AIAgent také metodu DeserializeThread , která znovu vytvoří vlákno ze serializovaného stavu. Metoda DeserializeThread znovu vytvoří vlákno s ChatMessageStore a AIContextProvider nakonfigurovaným v agentu.

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

Poznámka:

AgentThread objekty mohou obsahovat více než jen historii chatu, například zprostředkovatelé kontextu mohou také ukládat stav v objektu vlákna. Proto je důležité vždy serializovat, ukládat a deserializovat celý AgentThread objekt, aby se zajistilo, že je zachován veškerý stav.

Důležité

Objekty vždy považují za AgentThread neprůžné, pokud si nejste jisti vnitřními objekty. Obsah se může lišit nejen podle typu agenta, ale také podle typu služby a konfigurace.

Výstraha

Deserializace vlákna s jiným agentem, než který ho původně vytvořil, nebo s agentem, který má jinou konfiguraci než původní agent, může vést k chybám nebo neočekávanému chování.

Typy paměti

In-Memory Storage (výchozí)

Nejjednodušší forma paměti, ve které je historie konverzací uložena v paměti během modulu runtime aplikace. Toto je výchozí chování a nevyžaduje žádnou další konfiguraci.

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)

Trvalé úložiště zpráv

Pro aplikace, které potřebují zachovat historii konverzací napříč relacemi, poskytuje ChatMessageStore architektura implementace:

Integrovaný ChatMessageStore

Výchozí implementace v paměti, kterou lze serializovat:

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
)

Úložiště zpráv Redis

Pro produkční aplikace vyžadující trvalé úložiště:

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
)

Vlastní úložiště zpráv

Vlastní back-end úložiště můžete implementovat implementací :ChatMessageStoreProtocol

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"]

Návod

Podrobný příklad vytvoření vlastního úložiště zpráv najdete v kurzu Ukládání historie chatu v úložišti třetích stran .

Zprostředkovatelé kontextu (dynamická paměť)

Poskytovatelé kontextu umožňují sofistikované vzory paměti vložením relevantního kontextu před vyvolání každého agenta:

Základní zprostředkovatel kontextu

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

Návod

Podrobný příklad vytvoření vlastní součásti paměti najdete v kurzu Přidání paměti do agenta .

Externí paměťové služby

Architektura podporuje integraci se specializovanými paměťovými službami, jako je 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
)

Serializace vláken a trvalost

Architektura podporuje serializaci celých stavů vlákna pro trvalost napříč restartováními aplikace:

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)

Další kroky

Pozorovatelnost agenta

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-10

Sdílet prostřednictvím

Paměť agenta

Historie chatu (krátkodobá paměť)

Úložiště historie chatu v paměti

Snížení historie chatu s úložištěm In-Memory

Úložiště historie chatu služby odvození

Úložiště historie chatů třetích stran

Dlouhodobá paměť

Serializace AgentThread

Typy paměti

In-Memory Storage (výchozí)

Trvalé úložiště zpráv

Integrovaný ChatMessageStore

Úložiště zpráv Redis

Vlastní úložiště zpráv

Zprostředkovatelé kontextu (dynamická paměť)

Základní zprostředkovatel kontextu

Externí paměťové služby

Serializace vláken a trvalost

Další kroky

Váš názor

Další materiály