Skapa och använda minne i Foundry Agent Service (förhandsversion)

Viktigt

Minne (förhandsversion) i Foundry Agent Service och Api för minneslagring (förhandsversion) licensieras till dig som en del av din Azure-prenumeration och omfattas av villkor som gäller för "förhandsversioner" i Microsoft produktvillkor och Microsoft Products and Services Data Protection Addendum samt Microsoft Generativa AI Services-förhandsversioner i användningsvillkoren för Supplemental för Microsoft Azure förhandsversioner.

Minne i Foundry Agent Service är en hanterad, långsiktig minneslösning. Det möjliggör agentkontinuitet mellan sessioner, enheter och arbetsflöden. Genom att skapa och hantera minneslager kan du skapa agenter som behåller användarinställningar, upprätthåller konversationshistorik och levererar anpassade upplevelser.

Minneslager fungerar som beständig lagring och definierar vilka typer av information som är relevanta för varje agent. Du styr åtkomsten med hjälp av parametern scope , som segmenterade minne mellan användare för att säkerställa säkra och isolerade upplevelser.

Den här artikeln beskriver hur du skapar, hanterar och använder minneslager. För konceptuell information, se Minne i Foundry Agent Service.

Användningsstöd

Kapacitet Python SDK C# SDK JavaScript SDK REST API
Skapa, uppdatera, lista och ta bort minneslager ✔️ ✔️ ✔️ ✔️
Uppdatera och söka efter minnen ✔️ ✔️ ✔️ ✔️
Koppla minne till en prompt-agent ✔️ ✔️ ✔️ ✔️

Förutsättningar

Auktorisering och behörigheter

Vi rekommenderar rollbaserad åtkomstkontroll för produktionsdistributioner. Om roller inte är möjliga hoppar du över det här avsnittet och använder nyckelbaserad autentisering i stället.

Så här konfigurerar du rollbaserad åtkomst:

  1. Logga in på Azure-portalen.

  2. På ditt projekt:

    1. I den vänstra rutan väljer du Resurshanteringsidentitet>.
    2. Använd växlingsknappen för att aktivera en systemtilldelad hanterad identitet.
  3. På resursen som innehåller projektet:

    1. Välj Åtkomstkontroll (IAM) i den vänstra rutan.
    2. Välj Lägg tilllägg till >rolltilldelning.
    3. Tilldela Azure AI User till projektets hanterade identitet.

Konfigurera din miljö

Installera de paket som krävs:

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

Installera de paket som krävs:

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

Installera de paket som krävs:

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

Ange miljövariabler för projektslutpunkten och modelldistributionsnamnen:

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

Ange miljövariabler för projektslutpunkten, modelldistributioner, API-version och åtkomsttoken:

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

Förstå omfång

Parametern scope styr hur minnet partitioneras. Varje omfång i minneslagret behåller en isolerad uppsättning minnesobjekt. Om du till exempel skapar en kundsupportagent med minne bör varje kund ha sitt eget individuella minne.

Som utvecklare väljer du den nyckel som används för att lagra och hämta minnesobjekt. Rätt metod beror på hur du kommer åt minnet.

Via minnessökningsverktyget

När du kopplar minnessökningsverktyget till en agent, anger du värden för scope till {{$userId}} för att aktivera minnesisolering per användare utan att hårdkoda identifierare. Systemet löser automatiskt slutanvändarens identitet för varje svarsanrop från en av två källor:

  • x-memory-user-id begärandehuvud: Om det finns används huvudvärdet som användar-ID. Använd detta i proxy- eller serverdelsscenarier där tjänsten anropar API:et för en slutanvändares räkning.

  • Microsoft Entra autentiseringstoken: Om huvudet inte har angetts återgår systemet till anroparens klientorganisations-ID (TID) och objekt-ID (OID). Detta är standard i klientdelsscenarier där användare autentiserar direkt med Microsoft Entra.

Om du inte behöver isolering per användare använder du ett statiskt scope värde i stället.

Via minnes-API:er på låg nivå

När du anropar minnes-API:er direkt anger du scope uttryckligen i varje begäran. Du kan skicka ett statiskt värde, till exempel en universellt unik identifierare (UUID) eller en annan stabil identifierare från systemet. Automatisk extrahering av identiteter stöds inte för dessa åtgärder.

Skapa ett minneslager

Skapa ett dedikerat minneslager för varje agent för att upprätta tydliga gränser för minnesåtkomst och optimering. När du skapar ett minneslager anger du den chattmodell och inbäddningsmodelldistributioner som bearbetar ditt minnesinnehåll.

import os
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,
    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 for customer support agent",
)

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,
  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 for customer support agent",
  },
);

console.log(
  `Created memory store: ${memoryStore.name} (${memoryStore.id})`,
);
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 for customer support agent",
    "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,
        "user_profile_details": "Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
      }
    }
  }'

Tips

  • De återstående Python- och C#- och TypeScript-kodfragmenten bygger på klienten och variablerna som definieras i Skapa ett minneslager. Om du kör kodfragmenten separat ska du inkludera import- och klientinitieringskoden från det här avsnittet.
  • C#-kodfragmenten i den här artikeln använder synkrona metoder. För asynkron användning, se exemplen för minnessökningsverktyget och minneslagring.

Anpassa minne

Anpassa vilken information agenten lagrar för att effektivt och relevant hantera minnet samt vara sekretessvänligt. Använd parametern user_profile_details för att ange vilka typer av data som är viktiga för agentens funktion.

Ange exempelvis user_profile_details att prioritera "flygbolagspreferenser och kostbegränsningar" för en resebyrå. Den här fokuserade metoden hjälper minnessystemet att veta vilken information som ska extraheras, sammanfattas och checkas in i långtidsminnet.

Du kan också använda den här parametern för att undanta vissa typer av data, hålla minnet magert och kompatibelt med sekretesskraven. Ange till exempel user_profile_details "undvik irrelevanta eller känsliga data, till exempel ålder, ekonomi, exakt plats och autentiseringsuppgifter".

Uppdatera ett minneslager

Uppdatera egenskaper för minneslagring, till exempel description eller metadata, för att bättre hantera minneslager.

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

Lista minnesenheter

Hämta en lista över minneslager i projektet för att hantera och övervaka minnesinfrastrukturen.

# 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})`);
}
curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Använda minnen via ett agentverktyg

När du har skapat ett minneslager kan du koppla minnessökningsverktyget till en promptagent. Med det här verktyget kan agenten läsa från och skriva till ditt minnesarkiv under konversationer. Konfigurera verktyget med lämpliga inställningar för scope och update_delay för att styra när och hur minnen uppdateras.

Tips

För att koppla minnen till en enskild slutanvändare, ställ in scope till "{{$userId}}" i verktygsdefinitionen och använd x-memory-user-id: <user-id> som en header för varje svarsanrop. Systemet identifierar användaridentitetens omfattning. Utan header förfaller omfånget till anroparens Microsoft Entra-identitet (TID och OID). Mer information finns i Förstå omfång.

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}`,
);
# 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
            }
        ]
    }
}'

Skapa en konversation

Nu kan du skapa konversationer och begära agentsvar. I början av varje konversation matas statiska minnen in så att agenten har en omedelbar, beständig kontext. Kontextuella minnen hämtas per tur baserat på de senaste meddelandena för att informera varje svar.

Efter varje agentsvar anropar tjänsten internt update_memories. Faktiska skrivningar till långtidsminnet avaktiveras dock av update_delay inställningen. Uppdateringen är schemalagd och slutförs först efter den konfigurerade inaktivitetsperioden.

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 openaiClient = project.getOpenAIClient();

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

// Create an agent response to initial user message
const response = await openaiClient.responses.create(
  {
    conversation: conversation.id,
    input: "I prefer dark roast coffee",
  },
  {
    body: {
      agent: { 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 openaiClient.conversations.create();
console.log(`Created new conversation (id: ${newConversation.id})`);

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

console.log(`Response output: ${newResponse.output_text}`);
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"
      }
    }'

Använda minnen via API:er

Du kan interagera med ett minneslager direkt med hjälp av minneslagrings-API:erna. Börja med att lägga till minnen från konversationsinnehåll i minnesarkivet och sök sedan efter relevanta minnen för att ge kontext för agentinteraktioner.

Lägga till minnen i ett minnesarkiv

Lägg till minnen genom att tillhandahålla konversationsinnehåll i minnesarkivet. Systemet förbearbetar och efterbearbetar data, inklusive extrahering och konsolidering av minne, för att optimera agentens minne. Den här långvariga åtgärden kan ta ungefär en minut.

Bestäm hur du ska segmentera minne mellan användare genom att ange parametern scope . Du kan begränsa minnet till en specifik slutanvändare, ett team eller en annan identifierare.

Du kan uppdatera ett minneslager med innehåll från flera konversationers turer eller uppdatera efter varje tur och kedja samman uppdateringar med hjälp av föregående uppdateringsåtgärds-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}`,
  );
}
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}"

Sök efter minnen i ett minnesarkiv

Sök efter minnen för att hämta relevant kontext för agentinteraktioner. Ange namn och omfång för minnesarkivet för att begränsa sökningen.

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}`,
  );
}
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
    }
  }'

Hämta statiska eller kontextuella minnen

Ofta kan användarprofilminnen inte hämtas baserat på semantisk likhet med en användares meddelande. Vi rekommenderar att du matar in statiska minnen i början av varje konversation och använder kontextuella minnen för att generera varje agentsvar.

  • Om du vill hämta statiska minnen anropar du search_memories med ett scope men utan items eller previous_search_id. Detta returnerar användarprofilminnen som är associerade med omfånget.

  • Om du vill hämta kontextuella minnen, anropar du search_memories med items som är inställt på de senaste meddelandena. Detta kan returnera både användarprofil och chattsammanfattningsminnen som är mest relevanta för de angivna objekten.

Mer information om användarprofil och chattsammanfattningsminnen finns i Minnestyper.

Ta bort minnen

Varning

Innan du tar bort ett minneslager bör du överväga effekten på beroende agenter. Agenter med anslutna minneslager kan förlora åtkomst till historisk kontext.

Minnen ordnas efter omfång i ett minnesarkiv. Du kan ta bort minnen för ett visst omfång för att ta bort användarspecifika data, eller så kan du ta bort hela minnesarkivet för att ta bort alla minnen i alla omfång.

Ta bort minnen efter område

Ta bort alla minnen som är associerade med en viss användare eller gruppomfattning samtidigt som minneslagringsstrukturen bevaras. Använd den här åtgärden för att hantera begäranden om borttagning av användardata eller återställa minnet för specifika användare.

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

Ta bort ett minnesarkiv

Ta bort hela minnesarkivet och alla associerade minnen i alla omfång. Den här åtgärden kan inte ångras.

# 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);
curl -X DELETE "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Metodtips

  • Implementera åtkomstkontroller per användare: Undvik att ge agenter åtkomst till minnen som delas mellan alla användare. Använd egenskapen scope för att partitionering av minnesarkivet efter användare. När du delar scope mellan användare använder user_profile_details du för att instruera minnessystemet att inte lagra personlig information.

  • Mappa omfång till slutanvändaren: När du använder verktyget för minnessökning anger du scope till {{$userId}} i verktygsdefinitionen. Systemet identifierar användaridentiteten från rubriken i förfrågan x-memory-user-id, om den finns. Annars återgår den till anroparens Microsoft Entra token ({tid}_{oid}).

  • Minimera och skydda känsliga data: Lagra endast det som behövs för ditt användningsfall. Om du måste lagra känsliga data, till exempel personliga data, hälsodata eller konfidentiella affärsindata, redigera eller ta bort annat innehåll som kan användas för att spåra tillbaka till en individ.

  • Supportsekretess och efterlevnad: Ge användarna insyn, inklusive alternativ för att komma åt och ta bort sina data. Registrera alla borttagningar i en granskningslogg som visar manipulering. Se till att systemet följer lokala efterlevnadskrav och regelstandarder.

  • Segmentera data och isolera minne: Segmentera minnet logiskt och operativt i system med flera agenter. Tillåt kunder att definiera, isolera, inspektera och ta bort sitt eget minnesfotavtryck.

  • Övervaka minnesanvändning: Spåra tokenanvändning och minnesåtgärder för att förstå kostnader och optimera prestanda.

Felsökning

Frågan Orsak Upplösning
Begäranden misslyckas med ett autentiserings- eller auktoriseringsfel. Din identitet eller projekthanterade identitet har inte de roller som krävs. Kontrollera rollerna i auktorisering och behörigheter. För REST-anrop genererar du en ny åtkomsttoken och försöker igen.
Minnen visas inte efter en konversation. Minnesuppdateringarna är uppdelade eller bearbetas fortfarande. Öka väntetiden eller anropa uppdaterings-API:et med update_delay inställt på att 0 utlösa bearbetning omedelbart.
Minnessökning returnerar inga resultat. Värdet scope matchar inte det omfång som användes när minnen lagrades. Använd samma omfång för uppdatering och sökning. Om du mappar omfånget till användare använder du en stabil användaridentifierare.
Agentsvaret använder inte lagrat minne. Agenten har inte konfigurerats med minnessökningsverktyget, eller så är minneslagringsnamnet felaktigt. Bekräfta att agentdefinitionen memory_search_preview innehåller verktyget och refererar till rätt namn på minnesarkivet.