Geheugen maken en gebruiken in Foundry Agent Service (preview)

Belangrijk

Geheugen (preview) in Foundry Agent Service en de Memory Store-API (preview) hebben een licentie voor u als onderdeel van uw Azure-abonnement en zijn onderhevig aan voorwaarden die van toepassing zijn op Previews in de Microsoft Productvoorwaarden, de Microsoft Data Protection Addendum en de Aanvullende gebruiksvoorwaarden voor Microsoft Azure previews.

De nieuwste preview biedt nieuwe mogelijkheden en verbeteringen, waaronder:

  • Geheugenitembewerkingen voor het maken, lezen, bijwerken, vermelden en verwijderen van afzonderlijke geheugenrecords.
  • Standaard bewaarinstellingen op store-niveau, inclusief de standaard-TTL voor nieuw aangemaakte geheugenstores.
  • Het gedrag van de gesynchroniseerde geheugenopdracht wordt direct onthouden of vergeten.

Geheugen in Foundry Agent Service is een beheerde, langetermijngeheugenoplossing. Het maakt agentcontinuïteit mogelijk voor sessies, apparaten en werkstromen. Door geheugenarchieven te maken en te beheren, kunt u agents bouwen die gebruikersvoorkeuren behouden, de gespreksgeschiedenis onderhouden en persoonlijke ervaringen leveren.

Geheugenarchieven fungeren als permanente opslag, waarbij wordt gedefinieerd welke typen informatie relevant zijn voor elke agent. U bepaalt de toegang met behulp van de scope parameter, die het geheugen segmenteert voor gebruikers om veilige en geïsoleerde ervaringen te garanderen.

In dit artikel wordt uitgelegd hoe u geheugenarchieven maakt, beheert en gebruikt. Voor conceptuele informatie, zie Geheugen in Foundry Agent Service.

Volg dit pad voor een eerste end-to-end succes:

  1. Maak een geheugenopslag voor de agent.
  2. Koppel het hulpprogramma voor geheugenzoekopdrachten aan de agent.
  3. Maak een gesprek, verzend een voorkeur en wacht op de geconfigureerde updatevertraging, zodat de service deze kan onthouden.
  4. Start een nieuw gesprek in hetzelfde voorbeeld en stel een gerelateerde vraag om te bevestigen dat de agent de voorkeur terugroept.

Kies een werkstroom op basis van hoe u rechtstreeks geheugen wilt beheren:

Scenario Beginnen met Gebruik het om
Bestuur Een geheugenopslag maken Opslag- en bewaarinstellingen configureren, bijwerken, weergeven of verwijderen.
Opdrachten Direct onthouden of vergeten gedrag toepassen Houd rekening met een expliciete gebruikersaanvraag om informatie onmiddellijk te onthouden of te vergeten.
Items Geheugenitems beheren Afzonderlijke records rechtstreeks maken, inspecteren, bijwerken of verwijderen.

Voorbeelddekking

Een vinkje betekent dat dit artikel een voorbeeld voor die taal bevat. Een streepje betekent dat een voorbeeld momenteel niet is opgenomen; er wordt niet aangegeven of de SDK de bewerking ondersteunt.

Vermogen Python SDK C#SDK JavaScript SDK Java SDK REST API
Geheugenarchieven maken, bijwerken, weergeven en verwijderen ✔️ ✔️ ✔️ ✔️ ✔️
Geheugen koppelen aan een promptagent ✔️ ✔️ ✔️ ✔️ ✔️
Herinneringen bijwerken en zoeken ✔️ ✔️ ✔️ ✔️ ✔️
Opdrachten voor direct onthouden of vergeten toepassen ✔️ — ✔️ ✔️ ✔️
Geheugenitems maken, lezen, bijwerken, vermelden en verwijderen ✔️ — ✔️ ✔️ ✔️

Voorwaarden

Autorisatie en machtigingen

Gebruik op rollen gebaseerd toegangsbeheer voor productie-implementaties . Als rollen niet haalbaar zijn, slaat u deze sectie over en gebruikt u in plaats daarvan verificatie op basis van sleutels.

Op rollen gebaseerde toegang configureren:

  1. Meld u aan bij de Azure-portal.

  2. In uw project:

    1. Selecteer Resource Management>Identity in het linkerdeelvenster.
    2. Gebruik de wisselknop om een door het systeem toegewezen beheerde identiteit in te schakelen.

  3. Op de resource die uw project bevat:

    1. Selecteer toegangsbeheer (IAM) in het linkerdeelvenster.

    2. Selecteer Toevoegen>Roltoewijzing toevoegen.

    3. Wijs Foundry User toe aan de beheerde identiteit van uw project.

      Belangrijk

      De rollen Foundry RBAC zijn onlangs hernoemd. Foundry User, Foundry Owner, Foundry Account Owner en Foundry Project Manager zijn eerder benoemd Azure AI-gebruiker, Azure AI-eigenaar Azure AI-accounteigenaar en Azure AI Project Manager. Het kan zijn dat u op sommige plekken nog steeds de vorige namen ziet terwijl de naamswijziging wordt doorgevoerd. De rol-id's en basismachtigingen worden niet gewijzigd door de naamswijziging.

Uw omgeving instellen

Installeer de vereiste pakketten:

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

Installeer de vereiste pakketten:

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

Installeer de vereiste pakketten:

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

Gebruik Node.js 22 of hoger met @azure/ai-projects 2.4.0.

Installeer de vereiste pakketten:

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

Stel omgevingsvariabelen in voor de projecteindpunt- en modelimplementatienamen:

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>"

Stel omgevingsvariabelen in voor uw projecteindpunt, modelimplementaties, API-versie en toegangstoken:

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

Begrijp de scope

De scope parameter bepaalt hoe geheugen wordt gepartitioneerd. Elk scope in de geheugen opslag bewaart een geïsoleerde set van geheugenitems. Als u bijvoorbeeld een klantondersteuningsagent met geheugen maakt, moet elke klant een eigen afzonderlijk geheugen hebben.

Als ontwikkelaar kiest u de sleutel die wordt gebruikt om geheugenitems op te slaan en op te halen. De juiste aanpak is afhankelijk van hoe u toegang krijgt tot geheugen.

Via de geheugenzoektool

Wanneer u de geheugenzoeker aan een agent koppelt, stelt u scope in op {{$userId}} om per-gebruiker geheugenisolatie in te schakelen zonder hardgecodeerde identificeerders. Het systeem lost de identiteit van de eindgebruiker automatisch op bij elke reactieaanroep van een van de twee bronnen:

  • x-memory-user-id aanvraagheader: Indien aanwezig, wordt de headerwaarde gebruikt als de gebruikers-id. Gebruik dit in proxy- of back-endscenario's waarbij uw service de API aanroept namens een eindgebruiker.

  • Microsoft Entra verificatietoken: Als de header niet is ingesteld, valt het systeem terug op de tenant-id (TID) van de beller en object-id (OID). Dit is de standaardinstelling in front-endscenario's waarbij gebruikers zich rechtstreeks verifiëren met Microsoft Entra.

Als u geen isolatie per gebruiker nodig hebt, gebruikt u in plaats daarvan een statische scope waarde.

Via GEHEUGEN-API's op laag niveau

Wanneer u geheugen-API's rechtstreeks aanroept, geeft u scope expliciet op in elke aanvraag. U kunt een statische waarde doorgeven, zoals een universally unique identifier (UUID) of een andere stabiele id van uw systeem. Automatische identiteitsextractie wordt niet ondersteund voor deze bewerkingen.

Een geheugenopslag maken

Maak een toegewezen geheugenopslag voor elke agent om duidelijke grenzen vast te stellen voor geheugentoegang en optimalisatie. Wanneer u een geheugenarchief maakt, geeft u het chatmodel op en sluit u modelimplementaties in die uw geheugeninhoud verwerken.

Gebruik opties voor geheugenopslag om het extractiegedrag en de standaardwaarden voor retentie te beheren. In de nieuwste preview kunt u procedureel geheugen inschakelen en een standaard-TTL (seconden) instellen voor nieuw gemaakte geheugenvermeldingen.

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"
      }
    }
  }'

Tip

  • De resterende Python, C#, TypeScript en Java codefragmenten bouwen voort op de client en variabelen die zijn gedefinieerd in Een geheugenarchief maken. Als u deze codefragmenten onafhankelijk uitvoert, moet u de import- en client initialisatiecode uit deze sectie opnemen.

  • In de C#-fragmenten in dit artikel worden synchrone methoden gebruikt. Zie de voorbeelden memory-zoekprogramma en memory store voor asynchroon gebruik.

Geheugen aanpassen

Pas aan welke informatie de agent opslaat om geheugen efficiënt, relevant en privacy-respect te houden. Gebruik de user_profile_details parameter om de typen gegevens op te geven die essentieel zijn voor de functie van de agent.

Stel bijvoorbeeld user_profile_details in op prioriteit "voorkeur van vluchtmaatschappijen en dieetbeperkingen" voor een reisagent. Deze gerichte benadering helpt het geheugensysteem te weten welke gegevens moeten worden geëxtraheerd, samengevat en doorgevoerd in langetermijngeheugen.

U kunt deze parameter ook gebruiken om bepaalde typen gegevens uit te sluiten, geheugen mager te houden en te voldoen aan de privacyvereisten. Stel bijvoorbeeld user_profile_details in op 'vermijd irrelevante of gevoelige gegevens, zoals leeftijd, financiële gegevens, exacte locatie en referenties'.

TTL- en bewaarbeleid configureren

TTL is van toepassing op alle geheugengeheugens, of het nu gaat om directe geheugenopdrachten, extractie en samenvoeging of CRUD-bewerkingen op itemniveau. Als een geheugen wordt bijgewerkt en geconsolideerd, wordt de laatst bijgewerkte tijd opnieuw ingesteld.

TTL is alleen van toepassing op geheugenarchieven die zijn gemaakt nadat TTL-ondersteuning is geïntroduceerd. Dit heeft geen invloed op bestaande geheugenarchieven.

Een default_ttl_seconds waarde van 0 geeft aan dat er geen vervaldatum is. Kies een bewaarperiode die overeenkomt met uw vereisten voor naleving en levenscyclus van gebruikersgegevens.

Een geheugenopslag bijwerken

Werk eigenschappen van het geheugenarchief bij, zoals description of metadata, om geheugenarchieven beter te beheren.

# 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"
  }'

Geheugenarchieven weergeven

Haal een lijst met geheugenarchieven op in uw project om uw geheugeninfrastructuur te beheren en te bewaken.

# 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}"

Geheugens gebruiken via een agenthulpprogramma

Nadat u een geheugenopslag hebt gemaakt, kunt u het hulpprogramma voor geheugenzoekopdrachten koppelen aan een promptagent. Met dit hulpprogramma kan de agent tijdens gesprekken lezen van en schrijven naar uw geheugenopslag. Configureer het hulpprogramma met de juiste scope en update_delay om te bepalen hoe en wanneer geheugens worden bijgewerkt.

Tip

Als u geheugens wilt instellen voor een afzonderlijke eindgebruiker, stelt u scope in op "{{$userId}}" in de definitie van het hulpprogramma en gebruikt u x-memory-user-id: <user-id> als een header bij elke antwoordaanroep. Het systeem past de reikwijdte aan naar de identiteit van die gebruiker. Zonder de header valt het bereik terug op de Microsoft Entra identiteit van de beller (TID en OID). Zie Bereik begrijpen voor meer informatie.

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
            }
        ]
    }
}'

Een gesprek maken

U kunt nu gesprekken maken en agentreacties aanvragen. Aan het begin van elk gesprek worden statische geheugens geïnjecteerd, zodat de agent onmiddellijke, permanente context heeft. Contextuele herinneringen worden per beurt opgehaald op basis van de meest recente berichten om elke reactie te informeren.

Na elke reactie van de agent roept de service intern aan update_memories. Werkelijke schrijfbewerkingen naar langetermijngeheugen worden echter losgekoppeld door de update_delay instelling. De update wordt gepland en wordt alleen voltooid na de geconfigureerde periode van inactiviteit.

Note

In het bijgewerkte preview-schema gebruikt de uitvoer van het hulpprogramma voor geheugenzoekopdrachten een memories verzameling in plaats van het verouderde results veld. Als u onbewerkte uitvoerpayloads verwerkt, werkt u de parsers dienovereenkomstig bij.

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"
      }
    }'

Direct onthoud- of vergeetgedrag toepassen

Wanneer een gebruiker de agent expliciet vraagt om informatie te onthouden of te vergeten, past het hulpprogramma voor geheugenzoekopdrachten in de tools matrix de bewerking onmiddellijk toe en retourneert het resultaat als geheugenopdrachtitems in de antwoorduitvoer. Er is geen extra hulpprogrammaconfiguratie vereist.

Note

Opdrachten voor direct geheugen overschrijven de TTL van het geheugen niet. Als een geheugenarchief TTL heeft geconfigureerd, kunnen geheugenitems nog steeds verlopen, zelfs als ze zijn toegevoegd met een opdracht onthouden.

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)

In dit voorbeeld wordt het responseClient gemaakte gesprek opnieuw gebruikt.

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"
    }
  }'

Geheugen gebruiken via API's

U kunt rechtstreeks met een geheugenopslag werken met behulp van de API's voor het geheugenarchief. Begin met het toevoegen van herinneringen van gespreksinhoud aan het geheugenarchief en zoek vervolgens naar relevante herinneringen om context te bieden voor agentinteracties.

Herinneringen toevoegen aan een geheugenopslag

Voeg herinneringen toe door gespreksinhoud aan het geheugenarchief toe te voegen. Het systeem verwerkt en postprocesseert de gegevens, inclusief geheugenextractie en consolidatie, om het geheugen van de agent te optimaliseren. Deze langdurige bewerking kan ongeveer één minuut duren.

Bepaal hoe u geheugen over gebruikers segmenteert door de scope parameter op te geven. U kunt het geheugen toewijzen aan een specifieke eindgebruiker, een team of een andere id.

U kunt een geheugenopslag bijwerken met inhoud uit meerdere gespreksrondes, of na elke beurt bijwerken en daarbij updates ketenen met behulp van de vorige updatebewerkings-id.

# 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}"

Zoeken naar herinneringen in een geheugenarchief

Zoek geheugens om relevante context op te halen voor agentinteracties. Geef de naam en het bereik van het geheugenarchief op om de zoekopdracht te beperken.

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
    }
  }'

Statisch of contextueel geheugen ophalen

Vaak kunt u geen geheugens voor gebruikersprofielen ophalen op basis van semantische overeenkomsten met het bericht van een gebruiker. Injecteer statische geheugens aan het begin van elk gesprek en gebruik contextuele herinneringen om elk agentantwoord te genereren.

  • Om statische herinneringen op te halen, belt u search_memories met een scope, maar zonder items of previous_search_id. Hiermee worden geheugens voor gebruikersprofielen geretourneerd die zijn gekoppeld aan het bereik.

  • Roep search_memories aan met items ingesteld op de laatste berichten om contextuele herinneringen op te halen. Hiermee kunnen zowel gebruikersprofiel- als chatoverzichtsgeheugens worden geretourneerd die het meest relevant zijn voor de opgegeven items.

Zie Geheugentypen voor meer informatie over geheugen van gebruikersprofielen en chatsamenvattingen.

Geheugenonderdelen beheren

Gebruik bewerkingen op itemniveau om afzonderlijke geheugenrecords rechtstreeks te maken, te inspecteren, bij te werken en te verwijderen. Zie Herinneringen verwijderen voor verwijdering op bereikniveau of op archiefniveau.

Een geheugenitem maken

# 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"
  }'

Een geheugenitem ophalen

# 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}"

Geheugenitems weergeven

# 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}"

Een geheugenitem bijwerken

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

Een geheugenitem verwijderen

# 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}"

Herinneringen verwijderen

Waarschuwing

Voordat u een geheugenarchief verwijdert, moet u rekening houden met de impact op afhankelijke agents. Agents met gekoppelde geheugenarchieven hebben mogelijk geen toegang meer tot historische context.

Geheugens worden ingedeeld op bereik binnen een geheugenopslag. U kunt herinneringen voor een specifiek bereik verwijderen om gebruikersspecifieke gegevens te verwijderen of u kunt het hele geheugenarchief verwijderen om alle geheugens in alle bereiken te verwijderen.

Herinneringen per bereik verwijderen

Verwijder alle geheugens die zijn gekoppeld aan een bepaald gebruikers- of groepsbereik, terwijl u de structuur van het geheugenarchief behoudt. Gebruik deze bewerking om aanvragen voor het verwijderen van gebruikersgegevens af te handelen of geheugen opnieuw in te stellen voor specifieke gebruikers.

# 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"
  }'

Een geheugenarchief verwijderen

Verwijder de volledige geheugenopslag en alle geassocieerde geheugenobjecten in alle scopes. Deze bewerking kan niet ongedaan worden genomen.

# 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}"

Beste praktijken

  • Besturingselementen voor toegang per gebruiker implementeren: Voorkom dat agents toegang krijgen tot herinneringen die door alle gebruikers worden gedeeld. Gebruik de scope eigenschap om het geheugenarchief per gebruiker te partitioneren. Wanneer u deelt scope tussen gebruikers, gebruikt user_profile_details u dit om het geheugensysteem te instrueren geen persoonlijke gegevens op te slaan.

  • Het bereik toewijzen aan de eindgebruiker: Wanneer u het hulpprogramma voor geheugenzoekopdrachten gebruikt, stelt u deze in scope{{$userId}} de definitie van het hulpprogramma in. Het systeem lost de gebruikersidentiteit op uit de x-memory-user-id aanvraagheader, indien aanwezig. Anders valt het terug op het Microsoft Entra token van de beller ({tid}_{oid}).

  • Gevoelige gegevens minimaliseren en beveiligen: Sla alleen op wat nodig is voor uw use-case. Als u gevoelige gegevens, zoals persoonlijke gegevens, gezondheidsgegevens of vertrouwelijke zakelijke invoer, moet opslaan, redigeer of verwijder andere inhoud die kunnen worden gebruikt om een persoon te identificeren.

  • Ondersteuning voor privacy en naleving: Bied gebruikers transparantie, inclusief opties voor toegang tot en verwijdering van hun gegevens. Noteer alle verwijderingen in een manipulatiebestendig audit trail. Zorg ervoor dat het systeem voldoet aan lokale nalevingsvereisten en wettelijke normen.

  • Segmenteer gegevens en isoleer geheugen: Segmenteer in systemen met meerdere agents logisch en operationeel geheugen. Hiermee kunnen klanten hun eigen geheugenvoetafdruk definiëren, isoleren, inspecteren en verwijderen.

  • Geheugengebruik bewaken: Tokengebruik en geheugenbewerkingen bijhouden om de kosten te begrijpen en de prestaties te optimaliseren.

  • Besturingselementen voor gebruikersgericht geheugen beschikbaar maken: Bewerk- en verwijderacties op itemniveau ter ondersteuning van werkstromen voor vertrouwens- en gegevensrechten.

  • Standaardwaarden voor expliciete retentie instellen: Gebruik TTL-instellingen die overeenkomen met beleidsvereisten. Documentretentiegedrag in uw product-UX.

Probleemoplossing

Probleem Oorzaak Resolutie
Aanvragen mislukken met een verificatie- of autorisatiefout. Uw identiteit of de door het project beheerde identiteit heeft niet de vereiste rollen. Controleer de rollen in Autorisatie en machtigingen. Genereer voor REST-aanroepen een nieuw toegangstoken en probeer het opnieuw.
Herinneringen worden niet weergegeven na een gesprek. Geheugenupdates zijn gedebounced of nog in verwerking. Verhoog de wachttijd of roep de update-API aan met update_delay ingesteld op 0 om de verwerking onmiddellijk te activeren.
Geheugenzoekopdrachten retourneren geen resultaten. De scope waarde komt niet overeen met het bereik dat wordt gebruikt wanneer geheugens zijn opgeslagen. Gebruik hetzelfde bereik voor bijwerken en zoeken. Als u het bereik toewijst aan gebruikers, gebruikt u een stabiele gebruikers-id.
Het antwoord van de agent gebruikt geen opgeslagen geheugen. De agent is niet geconfigureerd met het hulpprogramma voor geheugenzoekopdrachten of de naam van het geheugenarchief is onjuist. Controleer of de agentdefinitie het memory_search_preview hulpprogramma bevat en verwijst naar de juiste naam van het geheugenarchief.
Procedureel geheugen of standaard-TTL-instelling is niet van kracht na een update. In de nieuwste previewversie kunt u alleen standaardopties instellen bij het maken van het geheugenarchief. Maak het geheugenarchief opnieuw met de gewenste standaardinstellingen of controleer of uw API-versie ondersteuning biedt voor updates na het maken van opties.
Een expliciet verzoek om iets te onthouden of te vergeten retourneerde geen geheugenopdrachten in de respons. Geheugenhulpprogramma's zijn niet correct geconfigureerd of de invoer is niet herkend als een opdracht voor onthouden of vergeten. Bevestig de configuratie van de geheugentool en test met directe bewoordingen als 'onthouden of vergeten'.

Verwante inhoud

  • Last updated on