Add i18n support to the documents

Author: seratch

Makefile

@@ -42,6 +42,11 @@ old_version_tests:
 build-docs:
 	uv run mkdocs build
 
+.PHONY: build-full-docs
+build-full-docs:
+	uv run docs/scripts/translate_docs.py
+	uv run mkdocs build
+
 .PHONY: serve-docs
 serve-docs:
 	uv run mkdocs serve

docs/ja/agents.md

@@ -0,0 +1,147 @@
+# エージェント
+
+エージェント はアプリケーションの基本的な構成要素です。エージェント は、大規模言語モデル（LLM）であり、 instructions と tools を用いて設定されます。
+
+## 基本設定
+
+エージェント の設定でよく使われるプロパティは以下の通りです。
+
+- `instructions` : 開発者メッセージまたはシステムプロンプトとも呼ばれます。
+- `model` : 使用する LLM を指定します。オプションで `model_settings` を指定し、temperature や top_p などのモデル調整パラメータを設定できます。
+- `tools` : エージェント がタスクを達成するために使用できるツールです。
+
+```python
+from agents import Agent, ModelSettings, function_tool
+
+@function_tool
+def get_weather(city: str) -> str:
+    return f"The weather in {city} is sunny"
+
+agent = Agent(
+    name="Haiku agent",
+    instructions="Always respond in haiku form",
+    model="o3-mini",
+    tools=[get_weather],
+)
+```
+
+## コンテキスト
+
+エージェント は、 `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールであり、作成したオブジェクトを `Runner.run()` に渡すことで、各エージェント、ツール、ハンドオフなどに渡されます。これはエージェントの実行に必要な依存関係や状態をまとめて保持するためのものです。任意の Python オブジェクトをコンテキストとして提供できます。
+
+```python
+@dataclass
+class UserContext:
+  uid: str
+  is_pro_user: bool
+
+  async def fetch_purchases() -> list[Purchase]:
+     return ...
+
+agent = Agent[UserContext](
+    ...,
+)
+```
+
+## 出力タイプ
+
+デフォルトでは、エージェント はプレーンテキスト（つまり `str` ）を出力します。特定の型の出力を生成させたい場合は、 `output_type` パラメータを使用します。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを使用しますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップ可能な型（データクラス、リスト、TypedDict など）であればどのような型でもサポートしています。
+
+```python
+from pydantic import BaseModel
+from agents import Agent
+
+
+class CalendarEvent(BaseModel):
+    name: str
+    date: str
+    participants: list[str]
+
+agent = Agent(
+    name="Calendar extractor",
+    instructions="Extract calendar events from text",
+    output_type=CalendarEvent,
+)
+```
+
+!!! note
+
+    `output_type` を指定すると、モデルは通常のプレーンテキストのレスポンスではなく、 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。
+
+## ハンドオフ
+
+ハンドオフ は、エージェント が処理を委譲できるサブエージェントです。ハンドオフのリストを提供すると、エージェント は必要に応じてそれらに処理を委譲できます。これは、特定のタスクに特化したモジュール型のエージェントを組み合わせて調整するための強力なパターンです。詳細は [ハンドオフ](handoffs.md) のドキュメントを参照してください。
+
+```python
+from agents import Agent
+
+booking_agent = Agent(...)
+refund_agent = Agent(...)
+
+triage_agent = Agent(
+    name="Triage agent",
+    instructions=(
+        "Help the user with their questions."
+        "If they ask about booking, handoff to the booking agent."
+        "If they ask about refunds, handoff to the refund agent."
+    ),
+    handoffs=[booking_agent, refund_agent],
+)
+```
+
+## 動的な instructions
+
+多くの場合、エージェント 作成時に instructions を指定しますが、関数を通じて動的に instructions を提供することも可能です。この関数はエージェントとコンテキストを受け取り、プロンプトを返します。通常の関数と `async` 関数の両方が使用可能です。
+
+```python
+def dynamic_instructions(
+    context: RunContextWrapper[UserContext], agent: Agent[UserContext]
+) -> str:
+    return f"The user's name is {context.context.name}. Help them with their questions."
+
+
+agent = Agent[UserContext](
+    name="Triage agent",
+    instructions=dynamic_instructions,
+)
+```
+
+## ライフサイクルイベント（フック）
+
+エージェント のライフサイクルを監視したい場合があります。例えば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりできます。エージェント のライフサイクルにフックするには、 `hooks` プロパティを使用します。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドします。
+
+## ガードレール
+
+ガードレール を使用すると、エージェント の実行と並行してユーザー入力に対するチェックや検証を実行できます。例えば、ユーザー入力の関連性を検証できます。詳細は [ガードレール](guardrails.md) のドキュメントを参照してください。
+
+## エージェント の複製（クローン）
+
+エージェント の `clone()` メソッドを使用すると、エージェント を複製し、必要に応じてプロパティを変更できます。
+
+```python
+pirate_agent = Agent(
+    name="Pirate",
+    instructions="Write like a pirate",
+    model="o3-mini",
+)
+
+robot_agent = pirate_agent.clone(
+    name="Robot",
+    instructions="Write like a robot",
+)
+```
+
+## ツール使用の強制
+
+ツールのリストを提供しても、必ずしも LLM がツールを使用するとは限りません。ツールの使用を強制するには、 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定します。有効な値は以下の通りです。
+
+1. `auto` : LLM がツールを使用するかどうかを決定します。
+2. `required` : LLM にツールの使用を強制します（ただし、どのツールを使用するかは LLM が判断します）。
+3. `none` : LLM にツールを使用しないことを強制します。
+4. 特定の文字列（例： `my_tool` ）を設定すると、LLM はその特定のツールを使用することを強制されます。
+
+!!! note
+
+    無限ループを防ぐため、フレームワークはツール呼び出し後に自動的に `tool_choice` を "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。無限ループは、ツールの実行結果が LLM に送信され、再びツール呼び出しが生成されるために発生します。
+
+    ツール呼び出し後に完全に停止させたい場合（自動モードで続行しない場合）は、 [`Agent.tool_use_behavior="stop_on_first_tool"`] を設定すると、ツールの出力を最終レスポンスとして直接使用し、それ以上の LLM 処理を行いません。

docs/ja/config.md

@@ -0,0 +1,94 @@
+# SDK の設定
+
+## API キーとクライアント
+
+デフォルトでは、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` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。
+
+```python
+from openai import AsyncOpenAI
+from agents import set_default_openai_client
+
+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 に変更できます。
+
+```python
+from agents import set_default_openai_api
+
+set_default_openai_api("chat_completions")
+```
+
+## トレーシング
+
+トレーシングはデフォルトで有効になっています。デフォルトでは、前述のセクションで設定した 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] 関数を使用してトレーシングを完全に無効化することもできます。
+
+```python
+from agents import set_tracing_disabled
+
+set_tracing_disabled(True)
+```
+
+## デバッグログ
+
+SDK はデフォルトでハンドラーが設定されていない 2 つの Python ロガーを持っています。デフォルトでは、警告およびエラーが `stdout` に送信され、それ以外のログは抑制されます。
+
+詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。
+
+```python
+from agents import enable_verbose_stdout_logging
+
+enable_verbose_stdout_logging()
+```
+
+また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることも可能です。詳細については、[Python logging ガイド](https://docs.python.org/3/howto/logging.html) を参照してください。
+
+```python
+import logging
+
+logger = logging.getLogger("openai.agents") # トレーシング用ロガーの場合は openai.agents.tracing
+
+# すべてのログを表示する場合
+logger.setLevel(logging.DEBUG)
+# INFO 以上を表示する場合
+logger.setLevel(logging.INFO)
+# WARNING 以上を表示する場合
+logger.setLevel(logging.WARNING)
+# その他、必要に応じて設定
+
+# 必要に応じてカスタマイズ可能ですが、デフォルトでは `stderr` に出力されます
+logger.addHandler(logging.StreamHandler())
+```
+
+### ログ内の機密データ
+
+一部のログには機密データ（ユーザーデータなど）が含まれる場合があります。このデータのログ記録を無効化したい場合は、以下の環境変数を設定してください。
+
+LLM の入力および出力のログ記録を無効化する場合：
+
+```bash
+export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
+```
+
+ツールの入力および出力のログ記録を無効化する場合：
+
+```bash
+export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1
+```

docs/ja/context.md

@@ -0,0 +1,77 @@
+# コンテキスト管理
+
+コンテキストという用語は多義的です。主に次の 2 種類のコンテキストがあります。
+
+1. コード内でローカルに利用可能なコンテキスト：これは、関数ツールの実行時、`on_handoff` などのコールバック時、ライフサイクルフック時などに必要となるデータや依存関係です。
+2. LLM が利用可能なコンテキスト：これは、LLM が応答を生成する際に参照するデータです。
+
+## ローカルコンテキスト
+
+これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その内部の [`context`][agents.run_context.RunContextWrapper.context] プロパティを通じて表現されます。動作の仕組みは以下の通りです。
+
+1. 任意の Python オブジェクトを作成します。一般的にはデータクラスや Pydantic オブジェクトを使用します。
+2. 作成したオブジェクトを各種の実行メソッドに渡します（例：`Runner.run(..., context=whatever)`）。
+3. すべての関数ツール呼び出しやライフサイクルフックなどには、ラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` を通じてアクセスできます。
+
+**最も重要な点** は、特定のエージェント実行において、すべてのエージェント、関数ツール、ライフサイクルフックなどが同じコンテキストの _型_ を使用しなければならないということです。
+
+コンテキストは以下のような用途で使用できます。
+
+- 実行時のコンテキストデータ（ユーザー名や UID など、ユーザーに関する情報）
+- 依存関係（ロガーオブジェクト、データ取得用オブジェクトなど）
+- ヘルパー関数
+
+!!! danger "注意"
+
+    コンテキストオブジェクトは LLM には送信され **ません**。これは純粋にローカルなオブジェクトであり、読み取り、書き込み、メソッド呼び出しが可能です。
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+from agents import Agent, RunContextWrapper, Runner, function_tool
+
+@dataclass
+class UserInfo:  # (1)!
+    name: str
+    uid: int
+
+@function_tool
+async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str:  # (2)!
+    return f"User {wrapper.context.name} is 47 years old"
+
+async def main():
+    user_info = UserInfo(name="John", uid=123)
+
+    agent = Agent[UserInfo](  # (3)!
+        name="Assistant",
+        tools=[fetch_user_age],
+    )
+
+    result = await Runner.run(  # (4)!
+        starting_agent=agent,
+        input="What is the age of the user?",
+        context=user_info,
+    )
+
+    print(result.final_output)  # (5)!
+    # The user John is 47 years old.
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+1. これがコンテキストオブジェクトです。ここではデータクラスを使用していますが、任意の型を使用できます。
+2. これは関数ツールです。`RunContextWrapper[UserInfo]` を引数として受け取り、コンテキストからデータを読み取っています。
+3. エージェントにジェネリック型 `UserInfo` を指定することで、型チェッカーがエラーを検出できるようにしています（例えば、異なるコンテキスト型を取るツールを渡そうとした場合など）。
+4. コンテキストを `run` 関数に渡しています。
+5. エージェントが正しくツールを呼び出し、年齢を取得しています。
+
+## エージェント / LLM コンテキスト
+
+LLM が呼び出される際、参照できるデータは会話履歴に含まれるもの **のみ** です。そのため、新しいデータを LLM に提供したい場合は、会話履歴に含まれるようにする必要があります。これを実現する方法はいくつかあります。
+
+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）やウェブ検索を使用する方法です。これらはファイルやデータベースから関連データを取得（検索）したり、ウェブからデータを取得（ウェブ検索）したりする特殊なツールです。これは関連するコンテキストデータに基づいて応答を「根拠付ける（grounding）」際に有効です。

docs/ja/examples.md

@@ -0,0 +1,40 @@
+# コード例
+
+SDK のさまざまな実装サンプルについては、[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) のコード例セクションをご覧ください。コード例は、異なるパターンや機能を示す複数のカテゴリに分類されています。
+
+## カテゴリ
+
+- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)：**
+  このカテゴリのコード例では、一般的なエージェント設計パターンを示しています。例えば、
+
+    - 決定論的ワークフロー
+    - ツールとしてのエージェント
+    - エージェントの並列実行
+
+- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic)：**
+  SDK の基本的な機能を示すコード例です。例えば、
+
+    - 動的なシステムプロンプト
+    - ストリーミング出力
+    - ライフサイクルイベント
+
+- **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools)：**
+  Web 検索やファイル検索などの OpenAI がホストするツールの実装方法と、それらをエージェントに統合する方法を学べます。
+
+- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers)：**
+  SDK で OpenAI 以外のモデルを使用する方法を確認できます。
+
+- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs)：**
+  エージェントのハンドオフに関する実践的なコード例を参照できます。
+
+- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp)：**
+  MCP を使用したエージェントの構築方法を学べます。
+
+- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** および **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot)：**
+  実際のアプリケーションを示す、より具体的なコード例です。
+
+    - **customer_service**：航空会社向けのカスタマーサービスシステムのコード例。
+    - **research_bot**：シンプルな詳細調査クローンのコード例。
+
+- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice)：**
+  TTS および STT モデルを使用した音声エージェントのコード例を参照できます。