Ügynök csevegési előzményei és memóriája

Az ügynök csevegési előzményei és memóriája kulcsfontosságú képességek, amelyek lehetővé teszik az ügynökök számára a beszélgetések kontextusának fenntartását, a felhasználói beállítások megjegyzését és a személyre szabott élmény biztosítását. Az Ügynök-keretrendszer több funkciót is kínál a különböző használati esetekhez, az egyszerű memóriabeli csevegőüzenet-tárolótól kezdve az állandó adatbázisokig és a speciális memóriaszolgáltatásokig.

Csevegési előzmények

Az Agent Framework számos csevegési előzménytárolási lehetőséget támogat. Az elérhető lehetőségek az ügynök típusa és az ügynök létrehozásához használt mögöttes szolgáltatás(ok) szerint változnak.

A két fő támogatott forgatókönyv a következő:

• Memóriabeli tárolás: Az ügynök olyan szolgáltatásra épül, amely nem támogatja a csevegési előzmények szolgáltatáson belüli tárolását (például OpenAI-csevegés befejezése). Az Agent Framework alapértelmezés szerint a teljes csevegési előzményt a memóriában tárolja az AgentThread objektumban, de a fejlesztők egyéni ChatMessageStore implementációt biztosíthatnak a csevegési előzmények külső tárolókban való tárolásához, ha szükséges.
• Szolgáltatáson belüli tárolás: Az ügynök olyan szolgáltatásra épül, amely a csevegési előzmények (például az Azure AI Foundry állandó ügynökei) szolgáltatáson belüli tárolását igényli. Az Agent Framework az objektumban AgentThread tárolja a távoli csevegési előzmények azonosítóját, és más csevegési előzmények tárolási beállításai nem támogatottak.

Memóriabeli csevegési előzmények tárolója

Ha olyan szolgáltatást használ, amely nem támogatja a csevegési előzmények szolgáltatáson belüli tárolását, az Agent Framework alapértelmezés szerint a csevegési előzmények memóriában való tárolására szolgál az AgentThread objektumban. Ebben az esetben a szálobjektumban tárolt teljes csevegési előzményeket, valamint az új üzeneteket minden ügynökfuttatáskor a mögöttes szolgáltatás megkapja. Ez a kialakítás természetes beszélgetési élményt tesz lehetővé az ügynökkel. A hívó csak az új felhasználói üzenetet adja meg, az ügynök pedig csak új válaszokat ad vissza. Az ügynök azonban hozzáfér a teljes beszélgetési előzményekhez, és a válasz létrehozásakor fogja használni.

Ha az OpenAI-csevegés befejezését használja az ügynökök mögöttes szolgáltatásaként, az alábbi kód azt a szálobjektumot eredményezi, amely az ügynök futásából származó csevegési előzményeket tartalmazza.

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

Ha az üzenetek a memóriában vannak tárolva, lekérheti az üzenetek listáját a szálról, és szükség esetén közvetlenül módosíthatja az üzeneteket.

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

Megjegyzés:

Az üzeneteknek az AgentThread objektumból való lekérése így csak akkor működik, ha memóriabeli tárolót használ.

Csevegési előzmények csökkentése a memóriában tárolt tárterülettel

Az alapértelmezés szerint használt beépített InMemoryChatMessageStore , ha a mögöttes szolgáltatás nem támogatja a szolgáltatáson belüli tárolást, a csevegőelőzmények méretének kezelésére egy redukátorsal konfigurálható. Ez azért hasznos, hogy ne lépje túl a mögöttes szolgáltatás környezeti méretkorlátját.

A InMemoryChatMessageStore csevegési előzmények méretének csökkentéséhez szükség van egy opcionális Microsoft.Extensions.AI.IChatReducer implementációra. Azt is lehetővé teszi, hogy konfigurálja azt az eseményt, amely során a redukáló meghívásra kerül, vagy egy üzenet hozzáadása után a csevegési előzményekhez, vagy mielőtt a rendszer visszaadja a csevegési előzményeket a következő meghíváshoz.

A reduktor konfigurálásához InMemoryChatMessageStore biztosíthatja a gyárnak, hogy minden újhoz InMemoryChatMessageStore újat AgentThread hozzon létre, és egy tetszőleges reduktort adjon át neki. A InMemoryChatMessageStore rendszer átadhat egy opcionális eseményindító eseményt is, amely a következőre állítható be: InMemoryChatMessageStore.ChatReducerTriggerEvent.AfterMessageAddedInMemoryChatMessageStore.ChatReducerTriggerEvent.BeforeMessagesRetrievalvagy.

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

Megjegyzés:

Ez a funkció csak InMemoryChatMessageStorea . Ha egy szolgáltatás rendelkezik szolgáltatáson belüli csevegési előzmények tárolóval, a szolgáltatáson múlik a csevegési előzmények méretének kezelése. Hasonlóképpen, ha külső tárolót használ (lásd alább), a harmadik féltől származó tárolási megoldáson múlik a csevegési előzmények méretének kezelése. Ha egy üzenettárolót ad meg ChatMessageStoreFactory , de beépített csevegési előzményeket tartalmazó szolgáltatást használ, a rendszer nem használja a gyárat.

Következtetési szolgáltatás csevegési előzményeinek tárolása

Ha olyan szolgáltatást használ, amely a csevegési előzmények szolgáltatáson belüli tárolását igényli, az Agent Framework az objektumban AgentThread tárolja a távoli csevegési előzmények azonosítóját.

Ha például az OpenAI-válaszok store=true értéket használnak az ügynökök alapjául szolgáló szolgáltatásként, az alábbi kód azt a szálobjektumot eredményezi, amely a szolgáltatás által visszaadott utolsó válaszazonosítót tartalmazza.

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

Megjegyzés:

Egyes szolgáltatások, például az OpenAI-válaszok támogatják a csevegési előzmények szolgáltatáson belüli tárolását (store=true), vagy az egyes meghívások teljes csevegési előzményeit (store=false). Ezért a szolgáltatás által használt módtól függően az Agent Framework alapértelmezés szerint a teljes csevegési előzményt tárolja a memóriában, vagy a szolgáltatás által tárolt csevegési előzményekre mutató azonosító-hivatkozást tárol.

Külső csevegési előzmények tárolója

Ha olyan szolgáltatást használ, amely nem támogatja a csevegési előzmények szolgáltatáson belüli tárolását, az Agent Framework lehetővé teszi a fejlesztők számára, hogy a csevegési előzmények alapértelmezett memóriabeli tárolóját lecserélik a külső csevegési előzmények tárolójára. A fejlesztőnek meg kell adnia az alap absztrakt ChatMessageStore osztály alosztályát.

Az ChatMessageStore osztály határozza meg a csevegőüzenetek tárolására és beolvasására szolgáló felületet. A fejlesztőknek implementálniuk kell azokat a AddMessagesAsync módszereket és GetMessagesAsync módszereket, amelyek lehetővé teszik az üzenetek távoli tárolóba való felvételét a létrehozásukkor, és az alapul szolgáló szolgáltatás meghívása előtt le kell kérniük az üzeneteket a távoli tárolóból.

Az ügynök a felhasználói lekérdezés feldolgozásakor visszaadott GetMessagesAsync összes üzenetet fogja használni. A megvalósító ChatMessageStore feladata annak biztosítása, hogy a csevegési előzmények mérete ne lépje túl a mögöttes szolgáltatás környezeti ablakát.

Ha olyan egyénit ChatMessageStore implementál, amely egy távoli áruházban tárolja a csevegési előzményeket, az adott szál csevegési előzményeit az adott szálon egyedi kulcs alatt kell tárolni. Az ChatMessageStore implementációnak létre kell hoznia ezt a kulcsot, és meg kell őriznie az állapotát. ChatMessageStore olyan metódussal Serialize rendelkezik, amely felülírható az állapot szerializálásához a szál szerializálásakor. A ChatMessageStore konstruktornak olyan konstruktort is biztosítania kell, amely bemenetként használja JsonElement az állapot deszerializálását.

Ha egyénit ChatMessageStore szeretne megadni egy ChatClientAgentügynökhöz, az ügynök létrehozásakor használhatja ezt ChatMessageStoreFactory a lehetőséget. Íme egy példa, amely bemutatja, hogyan adhatja át az egyéni implementációt ChatMessageStore egy ChatClientAgent Azure OpenAI-csevegés befejezésén alapulónak.

AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
    .GetChatClient(deploymentName)
    .CreateAIAgent(new ChatClientAgentOptions
    {
        Name = JokerName,
        ChatOptions = new() { 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);
        }
    });

Jótanács

Az egyéni üzenettárolók létrehozásáról részletes példát a Csevegési előzmények tárolása külső tárolóban oktatóanyagban talál.

Hosszú távú memória

Az Ügynök-keretrendszer lehetővé teszi a fejlesztők számára, hogy olyan egyéni összetevőket biztosítsanak, amelyek memóriákat nyerhetnek ki, vagy emlékeket biztosíthatnak egy ügynöknek.

Egy ilyen memóriaösszetevő implementálásához a fejlesztőnek alá kell sorolnia az AIContextProvider absztrakt alaposztályt. Ez az osztály két alapvető metódust InvokingAsync és InvokedAsync. Felül bírálat InvokedAsync esetén a fejlesztők megvizsgálhatják a felhasználók által biztosított vagy az ügynök által létrehozott összes üzenetet. InvokingAsync lehetővé teszi a fejlesztők számára, hogy további környezetet injektáljanak egy adott ügynök futtatásához. Rendszerutasításokat, további üzeneteket és további függvényeket is megadhat.

Jótanács

Az egyéni memóriaösszetevők létrehozásának részletes példáját a Memória hozzáadása ügynökhöz oktatóanyagban találja.

AgentThread szerializálás

Fontos, hogy egy objektumot meg lehessen őrizni az AgentThread ügynökhívások között. Ez lehetővé teszi azokat a helyzeteket, amikor egy felhasználó kérdést tehet fel az ügynökkel kapcsolatban, és hosszú időt vesz igénybe az utánkövetési kérdések feltevése. Ez lehetővé teszi, hogy az AgentThread állapot túlélje a szolgáltatás vagy az alkalmazás újraindítását.

Még akkor is, ha a csevegési előzményeket egy távoli tároló tárolja, az AgentThread objektum továbbra is tartalmaz egy azonosítót, amely a távoli csevegési előzményekre hivatkozik. AgentThread Az állapot elvesztése ezért a távoli csevegési előzmények azonosítójának elvesztését is eredményezi.

A AgentThread csakúgy, mint a hozzá csatolt objektumok mind biztosítják az SerializeAsync állapotuk szerializálásának módját. Ez AIAgent egy metódust DeserializeThread is biztosít, amely újra létrehozza a szálat a szerializált állapotból. A DeserializeThread metódus újra létrehozza a szálat az ChatMessageStore ügynökkel és AIContextProvider konfigurálva.

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

Megjegyzés:

AgentThread az objektumok nem csak csevegési előzményeket tartalmazhatnak, például a környezetszolgáltatók is tárolhatják az állapotot a szálobjektumban. Ezért fontos, hogy mindig szerializálja, tárolja és deszerializálja a teljes AgentThread objektumot, hogy minden állapot megmaradjon.

Fontos

Az objektumokat mindig átlátszatlan objektumként kezelje AgentThread , hacsak nem biztos a belső beállításokban. A tartalom nem csak az ügynök típusa, hanem a szolgáltatás típusa és konfigurációja szerint is változhat.

Figyelmeztetés

Ha egy szálat más ügynökkel deszerializál, mint amelyik eredetileg létrehozta, vagy egy olyan ügynökkel, amely más konfigurációval rendelkezik, mint az eredeti ügynök, hibákhoz vagy váratlan viselkedéshez vezethet.

Memóriatípusok

Az Agent Framework számos típusú memóriát támogat a különböző használati esetek kezeléséhez, beleértve a csevegési előzmények rövid távú memória részeként történő kezelését, valamint bővítménypontokat biztosít a hosszú távú memóriák ügynökökbe való kinyeréséhez, tárolásához és beadásához.

In-Memory Storage (alapértelmezett)

A legegyszerűbb memóriaforma, amelyben a beszélgetési előzmények a memóriában vannak tárolva az alkalmazás futásideje során. Ez az alapértelmezett viselkedés, és nem igényel további konfigurációt.

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)

Állandó üzenettárolók

Az olyan alkalmazások esetében, amelyeknek a beszélgetések előzményeit a munkamenetek során meg kell őrizni, a keretrendszer implementációkat biztosít ChatMessageStore :

Beépített ChatMessageStore

A memórián belüli alapértelmezett implementáció, amely szerializálható:

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 Üzenettár

Állandó tárolást igénylő éles alkalmazások esetén:

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
)

Egyéni üzenettároló

A saját háttérrendszerét a következő implementálásával ChatMessageStoreProtocolimplementálhatja:

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

Jótanács

Az egyéni üzenettárolók létrehozásáról részletes példát a Csevegési előzmények tárolása külső tárolóban oktatóanyagban talál.

Környezetszolgáltatók (dinamikus memória)

A környezetszolgáltatók kifinomult memóriamintákat tesznek lehetővé azáltal, hogy a megfelelő környezetet injektálják az egyes ügynökök meghívása előtt:

Alapszintű környezetszolgáltató

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

Jótanács

Az egyéni memóriaösszetevők létrehozásának részletes példáját a Memória hozzáadása ügynökhöz oktatóanyagban találja.

Külső memóriaszolgáltatások

A keretrendszer támogatja az olyan speciális memóriaszolgáltatások integrációját, mint a 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
)

Szál szerializálása és megőrzése

A keretrendszer támogatja a teljes szálállapotok szerializálását az alkalmazás újraindításai közötti adatmegőrzés érdekében:

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)

Következő lépések

Ügynökeszközök