Merge remote-tracking branch 'origin/main' into feat/sqlalchemy-sessions

Author: habema

docs/index.md

@@ -4,7 +4,7 @@ The [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) enables
 
 -   **Agents**, which are LLMs equipped with instructions and tools
 -   **Handoffs**, which allow agents to delegate to other agents for specific tasks
--   **Guardrails**, which enable the inputs to agents to be validated
+-   **Guardrails**, which enable validation of agent inputs and outputs
 -   **Sessions**, which automatically maintains conversation history across agent runs
 
 In combination with Python, these primitives are powerful enough to express complex relationships between tools and agents, and allow you to build real-world applications without a steep learning curve. In addition, the SDK comes with built-in **tracing** that lets you visualize and debug your agentic flows, as well as evaluate them and even fine-tune models for your application.

docs/ja/agents.md

@@ -4,16 +4,16 @@ search:
 ---
 # エージェント
 
-エージェントはアプリのコアとなる構成要素です。エージェントは instructions とツールで設定された大規模言語モデル（LLM）です。
+エージェントはアプリの中核となるビルディングブロックです。エージェントとは、指示とツールで構成された大規模言語モデル ( LLM ) です。
 
 ## 基本設定
 
-エージェントで最も一般的に設定するプロパティは次のとおりです。
+エージェントで最もよく設定するプロパティは次のとおりです。
 
-- `name`: エージェントを識別する必須の文字列。  
-- `instructions`: developer メッセージまたは system prompt とも呼ばれます。  
-- `model`: 使用する LLM、および temperature や top_p などのモデルチューニングパラメーターを設定する任意の `model_settings`。  
-- `tools`: エージェントがタスクを達成するために使用できるツール。  
+- `name`: エージェントを識別する必須の文字列。
+- `instructions`: developer メッセージまたは system prompt とも呼ばれます。
+- `model`: 使用する LLM、および temperature や top_p などのチューニングパラメーターを設定する `model_settings` (オプション)。
+- `tools`: エージェントがタスク達成のために使用できるツール。
 
 ```python
 from agents import Agent, ModelSettings, function_tool
@@ -33,7 +33,7 @@ agent = Agent(
 
 ## コンテキスト
 
-エージェントは `context` 型に対してジェネリックです。コンテキストは依存性インジェクション用のツールで、`Runner.run()` に渡すオブジェクトです。これがすべてのエージェント、ツール、ハンドオフなどに渡され、実行時の依存関係や状態をまとめて保持します。任意の Python オブジェクトをコンテキストとして渡すことができます。
+エージェントはその `context` 型に対して汎用的です。コンテキストは依存性注入ツールであり、あなたが作成して `Runner.run()` に渡すオブジェクトです。このオブジェクトはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行の依存関係や状態をまとめて保持します。コンテキストには任意の Python オブジェクトを渡せます。
 
 ```python
 @dataclass
@@ -52,7 +52,7 @@ agent = Agent[UserContext](
 
 ## 出力タイプ
 
-デフォルトでは、エージェントはプレーンテキスト（つまり `str`）を出力します。特定の型で出力させたい場合は、`output_type` パラメーターを使用します。よく使われるのは [Pydantic](https://docs.pydantic.dev/) オブジェクトですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型—dataclasses、list、TypedDict など—であれば何でもサポートされています。
+デフォルトでは、エージェントはプレーンテキスト (すなわち `str`) を出力します。特定の型で出力させたい場合は、`output_type` パラメーターを使用します。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを使いますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型―dataclass、list、TypedDict など―であれば利用できます。
 
 ```python
 from pydantic import BaseModel
@@ -73,11 +73,11 @@ agent = Agent(
 
 !!! note
 
-    `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。
+    `output_type` を指定すると、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。
 
 ## ハンドオフ
 
-ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを渡しておくと、エージェントは適切な場合にそれらへ委任できます。これは、単一タスクに特化したモジュール式エージェントをオーケストレーションする強力なパターンです。詳細は [ハンドオフ](handoffs.md) のドキュメントを参照してください。
+ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを提供すると、エージェントは関連する場合にそれらへ委譲できます。これは、単一タスクに特化したモジュール型エージェントをオーケストレーションする強力なパターンです。詳しくは [handoffs](handoffs.md) ドキュメントをご覧ください。
 
 ```python
 from agents import Agent
@@ -98,7 +98,7 @@ triage_agent = Agent(
 
 ## 動的 instructions
 
-多くの場合、エージェント作成時に instructions を指定しますが、関数を介して動的に instructions を提供することもできます。その関数はエージェントとコンテキストを受け取り、プロンプトを返さなければなりません。同期関数・`async` 関数のどちらも使用できます。
+通常はエージェント作成時に instructions を渡しますが、関数を通じて動的に渡すこともできます。この関数はエージェントと context を受け取り、プロンプトを返さなければなりません。同期関数と `async` 関数の両方を使用できます。
 
 ```python
 def dynamic_instructions(
@@ -113,17 +113,17 @@ agent = Agent[UserContext](
 )
 ```
 
-## ライフサイクルイベント（フック）
+## ライフサイクルイベント (フック)
 
-エージェントのライフサイクルを監視したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりできます。`hooks` プロパティを利用してエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] を継承し、必要なメソッドをオーバーライドしてください。
+エージェントのライフサイクルを監視したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータをプリフェッチしたりするケースです。`hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] をサブクラス化し、関心のあるメソッドをオーバーライドしてください。
 
 ## ガードレール
 
-ガードレールを使用すると、エージェントの実行と並行してユーザー入力に対するチェック／バリデーションを行えます。たとえば、ユーザー入力の関連性をスクリーニングすることが可能です。詳細は [ガードレール](guardrails.md) のドキュメントをご覧ください。
+ガードレールを使うと、エージェント実行と並行してユーザー入力に対するチェックやバリデーションを実行できます。たとえば、ユーザー入力の関連性をスクリーニングすることが可能です。詳細は [guardrails](guardrails.md) ドキュメントをご覧ください。
 
-## エージェントの複製／コピー
+## エージェントのクローン／コピー
 
-エージェントの `clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。
+エージェントの `clone()` メソッドを使うと、エージェントを複製し、任意のプロパティを変更できます。
 
 ```python
 pirate_agent = Agent(
@@ -140,12 +140,12 @@ robot_agent = pirate_agent.clone(
 
 ## ツール使用の強制
 
-ツールのリストを指定しても、LLM が必ずしもツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は次のとおりです。
+ツールのリストを渡しても、必ずしも LLM がツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定するとツール使用を強制できます。有効な値は次のとおりです。
 
-1. `auto`: LLM がツールを使うかどうかを判断します。  
-2. `required`: LLM にツール使用を必須とします（使用するツールは自動選択されます）。  
-3. `none`: LLM にツールを使用しないことを要求します。  
-4. 具体的な文字列（例: `my_tool`）を設定すると、その特定のツールの使用を要求します。  
+1. `auto` : LLM がツールを使用するかどうかを自動で判断します。
+2. `required` : LLM にツール使用を必須とします (使用するツールはインテリジェントに決定)。
+3. `none` : LLM にツールを使用しないことを要求します。
+4. 具体的な文字列 (例: `my_tool`) を設定すると、そのツールを必ず使用させます。
 
 ```python
 from agents import Agent, Runner, function_tool, ModelSettings
@@ -163,11 +163,12 @@ agent = Agent(
 )
 ```
 
-## ツール使用動作
+## ツール使用の挙動
 
-`Agent` の `tool_use_behavior` パラメーターはツール出力の扱いを制御します。  
-- `"run_llm_again"`: デフォルト。ツールを実行した後、LLM が結果を処理して最終応答を生成します。  
-- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を最終応答として使用し、LLM による追加処理を行いません。  
+`Agent` の `tool_use_behavior` パラメーターはツール出力の扱い方を制御します。
+
+- `"run_llm_again"`: デフォルト設定。ツールを実行し、その結果を LLM が処理して最終応答を生成します。
+- `"stop_on_first_tool"`: 最初に呼び出されたツールの出力をそのまま最終応答として使用し、追加の LLM 処理を行いません。
 
 ```python
 from agents import Agent, Runner, function_tool, ModelSettings
@@ -185,7 +186,7 @@ agent = Agent(
 )
 ```
 
-- `StopAtTools(stop_at_tool_names=[...])`: 指定したツールのいずれかが呼び出された時点で停止し、その出力を最終応答として使用します。  
+- `StopAtTools(stop_at_tool_names=[...])`: 指定したツールのいずれかが呼び出されると停止し、その出力を最終応答とします。  
 ```python
 from agents import Agent, Runner, function_tool
 from agents.agent import StopAtTools
@@ -207,7 +208,7 @@ agent = Agent(
     tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"])
 )
 ```
-- `ToolsToFinalOutputFunction`: ツールの結果を処理し、停止するか LLM を継続するかを判断するカスタム関数です。  
+- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を続行するかを決定するカスタム関数。  
 
 ```python
 from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
@@ -245,4 +246,4 @@ agent = Agent(
 
 !!! note
 
-    無限ループを防ぐため、フレームワークはツール呼び出し後に自動で `tool_choice` を "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。ツール結果が LLM に送られ、`tool_choice` により再度ツール呼び出しが生成される…というループを防ぐためです。
+    無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。ツール結果が LLM に送られ、その後 `tool_choice` により再度ツール呼び出しが生成され…という無限ループを防止するためです。

docs/ja/config.md

@@ -6,15 +6,15 @@ search:
 
 ## API キーとクライアント
 
-デフォルトでは、 SDK はインポートされるとすぐに LLM リクエストと トレーシング のために `OPENAI_API_KEY` 環境変数を探します。アプリが起動する前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。
+デフォルトでは、SDK をインポートした直後から、LLM リクエストとトレーシングに使用する環境変数 `OPENAI_API_KEY` を参照します。アプリ起動前にこの環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。
 
 ```python
 from agents import set_default_openai_key
 
 set_default_openai_key("sk-...")
 ```
 
-また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は `AsyncOpenAI` インスタンスを作成し、環境変数または前述のデフォルトキーに設定された API キーを使用します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。
+また、使用する OpenAI クライアントを個別に設定することも可能です。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを生成します。[set_default_openai_client()][agents.set_default_openai_client] 関数を使うことで、この設定を変更できます。
 
 ```python
 from openai import AsyncOpenAI
@@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...")
 set_default_openai_client(custom_client)
 ```
 
-最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは、 OpenAI Responses API を使用します。[set_default_openai_api()][agents.set_default_openai_api] 関数を使用して Chat Completions API を使用するように上書きできます。
+さらに、使用する OpenAI API もカスタマイズできます。デフォルトでは OpenAI Responses API を利用しますが、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用して Chat Completions API に切り替えられます。
 
 ```python
 from agents import set_default_openai_api
@@ -34,35 +34,35 @@ set_default_openai_api("chat_completions")
 
 ## トレーシング
 
-トレーシングはデフォルトで有効になっています。デフォルトでは、前述の OpenAI API キー（環境変数または設定したデフォルトキー）が使用されます。[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用して、トレーシングに使用される API キーを個別に設定できます。
+トレーシングはデフォルトで有効です。上記セクションで説明した OpenAI API キー（環境変数または設定したデフォルトキー）が使用されます。トレーシング専用の API キーを指定したい場合は、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を利用してください。
 
 ```python
 from agents import set_tracing_export_api_key
 
 set_tracing_export_api_key("sk-...")
 ```
 
-[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用すると、トレーシングを完全に無効化できます。
+トレーシングを完全に無効にする場合は、[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用します。
 
 ```python
 from agents import set_tracing_disabled
 
 set_tracing_disabled(True)
 ```
 
-## デバッグログ
+## デバッグ ロギング
 
-SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。そのため、デフォルトでは警告とエラーは `stdout` に送られますが、それ以外のログは抑制されます。
+SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、警告とエラーは `stdout` に送られますが、それ以外のログは抑制されます。
 
-詳細ログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。
+詳細なロギングを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。
 
 ```python
 from agents import enable_verbose_stdout_logging
 
 enable_verbose_stdout_logging()
 ```
 
-また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳しくは [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。
+ログを独自にカスタマイズしたい場合は、ハンドラー、フィルター、フォーマッターなどを追加できます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。
 
 ```python
 import logging
@@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING)
 logger.addHandler(logging.StreamHandler())
 ```
 
-### ログに含まれる機密データ
+### ログ内の機密データ
 
-一部のログには機密データ（例: ユーザー データ）が含まれる場合があります。これらのデータが記録されないようにするには、次の環境変数を設定してください。
+一部のログには機密データ（例：ユーザーデータ）が含まれる場合があります。こうしたデータの出力を無効にしたい場合は、以下の環境変数を設定してください。
 
-LLM の入力および出力のログを無効化するには:
+LLM の入力と出力のロギングを無効にする:
 
 ```bash
 export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
 ```
 
-ツールの入力および出力のログを無効化するには:
+ツールの入力と出力のロギングを無効にする:
 
 ```bash
 export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1