Langkah 4: Memori & Persistensi

Tambahkan konteks ke agen Anda sehingga dapat mengingat preferensi pengguna, interaksi sebelumnya, atau pengetahuan eksternal.

Secara bawaan, agen akan menyimpan riwayat obrolan dalam InMemoryChatHistoryProvider atau di layanan AI yang digunakan, tergantung pada kebutuhan layanan tersebut.

Agen berikut menggunakan OpenAI Chat Completion, yang tidak mendukung atau memerlukan penyimpanan riwayat obrolan dalam layanan sehingga secara otomatis membuat dan menggunakan InMemoryChatHistoryProvider.

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("Set AZURE_OPENAI_ENDPOINT");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "MemoryAgent");

Warning

DefaultAzureCredential nyaman untuk pengembangan tetapi membutuhkan pertimbangan yang cermat dalam produksi. Dalam produksi, pertimbangkan untuk menggunakan kredensial tertentu (misalnya, ManagedIdentityCredential) untuk menghindari masalah latensi, pemeriksaan kredensial yang tidak diinginkan, dan potensi risiko keamanan dari mekanisme fallback.

Untuk menggunakan ChatHistoryProvider kustom, Anda dapat meneruskannya ke opsi agen:

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("Set AZURE_OPENAI_ENDPOINT");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(model: deploymentName, options: new ChatClientAgentOptions()
    {
        ChatOptions = new() { Instructions = "You are a helpful assistant." },
        ChatHistoryProvider = new CustomChatHistoryProvider()
    });

Gunakan sesi untuk berbagi konteks di seluruh proses:

AgentSession session = await agent.CreateSessionAsync();

Console.WriteLine(await agent.RunAsync("Hello! What's the square root of 9?", session));
Console.WriteLine(await agent.RunAsync("My name is Alice", session));
Console.WriteLine(await agent.RunAsync("What is my name?", session));

Tip

Lihat di sini untuk aplikasi sampel lengkap yang dapat dijalankan.

Sampel lengkap mendefinisikan penyedia konteks, menambahkannya ke agen, dan menggunakan satu sesi untuk mempertahankan status personalisasi:

import asyncio
from typing import Any

from agent_framework import Agent, AgentSession, ContextProvider, SessionContext
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential


class UserMemoryProvider(ContextProvider):
    def __init__(self) -> None:
        super().__init__("user_memory")

    async def before_run(
        self,
        *,
        agent: Any,
        session: AgentSession | None,
        context: SessionContext,
        state: dict[str, Any],
    ) -> None:
        user_name = state.get("user_name")
        instructions = (
            f"The user's name is {user_name}. Address them by name." if user_name else "Ask for the user's name."
        )
        context.extend_instructions(self.source_id, instructions)

    async def after_run(
        self,
        *,
        agent: Any,
        session: AgentSession | None,
        context: SessionContext,
        state: dict[str, Any],
    ) -> None:
        for message in context.input_messages:
            text = message.text
            if not isinstance(text, str):
                continue
            _, marker, name = text.lower().partition("my name is")
            if marker and name.strip():
                state["user_name"] = name.split()[0].capitalize()


async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint="https://your-account.services.ai.azure.com/api/projects/your-project",
            model="gpt-6-luna",
            credential=AzureCliCredential(),
        ),
        instructions="You are a friendly assistant.",
        context_providers=[UserMemoryProvider()],
    )
    session = agent.create_session()

    print(await agent.run("Hello! What's the square root of 9?", session=session))
    print(await agent.run("My name is Alice", session=session))
    print(await agent.run("What is 2 + 2?", session=session))


if __name__ == "__main__":
    asyncio.run(main())

Tip

Lihat sampel lengkap untuk file lengkap yang dapat dijalankan.

Nota

Dalam Python, persistensi/memori ditangani oleh ContextProvider dan HistoryProvider implementasi. InMemoryHistoryProvider adalah penyedia riwayat lokal dalam memori bawaan. RawAgent dapat menambahkan InMemoryHistoryProvider() secara otomatis dalam kasus tertentu (misalnya, saat menggunakan sesi tanpa penyedia konteks yang dikonfigurasi dan tidak ada indikator penyimpanan sisi layanan), tetapi ini tidak dijamin dalam semua skenario. Jika Anda selalu menginginkan persistensi lokal, tambahkan InMemoryHistoryProvider secara eksplisit. Pastikan juga hanya satu penyedia riwayat yang memiliki load_messages=True, sehingga Anda tidak memutar ulang beberapa toko ke dalam pemanggilan yang sama.

Buat klien proyek dan penyimpanan memori dengan mengikuti memori semantik terkelola Microsoft Foundry. Kemudian gabungkan riwayat transkrip lokal, memori terkelola, dan penyimpanan audit:

from agent_framework import InMemoryHistoryProvider
from agent_framework.foundry import FoundryMemoryProvider

history = InMemoryHistoryProvider(load_messages=True)
memory = FoundryMemoryProvider(
    project_client=project_client,
    memory_store_name="user-memory",
    scope="user-123",
)
audit_store = InMemoryHistoryProvider(
    "audit",
    load_messages=False,
    store_context_messages=True,  # include context added by other providers
)

agent = client.as_agent(
    name="MemoryAgent",
    instructions="You are a friendly assistant.",
    context_providers=[history, memory, audit_store],  # audit store last
)

Secara default, agen menggunakan riwayat dalam memori lokal atau riwayat yang dikelola layanan tergantung pada penyedia dan sesi.

Agen Foundry berikut menggunakan deployment model berbasis proyek. Tambahkan penyedia konteks saat Anda menginginkan memori atau status personalisasi khusus aplikasi di luar riwayat percakapan.

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are a friendly assistant. Keep your answers brief.",
        Config: agent.Config{
            Name: "MemoryAgent",
        },
    },
)

Tentukan penyedia konteks yang menyimpan info pengguna dalam status sesi dan menyuntikkan instruksi personalisasi:

import (
    "context"
    "fmt"
    "strings"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/message"
)

const userMemorySourceID = "user_memory"

type providerState struct {
    UserName string `json:"user_name,omitempty"`
}

func newUserMemoryProvider() agent.ContextProvider {
    return agent.NewContextProvider(agent.ContextProviderConfig{
        SourceID: userMemorySourceID,
        Provide:  provideUserMemory,
        Store:    storeUserMemory,
    })
}

func provideUserMemory(ctx context.Context, invoking agent.InvokingContext) ([]*message.Message, []agent.Option, error) {
    session, _ := agent.GetOption(invoking.Options, agent.WithSession)
    var state providerState
    _, _ = session.Get(userMemorySourceID, &state)

    instructions := "You don't know the user's name yet. Ask for it politely."
    if state.UserName != "" {
        instructions = fmt.Sprintf("The user's name is %s. Always address them by name.", state.UserName)
    }
    return nil, []agent.Option{agent.WithInstructions(instructions)}, nil
}

func storeUserMemory(ctx context.Context, invoked agent.InvokedContext) error {
    session, _ := agent.GetOption(invoked.Options, agent.WithSession)
    var state providerState
    _, _ = session.Get(userMemorySourceID, &state)
    for _, msg := range invoked.RequestMessages {
        text := strings.TrimSpace(msg.Contents.Text())
        lower := strings.ToLower(text)
        if idx := strings.Index(lower, "my name is"); idx >= 0 {
            parts := strings.Fields(text[idx+len("my name is"):])
            if len(parts) == 0 {
                continue
            }
            state.UserName = strings.Trim(parts[0], ".,!?")
            session.Set(userMemorySourceID, state)
            break
        }
    }
    return nil
}

Buat agen dengan penyedia konteks:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are a friendly assistant.",
        Config: agent.Config{
            Name:             "MemoryAgent",
            ContextProviders: []agent.ContextProvider{newUserMemoryProvider()},
        },
    },
)

Jalankan — agen sekarang memiliki akses ke konteks:

ctx := context.Background()
session, err := a.CreateSession(ctx)
if err != nil {
    panic(err)
}

// The provider doesn't know the user yet.
resp, err := a.RunText(ctx, "Hello, what is the square root of 9?", agent.WithSession(session)).Collect()
fmt.Println(resp, err)

// Teach the provider the user's name.
resp, err = a.RunText(ctx, "My name is Alice", agent.WithSession(session)).Collect()
fmt.Println(resp, err)

// Subsequent calls are personalized using session state.
resp, err = a.RunText(ctx, "What is 2 + 2?", agent.WithSession(session)).Collect()
fmt.Println(resp, err)

Status personalisasi milik sesi, bukan instans penyedia. Serialkan sesi untuk mempertahankannya:

import "encoding/json"

data, err := json.Marshal(session)
if err != nil {
    panic(err)
}

var restored agent.Session
if err := json.Unmarshal(data, &restored); err != nil {
    panic(err)
}

resp, err = a.RunText(
    ctx,
    "What is my name?",
    agent.WithSession(&restored),
).Collect()
if err != nil {
    panic(err)
}
fmt.Println(resp.String())

Status provider yang dipulihkan masih berisi nama Alice. Agar tetap tersedia setelah proses dimulai ulang, simpan byte yang diserialkan di lapisan persistensi aplikasi Anda. Contoh ini bukan penyimpanan memori semantik antar-sesi.

Tip

Lihat sampel lengkap untuk file lengkap yang dapat dijalankan.

Langkah berikutnya

Langkah 5: Alur Kerja

Masuk lebih dalam:

  • Terakhir diperbarui pada