Quickstart: Dê a um agente hospedado memória persistente

Important

Os itens marcados como pré-visualização neste artigo estão atualmente em pré-visualização. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e a Microsoft não a recomenda para cargas de trabalho de produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos Suplementares de Utilização para Microsoft Azure Previews.

Neste quickstart, dá a um agente alojado memória semântica persistente, suportada por um armazenamento de memória Foundry. Sem memória, cada conversa começa do zero. Com um armazenamento de memória, o agente mantém factos estáveis sobre um utilizador, como um nome ou uma preferência alimentar, e recorda-os em sessões posteriores.

Conclui duas partes:

• Crie um armazenamento de memória e ligue-o ao agente. No caminho da CLI do Azure Developer, um hook de provisionamento agrupado executa-se após azd provision. No caminho Python, crias a loja diretamente com o SDK. A loja utiliza um modelo de chat e um modelo de embedding para extrair e indexar memórias de perfil de utilizador.
• Implemente um agente alojado que lê e escreve no armazenamento através de FoundryMemoryProvider. O fornecedor recupera memórias relevantes antes de cada chamada de modelo e atualiza a loja com novos factos após cada turno.

O código do agente, o fornecedor de memória e a autenticação vêm da amostra de memória do Foundry, por isso focas-te no fluxo de trabalho em vez da implementação.

Se usares um agente de programação como o GitHub Copilot, o Microsoft Foundry Skill pode ajudar a provisionar o armazenamento de memória, ligá-lo ao teu agente alojado e testar o comportamento de recordação.

Pré-requisitos

Este início rápido baseia-se na cadeia de ferramentas do agente hospedado. Complete primeiro os Pré-requisitos no quickstart do agente alojado, que abrangem a subscrição do Azure, funções de projeto, Python, a CLI do Azure Developer (azd) e a microsoft.foundry extensão.

Utiliza a CLI do Azure Developer neste percurso para criar a estrutura do exemplo, provisionar o armazenamento de memória através de um postprovision hook incluído, executar o agente localmente e implementá-lo.

Utilize o SDK do Python neste percurso para criar o armazenamento de memória com AIProjectClient.beta.memory_stores.create(...), carregar o código do agente alojado como uma nova versão, encaminhar temporariamente o tráfego para essa versão e validar que o mesmo utilizador com sessão iniciada é reconhecido em chamadas distintas.

Instale os pacotes Python usados neste caminho:

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

Utilize o SDK do .NET neste caminho para criar o armazenamento de memória com AIProjectClient.MemoryStores.CreateMemoryStore(...), carregar o código do agente alojado como uma nova versão, encaminhar temporariamente o tráfego para essa versão e validar que o mesmo utilizador com sessão iniciada é reconhecido em chamadas separadas.

Também precisas do SDK .NET 10 ou posterior.

Também precisa de uma implementação de um modelo de embedding no seu projeto Foundry, como text-embedding-3-small. O armazenamento de memória usa-o para indexar memórias. O modelo de chat do agente, como gpt-4o, pode ser a implementação que já usas para agentes alojados.

A sua identidade precisa do papel de Utilizador Foundry no âmbito do projeto Foundry através dos pré-requisitos de agente alojado, e também precisa do papel de Utilizador OpenAI de Serviços Cognitivos no mesmo âmbito. O armazenamento de memória utiliza o acesso ao plano de dados do projeto Foundry e a implementação de embeddings. Sem a função OpenAI, as gravações na memória falham com o erro 401 e o armazenamento permanece vazio.

Important

As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

Passo 1: Inicializar o agente hospedado

Inicializar um agente alojado a partir da amostra de memória do Foundry. A inicialização copia os ficheiros de exemplo, incluindo o script de provisionamento de memória e o gancho de provisionamento, para um novo diretório de serviço sob src/. Executa estes comandos num 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 a sua subscrição, projeto e uma implementação de modelo. Se não tens um projeto Foundry, azd ai agent init guia-te na criação de um.

Passo 2: Ativar o provisionamento com um único comando

O exemplo inclui um hook postprovision que cria o armazenamento em memória e liga-o automaticamente ao agente sempre que executa azd provision. Registe o hook ao nível superior do ficheiro azure.yaml gerado por azd ai agent init.

Abra azure.yaml e adicione o seguinte bloco de nível superior. Substitua <agent-name> pela pasta do 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 hook localiza-se automaticamente e é idempotente. É executado corretamente, independentemente do diretório a partir do qual azd o invoca, e as execuções subsequentes deixam inalterado qualquer armazenamento existente.

Note

Registe postprovision ao nível superior de azure.yaml. Os ganchos com âmbito de serviço suportam apenas o pacote e o ciclo de vida de implementação, não o provisionamento.

Passo 3: Provisionar o armazenamento de memória e os recursos do Azure

1. Aponte o gancho para a implementação do modelo de embedding que alimenta a memória semântica da loja:

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

2. Fornecimento

   azd provision
   

azd provision cria ou reutiliza o seu projeto Foundry e a implementação do modelo de chat. Depois, o postprovision hook:

• Cria o arquivo de memória com a funcionalidade de perfil de utilizador ativada e verifica-o no serviço.
• Define MEMORY_STORE_NAME para que o agente leia e escreva esse armazenamento. O hook 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 contentor.

O caminho da CLI não mostra um comando separado create memory store porque o hook agrupado executa essa lógica de criação para ti como parte de azd provision.

O hook define por omissão o nome da loja como agent_framework_memory. Para usar um nome diferente, defina-o antes de provisionar:

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

Passo 4: Executar o agente localmente

1. Inicie o agente:

   azd ai agent run
   

   Este comando cria um ambiente virtual, instala dependências e serve o agente em http://localhost:8088. O hook já define MEMORY_STORE_NAME no seu ambiente azd, por isso não precisa de configuração adicional. Os pacotes de pré-visualização podem gerar avisos de pip durante a configuração. Estes avisos não são impeditivos.

2. Num terminal separado, diga ao agente um facto sobre si:

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

3. Inicia uma nova sessão e confirma se o agente se lembra do facto da loja 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 o seu nome e a sua preferência, o que prova que os recuperou a partir do armazenamento de memória.

Passo 5: Implementar no Serviço Foundry Agent

Implementa o código-fonte do agente. azd empacota o código-fonte como ficheiro ZIP e carrega-o para o Foundry, que resolve dependências e constrói o agente alojado remotamente. O hook postprovision já escreve MEMORY_STORE_NAME em azure.yaml, por isso o agente implantado lê o mesmo armazenamento:

azd deploy

Quando o comando termina, a saída mostra links para o ambiente de testes do agente e para o ponto final do agente. Verifique a memória entre sessões no agente implementado. Guardar 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."

Depois, recorde-o numa sessão nova:

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

O agente destacado responde com o nome e a alergia memorizados.

Passo 1: Criar ou escolher um projeto Foundry

1. Abra o portal Foundry e crie um projeto Foundry, ou selecione um já existente.

2. No projeto, implemente:

   • Um modelo capaz de conversar, como gpt-5.4-mini.
   • Um modelo de incorporação, como text-embedding-3-small.

3. Copie o endpoint do projeto de Descrição geral e os nomes das implementações de Compilações>Implementações.

Passo 2: Descarregar a amostra de memória do Foundry

Clone o repositório de exemplos do Foundry:

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

Cria uma pasta funcional para os scripts de implementação. Nessa pasta, crie um .env ficheiro 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>

Passo 3: Provisionar a memória com Python

Este script pode ser executado novamente em segurança. Primeiro, chama get(...) para verificar se o repositório de memória já existe. Só liga create(...) se a loja não for encontrada.

Crie um ficheiro 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

Passo 4: Implementar o agente alojado com Python

Crie um ficheiro 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 carrega a amostra de memória como uma nova versão do agente hospedado, aponta temporariamente o agente hospedado para essa versão, invoca-a duas vezes como o mesmo utilizador iniciado sessão, e restaura a configuração anterior do endpoint quando esta termina.

Passo 5: Verificar se a memória persiste

A primeira chamada armazena o facto no armazenamento de memória. A segunda chamada pede a informação memorizada num pedido separado. Se o armazenamento de memória estiver configurado corretamente, a resposta deve mencionar o mesmo nome e preferência alimentar que forneceu no primeiro pedido.

Passo 1: Criar ou escolher um projeto Foundry

1. Abra o portal Foundry e crie um projeto Foundry, ou selecione um já existente.

2. No projeto, implemente:

   • Um modelo capaz de conversar, como gpt-4o.
   • Um modelo de incorporação, como text-embedding-3-small.

3. Copie o endpoint do projeto de Descrição geral e os nomes das implementações de Compilações>Implementações.

Passo 2: Descarregar a amostra de memória do Foundry

Clone o repositório de exemplos do Foundry:

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

O exemplo do agente alojado C# encontra-se em samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/src/foundry-memory-rag. Os próximos passos são implementar essa pasta como uma versão de agente alojada. O exemplo lê a sua configuração a partir destas variáveis de ambiente, que o código de implementação define no contentor:

Variável	Description
FOUNDRY_PROJECT_ENDPOINT	Endpoint do projeto Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME	Nome de implementação do modelo de chat.
AZURE_AI_EMBEDDING_DEPLOYMENT_NAME	Incorporar o nome da implementação do modelo.
AZURE_AI_MEMORY_STORE_ID	Nome do armazenamento de memória. O valor padrão é foundry-memory-rag-store.

Passo 3: Provisionar a memória com C #

Cria uma aplicação de consola .NET e instala os pacotes. As APIs do armazenamento de memória estão em versão preliminar, por isso instale o pacote de pré-lançamento Azure.AI.Projects:

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 é seguro para reexecutar. Primeiro liga GetMemoryStore(...) para verificar se a loja já existe, e só liga CreateMemoryStore(...) se a loja não for encontrada. Substitua Program.cs pelo seguinte código e defina endpoint, chatModel, e embeddingModel para 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

Passo 4: Implementar o agente alojado com C#

Crie uma segunda aplicação de consola para o código de implementaçã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

Em Program.cs, substitua o código existente pelo seguinte código. Defina endpoint, chatModel, embeddingModel, e samplePath aos seus valores. samplePath é o caminho completo para a foundry-memory-rag pasta de origem que clonou no Passo 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

Este código carrega a amostra de memória como uma nova versão do agente hospedado, aponta temporariamente o agente hospedado para essa versão, invoca-a duas vezes como o mesmo utilizador com sessão de entrada e restaura a configuração anterior do endpoint quando esta termina.

Passo 5: Verificar se a memória persiste

A primeira chamada armazena o facto no armazenamento de memória. A segunda chamada pede a informação memorizada num pedido separado. Se o armazenamento de memória estiver configurado corretamente, a resposta menciona o mesmo nome e preferência alimentar que forneceu no primeiro pedido. A extração de memória é assíncrona, por isso permite alguns segundos entre as duas chamadas para que o armazenamento indexe a memória.

Limpeza de recursos

Elimine os recursos quando tiver terminado para deixar de incorrer em custos.

Para eliminar o armazenamento de memória, use o AIProjectClient. Execute este script num 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())

Apague o agente e os seus recursos do Azure:

Warning

Se o ambiente atual azd criou o projeto Foundry, azd down apaga permanentemente o grupo de recursos do projeto e tudo o que nele existe. Se selecionou um projeto existente durante a inicialização, azd down deixa o projeto, o seu grupo de recursos, o agente alojado e outros recursos de início rápido no local. Para eliminar recursos que já não precisa do projeto existente, elimine-os separadamente.

azd down

Para eliminar o armazenamento de memória, use o mesmo padrão de script com o nome do seu armazenamento 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 criou um grupo de recursos ou projeto dedicado para este guia de introdução rápida, elimine-o do portal do Azure quando deixar de necessitar da implementação do chat, da implementação de incorporações ou do agente alojado.

O código de implementação já elimina a versão do agente alojado e restaura a configuração anterior do endpoint quando esta termina. Para eliminar o armazenamento de memória, adicione este código a uma aplicação de consola que tenha instalado o Azure.AI.Projects (pré-lançamento) e Azure.Identity os pacotes:

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 criou um grupo de recursos ou projeto dedicado para este guia de introdução rápida, elimine-o do portal do Azure quando deixar de necessitar da implementação do chat, da implementação de incorporações ou do agente alojado.

Troubleshooting

Problema	Solution
O agente implementado não tem memória ou MEMORY_STORE_NAME está vazio	Confirme se o postprovision hook foi executado durante azd provision e se azure.yaml tem MEMORY_STORE_NAME definido. Rerun azd provision para executar o hook novamente.
As escritas de memória falham com um 401 erro e o armazenamento fica vazio	Confirme que a pessoa que ligou já tem acesso de Foundry User no âmbito do projeto Foundry e atribua a função Cognitive Services OpenAI User no mesmo âmbito à sua identidade e à identidade de execução do agente implementado.
azd provision falha com um erro de permissões	Confirme que a sua identidade tem as funções do projeto indicadas em Pré-requisitos.
project.beta.memory_stores.create(...) falha com Authentication to the Azure OpenAI resource failed	Confirme que a sua identidade já dispõe de acesso Foundry User no âmbito do projeto Foundry, bem como da função Cognitive Services OpenAI User nesse âmbito. Verifique também se AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME aponta para uma implementação válida de embeddings.
A implementação em Python tem sucesso, mas a segunda chamada não recorda o facto armazenado	Espere mais alguns segundos antes da segunda chamada para que o armazenamento de memória termine a indexação, depois execute o script novamente.
O agente não se lembra de um facto que partilhaste	Aguarde alguns segundos após armazenar um facto antes de fazer uma consulta, para que o armazenamento termine de indexar a memória.
O agente não consegue ler nem escrever memórias após a implementação	Confirme que o hook postprovision criou o armazenamento no mesmo projeto em que o agente está implementado.

O que aprendeste

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

• Criei um armazenamento de memória Foundry com capacidade de perfil de utilizador.
• Foi implementado um agente alojado que lê e escreve no armazenamento através de FoundryMemoryProvider, utilizando o Azure Developer CLI, o SDK de Python ou o SDK do .NET.
• Verificou-se que o agente recorda factos do utilizador em sessões separadas, seja localmente com a CLI do Azure Developer ou remotamente com o SDK Python ou .NET após a implementação.

Passo seguinte

Avalie o seu agente hospedado

Conteúdo relacionado

• O que são agentes hospedados?
• Anexar memória a um agente
• Início rápido: Implemente o seu primeiro agente alojado
• Gerir agentes alojados