Início Rápido: Fornecer memória persistente a um agente hospedado

Importante

Os itens marcados como visualização neste artigo estão atualmente em versão prévia. Esta versão prévia é fornecida sem um contrato de nível de serviço (SLA), e a Microsoft não a recomenda para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Neste início rápido, você fornece a um agente hospedado memória semântica persistente apoiada por um repositório de memória do Foundry. Sem memória, cada conversa começa do zero. Com um repositório de memória, o agente retém fatos estáveis sobre um usuário, como um nome ou uma preferência alimentar, e os lembra em sessões posteriores.

Você conclui duas partes:

• Provisione um repositório de memória e conecte-o ao agente. No fluxo da Azure Developer CLI, um hook de provisionamento integrado é executado após azd provision. No caminho Python, você cria o repositório diretamente com o SDK. A loja usa um modelo de chat e um modelo de inserção para extrair e indexar memórias de perfil de usuário.
• Implante um agente hospedado que lê e grava o repositório por meio de FoundryMemoryProvider. O provedor recupera memórias relevantes antes de cada chamada de modelo e atualiza o repositório com novos fatos após cada turno.

O código do agente, o provedor de memória e a autenticação vêm do exemplo de memória do Foundry, portanto, você se concentra no fluxo de trabalho em vez da implementação.

Se você usar um agente de codificação como GitHub Copilot, o Microsoft Foundry Skill poderá ajudar a provisionar o repositório de memória, conectá-lo ao agente hospedado e testar o comportamento de recall.

Pré-requisitos

Este guia de início rápido se baseia no conjunto de ferramentas do agente hospedado. Conclua os pré-requisitos no início rápido do agente hospedado primeiro, que abrangem a assinatura Azure, as funções de projeto, Python, a CLI do Desenvolvedor do Azure (azd) e a microsoft.foundry extensão.

Você usa o Azure Developer CLI neste diretório para gerar a estrutura do exemplo, provisionar o armazenamento de memória por meio de um hook postprovision incluído no pacote, executar o agente localmente e implantá-lo.

Você usa o SDK do Python neste caminho para criar o repositório de memória com AIProjectClient.beta.memory_stores.create(...), carregar o código do agente hospedado como uma nova versão, rotear o tráfego para ele temporariamente e validar que o mesmo usuário autenticado é reconhecido em chamadas separadas.

Instale os pacotes de Python usados neste caminho:

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

Use o SDK do .NET neste caminho para criar o repositório de memória com AIProjectClient.MemoryStores.CreateMemoryStore(...), carregar o código do agente hospedado como uma nova versão, direcionar o tráfego para ele temporariamente e validar que o mesmo usuário autenticado seja reconhecido em chamadas separadas.

Você também precisa do SDK do .NET 10 ou posterior.

Também é necessária uma implantação de um modelo de incorporação no seu projeto do Foundry, como text-embedding-3-small. O repositório de memória o usa para indexar memórias. O modelo de chat do agente, como gpt-4o, pode ser a mesma implantação que você já usa para agentes hospedados.

Sua identidade precisa ter a função Usuário do Foundry no escopo do projeto do Foundry, nos pré-requisitos do agente hospedado e também precisa ter a função Usuário do OpenAI de Serviços Cognitivos no mesmo escopo. O armazenamento de memória usa o acesso ao plano de dados do projeto do Foundry, além da implantação de incorporação. Sem a função OpenAI, as gravações de memória falham com um 401 erro e o repositório permanece vazio.

Importante

As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

Etapa 1: inicializar o agente hospedado

Inicializar um agente hospedado a partir do exemplo de memória do Foundry. A inicialização copia os arquivos de exemplo, incluindo o script de provisionamento do repositório de memória e o gancho de provisionamento, em um novo diretório de serviço em src/. Execute esses comandos em um diretório vazio.

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 as instruções para selecionar sua assinatura, projeto e uma implantação de um modelo. Se você não tiver um projeto do Foundry, azd ai agent init orientará você na criação de um.

Etapa 2: Habilitar o provisionamento com um único comando

O exemplo inclui um postprovision gancho que cria o repositório de memória e o conecta ao agente automaticamente sempre que você executa azd provision. Registre o hook no nível superior do arquivo azure.yaml que azd ai agent init gerou.

Abra azure.yaml e adicione o seguinte bloco de nível superior. Substitua <agent-name> pela pasta de serviço que a inicialização criou em src/:

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

O gancho se localiza automaticamente e é idempotente. Funciona corretamente, independentemente do diretório de onde azd o invoque, e as reexecuções deixam um armazenamento existente inalterado.

Observação

Registre postprovision no nível superior de azure.yaml. Os hooks com escopo de serviço dão suporte apenas ao pacote e ao ciclo de vida de implantação, não ao provisionamento.

Etapa 3: Provisione o armazenamento de memória e os recursos do Azure

1. Aponte o hook para a implantação do modelo de inserção que alimenta a memória semântica do repositório:

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

2. Provisionamento

   azd provision
   

azd provision cria ou reutiliza seu projeto no Foundry e a implantação do modelo de chat. Em seguida, o hook postprovision:

• Cria o repositório de memória com o recurso de perfil de usuário habilitado e verifica-o no serviço.
• Define MEMORY_STORE_NAME para que o agente leia e grave esse repositório. O gancho persiste o nome no seu ambiente azd para execuções locais e no ambiente de serviço em azure.yaml para que azd deploy o envie para o contêiner.

O fluxo via CLI não mostra um comando create memory store separado, porque o hook incluído cuida dessa lógica de criação para você como parte de azd provision.

O hook define o nome do armazenamento como padrão para agent_framework_memory. Para usar um nome diferente, defina-o antes de provisionar:

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

Etapa 4: Executar o agente localmente

1. Inicie o agente:

   azd ai agent run
   

   Esse comando cria um ambiente virtual, instala dependências e atende ao agente em http://localhost:8088. O hook já define MEMORY_STORE_NAME no seu ambiente azd, portanto, você não precisa de configuração adicional. Os pacotes de prévia podem gerar avisos do pip durante a instalação. Esses avisos não bloqueiam.

2. Em um terminal separado, diga ao agente um fato sobre si mesmo:

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

3. Inicie uma nova sessão e confirme se o agente lembra o fato da Store em vez do histórico de conversas:

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

   O agente responde com seu nome e preferência, o que prova que ele os recuperou do repositório de memória.

Etapa 5: Implantar no Serviço de Agente do Foundry

Implante o código-fonte do agente. azd empacota a origem como um arquivo ZIP e o carrega no Foundry, que resolve dependências e cria o agente hospedado remotamente. O hook postprovision já grava MEMORY_STORE_NAME em azure.yaml, portanto o agente implantado lê o mesmo armazenamento:

azd deploy

Quando o comando termina, a saída mostra links para o playground do agente e o ponto de extremidade do agente. Verifique a memória em diferentes sessões no agente implementado. Armazene uma informação:

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

Em seguida, lembre-o em uma nova sessão:

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

O agente implantado responde com o nome e a alergia lembrados.

Etapa 1: Criar ou escolher um projeto do Foundry

1. Abra o portal do Foundry e crie um projeto do Foundry ou selecione um existente.

2. No projeto, implante:

   • Um modelo compatível com chat, como gpt-5.4-mini.
   • Um modelo de inserção, como text-embedding-3-small.

3. Copie o ponto de extremidade do projeto de Visão geral e os nomes das implantações de Compilação>Implantações.

Etapa 2: Baixar o exemplo de memória do Foundry

Faça um clone do repositório de exemplos do Foundry:

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

Crie uma pasta de trabalho para os scripts de implantação. Nessa pasta, crie um .env arquivo com estes 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>

Etapa 3: Provisionar o repositório de memória com Python

Esse script é seguro para ser executado novamente. Ele primeiro chama get(...) para verificar se o repositório de memória já existe. Ele só chamará create(...) se o repositório não for encontrado.

Crie um arquivo nomeado provision_memory_store.py na mesma pasta de trabalho 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())

Executar o script:

python provision_memory_store.py

Etapa 4: implantar o agente hospedado com Python

Crie um arquivo nomeado deploy_memory_agent.py na mesma pasta de trabalho 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,
            )

Executar o script:

python deploy_memory_agent.py

Este script envia a amostra de memória como uma nova versão do agente hospedado, aponta temporariamente o agente hospedado para essa versão, invoca-o duas vezes com o mesmo usuário conectado e restaura a configuração anterior do endpoint ao final.

Etapa 5: Verificar se a memória persiste

A primeira chamada armazena o fato no repositório de memória. A segunda chamada solicita o fato lembrado em uma solicitação separada. Se o repositório de memória estiver configurado corretamente, a resposta deverá mencionar o mesmo nome e preferência alimentar que você forneceu na primeira solicitação.

Etapa 1: Criar ou escolher um projeto do Foundry

1. Abra o portal do Foundry e crie um projeto do Foundry ou selecione um existente.

2. No projeto, implante:

   • Um modelo compatível com chat, como gpt-4o.
   • Um modelo de inserção, como text-embedding-3-small.

3. Copie o ponto de extremidade do projeto de Visão geral e os nomes das implantações de Compilação>Implantações.

Etapa 2: Baixar o exemplo de memória do Foundry

Faça um clone do repositório de exemplos do Foundry:

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

O exemplo de agente hospedado em C# está em samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/src/foundry-memory-rag. As próximas etapas implantam essa pasta como uma versão do agente hospedado. O exemplo lê sua configuração das seguintes variáveis de ambiente, que são definidas no contêiner pelo código de implantação:

Variable	Description
FOUNDRY_PROJECT_ENDPOINT	Endpoint do projeto Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME	Nome da implantação do modelo de chat.
AZURE_AI_EMBEDDING_DEPLOYMENT_NAME	Nome da implantação do modelo de inserção.
AZURE_AI_MEMORY_STORE_ID	Nome do repositório de memória. Usa foundry-memory-rag-store como padrão.

Etapa 3: Provisionar o repositório de memória com C#

Crie um aplicativo de console .NET e instale os pacotes. As APIs do repositório de memória estão em versão prévia, portanto, instale Azure.AI.Projects o pacote de pré-lançamento:

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

Esse código é seguro para ser executado novamente. Ele primeiro chama GetMemoryStore(...) para verificar se o repositório já existe e só chama CreateMemoryStore(...) se o repositório não for encontrado. Substitua Program.cs pelo código a seguir e defina endpoint, chatModel e embeddingModel com os valores do seu projeto:

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

Execute o aplicativo:

dotnet run

Etapa 4: Implantar o agente hospedado com C#

Crie um segundo aplicativo de console para o código de implantação:

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

In Program.cs, substitua o código existente pelo código a seguir. Definir endpoint, chatModel, embeddingModele samplePath para seus valores. samplePath é o caminho completo para a pasta de origem foundry-memory-rag clonada na Etapa 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);
}

Execute o aplicativo:

dotnet run

Esse código envia a amostra de memória como uma nova versão do agente hospedado, aponta temporariamente o agente hospedado para essa versão, invoca-o duas vezes como o mesmo usuário autenticado e restaura a configuração anterior do ponto de extremidade ao finalizar.

Etapa 5: Verificar se a memória persiste

A primeira chamada armazena o fato no repositório de memória. A segunda chamada solicita o fato lembrado em uma solicitação separada. Se o repositório de memória estiver configurado corretamente, a resposta mencionará o mesmo nome e preferência alimentar que você forneceu na primeira solicitação. A extração de memória é assíncrona, portanto, permita que alguns segundos entre as duas chamadas para o repositório indexem a memória.

Limpar os recursos

Exclua os recursos quando terminar de usá-los para deixar de gerar cobranças.

Para excluir o repositório de memória, use o AIProjectClient. Execute este script em um ambiente Python que tenha os pacotes azure-ai-projects e azure-identity instalados (por exemplo, execute 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())

Exclua o agente e seus recursos de Azure:

Warning

Se o ambiente atual azd criou o projeto Foundry, azd down exclui permanentemente o grupo de recursos do projeto e tudo o que está nele. Se você selecionou um projeto existente durante a inicialização, azd down deixa o projeto, seu grupo de recursos, o agente hospedado e outros recursos de início rápido em vigor. Para excluir recursos que você não precisa mais do projeto existente, exclua-os separadamente.

azd down

Para excluir o repositório de memória, use o mesmo padrão de script com o nome do repositório de memória:

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

Se você criou um grupo de recursos dedicado ou um projeto para este início rápido, exclua-o no portal do Azure quando você não precisar mais da implantação do chat, da implantação de embeddings ou do agente hospedado.

O código de implantação já exclui a versão do agente hospedado e restaura a configuração anterior do endpoint quando ele termina. Para excluir o repositório de memória, adicione este código a um aplicativo de console que tenha o Azure.AI.Projects (pré-lançamento) e Azure.Identity os pacotes 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}'.");

Se você criou um grupo de recursos dedicado ou um projeto para este início rápido, exclua-o no portal do Azure quando você não precisar mais da implantação do chat, da implantação de embeddings ou do agente hospedado.

Troubleshooting

Issue	Solução
O agente implantado não tem memória ou MEMORY_STORE_NAME está vazio	Confirme se o gancho postprovision foi executado durante azd provision e se azure.yaml tem MEMORY_STORE_NAME definido. Execute novamente azd provision para executar o hook novamente.
As gravações de memória falham com um 401 erro e o repositório permanece vazio	Confirme se o chamador já possui acesso de Usuário do Foundry no escopo do projeto do Foundry e atribua a função Usuário do OpenAI de Serviços Cognitivos no mesmo escopo à sua identidade e à identidade de tempo de execução do agente implantado.
azd provision falha com um erro de permissões	Confirme se sua identidade tem as funções de projeto listadas nos pré-requisitos.
project.beta.memory_stores.create(...) falha ao usar Authentication to the Azure OpenAI resource failed	Confirme se sua identidade já possui acesso de Usuário do Foundry no escopo do projeto do Foundry e também possui a função Usuário do OpenAI de Serviços Cognitivos nesse escopo. Verifique também se AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME aponta para uma implantação de incorporações válida.
A implantação em Python é bem-sucedida, mas a segunda chamada não recupera o fato armazenado	Aguarde mais alguns segundos antes da segunda chamada para que o repositório de memória conclua a indexação e execute o script novamente.
O agente não se lembra de um fato que você compartilhou	Permita alguns segundos depois de armazenar um fato antes de consultar, para que o repositório conclua a indexação da memória.
O agente não pode ler ou gravar memórias após a implantação	Confirme se o postprovision hook criou o armazenamento no mesmo projeto em que o agente está implantado.

O que você aprendeu

Neste guia de início rápido, você:

• Criou um repositório de memória do Foundry com a funcionalidade de perfil do usuário.
• Implante um agente hospedado que lê e grava no repositório por meio de FoundryMemoryProvider, usando a Azure Developer CLI, o SDK do Python ou o SDK do .NET.
• Foi verificado que o agente se recorda de informações do usuário em sessões distintas, seja localmente com o Azure Developer CLI, seja remotamente com o SDK do Python ou do .NET após a implantação.

Próxima etapa

Avaliar seu agente hospedado

Conteúdo relacionado

• O que são agentes hospedados?
• Anexar memória a um agente
• Início Rápido: Implantar seu primeiro agente hospedado
• Gerenciar agentes hospedados