Szybki start: nadawanie pamięci trwałej hostowanemu agentowi

Important

Elementy oznaczone podglądem w tym artykule są obecnie w wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług, a Microsoft nie zaleca korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

W tym przewodniku Szybki start nadasz hostowanemu agentowi trwałą, semantyczną pamięć opartą na usłudze Foundry magazynu pamięci. Bez pamięci każda rozmowa zaczyna się od podstaw. W magazynie pamięci agent zachowuje stabilne fakty dotyczące użytkownika, takie jak nazwa lub preferencja diety, i przypomina je w kolejnych sesjach.

Wykonasz dwie części:

  • Utwórz magazyn danych w pamięci i połącz go z agentem. W ścieżce Azure Developer CLI dołączony hook aprowizacji jest uruchamiany po elemencie azd provision. W ścieżce Python magazyn jest tworzony bezpośrednio za pomocą zestawu SDK. Magazyn używa modelu czatu i modelu osadzania do wyodrębniania i indeksowania wspomnień profilu użytkownika.
  • Wdróż hostowanego agenta , który odczytuje i zapisuje magazyn za pośrednictwem programu FoundryMemoryProvider. Dostawca pobiera odpowiednie zapamiętane informacje przed każdym wywołaniem modelu i aktualizuje repozytorium o nowe fakty po każdej turze.

Kod agenta, dostawca pamięci i uwierzytelnianie pochodzą z przykładu pamięci Foundry, więc koncentrujesz się na przepływie pracy, a nie na implementacji.

Jeśli używasz agenta kodowania, takiego jak GitHub Copilot, umiejętność Microsoft Foundry może pomóc aprowizować magazyn pamięci, połączyć go z hostowanym agentem i przetestować zachowanie przywoływania.

Wymagania wstępne

Ten przewodnik Szybki start bazuje na zestawie narzędzi hostowanego agenta. Najpierw wykonaj wymagania wstępne w przewodniku Szybki start dotyczącym hostowanego agenta, które obejmują subskrypcję platformy Azure, role projektu, język Python, interfejs wiersza polecenia Azure Developer CLI (azd) oraz rozszerzenie microsoft.foundry.

W tym scenariuszu użyjesz interfejsu wiersza polecenia Azure Developer CLI, aby wygenerować szkielet przykładowego rozwiązania, udostępnić magazyn pamięci za pomocą dołączonego elementu hook postprovision, uruchomić agenta lokalnie i wdrożyć go.

W tej ścieżce użyjesz zestawu Python SDK do utworzenia magazynu pamięci za pomocą AIProjectClient.beta.memory_stores.create(...), przesłania kodu hostowanego agenta jako nowej wersji, tymczasowego przekierowania do niej ruchu oraz sprawdzenia, czy ten sam zalogowany użytkownik jest pamiętany między oddzielnymi wywołaniami.

Zainstaluj pakiety Python używane w tej ścieżce:

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

Użyj zestawu .NET SDK w tej lokalizacji, aby utworzyć magazyn pamięci za pomocą polecenia AIProjectClient.MemoryStores.CreateMemoryStore(...), przesłać kod hostowanego agenta jako nową wersję, tymczasowo skierować do tej wersji ruch i sprawdzić, czy ten sam zalogowany użytkownik jest pamiętany podczas oddzielnych wywołań.

Potrzebny jest również zestaw SDK .NET 10 lub nowszy.

Potrzebujesz również wdrożenia modelu osadzania w projekcie Foundry, takim jak text-embedding-3-small. Magazyn pamięci używa go do indeksowania pamięci. Model czatu używany przez agenta, taki jak gpt-4o, może być tym samym wdrożeniem, którego już używasz w przypadku agentów hostowanych.

Do Twojej tożsamości musi być przypisana rola Użytkownik usługi Foundry w zakresie projektu Foundry, zgodnie z wymaganiami wstępnymi hostowanego agenta, a także rola Użytkownik usługi OpenAI usługi Cognitive Services w tym samym zakresie. Magazyn pamięciowy korzysta z dostępu do płaszczyzny danych projektu Foundry oraz z wdrożenia modelu osadzania. Bez roli OpenAI zapisy do pamięci kończą się błędem 401, a repozytorium pozostaje puste.

Important

Niedawno zmieniono nazwy ról RBAC w usłudze Foundry. Użytkownik Foundry, właściciel Foundry, właściciel konta Foundry i menedżer projektu Foundry były wcześniej nazywane odpowiednio użytkownikiem Azure AI, właścicielem Azure AI, właścicielem konta Azure AI i menedżerem projektu Azure AI. Poprzednie nazwy mogą być nadal widoczne w niektórych miejscach, podczas gdy zmiana nazwy jest wdrażana. Identyfikatory ról i uprawnienia podstawowe są niezmienione przez zmianę nazwy.

Krok 1. Inicjowanie hostowanego agenta

Zainicjuj hostowanego agenta na podstawie przykładu pamięci Foundry. Inicjowanie kopiuje przykładowe pliki, w tym skrypt aprowizacji magazynu pamięci i punkt zaczepienia aprowizacji, do nowego katalogu usługi w obszarze src/. Uruchom te polecenia w pustym katalogu.

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"

Postępuj zgodnie z monitami, aby wybrać subskrypcję, projekt i wdrożenie modelu. Jeśli nie masz projektu Foundry, azd ai agent init przeprowadzi Cię przez proces jego tworzenia.

Krok 2: Włącz konfigurację za pomocą jednego polecenia

Przykład zawiera postprovision hak, który tworzy magazyn pamięci i automatycznie łączy go z agentem za każdym razem, gdy uruchamiasz azd provision. Zarejestruj hook na najwyższym poziomie pliku azure.yaml, wygenerowanego przez azd ai agent init.

Otwórz azure.yaml i dodaj następujący blok najwyższego poziomu. Zastąp <agent-name> folderem usługi utworzonym przez inicjalizację w katalogu src/:

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

Hook jest samopozycjonujący się i idempotentny. Działa poprawnie niezależnie od katalogu, z którego wywoływane jest azd, a ponowne uruchomienia pozostawiają istniejące repozytorium bez zmian.

Note

Zarejestruj postprovision na najwyższym poziomie w azure.yaml. Hooki przypisane do usługi obsługują tylko cykl życia pakietowania i wdrażania, a nie aprowizację.

Krok 3. Aprowizuj magazyn pamięci i zasoby Azure

  1. Wskaż punkt zaczepienia we wdrożeniu modelu osadzania, które obsługuje pamięć semantyczną magazynu:

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

  2. Postanowienie:

    azd provision

azd provision tworzy lub używa ponownie projektu Foundry i wdrożenia modelu czatowego. Następnie postprovision funkcja hook:

  • Tworzy magazyn pamięci z włączoną funkcją profilu użytkownika i weryfikuje go w usłudze.
  • Ustawia MEMORY_STORE_NAME, aby agent mógł odczytywać i zapisywać ten magazyn danych. Hook zapisuje nazwę w środowisku azd na potrzeby lokalnych uruchomień oraz w środowisku usługi w azure.yaml, dzięki czemu azd deploy przekazuje ją do kontenera.

W ścieżce CLI nie jest wyświetlane oddzielne polecenie create memory store, ponieważ dołączony hook wykonuje tę logikę tworzenia za Ciebie w ramach azd provision.

Hook domyślnie ustawia nazwę sklepu na agent_framework_memory. Aby użyć innej nazwy, ustaw ją przed aprowizacją:

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

Krok 4. Uruchamianie agenta lokalnie

  1. Uruchom agenta:

    azd ai agent run

    To polecenie tworzy środowisko wirtualne, instaluje zależności i obsługuje agenta na platformie http://localhost:8088. Hook już ustawia MEMORY_STORE_NAME w środowisku azd, więc nie potrzebujesz żadnej dodatkowej konfiguracji. Pakiety w wersji zapoznawczej mogą tworzyć ostrzeżenia pip podczas instalacji. Te ostrzeżenia nie blokują działania.

  2. W osobnym terminalu poinformuj agenta o sobie:

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

  3. Rozpocznij nową sesję i potwierdź, że agent przypomina fakt ze sklepu, a nie z historii konwersacji:

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

    Agent odpowiada, podając twoje imię i preferencje, co potwierdza, że pobrał je z magazynu pamięci.

Krok 5. Wdrażanie w usłudze agenta programu Foundry

Wdróż kod źródłowy agenta. azd pakuje źródło jako plik ZIP i przekazuje je do rozwiązania Foundry, co rozwiązuje zależności i kompiluje hostowanego agenta zdalnie. Hook postprovision zapisuje już MEMORY_STORE_NAME do azure.yaml, więc wdrożony agent odczytuje ten sam magazyn danych:

azd deploy

Po zakończeniu polecenia dane wyjściowe zawierają linki do placu zabaw agenta i punktu końcowego agenta. Zweryfikuj pamięć między sesjami wdrożonego agenta. Przechowywanie faktów:

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

Następnie przypomnij sobie ją w nowej sesji:

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

Wdrożony agent podaje zapamiętane imię i informację o alergii.

Krok 1. Tworzenie lub wybieranie projektu Foundry

  1. Otwórz portal Foundry i utwórz projekt Foundry lub wybierz istniejący.

  2. W projekcie wdróż:

    • Model z funkcją czatu, taki jak gpt-5.4-mini.
    • Model osadzania, taki jak text-embedding-3-small.

  3. Skopiuj punkt końcowy projektu z sekcji Przegląd oraz nazwy wdrożeń z Kompilacja>Wdrożenia.

Krok 2: Pobierz próbkę pamięci Foundry

Sklonuj repozytorium z przykładami Foundry:

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

Utwórz folder roboczy dla skryptów wdrażania. W tym folderze utwórz plik .env z następującymi wartościami:

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>

Krok 3. Aprowizuj magazyn pamięci przy użyciu Python

Ten skrypt jest bezpieczny do ponownego uruchomienia. Najpierw wywołuje get(...), aby sprawdzić, czy magazyn pamięci już istnieje. Wywołuje create(...) tylko wtedy, gdy magazyn nie zostanie odnaleziony.

Utwórz plik o nazwie provision_memory_store.py w tym samym folderze roboczym co .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())

Uruchom skrypt:

python provision_memory_store.py

Krok 4. Wdrażanie hostowanego agenta przy użyciu Python

Utwórz plik o nazwie deploy_memory_agent.py w tym samym folderze roboczym co .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,
            )

Uruchom skrypt:

python deploy_memory_agent.py

Ten skrypt przesyła próbkę pamięci jako nową wersję hostowanego agenta, tymczasowo kieruje hostowanego agenta na tę wersję, dwukrotnie go wywołuje jako ten sam zalogowany użytkownik i po zakończeniu przywraca poprzednią konfigurację punktu końcowego.

Krok 5. Sprawdzanie, czy pamięć jest utrwalana

Pierwsze wywołanie zapisuje ten fakt w magazynie danych w pamięci. Drugie wywołanie dotyczy zapamiętanego faktu w osobnym żądaniu. Jeśli magazyn pamięci jest poprawnie skonfigurowany, odpowiedź powinna zawierać tę samą nazwę i preferencje żywieniowe podane w pierwszym żądaniu.

Krok 1. Tworzenie lub wybieranie projektu Foundry

  1. Otwórz portal Foundry i utwórz projekt Foundry lub wybierz istniejący.

  2. W projekcie wdróż:

    • Model z funkcją czatu, taki jak gpt-4o.
    • Model osadzania, taki jak text-embedding-3-small.

  3. Skopiuj punkt końcowy projektu z sekcji Przegląd oraz nazwy wdrożeń z Kompilacja>Wdrożenia.

Krok 2: Pobierz próbkę pamięci Foundry

Sklonuj repozytorium z przykładami Foundry:

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

Przykład hostowanego agenta C# znajduje się w samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/src/foundry-memory-rag. Następne kroki umożliwiają wdrożenie tego folderu jako hostowanej wersji agenta. Przykład odczytuje konfigurację z tych zmiennych środowiskowych, które kod wdrożenia ustawia w kontenerze:

Variable Description
FOUNDRY_PROJECT_ENDPOINT Punkt końcowy projektu Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME Nazwa wdrożenia modelu czatu.
AZURE_AI_EMBEDDING_DEPLOYMENT_NAME Osadzanie nazwy wdrożenia modelu.
AZURE_AI_MEMORY_STORE_ID Nazwa magazynu pamięci. Wartość domyślna to foundry-memory-rag-store.

Krok 3. Aprowizuj magazyn pamięci za pomocą języka C#

Utwórz aplikację konsolową .NET i zainstaluj pakiety. Interfejsy API magazynu pamięci są dostępne w wersji zapoznawczej, dlatego zainstaluj pakiet Azure.AI.Projects w wersji wstępnej:

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

Ten kod jest bezpieczny do ponownego uruchomienia. Najpierw wywołuje polecenie GetMemoryStore(...), aby sprawdzić, czy magazyn danych już istnieje, i wywołuje CreateMemoryStore(...) tylko wtedy, gdy magazyn danych nie zostanie znaleziony. Zastąp Program.cs następującym kodem i ustaw endpoint, chatModel oraz embeddingModel na wartości używane w projekcie:

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

Uruchom aplikację:

dotnet run

Krok 4. Wdrażanie hostowanego agenta za pomocą języka C#

Utwórz drugą aplikację konsolową dla kodu wdrożenia:

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

W Program.cspliku zastąp istniejący kod następującym kodem. Ustaw endpoint, chatModel, embeddingModel i samplePath na własne wartości. samplePath to pełna ścieżka do folderu źródłowego foundry-memory-rag sklonowanego w kroku 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);
}

Uruchom aplikację:

dotnet run

Ten kod przesyła próbkę pamięci jako nową wersję agenta hostowanego, tymczasowo kieruje agenta hostowanego na tę wersję, wywołuje go dwukrotnie jako ten sam zalogowany użytkownik i po zakończeniu przywraca konfigurację poprzedniego punktu końcowego.

Krok 5. Sprawdzanie, czy pamięć jest utrwalana

Pierwsze wywołanie zapisuje ten fakt w magazynie danych w pamięci. Drugie wywołanie dotyczy zapamiętanego faktu w osobnym żądaniu. Jeśli magazyn pamięci jest poprawnie skonfigurowany, odpowiedź wspomina o tej samej nazwie i preferencjach żywieniowych podanych w pierwszym żądaniu. Wyodrębnianie danych z pamięci odbywa się asynchronicznie, więc odczekaj kilka sekund między dwoma wywołaniami, aby magazyn mógł zindeksować pamięć.

Uprzątnij zasoby

Usuń zasoby po zakończeniu, aby zatrzymać naliczanie opłat.

Aby usunąć magazyn pamięci, użyj polecenia AIProjectClient. Uruchom ten skrypt w środowisku Python, w którym zainstalowano pakiety azure-ai-projects i azure-identity (na przykład uruchom polecenie 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())

Usuń agenta i jego zasoby Azure:

Warning

Jeśli bieżące azd środowisko utworzyło projekt Foundry, azd down trwale usuwa grupę zasobów projektu oraz wszystkie zawarte w niej zasoby. Jeśli podczas inicjowania wybrano istniejący projekt, azd down pozostawi projekt, jego grupę zasobów, hostowanego agenta i inne zasoby szybkiego startu. Aby usunąć zasoby, których już nie potrzebujesz z istniejącego projektu, usuń je oddzielnie.

azd down

Aby usunąć magazyn pamięci, użyj tego samego wzorca skryptu z nazwą magazynu pamięci:

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

Jeśli utworzysz dedykowaną grupę zasobów lub projekt dla tego przewodnika Szybki start, usuń tę grupę zasobów lub ten projekt z portalu Azure, gdy wdrożenie czatu, wdrożenie osadzeń lub hostowany agent nie będą już potrzebne.

Kod wdrożenia usuwa już wersję hostowanego agenta i przywraca poprzednią konfigurację punktu końcowego po zakończeniu. Aby usunąć magazyn w pamięci, dodaj ten kod do aplikacji konsolowej, w której zainstalowano pakiety Azure.AI.Projects (wersja wstępna) i 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}'.");

Jeśli utworzysz dedykowaną grupę zasobów lub projekt dla tego przewodnika Szybki start, usuń tę grupę zasobów lub ten projekt z portalu Azure, gdy wdrożenie czatu, wdrożenie osadzeń lub hostowany agent nie będą już potrzebne.

Troubleshooting

Problem Solution
Wdrożony agent nie ma pamięci lub MEMORY_STORE_NAME jest pusty Upewnij się, że hook postprovision został uruchomiony podczas azd provision i że w azure.yaml ustawiono MEMORY_STORE_NAME. Uruchom ponownie azd provision, aby ponownie uruchomić hook.
Zapisywanie pamięci kończy się niepowodzeniem z powodu błędu 401 , a magazyn pozostaje pusty Upewnij się, że wywołujący ma już dostęp Foundry User w zakresie projektu Foundry, i przyznaj rolę Cognitive Services OpenAI User w tym samym zakresie swojej tożsamości oraz tożsamości środowiska uruchomieniowego wdrożonego agenta.
azd provision niepowodzenie z powodu błędu uprawnień Upewnij się, że Twoje konto ma role w projekcie wymienione w wymaganiach wstępnych.
project.beta.memory_stores.create(...) kończy się niepowodzeniem przy użyciu Authentication to the Azure OpenAI resource failed Potwierdź, że Twoja tożsamość ma już przypisaną rolę Użytkownik usługi Foundry w zakresie projektu Foundry, a także rolę Użytkownik OpenAI usługi Cognitive Services w tym zakresie. Sprawdź również, czy AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME wskazuje na poprawne wdrożenie modelu osadzania.
Wdrożenie w Pythonie kończy się powodzeniem, ale drugie wywołanie nie przywołuje zapisanego faktu Poczekaj kilka sekund przed drugim wywołaniem, aby magazyn pamięci zakończył indeksowanie, a następnie ponownie uruchom skrypt.
Ten agent nie pamięta faktu, który został mu przekazany Poczekaj kilka sekund po zapisaniu faktu przed wykonaniem zapytania, aby magazyn zakończył indeksowanie pamięci.
Agent nie może odczytywać ani zapisywać pamięci po wdrożeniu Upewnij się, że hook postprovision utworzył repozytorium danych w tym samym projekcie, do którego wdrożono agenta.

Czego się nauczyłeś

W ramach tego szybkiego przewodnika wykonasz następujące czynności:

  • Utworzono magazyn pamięci Foundry z funkcją profilu użytkownika.
  • Wdrożono hostowanego agenta, który odczytuje dane z magazynu i zapisuje je w nim za pośrednictwem FoundryMemoryProvider, korzystając z interfejsu wiersza polecenia Azure Developer CLI, zestawu SDK dla języka Python lub zestawu SDK .NET.
  • Zweryfikowano, że agent pamięta informacje o użytkowniku w oddzielnych sesjach, zarówno lokalnie przy użyciu interfejsu wiersza polecenia Azure Developer CLI, jak i zdalnie przy użyciu zestawu SDK języka Python lub platformy .NET po wdrożeniu.

Następny krok

Ocena hostowanego agenta

Treści powiązane

  • Ostatnia aktualizacja o