クイックスタート: ホストされたエージェントに永続的なメモリを与える

Important

この記事でプレビューとしてマークされているアイテムは、現在プレビュー段階です。このプレビューはサービスレベルアグリーメント（SLA）なしで提供されており、Microsoft はこれを運用ワークロードでの使用に推奨していません。特定の機能がサポートされていないか、機能が制限されている可能性があります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

このクイックスタートでは、Foundry メモリストアによってサポートされる永続的なセマンティックメモリをホストされるエージェントに提供します。メモリがないと、すべての会話が最初から開始されます。メモリストアを使用すると、エージェントはユーザーに関する安定した事実 (名前や食事の好みなど) を保持し、後のセッションでそれらを呼び出します。

次の 2 つの部分を完了します。

メモリストアをプロビジョニング し、エージェントに接続します。 Azure Developer CLI パスでは、バンドルされたプロビジョニングフックはazd provision後に実行されます。 Python パスでは、SDK を使用してストアを直接作成します。ストアでは、チャットモデルと埋め込みモデルを使用して、ユーザープロファイルメモリを抽出してインデックスを作成します。
を介してストアの読み取りと書き込みを行うFoundryMemoryProviderします。プロバイダーは、各モデル呼び出しの前に関連するメモリを取得し、ターンごとに新しいファクトでストアを更新します。

エージェントコード、メモリプロバイダー、および認証は Foundry メモリサンプルから取得されるため、実装ではなくワークフローに重点を置きます。

GitHub Copilotなどのコーディングエージェントを使用する場合、Microsoft Foundry Skill は、メモリストアのプロビジョニング、ホストされたエージェントへの接続、および再現動作のテストに役立ちます。

Prerequisites

このクイックスタートは、hosted-agent ツールチェーンに基づいています。最初に、Azure サブスクリプション、プロジェクトロール、Python、Azure Developer CLI ()、および azd 拡張機能について説明する、ホストされたエージェントクイックスタートのmicrosoft.foundryを完了します。

このパスAzure Developer CLI を使用してサンプルをスキャフォールディングし、バンドルされたpostprovision フックを使用してメモリストアをプロビジョニングし、エージェントをローカルで実行してデプロイします。

このパスの Python SDK を使用して、AIProjectClient.beta.memory_stores.create(...)でメモリストアを作成し、新しいバージョンとしてホステッドエージェントコードをアップロードし、トラフィックを一時的にルーティングし、同じサインインユーザーが別々の呼び出しで記憶されていることを検証します。

このパスで使用するPython パッケージをインストールします。

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

このパスの .NET SDK を使用して、AIProjectClient.MemoryStores.CreateMemoryStore(...)を使用してメモリストアを作成し、新しいバージョンとしてホステッドエージェントコードをアップロードし、トラフィックを一時的にルーティングし、同じサインインユーザーが個別の呼び出しで記憶されていることを検証します。

.NET 10 SDK 以降も必要です。

また、foundry プロジェクトに埋め込みモデルのデプロイ ( text-embedding-3-smallなど) も必要です。メモリストアでは、メモリのインデックス作成に使用されます。 gpt-4o などのエージェントのチャットモデルには、ホスト型エージェントで既に使用しているデプロイをそのまま使用できます。

ID には、ホステッドエージェントの前提条件に基づき、Foundry プロジェクトスコープでの Foundry ユーザー ロールが必要です。また、同じスコープでの Cognitive Services OpenAI ユーザー ロールも必要です。メモリストアでは、Foundry プロジェクトのデータプレーンアクセスと埋め込みデプロイが使用されます。 OpenAI ロールがないと、メモリの書き込みが 401 エラーで失敗し、ストアは空のままです。

Important

Foundry RBAC ロールの名前が最近変更されました。 Foundry User, Foundry Owner, Foundry Account Owner、および Foundry Project Manager は、以前は、AZURE AI ユーザー、Azure AI 所有者、Azure AI アカウント所有者、および AZURE AI Project Manager という名前でした。名前の変更がロールアウトされている間、以前の名前が表示される場合があります。ロール ID とコアアクセス許可は、名前の変更によって変更されません。

手順 1: ホストされるエージェントを初期化する

Foundry メモリサンプルからホストされるエージェントを初期化します。初期化により、メモリストアプロビジョニングスクリプトやプロビジョニングフックなどのサンプルファイルが、 src/の新しいサービスディレクトリにコピーされます。空のディレクトリでこれらのコマンドを実行します。

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"

プロンプトに従って、サブスクリプション、プロジェクト、およびモデルのデプロイを選択します。 Foundry プロジェクトをお持ちでない場合は、azd ai agent init がその作成手順をご案内します。

手順 2: 1 コマンドプロビジョニングを有効にする

このサンプルには、メモリストアを作成し、postprovisionを実行するたびにエージェントに自動的に接続するazd provision フックが含まれています。 azure.yaml が生成した azd ai agent init ファイルのトップレベルでフックを登録します。

azure.yamlを開き、次の最上位ブロックを追加します。 <agent-name>を、初期化がsrc/で作成したサービスフォルダーに置き換えます。

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

このフックは自己位置決定可能で、べき等です。 azd がどのディレクトリからそれを呼び出しても正しく実行され、再実行しても既存のストアはそのまま維持されます。

注

postprovisionの最上位レベルでazure.yamlを登録します。サービススコープのフックでは、プロビジョニングではなく、パッケージとデプロイのライフサイクルのみがサポートされます。

手順 3: メモリストアとAzure リソースをプロビジョニングする

フックの参照先を、ストアのセマンティックメモリを支える埋め込みモデルのデプロイに設定します。
```
azd env set AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME "text-embedding-3-small"
```
提供：
```
azd provision
```

azd provision は、Foundry プロジェクトとチャットモデルのデプロイを作成または再利用します。次に、 postprovision フック:

ユーザープロファイル機能を有効にしてメモリストアを作成し、サービスで検証します。
エージェントがそのストアの読み取りと書き込みを行う MEMORY_STORE_NAME を設定します。フックは、ローカル実行用に名前を azd 環境に保存し、さらに azure.yaml のサービス環境にも保存することで、azd deploy がそれをコンテナーに渡せるようにします。

バンドルされたフックはcreate memory storeの一部として作成ロジックを自動的に実行するため、CLI パスには別の azd provision コマンドは表示されません。

フックは既定でストア名を agent_framework_memoryします。別の名前を使用する場合は、プロビジョニングを実行する前に設定してください。

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

手順 4: エージェントをローカルで実行する

エージェントを起動します。
```
azd ai agent run
```
このコマンドは、仮想環境を作成し、依存関係をインストールし、 http://localhost:8088にエージェントを提供します。フックは既にMEMORY_STORE_NAME環境にazdを設定しているため、追加の構成は必要ありません。プレビューパッケージは、セットアップ中に pip 警告を生成できます。これらの警告は非ブロッキングです。

別のターミナルで、エージェントに自分に関する事実を伝えます。

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

新しいセッションを開始し、エージェントが会話履歴からではなく、ストアからファクトを呼び戻したことを確認します。
```
azd ai agent invoke --local --new-session "Do you remember my name and any dietary preference I told you earlier?"
```
エージェントは自分の名前と好みで応答し、メモリストアから取得したと証明します。

手順 5: Foundry エージェントサービスにデプロイする

エージェントのソースコードをデプロイします。 azd ソースを ZIP ファイルとしてパッケージ化し、Foundry にアップロードします。このファイルは依存関係を解決し、ホストされているエージェントをリモートでビルドします。 postprovision フックは既にMEMORY_STORE_NAMEをazure.yamlに書き込んでいるため、デプロイされたエージェントは同じストアを読み取ります。

azd deploy

コマンドが完了すると、出力にエージェントプレイグラウンドとエージェントエンドポイントへのリンクが表示されます。デプロイされたエージェント上のセッション間でメモリを確認します。ファクトを格納する:

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

次に、新しいセッションでそれを思い出してください。

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

デプロイされたエージェントは、記憶された名前とアレルギーで回答します。

手順 1: Foundry プロジェクトを作成または選択する

Foundry ポータルを開き、Foundry プロジェクトを作成するか、既存のプロジェクトを選択します。
プロジェクトで、次をデプロイします。
- gpt-5.4-miniなどのチャット対応モデル。
- text-embedding-3-smallなどの埋め込みモデル。
[概要] からプロジェクトエンドポイントをコピーし、Build>Deployments からデプロイ名をコピーします。

手順 2: Foundry メモリサンプルをダウンロードする

Foundry サンプルリポジトリを複製します。

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

配置スクリプトの作業フォルダーを作成します。そのフォルダーに、次の値を含む .env ファイルを作成します。

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>

手順 3: Pythonを使用してメモリストアをプロビジョニングする

このスクリプトは、再実行しても安全です。最初に get(...) を呼び出して、メモリストアが既に存在するかどうかを確認します。ストアが見つからない場合にのみ create(...) を呼び出します。

provision_memory_store.pyと同じ作業フォルダーに .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())

スクリプトを実行します。

python provision_memory_store.py

手順 4: Pythonを使用してホステッドエージェントをデプロイする

deploy_memory_agent.pyと同じ作業フォルダーに .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,
            )

スクリプトを実行します。

python deploy_memory_agent.py

このスクリプトは、メモリサンプルを新しい hosted-agent バージョンとしてアップロードし、そのバージョンでホストされているエージェントを一時的にポイントし、同じサインインユーザーとして 2 回呼び出し、完了すると以前のエンドポイント構成を復元します。

手順 5: メモリが保持されることを確認する

最初の呼び出しでは、メモリストアにファクトが格納されます。 2 番目の呼び出しでは、別の要求で記憶された事実を要求します。メモリストアが正しく構成されている場合、応答には、最初の要求で指定したのと同じ名前と食事の設定が記述されている必要があります。

手順 1: Foundry プロジェクトを作成または選択する

Foundry ポータルを開き、Foundry プロジェクトを作成するか、既存のプロジェクトを選択します。
プロジェクトで、次をデプロイします。
- gpt-4oなどのチャット対応モデル。
- text-embedding-3-smallなどの埋め込みモデル。
[概要] からプロジェクトエンドポイントをコピーし、Build>Deployments からデプロイ名をコピーします。

手順 2: Foundry メモリサンプルをダウンロードする

Foundry サンプルリポジトリを複製します。

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

C# hosted-agent サンプルは、 samples/csharp/hosted-agents/agent-framework/foundry-memory-rag/src/foundry-memory-rag下にあります。次の手順では、そのフォルダーをホストされるエージェントのバージョンとしてデプロイします。このサンプルでは、コンテナーにデプロイコードが設定する次の環境変数から構成を読み取ります。

Variable	Description
`FOUNDRY_PROJECT_ENDPOINT`	Foundry プロジェクトエンドポイント。
`AZURE_AI_MODEL_DEPLOYMENT_NAME`	チャットモデルのデプロイメント名。
`AZURE_AI_EMBEDDING_DEPLOYMENT_NAME`	モデルデプロイ名の埋め込み。
`AZURE_AI_MEMORY_STORE_ID`	メモリストア名。既定値は `foundry-memory-rag-store` です。

手順 3: C を使用してメモリストアをプロビジョニングする#

.NETコンソールアプリを作成し、パッケージをインストールします。メモリストア API はプレビュー段階であるため、プレリリース 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

このコードは、再実行しても安全です。最初に GetMemoryStore(...) を呼び出してストアが既に存在するかどうかを確認し、ストアが見つからない場合にのみ CreateMemoryStore(...) 呼び出します。 Program.csを次のコードに置き換え、endpoint、chatModel、およびembeddingModelをプロジェクトの値に設定します。

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

次のようにアプリを実行します。

dotnet run

手順 4: C を使用してホストされるエージェントをデプロイする#

デプロイコード用の 2 つ目のコンソールアプリを作成します。

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

Program.csで、既存のコードを次のコードに置き換えます。 endpoint、chatModel、embeddingModel、samplePathを値に設定します。 samplePath は、手順 2 で複製した foundry-memory-rag ソースフォルダーへの完全なパスです。

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

次のようにアプリを実行します。

dotnet run

このコードは、新しい hosted-agent バージョンとしてメモリサンプルをアップロードし、そのバージョンでホストされているエージェントを一時的にポイントし、同じサインインユーザーとして 2 回呼び出し、完了すると以前のエンドポイント構成を復元します。

手順 5: メモリが保持されることを確認する

最初の呼び出しでは、メモリストアにファクトが格納されます。 2 番目の呼び出しでは、別の要求で記憶された事実を要求します。メモリストアが正しく構成されている場合、応答には、最初の要求で指定した名前と食事の設定が示されます。メモリ抽出は非同期であるため、ストアがメモリのインデックスを作成するために、2 つの呼び出しの間に数秒を許可します。

リソースをクリーンアップする

完了したらリソースを削除して、料金の発生を停止します。

メモリストアを削除するには、 AIProjectClientを使用します。 azure-ai-projectsパッケージとazure-identity パッケージがインストールされているPython環境でこのスクリプトを実行します (たとえば、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())

エージェントとそのAzureリソースを削除します。

Warning

現在の azd 環境で Foundry プロジェクトが作成された場合、 azd down はプロジェクトのリソースグループとその中のすべてのリソースグループを完全に削除します。初期化中に既存のプロジェクトを選択した場合、 azd down はプロジェクト、そのリソースグループ、ホストされているエージェント、およびその他のクイックスタートリソースはそのまま残ります。既存のプロジェクトから不要になったリソースを削除するには、それらを個別に削除します。

azd down

メモリストアを削除するには、メモリストア名と同じスクリプトパターンを使用します。

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

このクイックスタート用に専用のリソースグループまたはプロジェクトを作成した場合は、チャットのデプロイ、埋め込みデプロイ、またはホストされたエージェントが不要になった後、Azure ポータルから削除します。

デプロイコードでは、ホストされているエージェントのバージョンが既に削除され、完了すると以前のエンドポイント構成が復元されます。メモリストアを削除するには、 Azure.AI.Projects (プレリリース) パッケージと Azure.Identity パッケージがインストールされているコンソールアプリに次のコードを追加します。

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

トラブルシューティング

Issue	ソリューション
デプロイされたエージェントにメモリがない、または `MEMORY_STORE_NAME` が空である	`postprovision`中に`azd provision`フックが実行されたこと、および`azure.yaml`が`MEMORY_STORE_NAME`に設定されていることを確認します。 `azd provision`再実行してフックを再実行します。
メモリの書き込みが `401` エラーで失敗し、ストアが空のままである	呼び出し元が Foundry プロジェクトスコープに対する Foundry ユーザーアクセス権を既に持っているのを確認し、同じスコープの Cognitive Services OpenAI ユーザーロールを ID とデプロイされたエージェントのランタイム ID に付与します。
`azd provision` アクセス許可エラーで失敗する	ご自身の ID に、前提条件に記載されているプロジェクトロールが割り当てられていることを確認してください。
`project.beta.memory_stores.create(...)` は `Authentication to the Azure OpenAI resource failed` で失敗する	ご自身の ID に、Foundry プロジェクトスコープへのFoundry ユーザーアクセス権が既に付与されており、また、そのスコープでCognitive Services OpenAI ユーザーロールが付与されていることを確認してください。また、 `AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME` が有効な埋め込みデプロイを指していることを確認します。
Pythonデプロイは成功しますが、2 回目の呼び出しでは格納されたファクトが思い出されません	2 回目の呼び出しの前にさらに数秒待ってから、メモリストアのインデックス作成が完了したら、スクリプトをもう一度実行します。
エージェントは、共有した事実を思い出しません	クエリを実行する前にファクトを格納してから数秒待ってから、ストアでメモリのインデックス作成が完了します。
デプロイ後にエージェントがメモリの読み取りまたは書き込みを行えない	エージェントがデプロイされているのと同じプロジェクトに対して、 `postprovision` フックによってストアが作成されたことを確認します。

学習した内容

このクイックスタートでは、次の操作を行います。

ユーザープロファイル機能を使用して Foundry メモリストアを作成しました。
Azure Developer CLI、Python SDK、または .NET SDK を使用して、FoundryMemoryProviderを介してストアの読み取りと書き込みを行うホスト型エージェントをデプロイしました。
エージェントが、Azure Developer CLI を使用してローカルに、またはデプロイ後に Python または .NET SDK を使用してリモートで、個別のセッション間でユーザーファクトを呼び戻すことが確認されました。

次のステップ

ホストされているエージェントを評価する

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-09-11

クイック スタート: ホストされたエージェントに永続的なメモリを与える

Prerequisites

手順 1: ホストされるエージェントを初期化する

手順 2: 1 コマンド プロビジョニングを有効にする

手順 3: メモリ ストアとAzure リソースをプロビジョニングする

手順 4: エージェントをローカルで実行する

手順 5: Foundry エージェント サービスにデプロイする

手順 1: Foundry プロジェクトを作成または選択する

手順 2: Foundry メモリ サンプルをダウンロードする

手順 3: Pythonを使用してメモリ ストアをプロビジョニングする

手順 4: Pythonを使用してホステッド エージェントをデプロイする

手順 5: メモリが保持されることを確認する

手順 1: Foundry プロジェクトを作成または選択する

手順 2: Foundry メモリ サンプルをダウンロードする

手順 3: C を使用してメモリ ストアをプロビジョニングする#

手順 4: C を使用してホストされるエージェントをデプロイする#

手順 5: メモリが保持されることを確認する

リソースをクリーンアップする

トラブルシューティング

学習した内容

次のステップ

関連するコンテンツ

フィードバック

その他のリソース

クイックスタート: ホストされたエージェントに永続的なメモリを与える

手順 2: 1 コマンドプロビジョニングを有効にする

手順 3: メモリストアとAzure リソースをプロビジョニングする

手順 5: Foundry エージェントサービスにデプロイする

手順 2: Foundry メモリサンプルをダウンロードする

手順 3: Pythonを使用してメモリストアをプロビジョニングする

手順 4: Pythonを使用してホステッドエージェントをデプロイする

手順 2: Foundry メモリサンプルをダウンロードする

手順 3: C を使用してメモリストアをプロビジョニングする#