Merge branch 'main' into fix/conversation-assistant-replay-metadata

Author: seratch

docs/src/content/docs/ja/guides/sandbox-agents/clients.mdx

@@ -0,0 +1,115 @@
+---
+title: エージェントメモリ
+description: Preserve and reuse lessons from previous sandbox-agent runs.
+---
+
+import { Aside, Code } from '@astrojs/starlight/components';
+import conversationIdentityExample from '../../../../../../../examples/docs/sandbox-agents/conversation-identity.ts?raw';
+import enableMemoryExample from '../../../../../../../examples/docs/sandbox-agents/enable-memory.ts?raw';
+import generateMemoryExample from '../../../../../../../examples/docs/sandbox-agents/generate-memory.ts?raw';
+import memoryLayoutsExample from '../../../../../../../examples/docs/sandbox-agents/memory-layouts.ts?raw';
+import readOnlyMemoryExample from '../../../../../../../examples/docs/sandbox-agents/read-only-memory.ts?raw';
+
+メモリを使うと、以後の sandbox-agent の実行が過去の実行から学習できるようになります。これは、メッセージ履歴を保存する SDK の会話型 [セッション](/openai-agents-js/ja/guides/sessions) メモリとは別のものです。メモリは、過去の実行で得た学びを sandbox ワークスペース内のファイルに要約して保存します。
+
+<Aside type="caution" title="ベータ機能">
+  Sandbox agents はベータ版です。 API
+  の詳細、デフォルト値、サポートされる機能は、
+  一般提供前に変更される可能性があり、より高度な機能も今後追加される予定です。
+</Aside>
+
+メモリは、今後の実行における 3 種類のコストを削減できます。
+
+1. エージェントのコスト: エージェントがワークフローの完了に長い時間を要した場合、次回の実行では探索量を減らせるはずです。これにより、トークン使用量と完了までの時間を削減できます。
+2. ユーザーのコスト: ユーザーがエージェントを修正したり、好みを示したりした場合、今後の実行ではそのフィードバックを記憶できます。これにより、人間の介入を減らせます。
+3. コンテキストのコスト: エージェントが以前にタスクを完了していて、ユーザーがそのタスクを引き継ぎたい場合、ユーザーは以前のスレッドを探したり、すべてのコンテキストを再入力したりする必要がありません。これにより、タスクの説明を短くできます。
+
+## メモリの有効化
+
+sandbox-agent に機能として `memory()` を追加します。
+
+<Code lang="typescript" code={enableMemoryExample} title="メモリの有効化" />
+
+読み取りを有効にする場合、`memory()` には `shell()` が必要です。これにより、注入された要約だけでは不十分なときに、エージェントがメモリファイルを読み取り、検索できます。ライブメモリ更新がデフォルトで有効な場合は、`filesystem()` も必要です。これにより、エージェントが古いメモリを見つけた場合や、ユーザーからメモリの更新を求められた場合に、`memories/MEMORY.md` を更新できます。
+
+デフォルトでは、メモリアーティファクトは sandbox ワークスペース内の `memories/` に保存されます。後の実行で再利用するには、同じライブ sandbox セッションを維持するか、永続化されたセッション状態またはスナップショットから再開することで、設定された memories ディレクトリ全体を保持して再利用してください。新しい空の sandbox では、メモリも空の状態で始まります。
+
+`memory()` は、メモリの読み取りと生成の両方を有効にします。メモリは読み取るが新しいメモリは生成しないエージェントには `memory({ generate: false })` を使います。たとえば、内部エージェント、サブエージェント、チェッカー、または実行からあまり有用なシグナルが得られない単発のツールエージェントなどです。実行によって後で使うメモリは生成したいが、既存のメモリの影響は受けたくない場合は `memory({ read: null })` を使います。
+
+<Code
+  lang="typescript"
+  code={readOnlyMemoryExample}
+  title="読み取り専用メモリの設定"
+/>
+
+## メモリの読み取り
+
+メモリの読み取りでは、段階的開示が使われます。実行開始時に、SDK は一般的に有用なヒント、ユーザーの好み、利用可能なメモリをまとめた小さな要約 (`memory_summary.md`) を、エージェントの developer prompt に注入します。これにより、過去の作業が関係しそうかどうかを判断するのに十分なコンテキストが与えられます。
+
+過去の作業が関連していそうな場合、エージェントは現在のタスクのキーワードを使って、設定されたメモリインデックス（`memoriesDir` 配下の `MEMORY.md`）を検索します。さらに詳細が必要な場合にのみ、設定された `rollout_summaries/` ディレクトリ配下の対応する過去の rollout 要約を開きます。
+
+メモリは古くなることがあります。エージェントには、メモリはあくまで参考情報として扱い、現在の環境を信頼するよう指示されます。デフォルトでは、メモリ読み取りでは `liveUpdate` が有効なので、エージェントが古いメモリを見つけた場合、同じ実行内で設定された `MEMORY.md` を更新できます。たとえば、実行がレイテンシに敏感である場合など、エージェントにメモリを読ませたいが実行中は変更させたくないときは、ライブ更新を無効にしてください。
+
+## メモリの生成
+
+実行が終了すると、sandbox ランタイムはその実行セグメントを会話ファイルに追記します。蓄積された会話ファイルは、sandbox セッションが閉じるときに処理されます。これらの会話ファイルには、ユーザー入力、assistant とツールの項目、中断、最終出力が含まれる可能性があるため、機微なワークロードには適切なメモリストアと保持ポリシーを使用してください。
+
+メモリ生成には 2 つのフェーズがあります。
+
+1. フェーズ 1: 会話の抽出。メモリ生成モデルが 1 つの蓄積済み会話ファイルを処理し、会話要約を生成します。system、developer、reasoning の内容は除外されます。会話が長すぎる場合は、冒頭と末尾を保持したまま、コンテキストウィンドウに収まるように切り詰められます。また、フェーズ 2 で統合できるように、会話からの簡潔なメモである元のメモリ抽出も生成します。
+2. フェーズ 2: レイアウトの統合。統合エージェントが 1 つのメモリレイアウトに対応する元のメモリを読み取り、より多くの根拠が必要な場合は会話要約を開き、`MEMORY.md` と `memory_summary.md` にパターンを抽出します。
+
+デフォルトのワークスペースレイアウトは次のとおりです。
+
+```text
+workspace/
+├── sessions/
+│   └── <rollout-id>.jsonl
+└── memories/
+    ├── memory_summary.md
+    ├── MEMORY.md
+    ├── raw_memories.md
+    ├── raw_memories/
+    └── rollout_summaries/
+```
+
+メモリ生成は `memory({ generate: ... })` で設定できます。
+
+<Code lang="typescript" code={generateMemoryExample} title="メモリ生成の設定" />
+
+`extraPrompt` を使うと、たとえば GTM agent における顧客情報や企業情報のように、ユースケースで特に重要なシグナルをメモリ生成器に伝えられます。
+
+最近の元のメモリが `maxRawMemoriesForConsolidation` を超える場合、フェーズ 2 では最新の会話由来のメモリだけを残し、古いものを削除します。新しさは、その会話が最後に更新された時点に基づきます。この忘却メカニズムにより、メモリが最新の環境を反映しやすくなります。
+
+## マルチターン会話
+
+複数ターンの sandbox チャットでは、通常の SDK `Session` を同じライブ sandbox セッションと組み合わせて使います。
+
+<Code
+  lang="typescript"
+  code={conversationIdentityExample}
+  title="1 つの SDK セッションを 1 つの sandbox セッションと併用"
+/>
+
+両方の実行は同じメモリ会話ファイルに追記されます。これは、同じ SDK 会話セッションを渡しているため、同じセッション ID を共有するからです。これは、ライブワークスペースを識別する sandbox とは異なり、sandbox はメモリ会話 ID には使われません。フェーズ 1 は sandbox セッションが閉じたときに蓄積された会話全体を見るため、分離された 2 つのターンではなく、やり取り全体からメモリを抽出できます。
+
+複数の `run(...)` 呼び出しを 1 つのメモリ会話にしたい場合は、それらの呼び出しにまたがって安定した識別子を渡します。メモリが実行を会話に関連付けるときは、次の順序で解決されます。
+
+1. `run(...)` に渡した `conversationId`
+2. SDK `Session` を渡した場合の SDK `session` ID
+3. 上記のどちらもない場合の `groupId`
+4. 安定した識別子がない場合の、実行ごとに生成される ID
+
+## 異なるエージェント向けに異なるレイアウトを使ってメモリを分離する
+
+メモリの分離は、エージェント名ではなく `MemoryLayoutConfig` に基づきます。同じレイアウトと同じメモリ会話 ID を持つエージェントは、1 つのメモリ会話と 1 つの統合メモリを共有します。異なるレイアウトを持つエージェントは、同じ sandbox ワークスペースを共有していても、rollout ファイル、元のメモリ、`MEMORY.md`、`memory_summary.md` を別々に保持します。
+
+複数のエージェントが 1 つの sandbox を共有していてもメモリを共有すべきでない場合は、別々のレイアウトを使います。
+
+<Code
+  lang="typescript"
+  code={memoryLayoutsExample}
+  title="個別のメモリレイアウトを使う"
+/>
+
+これにより、あるドメインの分析が別のドメインのメモリに統合されることや、その逆を防げます。