docs: update translated document pages (#2893)

Author: github-actions[bot]

docs/ja/agents.md

@@ -4,45 +4,47 @@ search:
 ---
 # コンテキスト管理
 
-コンテキストは多義的な用語です。主に重要になるコンテキストは 2 つあります。
+コンテキストは多義的な用語です。主に、重要になるコンテキストには 2 つの分類があります。
 
-1. コード内でローカルに利用可能なコンテキスト: これは、ツール関数の実行時、`on_handoff` のようなコールバック時、ライフサイクルフック内などで必要になる可能性があるデータや依存関係です。
-2. LLM で利用可能なコンテキスト: これは、レスポンス生成時に LLM が参照するデータです。
+1. コード内でローカルに利用可能なコンテキスト: これは、関数ツールの実行時、`on_handoff` のようなコールバック時、ライフサイクルフック時などに必要になる可能性があるデータや依存関係です。
+2. LLM が利用可能なコンテキスト: これは、LLM がレスポンスを生成するときに参照するデータです。
 
 ## ローカルコンテキスト
 
-これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。
+これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その内部の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。動作は次のとおりです。
 
-1. 任意の Python オブジェクトを作成します。一般的なパターンは dataclass または Pydantic オブジェクトを使うことです。
-2. そのオブジェクトを各種 run メソッドに渡します (例: `Runner.run(..., context=whatever)`)。
-3. すべてのツール呼び出し、ライフサイクルフックなどに、`RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型であり、`wrapper.context` でアクセスできます。
+1. 任意の Python オブジェクトを作成します。一般的なパターンは、dataclass または Pydantic オブジェクトを使うことです。
+2. そのオブジェクトを各種 run メソッドに渡します（例: `Runner.run(..., context=whatever)`）。
+3. すべてのツール呼び出し、ライフサイクルフックなどには `RunContextWrapper[T]` のラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` でアクセスできます。
 
-注意すべき **最も重要な** 点: 特定のエージェント実行におけるすべてのエージェント、ツール関数、ライフサイクルなどは、同じコンテキストの _型_ を使用する必要があります。
+ランタイム固有の一部コールバックでは、SDK が `RunContextWrapper[T]` のより特化したサブクラスを渡す場合があります。たとえば、関数ツールのライフサイクルフックは通常 `ToolContext` を受け取り、`tool_call_id`、`tool_name`、`tool_arguments` などのツール呼び出しメタデータにもアクセスできます。
 
-コンテキストは次のような用途で使えます。
+認識しておくべき **最も重要** な点: 特定のエージェント実行におけるすべてのエージェント、関数ツール、ライフサイクルなどは、同じコンテキストの _型_ を使用する必要があります。
 
--   実行時の文脈データ (例: ユーザー名 / uid やその他のユーザー情報)
--   依存関係 (例: logger オブジェクト、データフェッチャーなど)
+コンテキストは次のような用途で使用できます。
+
+-   実行のためのコンテキストデータ（例: ユーザー名 / uid や、ユーザーに関するその他の情報）
+-   依存関係（例: logger オブジェクト、データ取得処理など）
 -   ヘルパー関数
 
-!!! danger "注記"
+!!! danger "注意"
 
-    コンテキストオブジェクトは LLM に送信され **ません**。これは純粋にローカルオブジェクトであり、読み取り、書き込み、メソッド呼び出しを行えます。
+    コンテキストオブジェクトは LLM に **送信されません**。これは純粋にローカルオブジェクトであり、読み取り、書き込み、メソッド呼び出しが可能です。
 
-単一の実行内では、派生ラッパーは同じ基盤の app コンテキスト、承認状態、使用量トラッキングを共有します。ネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行では別の `tool_input` が付与される場合がありますが、既定では app 状態の分離コピーは取得しません。
+1 回の実行内では、派生ラッパーは同じ基盤のアプリコンテキスト、承認状態、使用量トラッキングを共有します。ネストした [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行では別の `tool_input` が付与される場合がありますが、デフォルトではアプリ状態の分離コピーは取得しません。
 
 ### `RunContextWrapper` の公開内容
 
-[`RunContextWrapper`][agents.run_context.RunContextWrapper] は、app で定義したコンテキストオブジェクトのラッパーです。実際には、主に次を使用します。
+[`RunContextWrapper`][agents.run_context.RunContextWrapper] は、アプリで定義したコンテキストオブジェクトのラッパーです。実際には、主に次を使用します。
 
--   独自の可変 app 状態および依存関係には [`wrapper.context`][agents.run_context.RunContextWrapper.context]。
--   現在の実行全体で集計されたリクエストおよびトークン使用量には [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]。
--   現在の実行が [`Agent.as_tool()`][agents.agent.Agent.as_tool] 内で動作している場合の構造化入力には [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]。
--   承認状態をプログラムから更新する必要がある場合は [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]。
+-   独自の可変アプリ状態および依存関係には [`wrapper.context`][agents.run_context.RunContextWrapper.context]。
+-   現在の実行全体の集計されたリクエストおよびトークン使用量には [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]。
+-   現在の実行が [`Agent.as_tool()`][agents.agent.Agent.as_tool] 内で実行されているときの構造化入力には [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]。
+-   承認状態をプログラムで更新する必要がある場合は [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]。
 
-`wrapper.context` のみが app で定義したオブジェクトです。その他のフィールドは SDK が管理する実行時メタデータです。
+アプリで定義したオブジェクトは `wrapper.context` のみです。その他のフィールドは SDK が管理するランタイムメタデータです。
 
-後で human-in-the-loop や永続ジョブワークフローのために [`RunState`][agents.run_state.RunState] をシリアライズする場合、その実行時メタデータは状態とともに保存されます。シリアライズした状態を永続化または送信する予定がある場合、[`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] に秘密情報を入れるのは避けてください。
+後で human-in-the-loop や永続ジョブワークフロー向けに [`RunState`][agents.run_state.RunState] をシリアライズする場合、そのランタイムメタデータは状態とともに保存されます。シリアライズした状態を永続化または送信する予定がある場合は、[`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] にシークレットを入れないでください。
 
 会話状態は別の関心事項です。ターンをどのように引き継ぐかに応じて、`result.to_input_list()`、`session`、`conversation_id`、または `previous_response_id` を使用してください。この判断については [results](results.md)、[running agents](running_agents.md)、[sessions](sessions/index.md) を参照してください。
 
@@ -83,18 +85,18 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-1. これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使用できます。
-2. これがツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツール実装はコンテキストを読み取ります。
-3. エージェントにジェネリック `UserInfo` を指定しているため、型チェッカーがエラーを検出できます (たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合)。
+1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。
+2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツール実装はコンテキストから読み取ります。
+3. 型チェッカーがエラーを検出できるように、エージェントをジェネリック `UserInfo` で指定します（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合）。
 4. コンテキストは `run` 関数に渡されます。
 5. エージェントは正しくツールを呼び出し、年齢を取得します。
 
 ---
 
-### 高度な利用: `ToolContext`
+### 高度な使用法: `ToolContext`
 
-場合によっては、実行中のツールに関する追加メタデータ (名前、呼び出し ID、raw 引数文字列など) にアクセスしたいことがあります。  
-このために、`RunContextWrapper` を拡張した [`ToolContext`][agents.tool_context.ToolContext] クラスを使用できます。
+場合によっては、実行中のツールに関する追加メタデータ（名前、呼び出し ID、生の引数文字列など）にアクセスしたいことがあります。  
+このために、`RunContextWrapper` を拡張する [`ToolContext`][agents.tool_context.ToolContext] クラスを使用できます。
 
 ```python
 from typing import Annotated
@@ -123,24 +125,24 @@ agent = Agent(
 ```
 
 `ToolContext` は `RunContextWrapper` と同じ `.context` プロパティを提供し、  
-さらに現在のツール呼び出しに固有の追加フィールドを提供します。
+さらに現在のツール呼び出しに固有の追加フィールドも提供します。
 
-- `tool_name` – 呼び出されるツール名  
+- `tool_name` – 呼び出されるツールの名前  
 - `tool_call_id` – このツール呼び出しの一意識別子  
-- `tool_arguments` – ツールに渡される raw 引数字符串  
-- `tool_namespace` – ツールが `tool_namespace()` または他の名前空間付きサーフェス経由で読み込まれた場合の、ツール呼び出し用 Responses 名前空間  
-- `qualified_tool_name` – 名前空間が利用可能な場合の、名前空間付きツール名  
+- `tool_arguments` – ツールに渡される生の引数文字列  
+- `tool_namespace` – ツールが `tool_namespace()` または他の名前空間付きサーフェスを通じて読み込まれた場合の、ツール呼び出しの Responses 名前空間  
+- `qualified_tool_name` – 名前空間が利用可能な場合に、その名前空間で修飾されたツール名  
 
 実行中にツールレベルのメタデータが必要な場合は `ToolContext` を使用してください。  
-エージェントとツール間での一般的なコンテキスト共有では、`RunContextWrapper` で十分です。`ToolContext` は `RunContextWrapper` を拡張しているため、ネストされた `Agent.as_tool()` 実行で構造化入力が渡された場合は `.tool_input` も公開できます。
+エージェントとツール間の一般的なコンテキスト共有には、`RunContextWrapper` で十分です。`ToolContext` は `RunContextWrapper` を拡張しているため、ネストした `Agent.as_tool()` 実行が構造化入力を提供した場合は `.tool_input` も公開できます。
 
 ---
 
 ## エージェント / LLM コンテキスト
 
-LLM が呼び出されるとき、参照できるデータは会話履歴内のもの **のみ** です。これは、LLM に新しいデータを利用可能にしたい場合、それを会話履歴内で利用可能にする方法で渡す必要があることを意味します。方法はいくつかあります。
+LLM が呼び出されると、参照できるデータは会話履歴にあるもの **のみ** です。つまり、新しいデータを LLM で利用可能にしたい場合は、その履歴で利用できる形にする必要があります。方法はいくつかあります。
 
-1. Agent の `instructions` に追加できます。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的文字列にも、コンテキストを受け取って文字列を返す動的関数にもできます。これは、常に有用な情報 (たとえばユーザー名や現在日付) に対する一般的な手法です。
-2. `Runner.run` 関数を呼び出すときの `input` に追加します。これは `instructions` の手法に似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) でより下位のメッセージを持てます。
-3. 関数ツールを通じて公開します。これは _オンデマンド_ のコンテキストに有用です。つまり、LLM がデータを必要とするタイミングを判断し、そのデータ取得のためにツールを呼び出せます。
-4. retrieval または Web 検索を使用します。これらは、ファイルやデータベース (retrieval)、または Web (Web 検索) から関連データを取得できる特別なツールです。これは、関連する文脈データに基づいてレスポンスを「グラウンディング」するのに有用です。
+1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的文字列にもできますし、コンテキストを受け取って文字列を返す動的関数にもできます。これは、常に有用な情報（たとえばユーザー名や現在日付）に対する一般的な手法です。
+2. `Runner.run` 関数を呼び出す際の `input` に追加します。これは `instructions` の手法に似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) でより下位のメッセージを持てます。
+3. 関数ツールを介して公開します。これは _オンデマンド_ のコンテキストに有用です。LLM がデータを必要とするタイミングを判断し、そのデータを取得するためにツールを呼び出せます。
+4. retrieval または Web 検索を使用します。これらは、ファイルやデータベース（retrieval）、または Web（Web 検索）から関連データを取得できる特別なツールです。これは、レスポンスを関連するコンテキストデータに「グラウンディング」するのに有用です。