Foundry Agent Service'te bellek oluşturma ve kullanma (önizleme)

Önemli

Foundry Agent Hizmeti'ndeki Bellek (önizleme) ve Bellek Deposu API'si (önizleme), Azure aboneliğiniz kapsamında size lisanslanır ve Microsoft Ürün Koşulları, Microsoft Ürünleri ve Hizmetleri Veri Koruma Eki ve Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları belgelerinde "Önizlemeler" için geçerli olan koşullara tabidir.

En son önizleme, aşağıdakiler dahil olmak üzere yeni özellikler ve geliştirmeler sunar:

  • Tek tek bellek kayıtlarını oluşturmak, okumak, güncelleştirmek, listelemek ve silmek için bellek öğesi işlemleri.
  • Yeni oluşturulan bellek depoları için varsayılan TTL de dahil olmak üzere depolama düzeyi varsayılan bekletme denetimleri.
  • Eşzamanlı bellek komutunun doğrudan hatırla veya unut davranışı.

Foundry Aracısı Hizmeti'ndeki bellek, yönetilen, uzun vadeli bir bellek çözümüdür. Oturumlar, cihazlar ve iş akışları arasında aracı sürekliliği sağlar. Bellek depoları oluşturup yöneterek, kullanıcı tercihlerini koruyan, konuşma geçmişini koruyan ve kişiselleştirilmiş deneyimler sunan aracılar oluşturabilirsiniz.

Bellek depoları kalıcı depolama görevi görür ve her aracıyla ilgili bilgi türlerini tanımlar. Güvenli ve yalıtılmış deneyimler sağlamak için kullanıcılar arasında belleği bölümleyen parametresini kullanarak scope erişimi denetleyebilirsiniz.

Bu makalede bellek depolarını oluşturma, yönetme ve kullanma işlemleri açıklanmaktadır. Kavramsal bilgi için bkz Foundry Agent Service'de Bellek.

İlk uçtan uca başarı için şu yolu izleyin:

  1. Aracı için bir bellek deposu oluşturun.
  2. Bellek arama aracını aracıya ekleyin.
  3. Konuşma oluşturun, tercih gönderin ve hizmetin bunu anımsayabilmesi için yapılandırılmış güncelleştirme gecikmesini bekleyin.
  4. Aynı örnekte yeni bir konuşma başlatın ve aracının tercihi geri çağırdığını onaylamak için ilgili bir soru sorun.

Belleği nasıl doğrudan denetlemeniz gerektiğini temel alan bir iş akışı seçin:

Scenario Şununla başla Bunu kullanarak
Yönetim Bellek deposu oluşturma Depoları ve bekletme ayarlarını yapılandırın, güncelleştirin, listeleyin veya silin.
Komutlar Doğrudan anımsama veya unutma davranışı uygulama Bilgileri hemen anımsamak veya unutmak için açık bir kullanıcı isteğini kabul edin.
Öğeler Bellek öğelerini yönetme Tek tek kayıtları doğrudan oluşturun, inceleyin, güncelleştirin veya silin.

Örnek kapsam

Onay işareti, bu makalenin bu dil için bir örnek içerdiği anlamına gelir. Tire, bir örneğin şu anda dahil olmadığı anlamına gelir; SDK'nın işlemi destekleyip desteklemediğini göstermez.

Yeteneği Python SDK'sı C# SDK'sı JavaScript SDK'sı Java SDK'sı REST API
Bellek depolarını oluşturma, güncelleştirme, listeleme ve silme ✔️ ✔️ ✔️ ✔️ ✔️
İstem aracısına bellek ekleme ✔️ ✔️ ✔️ ✔️ ✔️
Bellekleri güncelleştirme ve arama ✔️ ✔️ ✔️ ✔️ ✔️
Doğrudan anımsa veya unut komutlarını uygulama ✔️ — ✔️ ✔️ ✔️
Bellek öğelerini oluşturma, okuma, güncelleştirme, listeleme ve silme ✔️ — ✔️ ✔️ ✔️

Önkoşullar

Yetkilendirme ve izinler

Üretim dağıtımları için rol tabanlı erişim denetimini kullanın. Roller uygun değilse, bu bölümü atlayın ve bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Rol tabanlı erişimi yapılandırmak için:

  1. Azure portalında oturum açın.

  2. Projenizde:

    1. Sol bölmeden Kaynak Yönetimi>Kimliği'ni seçin.
    2. Sistem tarafından atanan yönetilen kimliği etkinleştirmek için anahtarı kullanın.

  3. Projenizi içeren kaynakta:

    1. Sol bölmeden Erişim denetimi (IAM) öğesini seçin.

    2. Rol ataması ekle'yi> seçin.

    3. Foundry User'ı projenizin yönetilen kimliğine atayın.

      Önemli

      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.

Ortamınızı ayarlama

Gerekli paketleri yükleyin:

pip install "azure-ai-projects>=2.3.0" azure-identity

Gerekli paketleri yükleyin:

dotnet add package Azure.AI.Projects --version 2.1.0-beta.4
dotnet add package Azure.AI.Projects.Agents --version 2.1.0-beta.4
dotnet add package Azure.AI.Extensions.OpenAI --version 2.1.0-beta.4
dotnet add package Azure.Identity

Gerekli paketleri yükleyin:

npm install @azure/ai-projects @azure/identity

2.4.0 ile @azure/ai-projects Node.js 22 veya üzerini kullanın.

Gerekli paketleri yükleyin:

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-ai-agents</artifactId>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

Proje uç noktanız ve model dağıtım adlarınız için ortam değişkenlerini ayarlayın:

export FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"
export MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME="<chat-model-deployment-name>"
export MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME="<embedding-model-deployment-name>"

Proje uç noktanız, model dağıtımlarınız, API sürümünüz ve erişim belirteciniz için ortam değişkenlerini ayarlayın:

FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"
MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME="<chat-model-deployment-name>" # For example, gpt-5.2
MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME="<embedding-model-deployment-name>" # For example, text-embedding-3-small
API_VERSION="2025-11-15-preview"

# Get a short-lived access token using Azure CLI
ACCESS_TOKEN="$(az account get-access-token --resource https://ai.azure.com/ --query accessToken -o tsv)"

Kapsamı anlama

parametresi, scope belleğin nasıl bölümlendiğini denetler. Bellek deposundaki her kapsam, izole bir bellek öğesi koleksiyonu tutar. Örneğin, belleği olan bir müşteri destek aracısı oluşturursanız, her müşterinin kendi ayrı belleği olmalıdır.

Geliştirici olarak, bellek öğelerini depolamak ve almak için kullanılan anahtarı seçersiniz. Doğru yaklaşım, belleğe nasıl erişdiğinize bağlıdır.

Bellek arama aracı aracılığıyla

Bellek arama aracını bir aracıya eklediğinizde, tanımlayıcıları sabit kodlamadan kullanıcı başına bellek yalıtımını etkinleştirmek için scope olarak ayarlayın{{$userId}}. Sistem, iki kaynaktan gelen her yanıt çağrısında son kullanıcının kimliğini otomatik olarak çözümler:

  • x-memory-user-id istek üst bilgisi: Varsa, üst bilgi değeri kullanıcı kimliği olarak kullanılır. Hizmetinizin API'yi son kullanıcı adına çağırdığı ara sunucu veya arka uç senaryolarında bunu kullanın.

  • Microsoft Entra kimlik doğrulama belirteci: Üst bilgi ayarlı değilse, sistem çağıranın kiracı kimliğine (TID) ve nesne kimliğine (OID) geri döner. Bu, kullanıcıların doğrudan Microsoft Entra ile kimlik doğrulaması yaptığı ön uç senaryolarında varsayılandır.

Kullanıcı başına yalıtıma ihtiyacınız yoksa, bunun yerine statik scope bir değer kullanın.

Düşük düzeyli bellek API'leri aracılığıyla

Bellek API'lerini doğrudan çağırdığınızda, her istekte açıkça belirtinscope. Sisteminizden evrensel olarak benzersiz tanımlayıcı (UUID) veya başka bir kararlı tanımlayıcı gibi statik bir değer geçirebilirsiniz. Bu işlemler için otomatik kimlik ayıklama desteklenmez.

Bellek deposu oluşturma

Bellek erişimi ve iyileştirme için net sınırlar oluşturmak üzere her aracı için ayrılmış bir bellek deposu oluşturun. Bellek deposu oluşturduğunuzda, bellek içeriğinizi işleyen sohbet modelini ve ekleme modeli dağıtımlarını belirtin.

Ayıklama davranışını ve bekletme varsayılanlarını denetlemek için bellek deposu seçeneklerini kullanın. En son önizlemede yordamsal belleği etkinleştirebilir ve yeni oluşturulan bellek girişleri için varsayılan TTL (saniye) ayarlayabilirsiniz.

import os
from datetime import timedelta
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MemoryStoreDefaultDefinition, MemoryStoreDefaultOptions
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

memory_store_name = "my_memory_store"

# Specify memory store options
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
    procedural_memory_enabled=True,
    default_ttl_seconds=timedelta(days=30),
    user_profile_details="Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
)

# Create memory store
chat_model = os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"]
embedding_model = os.environ["MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME"]

definition = MemoryStoreDefaultDefinition(
    chat_model=chat_model,
    embedding_model=embedding_model,
    options=options
)

memory_store = project_client.beta.memory_stores.create(
    name=memory_store_name,
    definition=definition,
    description="Memory store with procedural memory and 30-day default TTL",
)

print(f"Created memory store: {memory_store.name}")

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

#pragma warning disable AAIP001

var projectEndpoint = Environment.GetEnvironmentVariable(
    "FOUNDRY_PROJECT_ENDPOINT");
var chatModel = Environment.GetEnvironmentVariable(
    "MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME");
var embeddingModel = Environment.GetEnvironmentVariable(
    "MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME");

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

var memoryStoreName = "my_memory_store";

// Specify memory store options
MemoryStoreDefaultDefinition memoryStoreDefinition = new(
    chatModel: chatModel,
    embeddingModel: embeddingModel
);
memoryStoreDefinition.Options = new(
    isUserProfileEnabled: true,
    isChatSummaryEnabled: true);
memoryStoreDefinition.Options.UserProfileDetails =
    "Avoid irrelevant or sensitive data, such as age, "
    + "financials, precise location, and credentials";

// Create memory store
MemoryStore memoryStore = projectClient.MemoryStores.CreateMemoryStore(
    name: memoryStoreName,
    definition: memoryStoreDefinition,
    description: "Memory store for customer support agent"
);

Console.WriteLine($"Created memory store: {memoryStore.Name}");

import { DefaultAzureCredential } from "@azure/identity";
import type {
  MemoryStoreDefaultDefinition,
  MemoryStoreDefaultOptions,
} from "@azure/ai-projects";
import { AIProjectClient } from "@azure/ai-projects";

const projectEndpoint =
  process.env["FOUNDRY_PROJECT_ENDPOINT"] ||
  "<project endpoint>";
const chatModelDeployment =
  process.env["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"] ||
  "<chat model deployment name>";
const embeddingModelDeployment =
  process.env["MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME"] ||
  "<embedding model deployment name>";

const memoryStoreName = "my_memory_store";

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

const memoryOptions: MemoryStoreDefaultOptions = {
  user_profile_enabled: true,
  chat_summary_enabled: true,
  procedural_memory_enabled: true,
  default_ttl_seconds: 30 * 24 * 60 * 60,
  user_profile_details:
    "Avoid irrelevant or sensitive data, such as age, " +
    "financials, precise location, and credentials",
};

const definition: MemoryStoreDefaultDefinition = {
  kind: "default",
  chat_model: chatModelDeployment,
  embedding_model: embeddingModelDeployment,
  options: memoryOptions,
};

const memoryStore = await project.beta.memoryStores.create(
  memoryStoreName,
  definition,
  {
    description: "Memory store with procedural memory and 30-day default TTL",
  },
);

console.log(
  `Created memory store: ${memoryStore.name} (${memoryStore.id})`,
);

import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.BetaMemoryStoresClient;
import com.azure.ai.agents.models.MemoryStoreDefaultDefinition;
import com.azure.ai.agents.models.MemoryStoreDefaultOptions;
import com.azure.ai.agents.models.MemoryStoreDetails;
import com.azure.identity.DefaultAzureCredentialBuilder;

String projectEndpoint = System.getenv("FOUNDRY_PROJECT_ENDPOINT");
String chatModel = System.getenv("MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME");
String embeddingModel =
  System.getenv("MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME");

BetaMemoryStoresClient memoryStoresClient = new AgentsClientBuilder()
  .credential(new DefaultAzureCredentialBuilder().build())
  .endpoint(projectEndpoint)
  .beta()
  .buildBetaMemoryStoresClient();

String memoryStoreName = "my_memory_store";

MemoryStoreDefaultDefinition definition =
  new MemoryStoreDefaultDefinition(chatModel, embeddingModel)
    .setOptions(new MemoryStoreDefaultOptions(true, true));

MemoryStoreDetails memoryStore = memoryStoresClient.createMemoryStore(
  memoryStoreName,
  definition,
  "Memory store for customer support agent",
  null);

System.out.println("Created memory store: " + memoryStore.getName());

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_memory_store",
    "description": "Memory store with procedural memory and 30-day default TTL",
    "definition": {
      "kind": "default",
      "chat_model": "'"${MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME}"'",
      "embedding_model": "'"${MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME}"'",
      "options": {
        "chat_summary_enabled": true,
        "user_profile_enabled": true,
        "procedural_memory_enabled": true,
        "default_ttl_seconds": 2592000,
        "user_profile_details": "Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
      }
    }
  }'

Ipucu

  • Kalan Python, C#, TypeScript ve Java kod parçacıkları, bellek deposu oluşturma bölümünde tanımlanan istemci ve değişkenler üzerinde oluşturulur. Bu kod parçacıklarını bağımsız olarak çalıştırırsanız, bu bölümdeki içeri aktarma ve istemci başlatma kodunu ekleyin.

  • Bu makaledeki C# kod parçacıkları zaman uyumlu yöntemleri kullanır. Zaman uyumsuz kullanım için bkz. memory arama aracı ve memory store örnekleri.

Belleği özelleştirme

Belleği verimli, ilgili ve gizliliğe saygılı tutmak için aracının hangi bilgileri depolayanı özelleştirin. Acentenin işlevi için kritik olan veri türlerini belirtmek için user_profile_details parametresini kullanın.

Örneğin, bir seyahat acentesi için "uçuş operatörü tercihi ve diyet kısıtlamaları"na öncelik vermek üzere ayarlayın user_profile_details . Bu odaklanmış yaklaşım, bellek sisteminin hangi ayrıntıların ayıklanacağını, özetleneceğini ve uzun süreli belleğe işleneceğini bilmesine yardımcı olur.

Bu parametreyi belirli veri türlerini dışlamak için de kullanabilir, belleğin zayıf ve gizlilik gereksinimleriyle uyumlu olmasını sağlayabilirsiniz. Örneğin, "yaş, finansal bilgiler, kesin konum ve kimlik bilgileri gibi ilgisiz veya hassas verilerden kaçının" olarak ayarlayın user_profile_details .

TTL ve bekletme ilkelerini yapılandırma

TTL, doğrudan bellek komutlarından, ayıklama ve birleştirmeden veya öğe düzeyinde CRUD işlemlerinden tüm bellekler için geçerlidir. Bir bellek güncelleştirilip birleştirilmişse, hizmet son güncelleştirme zamanını sıfırlar.

TTL yalnızca TTL desteği eklendikten sonra oluşturulan bellek depoları için geçerlidir. Mevcut bellek depolarını etkilemez.

default_ttl_seconds değeri0, süre sonu olmadığını gösterir. Uyumluluk ve kullanıcı verileri yaşam döngüsü gereksinimlerinizle eşleşen bir saklama süresi seçin.

Bellek depolarını güncelleştirme

Bellek depolarını daha iyi yönetmek için description veya metadata gibi bellek deposu özelliklerini güncelleştirin.

# Update memory store properties
updated_store = project_client.beta.memory_stores.update(
    name=memory_store_name,
    description="Updated description"
)

print(f"Updated: {updated_store.description}")

// Update memory store properties
MemoryStore updatedStore = projectClient.MemoryStores.UpdateMemoryStore(
    name: memoryStoreName,
    description: "Updated description"
);

Console.WriteLine($"Updated: {updatedStore.Description}");

const updatedStore = await project.beta.memoryStores.update(
  memoryStoreName,
  {
    description: "Updated description",
  },
);

console.log(`Updated: ${updatedStore.description}`);

import com.azure.ai.agents.models.MemoryStoreDetails;

MemoryStoreDetails updatedStore = memoryStoresClient.updateMemoryStore(
  memoryStoreName,
  "Updated description",
  null);

System.out.println("Updated: " + updatedStore.getDescription());

MEMORY_STORE_NAME="my_memory_store"

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/${MEMORY_STORE_NAME}?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description"
  }'

Bellek depolarını listeleme

Bellek altyapınızı yönetmek ve izlemek için projenizdeki bellek depolarının listesini alın.

# List all memory stores
stores_list = list(project_client.beta.memory_stores.list())

print(f"Found {len(stores_list)} memory stores")
for store in stores_list:
    print(f"- {store.name} ({store.description})")

// List all memory stores
foreach (MemoryStore store in projectClient.MemoryStores.GetMemoryStores())
{
    Console.WriteLine(
        $"Memory store: {store.Name} ({store.Description})");
}

const storeList = project.beta.memoryStores.list();

console.log("Listing all memory stores...");
for await (const store of storeList) {
  console.log(`  - Memory Store: ${store.name} (${store.id})`);
}

import com.azure.ai.agents.models.MemoryStoreDetails;

System.out.println("Listing all memory stores...");
for (MemoryStoreDetails store : memoryStoresClient.listMemoryStores()) {
    System.out.println(
        "  - Memory Store: " + store.getName() + " (" + store.getId() + ")");
}

curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Bellekleri bir aracı kullanarak kullanma

Bellek deposu oluşturduktan sonra, bellek arama aracını bir istem aracısına ekleyebilirsiniz. Bu araç, aracının konuşmalar sırasında bellek deponuzdan okumasını ve yazmasını sağlar. Aracı belleğin nasıl ve ne zaman güncellenmesini kontrol etmek için uygun scope ve update_delay ile yapılandırın.

Ipucu

Bellekleri bireysel bir son kullanıcıya göre sınırlandırmak için, araç tanımında scope'yi "{{$userId}}" olarak ayarlayın ve her yanıt çağrısında x-memory-user-id: <user-id>'yi bir üst bilgi olarak iletin. Sistem, kapsamı bu kullanıcının kimliğine çözümleştirir. Üst bilgi olmadan kapsam çağıranın Microsoft Entra kimliğine (TID ve OID) geri döner. Daha fazla bilgi için bkz. Kapsamı anlama.

from azure.ai.projects.models import MemorySearchPreviewTool, PromptAgentDefinition

# Set scope to associate the memories with
scope = "user_123"

openai_client = project_client.get_openai_client()

# Create memory search tool
tool = MemorySearchPreviewTool(
    memory_store_name=memory_store_name,
    scope=scope,
    update_delay=1, # Wait 1 second of inactivity before updating memories
    # In a real application, set this to a higher value like 300 (5 minutes, default)
)

# Create a prompt agent with memory search tool
agent = project_client.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model=os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"],
        instructions="You are a helpful assistant that answers general questions",
        tools=[tool],
    )
)

print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

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

#pragma warning disable OPENAI001

// Set scope to associate the memories with
string scope = "user_123";

// Create a prompt agent with memory search tool
DeclarativeAgentDefinition agentDefinition = new(model: chatModel)
{
    Instructions = "You are a helpful assistant that answers "
        + "general questions",
};
agentDefinition.Tools.Add(new MemorySearchPreviewTool(
    memoryStoreName: memoryStore.Name,
    scope: scope)
{
    UpdateDelayInSecs = 1, // Wait 1 second of inactivity before updating memories
    // In a real application, set this to a higher value
    // like 300 (5 minutes, default)
});

ProjectsAgentVersion agent =
    projectClient.AgentAdministrationClient.CreateAgentVersion(
        agentName: "MyAgent",
        options: new(agentDefinition));

Console.WriteLine(
    $"Agent created (id: {agent.Id}, name: {agent.Name}, "
    + $"version: {agent.Version})");

// Set scope to associate the memories with
const scope = "user_123";

const agent = await project.agents.createVersion(
  "memory-search-agent",
  {
    kind: "prompt",
    model: chatModelDeployment,
    instructions:
      "You are a helpful assistant that retrieves relevant " +
      "information from the user's memory store to answer their questions.",
    tools: [
      {
        type: "memory_search_preview",
        memory_store_name: memoryStoreName,
        scope: scope,
        update_delay: 1,
      },
    ],
  },
);

console.log(
  `Created agent with memory search tool, agent ID: ${agent.id}, ` +
    `name: ${agent.name}, version: ${agent.version}`,
);

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.MemorySearchPreviewTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;

String scope = "user_123";

AgentsClient agentsClient = new AgentsClientBuilder()
  .credential(new DefaultAzureCredentialBuilder().build())
  .endpoint(projectEndpoint)
  .buildAgentsClient();

MemorySearchPreviewTool memoryTool = new MemorySearchPreviewTool(
  memoryStoreName,
  scope).setUpdateDelaySeconds(1);

PromptAgentDefinition agentDefinition = new PromptAgentDefinition(chatModel)
  .setInstructions("You are a helpful assistant that answers general questions")
  .setTools(java.util.Collections.singletonList(memoryTool));

AgentVersionDetails agent =
  agentsClient.createAgentVersion("MyAgent", agentDefinition);

System.out.println(
  "Agent created (id: " + agent.getId() + ", name: " + agent.getName()
    + ", version: " + agent.getVersion() + ")");

# The agents API uses api-version=v1, which differs from the memory store API version
curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/agents?api-version=v1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyAgent",
    "definition": {
        "kind": "prompt",
        "model": "gpt-5.2",
        "instructions": "You are a helpful assistant that answers general questions",
        "tools": [
            {
              "type": "memory_search_preview",
              "memory_store_name": "my_memory_store",
              "scope": "user_123",
              "update_delay": 1
            }
        ]
    }
}'

Konuşma oluşturma

Artık konuşmalar oluşturabilir ve aracı yanıtları isteyebilirsiniz. Her konuşmanın başlangıcında statik bellekler eklenir, böylece aracı anında ve kalıcı bir bağlama sahip olur. Bağlamsal bellekler, her yanıtı bilgilendirmek için en son iletilere göre sırayla alınır.

Her bir aracı yanıtının ardından, hizmet dahili olarak update_memories metodunu çağırır. Ancak, uzun süreli belleğe gerçek yazma işlemleri update_delay ayarı tarafından tasfiye edilir. Güncelleştirme zamanlanır ve yalnızca yapılandırılan etkinlik dışı kalma süresinden sonra tamamlanır.

Note

Güncelleştirilmiş önizleme şemasında, bellek arama aracı çıkışı eski memories alan yerine bir results koleksiyon kullanır. Ham çıkış yüklerini işlerseniz ayrıştırıcılarınızı uygun şekilde güncelleştirin.

import time

# Create a conversation with the agent with memory tool enabled
conversation = openai_client.conversations.create()
print(f"Created conversation (id: {conversation.id})")

# Create an agent response to initial user message
response = openai_client.responses.create(
    input="I prefer dark roast coffee",
    conversation=conversation.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    # To scope memories to an end user, uncomment:
    # extra_headers={"x-memory-user-id": "<user-id>"},
)

print(f"Response output: {response.output_text}")

# After an inactivity in the conversation, memories will be extracted from the conversation and stored
print("Waiting for memories to be stored...")
time.sleep(65)

# Create a new conversation
new_conversation = openai_client.conversations.create()
print(f"Created new conversation (id: {new_conversation.id})")

# Create an agent response with stored memories
new_response = openai_client.responses.create(
    input="Please order my usual coffee",
    conversation=new_conversation.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response output: {new_response.output_text}")

using System.Threading;

#pragma warning disable OPENAI001

// Get a response client scoped to the agent
ProjectResponsesClient responseClient =
    projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgent(agent.Name);

// Create an agent response to initial user message
ResponseItem request = ResponseItem.CreateUserMessageItem(
    "I prefer dark roast coffee");
ResponseResult response = responseClient.CreateResponse([request]);
// To scope memories to an end user, uncomment:
// var options = new CreateResponseOptions();
// options.InputItems.Add(request);
// var requestOptions = new RequestOptions();
// requestOptions.AddHeader("x-memory-user-id", "<user-id>");
// ClientResult result = responseClient.CreateResponse(
//     BinaryContent.Create(options), requestOptions);
// ResponseResult response = ModelReaderWriter.Read<ResponseResult>(
//     result.GetRawResponse().Content);

Console.WriteLine($"Response output: {response.GetOutputText()}");

// After inactivity, memories are extracted and stored
Console.WriteLine("Waiting for memories to be stored...");
Thread.Sleep(65_000);

// Create a new response to demonstrate cross-session recall
ResponseItem newRequest = ResponseItem.CreateUserMessageItem(
    "Please order my usual coffee");
ResponseResult newResponse = responseClient.CreateResponse(
    [newRequest]);

Console.WriteLine(
    $"Response output: {newResponse.GetOutputText()}");

import { setTimeout } from "timers/promises";

const openai = project.getOpenAIClient();

// Create a conversation with the agent with memory tool enabled
const conversation = await openai.conversations.create();
console.log(`Created conversation (id: ${conversation.id})`);

// Create an agent response to initial user message
const response = await openai.responses.create(
  {
    conversation: conversation.id,
    input: "I prefer dark roast coffee",
  },
  {
    body: {
      agent_reference: { name: agent.name, type: "agent_reference" },
    },
    // To scope memories to an end user, uncomment:
    // headers: { "x-memory-user-id": "<user-id>" },
  },
);

console.log(`Response output: ${response.output_text}`);

// After inactivity, memories are extracted and stored
console.log("Waiting for memories to be stored...");
await setTimeout(65_000);

// Create a new conversation to demonstrate cross-session recall
const newConversation = await openai.conversations.create();
console.log(`Created new conversation (id: ${newConversation.id})`);

// Create an agent response with stored memories
const newResponse = await openai.responses.create(
  {
    conversation: newConversation.id,
    input: "Please order my usual coffee",
  },
  {
    body: {
      agent_reference: { name: agent.name, type: "agent_reference" },
    },
  },
);

console.log(`Response output: ${newResponse.output_text}`);

import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

ResponsesClient responsesClient = new AgentsClientBuilder()
  .credential(new DefaultAzureCredentialBuilder().build())
  .endpoint(projectEndpoint)
  .buildResponsesClient();

AgentReference agentReference = new AgentReference(agent.getName())
  .setVersion(agent.getVersion());

Response response = responsesClient.createAzureResponse(
  new AzureCreateResponseOptions().setAgentReference(agentReference),
  ResponseCreateParams.builder()
    .input("I prefer dark roast coffee"));

System.out.println("Response output: " + response.output());

System.out.println("Waiting for memories to be stored...");
Thread.sleep(65_000);

Response newResponse = responsesClient.createAzureResponse(
  new AzureCreateResponseOptions().setAgentReference(agentReference),
  ResponseCreateParams.builder()
    .input("Please order my usual coffee"));

System.out.println("Response output: " + newResponse.output());

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/conversations" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{}'

# Copy the "id" field from the previous response
# To scope memories to an end user, add -H "x-memory-user-id: <user-id>" to the following request
curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/responses" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "I prefer dark roast coffee",
      "conversation": "{conversation-id}",
      "agent_reference": {
        "type": "agent_reference",
        "name": "MyAgent"
      }
    }'

Doğrudan anımsama veya unutma davranışı uygulama

Kullanıcı aracıdan bilgileri açıkça hatırlamasını veya unutmasını istediğinde, dizideki tools bellek arama aracı işlemi hemen uygular ve sonucu yanıt çıkışında bellek komut öğeleri olarak döndürür. Ek araç yapılandırması gerekmez.

Note

Doğrudan bellek komutları bellek TTL'lerini geçersiz kılmaz. Bellek deposunda TTL yapılandırılmışsa, bellek öğelerinin süresi bir anımsa komutuyla eklenmiş olsa bile yine de dolabilir.

openai_client = project_client.get_openai_client()

# Configure the memory search tool
tools = [
    {
        "type": "memory_search_preview",
        "memory_store_name": memory_store_name,
        "scope": scope,
    }
]

# Ask the agent to remember information
remember_response = openai_client.responses.create(
    model=os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"],
    tools=tools,
    input="Remember that my preferred seat is aisle.",
)

for item in remember_response.output:
    if getattr(item, "type", None) == "memory_command_call":
        print(item.type)       # memory_command_call
        print(item.arguments)  # {"action": "remember", "content": "..."}
        print(item.status)     # completed

# Ask the agent to forget information
forget_response = openai_client.responses.create(
    model=os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"],
    tools=tools,
    input="Forget my preferred seat.",
)

for item in forget_response.output:
    if getattr(item, "type", None) == "memory_command_call":
        print(item.type)
        print(item.arguments)  # {"action": "forget", "content": "..."}
        print(item.status)

Bu örnekte responseClient, Konuşma oluşturma bölümünde oluşturulan yeniden kullanılır.

using Azure.AI.Extensions.OpenAI;
using OpenAI.Responses;

#pragma warning disable AAIP001
#pragma warning disable OPENAI001

static void PrintMemoryCommands(ResponseResult response)
{
    foreach (ResponseItem item in response.OutputItems)
    {
        switch (item.AsAgentResponseItem())
        {
            case MemoryCommandToolCall command:
                Console.WriteLine($"Arguments: {command.Arguments}");
                Console.WriteLine($"Status: {command.Status}");
                break;
            case MemoryCommandToolCallOutput output:
                Console.WriteLine($"Status: {output.Status}");
                break;
        }
    }
}

// Ask the agent to remember information
ResponseResult rememberResponse = responseClient.CreateResponse(
    [ResponseItem.CreateUserMessageItem(
        "Remember that my preferred seat is aisle.")]);
PrintMemoryCommands(rememberResponse);

// Ask the agent to forget information
ResponseResult forgetResponse = responseClient.CreateResponse(
    [ResponseItem.CreateUserMessageItem(
        "Forget my preferred seat.")]);
PrintMemoryCommands(forgetResponse);

const openai = project.getOpenAIClient();

// Configure the memory search tool
const tools = [
  {
    type: "memory_search_preview",
    memory_store_name: memoryStoreName,
    scope: scope,
  },
];

// Ask the agent to remember information
const rememberResponse = await openai.responses.create({
  model: chatModelDeployment,
  input: "Remember that my preferred seat is aisle.",
  tools: tools as any,
});

for (const item of rememberResponse.output) {
  const outputItem = item as Record<string, unknown>;
  if (outputItem["type"] === "memory_command_call") {
    console.log(outputItem["type"]);       // memory_command_call
    console.log(outputItem["arguments"]);
    // {"action": "remember", "content": "..."}
    console.log(outputItem["status"]);     // completed
  }
}

// Ask the agent to forget information
const forgetResponse = await openai.responses.create({
  model: chatModelDeployment,
  input: "Forget my preferred seat.",
  tools: tools as any,
});

for (const item of forgetResponse.output) {
  const outputItem = item as Record<string, unknown>;
  if (outputItem["type"] === "memory_command_call") {
    console.log(outputItem["type"]);
    console.log(outputItem["arguments"]);
    // {"action": "forget", "content": "..."}
    console.log(outputItem["status"]);
  }
}

import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

Response rememberResponse = responsesClient.createAzureResponse(
  new AzureCreateResponseOptions().setAgentReference(agentReference),
  ResponseCreateParams.builder()
    .input("Remember that my preferred seat is aisle."));

System.out.println(rememberResponse.output());

Response forgetResponse = responsesClient.createAzureResponse(
  new AzureCreateResponseOptions().setAgentReference(agentReference),
  ResponseCreateParams.builder()
    .input("Forget my preferred seat."));

System.out.println(forgetResponse.output());

# Reuse the {conversation-id} from the previous section
# To scope memories to an end user, set x-memory-user-id in each request
curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/responses" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-memory-user-id: <user-id>" \
  -d '{
    "input": "Remember that my preferred seat is aisle.",
    "conversation": "{conversation-id}",
    "agent_reference": {
      "type": "agent_reference",
      "name": "MyAgent"
    }
  }'

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/responses" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-memory-user-id: <user-id>" \
  -d '{
    "input": "Forget my preferred seat.",
    "conversation": "{conversation-id}",
    "agent_reference": {
      "type": "agent_reference",
      "name": "MyAgent"
    }
  }'

Bellekleri API'ler aracılığıyla kullanma

Bellek deposu API'lerini kullanarak bir bellek deposuyla doğrudan etkileşim kurabilirsiniz. Konuşma içeriğinden hafıza deposuna hafızalar ekleyerek başlayın ve ardından temsilci etkileşimlerine bağlam sağlamak için ilgili hafızaları arayın.

Hafıza deposuna hafıza ekleme

Bellek deposuna konuşma içeriği sağlayarak bellek ekleyin. Sistem, aracının bellek optimizasyonu için bellek veri çıkarımı ve birleştirme de dahil olmak üzere verileri ön işlemden ve son işlemden geçirir. Bu uzun süre çalışan işlem yaklaşık bir dakika sürebilir.

scope parametresini belirterek belleği kullanıcılar arasında nasıl segmentleyeceğinize karar verin. Belleğin kapsamını belirli bir son kullanıcı, ekip veya başka bir tanımlayıcıyla belirleyebilirsiniz.

Bir bellek deposunu birden çok konuşma adımıyla güncelleyebilir veya her adımda güncelleştirmeleri önceki güncelleştirme işlemi kimliğini kullanarak zincirleyebilirsiniz.

# Set scope to associate the memories with
scope = "user_123"

user_message = {
  "role": "user",
  "content": "I prefer dark roast coffee and usually drink it in the morning",
   "type": "message"
}

update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[user_message], # Pass conversation items that you want to add to memory
    update_delay=0, # Trigger update immediately without waiting for inactivity
)

# Wait for the update operation to complete, but can also fire and forget
update_result = update_poller.result()
print(f"Updated with {len(update_result.memory_operations)} memory operations")
for operation in update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

# Extend the previous update with another update and more messages
new_message = {
    "role":"user", 
    "content":"I also like cappuccinos in the afternoon", 
    "type":"message"}

new_update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[new_message],
    previous_update_id=update_poller.update_id, # Extend from previous update ID
    update_delay=0, # Trigger update immediately without waiting for inactivity
)
new_update_result = new_update_poller.result()
for operation in new_update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

#pragma warning disable OPENAI001

// Set scope to associate the memories with
string scope = "user_123";

MemoryUpdateOptions memoryOptions = new(scope)
{
    UpdateDelay = 0, // Trigger update immediately without waiting for inactivity
};
memoryOptions.Items.Add(ResponseItem.CreateUserMessageItem(
    "I prefer dark roast coffee and usually drink it "
    + "in the morning"));

// Wait for the update operation to complete
MemoryUpdateResult updateResult =
    projectClient.MemoryStores.WaitForMemoriesUpdate(
        memoryStoreName: memoryStore.Name,
        options: memoryOptions,
        pollingInterval: 500);

if (updateResult.Status == MemoryStoreUpdateStatus.Failed)
{
    throw new InvalidOperationException(
        updateResult.ErrorDetails);
}
Console.WriteLine(
    $"Updated with {updateResult.Details.MemoryOperations.Count} "
    + "memory operations");
foreach (var operation in updateResult.Details.MemoryOperations)
{
    Console.WriteLine(
        $"  - Operation: {operation.Kind}, "
        + $"Memory ID: {operation.MemoryItem.MemoryId}, "
        + $"Content: {operation.MemoryItem.Content}");
}

// Extend the previous update with another message
MemoryUpdateOptions newMemoryOptions = new(scope)
{
    PreviousUpdateId = updateResult.UpdateId,
    UpdateDelay = 0, // Trigger update immediately without waiting for inactivity
};
newMemoryOptions.Items.Add(ResponseItem.CreateUserMessageItem(
    "I also like cappuccinos in the afternoon"));

MemoryUpdateResult newUpdateResult =
    projectClient.MemoryStores.WaitForMemoriesUpdate(
        memoryStoreName: memoryStore.Name,
        options: newMemoryOptions,
        pollingInterval: 500);

if (newUpdateResult.Status == MemoryStoreUpdateStatus.Failed)
{
    throw new InvalidOperationException(
        newUpdateResult.ErrorDetails);
}
foreach (var operation in newUpdateResult.Details.MemoryOperations)
{
    Console.WriteLine(
        $"  - Operation: {operation.Kind}, "
        + $"Memory ID: {operation.MemoryItem.MemoryId}, "
        + $"Content: {operation.MemoryItem.Content}");
}

const scope = "user_123";

const userMessage: Record<string, unknown> = {
  type: "message",
  role: "user",
  content: [
    {
      type: "input_text",
      text: "I prefer dark roast coffee and usually drink it in the morning",
    },
  ],
};

console.log("\nSubmitting memory update request...");
const updatePoller = project.beta.memoryStores.updateMemories(
  memoryStoreName,
  scope,
  {
    items: [userMessage],
    updateDelayInSecs: 0,
  },
);

const updateResult = await updatePoller.pollUntilDone();
console.log(
  `Updated with ${updateResult.memory_operations.length} ` +
    `memory operation(s)`,
);
for (const operation of updateResult.memory_operations) {
  console.log(
    `  - Operation: ${operation.kind}, ` +
      `Memory ID: ${operation.memory_item.memory_id}, ` +
      `Content: ${operation.memory_item.content}`,
  );
}

// Extend the previous update with another message
const newMessage = {
  role: "user",
  content: "I also like cappuccinos in the afternoon",
  type: "message",
};

const newUpdatePoller = project.beta.memoryStores.updateMemories(
  memoryStoreName,
  scope,
  {
    items: [newMessage],
    updateDelayInSecs: 0,
  },
);

const newUpdateResult = await newUpdatePoller.pollUntilDone();
console.log(
  `Updated with ${newUpdateResult.memory_operations.length} ` +
    `memory operation(s)`,
);
for (const operation of newUpdateResult.memory_operations) {
  console.log(
    `  - Operation: ${operation.kind}, ` +
      `Memory ID: ${operation.memory_item.memory_id}, ` +
      `Content: ${operation.memory_item.content}`,
  );
}

import com.azure.ai.agents.models.MemoryStoreUpdateCompletedResult;
import com.azure.ai.agents.models.MemoryStoreUpdateResponse;
import com.azure.core.util.polling.SyncPoller;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseInputItem;
import java.util.Arrays;

ResponseInputItem userMessage = ResponseInputItem.ofEasyInputMessage(
  EasyInputMessage.builder()
    .role(EasyInputMessage.Role.USER)
    .content("I prefer dark roast coffee and usually drink it in the morning")
    .build());

SyncPoller<MemoryStoreUpdateResponse, MemoryStoreUpdateCompletedResult> updatePoller =
  memoryStoresClient.beginUpdateMemories(
    memoryStoreName,
    scope,
    Arrays.asList(userMessage),
    null,
    0);

updatePoller.waitForCompletion();
MemoryStoreUpdateCompletedResult updateResult = updatePoller.getFinalResult();
System.out.println(
  "Updated with " + updateResult.getMemoryOperations().size()
    + " memory operation(s)");
for (var operation : updateResult.getMemoryOperations()) {
  System.out.println(
    "  - Operation: " + operation.getKind() + ", Memory ID: "
      + operation.getMemoryItem().getMemoryId() + ", Content: "
      + operation.getMemoryItem().getContent());
}

ResponseInputItem newMessage = ResponseInputItem.ofEasyInputMessage(
  EasyInputMessage.builder()
    .role(EasyInputMessage.Role.USER)
    .content("I also like cappuccinos in the afternoon")
    .build());

// Pass null for previousUpdateId to start a fresh independent update.
// To chain from the previous update, pass the update ID from the
// intermediate poller response instead.
SyncPoller<MemoryStoreUpdateResponse, MemoryStoreUpdateCompletedResult> newUpdatePoller =
  memoryStoresClient.beginUpdateMemories(
    memoryStoreName,
    scope,
    Arrays.asList(newMessage),
    null,
    0);

newUpdatePoller.waitForCompletion();
MemoryStoreUpdateCompletedResult newUpdateResult = newUpdatePoller.getFinalResult();
for (var newOperation : newUpdateResult.getMemoryOperations()) {
  System.out.println(
    "  - Operation: " + newOperation.getKind() + ", Memory ID: "
      + newOperation.getMemoryItem().getMemoryId() + ", Content: "
      + newOperation.getMemoryItem().getContent());
}

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store:update_memories?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user_123",
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "I prefer dark roast coffee and usually drink it in the morning"
          }
        ]
      }
    ],
    "update_delay": 0
  }'

# Get add memory status by polling the update_id
# Use the "update_id" from previous response
UPDATE_ID=<your_update_id>
curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/updates/${UPDATE_ID}?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Bellek deposunda anıları arayın

Aracı etkileşimleri için ilgili bağlamı almak üzere hafızaları araştırın. Aramayı daraltmak için bellek deposu adını ve kapsamını belirtin.

from azure.ai.projects.models import MemorySearchOptions

# Search memories by a query
query_message = {"role": "user", "content": "What are my coffee preferences?", "type": "message"}

search_response = project_client.beta.memory_stores.search_memories(
    name=memory_store_name,
    scope=scope,
    items=[query_message],
    options=MemorySearchOptions(max_memories=5)
)
print(f"Found {len(search_response.memories)} memories")
for memory in search_response.memories:
    print(f"  - Memory ID: {memory.memory_item.memory_id}, Content: {memory.memory_item.content}")

#pragma warning disable OPENAI001

// Search memories by a query
MemorySearchOptions searchOptions = new(scope)
{
    Items =
    {
        ResponseItem.CreateUserMessageItem(
            "What are my coffee preferences?")
    },
    ResultOptions = new() { MaxMemories = 5 },
};

MemoryStoreSearchResponse searchResponse =
    projectClient.MemoryStores.SearchMemories(
        memoryStoreName: memoryStore.Name,
        options: searchOptions);

Console.WriteLine(
    $"Found {searchResponse.Memories.Count} memories");
foreach (MemorySearchItem item in searchResponse.Memories)
{
    Console.WriteLine(
        $"  - Content: {item.MemoryItem.Content}");
}

const queryMessage: Record<string, unknown> = {
  type: "message",
  role: "user",
  content: [
    { type: "input_text", text: "What are my coffee preferences?" },
  ],
};

console.log("\nSearching memories for stored preferences...");
const searchResponse =
  await project.beta.memoryStores.searchMemories(
    memoryStoreName,
    scope,
    {
      items: [queryMessage],
      options: { max_memories: 5 },
    },
  );

console.log(`Found ${searchResponse.memories.length} memory item(s)`);
for (const memory of searchResponse.memories) {
  console.log(
    `  - Memory ID: ${memory.memory_item.memory_id}, ` +
      `Content: ${memory.memory_item.content}`,
  );
}

import com.azure.ai.agents.models.MemorySearchItem;
import com.azure.ai.agents.models.MemorySearchOptions;
import com.azure.ai.agents.models.MemoryStoreSearchResponse;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseInputItem;
import java.util.Arrays;

ResponseInputItem queryMessage = ResponseInputItem.ofEasyInputMessage(
  EasyInputMessage.builder()
    .role(EasyInputMessage.Role.USER)
    .content("What are my coffee preferences?")
    .build());

MemorySearchOptions searchOptions = new MemorySearchOptions()
  .setMaxMemories(5);

MemoryStoreSearchResponse searchResponse = memoryStoresClient.searchMemories(
  memoryStoreName,
  scope,
  Arrays.asList(queryMessage),
  null,
  searchOptions);

System.out.println("Found " + searchResponse.getMemories().size() + " memories");
for (MemorySearchItem item : searchResponse.getMemories()) {
  System.out.println(
    "  - Memory ID: " + item.getMemoryItem().getMemoryId() + ", Content: "
      + item.getMemoryItem().getContent());
}

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store:search_memories?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user_123",
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "What are my coffee preferences?"
          }
        ]
      }
    ],
    "options": {
      "max_memories": 5
    }
  }'

Statik veya bağlamsal bellekleri alma

Genellikle, kullanıcının iletisine anlamsal benzerlik temelinde kullanıcı profili belleklerini alamazsınız. Her konuşmanın başına statik bellekler yerleştirin ve her aracı yanıtını oluşturmak için bağlamsal bellekleri kullanın.

  • Statik bellekleri almak için search_memories ile scope kullanın, ancak items veya previous_search_id olmadan çağrıyı gerçekleştirin. Bu, kapsamla ilişkili kullanıcı profili belleklerini döndürür.

  • Bağlamsal bellekleri geri çağırmak için search_memories, items en son iletilere ayarlanmış olarak çağırın. Bu, hem kullanıcı profili hem de belirli öğelerle en ilgili sohbet özeti anılarını döndürebilir.

Kullanıcı profili ve sohbet özeti anıları hakkında daha fazla bilgi için bkz. Bellek türleri.

Bellek öğelerini yönetme

Tek tek bellek kayıtlarını doğrudan oluşturmak, incelemek, güncelleştirmek ve silmek için öğe düzeyinde işlemleri kullanın. Kapsam düzeyinde veya mağaza düzeyinde silme işlemi için bkz. Bellekleri silme.

Bellek öğesi oluşturma

# Create a memory item directly
created = project_client.beta.memory_stores.create_memory(
    name=memory_store_name,
    scope="defaultUser",
    content="User prefers concise changelogs with impact-first summaries.",
    kind="user_profile",
)

print(f"Memory ID: {created.memory_id}")
print(f"Content: {created.content}")
print(f"Kind: {created.kind}")

using Azure.AI.Projects.Memory;

#pragma warning disable AAIP001

// Create a memory item directly
MemoryItem created = projectClient.MemoryStores.CreateMemory(
    name: memoryStoreName,
    scope: "defaultUser",
    content: "User prefers concise changelogs with impact-first summaries.",
    kind: MemoryItemKind.UserProfile);

Console.WriteLine($"Memory ID: {created.MemoryId}");
Console.WriteLine($"Content: {created.Content}");
Console.WriteLine($"Scope: {created.Scope}");

// Create a memory item directly
const created = await project.beta.memoryStores.createMemory(
  memoryStoreName,
  "defaultUser",
  "User prefers concise changelogs with impact-first summaries.",
  "user_profile",
);

console.log(`Memory ID: ${created.memory_id}`);
console.log(`Content: ${created.content}`);
console.log(`Kind: ${created.kind}`);

import com.azure.ai.agents.models.MemoryItem;
import com.azure.ai.agents.models.MemoryItemKind;

MemoryItem created = memoryStoresClient.createMemory(
  memoryStoreName,
  "defaultUser",
  "User prefers concise changelogs with impact-first summaries.",
  MemoryItemKind.USER_PROFILE);

System.out.println("Memory ID: " + created.getMemoryId());
System.out.println("Content: " + created.getContent());
System.out.println("Kind: " + created.getKind());

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "defaultUser",
    "content": "User prefers concise changelogs with impact-first summaries.",
    "kind": "user_profile"
  }'

Bellek öğesini al

# Retrieve a memory item by ID
item = project_client.beta.memory_stores.get_memory(
    name=memory_store_name,
    memory_id="<memory-item-id>",
)

print(f"Memory ID: {item.memory_id}")
print(f"Content: {item.content}")
print(f"Kind: {item.kind}")

using Azure.AI.Projects.Memory;

#pragma warning disable AAIP001

// Retrieve a memory item by ID
MemoryItem item = projectClient.MemoryStores.GetMemory(
    name: memoryStoreName,
    memoryId: "<memory-item-id>");

Console.WriteLine($"Memory ID: {item.MemoryId}");
Console.WriteLine($"Content: {item.Content}");
Console.WriteLine($"Scope: {item.Scope}");

// Retrieve a memory item by ID
const item = await project.beta.memoryStores.getMemory(
  memoryStoreName,
  "<memory-item-id>",
);

console.log(`Memory ID: ${item.memory_id}`);
console.log(`Content: ${item.content}`);
console.log(`Kind: ${item.kind}`);

import com.azure.ai.agents.models.MemoryItem;

MemoryItem memItem = memoryStoresClient.getMemory(
  memoryStoreName,
  "<memory-item-id>");

System.out.println("Memory ID: " + memItem.getMemoryId());
System.out.println("Content: " + memItem.getContent());
System.out.println("Kind: " + memItem.getKind());

curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items/<memory-item-id>?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Bellek öğelerini listeleme

# List all memory items in the store
memories = project_client.beta.memory_stores.list_memories(
    name=memory_store_name,
    scope="defaultUser",
)

count = 0
for item in memories:
    count += 1
    print(f"- {item.memory_id} [{item.kind}]: {item.content}")

print(f"Total memories: {count}")

using Azure.AI.Projects.Memory;

#pragma warning disable AAIP001

// List all memory items in the store
int count = 0;
foreach (MemoryItem item in projectClient.MemoryStores.GetMemories(
    name: memoryStoreName,
    scope: "defaultUser"))
{
    count++;
    Console.WriteLine(
  $"- {item.MemoryId} [{item.Scope}]: {item.Content}");
}

Console.WriteLine($"Total memories: {count}");

// List all memory items in the store
const memoriesList = project.beta.memoryStores.listMemories(
  memoryStoreName,
  "defaultUser",
);

let count = 0;
for await (const item of memoriesList) {
  count += 1;
  console.log(`- ${item.memory_id} [${item.kind}]: ${item.content}`);
}
console.log(`Total memories: ${count}`);

import com.azure.ai.agents.models.ListMemoriesOptions;
import com.azure.ai.agents.models.MemoryItem;

ListMemoriesOptions options = new ListMemoriesOptions(
  memoryStoreName,
  "defaultUser");

int count = 0;
for (MemoryItem memoryEntry : memoryStoresClient.listMemories(options)) {
  count++;
  System.out.println(
    "- " + memoryEntry.getMemoryId() + " [" + memoryEntry.getKind() + "]: "
      + memoryEntry.getContent());
}

System.out.println("Total memories: " + count);

curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items:list?scope=user_123&api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Bellek öğesini güncelleştirme

# Update a memory item by ID
updated = project_client.beta.memory_stores.update_memory(
    name=memory_store_name,
    memory_id="<memory-item-id>",
    content="User prefers detailed technical explanations with examples.",
)

print(f"Updated: {updated.content}")

using Azure.AI.Projects.Memory;

#pragma warning disable AAIP001

// Update a memory item by ID
MemoryItem updated = projectClient.MemoryStores.UpdateMemory(
    name: memoryStoreName,
    memoryId: "<memory-item-id>",
    content: "User prefers detailed technical explanations with examples.");

Console.WriteLine($"Updated: {updated.Content}");

// Update a memory item by ID
const updated = await project.beta.memoryStores.updateMemory(
  memoryStoreName,
  "<memory-item-id>",
  "User prefers detailed technical explanations with examples.",
);

console.log(`Updated: ${updated.content}`);

import com.azure.ai.agents.models.MemoryItem;

MemoryItem updated = memoryStoresClient.updateMemory(
  memoryStoreName,
  "<memory-item-id>",
  "User prefers detailed technical explanations with examples.");

System.out.println("Updated: " + updated.getContent());

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items/<memory-item-id>?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers detailed technical explanations with examples."}'

Bellek öğesini silme

# Delete a memory item by ID
project_client.beta.memory_stores.delete_memory(
    name=memory_store_name,
    memory_id="<memory-item-id>",
)

print("Memory item deleted successfully")

using Azure.AI.Projects.Memory;

#pragma warning disable AAIP001

// Delete a memory item by ID
MemoryDeletionResult result = projectClient.MemoryStores.DeleteMemory(
    name: memoryStoreName,
    memoryId: "<memory-item-id>");

Console.WriteLine(
    $"Memory item {result.MemoryId} deleted: {result.Deleted}");

// Delete a memory item by ID
await project.beta.memoryStores.deleteMemory(
  memoryStoreName,
  "<memory-item-id>",
);

console.log("Memory item deleted successfully");

memoryStoresClient.deleteMemory(memoryStoreName, "<memory-item-id>");

System.out.println("Memory item deleted successfully");

curl -X DELETE "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items/<memory-item-id>?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Anıları silme

Uyarı

Bellek depolarını silmeden önce bağımlı aracılar üzerindeki etkiyi göz önünde bulundurun. Ekli bellek birimlerine sahip aracılar geçmiş bağlam erişimini kaybedebilir.

Bellekler, bir bellek deposu içinde kapsama göre düzenlenir. Kullanıcıya özgü verileri kaldırmak için belirli bir kapsama ilişkin bellekleri silebilir veya tüm kapsamlardaki tüm bellekleri kaldırmak için bellek deposunun tamamını silebilirsiniz.

Belirli kapsamlar bazında hafıza verilerini silme

Bellek deposu yapısını korurken belirli bir kullanıcı veya grup kapsamıyla ilişkili tüm bellekleri kaldırın. Kullanıcı veri silme isteklerini işlemek veya belirli kullanıcılar için belleği sıfırlamak için bu işlemi kullanın.

# Delete memories for a specific scope
project_client.beta.memory_stores.delete_scope(
    name=memory_store_name,
    scope="user_123"
)

print(f"Deleted memories for scope: user_123")

// Delete memories for a specific scope
MemoryStoreDeleteScopeResponse deleteScopeResponse =
    projectClient.MemoryStores.DeleteScope(
        name: memoryStore.Name,
        scope: "user_123");

Console.WriteLine(
    $"Deleted scope: {deleteScopeResponse.Name}, "
    + $"success: {deleteScopeResponse.IsDeleted}");

console.log("\nDeleting memories for scope...");
await project.beta.memoryStores.deleteScope(memoryStoreName, scope);

memoryStoresClient.deleteScope(memoryStoreName, "user_123");

System.out.println("Deleted memories for scope: user_123");

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store:delete_scope?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user_123"
  }'

Bellek depolarını silme

Tüm kapsamlarda bellek deposunun tamamını ve ilişkili tüm bellekleri kaldırın. Bu işlem geri alınamaz.

# Delete the entire memory store
delete_response = project_client.beta.memory_stores.delete(memory_store_name)
print(f"Deleted memory store: {delete_response.deleted}")

// Delete the entire memory store
DeleteMemoryStoreResponse deleteResponse =
    projectClient.MemoryStores.DeleteMemoryStore(
        name: memoryStore.Name);

Console.WriteLine(
    $"Deleted memory store: {deleteResponse.Name}, "
    + $"success: {deleteResponse.IsDeleted}");

console.log("Deleting memory store...");
await project.beta.memoryStores.delete(memoryStoreName);

memoryStoresClient.deleteMemoryStore(memoryStoreName);

System.out.println("Deleted memory store: " + memoryStoreName);

curl -X DELETE "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

En iyi yöntemler

  • Kullanıcı başına erişim denetimleri uygulayın: Aracılara tüm kullanıcılar arasında paylaşılan anılara erişim vermekten kaçının. bellek depoyu scope kullanıcıya göre bölümlendirmek için özelliğini kullanın. Kullanıcılar arasında scope paylaşırken, bellek sistemine kişisel bilgileri depolamamasını bildirmek için user_profile_details kullanın.

  • Harita kapsamı son kullanıcıya eşleyin:Bellek arama aracını kullandığınızda, araç tanımında scope olarak {{$userId}} ayarlayın. Sistem, varsa istek üst bilgisinden x-memory-user-id kullanıcı kimliğini çözümler. Aksi takdirde, çağıranın Microsoft Entra belirtecine ({tid}_{oid}) geri döner.

  • Hassas verileri en aza indirin ve koruyun: Yalnızca kullanım senaryonuz için gerekenleri depolayın. Kişisel veriler, sağlık verileri veya gizli iş bilgileri gibi hassas verileri depolamanız gerekiyorsa, bir kişiyi belirlemeye yarayabilecek diğer içeriği maskeleme veya kaldırma.

  • Gizlilik ve uyumluluk desteği: Kullanıcılara verilerine erişme ve verileri silme seçenekleri de dahil olmak üzere saydamlık sağlayın. Tüm silmeleri kurcalamaya karşı korumalı bir denetim kaydına kaydedin. Sistemin yerel uyumluluk gereksinimlerine ve mevzuat standartlarına uydığından emin olun.

  • Verileri segmentlere ayırma ve belleği yalıtma: Çok aracılı sistemlerde belleği mantıksal ve operasyonel olarak segmentlere ayırın. Müşterilerin kendi bellek ayak izlerini tanımlamasına, yalıtmasına, incelemesine ve silmesine izin verin.

  • Bellek kullanımını izleme: Maliyetleri anlamak ve performansı iyileştirmek için belirteç kullanımını ve bellek işlemlerini izleyin.

  • Kullanıcıya yönelik bellek denetimlerini kullanıma sunma: Güven ve veri hakları iş akışlarını desteklemek için öğe düzeyinde düzenleme ve silme eylemleri sağlayın.

  • Açık saklama varsayılanlarını ayarlayın: İlke gereksinimleriyle eşleşen TTL ayarlarını kullanın. Ürün UX'inizde belge saklama davranışı.

Sorun giderme

Sorunu Neden Çözünürlük
İstekler bir kimlik doğrulaması veya yetkilendirme hatasıyla başarısız olur. Kimliğiniz veya proje tarafından yönetilen kimliğiniz gerekli rollere sahip değil. Yetkilendirme ve izinler bölümünde rolleri doğrulayın. REST çağrıları için yeni bir erişim belirteci oluşturun ve yeniden deneyin.
Anılar konuşmadan sonra görünmez. Bellek güncelleştirmeleri iptal edildi veya hala işleniyor. : Bekleme süresini artırın veya olarak ayarlanmış güncelleme API'sini işlemeyi hemen tetiklemek için çağırın.
Bellek araması sonuç döndürmez. Değer, scope bellekler depolandığında kullanılan kapsamla eşleşmiyor. Güncelleştirme ve arama için aynı kapsamı kullanın. Kapsamı kullanıcılarla eşlerseniz, kararlı bir kullanıcı tanımlayıcısı kullanın.
Ajan yanıtı depolanan belleği kullanmaz. Aracı bellek arama aracıyla yapılandırılmamış veya bellek deposu adı yanlış. Aracı tanımının memory_search_preview aracını içerdiğini ve doğru bellek deposu adına başvurmasını onaylayın.
Yordamsal bellek veya varsayılan TTL ayarı bir güncelleştirmeden sonra etkili olmadı. En son önizlemede, varsayılan seçenekleri yalnızca bellek deposu oluşturma zamanında ayarlayabilirsiniz. bellek deposunu istediğiniz varsayılan değerlerle yeniden oluşturun veya API sürümünüzün oluşturma sonrası seçenek güncelleştirmelerini destekleyip desteklemediğini denetleyin.
Açık bir anımsama veya unutma isteği yanıtta bellek komut öğelerini döndürmedi. Bellek araçları doğru yapılandırılmadı veya giriş bir anımsa veya unut komutu olarak tanınmadı. Bellek aracı yapılandırmasını onaylayın ve doğrudan anımsama veya unutma tümceleriyle test edin.

İlgili içerik

  • Last updated on