Schnellstart: Bereitstellen des beständigen Speichers eines gehosteten Agents

Sie verwenden die Azure Developer CLI in diesem Workflow, um das Beispielgerüst zu erstellen, den Speicher über einen gebündelten postprovision-Hook einzurichten, den Agent lokal auszuführen und ihn bereitzustellen.

Sie verwenden das Python SDK in diesem Pfad, um den Speicher mit AIProjectClient.beta.memory_stores.create(...)zu erstellen, den Code des gehosteten Agents als neue Version hochzuladen, den Datenverkehr vorübergehend weiterzuleiten und zu überprüfen, ob derselbe angemeldete Benutzer über separate Aufrufe hinweg gespeichert wird.

Installieren Sie die in diesem Pfad verwendeten Python Pakete:

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

Schritt 1: Initialisieren des gehosteten Agents

Initialisieren Sie einen gehosteten Agenten aus dem Foundry-Speicherbeispiel. Die Initialisierung kopiert die Beispieldateien, einschließlich des Bereitstellungsskripts für den In-Memory-Speicher und des Bereitstellungs-Hooks, in ein neues Dienstverzeichnis unter src/. Führen Sie diese Befehle in einem leeren Verzeichnis aus.

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

Folgen Sie den Anweisungen, um Ihr Abonnement, Ihr Projekt und eine Modellbereitstellung auszuwählen. Wenn Sie noch kein Foundry-Projekt haben, führt Sie azd ai agent init durch das Erstellen eines solchen Projekts.

Schritt 2: Bereitstellung mit einem einzigen Befehl aktivieren

Das Beispiel enthält einen postprovision-Hook, der den Memory Store erstellt und ihn jedes Mal, wenn Sie azd provision ausführen, automatisch mit dem Agenten verbindet. Registrieren Sie den Hook auf oberster Ebene der Datei azure.yaml, die azd ai agent init generiert hat.

Öffnen Sie azure.yaml und fügen Sie den folgenden Block der obersten Ebene hinzu. Ersetzen Sie <agent-name> durch den Dienstordner, den die Initialisierung unter src/ erstellt hat:

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

Der Hook lokalisiert sich selbst und ist idempotent. Er wird unabhängig davon, aus welchem Verzeichnis azd ihn aufruft, ordnungsgemäß ausgeführt, und bei erneuten Ausführungen bleibt ein vorhandener Speicher unverändert.

Schritt 3: Bereitstellen des Speicherspeichers und Azure Ressourcen

1. Verweisen Sie mit dem Hook auf die Einbettungsmodellbereitstellung, die den semantischen Speicher des Speichers unterstützt:

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

2. Bereitstellung:

   azd provision
   

azd provision erstellt Ihr Foundry-Projekt und Ihre Chatmodellbereitstellung oder verwendet diese wieder. Dann der postprovision Haken:

• Erstellt den Speicher mit aktivierter Benutzerprofilfunktion und überprüft ihn im Dienst.
• Legt MEMORY_STORE_NAME fest, dass der Agent den Speicher liest und schreibt. Der Hook speichert den Namen für lokale Ausführungen in Ihrer azd-Umgebung und in der Serviceumgebung in azure.yaml, sodass azd deploy ihn an den Container weitergibt.

Der CLI-Pfad zeigt keinen separaten create memory store-Befehl an, da der mitgelieferte Hook diese Logik zur Erstellung für Sie im Rahmen von azd provision ausführt.

Der Hook verwendet standardmäßig den Store-Namen agent_framework_memory. Wenn Sie einen anderen Namen verwenden möchten, legen Sie ihn vor der Bereitstellung fest:

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

Schritt 4: Agenten lokal ausführen

1. Starten Sie den Agent:

   azd ai agent run
   

   Dieser Befehl erstellt eine virtuelle Umgebung, installiert Abhängigkeiten und stellt den Agenten unter http://localhost:8088 bereit. Der Hook setzt bereits MEMORY_STORE_NAME in deiner azd-Umgebung, sodass du keine zusätzliche Konfiguration benötigst. Vorschaupakete können während des Setups Pip-Warnungen erzeugen. Diese Warnungen sind nicht blockierend.

2. Teilen Sie dem Agenten in einem separaten Terminal eine Tatsache über sich selbst mit:

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

3. Starten Sie eine neue Sitzung, und vergewissern Sie sich, dass der Agent die Tatsache aus dem Speicher und nicht aus dem Unterhaltungsverlauf abruft:

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

   Der Agent antwortt mit Ihrem Namen und Ihrer Vorliebe, was beweist, dass er sie aus dem Speicher abgerufen hat.

Schritt 5: Bereitstellen für den Foundry Agent Service

Stellen Sie den Agent-Quellcode bereit. azd packt die Quelle als ZIP-Datei und lädt sie in Foundry hoch, wodurch Abhängigkeiten aufgelöst und der gehostete Agent remote erstellt wird. Der postprovision Hook schreibt MEMORY_STORE_NAME bereits in azure.yaml, sodass der bereitgestellte Agent denselben Speicher liest:

azd deploy

Wenn der Befehl abgeschlossen ist, zeigt die Ausgabe Links zum Agent-Playground und zum Agent-Endpunkt an. Überprüfen Sie den Arbeitsspeicher sitzungsübergreifend auf dem bereitgestellten Agenten. Speichern Sie eine Tatsache:

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

Rufen Sie es dann in einer neuen Sitzung zurück:

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

Der bereitgestellte Agent antwortet mit dem gespeicherten Namen und der Allergie.

Schritt 1: Erstellen oder Auswählen eines Foundry-Projekts

1. Öffnen Sie das Foundry-Portal , und erstellen Sie ein Foundry-Projekt, oder wählen Sie ein vorhandenes Projekt aus.

2. Stellen Sie im Projekt Folgendes bereit:

   • Ein chatfähiges Modell wie gpt-5.4-mini.
   • Ein Einbettungsmodell wie text-embedding-3-small.

3. Kopieren Sie den Projektendpunkt aus Übersicht und die Namen der Bereitstellungen aus Build>Bereitstellungen.

Schritt 2: Herunterladen des Foundry-Speicherbeispiels

Klonen Sie das Repository für Foundry-Beispiele:

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

Erstellen Sie einen Arbeitsordner für die Bereitstellungsskripts. Erstellen Sie in diesem Ordner eine .env Datei mit den folgenden Werten:

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>

Schritt 3: Bereitstellen des Speichers mit Python

Dieses Skript kann sicher erneut ausgeführt werden. Zunächst wird get(...) aufgerufen, um zu prüfen, ob der Speicher bereits existiert. create(...) wird nur aufgerufen, wenn der Store nicht gefunden wird.

Erstellen Sie eine Datei provision_memory_store.py namens im selben Arbeitsordner wie .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())

Führen Sie das Skript aus:

python provision_memory_store.py

Schritt 4: Bereitstellen des gehosteten Agents mit Python

Erstellen Sie eine Datei deploy_memory_agent.py namens im selben Arbeitsordner wie .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,
            )

Führen Sie das Skript aus:

python deploy_memory_agent.py

Dieses Skript lädt das Speicherbeispiel als neue Version des gehosteten Agents hoch, verweist den gehosteten Agent vorübergehend auf diese Version, ruft es zweimal als denselben angemeldeten Benutzer auf und stellt die vorherige Endpunktkonfiguration wieder her, wenn sie abgeschlossen ist.

Schritt 5: Überprüfen, ob der Arbeitsspeicher beibehalten wird

Der erste Anruf speichert die Tatsache im Speicher. Der zweite Anruf fordert die erinnerte Tatsache in einer separaten Anforderung an. Wenn der Speicher richtig konfiguriert ist, sollte die Antwort denselben Namen und die Ernährungspräferenz erwähnen, die Sie in der ersten Anforderung angegeben haben.

Um den Speicher zu löschen, verwenden Sie die AIProjectClient. Führen Sie dieses Skript in einer Python-Umgebung aus, in der die Pakete azure-ai-projects und azure-identity installiert sind (führen Sie z. B. pip install "azure-ai-projects>=2.3.0" azure-identity aus):

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

Löschen Sie den Agent und seine Azure Ressourcen:

azd down

Verwenden Sie zum Löschen des Memory Stores dasselbe Skriptmuster unter Verwendung des Namens Ihres Memory Stores:

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

Wenn Sie für diese Schnellstartanleitung eine dedizierte Ressourcengruppe oder ein dediziertes Projekt erstellt haben, löschen Sie sie aus dem Azure-Portal, nachdem Sie die Chatbereitstellung, die Einbettungsbereitstellung oder den gehosteten Agent nicht mehr benötigen.