MongoDBと Clade Agent SDK の統合

Overview

claude-agent-sdk-mongodb-session-storeパッケージは、アプリケーション内で句読点エージェント SDK と対話するためのMongoDBベースのセッション ストア アダプターを提供します。セッションは 、対話とエージェントが実行したアクションのレコードであり、個々のエントリとして保存されます。デフォルトでは 、Clade Agent SDK は、エージェントを呼び出すホストにトランザクションを保存します 。 MongoDBアダプターはこれらのエントリをMongoDBに保存するため、トランザクションはホストとMongoDBの両方に保持されます。その後、別のホストからセッションを再開できます。

アダプターを使用して、次のタスクを実行できます。

• 別のプロセスまたはホストからセッションを再開

• セッション履歴をアプリケーションデータと同じ配置で保持

• MongoDBツールによるクエリとセッション履歴の監査する

インストールとセットアップ

アダプターを使用するには、次のコンポーネントが使用可能である必要があります。

• Python 3.10 以降

• MongoDB 7.0 以降を実行するMongoDBデプロイ

• アナライザAPIキー

App Services APIキーの取得と設定の方法については、「 句エージェント SDK クイックスタート 」を参照してください。セッション ストアは、このキーを使用したり参照したりしません。

ターミナルで次のコマンドを実行して、アダプターとその依存関係をインストールします。

uv add claude-agent-sdk-mongodb-session-store

このコマンドは、アダプターとその claude-agent-sdk および pymongo 依存関係をインストールします。

次の例に示すように、環境変数に接続文字列を設定します。アダプターは作成したクライアントを使用するため、認証情報はクライアント構成に残ります。

export MONGODB_URI="<connection-string>"

セッションの永続化

デフォルトでは 、Clude Agent SDK は各セッションの記録をエージェントが実行されるホスト上にのみ保持します。次の例では、 MongoDBセッション ストアを作成し、そのインデックスを初期化してクエリを実行します。アダプターは、エージェントの実行時にセッション トランザクションをMongoDBに永続化します。この例では、結果と SDK が割り当てたセッションIDが出力されます。

import asyncio
import os
from pymongo import AsyncMongoClient
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from claude_agent_sdk_mongodb_session_store import MongoDBSessionStore
async def main() -> None:
    client = AsyncMongoClient(
        os.environ["MONGODB_URI"],
        readPreference="primary",
        w="majority",
        serverSelectionTimeoutMS=10_000,
        timeoutMS=20_000,
    )
    store = MongoDBSessionStore(client=client, db_name="claude")
    # Set up the database indexes that optimize the store's performance.
    # This operation is idempotent, so you can run it on every startup.
    await store.create_schema()
    async for message in query(
        prompt="Review this codebase and explain what it does.",
        options=ClaudeAgentOptions(session_store=store),
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)
            # The SDK assigns the session ID. Save it so that you can
            # resume the session later.
            print(f"Session ID: {message.session_id}")
    await client.close()
asyncio.run(main())

セッションを再開する

セッションを再開するには、ClaudeAgentOptionsオブジェクトを作成し、再開するセッションのストアオブジェクトとセッションIDを渡します。 SDK は、最初の実行の結果メッセージの session_idフィールドにセッションIDを返します。

非同期関数内で次のスニペットを使用してセッションを再開できます。 <session-id> をセッションIDに置き換えます。

# Pass the same store and the session ID from the earlier run.
async for message in query(
    prompt="Suggest how to improve this codebase.",
    options=ClaudeAgentOptions(
        session_store=store,
        resume="<session-id>",
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

保持と運用上の考慮事項

アダプターは各トランザクションエントリをドキュメントとして保存し、単独ではセッションを削除しません。アクティブでなくなったセッションを削除するには、cronジョブや Atlasの予定されたトリガーなどのスケジュールで delete_inactive() を呼び出します。

from datetime import timedelta
# Delete every session with no new entries in the last 30 days.
deleted = await store.delete_inactive(timedelta(days=30))
print(f"Deleted {deleted} inactive sessions.")

time-to-Liveインデックスまたはエントリ時に delete_many() フィルターを使用して、個々のエントリを削除しないでください。まだ使用中のセッションの最も古いエントリを削除すると、アプリケーションが再開できないトランザクションが残ります。

追加リソース

MongoDBセッション ストア アダプターと 句エージェント SDK の詳細については、次のリソースを参照してください。

• Clade Agent SDK セッションストレージのドキュメント

• MongoDBセッション ストア アダプターリポジトリ

リポジトリにアクセスして、アダプターの最新状態を維持し、リポジトリを起動することを検討してください。