Bagikan melalui

Riwayat dan Memori Obrolan Agen

Riwayat obrolan agen dan memori adalah kemampuan penting yang memungkinkan agen mempertahankan konteks di seluruh percakapan, mengingat preferensi pengguna, dan memberikan pengalaman yang dipersonalisasi. Kerangka Kerja Agen menyediakan beberapa fitur agar sesuai dengan kasus penggunaan yang berbeda, dari penyimpanan pesan obrolan dalam memori sederhana hingga database persisten dan layanan memori khusus.

Riwayat Obrolan

Berbagai opsi penyimpanan riwayat obrolan didukung oleh Agent Framework. Opsi yang tersedia bervariasi menurut jenis agen dan layanan yang mendasar yang digunakan untuk membangun agen.

Dua skenario utama yang didukung adalah:

  • Penyimpanan dalam memori: Agen dibangun di atas layanan yang tidak mendukung penyimpanan riwayat obrolan dalam layanan (misalnya, Penyelesaian Obrolan OpenAI). Secara default, Agent Framework menyimpan riwayat obrolan lengkap dalam memori dalam AgentSession objek, tetapi pengembang dapat menyediakan implementasi kustom ChatHistoryProvider untuk menyimpan riwayat obrolan di penyimpanan pihak ketiga jika diperlukan.
  • Penyimpanan dalam layanan: Agen dibangun di atas layanan yang memerlukan penyimpanan riwayat obrolan dalam layanan (misalnya, Agen Persisten Azure AI Foundry). Agent Framework menyimpan ID riwayat obrolan jarak jauh di AgentSession objek, dan tidak ada opsi penyimpanan riwayat obrolan lainnya yang didukung.

Penyimpanan riwayat obrolan dalam memori

Saat menggunakan layanan yang tidak mendukung penyimpanan riwayat obrolan dalam layanan, Agent Framework default untuk menyimpan riwayat obrolan dalam memori di AgentSession objek. Dalam hal ini, riwayat obrolan lengkap yang disimpan dalam objek sesi, ditambah pesan baru apa pun, akan diberikan kepada layanan yang mendasari pada setiap agen yang dijalankan. Desain ini memungkinkan pengalaman percakapan alami dengan agen. Pemanggil hanya menyediakan pesan pengguna baru, dan agen hanya mengembalikan jawaban baru. Tetapi agen memiliki akses ke riwayat percakapan lengkap dan akan menggunakannya saat menghasilkan responsnya.

Saat menggunakan OpenAI Chat Completion sebagai layanan yang mendasari untuk agen, kode berikut menghasilkan objek sesi yang berisi riwayat obrolan dari agen yang dijalankan.

AIAgent agent = new OpenAIClient("<your_api_key>")
     .GetChatClient(modelName)
     .AsAIAgent(JokerInstructions, JokerName);
AgentSession session = await agent.GetNewSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));

Di mana pesan disimpan dalam memori, dimungkinkan untuk mengambil daftar pesan dari sesi dan memanipulasi pesan secara langsung jika diperlukan.

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

Nota

Mengambil pesan dari objek dengan AgentSession cara ini hanya berfungsi jika penyimpanan dalam memori sedang digunakan.

Pengurangan riwayat obrolan dengan penyimpanan dalam memori

Bawaan yang digunakan secara default ketika layanan yang mendasar tidak mendukung penyimpanan dalam layanan, dapat dikonfigurasi InMemoryChatHistoryProvider dengan peredam untuk mengelola ukuran riwayat obrolan. Ini berguna untuk menghindari melebihi batas ukuran konteks layanan yang mendasarinya.

InMemoryChatHistoryProvider dapat mengambil implementasi opsional Microsoft.Extensions.AI.IChatReducer untuk mengurangi ukuran riwayat obrolan. Ini juga memungkinkan Anda untuk mengonfigurasi peristiwa di mana peredam dipanggil, baik setelah pesan ditambahkan ke riwayat obrolan atau sebelum riwayat obrolan dikembalikan untuk pemanggilan berikutnya.

Untuk mengonfigurasi InMemoryChatHistoryProvider dengan peredam, Anda dapat menyediakan pabrik untuk membuat baru InMemoryChatHistoryProvider untuk setiap yang baru AgentSession dan meneruskannya sebagai peredam pilihan Anda. juga InMemoryChatHistoryProvider dapat diteruskan peristiwa pemicu opsional yang dapat diatur ke InMemoryChatHistoryProvider.ChatReducerTriggerEvent.AfterMessageAdded atau InMemoryChatHistoryProvider.ChatReducerTriggerEvent.BeforeMessagesRetrieval.

Pabrik adalah fungsi asinkron yang menerima objek konteks dan token pembatalan.

AIAgent agent = new OpenAIClient("<your_api_key>")
    .GetChatClient(modelName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = JokerName,
        ChatOptions = new() { Instructions = JokerInstructions },
        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(
            new InMemoryChatHistoryProvider(
                new MessageCountingChatReducer(2),
                ctx.SerializedState,
                ctx.JsonSerializerOptions,
                InMemoryChatHistoryProvider.ChatReducerTriggerEvent.AfterMessageAdded))
    });

Nota

Fitur ini hanya didukung saat menggunakan InMemoryChatHistoryProvider. Ketika layanan memiliki penyimpanan riwayat obrolan dalam layanan, terserah layanan itu sendiri untuk mengelola ukuran riwayat obrolan. Demikian pula, saat menggunakan penyimpanan pihak ke-3 (lihat di bawah), terserah solusi penyimpanan pihak ke-3 untuk mengelola ukuran riwayat obrolan. Jika Anda menyediakan ChatHistoryProviderFactory untuk penyedia riwayat obrolan tetapi Anda menggunakan layanan dengan penyimpanan riwayat obrolan bawaan, pabrik tidak akan digunakan.

Penyimpanan riwayat obrolan layanan inferensi

Saat menggunakan layanan yang memerlukan penyimpanan riwayat obrolan dalam layanan, Agent Framework menyimpan ID riwayat obrolan jarak jauh di AgentSession objek.

Misalnya, saat menggunakan Respons OpenAI dengan store=true sebagai layanan yang mendasari untuk agen, kode berikut akan menghasilkan objek sesi yang berisi ID respons terakhir yang dikembalikan oleh layanan.

AIAgent agent = new OpenAIClient("<your_api_key>")
     .GetOpenAIResponseClient(modelName)
     .AsAIAgent(JokerInstructions, JokerName);
AgentSession session = await agent.GetNewSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));

Nota

Beberapa layanan, misalnya, Respons OpenAI mendukung penyimpanan riwayat obrolan dalam layanan (store=true), atau memberikan riwayat obrolan lengkap pada setiap pemanggilan (store=false). Oleh karena itu, tergantung pada mode tempat layanan digunakan, Agent Framework akan secara default menyimpan riwayat obrolan lengkap dalam memori, atau menyimpan referensi ID ke riwayat obrolan yang disimpan layanan.

Penyimpanan riwayat obrolan pihak ketiga

Saat menggunakan layanan yang tidak mendukung penyimpanan riwayat obrolan dalam layanan, Agent Framework memungkinkan pengembang untuk mengganti penyimpanan dalam memori default riwayat obrolan dengan penyimpanan riwayat obrolan pihak ketiga. Pengembang diharuskan untuk menyediakan subkelas kelas abstrak ChatHistoryProvider dasar.

Kelas ChatHistoryProvider menentukan antarmuka untuk menyimpan dan mengambil pesan obrolan. Pengembang harus menerapkan InvokedAsync metode dan InvokingAsync untuk menambahkan pesan ke penyimpanan jarak jauh saat dibuat, dan mengambil pesan dari penyimpanan jarak jauh sebelum memanggil layanan yang mendasar.

Agen akan menggunakan semua pesan yang dikembalikan oleh InvokingAsync saat memproses kueri pengguna. Terserah pelaksana ChatHistoryProvider untuk memastikan bahwa ukuran riwayat obrolan tidak melebihi jendela konteks layanan yang mendasar.

Saat menerapkan kustom ChatHistoryProvider yang menyimpan riwayat obrolan di penyimpanan jarak jauh, riwayat obrolan untuk sesi tersebut harus disimpan di bawah kunci yang unik untuk sesi tersebut. Implementasi ChatHistoryProvider harus menghasilkan kunci ini dan menyimpannya dalam keadaannya. ChatHistoryProvider memiliki Serialize metode yang dapat ditimpa untuk menserialisasikan statusnya ketika sesi diserialisasikan. juga ChatHistoryProvider harus menyediakan konstruktor yang mengambil JsonElement sebagai input untuk mendukung deserialisasi statusnya.

Untuk menyediakan kustom ChatHistoryProvider ke ChatClientAgent, Anda dapat menggunakan ChatHistoryProviderFactory opsi saat membuat agen. Berikut adalah contoh yang menunjukkan cara meneruskan implementasi ChatHistoryProvider kustom ke ChatClientAgent yang didasarkan pada Penyelesaian Obrolan Azure OpenAI.

Pabrik adalah fungsi asinkron yang menerima objek konteks dan token pembatalan.

AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = JokerName,
        ChatOptions = new() { Instructions = JokerInstructions },
        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(
            // Create a new chat history provider for this agent that stores the messages in a custom store.
            // Each session must get its own copy of the CustomChatHistoryProvider, since the provider
            // also contains the ID that the session is stored under.
            new CustomChatHistoryProvider(
                vectorStore,
                ctx.SerializedState,
                ctx.JsonSerializerOptions))
    });

Tip

Untuk contoh terperinci tentang cara membuat penyimpanan pesan kustom, lihat tutorial Menyimpan Riwayat Obrolan di Penyimpanan Pihak ke-3 .

Memori jangka panjang

Kerangka Kerja Agen memungkinkan pengembang untuk menyediakan komponen kustom yang dapat mengekstrak memori atau memberikan memori kepada agen.

Untuk mengimplementasikan komponen memori seperti itu, pengembang perlu subkelas AIContextProvider kelas dasar abstrak. Kelas ini memiliki dua metode inti, InvokingAsync dan InvokedAsync. Saat ditimpa, InvokedAsync memungkinkan pengembang untuk memeriksa semua pesan yang disediakan oleh pengguna atau dihasilkan oleh agen. InvokingAsync memungkinkan pengembang untuk menyuntikkan konteks tambahan untuk eksekusi agen tertentu. Instruksi sistem, pesan tambahan, dan fungsi tambahan dapat disediakan.

Tip

Untuk contoh terperinci tentang cara membuat komponen memori kustom, lihat tutorial Menambahkan Memori ke Agen .

Serialisasi AgentSession

Penting untuk dapat mempertahankan AgentSession objek antara pemanggilan agen. Ini memungkinkan situasi di mana pengguna mungkin mengajukan pertanyaan tentang agen, dan membutuhkan waktu lama untuk mengajukan pertanyaan tindak lanjut. Ini memungkinkan status AgentSession untuk bertahan hidup dari layanan atau mulai ulang aplikasi.

Bahkan jika riwayat obrolan disimpan di penyimpanan jarak jauh, AgentSession objek masih berisi ID yang merujuk riwayat obrolan jarak jauh. Oleh karena itu, kehilangan status AgentSession akan mengakibatkan juga kehilangan ID riwayat obrolan jarak jauh.

Serta AgentSession objek apa pun yang melekat padanya, oleh karena itu semua menyediakan Serialize metode untuk menserialisasikan statusnya. juga AIAgent menyediakan DeserializeSessionAsync metode yang membuat ulang sesi dari status berseri. Metode ini DeserializeSessionAsync membuat ulang sesi dengan dan AIContextProvider dikonfigurasi ChatHistoryProvider pada agen.

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

// Re-create the session from the JsonElement.
AgentSession resumedSession = await agent.DeserializeSessionAsync(serializedSessionState);

Nota

AgentSession objek mungkin berisi lebih dari sekadar riwayat obrolan, misalnya penyedia konteks juga dapat menyimpan status di objek sesi. Oleh karena itu, penting untuk selalu membuat serialisasi, menyimpan, dan mendeserialisasi seluruh AgentSession objek untuk memastikan bahwa semua status dipertahankan.

Penting

Selalu perlakukan AgentSession objek sebagai objek buram, kecuali Anda sangat yakin dengan internalnya. Konten dapat bervariasi tidak hanya berdasarkan jenis agen, tetapi juga berdasarkan jenis layanan dan konfigurasi.

Peringatan

Mendeserialisasi sesi dengan agen yang berbeda dari yang awalnya membuatnya, atau dengan agen yang memiliki konfigurasi yang berbeda dari agen asli, dapat mengakibatkan kesalahan atau perilaku tak terduga.

Jenis Memori

Agent Framework mendukung beberapa jenis memori untuk mengakomodasi kasus penggunaan yang berbeda, termasuk mengelola riwayat obrolan sebagai bagian dari memori jangka pendek dan menyediakan titik ekstensi untuk mengekstrak, menyimpan, dan menyuntikkan memori jangka panjang ke agen.

In-Memory Storage (Default)

Bentuk memori paling sederhana di mana riwayat percakapan disimpan dalam memori selama runtime aplikasi. Ini adalah perilaku default dan tidak memerlukan konfigurasi tambahan.

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)

Penyimpanan Pesan Persisten

Untuk aplikasi yang perlu mempertahankan riwayat percakapan di seluruh sesi, kerangka kerja menyediakan ChatMessageStore implementasi:

ChatMessageStore bawaan

Implementasi dalam memori default yang dapat diserialisasikan:

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
)

Penyimpanan Pesan Redis

Untuk aplikasi produksi yang memerlukan penyimpanan persisten:

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
)

Penyimpanan Pesan Kustom

Anda dapat menerapkan backend penyimpanan Anda sendiri dengan menerapkan 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"]

Tip

Untuk contoh terperinci tentang cara membuat penyimpanan pesan kustom, lihat tutorial Menyimpan Riwayat Obrolan di Penyimpanan Pihak ke-3 .

Penyedia Konteks (Memori Dinamis)

Penyedia konteks mengaktifkan pola memori canggih dengan menyuntikkan konteks yang relevan sebelum setiap pemanggilan agen:

Penyedia Konteks Dasar

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

Tip

Untuk contoh terperinci tentang cara membuat komponen memori kustom, lihat tutorial Menambahkan Memori ke Agen .

Layanan Memori Eksternal

Kerangka kerja ini mendukung integrasi dengan layanan memori khusus seperti 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
)

Serialisasi dan Persistensi Utas

Kerangka kerja ini mendukung serialisasi seluruh status utas untuk persistensi di seluruh mulai ulang aplikasi:

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)

Langkah selanjutnya

Alat Agen

  • Last updated on