Microsoft Agent Framework、Azure Cosmos DB で永続メモリ

エージェントは、現在の会話を超えて重要な情報を記憶できる場合に、より有用になります。本日、Azure Cosmos DB をバックエンドに持つ耐久性のあるクロスセッションメモリを Microsoft Agent Framework のエージェントに提供するための新しいプレビュー統合を発表します。

この新 Python パッケージ「agent-framework-azure-cosmos-memory」には、CosmosMemoryContextProvider が含まれています。これをエージェントに一度接続するだけで、会話のやり取りを自動的に保存し、永続的なメモリを抽出し、後の会話で関連する事実や要約、ユーザープロファイルを呼び出すことが可能になります。

この統合は、Azure Cosmos DB チームが「Native Agent Memory for Microsoft Agent Framework, Powered by Azure Cosmos DB」で紹介しました。ここでは、Agent Framework の開発者にとってこれが何を意味するか、またどのようにしてフレームワークのコンテキストプロバイダーモデルに自然に適合するかに焦点を当てます。

プレビュー: agent-framework-azure-cosmos-memory は現在、Python 専用で利用可能です。パッケージおよびその API は、一般公開前に変更される可能性があります。

エージェントライフサイクルに参加するメモリ

Agent Framework では、ContextProvider がすべてのエージェント呼び出しの周囲で動作します。これはモデルの実行前に情報を追加し、実行完了後に反応することができます。この仕組みにより、コンテキストプロバイダーはメモリの拡張ポイントとして自然に機能します。エージェントループは Agent Framework 内に留まりつつ、ストレージ、検索、メモリ処理はプロバイダーが担当するのです。

CosmosMemoryContextProvider は、このライフサイクルの両側面を活用しています：

実行前には、入力されたメッセージに関連する記憶を検索し、モデルのコンテキストに追加します。

実行後には、新しい会話履歴を保存します。その後、Azure Cosmos DB Agent Memory Toolkit が背景で事実の抽出、要約の生成、ユーザープロファイルの更新を行います。

エージェントがメモリーツールの呼び出しを判断する必要はなく、アプリケーション側で別個の検索パイプラインを調整する必要もありません。メモリー機能は、すべての実行プロセスに組み込まれています。

仕組みの概要

Agent Framework がエージェントループを管理し、プロバイダーを呼び出します。このプロバイダーが、Azure Cosmos DB Agent Memory Toolkit のライフサイクルに適応させます。同ツールがストレージモデルと処理パイプラインを担います。Azure Cosmos DB for NoSQL は会話履歴と派生した記憶データを保存し、同一データベース内でのベクトル検索、全文検索、ハイブリッド検索をサポートします。

アーキテクチャ図は Azure Cosmos DB チームの提供によるものです。メモリーパイプラインの詳細については、元の発表記事をご覧ください。

Python エージェントに永続的な記憶を追加する

Agent Framework Foundry プロバイダーと併せて、プレビュー版の統合をインストールしてください：

Azure Cosmos DB を使用した Microsoft Agent Framework のネイティブメモリ機能を利用するには、以下のコマンドで必要なパッケージをインストールしてください。

pip install --pre agent-framework-azure-cosmos-memory agent-framework-foundry

その後、Azure リソースの設定として COSMOS_ENDPOINT、FOUNDRY_ENDPOINT、EMBEDDING_MODEL、CHAT_MODEL の各環境変数を設定します。これでプロバイダーを作成し、エージェントの context_providers コレクションに追加できます。

これにより、一意のユーザー ID（user_id）を安定して使用することで、新しいセッションでも以前のセッションで学習した記憶を参照できるようになります。

import asyncio

import os

from agent_framework import Agent

from agent_framework.foundry import FoundryChatClient

from agent_framework_azure_cosmos_memory import CosmosMemoryContextProvider

from azure.identity.aio import DefaultAzureCredential

async def main() -> None:

credential = DefaultAzureCredential()

memory = CosmosMemoryContextProvider(

cosmos_endpoint=os.environ["COSMOS_ENDPOINT"],

cosmos_database=os.getenv("COSMOS_DATABASE", "ai_memory"),

foundry_endpoint=os.environ["FOUNDRY_ENDPOINT"],

embedding_model=os.environ["EMBEDDING_MODEL"],

chat_model=os.environ["CHAT_MODEL"],

credential=credential,

)

agent = Agent(

client=FoundryChatClient(

project_endpoint=os.environ["FOUNDRY_ENDPOINT"],

model=os.environ["CHAT_MODEL"],

credential=credential,

),

instructions="You are a helpful assistant with long-term memory.",

context_providers=[memory],

)

async with credential, memory:

first_session = agent.create_session()

first_session.state.setdefault(memory.source_id, {})["user_id"] = "alice"

await agent.run(

"I love hiking and I'm allergic to peanuts.",

session=first_session,

)

# Wait for background extraction so this immediate demo is deterministic.

await memory.flush()

同じユーザーの新しいセッションでも、最初のセッションからの記憶を参照可能

second_session = agent.create_session()
second_session.state.setdefault(memory.source_id, {})["user_id"] = "alice"
reply = await agent.run(
    "What should I pack for a trail lunch?",
    session=second_session,
)
print(reply.text)

asyncio.run(main())

プロバイダーはシャットダウン前に、保留中の非同期バックグラウンド抽出を完了させます。実際のアプリケーションでは、リクエストから任意の値を受け取るのではなく、認証済みのユーザーから user_id を取得してください。安定したユーザー ID を指定しない場合、プロバイダーはセッション間の知識を引き継ぐ代わりに、セッションスコープ内のメモリにフォールバックします。

この例で使われている Foundry エンドポイントは、ツールキットの抽出・埋め込みモデルとチャットエージェントの両方を支えています。DefaultAzureCredential を利用すれば、ローカル開発では az login で、本番環境ではマネージド ID で認証できるため、コードにキーを直接記述する必要はありません。

エージェントが得られるメリット

この統合により、Agent Framework の開発者は、以下の機能を単一のコンポーザブルなプロバイダーとして利用できます：

• 安定したユーザー ID にスコープされた、セッション間での記憶参照機能
• ファクト（事実）、手続き的・事象的メモリ、スレッドの要約、ユーザープロフィールなどを含む派生メモリ
• Azure Cosmos DB に内蔵されたベクトル検索と全文検索を組み合わせたハイブリッド検索
• エージェントの応答パスをブロックしない非同期バックグラウンド抽出機能

デフォルトのメモリ仕様では不十分な場合に、カスタムの Prompty テンプレートを使用してドメイン固有の抽出を行うことができます。

これにより責任範囲が明確に保たれます。Agent Framework はエージェントの実行とコンテキストの構成を担当し、Azure Cosmos DB が長期メモリの保存・処理・取得を担います。

始め方

Azure Cosmos DB チームによる完全な発表記事やウォークスルーをご覧ください。

basic_usage.py または interactive_chat.py のサンプルを実行してください。

agent-framework-azure-cosmos-memory パッケージと Agent Memory Toolkit を探索してみましょう。

Agent Framework におけるコンテキストプロバイダーの詳細や、利用可能なコンテキストプロバイダーの統合一覧もご確認ください。

CosmosMemoryContextProvider を使用すると、永続的なメモリが Agent Framework エージェントの構成要素の一つとして追加されます。プロバイダーを接続し、ユーザーごとにスコープを設定するだけで、フレームワークのライフサイクルが自動的に残りの処理を行います。

「Native memory for Microsoft Agent Framework with Azure Cosmos DB」という記事は、Microsoft Agent Framework で最初に公開されました。