Condividi tramite

Creare e usare la memoria nel servizio agente Foundry (anteprima)

Importante

La memoria (anteprima) nel servizio Foundry Agent e l'API Memory Store (anteprima) vengono concesse in licenza all'utente come parte della sottoscrizione di Azure e sono soggette alle condizioni applicabili alle "anteprime" nei Termini del prodotto Microsoft e nel Componente aggiuntivo per la protezione dei dati dei prodotti e dei servizi Microsoft, nonché alle condizioni per le anteprime dei servizi di intelligenza artificiale generativa di Microsoft nelle Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

La memoria nel servizio agente Foundry è una soluzione di memoria gestita a lungo termine. Consente la continuità dell'agente tra sessioni, dispositivi e flussi di lavoro. Creando e gestendo archivi di memoria, è possibile creare agenti che mantengono le preferenze utente, mantengono la cronologia delle conversazioni e offrono esperienze personalizzate.

Gli archivi di memoria fungono da risorsa di archiviazione permanente, definendo quali tipi di informazioni sono rilevanti per ogni agente. È possibile controllare l'accesso usando il parametro , che segmenta la scope memoria tra gli utenti per garantire esperienze sicure e isolate.

Questo articolo illustra come creare, gestire e usare archivi di memoria. Per informazioni concettuali, vedere Memory in Foundry Agent Service.

Supporto per l'utilizzo

Capability PYTHON SDK JavaScript SDK REST API
Creare, aggiornare, elencare ed eliminare archivi di memoria ✔️ ✔️ ✔️
Aggiornare e cercare ricordi ✔️ ✔️ ✔️
Collegare la memoria a un agente richiesta ✔️ ✔️ ✔️

Prerequisiti

Autorizzazione e autorizzazioni

È consigliabile controllare l'accesso in base al ruolo per le distribuzioni di produzione. Se i ruoli non sono fattibili, ignorare questa sezione e usare invece l'autenticazione basata su chiave.

Per configurare l'accesso in base al ruolo:

  1. Accedi al portale di Azure.
  2. Nel progetto:
    1. Nel riquadro sinistro selezionare Gestione risorse>Identità.
    2. Usare l'interruttore per abilitare un'identità gestita assegnata dal sistema.
  3. Nella risorsa che contiene il progetto:
    1. Nel riquadro sinistro selezionare Controllo di accesso (IAM).
    2. Seleziona Aggiungi>Aggiungi assegnazione ruolo.
    3. Assegna Azure AI User all'identità gestita del tuo progetto.

Impostare le variabili di ambiente

Impostare le variabili di ambiente per i nomi dell'endpoint del progetto e della distribuzione del modello:

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

Impostare le variabili di ambiente per l'endpoint del progetto, le distribuzioni di modelli, la versione dell'API e il token di accesso:

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

Comprendere l'ambito

Il scope parametro controlla la modalità di partizionamento della memoria. Ogni ambito nell'archivio di memoria mantiene una raccolta isolata di elementi di memoria. Ad esempio, se si crea un agente di supporto clienti con memoria, ogni cliente deve avere la propria memoria individuale.

Gli sviluppatori scelgono la chiave usata per archiviare e recuperare gli elementi di memoria. È possibile passare un valore statico, ad esempio un identificatore univoco universale (UUID) o un altro identificatore stabile dal sistema.

In alternativa, quando si specifica {{$userId}} come ambito, il sistema estrae automaticamente l'ID tenant (TID) e l'ID oggetto (OID) dall'intestazione di autenticazione della richiesta. Questo approccio offre a ogni utente autenticato la propria partizione di memoria isolata, eliminando la necessità di gestire manualmente gli identificatori.

Creare un archivio di memoria

Creare un archivio memoria dedicato per ogni agente per stabilire limiti chiari per l'accesso alla memoria e l'ottimizzazione. Quando si crea un archivio di memoria, specificare le distribuzioni del modello di chat e del modello di incorporamento che elaborano il contenuto della memoria.

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

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

Suggerimento

I frammenti di codice nelle sezioni rimanenti di questo articolo si basano sul client e sulle variabili definite in Creare un archivio di memoria. Se esegui questi frammenti in modo indipendente, includi il codice di importazione e inizializzazione del client da questa sezione.

Personalizzare la memoria

Personalizzare le informazioni archiviate dall'agente per mantenere la memoria efficiente, pertinente e rispetto della privacy. Usare il user_profile_details parametro per specificare i tipi di dati critici per la funzione dell'agente.

Ad esempio, impostare user_profile_details come priorità "preferenza vettore di volo e restrizioni dietetiche" per un agente di viaggio. Questo approccio incentrato consente al sistema di memoria di individuare i dettagli da estrarre, riepilogare e archiviare nella memoria a lungo termine.

È anche possibile usare questo parametro per escludere determinati tipi di dati, mantenendo la memoria snella e conforme ai requisiti di privacy. Ad esempio, impostare su user_profile_details "evitare dati irrilevanti o sensibili, ad esempio età, finanziari, posizione precisa e credenziali".

Aggiornare un archivio di memoria

Aggiornare le proprietà dell'archivio memoria, ad esempio description o metadata, per gestire meglio gli archivi di memoria.

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

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

Elencare gli archivi di memoria

Recuperare un elenco di archivi di memoria nel progetto per gestire e monitorare l'infrastruttura di memoria.

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

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

Usare le memorie tramite uno strumento agente

Dopo aver creato un archivio memoria, è possibile collegare lo strumento di ricerca della memoria a un agente prompt. Questo strumento consente all'agente di leggere e scrivere nell'archivio memoria durante le conversazioni. Configurare lo strumento con il appropriato scope e update_delay per controllare come e quando vengono aggiornati i ricordi.

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

# Set scope to associate the memories with
# You can also use "{{$userId}}" to take the TID and OID of the request authentication header
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})")

// Set scope to associate the memories with
// You can also use "{{$userId}}" to take the TID and OID of the request authentication header
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}`,
);

# Note: 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
            }
        ]
    }
}'

Creare una conversazione

È ora possibile creare conversazioni e richiedere risposte dell'agente. All'inizio di ogni conversazione, i ricordi statici vengono inseriti in modo che l'agente abbia un contesto immediato e permanente. I ricordi contestuali vengono recuperati per turno in base ai messaggi più recenti per informare ogni risposta.

Dopo ogni risposta dell'agente, il servizio chiama internamente update_memories. Tuttavia, le scritture effettive nella memoria a lungo termine vengono annullate dall'impostazione update_delay . L'aggiornamento è pianificato e viene completato solo dopo il periodo di inattività configurato.

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

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

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

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

Utilizzare memoria tramite API

È possibile interagire con un archivio di memoria direttamente usando le API dell'archivio di memoria. Per iniziare, aggiungere memorie dal contenuto della conversazione all'archivio memoria e quindi cercare memorie pertinenti per fornire contesto per le interazioni con l'agente.

Aggiungere ricordi a un archivio memoria

Aggiungi ricordi fornendo il contenuto della conversazione allo store di memoria. Il sistema pre-elabora e post-elabora i dati, inclusi l'estrazione e il consolidamento della memoria, per ottimizzare la memoria dell'agente. Questa operazione di lunga durata potrebbe richiedere circa un minuto.

Decidere come segmentare la memoria tra gli utenti specificando il scope parametro . È possibile definire l'ambito della memoria a un utente finale specifico, a un team o a un altro identificatore.

È possibile aggiornare un archivio di memoria con il contenuto di più turni di conversazione, oppure eseguire un aggiornamento dopo ogni turno concatenando gli aggiornamenti utilizzando l'ID dell'operazione di aggiornamento precedente.

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

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

Cercare ricordi in un archivio memoria

Cercare ricordi per recuperare il contesto pertinente per le interazioni con l'agente. Specificare il nome e l'ambito dell'archivio di memoria per restringere la ricerca.

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

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

Recupera ricordi statici o contestuali

Spesso, i ricordi del profilo utente non possono essere recuperati in base alla somiglianza semantica con il messaggio di un utente. È consigliabile inserire memorie statiche all'inizio di ogni conversazione e usare memorie contestuali per generare ogni risposta dell'agente.

  • Per recuperare memorie statiche, chiamare search_memories con un scope ma senza items o previous_search_id. In questo modo vengono restituite le memorie del profilo utente associate all'ambito.

  • Per recuperare i ricordi contestuali, chiamare search_memories con items impostato sui messaggi più recenti. Questo può restituire sia i ricordi di riepilogo del profilo utente che i ricordi di riepilogo della chat più rilevanti per gli elementi specificati.

Per altre informazioni sui ricordi di riepilogo del profilo utente e della chat, vedere Tipi di memoria.

Eliminare i ricordi

Avviso

Prima di eliminare un archivio di memoria, prendere in considerazione l'impatto sugli agenti dipendenti. Gli agenti con archivi di memoria collegati potrebbero perdere l'accesso al contesto cronologico.

I ricordi sono organizzati in base all'ambito all'interno di un archivio di memoria. È possibile eliminare i ricordi per un ambito specifico per rimuovere i dati specifici dell'utente oppure eliminare l'intero archivio memoria per rimuovere tutti i ricordi in tutti gli ambiti.

Eliminare i ricordi in base all'ambito

Rimuovere tutti i ricordi associati a un determinato ambito utente o gruppo mantenendo al tempo stesso la struttura dell'archivio memoria. Usare questa operazione per gestire le richieste di eliminazione dei dati utente o reimpostare la memoria per utenti specifici.

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

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

Eliminare un archivio di memoria

Rimuovere l'intera memoria e tutte le memorie associate in tutti gli ambiti. questa operazione è irreversibile.

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

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

Procedure consigliate

  • Implementare i controlli di accesso per utente: Evitare di concedere agli agenti l'accesso ai ricordi condivisi tra tutti gli utenti. Usare la scope proprietà per partizionare l'archivio di memoria in base all'utente. Quando si condivide scope tra gli utenti, usare user_profile_details per indicare al sistema di memoria di non archiviare le informazioni personali.

  • Eseguire il mapping dell'ambito a un utente autenticato: Quando si specifica l'ambito nello strumento di ricerca della memoria, impostare scope={{$userId}} per eseguire il mapping all'utente dal token di autenticazione ({tid}_{oid}). Ciò garantisce che le ricerche in memoria siano destinate automaticamente all'utente corretto.

  • Ridurre al minimo e proteggere i dati sensibili: Archiviare solo ciò che è necessario per il caso d'uso. Se è necessario archiviare dati sensibili, ad esempio dati personali, dati sanitari o input aziendali riservati, oscurare o rimuovere altri contenuti che possano essere utilizzati per risalire a una persona.

  • Supporto della privacy e della conformità: Fornire agli utenti la trasparenza, incluse le opzioni per accedere ed eliminare i dati. Registrare tutte le eliminazioni in un audit trail a prova di manomissione. Assicurarsi che il sistema rispetti i requisiti di conformità locali e gli standard normativi.

  • Segmentare i dati e isolare la memoria: Nei sistemi multi-agente segmentare la memoria in modo logico e operativo. Consentire ai clienti di definire, isolare, ispezionare ed eliminare la propria impronta di memoria.

  • Monitorare l'utilizzo della memoria: Tenere traccia dell'utilizzo dei token e delle operazioni di memoria per comprendere i costi e ottimizzare le prestazioni.

Risoluzione dei problemi

Problema Motivo Risoluzione
Le richieste hanno esito negativo con un errore di autenticazione o autorizzazione. L'identità o l'identità gestita del progetto non dispone dei ruoli necessari. Verificare i ruoli in Autorizzazione e autorizzazioni. Per le chiamate REST, generare un nuovo token di accesso e riprovare.
I ricordi non vengono visualizzati dopo una conversazione. Gli aggiornamenti della memoria sono soggetti a debounce o sono ancora in elaborazione. Aumentare il tempo di attesa o chiamare l'API di aggiornamento con update_delay impostato su 0 per attivare immediatamente l'elaborazione.
La ricerca di memoria non restituisce risultati. Il scope valore non corrisponde all'ambito usato durante l'archiviazione delle memorie. Usare lo stesso ambito per l'aggiornamento e la ricerca. Se si mappa l'ambito agli utenti, utilizzare un identificatore utente stabile.
La risposta dell'agente non usa la memoria archiviata. L'agente non è configurato con lo strumento di ricerca della memoria o il nome dell'archivio memoria non è corretto. Verificare che la definizione dell'agente includa lo memory_search_preview strumento e faccia riferimento al nome corretto dell'archivio di memoria.

Contenuti correlati

  • Last updated on