Mulai cepat: Memberikan memori persisten agen yang dihosting

Important

Item yang ditandai sebagai pratinjau dalam artikel ini saat ini masih dalam pratinjau. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan Microsoft tidak merekomendasikannya untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.

Dalam panduan memulai cepat ini, Anda memberikan memori semantik persisten kepada agen terhosting yang didukung oleh penyimpanan memori Foundry. Tanpa memori, setiap percakapan dimulai dari awal. Dengan penyimpanan memori, agen mempertahankan fakta stabil tentang pengguna, seperti nama atau preferensi diet, dan mengingatnya di sesi selanjutnya.

Anda menyelesaikan dua bagian:

  • Buat penyimpanan memori dan hubungkan ke agen. Dalam alur Azure Developer CLI, hook provisi bawaan berjalan setelah azd provision. Di jalur Python, Anda membuat toko langsung dengan SDK. Sistem ini menggunakan model chat dan model embedding untuk mengekstrak dan mengindeks memori profil pengguna.
  • Terapkan agen terhosting yang membaca dan menulis ke penyimpanan data melalui FoundryMemoryProvider. Penyedia mengambil memori yang relevan sebelum setiap panggilan model dan memperbarui toko dengan fakta baru setelah setiap giliran.

Kode agen, penyedia memori, dan autentikasi berasal dari sampel memori Foundry, sehingga Anda fokus pada alur kerja daripada implementasi.

Jika Anda menggunakan agen pengkodian seperti GitHub Copilot, keterampilan Microsoft Foundry dapat membantu menyediakan penyimpanan memori, mengirimkannya ke agen yang dihosting, dan menguji perilaku pengenalan.

Prasyarat

Panduan memulai cepat ini berdasarkan toolchain hosted-agent. Selesaikan Prasyarat dalam panduan mulai cepat agen yang dihosting terlebih dahulu, yang mencakup langganan Azure, peran proyek, Python, Azure Developer CLI (azd), dan ekstensi microsoft.foundry.

Anda menggunakan Azure Developer CLI pada alur ini untuk membuat kerangka sampel, menyediakan penyimpanan memori melalui hook bawaan postprovision, menjalankan agen secara lokal, dan menyebarkannya.

Anda menggunakan SDK Python pada jalur ini untuk membuat penyimpanan memori dengan AIProjectClient.beta.memory_stores.create(...), mengunggah kode hosted-agent sebagai versi baru, mengarahkan lalu lintas ke sana untuk sementara, dan memvalidasi bahwa pengguna yang sama yang telah masuk tetap diingat pada panggilan-panggilan yang terpisah.

Instal paket Python yang digunakan dalam jalur ini:

pip install "azure-ai-projects>=2.3.0" python-dotenv

Gunakan SDK .NET pada jalur ini untuk membuat penyimpanan memori dengan AIProjectClient.MemoryStores.CreateMemoryStore(...), mengunggah kode agen yang dihosting sebagai versi baru, mengarahkan lalu lintas ke versi tersebut untuk sementara, dan memverifikasi bahwa pengguna yang sama yang telah masuk tetap dikenali pada panggilan yang terpisah.

Anda juga memerlukan .NET 10 SDK atau yang lebih baru.

Anda juga memerlukan penyebaran model penyematan dalam proyek Foundry Anda, seperti text-embedding-3-small. Penyimpanan memori menggunakannya untuk mengindeks memori. Model obrolan agen, seperti gpt-4o, dapat menjadi penyebaran yang sudah Anda gunakan untuk agen yang dihosting.

Identitas Anda memerlukan peran Foundry User dalam cakupan proyek Foundry melalui prasyarat hosted-agent, serta memerlukan peran Cognitive Services OpenAI User dalam cakupan yang sama. Penyimpanan memori menggunakan akses bidang data proyek Foundry ditambah penyebaran penyematan. Tanpa peran OpenAI, penulisan memori gagal dengan kesalahan 401 dan penyimpanan tetap kosong.

Important

Peran Foundry RBAC baru-baru ini diubah namanya. Pengguna Foundry, Pemilik Foundry, Pemilik Akun Foundry, dan Manajer Proyek Foundry sebelumnya bernama Pengguna Azure AI, Pemilik Azure AI, Pemilik Akun Azure AI, dan Manajer Proyek Azure AI. Anda mungkin masih melihat nama sebelumnya di beberapa tempat saat penggantian nama diluncurkan. ID peran dan izin inti tidak berubah oleh penggantian nama.

Langkah 1: Inisialisasi agen yang dihosting

Menginisialisasi agen yang dihosting dari sampel memori Foundry. Inisialisasi menyalin file sampel, termasuk skrip provisi penyimpanan memori dan hook provisi, ke direktori layanan baru di bawah src/. Jalankan perintah ini dalam direktori kosong.

mkdir my-memory-agent
cd my-memory-agent
azd ai agent init -t "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/azure.yaml"

Ikuti perintah untuk memilih langganan, proyek, dan penyebaran model Anda. Jika Anda tidak memiliki proyek Foundry, azd ai agent init memandu Anda membuat proyek.

Langkah 2: Aktifkan penyediaan dengan satu perintah

Contoh ini mencakup postprovision hook yang membuat penyimpanan memori dan menghubungkannya ke agen secara otomatis setiap kali Anda menjalankan azd provision. Daftarkan hook pada tingkat teratas di file azure.yaml yang dihasilkan oleh azd ai agent init.

Buka azure.yaml dan tambahkan blok tingkat atas berikut. Ganti <agent-name> dengan folder layanan yang inisialisasi dibuat di bawah src/:

hooks:
  postprovision:
    posix:
      shell: sh
      run: ./src/<agent-name>/hooks/postprovision.sh
    windows:
      shell: pwsh
      run: ./src/<agent-name>/hooks/postprovision.ps1

Hook tersebut bersifat dapat menemukan posisinya sendiri dan idempoten. Program ini berjalan dengan benar apa pun direktori asal azd dijalankan, dan menjalankannya kembali akan membiarkan penyimpanan yang ada tetap apa adanya.

Note

Daftarkan postprovision pada tingkat teratas dari azure.yaml. Kait cakupan layanan hanya mendukung paket dan menyebarkan siklus hidup, bukan provisi.

Langkah 3: Memprovisikan penyimpanan memori dan sumber daya Azure

  1. Arahkan kait pada penyebaran model penyematan yang mendukung memori semantik toko:

    azd env set AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME "text-embedding-3-small"

  2. Penyediaan:

    azd provision

azd provision membuat atau menggunakan kembali proyek Foundry dan penerapan model chat Anda. Kemudian kait postprovision :

  • Membuat penyimpanan memori dengan kemampuan profil pengguna diaktifkan dan memverifikasinya pada layanan.
  • MEMORY_STORE_NAME Mengatur agar agen membaca dan menulis penyimpanan tersebut. Hook mempertahankan nama ke lingkungan Anda azd untuk eksekusi lokal dan ke lingkungan azure.yaml layanan sehingga azd deploy mengirimkannya ke kontainer.

Alur CLI tidak menampilkan perintah create memory store yang terpisah karena hook bawaan menjalankan logika pembuatan tersebut untuk Anda sebagai bagian dari azd provision.

Hook ini menetapkan nama toko bawaan ke agent_framework_memory. Untuk menggunakan nama yang berbeda, atur nama tersebut sebelum Anda menyediakannya:

azd env set MEMORY_STORE_NAME "<your-store-name>"

Langkah 4: Jalankan agen secara lokal

  1. Mulai agen:

    azd ai agent run

    Perintah ini membuat lingkungan virtual, menginstal dependensi, dan melayani agen pada http://localhost:8088. Hook sudah menetapkan MEMORY_STORE_NAME dalam lingkungan azd Anda, jadi Anda tidak perlu konfigurasi tambahan. Paket pratinjau dapat menghasilkan peringatan pip selama penyiapan. Peringatan ini tidak memblokir.

  2. Di terminal terpisah, beri tahu agen fakta tentang diri Anda:

    azd ai agent invoke --local "Hi! My name is Linda and I'm vegetarian. Please remember that."

  3. Mulai sesi baru dan konfirmasikan agen mengingat fakta dari toko daripada dari riwayat percakapan:

    azd ai agent invoke --local --new-session "Do you remember my name and any dietary preference I told you earlier?"

    Agen menjawab dengan menyebut nama dan preferensi Anda, yang membuktikan bahwa informasi tersebut diambil dari penyimpanan memori.

Langkah 5: Terapkan ke Foundry Agent Service

Terapkan kode sumber agen. azd mengemas sumber sebagai file ZIP dan mengunggahnya ke Foundry, yang menyelesaikan dependensi dan membangun agen yang dihosting dari jarak jauh. Hook postprovision tersebut sudah menulis MEMORY_STORE_NAME ke dalam azure.yaml, sehingga agen yang di-deploy membaca penyimpanan yang sama:

azd deploy

Setelah perintah selesai, output menunjukkan tautan ke taman bermain agen dan titik akhir agen. Verifikasi memori antar-sesi pada agen yang diterapkan. Simpan sebuah fakta:

azd ai agent invoke --new-session "Hi! My name is Marco and I'm allergic to peanuts. Please remember this about me."

Kemudian ingatlah dalam sesi baru:

azd ai agent invoke --new-session "What's my name, and is there any food I should avoid?"

Agen yang di-deploy menjawab dengan menyebut nama dan alergi yang diingatnya.

Langkah 1: Membuat atau memilih proyek Foundry

  1. Buka portal Foundry dan buat proyek Foundry, atau pilih yang sudah ada.

  2. Dalam proyek, sebarkan:

    • Model yang dapat melakukan chat seperti gpt-5.4-mini.
    • Model penyematan seperti text-embedding-3-small.

  3. Salin titik akhir proyek dari Gambaran Umum dan nama penyebaran dariPenyebaran>.

Langkah 2: Unduh sampel memori Foundry

Kloning repositori sampel Foundry:

git clone https://github.com/microsoft-foundry/foundry-samples.git

Buat folder yang berfungsi untuk skrip penyebaran. Di folder tersebut, buat .env file dengan nilai-nilai ini:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-chat-model-deployment-name>
AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME=<your-embedding-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=memory-agent
MEMORY_STORE_NAME=agent_framework_memory
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/src/agent-framework-agent-foundry-memory-responses>

Langkah 3: Memprovisikan penyimpanan memori dengan Python

Skrip ini aman untuk dijalankan ulang. Pertama, ini memanggil get(...) untuk memeriksa apakah penyimpanan memori sudah ada. Ini hanya memanggil create(...) jika toko tidak ditemukan.

Buat file bernama provision_memory_store.py di folder kerja yang sama dengan .env:

import asyncio
import os

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
    MemoryStoreDefaultDefinition,
    MemoryStoreDefaultOptions,
)
from azure.core.exceptions import ResourceNotFoundError
from azure.identity.aio import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()


async def main() -> None:
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    memory_store_name = os.environ["MEMORY_STORE_NAME"]
    chat_model = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
    embedding_model = os.environ["AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME"]

    async with (
        DefaultAzureCredential() as credential,
        AIProjectClient(
            endpoint=endpoint,
            credential=credential,
            allow_preview=True,
        ) as project,
    ):
        try:
            existing = await project.beta.memory_stores.get(name=memory_store_name)
            print(
                f"Memory store '{existing.name}' already exists "
                f"(id={existing.id}); leaving as-is."
            )
            return
        except ResourceNotFoundError:
            pass

        definition = MemoryStoreDefaultDefinition(
            chat_model=chat_model,
            embedding_model=embedding_model,
            options=MemoryStoreDefaultOptions(
                chat_summary_enabled=False,
                user_profile_enabled=True,
                user_profile_details=(
                    "Avoid irrelevant or sensitive data, such as age, "
                    "financials, precise location, and credentials"
                ),
            ),
        )

        created = await project.beta.memory_stores.create(
            name=memory_store_name,
            description="Memory store for the hosted-agent memory quickstart",
            definition=definition,
        )
        print(f"Created memory store '{created.name}' (id={created.id}).")


asyncio.run(main())

Jalankan skrip:

python provision_memory_store.py

Langkah 4: Sebarkan agen yang dihosting dengan Python

Buat file bernama deploy_memory_agent.py di folder kerja yang sama dengan .env:

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointConfig,
    CodeConfiguration,
    CodeDependencyResolution,
    FixedRatioVersionSelectionRule,
    HostedAgentDefinition,
    ProtocolConfiguration,
    ProtocolVersionRecord,
    ResponsesProtocolConfiguration,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "memory-agent")
memory_store_name = os.environ["MEMORY_STORE_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
    zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
    excluded = {".git", ".venv", "__pycache__", ".env"}

    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
        for path in source_dir.rglob("*"):
            if not path.is_file():
                continue
            if any(part in excluded for part in path.parts):
                continue
            zip_file.write(path, path.relative_to(source_dir))

    return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
    for attempt in range(60):
        time.sleep(10)
        details = project_client.agents.get_version(
            agent_name=agent_name,
            agent_version=version,
        )
        status = details["status"]
        print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

        if status == "active":
            return

        if status == "failed":
            raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

    raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
    code_zip_path.open("rb") as code_stream,
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=endpoint,
        credential=credential,
        allow_preview=True,
    ) as project_client,
):
    original_agent_endpoint = None
    created = None

    try:
        created = project_client.agents.create_version_from_code(
            agent_name=agent_name,
            description="Hosted agent with persistent Foundry memory.",
            definition=HostedAgentDefinition(
                cpu="0.5",
                memory="1Gi",
                code_configuration=CodeConfiguration(
                    runtime="python_3_13",
                    entry_point=["python", "main.py"],
                    dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
                ),
                environment_variables={
                    "FOUNDRY_PROJECT_ENDPOINT": endpoint,
                    "AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
                    "MEMORY_STORE_NAME": memory_store_name,
                },
                protocol_versions=[
                    ProtocolVersionRecord(protocol="responses", version="2.0.0")
                ],
            ),
            code=code_stream,
        )

        print(f"Created hosted agent version {created.version}")
        wait_for_active_version(project_client, created.version)

        original_agent_endpoint = project_client.agents.get(
            agent_name=agent_name
        ).agent_endpoint

        project_client.agents.update_details(
            agent_name=agent_name,
            agent_endpoint=AgentEndpointConfig(
                version_selector=VersionSelector(
                    version_selection_rules=[
                        FixedRatioVersionSelectionRule(
                            agent_version=created.version,
                            traffic_percentage=100,
                        ),
                    ]
                ),
                protocol_configuration=ProtocolConfiguration(
                    responses=ResponsesProtocolConfiguration()
                ),
            ),
        )

        with project_client.get_openai_client(agent_name=agent_name) as openai_client:
            first_response = openai_client.responses.create(
                input="Hi! My name is Linda and I'm vegetarian. Please remember that.",
            )
            print(first_response.output_text)

            time.sleep(10)

            second_response = openai_client.responses.create(
                input=(
                    "Do you remember my name and any dietary preference I told "
                    "you earlier?"
                ),
            )
            print(second_response.output_text)
    finally:
        if original_agent_endpoint is not None:
            project_client.agents.update_details(
                agent_name=agent_name,
                agent_endpoint=original_agent_endpoint,
            )

        if created is not None:
            project_client.agents.delete_version(
                agent_name=agent_name,
                agent_version=created.version,
                force=True,
            )

Jalankan skrip:

python deploy_memory_agent.py

Skrip ini mengunggah sampel memori sebagai versi agen yang dihosting baru, mengarahkan agen yang dihosting pada versi tersebut untuk sementara waktu, memanggilnya dua kali sebagai pengguna yang masuk yang sama, dan memulihkan konfigurasi titik akhir sebelumnya saat selesai.

Langkah 5: Verifikasi bahwa memori berlanjut

Panggilan pertama menyimpan fakta tersebut dalam penyimpanan memori. Panggilan kedua meminta fakta yang diingat dalam permintaan terpisah. Jika penyimpanan memori dikonfigurasi dengan benar, respons harus menyebutkan nama dan preferensi diet yang sama yang Anda berikan dalam permintaan pertama.

Langkah 1: Membuat atau memilih proyek Foundry

  1. Buka portal Foundry dan buat proyek Foundry, atau pilih yang sudah ada.

  2. Dalam proyek, sebarkan:

    • Model yang dapat melakukan chat seperti gpt-4o.
    • Model penyematan seperti text-embedding-3-small.

  3. Salin titik akhir proyek dari Gambaran Umum dan nama penyebaran dariPenyebaran>.

Langkah 2: Unduh sampel memori Foundry

Kloning repositori sampel Foundry:

git clone https://github.com/microsoft-foundry/foundry-samples.git

Sampel agen yang dihosting C# berada di bawah samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/src/foundry-memory-rag. Langkah selanjutnya menerapkan folder tersebut sebagai versi agen terhosting. Contoh ini membaca konfigurasi dari variabel lingkungan berikut, yang diatur oleh kode deployment pada kontainer:

Variabel Description
FOUNDRY_PROJECT_ENDPOINT Titik akhir proyek Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME Nama penerapan model chat.
AZURE_AI_EMBEDDING_DEPLOYMENT_NAME Menyematkan nama penyebaran model.
AZURE_AI_MEMORY_STORE_ID Nama penyimpanan memori. Secara default menjadi foundry-memory-rag-store.

Langkah 3: Memprovisikan penyimpanan memori dengan C#

Buat aplikasi konsol .NET dan instal paket. API penyimpanan memori berada dalam pratinjau, jadi instal paket pra-rilis Azure.AI.Projects:

dotnet new console --name provision-memory-store
cd provision-memory-store
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity

Kode ini aman untuk dijalankan ulang. Ini pertama-tama memanggil GetMemoryStore(...) untuk memeriksa apakah penyimpanan sudah ada, dan hanya memanggil CreateMemoryStore(...) jika penyimpanan tidak ditemukan. Ganti Program.cs dengan kode berikut dan atur endpoint, chatModel, dan embeddingModel ke nilai proyek Anda:

using System.ClientModel;
using Azure.AI.Projects;
using Azure.AI.Projects.Memory;
using Azure.Identity;

#pragma warning disable AAIP001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var embeddingModel = "text-embedding-3-small";
var memoryStoreName = "foundry-memory-rag-store";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());

try
{
    MemoryStore existing = projectClient.MemoryStores.GetMemoryStore(memoryStoreName);
    Console.WriteLine($"Memory store '{existing.Name}' already exists (id={existing.Id}); leaving as-is.");
}
catch (ClientResultException ex) when (ex.Status == 404)
{
    MemoryStore created = projectClient.MemoryStores.CreateMemoryStore(
        memoryStoreName,
        new MemoryStoreDefaultDefinition(chatModel, embeddingModel)
        {
            Options = new MemoryStoreDefaultOptions(isUserProfileEnabled: true, isChatSummaryEnabled: false)
            {
                UserProfileDetails =
                    "Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials",
            },
        },
        description: "Memory store for the hosted-agent memory quickstart");
    Console.WriteLine($"Created memory store '{created.Name}' (id={created.Id}).");
}

Jalankan aplikasi:

dotnet run

Langkah 4: Sebarkan agen yang dihosting dengan C#

Buat aplikasi konsol kedua untuk kode penyebaran:

dotnet new console --name deploy-memory-agent
cd deploy-memory-agent
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

Di Program.cs, ganti kode yang ada dengan kode berikut. Atur endpoint, chatModel, embeddingModel, dan samplePath ke nilai Anda. samplePath adalah jalur lengkap ke folder sumber yang foundry-memory-rag Anda kloning di Langkah 2:

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var embeddingModel = "text-embedding-3-small";
var agentName = "memory-agent";
var memoryStoreName = "foundry-memory-rag-store";
var samplePath =
    @"<path-to-foundry-samples>\samples\csharp\hosted-agents\agent-framework\foundry-memory-rag\src\foundry-memory-rag";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;

HostedAgentDefinition definition = new(cpu: "0.5", memory: "1Gi")
{
    Versions = { new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0") },
    CodeConfiguration = new(
        runtime: "dotnet_10",
        entryPoint: ["dotnet", "foundry-memory-rag.dll"],
        dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add("FOUNDRY_PROJECT_ENDPOINT", endpoint);
definition.EnvironmentVariables.Add("AZURE_AI_MODEL_DEPLOYMENT_NAME", chatModel);
definition.EnvironmentVariables.Add("AZURE_AI_EMBEDDING_DEPLOYMENT_NAME", embeddingModel);
definition.EnvironmentVariables.Add("AZURE_AI_MEMORY_STORE_ID", memoryStoreName);

ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;
try
{
    created = agentsClient.CreateAgentVersionFromCode(
        agentName, samplePath, new AgentVersionFromCodeMetadata(definition));
    Console.WriteLine($"Created hosted agent version {created.Version}");

    for (var attempt = 1; attempt <= 60; attempt++)
    {
        Thread.Sleep(TimeSpan.FromSeconds(10));
        created = agentsClient.GetAgentVersion(agentName, created.Version);
        Console.WriteLine($"Provisioning status: {created.Status} (attempt {attempt}/60)");
        if (created.Status == AgentVersionStatus.Active) break;
        if (created.Status == AgentVersionStatus.Failed)
            throw new InvalidOperationException("Hosted agent provisioning failed.");
    }

    ProjectsAgentRecord agent = agentsClient.GetAgent(agentName);
    originalEndpoint = agent.AgentEndpoint;
    agentsClient.PatchAgent(agentName, new PatchAgentOptions
    {
        AgentEndpoint = new AgentEndpointConfiguration
        {
            VersionSelector = new([new FixedRatioVersionSelectionRule(created.Version, 100)]),
            ProtocolConfiguration = new() { Responses = new ResponsesProtocolConfiguration() },
        },
    });

    ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgentEndpoint(agentName);

    ResponseResult first = responsesClient.CreateResponse(
        "Hi! My name is Linda and I'm vegetarian. Please remember that.");
    Console.WriteLine(first.GetOutputText());

    Thread.Sleep(TimeSpan.FromSeconds(10));

    ResponseResult second = responsesClient.CreateResponse(
        "Do you remember my name and any dietary preference I told you earlier?");
    Console.WriteLine(second.GetOutputText());
}
finally
{
    if (originalEndpoint is not null)
        agentsClient.PatchAgent(agentName, new PatchAgentOptions { AgentEndpoint = originalEndpoint });
    if (created is not null)
        agentsClient.DeleteAgentVersion(agentName, created.Version, force: true);
}

Jalankan aplikasi:

dotnet run

Kode ini mengunggah sampel memori sebagai versi agen yang dihosting baru, mengarahkan agen yang dihosting pada versi tersebut untuk sementara, memanggilnya dua kali sebagai pengguna yang masuk yang sama, dan memulihkan konfigurasi titik akhir sebelumnya setelah selesai.

Langkah 5: Verifikasi bahwa memori berlanjut

Panggilan pertama menyimpan fakta tersebut dalam penyimpanan memori. Panggilan kedua meminta fakta yang diingat dalam permintaan terpisah. Jika penyimpanan memori dikonfigurasi dengan benar, respons menyebutkan nama dan preferensi diet yang sama yang Anda berikan dalam permintaan pertama. Ekstraksi memori bersifat asinkron, jadi beri jeda beberapa detik di antara kedua panggilan agar penyimpanan dapat mengindeks memori.

Membersihkan sumber daya

Hapus sumber daya setelah selesai sehingga Anda berhenti dikenakan biaya.

Untuk menghapus penyimpanan memori, gunakan AIProjectClient. Jalankan skrip ini di lingkungan Python yang menginstal azure-ai-projects paket dan azure-identity (misalnya, jalankan pip install "azure-ai-projects>=2.3.0"):

import asyncio
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient

async def delete():
    async with (
        DefaultAzureCredential() as credential,
        AIProjectClient(
            endpoint="https://<account>.services.ai.azure.com/api/projects/<project>",
            credential=credential,
            allow_preview=True,
        ) as project,
    ):
        await project.beta.memory_stores.delete("agent_framework_memory")

asyncio.run(delete())

Hapus agen dan sumber daya Azure:

Warning

Jika lingkungan saat ini azd membuat proyek Foundry, azd down secara permanen menghapus grup sumber daya proyek dan semua yang ada di dalamnya. Jika Anda memilih proyek yang sudah ada selama inisialisasi, azd down tetap mempertahankan proyek, grup sumber dayanya, agen yang di-host, dan sumber daya mulai cepat lainnya sebagaimana adanya. Untuk menghapus sumber daya yang tidak lagi Anda butuhkan dari proyek yang ada, hapus secara terpisah.

azd down

Untuk menghapus penyimpanan memori, gunakan pola skrip yang sama dengan nama penyimpanan memori Anda:

import asyncio
import os

from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()


async def delete() -> None:
    async with (
        DefaultAzureCredential() as credential,
        AIProjectClient(
            endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            credential=credential,
            allow_preview=True,
        ) as project,
    ):
        await project.beta.memory_stores.delete(os.environ["MEMORY_STORE_NAME"])


asyncio.run(delete())

Jika Anda membuat grup sumber daya atau proyek khusus untuk mulai cepat ini, hapus dari portal Azure setelah Anda tidak lagi memerlukan penyebaran obrolan, penyebaran penyematan, atau agen yang dihosting.

Kode penyebaran sudah menghapus versi agen yang dihosting dan memulihkan konfigurasi titik akhir sebelumnya setelah selesai. Untuk menghapus penyimpanan memori, tambahkan kode ini ke aplikasi konsol yang telah menginstal paket Azure.AI.Projects (prarilis) dan Azure.Identity:

using Azure.AI.Projects;
using Azure.Identity;

#pragma warning disable AAIP001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var memoryStoreName = "foundry-memory-rag-store";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
projectClient.MemoryStores.DeleteMemoryStore(memoryStoreName);
Console.WriteLine($"Deleted memory store '{memoryStoreName}'.");

Jika Anda membuat grup sumber daya atau proyek khusus untuk mulai cepat ini, hapus dari portal Azure setelah Anda tidak lagi memerlukan penyebaran obrolan, penyebaran penyematan, atau agen yang dihosting.

Troubleshooting

Issue Solution
Agen yang disebarkan tidak memiliki memori, atau MEMORY_STORE_NAME kosong Pastikan hook postprovision dijalankan selama azd provision dan azure.yaml telah disetel ke MEMORY_STORE_NAME. Jalankan ulang azd provision untuk menjalankan hook lagi.
Penulisan memori gagal dengan 401 kesalahan dan penyimpanan tetap kosong Pastikan bahwa pemanggil sudah memiliki akses Foundry User dalam cakupan proyek Foundry, dan berikan peran Cognitive Services OpenAI User pada cakupan yang sama kepada identitas Anda dan identitas runtime agen yang diterapkan.
azd provision gagal karena kesalahan izin Pastikan identitas Anda memiliki peran proyek yang tercantum dalam Prasyarat.
project.beta.memory_stores.create(...) gagal dengan Authentication to the Azure OpenAI resource failed Konfirmasikan identitas Anda sudah memiliki akses Pengguna Foundry pada cakupan proyek Foundry, dan juga memiliki peran Pengguna OpenAI Cognitive Services pada cakupan tersebut. Pastikan juga bahwa AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME mengarah ke deployment embedding yang valid.
Penyebaran Python berhasil tetapi panggilan kedua tidak memanggil kembali fakta yang disimpan Tunggu beberapa detik lagi sebelum panggilan kedua sehingga penyimpanan memori selesai mengindeks, lalu jalankan skrip lagi.
Agen tidak ingat fakta yang Anda bagikan Tunggu beberapa detik setelah menyimpan fakta sebelum Anda melakukan kueri, agar penyimpanan selesai mengindeks memori.
Agen tidak dapat membaca atau menulis ingatan setelah penerapan Konfirmasikan bahwa postprovision hook membuat penyimpanan terhadap proyek yang sama tempat agen disebarkan.

Apa yang Anda pelajari

Dalam panduan memulai cepat ini, Anda:

  • Membuat penyimpanan memori Foundry dengan kemampuan profil pengguna.
  • Menyebarkan agen yang dihosting yang membaca dan menulis ke penyimpanan dengan FoundryMemoryProvider menggunakan Azure Developer CLI, Python SDK, atau SDK .NET.
  • Memastikan bahwa agen mengingat informasi pengguna di berbagai sesi yang terpisah, baik secara lokal dengan Azure Developer CLI maupun secara jarak jauh dengan SDK Python atau .NET setelah penerapan.

Langkah selanjutnya

Evaluasi agen terhosting Anda

Konten terkait

  • Terakhir diperbarui pada