ストレージは、会話履歴が存在する場所、読み込まれる履歴の量、およびセッションを再開できる信頼性を制御します。
組み込みのストレージ モード
Agent Framework では、次の 2 つの通常のストレージ モードがサポートされています。
| モード | 格納される内容 | 一般的な使用 |
|---|---|---|
| ローカル セッションの状態 |
AgentSession.stateでの完全なチャット履歴 (InMemoryHistoryProvider など) |
サーバー側の会話の永続化を必要としないサービス |
| サービスで管理されるストレージ | サービスの会話状態。 AgentSession.service_session_id がポイントする |
ネイティブの永続的な会話をサポートするサービス |
メモリ内チャット履歴ストレージ
プロバイダーがサーバー側のチャット履歴を必要としない場合、Agent Framework はセッション内の履歴をローカルに保持し、実行ごとに関連するメッセージを送信します。
AIAgent agent = new OpenAIClient("<your_api_key>")
.GetChatClient(modelName)
.AsAIAgent(instructions: "You are a helpful assistant.", name: "Assistant");
AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
// Works when in-memory storage is active.
IList<ChatMessage>? messages = session.GetService<IList<ChatMessage>>();
from agent_framework import InMemoryHistoryProvider
from agent_framework.openai import OpenAIChatClient
agent = OpenAIChatClient().as_agent(
name="StorageAgent",
instructions="You are a helpful assistant.",
context_providers=[InMemoryHistoryProvider("memory", load_messages=True)],
)
session = agent.create_session()
await agent.run("Remember that I like Italian food.", session=session)
メモリ内履歴サイズの縮小
履歴がモデルの制限を超えるほど大きくなった場合は、縮小ツールを適用してください。
AIAgent agent = new OpenAIClient("<your_api_key>")
.GetChatClient(modelName)
.AsAIAgent(new ChatClientAgentOptions
{
Name = "Assistant",
ChatOptions = new() { Instructions = "You are a helpful assistant." },
ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(
new InMemoryChatHistoryProvider(
new MessageCountingChatReducer(20),
ctx.SerializedState,
ctx.JsonSerializerOptions,
InMemoryChatHistoryProvider.ChatReducerTriggerEvent.AfterMessageAdded))
});
注
Reducer の構成は、メモリ内履歴プロバイダーに適用されます。 サービス管理履歴の場合、削減動作はプロバイダー/サービス固有です。
サービスで管理されるストレージ
サービスが会話履歴を管理すると、セッションにはリモート会話識別子が格納されます。
AIAgent agent = new OpenAIClient("<your_api_key>")
.GetOpenAIResponseClient(modelName)
.AsAIAgent(instructions: "You are a helpful assistant.", name: "Assistant");
AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
# Rehydrate when the service already has the conversation state.
session = agent.get_session(service_session_id="<service-conversation-id>")
response = await agent.run("Continue this conversation.", session=session)
サード パーティのストレージ パターン
データベース/Redis/BLOB ベースの履歴の場合は、カスタム履歴プロバイダーを実装します。
主要なガイダンス:
- セッション スコープ キーの下にメッセージを格納します。
- 返された履歴をモデル コンテキストの制限内に保持します。
- プロバイダー固有の識別子を
session.stateに保持します。 - Python では、
load_messages=Trueを使用する履歴プロバイダーは 1 つだけです。
from agent_framework.openai import OpenAIChatClient
history = DatabaseHistoryProvider(db_client)
agent = OpenAIChatClient().as_agent(
name="StorageAgent",
instructions="You are a helpful assistant.",
context_providers=[history],
)
session = agent.create_session()
await agent.run("Store this conversation.", session=session)
再起動後のセッションの永続化
メッセージ テキストだけでなく、完全な AgentSessionを保持します。
JsonElement serialized = agent.SerializeSession(session);
// Store serialized payload in durable storage.
AgentSession resumed = await agent.DeserializeSessionAsync(serialized);
serialized = session.to_dict()
# Store serialized payload in durable storage.
resumed = AgentSession.from_dict(serialized)
Important
AgentSessionを不透明な状態オブジェクトとして扱い、それを作成したのと同じエージェント/プロバイダー構成で復元します。
ヒント
追加の監査/評価履歴プロバイダー (load_messages=False、 store_context_messages=True) を使用して、プライマリ履歴の読み込みに影響を与えずに、エンリッチされたコンテキストと入力/出力をキャプチャします。