Hızlı Başlangıç: Barındırılan aracıya kalıcı bellek verme

Important

Bu makalede önizleme olarak işaretlenmiş öğeler şu anda önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve Microsoft üretim iş yükleri için bunu önermez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Bu hızlı başlangıçta, Foundry bellek deposu tarafından yedeklenen barındırılan bir aracıya kalıcı, anlamsal bellek verirsiniz. Hafıza olmadan, her konuşma sıfırdan başlar. Bir bellek deposuyla, temsilci bir kullanıcı hakkında ad veya diyet tercihi gibi kararlı olguları korur ve bunları sonraki oturumlarda hatırlar.

İki bölümü tamamlarsınız:

• Bir bellek deposu oluşturun ve bunu aracıya bağlayın. Azure Developer CLI akışında, azd provision sonrasında birlikte gelen bir sağlama kancası çalışır. Python yolunda, depoyu doğrudan SDK ile oluşturursunuz. Mağaza, kullanıcı profili belleklerini ayıklamak ve dizine eklemek için bir sohbet modeli ve ekleme modeli kullanır.
• Sağlayıcı, her model çağrısından önce ilgili anıları alır ve her dönüş sonrasında mağazayı yeni olgularla güncelleştirir.

Aracı kodu, bellek sağlayıcısı ve kimlik doğrulaması, Foundry bellek örneğinden gelir, bu nedenle uygulama yerine iş akışına odaklanırsınız.

GitHub Copilot gibi bir kodlama aracısı kullanıyorsanız, Microsoft Foundry Skill bellek deponuzu sağlamaya, barındırılan aracınıza bağlamaya ve geri çağırma davranışını test etmeye yardımcı olabilir.

Prerequisites

Bu hızlı başlangıç, barındırılan aracı zincirini temel alır. İlk olarak Azure aboneliğini, proje rollerini, Python, Azure Geliştirici CLI'sini () ve uzantıyı kapsayan barındırılan aracı hızlı başlangıcında azdmicrosoft.foundry tamamlayın.

Bu yolda, örneği oluşturmak, bellek deposunu paketlenmiş bir postprovision kancası aracılığıyla hazırlamak, aracıyı yerel olarak çalıştırmak ve dağıtmak için Azure Developer CLI'yi kullanırsınız.

Bu yolda, AIProjectClient.beta.memory_stores.create(...) ile bellek deposunu oluşturmak, barındırılan ajan kodunu yeni bir sürüm olarak karşıya yüklemek, trafiği geçici olarak bu sürüme yönlendirmek ve aynı oturum açmış kullanıcının ayrı çağrılar arasında hatırlandığını doğrulamak için Python SDK'sını kullanırsınız.

Bu yolda kullanılan Python paketlerini yükleyin:

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

Bu yoldaki .NET SDK'sını kullanarak AIProjectClient.MemoryStores.CreateMemoryStore(...) ile bellek deposunu oluşturun, barındırılan aracı kodunu yeni bir sürüm olarak karşıya yükleyin, trafiği geçici olarak buna yönlendirin ve oturum açmış aynı kullanıcının ayrı çağrılar arasında hatırlandığını doğrulayın.

Ayrıca .NET 10 SDK veya sonraki bir sürümüne de ihtiyacınız vardır.

Ayrıca, Foundry projenizde gibi text-embedding-3-smallbir ekleme modeli dağıtımına da ihtiyacınız vardır. Bellek deposu, bellekleri dizine almak için bunu kullanır. Ajanın sohbet modeli olarak, örneğin gpt-4o, barındırılan ajanlar için halihazırda kullandığınız dağıtım kullanılabilir.

Kimliğinizin, barındırılan aracı önkoşulları aracılığıyla Foundry proje kapsamında Foundry User rolüne sahip olması ve ayrıca aynı kapsamda Cognitive Services OpenAI User rolüne de sahip olması gerekir. Bellek deposu, Foundry projesinin veri düzlemi erişimine ek olarak gömme modeli dağıtımını kullanır. OpenAI rolü olmadan bellek yazma işlemleri bir 401 hatayla başarısız olur ve depo boş kalır.

Important

Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.

1. Adım: Barındırılan aracıyı başlatma

Foundry bellek örneğinden bir barındırılan aracı başlatın. Başlatma, bellek deposu sağlama komut dosyası ve sağlama kancası da dahil olmak üzere örnek dosyaları, src/ altında yeni bir hizmet dizinine kopyalar. Bu komutları boş bir dizinde çalıştırın.

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"

Aboneliğinizi, projenizi ve model dağıtımınızı seçmek için istemleri izleyin. Dökümhane projeniz yoksa, azd ai agent init bir proje oluştururken size yol gösterir.

2. Adım: Tek komutla sağlamayı etkinleştirme

Örnek, bellek deposunu oluşturan ve postprovision öğesini her çalıştırdığınızda bunu aracıya otomatik olarak bağlayan bir azd provision kancası içerir. azure.yaml tarafından oluşturulan azd ai agent init dosyasının en üst düzeyine kancayı kaydedin.

azure.yaml öğesini açın ve aşağıdaki üst düzey bloğu ekleyin. <agent-name> altında başlatma işleminin oluşturduğu hizmet klasörüyle src/ öğesini değiştirin:

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

Kanca kendini konumlandıran ve idempotenttir. azd hangi dizinden çağrılırsa çağrılsın doğru şekilde çalışır ve yeniden çalıştırmalar mevcut depoyu olduğu gibi bırakır.

Uyarı

postprovision öğesini azure.yaml öğesinin en üst düzeyinde kaydedin. Hizmet kapsamındaki kancalar yalnızca paketleme ve dağıtım yaşam döngüsünü destekler, kaynak sağlamayı desteklemez.

3. Adım: Bellek depoyu ve Azure kaynaklarını sağlama

1. Bağlantıyı, veri deposunun anlamsal belleğine güç sağlayan gömme modeli dağıtımına yöneltin:

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

2. Sağlama:

   azd provision
   

azd provision Foundry projenizi ve sohbet modeli dağıtımınızı oluşturur veya yeniden kullanır. Ardından postprovision hook:

• Kullanıcı profili özelliği etkinleştirilmiş bellek deposunu oluşturur ve bunu hizmet üzerinde doğrular.
• MEMORY_STORE_NAME, aracının bu depoyu okuyup yazmasını sağlar. Hook, yerel çalıştırmalar için adı azd ortamınıza ve azure.yaml içindeki hizmet ortamına kaydeder; böylece azd deploy bunu kapsayıcıya gönderir.

CLI yolu, ayrı bir create memory store komutu göstermez; çünkü paketlenmiş kanca bu oluşturma mantığını sizin için azd provision işleminin bir parçası olarak çalıştırır.

Hook, mağaza adını varsayılan olarak agent_framework_memory değerine ayarlar. Farklı bir ad kullanmak için, provision etmeden önce bunu ayarlayın:

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

4. Adım: Ajanı yerel olarak çalıştırın

1. Aracıyı başlatın:

   azd ai agent run
   

   Bu komut bir sanal ortam oluşturur, bağımlılıkları yükler ve aracıya üzerinde http://localhost:8088hizmet eder. Hook, MEMORY_STORE_NAME ortamınızda azd öğesini zaten ayarladığı için ek yapılandırmaya gerek yoktur. Önizleme paketleri kurulum sırasında pip uyarıları üretebilir. Bu uyarılar engelleyici değildir.

2. Ayrı bir terminalde temsilciye kendinizle ilgili bir gerçeği söyleyin:

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

3. Yeni bir oturum başlatın ve ajanın bu bilgiyi konuşma geçmişinden değil de depodan hatırlayıp hatırlamadığını doğrulayın:

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

   Temsilci, yanıtında adınızı ve tercihinizi belirtir; bu da bunları bellek deposundan aldığını kanıtlar.

5. Adım: Foundry Ajan Hizmetine Dağıtma

Ajan kaynak kodunu dağıtın. azd kaynağı ZIP dosyası olarak paketler ve bağımlılıkları çözümleyen ve barındırılan aracıyı uzaktan oluşturan Foundry'ye yükler. postprovision kancası MEMORY_STORE_NAME değerini zaten azure.yaml içine yazar, bu nedenle dağıtılan ajan aynı depoyu okur:

azd deploy

Komut tamamlandığında, çıktı ajan oyun alanı ve ajan uç noktası bağlantılarını gösterir. Dağıtılan aracıdaki oturumlar arasında belleği doğrulayın. Bir bilgiyi depolayın:

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

Ardından yeni bir oturumda hatırlayın:

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

Dağıtılan ajan, hatırlanan ad ve alerjiyle yanıt verir.

1. Adım: Dökümhane projesi oluşturma veya seçme

1. Foundry portalını açın ve bir Dökümhane projesi oluşturun veya var olan bir projeyi seçin.

2. Projede şunları dağıtın:

   • gpt-5.4-mini gibi sohbet edebilen bir model.
   • text-embedding-3-small gibi bir gömme modeli.

3. Genel Bakış'tan proje uç noktasını ve Derleme>Dağıtımları'ndan dağıtım adlarını kopyalayın.

2. Adım: Dökümhane bellek örneğini indirme

Foundry örnekleri deposunu klonlayın:

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

Dağıtım betikleri için bir çalışma klasörü oluşturun. Bu klasörde şu değerlere sahip bir .env dosya oluşturun:

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>

3. Adım: Bellek depoyu Python ile sağlama

Bu betiği yeniden çalıştırmak güvenlidir. Önce bellek deposunun zaten var olup olmadığını denetlemek için çağırır get(...) . Yalnızca mağaza bulunamazsa arar create(...) .

ile aynı çalışma klasöründe provision_memory_store.pyadlı .env bir dosya oluşturun:

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

Betiği Çalıştırın:

python provision_memory_store.py

4. Adım: Barındırılan aracıyı Python ile dağıtma

ile aynı çalışma klasöründe deploy_memory_agent.pyadlı .env bir dosya oluşturun:

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

Betiği Çalıştırın:

python deploy_memory_agent.py

Bu betik bellek örneğini yeni bir barındırılan aracı sürümü olarak karşıya yükler, barındırılan aracıyı geçici olarak bu sürüme yönlendirir, oturum açmış aynı kullanıcı olarak onu iki kez çağırır ve işlem tamamlandığında önceki uç nokta yapılandırmasını geri yükler.

5. Adım: Belleğin kalıcı olduğunu doğrulama

İlk çağrı, bilgiyi bellek deposunda saklar. İkinci çağrı, hatırlanan bilgiyi ayrı bir istekte ister. Bellek deposu doğru yapılandırıldıysa, yanıt ilk istekte sağladığınız aynı adı ve diyet tercihini belirtmelidir.

1. Adım: Dökümhane projesi oluşturma veya seçme

1. Foundry portalını açın ve bir Dökümhane projesi oluşturun veya var olan bir projeyi seçin.

2. Projede şunları dağıtın:

   • gpt-4o gibi sohbet edebilen bir model.
   • text-embedding-3-small gibi bir gömme modeli.

3. Genel Bakış'tan proje uç noktasını ve Derleme>Dağıtımları'ndan dağıtım adlarını kopyalayın.

2. Adım: Dökümhane bellek örneğini indirme

Foundry örnekleri deposunu klonlayın:

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

C# hosted-agent örneği samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/src/foundry-memory-rag altında bulunur. Sonraki adımlar bu klasörü barındırılan aracı sürümü olarak dağıtır. Örnek, dağıtım kodunun kapsayıcıda ayarladığı bu ortam değişkenlerinden yapılandırmasını okur:

Variable	Description
FOUNDRY_PROJECT_ENDPOINT	Dökümhane proje uç noktası.
AZURE_AI_MODEL_DEPLOYMENT_NAME	Sohbet modeli dağıtım adı.
AZURE_AI_EMBEDDING_DEPLOYMENT_NAME	Model dağıtım adı ekleniyor.
AZURE_AI_MEMORY_STORE_ID	Bellek deposu adı. Varsayılan değer foundry-memory-rag-store’dır.

3. Adım: C ile bellek depounu sağlama#

bir .NET konsol uygulaması oluşturun ve paketleri yükleyin. Bellek deposu API'leri önizleme aşamasında olduğundan yayın Azure.AI.Projects öncesi paketini yükleyin:

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

Bu kodun yeniden çalıştırılması güvenlidir. İlk olarak mağazanın zaten var olup olmadığını denetlemek için arar GetMemoryStore(...) ve yalnızca mağaza bulunamazsa arar CreateMemoryStore(...) . Program.cs öğesini aşağıdaki kodla değiştirin ve chatModel, embeddingModel ve endpoint öğelerini projenize ait değerlere ayarlayın:

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

Uygulamayı çalıştırın:

dotnet run

4. Adım: Barındırılan aracıyı C ile dağıtma#

Dağıtım kodu için ikinci bir konsol uygulaması oluşturun:

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

içinde Program.cs, mevcut kodu aşağıdaki kodla değiştirin. chatModel, embeddingModel, samplePath ve endpoint öğelerini kendi değerlerinize ayarlayın. samplePath 2. Adımda kopyaladığınız kaynak klasörün tam yoludur foundry-memory-rag :

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

Uygulamayı çalıştırın:

dotnet run

Bu kod, bellek örneğini yeni bir barındırılan aracı sürümü olarak karşıya yükler, barındırılan aracıyı geçici olarak bu sürüme yönlendirir, oturum açmış aynı kullanıcı olarak onu iki kez çağırır ve işlem tamamlandığında önceki uç nokta yapılandırmasını geri yükler.

5. Adım: Belleğin kalıcı olduğunu doğrulama

İlk çağrı, bilgiyi bellek deposunda saklar. İkinci çağrı, hatırlanan bilgiyi ayrı bir istekte ister. Bellek deposu doğru yapılandırıldıysa, yanıt ilk istekte sağladığınız aynı ad ve diyet tercihini ifade eder. Belleğin çıkarılması eşzamansızdır, bu nedenle depolama alanının belleği dizine alabilmesi için iki çağrı arasında birkaç saniye bekleyin.

Kaynakları temizle

İşiniz bittiğinde kaynakları silin, böylece ücretlendirmeyi durdurun.

Bellek depoyu silmek için kullanın AIProjectClient. Bu betiği, azure-ai-projects ve azure-identity paketlerinin yüklü olduğu bir Python ortamında çalıştırın (örneğin, pip install "azure-ai-projects>=2.3.0" komutunu çalıştırın):

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

Aracıyı ve Azure kaynaklarını silin:

Warning

Geçerli azd ortam Foundry projesini oluşturduysa, azd down projenin kaynak grubunu ve içindeki her şeyi kalıcı olarak siler. Başlatma sırasında mevcut bir projeyi seçtiyseniz projeyi, azd down kaynak grubunu, barındırılan aracıyı ve diğer hızlı başlangıç kaynaklarını yerinde bırakır. Artık ihtiyacınız olmayan kaynakları mevcut projeden silmek için bunları ayrı olarak silin.

azd down

Bellek deposunu silmek için, bellek deposu adınızla aynı betik desenini kullanın:

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

Bu hızlı başlangıç için ayrılmış bir kaynak grubu veya proje oluşturduysanız sohbet dağıtımına, dağıtım eklemeye veya barındırılan aracıya artık ihtiyacınız kalmadıktan sonra bunu Azure portalından silin.

Dağıtım kodu barındırılan aracı sürümünü zaten siler ve tamamlandığında önceki uç nokta yapılandırmasını geri yükler. Bellek depoyu silmek için bu kodu (ön sürüm) ve Azure.Identity paketlerin yüklü olduğu Azure.AI.Projects bir konsol uygulamasına ekleyin:

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

Bu hızlı başlangıç için ayrılmış bir kaynak grubu veya proje oluşturduysanız sohbet dağıtımına, dağıtım eklemeye veya barındırılan aracıya artık ihtiyacınız kalmadıktan sonra bunu Azure portalından silin.

Sorun giderme

Issue	Solution
Dağıtılan aracıda bellek yok veya MEMORY_STORE_NAME boş	postprovision sırasında azd provision hook’un çalıştığını ve azure.yaml öğesinin MEMORY_STORE_NAME olarak ayarlandığını doğrulayın. azd provision öğesini, hook’u yeniden çalıştırmak için yeniden çalıştırın.
Bellek yazma işlemleri bir 401 hatayla başarısız olur ve depo boş kalır	Çağıranın, Foundry projesi kapsamında zaten Foundry Kullanıcısı erişimine sahip olduğunu doğrulayın ve aynı kapsamda Bilişsel Hizmetler OpenAI Kullanıcısı rolünü kendi kimliğinize ve dağıtılan ajanın çalışma zamanı kimliğine atayın.
azd provision izin hatasıyla başarısız oluyor	Kimliğinizin Önkoşullar bölümünde listelenen proje rollerine sahip olduğunu onaylayın.
project.beta.memory_stores.create(...), Authentication to the Azure OpenAI resource failed ile başarısız olur	Kimliğinizin, Foundry proje kapsamında zaten Foundry User erişimine sahip olduğunu ve ayrıca bu kapsamda Cognitive Services OpenAI User rolüne sahip olduğunu doğrulayın. Ayrıca AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME öğesinin geçerli bir gömme dağıtımını işaret ettiğini doğrulayın.
Python dağıtımı başarılı olur, ancak ikinci çağrı depolanan olguyu geri çağırmıyor	bellek deposunun dizin oluşturmayı tamamlayıp betiği yeniden çalıştırması için ikinci çağrıdan önce birkaç saniye daha bekleyin.
Ajan, paylaştığınız bir bilgiyi hatırlamıyor	Sorgulamadan önce bir olguyu depoladıktan sonra birkaç saniye bekleyin, böylece depo belleğin dizinini oluşturmayı tamamlar.
Ajan, dağıtımdan sonra bellekleri okuyamaz veya yazamaz	postprovision kancasının, store’u ajanın dağıtıldığı projeyle aynı projede oluşturduğunu doğrulayın.

Öğrendiklerin

Bu hızlı başlangıç rehberinde şunları yapacaksınız:

• Kullanıcı profili özelliğine sahip bir Foundry bellek deposu oluşturuldu.
• Azure Developer CLI, Python SDK veya .NET SDK kullanarak FoundryMemoryProvider aracılığıyla depoya okuyan ve depoya yazan barındırılan bir aracı dağıtın.
• Aracının, Azure Geliştirici CLI ile yerel olarak veya dağıtımdan sonra Python veya .NET SDK ile uzaktan ayrı oturumlarda kullanıcı olgularını geri çağırdığını doğrulandı.

Sonraki adım

Barındırılan aracınızı değerlendirme

İlgili içerik

• Barındırılan ajanlar nedir?
• Aracıya bellek ekleme
• Hızlı Başlangıç ​​Kılavuzu: İlk Barındırılan Ajandınızı Dağıtın
• Barındırılan aracıları yönetme