Add i18n support to the documents (#460)
This commit is contained in:
Kazuhiro Sera
GitHub
parent
9d3d6a58e5
commit
ece647b93f
25 changed files with 2321 additions and 73 deletions
5
Makefile
5
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
|
||||
|
|
|
|||
147
docs/ja/agents.md
Normal file
147
docs/ja/agents.md
Normal file
|
|
@ -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 処理を行いません。
|
||||
94
docs/ja/config.md
Normal file
94
docs/ja/config.md
Normal file
|
|
@ -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
|
||||
```
|
||||
77
docs/ja/context.md
Normal file
77
docs/ja/context.md
Normal file
|
|
@ -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）」際に有効です。
|
||||
40
docs/ja/examples.md
Normal file
40
docs/ja/examples.md
Normal file
|
|
@ -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 モデルを使用した音声エージェントのコード例を参照できます。
|
||||
154
docs/ja/guardrails.md
Normal file
154
docs/ja/guardrails.md
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
# ガードレール
|
||||
|
||||
ガードレールは、エージェント と _並行して_ 実行され、ユーザー入力のチェックや検証を可能にします。例えば、顧客のリクエストを処理するために非常に高性能（したがって遅く高価）なモデルを使用する エージェント があるとします。悪意のあるユーザーがそのモデルに数学の宿題を解かせるようなことは避けたいでしょう。そのため、高速で安価なモデルを使った ガードレール を実行できます。ガードレール が悪意のある使用を検知すると、即座にエラーを発生させ、高価なモデルの実行を停止し、時間とコストを節約できます。
|
||||
|
||||
ガードレール には 2 種類あります：
|
||||
|
||||
1. 入力ガードレール：最初のユーザー入力に対して実行されます。
|
||||
2. 出力ガードレール：最終的な エージェント の出力に対して実行されます。
|
||||
|
||||
## 入力ガードレール
|
||||
|
||||
入力ガードレール は次の 3 ステップで実行されます：
|
||||
|
||||
1. 最初に、ガードレール は エージェント に渡されたものと同じ入力を受け取ります。
|
||||
2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。
|
||||
3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理が可能になります。
|
||||
|
||||
!!! Note
|
||||
|
||||
入力ガードレール はユーザー入力に対して実行されるため、エージェント の ガードレール は、その エージェント が *最初の* エージェント である場合にのみ実行されます。なぜ `guardrails` プロパティが エージェント にあり、`Runner.run` に渡されないのか疑問に思うかもしれませんが、これは ガードレール が実際の エージェント に関連付けられる傾向があるためです。異なる エージェント には異なる ガードレール を実行するため、コードを同じ場所に配置することで可読性が向上します。
|
||||
|
||||
## 出力ガードレール
|
||||
|
||||
出力ガードレール は次の 3 ステップで実行されます：
|
||||
|
||||
1. 最初に、ガードレール は エージェント に渡されたものと同じ入力を受け取ります。
|
||||
2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます。
|
||||
3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理が可能になります。
|
||||
|
||||
!!! Note
|
||||
|
||||
出力ガードレール は最終的な エージェント の出力に対して実行されるため、エージェント の ガードレール は、その エージェント が *最後の* エージェント である場合にのみ実行されます。入力ガードレール と同様に、これは ガードレール が実際の エージェント に関連付けられる傾向があるためです。異なる エージェント には異なる ガードレール を実行するため、コードを同じ場所に配置することで可読性が向上します。
|
||||
|
||||
## トリップワイヤ（Tripwires）
|
||||
|
||||
入力または出力が ガードレール を通過できない場合、ガードレール はトリップワイヤを使ってこれを通知します。トリップワイヤがトリガーされた ガードレール を検知すると、即座に `{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、エージェント の実行を停止します。
|
||||
|
||||
## ガードレール の実装
|
||||
|
||||
入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を提供する必要があります。この例では、内部で エージェント を実行することでこれを実現します。
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
from agents import (
|
||||
Agent,
|
||||
GuardrailFunctionOutput,
|
||||
InputGuardrailTripwireTriggered,
|
||||
RunContextWrapper,
|
||||
Runner,
|
||||
TResponseInputItem,
|
||||
input_guardrail,
|
||||
)
|
||||
|
||||
class MathHomeworkOutput(BaseModel):
|
||||
is_math_homework: bool
|
||||
reasoning: str
|
||||
|
||||
guardrail_agent = Agent( # (1)!
|
||||
name="Guardrail check",
|
||||
instructions="Check if the user is asking you to do their math homework.",
|
||||
output_type=MathHomeworkOutput,
|
||||
)
|
||||
|
||||
|
||||
@input_guardrail
|
||||
async def math_guardrail( # (2)!
|
||||
ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem]
|
||||
) -> GuardrailFunctionOutput:
|
||||
result = await Runner.run(guardrail_agent, input, context=ctx.context)
|
||||
|
||||
return GuardrailFunctionOutput(
|
||||
output_info=result.final_output, # (3)!
|
||||
tripwire_triggered=result.final_output.is_math_homework,
|
||||
)
|
||||
|
||||
|
||||
agent = Agent( # (4)!
|
||||
name="Customer support agent",
|
||||
instructions="You are a customer support agent. You help customers with their questions.",
|
||||
input_guardrails=[math_guardrail],
|
||||
)
|
||||
|
||||
async def main():
|
||||
# This should trip the guardrail
|
||||
try:
|
||||
await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?")
|
||||
print("Guardrail didn't trip - this is unexpected")
|
||||
|
||||
except InputGuardrailTripwireTriggered:
|
||||
print("Math homework guardrail tripped")
|
||||
```
|
||||
|
||||
1. この エージェント を ガードレール関数 内で使用します。
|
||||
2. これは エージェント の入力とコンテキストを受け取り、結果を返す ガードレール関数 です。
|
||||
3. ガードレール の結果に追加情報を含めることができます。
|
||||
4. これはワークフローを定義する実際の エージェント です。
|
||||
|
||||
出力ガードレール も同様です。
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
from agents import (
|
||||
Agent,
|
||||
GuardrailFunctionOutput,
|
||||
OutputGuardrailTripwireTriggered,
|
||||
RunContextWrapper,
|
||||
Runner,
|
||||
output_guardrail,
|
||||
)
|
||||
class MessageOutput(BaseModel): # (1)!
|
||||
response: str
|
||||
|
||||
class MathOutput(BaseModel): # (2)!
|
||||
reasoning: str
|
||||
is_math: bool
|
||||
|
||||
guardrail_agent = Agent(
|
||||
name="Guardrail check",
|
||||
instructions="Check if the output includes any math.",
|
||||
output_type=MathOutput,
|
||||
)
|
||||
|
||||
@output_guardrail
|
||||
async def math_guardrail( # (3)!
|
||||
ctx: RunContextWrapper, agent: Agent, output: MessageOutput
|
||||
) -> GuardrailFunctionOutput:
|
||||
result = await Runner.run(guardrail_agent, output.response, context=ctx.context)
|
||||
|
||||
return GuardrailFunctionOutput(
|
||||
output_info=result.final_output,
|
||||
tripwire_triggered=result.final_output.is_math,
|
||||
)
|
||||
|
||||
agent = Agent( # (4)!
|
||||
name="Customer support agent",
|
||||
instructions="You are a customer support agent. You help customers with their questions.",
|
||||
output_guardrails=[math_guardrail],
|
||||
output_type=MessageOutput,
|
||||
)
|
||||
|
||||
async def main():
|
||||
# This should trip the guardrail
|
||||
try:
|
||||
await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?")
|
||||
print("Guardrail didn't trip - this is unexpected")
|
||||
|
||||
except OutputGuardrailTripwireTriggered:
|
||||
print("Math output guardrail tripped")
|
||||
```
|
||||
|
||||
1. これは実際の エージェント の出力タイプです。
|
||||
2. これは ガードレール の出力タイプです。
|
||||
3. これは エージェント の出力を受け取り、結果を返す ガードレール関数 です。
|
||||
4. これはワークフローを定義する実際の エージェント です。
|
||||
113
docs/ja/handoffs.md
Normal file
113
docs/ja/handoffs.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
# ハンドオフ
|
||||
|
||||
ハンドオフを使用すると、あるエージェントが別のエージェントにタスクを委任できます。これは、異なるエージェントがそれぞれ特定の分野を専門としている場合に特に役立ちます。例えば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専門に処理するエージェントを用意できます。
|
||||
|
||||
ハンドオフは、LLM に対してツールとして表現されます。例えば、`Refund Agent` という名前のエージェントへのハンドオフがある場合、そのツールは `transfer_to_refund_agent` と呼ばれます。
|
||||
|
||||
## ハンドオフの作成
|
||||
|
||||
すべてのエージェントは [`handoffs`][agents.agent.Agent.handoffs] パラメータを持ち、これは直接 `Agent` を指定するか、またはカスタマイズされた `Handoff` オブジェクトを指定できます。
|
||||
|
||||
Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使用してハンドオフを作成できます。この関数を使用すると、ハンドオフ先のエージェントを指定し、オプションでオーバーライドや入力フィルターを設定できます。
|
||||
|
||||
### 基本的な使用方法
|
||||
|
||||
シンプルなハンドオフの作成方法は以下の通りです。
|
||||
|
||||
```python
|
||||
from agents import Agent, handoff
|
||||
|
||||
billing_agent = Agent(name="Billing agent")
|
||||
refund_agent = Agent(name="Refund agent")
|
||||
|
||||
# (1)!
|
||||
triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])
|
||||
```
|
||||
|
||||
1. エージェントを直接指定する方法（`billing_agent` のように）と、`handoff()` 関数を使用する方法があります。
|
||||
|
||||
### `handoff()` 関数を使用したハンドオフのカスタマイズ
|
||||
|
||||
[`handoff()`][agents.handoffs.handoff] 関数を使用すると、以下の項目をカスタマイズできます。
|
||||
|
||||
- `agent`：ハンドオフ先のエージェントを指定します。
|
||||
- `tool_name_override`：デフォルトでは `Handoff.default_tool_name()` 関数が使用され、`transfer_to_<agent_name>` という形式になりますが、これをオーバーライドできます。
|
||||
- `tool_description_override`：デフォルトのツール説明（`Handoff.default_tool_description()`）をオーバーライドします。
|
||||
- `on_handoff`：ハンドオフが呼び出された際に実行されるコールバック関数です。これは、ハンドオフが呼ばれた時点でデータ取得などの処理を開始する場合に便利です。この関数はエージェントのコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメータで制御されます。
|
||||
- `input_type`：ハンドオフが期待する入力の型を指定します（オプション）。
|
||||
- `input_filter`：次のエージェントが受け取る入力をフィルタリングできます。詳細は後述します。
|
||||
|
||||
```python
|
||||
from agents import Agent, handoff, RunContextWrapper
|
||||
|
||||
def on_handoff(ctx: RunContextWrapper[None]):
|
||||
print("Handoff called")
|
||||
|
||||
agent = Agent(name="My agent")
|
||||
|
||||
handoff_obj = handoff(
|
||||
agent=agent,
|
||||
on_handoff=on_handoff,
|
||||
tool_name_override="custom_handoff_tool",
|
||||
tool_description_override="Custom description",
|
||||
)
|
||||
```
|
||||
|
||||
## ハンドオフの入力
|
||||
|
||||
特定の状況では、LLM がハンドオフを呼び出す際に何らかのデータを提供するようにしたい場合があります。例えば、「Escalation agent（エスカレーションエージェント）」へのハンドオフを考えると、ログ記録のために理由を提供してほしい場合があります。
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
|
||||
from agents import Agent, handoff, RunContextWrapper
|
||||
|
||||
class EscalationData(BaseModel):
|
||||
reason: str
|
||||
|
||||
async def on_handoff(ctx: RunContextWrapper[None], input_data: EscalationData):
|
||||
print(f"Escalation agent called with reason: {input_data.reason}")
|
||||
|
||||
agent = Agent(name="Escalation agent")
|
||||
|
||||
handoff_obj = handoff(
|
||||
agent=agent,
|
||||
on_handoff=on_handoff,
|
||||
input_type=EscalationData,
|
||||
)
|
||||
```
|
||||
|
||||
## 入力フィルター
|
||||
|
||||
ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、それまでの会話履歴全体を参照できるようになります。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] として受け取り、新しい `HandoffInputData` を返す関数です。
|
||||
|
||||
よくあるパターン（例えば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] にあらかじめ実装されています。
|
||||
|
||||
```python
|
||||
from agents import Agent, handoff
|
||||
from agents.extensions import handoff_filters
|
||||
|
||||
agent = Agent(name="FAQ agent")
|
||||
|
||||
handoff_obj = handoff(
|
||||
agent=agent,
|
||||
input_filter=handoff_filters.remove_all_tools, # (1)!
|
||||
)
|
||||
```
|
||||
|
||||
1. これにより、`FAQ agent` が呼び出された際に履歴からすべてのツールが自動的に削除されます。
|
||||
|
||||
## 推奨プロンプト
|
||||
|
||||
LLM がハンドオフを適切に理解できるようにするため、エージェントのプロンプトにハンドオフに関する情報を含めることを推奨します。推奨されるプレフィックスは [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に用意されています。または、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトに自動的に追加できます。
|
||||
|
||||
```python
|
||||
from agents import Agent
|
||||
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
|
||||
|
||||
billing_agent = Agent(
|
||||
name="Billing agent",
|
||||
instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
|
||||
<Fill in the rest of your prompt here>.""",
|
||||
)
|
||||
```
|
||||
52
docs/ja/index.md
Normal file
52
docs/ja/index.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
# OpenAI Agents SDK
|
||||
|
||||
[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、軽量で使いやすく、抽象化を最小限に抑えたエージェントベースの AI アプリケーションを構築できるようにします。これは、以前のエージェント実験である [Swarm](https://github.com/openai/swarm/tree/main) を本番環境向けにアップグレードしたものです。Agents SDK は非常に少数の基本コンポーネント（primitives）で構成されています。
|
||||
|
||||
- **エージェント** : instructions と tools を備えた LLM
|
||||
- **ハンドオフ** : 特定のタスクを他のエージェントに委任する仕組み
|
||||
- **ガードレール** : エージェントへの入力を検証する仕組み
|
||||
|
||||
これらの基本コンポーネントを Python と組み合わせることで、ツールとエージェント間の複雑な関係を表現でき、急な学習曲線なしに実世界のアプリケーションを構築できます。さらに SDK には、エージェントのフローを視覚化・デバッグし、評価やモデルのファインチューニングまで可能にする組み込みの **トレーシング** 機能が備わっています。
|
||||
|
||||
## Agents SDK を使う理由
|
||||
|
||||
SDK は以下の 2 つの設計原則に基づいています。
|
||||
|
||||
1. 利用価値のある十分な機能を備えつつ、迅速に習得できるよう基本コンポーネントを最小限に抑える。
|
||||
2. そのままでも優れた動作をするが、必要に応じて細かくカスタマイズ可能。
|
||||
|
||||
SDK の主な機能は以下の通りです。
|
||||
|
||||
- **エージェントループ** : ツールの呼び出し、LLM への実行結果の送信、LLM が完了するまでのループ処理を組み込みで提供。
|
||||
- **Python ファースト** : 新しい抽象化を学ぶ必要なく、Python の言語機能を使ってエージェントの連携やチェーンを構築可能。
|
||||
- **ハンドオフ** : 複数のエージェント間での調整やタスク委任を可能にする強力な機能。
|
||||
- **ガードレール** : エージェントと並行して入力の検証やチェックを実行し、チェックが失敗した場合は早期に処理を中断。
|
||||
- **関数ツール** : 任意の Python 関数をツールに変換し、自動的なスキーマ生成と Pydantic による検証を提供。
|
||||
- **トレーシング** : ワークフローの視覚化、デバッグ、モニタリングを可能にする組み込みのトレーシング機能。OpenAI が提供する評価、ファインチューニング、蒸留ツールも利用可能。
|
||||
|
||||
## インストール
|
||||
|
||||
```bash
|
||||
pip install openai-agents
|
||||
```
|
||||
|
||||
## Hello World の例
|
||||
|
||||
```python
|
||||
from agents import Agent, Runner
|
||||
|
||||
agent = Agent(name="Assistant", instructions="You are a helpful assistant")
|
||||
|
||||
result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
|
||||
print(result.final_output)
|
||||
|
||||
# Code within the code,
|
||||
# Functions calling themselves,
|
||||
# Infinite loop's dance.
|
||||
```
|
||||
|
||||
（_実行する場合は、環境変数 `OPENAI_API_KEY` を設定してください。_）
|
||||
|
||||
```bash
|
||||
export OPENAI_API_KEY=sk-...
|
||||
```
|
||||
59
docs/ja/mcp.md
Normal file
59
docs/ja/mcp.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
# Model context protocol (MCP)
|
||||
|
||||
[Model context protocol](https://modelcontextprotocol.io/introduction)（別名 MCP）は、LLM にツールやコンテキストを提供するための方法です。MCP のドキュメントから引用します：
|
||||
|
||||
> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP は AI アプリケーションにおける USB-C ポートのようなものです。USB-C がデバイスをさまざまな周辺機器やアクセサリに接続するための標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。
|
||||
|
||||
Agents SDK は MCP をサポートしています。これにより、さまざまな MCP サーバーを使用して、エージェントにツールを提供できます。
|
||||
|
||||
## MCP サーバー
|
||||
|
||||
現在、MCP の仕様では、使用するトランスポートメカニズムに基づいて 2 種類のサーバーが定義されています：
|
||||
|
||||
1. **stdio** サーバーはアプリケーションのサブプロセスとして実行されます。これらは「ローカル」で実行されると考えることができます。
|
||||
2. **HTTP over SSE** サーバーはリモートで実行されます。これらには URL を介して接続します。
|
||||
|
||||
これらのサーバーに接続するには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] および [`MCPServerSse`][agents.mcp.server.MCPServerSse] クラスを使用できます。
|
||||
|
||||
例えば、[公式 MCP ファイルシステムサーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)を使用する場合は以下のようになります：
|
||||
|
||||
```python
|
||||
async with MCPServerStdio(
|
||||
params={
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
|
||||
}
|
||||
) as server:
|
||||
tools = await server.list_tools()
|
||||
```
|
||||
|
||||
## MCP サーバーの使用方法
|
||||
|
||||
MCP サーバーはエージェントに追加できます。Agents SDK はエージェントが実行されるたびに MCP サーバーの `list_tools()` を呼び出します。これにより、LLM は MCP サーバーのツールを認識します。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を呼び出します。
|
||||
|
||||
```python
|
||||
agent=Agent(
|
||||
name="Assistant",
|
||||
instructions="Use the tools to achieve the task",
|
||||
mcp_servers=[mcp_server_1, mcp_server_2]
|
||||
)
|
||||
```
|
||||
|
||||
## キャッシュ
|
||||
|
||||
エージェントが実行されるたびに、MCP サーバーの `list_tools()` が呼び出されます。特にサーバーがリモートの場合、これはレイテンシの原因となる可能性があります。ツールのリストを自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] と [`MCPServerSse`][agents.mcp.server.MCPServerSse] の両方に `cache_tools_list=True` を渡します。これは、ツールのリストが変更されないことが確実な場合にのみ行ってください。
|
||||
|
||||
キャッシュを無効化したい場合は、サーバーの `invalidate_tools_cache()` を呼び出します。
|
||||
|
||||
## エンドツーエンドのコード例
|
||||
|
||||
完全な動作コード例については、[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) を参照してください。
|
||||
|
||||
## トレーシング
|
||||
|
||||
[トレーシング](./tracing.md) は、以下を含む MCP 操作を自動的にキャプチャします：
|
||||
|
||||
1. MCP サーバーへのツール一覧取得の呼び出し
|
||||
2. 関数呼び出しに関する MCP 関連情報
|
||||
|
||||
|
||||
93
docs/ja/models.md
Normal file
93
docs/ja/models.md
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
# モデル
|
||||
|
||||
Agents SDK は、OpenAI モデルを以下の 2 種類の形式で標準サポートしています。
|
||||
|
||||
- **推奨** : 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出す [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]
|
||||
- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出す [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]
|
||||
|
||||
## モデルの混在と組み合わせ
|
||||
|
||||
単一のワークフロー内で、各エージェントごとに異なるモデルを使用したい場合があります。例えば、トリアージには小型で高速なモデルを使用し、複雑なタスクにはより大きく高性能なモデルを使用することができます。[`Agent`][agents.Agent] を設定する際、以下のいずれかの方法で特定のモデルを選択できます。
|
||||
|
||||
1. OpenAI モデルの名前を直接指定する。
|
||||
2. 任意のモデル名と、その名前をモデルインスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を指定する。
|
||||
3. [`Model`][agents.models.interface.Model] 実装を直接指定する。
|
||||
|
||||
!!! note
|
||||
|
||||
SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形式をサポートしていますが、各ワークフローでは単一のモデル形式を使用することを推奨します。これは、2 つの形式が異なる機能やツールをサポートしているためです。ワークフローで複数のモデル形式を混在させる必要がある場合は、使用するすべての機能が両方の形式で利用可能であることを確認してください。
|
||||
|
||||
```python
|
||||
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
|
||||
import asyncio
|
||||
|
||||
spanish_agent = Agent(
|
||||
name="Spanish agent",
|
||||
instructions="You only speak Spanish.",
|
||||
model="o3-mini", # (1)!
|
||||
)
|
||||
|
||||
english_agent = Agent(
|
||||
name="English agent",
|
||||
instructions="You only speak English",
|
||||
model=OpenAIChatCompletionsModel( # (2)!
|
||||
model="gpt-4o",
|
||||
openai_client=AsyncOpenAI()
|
||||
),
|
||||
)
|
||||
|
||||
triage_agent = Agent(
|
||||
name="Triage agent",
|
||||
instructions="Handoff to the appropriate agent based on the language of the request.",
|
||||
handoffs=[spanish_agent, english_agent],
|
||||
model="gpt-3.5-turbo",
|
||||
)
|
||||
|
||||
async def main():
|
||||
result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
1. OpenAI モデルの名前を直接指定しています。
|
||||
2. [`Model`][agents.models.interface.Model] 実装を指定しています。
|
||||
|
||||
## 他の LLM プロバイダーの使用
|
||||
|
||||
他の LLM プロバイダーを使用するには、以下の 3 つの方法があります（コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。
|
||||
|
||||
1. [`set_default_openai_client`][agents.set_default_openai_client] は、グローバルに `AsyncOpenAI` インスタンスを LLM クライアントとして使用したい場合に便利です。これは、LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に使用します。設定可能なコード例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。
|
||||
2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより、「この実行におけるすべてのエージェントにカスタムモデルプロバイダーを使用する」と指定できます。設定可能なコード例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。
|
||||
3. [`Agent.model`][agents.agent.Agent.model] は特定のエージェントインスタンスにモデルを指定できます。これにより、異なるエージェントに異なるプロバイダーを組み合わせて使用できます。設定可能なコード例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。
|
||||
|
||||
`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` を使用してトレーシングを無効化するか、[別のトレーシングプロセッサ](tracing.md) を設定することを推奨します。
|
||||
|
||||
!!! note
|
||||
|
||||
これらのコード例では Chat Completions API / モデルを使用しています。これは、多くの LLM プロバイダーがまだ Responses API をサポートしていないためです。使用する LLM プロバイダーが Responses API をサポートしている場合は、Responses の使用を推奨します。
|
||||
|
||||
## 他の LLM プロバイダー使用時の一般的な問題
|
||||
|
||||
### トレーシングクライアントのエラー 401
|
||||
|
||||
トレーシングに関連するエラーが発生する場合、これはトレースが OpenAI サーバーにアップロードされるためであり、OpenAI API キーを持っていないことが原因です。解決方法は以下の 3 つです。
|
||||
|
||||
1. トレーシングを完全に無効化する : [`set_tracing_disabled(True)`][agents.set_tracing_disabled]
|
||||
2. トレーシング用に OpenAI キーを設定する : [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) から取得する必要があります。
|
||||
3. OpenAI 以外のトレースプロセッサを使用する : 詳細は [トレーシングドキュメント](tracing.md#custom-tracing-processors) を参照してください。
|
||||
|
||||
### Responses API のサポート
|
||||
|
||||
SDK はデフォルトで Responses API を使用しますが、多くの他の LLM プロバイダーはまだこれをサポートしていません。そのため、404 エラーなどが発生する場合があります。解決方法は以下の 2 つです。
|
||||
|
||||
1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に有効です。
|
||||
2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) を参照してください。
|
||||
|
||||
### structured outputs のサポート
|
||||
|
||||
一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。そのため、以下のようなエラーが発生する場合があります。
|
||||
|
||||
```
|
||||
BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' : value is not one of the allowed values ['text','json_object']", 'type': 'invalid_request_error'}}
|
||||
```
|
||||
|
||||
これは一部のモデルプロバイダーの制限であり、JSON 出力はサポートしていますが、出力に使用する `json_schema` を指定できないためです。この問題への対応を進めていますが、現時点では JSON スキーマ出力をサポートするプロバイダーを使用することを推奨します。そうでない場合、アプリケーションが不適切な JSON により頻繁に破損する可能性があります。
|
||||
37
docs/ja/multi_agent.md
Normal file
37
docs/ja/multi_agent.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
# 複数のエージェントのオーケストレーション
|
||||
|
||||
オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントがどの順序で実行され、次に何を行うかをどのように決定するかを意味します。エージェントをオーケストレーションする主な方法は 2 つあります。
|
||||
|
||||
1. LLM に判断を任せる方法：LLM の知性を利用して計画、推論を行い、それに基づいて次のステップを決定します。
|
||||
2. コードによるオーケストレーション：コードを通じてエージェントの流れを決定します。
|
||||
|
||||
これらのパターンは組み合わせて使用することも可能です。それぞれのトレードオフについて以下で説明します。
|
||||
|
||||
## LLM によるオーケストレーション
|
||||
|
||||
エージェントとは、LLM に instructions、tools、handoffs を与えたものです。これにより、自由度の高いタスクを与えられた場合でも、LLM は自律的にタスクの取り組み方を計画し、tools を使ってアクションを実行したりデータを取得したり、handoffs を使ってサブエージェントにタスクを委任したりできます。例えば、調査エージェントには以下のようなツールを装備できます。
|
||||
|
||||
- Web 検索：オンラインで情報を検索
|
||||
- ファイル検索と取得：独自データや接続先から情報を検索
|
||||
- コンピュータ操作：コンピュータ上でアクションを実行
|
||||
- コード実行：データ分析を実施
|
||||
- ハンドオフ：計画立案やレポート作成などに特化したエージェントにタスクを委任
|
||||
|
||||
このパターンは、自由度の高いタスクで LLM の知性に頼りたい場合に適しています。ここで重要な戦術は以下の通りです。
|
||||
|
||||
1. 良質なプロンプトに投資する。利用可能なツール、使用方法、動作パラメータを明確にする。
|
||||
2. アプリを監視し、繰り返し改善する。問題が発生した箇所を特定し、プロンプトを改善する。
|
||||
3. エージェントが自己内省し改善できるようにする。例えばループ内で実行し、自らを批評させたり、エラーメッセージを与えて改善させたりする。
|
||||
4. 汎用的なエージェントにあらゆるタスクを任せるのではなく、特定のタスクに秀でた専門エージェントを用意する。
|
||||
5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスクの遂行能力を向上させることができる。
|
||||
|
||||
## コードによるオーケストレーション
|
||||
|
||||
LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度、コスト、パフォーマンスの観点でより決定論的で予測可能になります。ここでの一般的なパターンは以下の通りです。
|
||||
|
||||
- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用して、コードで検査可能な適切な形式のデータを生成する。例えば、エージェントにタスクをいくつかのカテゴリに分類させ、そのカテゴリに基づいて次のエージェントを選択することができます。
|
||||
- 複数のエージェントを連鎖させ、一つのエージェントの出力を次のエージェントの入力に変換する。例えばブログ記事を書くというタスクを、調査、アウトライン作成、記事執筆、批評、改善という一連のステップに分解できます。
|
||||
- タスクを実行するエージェントを、評価とフィードバックを行うエージェントと共に `while` ループ内で実行し、評価エージェントが出力が一定の基準を満たすと判断するまで繰り返します。
|
||||
- 複数のエージェントを並列で実行する。例えば Python の基本コンポーネント (`asyncio.gather` など) を使用します。これは、互いに依存しない複数のタスクを高速に処理する場合に有効です。
|
||||
|
||||
[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数のコード例があります。
|
||||
188
docs/ja/quickstart.md
Normal file
188
docs/ja/quickstart.md
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
# クイックスタート
|
||||
|
||||
## プロジェクトと仮想環境の作成
|
||||
|
||||
以下の操作は一度だけ行います。
|
||||
|
||||
```bash
|
||||
mkdir my_project
|
||||
cd my_project
|
||||
python -m venv .venv
|
||||
```
|
||||
|
||||
### 仮想環境の有効化
|
||||
|
||||
新しいターミナルセッションを開始するたびに、この操作を行います。
|
||||
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
### Agents SDK のインストール
|
||||
|
||||
```bash
|
||||
pip install openai-agents # または `uv add openai-agents` など
|
||||
```
|
||||
|
||||
### OpenAI API キーの設定
|
||||
|
||||
API キーをお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。
|
||||
|
||||
```bash
|
||||
export OPENAI_API_KEY=sk-...
|
||||
```
|
||||
|
||||
## 最初のエージェントの作成
|
||||
|
||||
エージェント は、 instructions 、名前、およびオプションの設定（ `model_config` など）で定義します。
|
||||
|
||||
```python
|
||||
from agents import Agent
|
||||
|
||||
agent = Agent(
|
||||
name="Math Tutor",
|
||||
instructions="You provide help with math problems. Explain your reasoning at each step and include examples",
|
||||
)
|
||||
```
|
||||
|
||||
## さらに複数のエージェントを追加する
|
||||
|
||||
追加のエージェントも同様に定義できます。 `handoff_description` は、ハンドオフのルーティングを決定するための追加のコンテキストを提供します。
|
||||
|
||||
```python
|
||||
from agents import Agent
|
||||
|
||||
history_tutor_agent = Agent(
|
||||
name="History Tutor",
|
||||
handoff_description="Specialist agent for historical questions",
|
||||
instructions="You provide assistance with historical queries. Explain important events and context clearly.",
|
||||
)
|
||||
|
||||
math_tutor_agent = Agent(
|
||||
name="Math Tutor",
|
||||
handoff_description="Specialist agent for math questions",
|
||||
instructions="You provide help with math problems. Explain your reasoning at each step and include examples",
|
||||
)
|
||||
```
|
||||
|
||||
## ハンドオフの定義
|
||||
|
||||
各エージェントに対して、タスクを進める方法を決定するために選択可能なハンドオフのオプションを定義できます。
|
||||
|
||||
```python
|
||||
triage_agent = Agent(
|
||||
name="Triage Agent",
|
||||
instructions="You determine which agent to use based on the user's homework question",
|
||||
handoffs=[history_tutor_agent, math_tutor_agent]
|
||||
)
|
||||
```
|
||||
|
||||
## エージェントのオーケストレーションを実行する
|
||||
|
||||
ワークフローが正しく動作し、トリアージエージェントが 2 つの専門エージェント間で適切にルーティングすることを確認しましょう。
|
||||
|
||||
```python
|
||||
from agents import Runner
|
||||
|
||||
async def main():
|
||||
result = await Runner.run(triage_agent, "What is the capital of France?")
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
## ガードレールの追加
|
||||
|
||||
入力または出力に対して実行するカスタムのガードレールを定義できます。
|
||||
|
||||
```python
|
||||
from agents import GuardrailFunctionOutput, Agent, Runner
|
||||
from pydantic import BaseModel
|
||||
|
||||
class HomeworkOutput(BaseModel):
|
||||
is_homework: bool
|
||||
reasoning: str
|
||||
|
||||
guardrail_agent = Agent(
|
||||
name="Guardrail check",
|
||||
instructions="Check if the user is asking about homework.",
|
||||
output_type=HomeworkOutput,
|
||||
)
|
||||
|
||||
async def homework_guardrail(ctx, agent, input_data):
|
||||
result = await Runner.run(guardrail_agent, input_data, context=ctx.context)
|
||||
final_output = result.final_output_as(HomeworkOutput)
|
||||
return GuardrailFunctionOutput(
|
||||
output_info=final_output,
|
||||
tripwire_triggered=not final_output.is_homework,
|
||||
)
|
||||
```
|
||||
|
||||
## すべてを統合する
|
||||
|
||||
ハンドオフと入力ガードレールを使用して、ワークフロー全体を統合して実行しましょう。
|
||||
|
||||
```python
|
||||
from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner
|
||||
from pydantic import BaseModel
|
||||
import asyncio
|
||||
|
||||
class HomeworkOutput(BaseModel):
|
||||
is_homework: bool
|
||||
reasoning: str
|
||||
|
||||
guardrail_agent = Agent(
|
||||
name="Guardrail check",
|
||||
instructions="Check if the user is asking about homework.",
|
||||
output_type=HomeworkOutput,
|
||||
)
|
||||
|
||||
math_tutor_agent = Agent(
|
||||
name="Math Tutor",
|
||||
handoff_description="Specialist agent for math questions",
|
||||
instructions="You provide help with math problems. Explain your reasoning at each step and include examples",
|
||||
)
|
||||
|
||||
history_tutor_agent = Agent(
|
||||
name="History Tutor",
|
||||
handoff_description="Specialist agent for historical questions",
|
||||
instructions="You provide assistance with historical queries. Explain important events and context clearly.",
|
||||
)
|
||||
|
||||
async def homework_guardrail(ctx, agent, input_data):
|
||||
result = await Runner.run(guardrail_agent, input_data, context=ctx.context)
|
||||
final_output = result.final_output_as(HomeworkOutput)
|
||||
return GuardrailFunctionOutput(
|
||||
output_info=final_output,
|
||||
tripwire_triggered=not final_output.is_homework,
|
||||
)
|
||||
|
||||
triage_agent = Agent(
|
||||
name="Triage Agent",
|
||||
instructions="You determine which agent to use based on the user's homework question",
|
||||
handoffs=[history_tutor_agent, math_tutor_agent],
|
||||
input_guardrails=[
|
||||
InputGuardrail(guardrail_function=homework_guardrail),
|
||||
],
|
||||
)
|
||||
|
||||
async def main():
|
||||
result = await Runner.run(triage_agent, "who was the first president of the united states?")
|
||||
print(result.final_output)
|
||||
|
||||
result = await Runner.run(triage_agent, "what is life")
|
||||
print(result.final_output)
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## トレースの確認
|
||||
|
||||
エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードのトレースビューア](https://platform.openai.com/traces) にアクセスして、エージェント実行のトレースを確認してください。
|
||||
|
||||
## 次のステップ
|
||||
|
||||
より複雑なエージェントフローの構築方法を学びましょう。
|
||||
|
||||
- [エージェント](agents.md) の設定方法について学ぶ。
|
||||
- [エージェントの実行方法](running_agents.md) について学ぶ。
|
||||
- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models.md) について学ぶ。
|
||||
52
docs/ja/results.md
Normal file
52
docs/ja/results.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
# 実行結果
|
||||
|
||||
`Runner.run` メソッドを呼び出すと、以下のいずれかが返されます。
|
||||
|
||||
- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult]
|
||||
- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming]
|
||||
|
||||
これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれています。
|
||||
|
||||
## 最終出力
|
||||
|
||||
[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が格納されています。これは以下のいずれかです。
|
||||
|
||||
- 最後のエージェントに `output_type` が定義されていない場合は `str`
|
||||
- エージェントに `output_type` が定義されている場合は、その型（`last_agent.output_type`）のオブジェクト
|
||||
|
||||
!!! note
|
||||
|
||||
`final_output` は型としては `Any` です。これはハンドオフが発生する可能性があるため、静的に型付けできないためです。ハンドオフが発生すると、どのエージェントでも最後のエージェントになり得るため、可能な出力型の集合を静的に特定できません。
|
||||
|
||||
## 次のターンの入力
|
||||
|
||||
[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使用すると、実行結果を入力リストに変換できます。これは、元々提供した入力とエージェントの実行中に生成された項目を連結したものです。これにより、あるエージェントの実行結果を別の実行に渡したり、ループ内で実行して毎回新しいユーザー入力を追加したりすることが容易になります。
|
||||
|
||||
## 最後のエージェント
|
||||
|
||||
[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが格納されています。アプリケーションによっては、次回ユーザーが何かを入力する際に役立つことがあります。例えば、最前線のトリアージエージェントが言語特化型エージェントにハンドオフする場合、最後のエージェントを保存しておき、次回ユーザーがエージェントにメッセージを送る際に再利用できます。
|
||||
|
||||
## 新規項目
|
||||
|
||||
[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しい項目が格納されています。これらの項目は [`RunItem`][agents.items.RunItem] です。RunItem は LLM によって生成された raw 項目をラップしています。
|
||||
|
||||
- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw 項目は生成されたメッセージです。
|
||||
- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフツールを呼び出したことを示します。raw 項目は LLM からのツール呼び出し項目です。
|
||||
- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。raw 項目はハンドオフツール呼び出しに対するツールの応答です。また、この項目からソース／ターゲットエージェントにアクセスできます。
|
||||
- [`ToolCallItem`][agents.items.ToolCallItem] は LLM がツールを呼び出したことを示します。
|
||||
- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが呼び出されたことを示します。raw 項目はツールの応答です。また、この項目からツールの出力にアクセスできます。
|
||||
- [`ReasoningItem`][agents.items.ReasoningItem] は LLM による推論項目を示します。raw 項目は生成された推論内容です。
|
||||
|
||||
## その他の情報
|
||||
|
||||
### ガードレールの実行結果
|
||||
|
||||
[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] および [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの実行結果が格納されています（存在する場合）。ガードレールの実行結果にはログや保存したい有用な情報が含まれることがあるため、これらを利用可能にしています。
|
||||
|
||||
### raw レスポンス
|
||||
|
||||
[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が格納されています。
|
||||
|
||||
### 元の入力
|
||||
|
||||
[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに提供した元の入力が格納されています。ほとんどの場合、これは必要ありませんが、必要に応じて利用可能です。
|
||||
95
docs/ja/running_agents.md
Normal file
95
docs/ja/running_agents.md
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
# エージェントの実行
|
||||
|
||||
エージェントは [`Runner`][agents.run.Runner] クラスを通じて実行できます。以下の 3 つの方法があります。
|
||||
|
||||
1. [`Runner.run()`][agents.run.Runner.run]：非同期で実行され、[`RunResult`][agents.result.RunResult] を返します。
|
||||
2. [`Runner.run_sync()`][agents.run.Runner.run_sync]：同期メソッドで、内部的には `.run()` を呼び出します。
|
||||
3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]：非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントを順次ストリームします。
|
||||
|
||||
```python
|
||||
from agents import Agent, Runner
|
||||
|
||||
async def main():
|
||||
agent = Agent(name="Assistant", instructions="You are a helpful assistant")
|
||||
|
||||
result = await Runner.run(agent, "Write a haiku about recursion in programming.")
|
||||
print(result.final_output)
|
||||
# Code within the code,
|
||||
# Functions calling themselves,
|
||||
# Infinite loop's dance.
|
||||
```
|
||||
|
||||
詳細は [results ガイド](results.md) を参照してください。
|
||||
|
||||
## エージェントの実行ループ
|
||||
|
||||
`Runner` の run メソッドを使用する際、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージとして扱われる）または OpenAI Responses API の項目リストのいずれかです。
|
||||
|
||||
Runner は以下のループを実行します。
|
||||
|
||||
1. 現在のエージェントと入力を用いて LLM を呼び出します。
|
||||
2. LLM が出力を生成します。
|
||||
1. LLM が `final_output` を返した場合、ループを終了し結果を返します。
|
||||
2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、再度ループを実行します。
|
||||
3. LLM がツール呼び出しを生成した場合、それらのツール呼び出しを実行し、結果を追加して再度ループを実行します。
|
||||
3. 指定された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を発生させます。
|
||||
|
||||
!!! note
|
||||
|
||||
LLM の出力が「最終出力（final output）」とみなされる条件は、望ましいタイプのテキスト出力を生成し、かつツール呼び出しがない場合です。
|
||||
|
||||
## ストリーミング
|
||||
|
||||
ストリーミングを使用すると、LLM の実行中にストリーミングイベントを受け取ることができます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に実行に関する完全な情報（生成されたすべての新しい出力を含む）が格納されます。ストリーミングイベントを取得するには `.stream_events()` を呼び出します。詳細は [streaming ガイド](streaming.md) を参照してください。
|
||||
|
||||
## 実行設定（Run config）
|
||||
|
||||
`run_config` パラメータを使用すると、エージェント実行時のグローバル設定を構成できます。
|
||||
|
||||
- [`model`][agents.run.RunConfig.model]：各エージェントの `model` 設定に関係なく、グローバルな LLM モデルを指定します。
|
||||
- [`model_provider`][agents.run.RunConfig.model_provider]：モデル名を検索するためのモデルプロバイダーを指定します（デフォルトは OpenAI）。
|
||||
- [`model_settings`][agents.run.RunConfig.model_settings]：エージェント固有の設定を上書きします。例えば、グローバルな `temperature` や `top_p` を設定できます。
|
||||
- [`input_guardrails`][agents.run.RunConfig.input_guardrails]、[`output_guardrails`][agents.run.RunConfig.output_guardrails]：すべての実行に適用する入力または出力のガードレールのリストです。
|
||||
- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]：ハンドオフに既存の入力フィルターがない場合に適用されるグローバルな入力フィルターです。入力フィルターを使用すると、新しいエージェントに送信される入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。
|
||||
- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]：実行全体の [トレーシング](tracing.md) を無効にします。
|
||||
- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]：トレースに LLM やツール呼び出しの入出力など、機密性の高いデータを含めるかどうかを設定します。
|
||||
- [`workflow_name`][agents.run.RunConfig.workflow_name]、[`trace_id`][agents.run.RunConfig.trace_id]、[`group_id`][agents.run.RunConfig.group_id]：トレーシングのワークフロー名、トレース ID、トレースグループ ID を設定します。少なくとも `workflow_name` を設定することを推奨します。グループ ID はオプションで、複数の実行間でトレースを関連付けることができます。
|
||||
- [`trace_metadata`][agents.run.RunConfig.trace_metadata]：すべてのトレースに含めるメタデータです。
|
||||
|
||||
## 会話／チャットスレッド
|
||||
|
||||
いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行され（したがって 1 つ以上の LLM 呼び出しが発生）、チャット会話における単一の論理的ターンを表します。例えば：
|
||||
|
||||
1. ユーザーのターン：ユーザーがテキストを入力
|
||||
2. Runner の実行：最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントにハンドオフし、2 番目のエージェントがさらにツールを実行して出力を生成
|
||||
|
||||
エージェントの実行終了時に、ユーザーに何を表示するかを選択できます。例えば、エージェントが生成したすべての新しい項目を表示するか、最終出力のみを表示するかを選択できます。いずれの場合も、ユーザーが追加の質問をした場合、再度 run メソッドを呼び出します。
|
||||
|
||||
次のターンの入力を取得するには、基本クラスの [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用できます。
|
||||
|
||||
```python
|
||||
async def main():
|
||||
agent = Agent(name="Assistant", instructions="Reply very concisely.")
|
||||
|
||||
with trace(workflow_name="Conversation", group_id=thread_id):
|
||||
# First turn
|
||||
result = await Runner.run(agent, "What city is the Golden Gate Bridge in?")
|
||||
print(result.final_output)
|
||||
# San Francisco
|
||||
|
||||
# Second turn
|
||||
new_input = result.to_input_list() + [{"role": "user", "content": "What state is it in?"}]
|
||||
result = await Runner.run(agent, new_input)
|
||||
print(result.final_output)
|
||||
# California
|
||||
```
|
||||
|
||||
## 例外
|
||||
|
||||
SDK は特定の状況で例外を発生させます。完全なリストは [`agents.exceptions`][] にあります。概要は以下の通りです。
|
||||
|
||||
- [`AgentsException`][agents.exceptions.AgentsException]：SDK 内で発生するすべての例外の基底クラスです。
|
||||
- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]：実行が指定された `max_turns` を超えた場合に発生します。
|
||||
- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：モデルが不正な出力（不正な JSON や存在しないツールの使用など）を生成した場合に発生します。
|
||||
- [`UserError`][agents.exceptions.UserError]：SDK を使用するコードに誤りがある場合に発生します。
|
||||
- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered]、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]：[ガードレール](guardrails.md) がトリガーされた場合に発生します。
|
||||
87
docs/ja/streaming.md
Normal file
87
docs/ja/streaming.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
# ストリーミング
|
||||
|
||||
ストリーミングを使用すると、エージェントの実行中にその進行状況の更新を購読できます。これは、エンドユーザーに進捗状況や部分的な応答を表示する際に役立ちます。
|
||||
|
||||
ストリーミングを行うには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。
|
||||
|
||||
## raw response events
|
||||
|
||||
[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API の形式であり、各イベントはタイプ（`response.created` や `response.output_text.delta` など）とデータを持ちます。これらのイベントは、生成された応答メッセージを即座にユーザーにストリーミングしたい場合に役立ちます。
|
||||
|
||||
例えば、以下のコードは LLM が生成したテキストをトークンごとに出力します。
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from openai.types.responses import ResponseTextDeltaEvent
|
||||
from agents import Agent, Runner
|
||||
|
||||
async def main():
|
||||
agent = Agent(
|
||||
name="Joker",
|
||||
instructions="You are a helpful assistant.",
|
||||
)
|
||||
|
||||
result = Runner.run_streamed(agent, input="Please tell me 5 jokes.")
|
||||
async for event in result.stream_events():
|
||||
if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
|
||||
print(event.data.delta, end="", flush=True)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## Run item events と agent events
|
||||
|
||||
[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。これらはアイテムが完全に生成された際に通知されます。これにより、トークン単位ではなく、「メッセージが生成された」「ツールが実行された」などのレベルで進捗状況をユーザーに通知できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更された際（例えばハンドオフの結果として）に更新を通知します。
|
||||
|
||||
例えば、以下のコードは raw イベントを無視し、更新情報のみをユーザーにストリーミングします。
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import random
|
||||
from agents import Agent, ItemHelpers, Runner, function_tool
|
||||
|
||||
@function_tool
|
||||
def how_many_jokes() -> int:
|
||||
return random.randint(1, 10)
|
||||
|
||||
|
||||
async def main():
|
||||
agent = Agent(
|
||||
name="Joker",
|
||||
instructions="First call the `how_many_jokes` tool, then tell that many jokes.",
|
||||
tools=[how_many_jokes],
|
||||
)
|
||||
|
||||
result = Runner.run_streamed(
|
||||
agent,
|
||||
input="Hello",
|
||||
)
|
||||
print("=== Run starting ===")
|
||||
|
||||
async for event in result.stream_events():
|
||||
# raw response イベントのデルタは無視します
|
||||
if event.type == "raw_response_event":
|
||||
continue
|
||||
# エージェントが更新された場合、それを表示します
|
||||
elif event.type == "agent_updated_stream_event":
|
||||
print(f"Agent updated: {event.new_agent.name}")
|
||||
continue
|
||||
# アイテムが生成された場合、それを表示します
|
||||
elif event.type == "run_item_stream_event":
|
||||
if event.item.type == "tool_call_item":
|
||||
print("-- Tool was called")
|
||||
elif event.item.type == "tool_call_output_item":
|
||||
print(f"-- Tool output: {event.item.output}")
|
||||
elif event.item.type == "message_output_item":
|
||||
print(f"-- Message output:\n {ItemHelpers.text_message_output(event.item)}")
|
||||
else:
|
||||
pass # 他のイベントタイプは無視します
|
||||
|
||||
print("=== Run complete ===")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
269
docs/ja/tools.md
Normal file
269
docs/ja/tools.md
Normal file
|
|
@ -0,0 +1,269 @@
|
|||
# ツール
|
||||
|
||||
ツールを使用すると、エージェントがデータ取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作などのアクションを実行できます。Agents SDK には以下の 3 種類のツールがあります。
|
||||
|
||||
- ホスト型ツール：AI モデルと共に LLM サーバー上で実行されます。OpenAI は、検索、ウェブ検索、コンピュータ操作をホスト型ツール（OpenAI がホストするツール）として提供しています。
|
||||
- 関数呼び出し：任意の Python 関数をツールとして使用できます。
|
||||
- エージェントをツールとして使用：エージェントをツールとして使用でき、エージェント間でハンドオフを行わずに他のエージェントを呼び出せます。
|
||||
|
||||
## ホスト型ツール
|
||||
|
||||
[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合、OpenAI はいくつかの組み込みツールを提供しています。
|
||||
|
||||
- [`WebSearchTool`][agents.tool.WebSearchTool] は、エージェントがウェブ検索を行うためのツールです。
|
||||
- [`FileSearchTool`][agents.tool.FileSearchTool] は、OpenAI のベクトルストアから情報を取得するためのツールです。
|
||||
- [`ComputerTool`][agents.tool.ComputerTool] は、コンピュータ操作タスクを自動化するためのツールです。
|
||||
|
||||
```python
|
||||
from agents import Agent, FileSearchTool, Runner, WebSearchTool
|
||||
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
tools=[
|
||||
WebSearchTool(),
|
||||
FileSearchTool(
|
||||
max_num_results=3,
|
||||
vector_store_ids=["VECTOR_STORE_ID"],
|
||||
),
|
||||
],
|
||||
)
|
||||
|
||||
async def main():
|
||||
result = await Runner.run(agent, "Which coffee shop should I go to, taking into account my preferences and the weather today in SF?")
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
## 関数ツール
|
||||
|
||||
任意の Python 関数をツールとして使用できます。Agents SDK は自動的にツールを設定します。
|
||||
|
||||
- ツール名は Python 関数名が使用されます（または任意の名前を指定可能）。
|
||||
- ツールの説明は関数の docstring から取得されます（または任意の説明を指定可能）。
|
||||
- 関数の入力スキーマは関数の引数から自動的に作成されます。
|
||||
- 各入力の説明は、無効化されていない限り、関数の docstring から取得されます。
|
||||
|
||||
Python の `inspect` モジュールを使用して関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) を使用して docstring を解析し、`pydantic` を使用してスキーマを作成します。
|
||||
|
||||
```python
|
||||
import json
|
||||
|
||||
from typing_extensions import TypedDict, Any
|
||||
|
||||
from agents import Agent, FunctionTool, RunContextWrapper, function_tool
|
||||
|
||||
|
||||
class Location(TypedDict):
|
||||
lat: float
|
||||
long: float
|
||||
|
||||
@function_tool # (1)!
|
||||
async def fetch_weather(location: Location) -> str:
|
||||
# (2)!
|
||||
"""Fetch the weather for a given location.
|
||||
|
||||
Args:
|
||||
location: The location to fetch the weather for.
|
||||
"""
|
||||
# In real life, we'd fetch the weather from a weather API
|
||||
return "sunny"
|
||||
|
||||
|
||||
@function_tool(name_override="fetch_data") # (3)!
|
||||
def read_file(ctx: RunContextWrapper[Any], path: str, directory: str | None = None) -> str:
|
||||
"""Read the contents of a file.
|
||||
|
||||
Args:
|
||||
path: The path to the file to read.
|
||||
directory: The directory to read the file from.
|
||||
"""
|
||||
# In real life, we'd read the file from the file system
|
||||
return "<file contents>"
|
||||
|
||||
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
tools=[fetch_weather, read_file], # (4)!
|
||||
)
|
||||
|
||||
for tool in agent.tools:
|
||||
if isinstance(tool, FunctionTool):
|
||||
print(tool.name)
|
||||
print(tool.description)
|
||||
print(json.dumps(tool.params_json_schema, indent=2))
|
||||
print()
|
||||
|
||||
```
|
||||
|
||||
1. 任意の Python 型を関数の引数として使用可能で、関数は同期または非同期のどちらでも構いません。
|
||||
2. docstring が存在する場合、ツールおよび引数の説明として使用されます。
|
||||
3. 関数はオプションで `context` を引数として受け取れます（最初の引数である必要があります）。また、ツール名や説明、docstring のスタイルなどを上書き設定できます。
|
||||
4. デコレータを付けた関数をツールのリストに渡すことができます。
|
||||
|
||||
??? note "クリックして出力を表示"
|
||||
|
||||
```
|
||||
fetch_weather
|
||||
Fetch the weather for a given location.
|
||||
{
|
||||
"$defs": {
|
||||
"Location": {
|
||||
"properties": {
|
||||
"lat": {
|
||||
"title": "Lat",
|
||||
"type": "number"
|
||||
},
|
||||
"long": {
|
||||
"title": "Long",
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"lat",
|
||||
"long"
|
||||
],
|
||||
"title": "Location",
|
||||
"type": "object"
|
||||
}
|
||||
},
|
||||
"properties": {
|
||||
"location": {
|
||||
"$ref": "#/$defs/Location",
|
||||
"description": "The location to fetch the weather for."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"location"
|
||||
],
|
||||
"title": "fetch_weather_args",
|
||||
"type": "object"
|
||||
}
|
||||
|
||||
fetch_data
|
||||
Read the contents of a file.
|
||||
{
|
||||
"properties": {
|
||||
"path": {
|
||||
"description": "The path to the file to read.",
|
||||
"title": "Path",
|
||||
"type": "string"
|
||||
},
|
||||
"directory": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"default": null,
|
||||
"description": "The directory to read the file from.",
|
||||
"title": "Directory"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"path"
|
||||
],
|
||||
"title": "fetch_data_args",
|
||||
"type": "object"
|
||||
}
|
||||
```
|
||||
### カスタム関数ツール
|
||||
|
||||
Python 関数をツールとして使用したくない場合もあります。その場合は、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。作成時には以下を指定する必要があります：
|
||||
|
||||
- `name`
|
||||
- `description`
|
||||
- 引数の JSON スキーマを示す `params_json_schema`
|
||||
- 非同期関数である `on_invoke_tool`（コンテキストと引数を JSON 文字列として受け取り、ツールの出力を文字列として返す必要があります）
|
||||
|
||||
```python
|
||||
from typing import Any
|
||||
|
||||
from pydantic import BaseModel
|
||||
|
||||
from agents import RunContextWrapper, FunctionTool
|
||||
|
||||
|
||||
|
||||
def do_some_work(data: str) -> str:
|
||||
return "done"
|
||||
|
||||
|
||||
class FunctionArgs(BaseModel):
|
||||
username: str
|
||||
age: int
|
||||
|
||||
|
||||
async def run_function(ctx: RunContextWrapper[Any], args: str) -> str:
|
||||
parsed = FunctionArgs.model_validate_json(args)
|
||||
return do_some_work(data=f"{parsed.username} is {parsed.age} years old")
|
||||
|
||||
|
||||
tool = FunctionTool(
|
||||
name="process_user",
|
||||
description="Processes extracted user data",
|
||||
params_json_schema=FunctionArgs.model_json_schema(),
|
||||
on_invoke_tool=run_function,
|
||||
)
|
||||
```
|
||||
|
||||
### 引数とドックストリングの自動解析
|
||||
|
||||
前述の通り、関数のシグネチャを自動的に解析してツールのスキーマを抽出し、ドックストリングを解析してツールおよび各引数の説明を抽出します。これに関する注意点は以下の通りです：
|
||||
|
||||
1. シグネチャの解析は `inspect` モジュールを使用して行われます。型アノテーションを用いて引数の型を把握し、動的に Pydantic モデルを構築して全体のスキーマを表現します。Python の基本型（basic components）、Pydantic モデル、TypedDict など、ほとんどの型をサポートしています。
|
||||
2. ドックストリングの解析には `griffe` を使用します。サポートされるドックストリング形式は `google`、`sphinx`、`numpy` です。ドックストリング形式は自動検出を試みますが、これはベストエフォートであり、`function_tool` 呼び出し時に明示的に指定することも可能です。また、`use_docstring_info` を `False` に設定することでドックストリングの解析を無効化できます。
|
||||
|
||||
スキーマ抽出のコードは [`agents.function_schema`][] にあります。
|
||||
|
||||
## ツールとしてのエージェント
|
||||
|
||||
一部のワークフローでは、制御をハンドオフするのではなく、中央のエージェントが専門化されたエージェントのネットワークを調整することが望ましい場合があります。このような場合、エージェントをツールとしてモデル化できます。
|
||||
|
||||
```python
|
||||
from agents import Agent, Runner
|
||||
import asyncio
|
||||
|
||||
spanish_agent = Agent(
|
||||
name="Spanish agent",
|
||||
instructions="You translate the user's message to Spanish",
|
||||
)
|
||||
|
||||
french_agent = Agent(
|
||||
name="French agent",
|
||||
instructions="You translate the user's message to French",
|
||||
)
|
||||
|
||||
orchestrator_agent = Agent(
|
||||
name="orchestrator_agent",
|
||||
instructions=(
|
||||
"You are a translation agent. You use the tools given to you to translate."
|
||||
"If asked for multiple translations, you call the relevant tools."
|
||||
),
|
||||
tools=[
|
||||
spanish_agent.as_tool(
|
||||
tool_name="translate_to_spanish",
|
||||
tool_description="Translate the user's message to Spanish",
|
||||
),
|
||||
french_agent.as_tool(
|
||||
tool_name="translate_to_french",
|
||||
tool_description="Translate the user's message to French",
|
||||
),
|
||||
],
|
||||
)
|
||||
|
||||
async def main():
|
||||
result = await Runner.run(orchestrator_agent, input="Say 'Hello, how are you?' in Spanish.")
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
## 関数ツールにおけるエラー処理
|
||||
|
||||
`@function_tool` を使用して関数ツールを作成する際、`failure_error_function` を渡すことができます。これはツール呼び出しがクラッシュした場合に、LLM にエラー応答を提供する関数です。
|
||||
|
||||
- デフォルト（何も渡さない場合）では、エラーが発生したことを LLM に通知する `default_tool_error_function` が実行されます。
|
||||
- 独自のエラー関数を渡した場合は、それが代わりに実行され、その応答が LLM に送信されます。
|
||||
- 明示的に `None` を渡した場合、ツール呼び出しのエラーは再度発生（re-raise）し、自分で処理する必要があります。この場合、モデルが無効な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などが発生します。
|
||||
|
||||
手動で `FunctionTool` オブジェクトを作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。
|
||||
102
docs/ja/tracing.md
Normal file
102
docs/ja/tracing.md
Normal file
|
|
@ -0,0 +1,102 @@
|
|||
# トレーシング
|
||||
|
||||
Agents SDK には組み込みのトレーシング機能があり、エージェントの実行中に発生するイベント（LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで）を包括的に記録します。[Traces ダッシュボード](https://platform.openai.com/traces) を使用して、開発中および本番環境でワークフローのデバッグ、可視化、監視が可能です。
|
||||
|
||||
!!!note
|
||||
|
||||
トレーシングはデフォルトで有効になっています。トレーシングを無効にする方法は 2 つあります。
|
||||
|
||||
1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化できます。
|
||||
2. 個別の実行でトレーシングを無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します。
|
||||
|
||||
***OpenAI の API を使用してゼロデータ保持（ZDR）ポリシーで運用している組織の場合、トレーシングは利用できません。***
|
||||
|
||||
## トレースとスパン
|
||||
|
||||
- **トレース（Traces）** は、ワークフローの単一のエンドツーエンド操作を表します。トレースは複数のスパン（Spans）で構成されます。トレースには以下のプロパティがあります。
|
||||
- `workflow_name`：論理的なワークフローまたはアプリ名。例：「Code generation」や「Customer service」。
|
||||
- `trace_id`：トレースの一意な ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。
|
||||
- `group_id`：同じ会話からの複数のトレースを関連付けるためのオプションのグループ ID。例えば、チャットスレッド ID を使用できます。
|
||||
- `disabled`：True の場合、このトレースは記録されません。
|
||||
- `metadata`：トレースに関するオプションのメタデータ。
|
||||
- **スパン（Spans）** は、開始時刻と終了時刻を持つ操作を表します。スパンには以下が含まれます。
|
||||
- `started_at` と `ended_at` のタイムスタンプ。
|
||||
- 所属するトレースを示す `trace_id`。
|
||||
- 親スパンを指す `parent_id`（存在する場合）。
|
||||
- スパンに関する情報を含む `span_data`。例えば、`AgentSpanData` はエージェントに関する情報を、`GenerationSpanData` は LLM の生成に関する情報を含みます。
|
||||
|
||||
## デフォルトのトレーシング
|
||||
|
||||
デフォルトでは、SDK は以下をトレースします。
|
||||
|
||||
- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされます。
|
||||
- エージェントが実行されるたびに `agent_span()` でラップされます。
|
||||
- LLM の生成は `generation_span()` でラップされます。
|
||||
- 関数ツールの呼び出しはそれぞれ `function_span()` でラップされます。
|
||||
- ガードレールは `guardrail_span()` でラップされます。
|
||||
- ハンドオフは `handoff_span()` でラップされます。
|
||||
- 音声入力（音声からテキスト）は `transcription_span()` でラップされます。
|
||||
- 音声出力（テキストから音声）は `speech_span()` でラップされます。
|
||||
- 関連する音声スパンは `speech_group_span()` の下にまとめられる場合があります。
|
||||
|
||||
デフォルトでは、トレース名は「Agent trace」です。`trace` を使用する場合、この名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] を使用して名前やその他のプロパティを設定できます。
|
||||
|
||||
さらに、[カスタムトレースプロセッサ](#custom-tracing-processors) を設定して、トレースを他の宛先に送信することも可能です（置き換えまたは追加の宛先として）。
|
||||
|
||||
## 上位レベルのトレース
|
||||
|
||||
複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合、コード全体を `trace()` でラップします。
|
||||
|
||||
```python
|
||||
from agents import Agent, Runner, trace
|
||||
|
||||
async def main():
|
||||
agent = Agent(name="Joke generator", instructions="Tell funny jokes.")
|
||||
|
||||
with trace("Joke workflow"): # (1)!
|
||||
first_result = await Runner.run(agent, "Tell me a joke")
|
||||
second_result = await Runner.run(agent, f"Rate this joke: {first_result.final_output}")
|
||||
print(f"Joke: {first_result.final_output}")
|
||||
print(f"Rating: {second_result.final_output}")
|
||||
```
|
||||
|
||||
1. 2 回の `Runner.run` 呼び出しが `with trace()` でラップされているため、個別の実行はそれぞれ別のトレースを作成するのではなく、全体のトレースの一部になります。
|
||||
|
||||
## トレースの作成
|
||||
|
||||
トレースを作成するには [`trace()`][agents.tracing.trace] 関数を使用します。トレースは開始と終了が必要です。以下の 2 つの方法があります。
|
||||
|
||||
1. **推奨**：コンテキストマネージャとして使用します（例：`with trace(...) as my_trace`）。これによりトレースの開始と終了が自動的に行われます。
|
||||
2. 手動で [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を呼び出すこともできます。
|
||||
|
||||
現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を介して追跡されます。これにより、並行処理でも自動的に動作します。トレースを手動で開始・終了する場合、`start()` と `finish()` に `mark_as_current` と `reset_current` を渡して現在のトレースを更新する必要があります。
|
||||
|
||||
## スパンの作成
|
||||
|
||||
スパンを作成するには、各種の [`*_span()`][agents.tracing.create] メソッドを使用します。通常、スパンを手動で作成する必要はありません。カスタムスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] 関数も利用可能です。
|
||||
|
||||
スパンは自動的に現在のトレースに属し、最も近い現在のスパンの下にネストされます。これは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を介して追跡されます。
|
||||
|
||||
## 機密データ
|
||||
|
||||
一部のスパンは機密データを含む可能性があります。
|
||||
|
||||
`generation_span()` は LLM 生成の入出力を、`function_span()` は関数呼び出しの入出力を保存します。これらには機密データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を使用してデータの取得を無効化できます。
|
||||
|
||||
同様に、音声スパンはデフォルトで音声データを base64 エンコードされた PCM データとして含みます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して音声データの取得を無効化できます。
|
||||
|
||||
## カスタムトレーシングプロセッサ
|
||||
|
||||
トレーシングの高レベルアーキテクチャは以下の通りです。
|
||||
|
||||
- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。
|
||||
- `TraceProvider` はトレースを OpenAI バックエンドに送信する [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] と [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] で構成されます。
|
||||
|
||||
このデフォルト設定をカスタマイズするには、以下の 2 つの方法があります。
|
||||
|
||||
1. [`add_trace_processor()`][agents.tracing.add_trace_processor] で追加のプロセッサを追加できます。
|
||||
2. [`set_trace_processors()`][agents.tracing.set_trace_processors] でデフォルトのプロセッサを置き換えることができます。
|
||||
|
||||
## 外部トレーシングプロセッサ一覧
|
||||
|
||||
（省略：原文のまま）
|
||||
83
docs/ja/visualization.md
Normal file
83
docs/ja/visualization.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# エージェントの可視化
|
||||
|
||||
エージェントの可視化を使用すると、**Graphviz** を用いてエージェントとその関係性を構造化したグラフィカルな表現として生成できます。これにより、アプリケーション内でエージェント、ツール、およびハンドオフがどのように相互作用するかを理解できます。
|
||||
|
||||
## インストール
|
||||
|
||||
オプションの依存関係グループ `viz` をインストールします：
|
||||
|
||||
```bash
|
||||
pip install "openai-agents[viz]"
|
||||
```
|
||||
|
||||
## グラフの生成
|
||||
|
||||
`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は以下のような有向グラフを作成します：
|
||||
|
||||
- **エージェント** は黄色の四角形で表されます。
|
||||
- **ツール** は緑色の楕円形で表されます。
|
||||
- **ハンドオフ** はあるエージェントから別のエージェントへの有向エッジで表されます。
|
||||
|
||||
### 使用例
|
||||
|
||||
```python
|
||||
from agents import Agent, function_tool
|
||||
from agents.extensions.visualization import draw_graph
|
||||
|
||||
@function_tool
|
||||
def get_weather(city: str) -> str:
|
||||
return f"The weather in {city} is sunny."
|
||||
|
||||
spanish_agent = Agent(
|
||||
name="Spanish agent",
|
||||
instructions="You only speak Spanish.",
|
||||
)
|
||||
|
||||
english_agent = Agent(
|
||||
name="English agent",
|
||||
instructions="You only speak English",
|
||||
)
|
||||
|
||||
triage_agent = Agent(
|
||||
name="Triage agent",
|
||||
instructions="Handoff to the appropriate agent based on the language of the request.",
|
||||
handoffs=[spanish_agent, english_agent],
|
||||
tools=[get_weather],
|
||||
)
|
||||
|
||||
draw_graph(triage_agent)
|
||||
```
|
||||
|
||||
|
||||
|
||||
これにより、**triage agent** とそのサブエージェントおよびツールとの接続構造を視覚的に表現したグラフが生成されます。
|
||||
|
||||
## 可視化の理解
|
||||
|
||||
生成されたグラフには以下が含まれます：
|
||||
|
||||
- エントリーポイントを示す **開始ノード** (`__start__`)。
|
||||
- 黄色で塗りつぶされた四角形で表されるエージェント。
|
||||
- 緑色で塗りつぶされた楕円形で表されるツール。
|
||||
- 相互作用を示す有向エッジ：
|
||||
- エージェント間のハンドオフは **実線矢印**。
|
||||
- ツールの呼び出しは **点線矢印**。
|
||||
- 実行終了地点を示す **終了ノード** (`__end__`)。
|
||||
|
||||
## グラフのカスタマイズ
|
||||
|
||||
### グラフの表示
|
||||
デフォルトでは、`draw_graph` はグラフをインラインで表示します。グラフを別ウィンドウで表示するには、以下のように記述します：
|
||||
|
||||
```python
|
||||
draw_graph(triage_agent).view()
|
||||
```
|
||||
|
||||
### グラフの保存
|
||||
デフォルトでは、`draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します：
|
||||
|
||||
```python
|
||||
draw_graph(triage_agent, filename="agent_graph.png")
|
||||
```
|
||||
|
||||
これにより、作業ディレクトリに `agent_graph.png` が生成されます。
|
||||
75
docs/ja/voice/pipeline.md
Normal file
75
docs/ja/voice/pipeline.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# パイプラインとワークフロー
|
||||
|
||||
[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] クラスを使用すると、エージェントのワークフローを簡単に音声アプリに変換できます。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、ワークフロー出力の音声への変換を処理します。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
%% Input
|
||||
A["🎤 Audio Input"]
|
||||
|
||||
%% Voice Pipeline
|
||||
subgraph Voice_Pipeline [Voice Pipeline]
|
||||
direction TB
|
||||
B["Transcribe (speech-to-text)"]
|
||||
C["Your Code"]:::highlight
|
||||
D["Text-to-speech"]
|
||||
B --> C --> D
|
||||
end
|
||||
|
||||
%% Output
|
||||
E["🎧 Audio Output"]
|
||||
|
||||
%% Flow
|
||||
A --> Voice_Pipeline
|
||||
Voice_Pipeline --> E
|
||||
|
||||
%% Custom styling
|
||||
classDef highlight fill:#ffcc66,stroke:#333,stroke-width:1px,font-weight:700;
|
||||
|
||||
```
|
||||
|
||||
## パイプラインの設定
|
||||
|
||||
パイプラインを作成する際、以下の項目を設定できます。
|
||||
|
||||
1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]：新しい音声が文字起こしされるたびに実行されるコードです。
|
||||
2. 使用する [`speech-to-text`][agents.voice.model.STTModel] および [`text-to-speech`][agents.voice.model.TTSModel] モデル
|
||||
3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]：以下のような設定が可能です。
|
||||
- モデル名をモデルにマッピングするモデルプロバイダー
|
||||
- トレーシング（トレーシングの無効化、音声ファイルのアップロード有無、ワークフロー名、トレース ID など）
|
||||
- TTS および STT モデルの設定（プロンプト、言語、使用するデータ型など）
|
||||
|
||||
## パイプラインの実行
|
||||
|
||||
パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドを使用して実行できます。このメソッドでは、以下の 2 種類の形式で音声入力を渡すことができます。
|
||||
|
||||
1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声トランスクリプトがあり、それに対する結果を生成したい場合に使用します。これは、話者が話し終えたタイミングを検出する必要がない場合に便利です。例えば、事前録音された音声や、ユーザーが話し終えたタイミングが明確なプッシュトゥトーク型アプリなどです。
|
||||
2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたタイミングを検出する必要がある場合に使用します。音声チャンクを検出時に順次送信でき、音声パイプラインは「アクティビティ検出」と呼ばれるプロセスを通じて、適切なタイミングでエージェントのワークフローを自動的に実行します。
|
||||
|
||||
## 実行結果
|
||||
|
||||
音声パイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリームとして取得できるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、以下を含みます。
|
||||
|
||||
1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]：音声チャンクを含むイベントです。
|
||||
2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]：ターンの開始や終了など、ライフサイクルイベントを通知します。
|
||||
3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]：エラーイベントです。
|
||||
|
||||
```python
|
||||
|
||||
result = await pipeline.run(input)
|
||||
|
||||
async for event in result.stream():
|
||||
if event.type == "voice_stream_event_audio":
|
||||
# play audio
|
||||
elif event.type == "voice_stream_event_lifecycle":
|
||||
# lifecycle
|
||||
elif event.type == "voice_stream_event_error"
|
||||
# error
|
||||
...
|
||||
```
|
||||
|
||||
## ベストプラクティス
|
||||
|
||||
### 割り込み処理
|
||||
|
||||
Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込み処理をサポートしていません。その代わり、検出された各ターンごとにワークフローが個別に実行されます。アプリケーション内で割り込みを処理したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視できます。`turn_started` は新しいターンが文字起こしされ、処理が開始されたことを示します。`turn_ended` は、該当するターンのすべての音声が送信された後にトリガーされます。これらのイベントを利用して、モデルがターンを開始した際に話者のマイクをミュートし、ターンに関連するすべての音声を送信した後にミュートを解除する、といった処理が可能です。
|
||||
194
docs/ja/voice/quickstart.md
Normal file
194
docs/ja/voice/quickstart.md
Normal file
|
|
@ -0,0 +1,194 @@
|
|||
# クイックスタート
|
||||
|
||||
## 前提条件
|
||||
|
||||
まず、Agents SDK の基本的な[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしてください。その後、SDK のオプションである音声関連の依存関係をインストールします。
|
||||
|
||||
```bash
|
||||
pip install 'openai-agents[voice]'
|
||||
```
|
||||
|
||||
## コンセプト
|
||||
|
||||
理解すべき主なコンセプトは [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは以下の 3 ステップで構成されています。
|
||||
|
||||
1. 音声認識モデルを実行し、音声をテキストに変換します。
|
||||
2. 通常はエージェントを用いたワークフローであるコードを実行し、実行結果を生成します。
|
||||
3. テキスト読み上げモデルを実行し、実行結果のテキストを再び音声に変換します。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
%% Input
|
||||
A["🎤 Audio Input"]
|
||||
|
||||
%% Voice Pipeline
|
||||
subgraph Voice_Pipeline [Voice Pipeline]
|
||||
direction TB
|
||||
B["Transcribe (speech-to-text)"]
|
||||
C["Your Code"]:::highlight
|
||||
D["Text-to-speech"]
|
||||
B --> C --> D
|
||||
end
|
||||
|
||||
%% Output
|
||||
E["🎧 Audio Output"]
|
||||
|
||||
%% Flow
|
||||
A --> Voice_Pipeline
|
||||
Voice_Pipeline --> E
|
||||
|
||||
%% Custom styling
|
||||
classDef highlight fill:#ffcc66,stroke:#333,stroke-width:1px,font-weight:700;
|
||||
|
||||
```
|
||||
|
||||
## エージェント
|
||||
|
||||
まず、いくつかのエージェントを設定します。この SDK でエージェントを作成したことがあれば、馴染みのある内容です。ここでは、複数のエージェント、ハンドオフ、およびツールを設定します。
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import random
|
||||
|
||||
from agents import (
|
||||
Agent,
|
||||
function_tool,
|
||||
)
|
||||
from agents.extensions.handoff_prompt import prompt_with_handoff_instructions
|
||||
|
||||
|
||||
|
||||
@function_tool
|
||||
def get_weather(city: str) -> str:
|
||||
"""Get the weather for a given city."""
|
||||
print(f"[debug] get_weather called with city: {city}")
|
||||
choices = ["sunny", "cloudy", "rainy", "snowy"]
|
||||
return f"The weather in {city} is {random.choice(choices)}."
|
||||
|
||||
|
||||
spanish_agent = Agent(
|
||||
name="Spanish",
|
||||
handoff_description="A spanish speaking agent.",
|
||||
instructions=prompt_with_handoff_instructions(
|
||||
"You're speaking to a human, so be polite and concise. Speak in Spanish.",
|
||||
),
|
||||
model="gpt-4o-mini",
|
||||
)
|
||||
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
instructions=prompt_with_handoff_instructions(
|
||||
"You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
|
||||
),
|
||||
model="gpt-4o-mini",
|
||||
handoffs=[spanish_agent],
|
||||
tools=[get_weather],
|
||||
)
|
||||
```
|
||||
|
||||
## 音声パイプライン
|
||||
|
||||
ここでは、ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用し、シンプルな音声パイプラインを設定します。
|
||||
|
||||
```python
|
||||
from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline
|
||||
pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
|
||||
```
|
||||
|
||||
## パイプラインの実行
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import sounddevice as sd
|
||||
from agents.voice import AudioInput
|
||||
|
||||
# 簡単のため、ここでは 3 秒間の無音を作成します
|
||||
# 実際にはマイクからの音声データを使用します
|
||||
buffer = np.zeros(24000 * 3, dtype=np.int16)
|
||||
audio_input = AudioInput(buffer=buffer)
|
||||
|
||||
result = await pipeline.run(audio_input)
|
||||
|
||||
# `sounddevice` を使ってオーディオプレイヤーを作成します
|
||||
player = sd.OutputStream(samplerate=24000, channels=1, dtype=np.int16)
|
||||
player.start()
|
||||
|
||||
# 音声ストリームをリアルタイムで再生します
|
||||
async for event in result.stream():
|
||||
if event.type == "voice_stream_event_audio":
|
||||
player.write(event.data)
|
||||
|
||||
```
|
||||
|
||||
## すべてをまとめる
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import random
|
||||
|
||||
import numpy as np
|
||||
import sounddevice as sd
|
||||
|
||||
from agents import (
|
||||
Agent,
|
||||
function_tool,
|
||||
set_tracing_disabled,
|
||||
)
|
||||
from agents.voice import (
|
||||
AudioInput,
|
||||
SingleAgentVoiceWorkflow,
|
||||
VoicePipeline,
|
||||
)
|
||||
from agents.extensions.handoff_prompt import prompt_with_handoff_instructions
|
||||
|
||||
|
||||
@function_tool
|
||||
def get_weather(city: str) -> str:
|
||||
"""Get the weather for a given city."""
|
||||
print(f"[debug] get_weather called with city: {city}")
|
||||
choices = ["sunny", "cloudy", "rainy", "snowy"]
|
||||
return f"The weather in {city} is {random.choice(choices)}."
|
||||
|
||||
|
||||
spanish_agent = Agent(
|
||||
name="Spanish",
|
||||
handoff_description="A spanish speaking agent.",
|
||||
instructions=prompt_with_handoff_instructions(
|
||||
"You're speaking to a human, so be polite and concise. Speak in Spanish.",
|
||||
),
|
||||
model="gpt-4o-mini",
|
||||
)
|
||||
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
instructions=prompt_with_handoff_instructions(
|
||||
"You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
|
||||
),
|
||||
model="gpt-4o-mini",
|
||||
handoffs=[spanish_agent],
|
||||
tools=[get_weather],
|
||||
)
|
||||
|
||||
|
||||
async def main():
|
||||
pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
|
||||
buffer = np.zeros(24000 * 3, dtype=np.int16)
|
||||
audio_input = AudioInput(buffer=buffer)
|
||||
|
||||
result = await pipeline.run(audio_input)
|
||||
|
||||
# `sounddevice` を使ってオーディオプレイヤーを作成します
|
||||
player = sd.OutputStream(samplerate=24000, channels=1, dtype=np.int16)
|
||||
player.start()
|
||||
|
||||
# 音声ストリームをリアルタイムで再生します
|
||||
async for event in result.stream():
|
||||
if event.type == "voice_stream_event_audio":
|
||||
player.write(event.data)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
このコード例を実行すると、エージェントがあなたに話しかけます。実際にエージェントと会話できるデモについては、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) のコード例を参照してください。
|
||||
14
docs/ja/voice/tracing.md
Normal file
14
docs/ja/voice/tracing.md
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
# トレーシング
|
||||
|
||||
[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。
|
||||
|
||||
基本的なトレーシング情報については、上記のトレーシングドキュメントを参照してください。さらに、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を使用してパイプラインのトレーシングを設定できます。
|
||||
|
||||
主なトレーシング関連フィールドは以下のとおりです。
|
||||
|
||||
- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。
|
||||
- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]：音声文字起こしなど、機密性の高いデータをトレースに含めるかどうかを制御します。これは特に音声パイプライン向けであり、ワークフロー内部の処理には影響しません。
|
||||
- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]：トレースに音声データを含めるかどうかを制御します。
|
||||
- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]：トレースするワークフローの名前です。
|
||||
- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]：複数のトレースを関連付けるためのトレースの `group_id` です。
|
||||
- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：トレースに含める追加のメタデータです。
|
||||
158
docs/scripts/translate_docs.py
Normal file
158
docs/scripts/translate_docs.py
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
# ruff: noqa
|
||||
import os
|
||||
from openai import OpenAI
|
||||
from concurrent.futures import ThreadPoolExecutor
|
||||
|
||||
|
||||
# Define the source and target directories
|
||||
source_dir = "docs"
|
||||
languages = {
|
||||
"ja": "Japanese",
|
||||
# Add more languages here, e.g., "fr": "French"
|
||||
}
|
||||
|
||||
# Initialize OpenAI client
|
||||
openai_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
|
||||
|
||||
# Define dictionaries for translation control
|
||||
do_not_translate = [
|
||||
"OpenAI",
|
||||
"Agents SDK",
|
||||
"Hello World",
|
||||
"Model Context Protocol",
|
||||
"structured outputs",
|
||||
# Add more terms here
|
||||
]
|
||||
|
||||
eng_to_non_eng_mapping = {
|
||||
"ja": {
|
||||
"agents": "エージェント",
|
||||
"computer use": "コンピュータ操作",
|
||||
"OAI hosted tools": "OpenAI がホストするツール",
|
||||
"well formed data": "適切な形式のデータ",
|
||||
"guardrail": "ガードレール",
|
||||
"handoffs": "ハンドオフ",
|
||||
"function tools": "関数ツール",
|
||||
"tracing": "トレーシング",
|
||||
"code examples": "コード例",
|
||||
"vector store": "ベクトルストア",
|
||||
# Add more Japanese mappings here
|
||||
},
|
||||
# Add more languages here
|
||||
}
|
||||
eng_to_non_eng_instructions = {
|
||||
"ja": {
|
||||
"The term 'result' in the Runner guide context must be translated like 'execution results'",
|
||||
"The term 'raw' in 'raw response events' must be kept as is",
|
||||
"The term 'examples' must be code examples when the page mentions the code examples in the repo, it can be translated as either 'code exmaples' or 'sample code'.",
|
||||
"The term 'primitives' can be translated as basic components or building blocks.",
|
||||
"When the terms 'instructions' and 'tools' are mentioned as API parameter names, they must be kept as is.",
|
||||
# Add more Japanese mappings here
|
||||
},
|
||||
# Add more languages here
|
||||
}
|
||||
|
||||
|
||||
def built_instructions(target_language: str, lang_code: str) -> str:
|
||||
do_not_translate_terms = "\n".join(do_not_translate)
|
||||
specific_terms = "\n".join(
|
||||
[f"{k} -> {v}" for k, v in eng_to_non_eng_mapping.get(lang_code, {}).items()]
|
||||
)
|
||||
specific_instructions = "\n".join(eng_to_non_eng_instructions.get(lang_code, {}))
|
||||
return f"""You are a professional translator with extensive experience in translating technical documents.
|
||||
You are assigned to translate markdown text written in English into {target_language}.
|
||||
The tone and voice must be concise, consistent, and most importantly professional.
|
||||
You must return only the generated markdown text. Don't include any additional comments.
|
||||
When you're unable to complete full translation, return an error message indicating the reason instead of returning partial results.
|
||||
|
||||
# Do not translate
|
||||
{do_not_translate_terms}
|
||||
|
||||
# Specific term mappings
|
||||
When you convert these terms, do not append whitespaces before/after the terms.
|
||||
{specific_terms}
|
||||
{specific_instructions}
|
||||
|
||||
# Other Rules
|
||||
- When translating into Japanese, ensure there are spaces before and after alphanumeric terms and markdown special characters like italic and bold.
|
||||
- When translating very uncommon technical terms, include both the translated term and the original term in parentheses. That said, the section titles should be as simple as possible.
|
||||
- You must skip translating any parts of code snippets and code comments
|
||||
- "./assets/*" needs to be converted to "../assets/*"; markdown files like ./tracing.md can be kept as is.
|
||||
"""
|
||||
|
||||
|
||||
# Function to translate and save files
|
||||
def translate_file(file_path: str, target_path: str, lang_code: str) -> None:
|
||||
print(f"Translating {file_path} into a different language: {lang_code}")
|
||||
with open(file_path, encoding="utf-8") as f:
|
||||
content = f.read()
|
||||
|
||||
# Split content into lines
|
||||
lines: list[str] = content.splitlines()
|
||||
chunks: list[str] = []
|
||||
current_chunk: list[str] = []
|
||||
|
||||
# Split content into chunks of up to 120 lines, ensuring splits occur before section titles
|
||||
for line in lines:
|
||||
if len(current_chunk) >= 120 and line.startswith("#"):
|
||||
chunks.append("\n".join(current_chunk))
|
||||
current_chunk = []
|
||||
current_chunk.append(line)
|
||||
if current_chunk:
|
||||
chunks.append("\n".join(current_chunk))
|
||||
|
||||
# Translate each chunk separately and combine results
|
||||
translated_content: list[str] = []
|
||||
for chunk in chunks:
|
||||
response = openai_client.responses.create(
|
||||
model="gpt-4.5-preview",
|
||||
temperature=0.0,
|
||||
instructions=built_instructions(languages[lang_code], lang_code),
|
||||
input=chunk,
|
||||
)
|
||||
translated_content.append(response.output_text)
|
||||
|
||||
# Save the combined translated content
|
||||
with open(target_path, "w", encoding="utf-8") as f:
|
||||
f.write("\n".join(translated_content))
|
||||
|
||||
|
||||
def translate_single_source_file(file_path: str) -> None:
|
||||
relative_path = os.path.relpath(file_path, source_dir)
|
||||
if "ref/" in relative_path or not file_path.endswith(".md"):
|
||||
return
|
||||
|
||||
for lang_code in languages:
|
||||
target_dir = os.path.join(source_dir, lang_code)
|
||||
target_path = os.path.join(target_dir, relative_path)
|
||||
|
||||
# Ensure the target directory exists
|
||||
os.makedirs(os.path.dirname(target_path), exist_ok=True)
|
||||
|
||||
# Translate and save the file
|
||||
translate_file(file_path, target_path, lang_code)
|
||||
|
||||
|
||||
def main():
|
||||
# Traverse the source directory
|
||||
for root, _, file_names in os.walk(source_dir):
|
||||
# Skip the target directories
|
||||
if any(lang in root for lang in languages):
|
||||
continue
|
||||
with ThreadPoolExecutor(max_workers=20) as executor:
|
||||
futures = [
|
||||
executor.submit(
|
||||
translate_single_source_file,
|
||||
os.path.join(root, file_name),
|
||||
)
|
||||
for file_name in file_names
|
||||
]
|
||||
for future in futures:
|
||||
future.result()
|
||||
|
||||
print("Translation completed.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
# translate_single_source_file("docs/tools.md")
|
||||
main()
|
||||
188
mkdocs.yml
188
mkdocs.yml
|
|
@ -18,79 +18,6 @@ theme:
|
|||
primary: black
|
||||
logo: assets/logo.svg
|
||||
favicon: images/favicon-platform.svg
|
||||
nav:
|
||||
- Intro: index.md
|
||||
- Quickstart: quickstart.md
|
||||
- Examples: examples.md
|
||||
- Documentation:
|
||||
- agents.md
|
||||
- running_agents.md
|
||||
- results.md
|
||||
- streaming.md
|
||||
- tools.md
|
||||
- mcp.md
|
||||
- handoffs.md
|
||||
- tracing.md
|
||||
- context.md
|
||||
- guardrails.md
|
||||
- multi_agent.md
|
||||
- models.md
|
||||
- config.md
|
||||
- visualization.md
|
||||
- Voice agents:
|
||||
- voice/quickstart.md
|
||||
- voice/pipeline.md
|
||||
- voice/tracing.md
|
||||
- API Reference:
|
||||
- Agents:
|
||||
- ref/index.md
|
||||
- ref/agent.md
|
||||
- ref/run.md
|
||||
- ref/tool.md
|
||||
- ref/result.md
|
||||
- ref/stream_events.md
|
||||
- ref/handoffs.md
|
||||
- ref/lifecycle.md
|
||||
- ref/items.md
|
||||
- ref/run_context.md
|
||||
- ref/usage.md
|
||||
- ref/exceptions.md
|
||||
- ref/guardrail.md
|
||||
- ref/model_settings.md
|
||||
- ref/agent_output.md
|
||||
- ref/function_schema.md
|
||||
- ref/models/interface.md
|
||||
- ref/models/openai_chatcompletions.md
|
||||
- ref/models/openai_responses.md
|
||||
- ref/mcp/server.md
|
||||
- ref/mcp/util.md
|
||||
- Tracing:
|
||||
- ref/tracing/index.md
|
||||
- ref/tracing/create.md
|
||||
- ref/tracing/traces.md
|
||||
- ref/tracing/spans.md
|
||||
- ref/tracing/processor_interface.md
|
||||
- ref/tracing/processors.md
|
||||
- ref/tracing/scope.md
|
||||
- ref/tracing/setup.md
|
||||
- ref/tracing/span_data.md
|
||||
- ref/tracing/util.md
|
||||
- Voice:
|
||||
- ref/voice/pipeline.md
|
||||
- ref/voice/workflow.md
|
||||
- ref/voice/input.md
|
||||
- ref/voice/result.md
|
||||
- ref/voice/pipeline_config.md
|
||||
- ref/voice/events.md
|
||||
- ref/voice/exceptions.md
|
||||
- ref/voice/model.md
|
||||
- ref/voice/utils.md
|
||||
- ref/voice/models/openai_provider.md
|
||||
- ref/voice/models/openai_stt.md
|
||||
- ref/voice/models/openai_tts.md
|
||||
- Extensions:
|
||||
- ref/extensions/handoff_filters.md
|
||||
- ref/extensions/handoff_prompt.md
|
||||
|
||||
plugins:
|
||||
- search
|
||||
|
|
@ -113,10 +40,125 @@ plugins:
|
|||
heading_level: 3
|
||||
# Show inherited members
|
||||
inherited_members: true
|
||||
- i18n:
|
||||
docs_structure: folder
|
||||
languages:
|
||||
- locale: en
|
||||
default: true
|
||||
name: English
|
||||
build: true
|
||||
nav:
|
||||
- Intro: index.md
|
||||
- Quickstart: quickstart.md
|
||||
- Examples: examples.md
|
||||
- Documentation:
|
||||
- agents.md
|
||||
- running_agents.md
|
||||
- results.md
|
||||
- streaming.md
|
||||
- tools.md
|
||||
- mcp.md
|
||||
- handoffs.md
|
||||
- tracing.md
|
||||
- context.md
|
||||
- guardrails.md
|
||||
- multi_agent.md
|
||||
- models.md
|
||||
- config.md
|
||||
- visualization.md
|
||||
- Voice agents:
|
||||
- voice/quickstart.md
|
||||
- voice/pipeline.md
|
||||
- voice/tracing.md
|
||||
- API Reference:
|
||||
- Agents:
|
||||
- ref/index.md
|
||||
- ref/agent.md
|
||||
- ref/run.md
|
||||
- ref/tool.md
|
||||
- ref/result.md
|
||||
- ref/stream_events.md
|
||||
- ref/handoffs.md
|
||||
- ref/lifecycle.md
|
||||
- ref/items.md
|
||||
- ref/run_context.md
|
||||
- ref/usage.md
|
||||
- ref/exceptions.md
|
||||
- ref/guardrail.md
|
||||
- ref/model_settings.md
|
||||
- ref/agent_output.md
|
||||
- ref/function_schema.md
|
||||
- ref/models/interface.md
|
||||
- ref/models/openai_chatcompletions.md
|
||||
- ref/models/openai_responses.md
|
||||
- ref/mcp/server.md
|
||||
- ref/mcp/util.md
|
||||
- Tracing:
|
||||
- ref/tracing/index.md
|
||||
- ref/tracing/create.md
|
||||
- ref/tracing/traces.md
|
||||
- ref/tracing/spans.md
|
||||
- ref/tracing/processor_interface.md
|
||||
- ref/tracing/processors.md
|
||||
- ref/tracing/scope.md
|
||||
- ref/tracing/setup.md
|
||||
- ref/tracing/span_data.md
|
||||
- ref/tracing/util.md
|
||||
- Voice:
|
||||
- ref/voice/pipeline.md
|
||||
- ref/voice/workflow.md
|
||||
- ref/voice/input.md
|
||||
- ref/voice/result.md
|
||||
- ref/voice/pipeline_config.md
|
||||
- ref/voice/events.md
|
||||
- ref/voice/exceptions.md
|
||||
- ref/voice/model.md
|
||||
- ref/voice/utils.md
|
||||
- ref/voice/models/openai_provider.md
|
||||
- ref/voice/models/openai_stt.md
|
||||
- ref/voice/models/openai_tts.md
|
||||
- Extensions:
|
||||
- ref/extensions/handoff_filters.md
|
||||
- ref/extensions/handoff_prompt.md
|
||||
|
||||
- locale: ja
|
||||
name: 日本語
|
||||
build: true
|
||||
nav:
|
||||
- はじめに: index.md
|
||||
- クイックスタート: quickstart.md
|
||||
- サンプル例: examples.md
|
||||
- ドキュメント:
|
||||
- agents.md
|
||||
- running_agents.md
|
||||
- results.md
|
||||
- streaming.md
|
||||
- tools.md
|
||||
- mcp.md
|
||||
- handoffs.md
|
||||
- tracing.md
|
||||
- context.md
|
||||
- guardrails.md
|
||||
- multi_agent.md
|
||||
- models.md
|
||||
- config.md
|
||||
- visualization.md
|
||||
- 音声エージェント:
|
||||
- voice/quickstart.md
|
||||
- voice/pipeline.md
|
||||
- voice/tracing.md
|
||||
|
||||
extra:
|
||||
# Remove material generation message in footer
|
||||
generator: false
|
||||
language: en
|
||||
alternate:
|
||||
- name: English
|
||||
link: /openai-agents-python/
|
||||
lang: en
|
||||
- name: 日本語
|
||||
link: /openai-agents-python/ja/
|
||||
lang: ja
|
||||
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences:
|
||||
|
|
|
|||
|
|
@ -14,6 +14,7 @@ dependencies = [
|
|||
"requests>=2.0, <3",
|
||||
"types-requests>=2.0, <3",
|
||||
"mcp>=1.6.0, <2; python_version >= '3.10'",
|
||||
"mkdocs-static-i18n>=1.3.0",
|
||||
]
|
||||
classifiers = [
|
||||
"Typing :: Typed",
|
||||
|
|
@ -48,6 +49,7 @@ dev = [
|
|||
"mkdocs>=1.6.0",
|
||||
"mkdocs-material>=9.6.0",
|
||||
"mkdocstrings[python]>=0.28.0",
|
||||
"mkdocs-static-i18n",
|
||||
"coverage>=7.6.12",
|
||||
"playwright==1.50.0",
|
||||
"inline-snapshot>=0.20.7",
|
||||
|
|
|
|||
16
uv.lock
16
uv.lock
|
|
@ -851,6 +851,18 @@ wheels = [
|
|||
{ url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728 },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "mkdocs-static-i18n"
|
||||
version = "1.3.0"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
dependencies = [
|
||||
{ name = "mkdocs" },
|
||||
]
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/03/2b/59652a2550465fde25ae6a009cb6d74d0f7e724d272fc952685807b29ca1/mkdocs_static_i18n-1.3.0.tar.gz", hash = "sha256:65731e1e4ec6d719693e24fee9340f5516460b2b7244d2a89bed4ce3cfa6a173", size = 1370450 }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/ca/f7/ef222a7a2f96ecf79c7c00bfc9dde3b22cd2cc1bd2b7472c7b204fc64225/mkdocs_static_i18n-1.3.0-py3-none-any.whl", hash = "sha256:7905d52fff71d2c108b6c344fd223e848ca7e39ddf319b70864dfa47dba85d6b", size = 21660 },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "mkdocstrings"
|
||||
version = "0.29.0"
|
||||
|
|
@ -1092,6 +1104,7 @@ source = { editable = "." }
|
|||
dependencies = [
|
||||
{ name = "griffe" },
|
||||
{ name = "mcp", marker = "python_full_version >= '3.10'" },
|
||||
{ name = "mkdocs-static-i18n" },
|
||||
{ name = "openai" },
|
||||
{ name = "pydantic" },
|
||||
{ name = "requests" },
|
||||
|
|
@ -1115,6 +1128,7 @@ dev = [
|
|||
{ name = "inline-snapshot" },
|
||||
{ name = "mkdocs" },
|
||||
{ name = "mkdocs-material" },
|
||||
{ name = "mkdocs-static-i18n" },
|
||||
{ name = "mkdocstrings", extra = ["python"] },
|
||||
{ name = "mypy" },
|
||||
{ name = "playwright" },
|
||||
|
|
@ -1135,6 +1149,7 @@ requires-dist = [
|
|||
{ name = "graphviz", marker = "extra == 'viz'", specifier = ">=0.17" },
|
||||
{ name = "griffe", specifier = ">=1.5.6,<2" },
|
||||
{ name = "mcp", marker = "python_full_version >= '3.10'", specifier = ">=1.6.0,<2" },
|
||||
{ name = "mkdocs-static-i18n", specifier = ">=1.3.0" },
|
||||
{ name = "numpy", marker = "python_full_version >= '3.10' and extra == 'voice'", specifier = ">=2.2.0,<3" },
|
||||
{ name = "openai", specifier = ">=1.66.5" },
|
||||
{ name = "pydantic", specifier = ">=2.10,<3" },
|
||||
|
|
@ -1152,6 +1167,7 @@ dev = [
|
|||
{ name = "inline-snapshot", specifier = ">=0.20.7" },
|
||||
{ name = "mkdocs", specifier = ">=1.6.0" },
|
||||
{ name = "mkdocs-material", specifier = ">=9.6.0" },
|
||||
{ name = "mkdocs-static-i18n" },
|
||||
{ name = "mkdocstrings", extras = ["python"], specifier = ">=0.28.0" },
|
||||
{ name = "mypy" },
|
||||
{ name = "playwright", specifier = "==1.50.0" },
|
||||
|
|
|
|||
Loading…
Reference in a new issue