Inicio rápido: Concesión de memoria persistente de un agente hospedado

Importante

Los elementos marcados como versión preliminar en este artículo se encuentran actualmente en versión preliminar. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y Microsoft no lo recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

En este inicio rápido, darás al agente hospedado una memoria semántica persistente respaldada por un almacén de memoria de Foundry. Sin memoria, cada conversación comienza desde cero. Con un almacén de memoria, el agente conserva hechos estables sobre un usuario, como un nombre o una preferencia alimentaria, y los recuerda en sesiones posteriores.

Debes completar dos partes:

  • Cree un almacén de memoria y conéctelo al agente. En la ruta de la CLI de desarrollador de Azure, se ejecuta un gancho de aprovisionamiento integrado después de azd provision. En Python, se crea el almacén directamente con el SDK. El almacén usa un modelo de chat y un modelo de inserción para extraer e indexar memorias del perfil de usuario.
  • Implemente un agente hospedado que lea y escriba en el almacén mediante FoundryMemoryProvider. El proveedor recupera las memorias pertinentes antes de cada llamada al modelo y actualiza el almacén con nuevos datos después de cada turno.

El código del agente, el proveedor de memoria y la autenticación proceden del ejemplo de memoria Foundry, por lo que se centra en el flujo de trabajo en lugar de en la implementación.

Si usa un agente de codificación como GitHub Copilot, la aptitud de Microsoft Foundry puede ayudar a aprovisionar el almacén de memoria, conectarlo al agente hospedado y probar el comportamiento de recuperación.

Prerequisites

Esta guía de inicio rápido se basa en la cadena de herramientas del agente hospedado. Complete primero los requisitos previos del inicio rápido del agente hospedado, que abarcan la suscripción Azure, los roles de proyecto, Python, la CLI de Azure Developer (azd) y la microsoft.foundry extensión.

En esta ruta, se utiliza la CLI de desarrollador de Azure para generar el esqueleto del ejemplo, aprovisionar el almacén de memoria mediante un gancho postprovision integrado, ejecutar el agente localmente e implementarlo.

Utiliza el SDK de Python en esta ruta para crear el almacén de memoria con AIProjectClient.beta.memory_stores.create(...), cargar el código del agente alojado como una nueva versión, redirigir temporalmente el tráfico hacia él y validar que se siga reconociendo al mismo usuario que ha iniciado sesión en llamadas distintas.

Instale los paquetes de Python usados en esta ruta de acceso:

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

Utilice el SDK de .NET en esta ruta para crear el almacén de memoria con AIProjectClient.MemoryStores.CreateMemoryStore(...), cargue el código del agente hospedado como una nueva versión, redirija temporalmente el tráfico a esa versión y compruebe que se recuerda al mismo usuario que ha iniciado sesión en llamadas independientes.

También necesita el SDK de .NET 10 o posterior.

También necesita una implementación de modelo de inserción en su proyecto de Foundry, como text-embedding-3-small. El almacén de memoria lo usa para indexar memorias. El modelo de chat del agente, como gpt-4o, puede ser la implementación que ya usa para agentes hospedados.

Su identidad necesita el rol Usuario de Foundry en el ámbito del proyecto de Foundry a través de los requisitos previos del agente hospedado, y también necesita el rol Usuario de Cognitive Services OpenAI en el mismo ámbito. El almacén de memoria utiliza el acceso al plano de datos del proyecto de Foundry, además de la implementación de incrustación. Sin el rol de OpenAI, las escrituras en la memoria generan un error con un error 401 y el almacén permanece vacío.

Importante

Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

Paso 1: Inicialización del agente hospedado

Inicializar un agente alojado a partir del ejemplo de memoria de Foundry. La inicialización copia los archivos de ejemplo, incluido el script de aprovisionamiento del almacén de memoria y el enlace de aprovisionamiento, en un nuevo directorio de servicio dentro de src/. Ejecute estos comandos en un directorio vacío.

mkdir my-memory-agent
cd my-memory-agent
azd ai agent init -t "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/azure.yaml"

Siga las indicaciones para seleccionar la suscripción, el proyecto y una implementación de modelos. Si no tiene un proyecto de Foundry, azd ai agent init le guía en la creación de uno.

Paso 2: Habilitar el aprovisionamiento con un solo comando

El ejemplo incluye un postprovision hook que crea el almacén de memoria y lo conecta automáticamente al agente cada vez que ejecutas azd provision. Registre el enlace en el nivel superior del archivo azure.yaml que generó azd ai agent init.

Abra azure.yaml y agregue el siguiente bloque de nivel superior. Reemplace por <agent-name> la carpeta de servicio que creó la inicialización en src/:

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

El enlace se localiza automáticamente y es idempotente. Se ejecuta correctamente con independencia del directorio desde el que azd lo invoque, y las nuevas ejecuciones dejan intacto cualquier almacén existente.

Note

Registre postprovision en el nivel superior de azure.yaml. Los enlaces con ámbito de servicio solo admiten el ciclo de vida de empaquetado e implementación, no el aprovisionamiento.

Paso 3: Aprovisionar el almacén de memoria y los recursos de Azure

  1. Dirija el enlace a la implementación del modelo de inserción que alimenta la memoria semántica del almacén:

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

  2. Provisión:

    azd provision

azd provision crea o reutiliza su proyecto de Foundry y la implementación del modelo de chat. A continuación, el enlace postprovision:

  • Crea el almacén de memoria con la funcionalidad de perfil de usuario habilitada y la comprueba en el servicio.
  • Establece MEMORY_STORE_NAME para que el agente lea y escriba en ese almacén. El hook persiste el nombre en su entorno azd para las ejecuciones locales y en el entorno del servicio en azure.yaml, de modo que azd deploy lo envía al contenedor.

En el flujo de la CLI no aparece un comando independiente create memory store porque el hook incluido se encarga de esa lógica de creación como parte de azd provision.

El hook establece el nombre del store de forma predeterminada en agent_framework_memory. Para usar un nombre diferente, configúrelo antes de realizar el aprovisionamiento:

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

Paso 4: Ejecución del agente de forma local

  1. Inicie el agente:

    azd ai agent run

    Este comando crea un entorno virtual, instala dependencias y sirve al agente en http://localhost:8088. El hook ya configura MEMORY_STORE_NAME en tu entorno azd, por lo que no necesitas configuración adicional. Los paquetes en versión preliminar pueden generar advertencias de pip durante la instalación. Estas advertencias no son bloqueantes.

  2. En un terminal independiente, indique al agente un hecho sobre usted mismo:

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

  3. Inicie una nueva sesión y confirme que el agente recuerda el dato desde el almacén, y no desde el historial de conversación:

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

    El agente responde con su nombre y su preferencia, lo que demuestra que los recuperó del almacén de memoria.

Paso 5: Implementación en Foundry Agent Service

Implemente el código fuente del agente. azd empaqueta el origen como un archivo ZIP y lo carga en Foundry, que resuelve las dependencias y compila el agente hospedado de forma remota. El gancho postprovision ya escribe MEMORY_STORE_NAME en azure.yaml, por lo que el agente desplegado lee el mismo almacén:

azd deploy

Una vez finalizado el comando, la salida muestra enlaces al entorno de pruebas del agente y al punto de conexión del agente. Compruebe la memoria entre sesiones del agente implementado. Almacenar un hecho:

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

A continuación, recuárdalo en una sesión nueva:

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

El agente implementado responde con el nombre y la alergia recordados.

Paso 1: Crear o elegir un proyecto de Foundry

  1. Abra el portal de Foundry y cree un proyecto foundry o seleccione uno existente.

  2. En el proyecto, implemente:

    • Un modelo compatible con chat, como gpt-5.4-mini.
    • Un modelo de inserción, como text-embedding-3-small.

  3. Copie el punto de conexión del proyecto de Información general y los nombres de las implementaciones de Compilación>Implementaciones.

Paso 2: Descargar el ejemplo de memoria de Foundry

Clona el repositorio de ejemplos de Foundry:

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

Cree una carpeta de trabajo para los scripts de implementación. En esa carpeta, cree un .env archivo con estos valores:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-chat-model-deployment-name>
AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME=<your-embedding-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=memory-agent
MEMORY_STORE_NAME=agent_framework_memory
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/13-foundry-memory/src/agent-framework-agent-foundry-memory-responses>

Paso 3: Aprovisionar el almacén de memoria con Python

Este script es seguro para volver a ejecutarse. Primero llama a get(...) para comprobar si el almacén de memoria ya existe. Solo llama a create(...) si no se encuentra el almacén.

Cree un archivo denominado provision_memory_store.py en la misma carpeta de trabajo que .env:

import asyncio
import os

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
    MemoryStoreDefaultDefinition,
    MemoryStoreDefaultOptions,
)
from azure.core.exceptions import ResourceNotFoundError
from azure.identity.aio import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()


async def main() -> None:
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    memory_store_name = os.environ["MEMORY_STORE_NAME"]
    chat_model = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
    embedding_model = os.environ["AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME"]

    async with (
        DefaultAzureCredential() as credential,
        AIProjectClient(
            endpoint=endpoint,
            credential=credential,
            allow_preview=True,
        ) as project,
    ):
        try:
            existing = await project.beta.memory_stores.get(name=memory_store_name)
            print(
                f"Memory store '{existing.name}' already exists "
                f"(id={existing.id}); leaving as-is."
            )
            return
        except ResourceNotFoundError:
            pass

        definition = MemoryStoreDefaultDefinition(
            chat_model=chat_model,
            embedding_model=embedding_model,
            options=MemoryStoreDefaultOptions(
                chat_summary_enabled=False,
                user_profile_enabled=True,
                user_profile_details=(
                    "Avoid irrelevant or sensitive data, such as age, "
                    "financials, precise location, and credentials"
                ),
            ),
        )

        created = await project.beta.memory_stores.create(
            name=memory_store_name,
            description="Memory store for the hosted-agent memory quickstart",
            definition=definition,
        )
        print(f"Created memory store '{created.name}' (id={created.id}).")


asyncio.run(main())

Ejecute el script:

python provision_memory_store.py

Paso 4: Implementación del agente hospedado con Python

Cree un archivo denominado deploy_memory_agent.py en la misma carpeta de trabajo que .env:

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointConfig,
    CodeConfiguration,
    CodeDependencyResolution,
    FixedRatioVersionSelectionRule,
    HostedAgentDefinition,
    ProtocolConfiguration,
    ProtocolVersionRecord,
    ResponsesProtocolConfiguration,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "memory-agent")
memory_store_name = os.environ["MEMORY_STORE_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
    zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
    excluded = {".git", ".venv", "__pycache__", ".env"}

    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
        for path in source_dir.rglob("*"):
            if not path.is_file():
                continue
            if any(part in excluded for part in path.parts):
                continue
            zip_file.write(path, path.relative_to(source_dir))

    return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
    for attempt in range(60):
        time.sleep(10)
        details = project_client.agents.get_version(
            agent_name=agent_name,
            agent_version=version,
        )
        status = details["status"]
        print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

        if status == "active":
            return

        if status == "failed":
            raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

    raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
    code_zip_path.open("rb") as code_stream,
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=endpoint,
        credential=credential,
        allow_preview=True,
    ) as project_client,
):
    original_agent_endpoint = None
    created = None

    try:
        created = project_client.agents.create_version_from_code(
            agent_name=agent_name,
            description="Hosted agent with persistent Foundry memory.",
            definition=HostedAgentDefinition(
                cpu="0.5",
                memory="1Gi",
                code_configuration=CodeConfiguration(
                    runtime="python_3_13",
                    entry_point=["python", "main.py"],
                    dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
                ),
                environment_variables={
                    "FOUNDRY_PROJECT_ENDPOINT": endpoint,
                    "AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
                    "MEMORY_STORE_NAME": memory_store_name,
                },
                protocol_versions=[
                    ProtocolVersionRecord(protocol="responses", version="2.0.0")
                ],
            ),
            code=code_stream,
        )

        print(f"Created hosted agent version {created.version}")
        wait_for_active_version(project_client, created.version)

        original_agent_endpoint = project_client.agents.get(
            agent_name=agent_name
        ).agent_endpoint

        project_client.agents.update_details(
            agent_name=agent_name,
            agent_endpoint=AgentEndpointConfig(
                version_selector=VersionSelector(
                    version_selection_rules=[
                        FixedRatioVersionSelectionRule(
                            agent_version=created.version,
                            traffic_percentage=100,
                        ),
                    ]
                ),
                protocol_configuration=ProtocolConfiguration(
                    responses=ResponsesProtocolConfiguration()
                ),
            ),
        )

        with project_client.get_openai_client(agent_name=agent_name) as openai_client:
            first_response = openai_client.responses.create(
                input="Hi! My name is Linda and I'm vegetarian. Please remember that.",
            )
            print(first_response.output_text)

            time.sleep(10)

            second_response = openai_client.responses.create(
                input=(
                    "Do you remember my name and any dietary preference I told "
                    "you earlier?"
                ),
            )
            print(second_response.output_text)
    finally:
        if original_agent_endpoint is not None:
            project_client.agents.update_details(
                agent_name=agent_name,
                agent_endpoint=original_agent_endpoint,
            )

        if created is not None:
            project_client.agents.delete_version(
                agent_name=agent_name,
                agent_version=created.version,
                force=True,
            )

Ejecute el script:

python deploy_memory_agent.py

Este script carga la muestra de memoria como una nueva versión del agente hospedado, hace que el agente hospedado apunte temporalmente a esa versión, lo invoca dos veces como el mismo usuario que ha iniciado sesión y restaura la configuración anterior del punto de conexión cuando finaliza.

Paso 5: Comprobar que la memoria persiste

La primera llamada almacena el dato en el almacenamiento de memoria. La segunda llamada solicita el dato memorizado en una solicitud independiente. Si el almacén de memoria está configurado correctamente, la respuesta debe mencionar el mismo nombre y preferencia alimentaria que proporcionó en la primera solicitud.

Paso 1: Crear o elegir un proyecto de Foundry

  1. Abra el portal de Foundry y cree un proyecto foundry o seleccione uno existente.

  2. En el proyecto, implemente:

    • Un modelo compatible con chat, como gpt-4o.
    • Un modelo de inserción, como text-embedding-3-small.

  3. Copie el punto de conexión del proyecto de Información general y los nombres de las implementaciones de Compilación>Implementaciones.

Paso 2: Descargar el ejemplo de memoria de Foundry

Clona el repositorio de ejemplos de Foundry:

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

El ejemplo del agente hospedado de C# está en samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/src/foundry-memory-rag. Los pasos siguientes implementan esa carpeta como una versión del agente hospedado. El ejemplo lee su configuración de estas variables de entorno, que el código de implementación establece en el contenedor:

Variable Descripción
FOUNDRY_PROJECT_ENDPOINT Punto final de proyecto de Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME Nombre de implementación del modelo de chat.
AZURE_AI_EMBEDDING_DEPLOYMENT_NAME Inserción del nombre de implementación del modelo.
AZURE_AI_MEMORY_STORE_ID Nombre del almacenamiento de memoria. Tiene como valor predeterminado foundry-memory-rag-store.

Paso 3: Aprovisionamiento del almacén de memoria con C#

Cree una aplicación de consola de .NET e instale los paquetes. Las API de almacenamiento de memoria están en versión preliminar, por lo que debe instalar el paquete de versión Azure.AI.Projects preliminar:

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

Este código es seguro para volver a ejecutarse. Primero llama GetMemoryStore(...) a para comprobar si el almacén ya existe y solo llama CreateMemoryStore(...) a si no se encuentra el almacén. Reemplace Program.cs por el siguiente código y establezca endpoint, chatModel y embeddingModel con los valores de su proyecto:

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

#pragma warning disable AAIP001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var embeddingModel = "text-embedding-3-small";
var memoryStoreName = "foundry-memory-rag-store";

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

try
{
    MemoryStore existing = projectClient.MemoryStores.GetMemoryStore(memoryStoreName);
    Console.WriteLine($"Memory store '{existing.Name}' already exists (id={existing.Id}); leaving as-is.");
}
catch (ClientResultException ex) when (ex.Status == 404)
{
    MemoryStore created = projectClient.MemoryStores.CreateMemoryStore(
        memoryStoreName,
        new MemoryStoreDefaultDefinition(chatModel, embeddingModel)
        {
            Options = new MemoryStoreDefaultOptions(isUserProfileEnabled: true, isChatSummaryEnabled: false)
            {
                UserProfileDetails =
                    "Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials",
            },
        },
        description: "Memory store for the hosted-agent memory quickstart");
    Console.WriteLine($"Created memory store '{created.Name}' (id={created.Id}).");
}

Ejecute la aplicación:

dotnet run

Paso 4: Implementación del agente hospedado con C#

Cree una segunda aplicación de consola para el código de implementación:

dotnet new console --name deploy-memory-agent
cd deploy-memory-agent
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

En Program.cs, reemplace el código existente por el código siguiente. Establezca los valores de endpoint, chatModel, embeddingModel y samplePath. samplePath es la ruta de acceso completa a la foundry-memory-rag carpeta de origen que ha clonado en el paso 2:

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

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var embeddingModel = "text-embedding-3-small";
var agentName = "memory-agent";
var memoryStoreName = "foundry-memory-rag-store";
var samplePath =
    @"<path-to-foundry-samples>\samples\csharp\hosted-agents\agent-framework\foundry-memory-rag\src\foundry-memory-rag";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;

HostedAgentDefinition definition = new(cpu: "0.5", memory: "1Gi")
{
    Versions = { new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0") },
    CodeConfiguration = new(
        runtime: "dotnet_10",
        entryPoint: ["dotnet", "foundry-memory-rag.dll"],
        dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add("FOUNDRY_PROJECT_ENDPOINT", endpoint);
definition.EnvironmentVariables.Add("AZURE_AI_MODEL_DEPLOYMENT_NAME", chatModel);
definition.EnvironmentVariables.Add("AZURE_AI_EMBEDDING_DEPLOYMENT_NAME", embeddingModel);
definition.EnvironmentVariables.Add("AZURE_AI_MEMORY_STORE_ID", memoryStoreName);

ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;
try
{
    created = agentsClient.CreateAgentVersionFromCode(
        agentName, samplePath, new AgentVersionFromCodeMetadata(definition));
    Console.WriteLine($"Created hosted agent version {created.Version}");

    for (var attempt = 1; attempt <= 60; attempt++)
    {
        Thread.Sleep(TimeSpan.FromSeconds(10));
        created = agentsClient.GetAgentVersion(agentName, created.Version);
        Console.WriteLine($"Provisioning status: {created.Status} (attempt {attempt}/60)");
        if (created.Status == AgentVersionStatus.Active) break;
        if (created.Status == AgentVersionStatus.Failed)
            throw new InvalidOperationException("Hosted agent provisioning failed.");
    }

    ProjectsAgentRecord agent = agentsClient.GetAgent(agentName);
    originalEndpoint = agent.AgentEndpoint;
    agentsClient.PatchAgent(agentName, new PatchAgentOptions
    {
        AgentEndpoint = new AgentEndpointConfiguration
        {
            VersionSelector = new([new FixedRatioVersionSelectionRule(created.Version, 100)]),
            ProtocolConfiguration = new() { Responses = new ResponsesProtocolConfiguration() },
        },
    });

    ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgentEndpoint(agentName);

    ResponseResult first = responsesClient.CreateResponse(
        "Hi! My name is Linda and I'm vegetarian. Please remember that.");
    Console.WriteLine(first.GetOutputText());

    Thread.Sleep(TimeSpan.FromSeconds(10));

    ResponseResult second = responsesClient.CreateResponse(
        "Do you remember my name and any dietary preference I told you earlier?");
    Console.WriteLine(second.GetOutputText());
}
finally
{
    if (originalEndpoint is not null)
        agentsClient.PatchAgent(agentName, new PatchAgentOptions { AgentEndpoint = originalEndpoint });
    if (created is not null)
        agentsClient.DeleteAgentVersion(agentName, created.Version, force: true);
}

Ejecute la aplicación:

dotnet run

Este código carga la muestra de memoria como una nueva versión del agente hospedado, hace que el agente hospedado apunte temporalmente a esa versión, lo invoca dos veces como el mismo usuario con la sesión iniciada y restaura la configuración anterior del punto de conexión cuando finaliza.

Paso 5: Comprobar que la memoria persiste

La primera llamada almacena el dato en el almacenamiento de memoria. La segunda llamada solicita el dato memorizado en una solicitud independiente. Si el almacén de memoria está configurado correctamente, la respuesta menciona el mismo nombre y la misma preferencia dietética que proporcionaste en la primera petición. La extracción de memoria es asincrónica, así que deja pasar unos segundos entre las dos llamadas para que el almacén indexe la memoria.

Limpieza de recursos

Elimine los recursos cuando haya terminado para dejar de incurrir en cargos.

Para eliminar el almacén de memoria, utilice AIProjectClient. Ejecute este script en un entorno de Python que tenga instalados los azure-ai-projects paquetes y azure-identity (por ejemplo, ejecute pip install "azure-ai-projects>=2.3.0"):

import asyncio
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient

async def delete():
    async with (
        DefaultAzureCredential() as credential,
        AIProjectClient(
            endpoint="https://<account>.services.ai.azure.com/api/projects/<project>",
            credential=credential,
            allow_preview=True,
        ) as project,
    ):
        await project.beta.memory_stores.delete("agent_framework_memory")

asyncio.run(delete())

Elimine el agente y sus recursos de Azure:

Warning

Si el entorno actual azd creó el proyecto Foundry, azd down elimina permanentemente el grupo de recursos del proyecto y todo lo que contiene. Si seleccionó un proyecto existente durante la inicialización, azd down deja en su lugar el proyecto, su grupo de recursos, el agente alojado y otros recursos de inicio rápido. Para eliminar los recursos que ya no necesite del proyecto existente, elimínelos por separado.

azd down

Para eliminar el almacén de memoria, use el mismo patrón de script con el nombre del almacén de memoria:

import asyncio
import os

from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()


async def delete() -> None:
    async with (
        DefaultAzureCredential() as credential,
        AIProjectClient(
            endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            credential=credential,
            allow_preview=True,
        ) as project,
    ):
        await project.beta.memory_stores.delete(os.environ["MEMORY_STORE_NAME"])


asyncio.run(delete())

Si has creado un grupo de recursos o un proyecto específico para esta guía de inicio rápido, elimínalo del Azure Portal cuando ya no necesites la implementación de chat, la implementación incrustada o el agente hospedado.

El código de implementación ya elimina la versión del agente hospedado y restaura la configuración del punto de conexión anterior cuando finaliza. Para eliminar el almacén de memoria, agregue este código a una aplicación de consola con los Azure.AI.Projects paquetes (versión preliminar) y Azure.Identity instalados:

using Azure.AI.Projects;
using Azure.Identity;

#pragma warning disable AAIP001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var memoryStoreName = "foundry-memory-rag-store";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
projectClient.MemoryStores.DeleteMemoryStore(memoryStoreName);
Console.WriteLine($"Deleted memory store '{memoryStoreName}'.");

Si has creado un grupo de recursos o un proyecto específico para esta guía de inicio rápido, elimínalo del Azure Portal cuando ya no necesites la implementación de chat, la implementación incrustada o el agente hospedado.

Solución de problemas

Issue Solución
El agente implementado no tiene memoria o MEMORY_STORE_NAME está vacío Confirme que el hook postprovision se ejecutó durante azd provision y que azure.yaml tiene MEMORY_STORE_NAME configurado. Vuelva a ejecutar azd provision para ejecutar de nuevo el hook.
Las operaciones de escritura en memoria fallan con el error 401 y el almacén permanece vacío Comprueba que el usuario que realiza la llamada ya tenga acceso como Usuario de Foundry en el ámbito del proyecto de Foundry y concede el rol Usuario de Cognitive Services OpenAI en ese mismo ámbito a tu identidad y a la identidad de tiempo de ejecución del agente implementado.
azd provision falla con un error de permisos Confirme que su identidad tiene los roles de proyecto indicados en los requisitos previos.
project.beta.memory_stores.create(...) produce un error con Authentication to the Azure OpenAI resource failed Comprueba que tu identidad ya tenga acceso de Usuario de Foundry en el ámbito del proyecto de Foundry y que, además, tenga el rol de Usuario de OpenAI de Cognitive Services en ese ámbito. Comprueba también que AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME apunte a una implementación de integración válida.
La implementación de Python se realiza correctamente, pero la segunda llamada no recuerda el hecho almacenado Espere unos segundos más antes de la segunda llamada para que el almacén de memoria finalice la indexación y vuelva a ejecutar el script.
El agente no recuerda un hecho que ha compartido Espere unos segundos después de almacenar un dato antes de realizar una consulta, para que el sistema termine de indexar la memoria.
El agente no puede leer ni escribir memorias después de la implementación Confirme que el enlace postprovision creó el almacén en el mismo proyecto en el que está implementado el agente.

Lo que ha aprendido

En esta guía de inicio rápido:

  • Ha creado un almacén de memoria de Foundry con la capacidad de perfil de usuario.
  • Implementó un agente hospedado que lee y escribe en el almacén mediante FoundryMemoryProvider Azure CLI para desarrolladores, el SDK de Python o el SDK de .NET.
  • Se ha comprobado que el agente recupera los hechos del usuario en sesiones independientes, ya sea localmente con Azure CLI para desarrolladores o de forma remota con el SDK de Python o .NET después de la implementación.

Paso siguiente

Evaluación del agente hospedado

Contenido relacionado

  • Se actualizó por última vez el