admin-valentin/openai-agents-python
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Evolve the doc translation workflow by using gpt-4.1 (#507)

Browse source 
This pull request enhances the document translation workflow by
switching to the new GPT-4.1 model. The generator script’s prompt now
includes a “workflow” section that guides the model to iterate
self-reviews on its outputs to autonomously achieve the highest quality.
This addition has noticeably improved the naturalness and consistency of
the wording in the translated outputs.
This commit is contained in:
Kazuhiro Sera 2025-04-15 11:04:07 +09:00 committed by GitHub
parent 92d6e3e66c
commit 360f173b73
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 438 additions and 430 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
docs/ja/agents.md
View file

@ -1,14 +1,14 @@
# エージェント
エージェントはアプリのコア構成要素です。エージェントは、指示とツールで構成された大規模言語モデル (LLM) です。
エージェントは、アプリケーションの中核となる基本コンポーネントです。エージェントとは、instructions とツールで構成された大規模言語モデル（LLM）のことです。
## 基本設定
エージェントで設定する最も一般的なプロパティは次のとおりです：
エージェントで最も一般的に設定するプロパティは以下の通りです。
- `instructions`: 開発者メッセージまたはシステムプロンプトとも呼ばれます。
- `model`: 使用する LLM と、temperature や top_p などのモデル調整パラメーターを設定するためのオプションの `model_settings`。
- `tools`: エージェントがタスクを達成するために使用できるツール。
- `instructions`：developer message や システムプロンプト(system prompt)とも呼ばれます。
- `model`：どの LLM を使用するか、また `model_settings` で temperature や top_p などのモデル調整パラメーターを設定できます。
- `tools`：エージェントがタスクを達成するために使用できるツールです。
```python
from agents import Agent, ModelSettings, function_tool
@ -27,7 +27,7 @@ agent = Agent(
## コンテキスト
エージェントは `context` タイプに対して汎用的です。コンテキストは依存性注入ツールであり、`Runner.run()` に渡すために作成するオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェントの実行に必要な依存関係や状態をまとめたものとして機能します。任意の Python オブジェクトをコンテキストとして提供できます。
エージェントは `context` 型に対して汎用的です。コンテキストは依存性注入ツールであり、`Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行時の依存関係や状態をまとめて管理します。任意の Python オブジェクトを context として指定できます。
```python
@dataclass
@ -45,7 +45,7 @@ agent = Agent[UserContext](
## 出力タイプ
デフォルトでは、エージェントはプレーンテキスト（つまり `str`）の出力を生成します。特定のタイプの出力をエージェントに生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢として [Pydantic](https://docs.pydantic.dev/) オブジェクトを使用しますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意のタイプをサポートしています - データクラス、リスト、TypedDict など。
デフォルトでは、エージェントはプレーンテキスト（つまり `str`）出力を生成します。特定の型の出力をエージェントに生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢として [Pydantic](https://docs.pydantic.dev/) オブジェクトがありますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型（dataclasses、リスト、TypedDict など）であればサポートしています。
```python
from pydantic import BaseModel
@ -66,11 +66,11 @@ agent = Agent(
!!! note
`output_type` を渡すと、モデルに通常のプレーンテキスト応答の代わりに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示します。
`output_type` を指定すると、モデルは通常のプレーンテキスト応答の代わりに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。
## ハンドオフ
ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを提供し、エージェントは関連する場合にそれらに委任することができます。これは、単一のタスクに優れたモジュール化された専門エージェントを編成する強力なパターンです。[handoffs](handoffs.md) ドキュメントで詳細をお読みください。
ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを指定すると、エージェントは必要に応じてそれらに処理を委任できます。これは、単一タスクに特化したモジュール型のエージェントをオーケストレーションする強力なパターンです。詳細は [handoffs](handoffs.md) ドキュメントをご覧ください。
```python
from agents import Agent
@ -89,9 +89,9 @@ triage_agent = Agent(
)
```
## 動的指示
## 動的 instructions
ほとんどの場合、エージェントを作成する際に指示を提供できますが、関数を介して動的な指示を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が受け入れられます。
多くの場合、エージェント作成時に instructions を指定できますが、関数を使って動的に instructions を提供することも可能です。この関数はエージェントと context を受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が利用可能です。
```python
def dynamic_instructions(
@ -108,15 +108,15 @@ agent = Agent[UserContext](
## ライフサイクルイベント（フック）
時には、エージェントのライフサイクルを観察したいことがあります。たとえば、イベントを記録したり、特定のイベントが発生したときにデータを事前取得したりすることができます。`hooks` プロパティを使用してエージェントのライフサイクルにフックすることができます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、興味のあるメソッドをオーバーライドします。
エージェントのライフサイクルを監視したい場合があります。たとえば、イベントを記録したり、特定のイベント発生時にデータを事前取得したりしたい場合です。`hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。
## ガードレール
ガードレールを使用すると、エージェントの実行と並行してユーザー入力のチェック/検証を行うことができます。たとえば、ユーザーの入力を関連性でスクリーニングすることができます。[guardrails](guardrails.md) ドキュメントで詳細をお読みください。
ガードレールを使うと、エージェントの実行と並行して user 入力のチェックやバリデーションを行えます。たとえば、user の入力が関連性のある内容かどうかをスクリーニングできます。詳細は [guardrails](guardrails.md) ドキュメントをご覧ください。
## エージェントのクローン/コピー
## エージェントのクローン／コピー
エージェントの `clone()` メソッドを使用すると、エージェントを複製し、任意のプロパティを変更することができます。
エージェントの `clone()` メソッドを使うことで、エージェントを複製し、任意のプロパティを変更できます。
```python
pirate_agent = Agent(
@ -133,15 +133,15 @@ robot_agent = pirate_agent.clone(
## ツール使用の強制
ツールのリストを提供しても、LLM がツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は次のとおりです：
ツールのリストを指定しても、必ずしも LLM がツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツールの使用を強制できます。有効な値は以下の通りです。
1. `auto`：LLM がツールを使用するかどうかを決定します。
2. `required`：LLM がツールを使用する必要があります（ただし、どのツールを使用するかは賢く決定できます）。
3. `none`：LLM がツールを使用しないことを要求します。
4. 特定の文字列を設定する例：`my_tool`、特定のツールを使用することを要求します。
1. `auto`：LLM がツールを使うかどうかを自動で判断します。
2. `required`：LLM にツールの使用を必須とします（どのツールを使うかは賢く選択されます）。
3. `none`：LLM にツールを _使わない_ ことを要求します。
4. 特定の文字列（例：`my_tool`）を指定すると、その特定のツールの使用を必須とします。
!!! note
無限ループを防ぐために、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。無限ループは、ツールの結果が LLM に送信され、その後 `tool_choice` によって別のツール呼び出しが生成されるために発生します。
無限ループを防ぐため、フレームワークはツール呼び出し後に自動的に `tool_choice` を "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。無限ループは、ツールの execution results が LLM に送信され、`tool_choice` のために再度ツール呼び出しが発生し、これが繰り返されることで発生します。
ツール呼び出し後にエージェントが完全に停止するようにしたい場合（自動モードで続行するのではなく）、[`Agent.tool_use_behavior="stop_on_first_tool"`] を設定することで、ツールの出力を最終応答として直接使用し、さらなる LLM 処理を行わないようにできます。
ツール呼び出し後にエージェントを完全に停止させたい場合（auto モードで継続させたくない場合）は、[`Agent.tool_use_behavior="stop_on_first_tool"`] を設定できます。これにより、ツールの出力がそのまま最終応答として使用され、以降の LLM 処理は行われません。

24
docs/ja/config.md
View file

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

44
docs/ja/context.md
View file

@ -1,29 +1,29 @@
# コンテキスト管理
コンテキストは多義的な用語です。考慮すべき主なコンテキストのクラスは2つあります。
コンテキストは多義的な用語です。主に関心を持つべきコンテキストには、次の 2 つの大きなクラスがあります。
1. コードにローカルで利用可能なコンテキスト: これは、ツール関数が実行されるときや、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。
2. LLM に利用可能なコンテキスト: これは、LLM が応答を生成するときに参照するデータです。
1. コード内でローカルに利用可能なコンテキスト：これは、ツール関数の実行時や `on_handoff` のようなコールバック、ライフサイクルフックなどで必要となるデータや依存関係です。
2. LLM に利用可能なコンテキスト：これは、LLM がレスポンスを生成する際に参照できるデータです。
## ローカルコンテキスト
これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスとその中の [`context`][agents.run_context.RunContextWrapper.context] プロパティを通じて表現されます。動作の仕組みは次の通りです。
これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスおよびその中の [`context`][agents.run_context.RunContextWrapper.context] プロパティによって表現されます。仕組みは以下の通りです。
1. 任意の Python オブジェクトを作成します。一般的なパターンは、データクラスや Pydantic オブジェクトを使用することです。
2. そのオブジェクトを様々な実行メソッドに渡します（例: `Runner.run(..., **context=whatever**)`）。
3. すべてのツール呼び出し、ライフサイクルフックなどにラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` を通じてアクセスできます。
1. 任意の Python オブジェクトを作成します。一般的なパターンとしては、dataclass や Pydantic オブジェクトを使います。
2. そのオブジェクトを各種 run メソッド（例：`Runner.run(..., **context=whatever**))`）に渡します。
3. すべてのツール呼び出しやライフサイクルフックなどには、ラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` からアクセスできます。
**最も重要な**点は、特定のエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどが同じ _型_ のコンテキストを使用しなければならないことです。
**最も重要**な注意点：特定のエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは、同じ _型_ のコンテキストを使用する必要があります。
コンテキストは以下のような用途に使用できます。
コンテキストは以下のような用途で利用できます。
- 実行のためのコンテキストデータ（例: ユーザー名/uid やその他のユーザー情報）
- 依存関係（例: ロガーオブジェクト、データフェッチャーなど）
- ヘルパー関数
- 実行時のコンテキストデータ（例：ユーザー名/uid やユーザーに関するその他の情報など）
- 依存関係（例：ロガーオブジェクト、データフェッチャーなど）
- ヘルパー関数
!!! danger "注意"
コンテキストオブジェクトは **LLM に送信されません**。これは純粋にローカルなオブジェクトであり、読み書きやメソッドの呼び出しが可能です。
コンテキストオブジェクトは **LLM には送信されません**。これは純粋にローカルなオブジェクトであり、読み書きやメソッド呼び出しが可能です。
```python
import asyncio
@ -61,17 +61,17 @@ if __name__ == "__main__":
asyncio.run(main())
```
1. これはコンテキストオブジェクトです。ここではデータクラスを使用していますが、任意の型を使用できます。
2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツールの実装はコンテキストから読み取ります。
3. エージェントをジェネリック `UserInfo` でマークし、型チェッカーがエラーを検出できるようにします（例えば、異なるコンテキスト型を取るツールを渡そうとした場合）。
1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を利用できます。
2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っていることが分かります。ツールの実装はコンテキストから値を読み取ります。
3. エージェントにはジェネリック型 `UserInfo` を指定しています。これにより、型チェッカーがエラーを検出できます（例えば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。
4. コンテキストは `run` 関数に渡されます。
5. エージェントは正しくツールを呼び出し、年齢を取得します。
## エージェント/LLM コンテキスト
## エージェント／LLM コンテキスト
LLM が呼び出されるとき、**唯一** 参照できるデータは会話履歴からのものです。新しいデータを 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. リトリーバルや Web 検索を使用します。これらはファイルやデータベース（リトリーバル）、または Web（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータで応答を「グラウンド」するのに有用です。
1. エージェントの `instructions` に追加する。この方法は「システムプロンプト」や「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的な関数でも構いません。たとえば、ユーザー名や現在の日付など、常に有用な情報に適しています。
2. `Runner.run` 関数を呼び出す際に `input` に追加する。この方法は `instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位メッセージとして追加できます。
3. 関数ツールを通じて公開する。この方法は _オンデマンド_ のコンテキストに適しています。LLM が必要なタイミングでツールを呼び出し、データを取得できます。
4. リトリーバルや Web 検索を利用する。これらはファイルやデータベース（リトリーバル）、または Web（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに基づいたレスポンスを「グラウンディング」するのに役立ちます。

40
docs/ja/examples.md
View file

@ -1,40 +1,40 @@
# サンプルコード
# コード例
SDK のさまざまなサンプル実装は、[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples)のサンプルコードセクションで確認できます。これらのサンプルコードは、異なるパターンや機能を示すいくつかのカテゴリーに整理されています。
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):**
このカテゴリーの例は、一般的なエージェント設計パターンを示しています。例えば、
- **[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 の基本的な機能を紹介しています。例えば、
- **[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 がホストするツールを実装し、それらをエージェントに統合する方法を学びます。
- **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
OpenAI がホストするツール（Web 検索やファイル検索など）の実装方法や、それらをエージェントに統合する方法を学べます。
- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
OpenAI 以外のモデルを SDK で使用する方法を探ります。
- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
OpenAI 以外のモデルを SDK で利用する方法を紹介しています。
- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
エージェントのハンドオフの実用的な例を見てみましょう。
- **[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 を使用してエージェントを構築する方法を学びます。
- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
Model context protocol (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):**
実際のアプリケーションを示す、さらに詳細な2つの例
- **[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):**
実際のユースケースを示す、より発展的な 2 つのコード例です。
- **customer_service**: 航空会社向けのカスタマーサービスシステムの例。
- **customer_service**: 航空会社向けカスタマーサービスシステムの例。
- **research_bot**: シンプルなディープリサーチクローン。
- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
TTS と STT モデルを使用した音声エージェントの例を見てみましょう。
- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
TTS および STT モデルを利用した音声エージェントのコード例をご覧いただけます。

40
docs/ja/guardrails.md
View file

@ -1,43 +1,43 @@
# ガードレール
ガードレールはエージェントと _並行して_ 実行され、ユーザー入力のチェックと検証を可能にします。例えば、非常に賢い（したがって遅く/高価な）モデルを使用して顧客のリクエストを支援するエージェントがあるとします。悪意のあるユーザーがモデルに数学の宿題を手伝わせるようなことは避けたいでしょう。そこで、速く/安価なモデルでガードレールを実行できます。ガードレールが悪意のある使用を検出した場合、即座にエラーを発生させ、高価なモデルの実行を停止し、時間とお金を節約できます。
ガードレールは、エージェントと _並行して_ 実行され、ユーザー入力のチェックやバリデーションを行うことができます。例えば、非常に賢い（そのため遅くて高価な）モデルを使ってカスタマーリクエストに対応するエージェントがあるとします。悪意のあるユーザーがモデルに数学の宿題を手伝わせるようなリクエストを送ることは避けたいでしょう。そこで、ガードレールを高速かつ安価なモデルで実行できます。ガードレールが悪意のある利用を検知した場合、即座にエラーを発生させ、高価なモデルの実行を止めて時間やコストを節約できます。
ガードレールには2種類あります：
ガードレールには 2 種類あります：
1. 入力ガードレールは初期のユーザー入力に対して実行されます
2. 出力ガードレールは最終的なエージェントの出力に対して実行されます
1. 入力ガードレール：最初のユーザー入力に対して実行されます
2. 出力ガードレール：最終的なエージェント出力に対して実行されます
## 入力ガードレール
入力ガードレールは3つのステップで実行されます：
入力ガードレールは 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]例外が発生し、ユーザーに適切に応答したり、例外を処理したりできます。
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` に渡されないのか疑問に思うかもしれません。それは、ガードレールが実際のエージェントに関連している傾向があるためです。異なるエージェントには異なるガードレールを実行するので、コードを一緒に配置することは可読性に役立ちます。
入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントのガードレールは *最初* のエージェントでのみ実行されます。「なぜ `guardrails` プロパティがエージェントにあり、`Runner.run` に渡さないのか？」と疑問に思うかもしれません。これは、ガードレールが実際のエージェントに関連することが多いためです。異なるエージェントごとに異なるガードレールを実行するため、コードを同じ場所にまとめておくと可読性が向上します。
## 出力ガードレール
出力ガードレールは3つのステップで実行されます：
出力ガードレールも 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]例外が発生し、ユーザーに適切に応答したり、例外を処理したりできます。
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
出力ガードレールは最終的なエージェントの出力に対して実行されることを意図しているため、エージェントのガードレールはエージェントが*最後の*エージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールが実際のエージェントに関連している傾向があるため、コードを一緒に配置することは可読性に役立ちます。
出力ガードレールは最終的なエージェント出力に対して実行されることを想定しているため、エージェントのガードレールは *最後* のエージェントでのみ実行されます。入力ガードレールと同様に、ガードレールが実際のエージェントに関連することが多いため、コードを同じ場所にまとめておくと可読性が向上します。
## トリップワイヤー
入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤーでこれを知らせることができます。トリップワイヤーがトリガーされたガードレールを確認するとすぐに、`{Input,Output}GuardrailTripwireTriggered`例外を即座に発生させ、エージェントの実行を停止します。
入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤーでこれを通知できます。トリップワイヤーが発動したガードレールを検知した時点で、即座に `{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、エージェントの実行を停止します。
## ガードレールの実装
入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]を返す関数を提供する必要があります。この例では、エージェントを内部で実行することでこれを行います。
入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、内部でエージェントを実行することでこれを実現します。
```python
from pydantic import BaseModel
@ -90,8 +90,8 @@ async def main():
print("Math homework guardrail tripped")
```
1. このエージェントをガードレール関数で使用します。
2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。
1. このエージェントをガードレール関数内で使用します。
2. これはエージェントの入力やコンテキストを受け取り、結果を返すガードレール関数です。
3. ガードレールの結果に追加情報を含めることができます。
4. これはワークフローを定義する実際のエージェントです。
@ -148,7 +148,7 @@ async def main():
print("Math output guardrail tripped")
```
1. これは実際のエージェントの出力タイプです。
2. これはガードレールの出力タイプです。
1. これは実際のエージェントの出力型です。
2. これはガードレールの出力型です。
3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。
4. これはワークフローを定義する実際のエージェントです。

32
docs/ja/handoffs.md
View file

@ -1,18 +1,18 @@
# ハンドオフ
ハンドオフは、エージェントがタスクを他のエージェントに委任することを可能にします。これは、異なるエージェントが異なる分野に特化しているシナリオで特に有用です。例えば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専門に扱うエージェントがいるかもしれません。
ハンドオフは、エージェントが他のエージェントにタスクを委任できる仕組みです。これは、異なるエージェントがそれぞれ異なる分野に特化しているシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専門に扱うエージェントが存在する場合があります。
ハンドオフは LLM にとってツールとして表現されます。したがって、`Refund Agent` という名前のエージェントへのハンドオフがある場合、ツールは `transfer_to_refund_agent` と呼ばれます。
ハンドオフは LLM からはツールとして認識されます。たとえば、`Refund Agent` という名前のエージェントへのハンドオフがある場合、そのツール名は `transfer_to_refund_agent` となります。
## ハンドオフの作成
すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、これは `Agent` を直接取るか、ハンドオフをカスタマイズする `Handoff` オブジェクトを取ることができます。
すべてのエージェントは [`handoffs`][agents.agent.Agent.handoffs] パラメーターを持っており、これは直接 `Agent` を指定することも、ハンドオフをカスタマイズする `Handoff` オブジェクトを指定することもできます。
Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使用してハンドオフを作成できます。この関数を使用すると、ハンドオフ先のエージェントを指定し、オプションでオーバーライドや入力フィルターを設定できます。
Agents SDK で提供されている [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントや、オプションのオーバーライドや入力フィルターを指定できます。
### 基本的な使い方
簡単なハンドオフを作成する方法は次のとおりです。
シンプルなハンドオフの作成方法は以下の通りです。
```python
from agents import Agent, handoff
@ -24,18 +24,18 @@ refund_agent = Agent(name="Refund agent")
triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])
```
1. エージェントを直接使用することも（`billing_agent` のように）、`handoff()` 関数を使用することもできます。
1. エージェントを直接指定する（例：`billing_agent`）ことも、`handoff()` 関数を使うこともできます。
### `handoff()` 関数によるハンドオフのカスタマイズ
[`handoff()`][agents.handoffs.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`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は以下を参照してください。
- `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
@ -55,7 +55,7 @@ handoff_obj = handoff(
## ハンドオフ入力
特定の状況では、LLM がハンドオフを呼び出す際にデータを提供することを望む場合があります。例えば、「エスカレーションエージェント」へのハンドオフを想像してください。理由を提供してログに記録したいかもしれません。
状況によっては、LLM にハンドオフ時に何らかのデータを提供してほしい場合があります。たとえば、「エスカレーションエージェント」へのハンドオフを考えてみましょう。この場合、理由を提供して記録できるようにしたいことがあります。
```python
from pydantic import BaseModel
@ -79,9 +79,9 @@ handoff_obj = handoff(
## 入力フィルター
ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、以前の会話履歴全体を見ることができます。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で受け取り、新しい `HandoffInputData` を返す必要がある関数です。
ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を見ることができます。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] を受け取り、新しい `HandoffInputData` を返す関数です。
一般的なパターン（例えば、履歴からすべてのツール呼び出しを削除する）が [`agents.extensions.handoff_filters`][] に実装されています。
よくあるパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] で実装されています。
```python
from agents import Agent, handoff
@ -99,7 +99,7 @@ handoff_obj = handoff(
## 推奨プロンプト
LLM がハンドオフを正しく理解するために、エージェントにハンドオフに関する情報を含めることをお勧めします。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨されるプレフィックスがあります。または、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、プロンプトに推奨データを自動的に追加できます。
LLM がハンドオフを正しく理解できるようにするため、エージェントにハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] で推奨されるプレフィックスを利用するか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトに自動追加できます。
```python
from agents import Agent

36
docs/ja/index.md
View file

@ -1,28 +1,28 @@
# OpenAI エージェント SDK
# OpenAI Agents SDK
[OpenAI エージェント SDK](https://github.com/openai/openai-agents-python) は、軽量で使いやすいパッケージでエージェント AI アプリを構築することを可能にします。これは、以前のエージェントの実験である [Swarm](https://github.com/openai/swarm/tree/main) のプロダクション対応のアップグレード版です。エージェント SDK には、非常に少ない基本コンポーネントがあります。
[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、非常に少ない抽象化で、軽量かつ使いやすいパッケージで エージェント 型 AI アプリを構築できる SDK です。これは、以前のエージェント向け実験プロジェクト [Swarm](https://github.com/openai/swarm/tree/main) の本番運用向けアップグレード版です。Agents SDK には、非常に少数の基本コンポーネントが含まれています。
- **エージェント**: instructions と tools を備えた LLM
- **ハンドオフ**: エージェントが特定のタスクを他のエージェントに委任することを可能にします
- **ガードレール**: エージェントへの入力を検証することを可能にします
- **エージェント**： instructions と tools を備えた LLM
- **ハンドオフ**：特定のタスクを他のエージェントに委任できる仕組み
- **ガードレール**：エージェントへの入力を検証できる仕組み
これらの基本コンポーネントは Python と組み合わせることで、ツールとエージェント間の複雑な関係を表現するのに十分な強力さを持ち、急な学習曲線なしで実際のアプリケーションを構築することができます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを視覚化してデバッグし、評価し、さらにはアプリケーション用にモデルを微調整することができます。
Python と組み合わせることで、これらの基本コンポーネントは tools と エージェント 間の複雑な関係を表現でき、急な学習コストなしに実用的なアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** 機能があり、エージェント フローの可視化やデバッグ、評価、さらにはアプリケーション向けモデルのファインチューニングも可能です。
## なぜエージェント SDK を使うのか
## なぜ Agents SDK を使うのか
SDK には 2 つの設計原則があります。
1. 使用する価値があるだけの機能を持ち、学習が迅速になるように基本コンポーネントを少なくする。
2. すぐに使えるが、何が起こるかを正確にカスタマイズできる。
1. 使う価値のある十分な機能を持ちつつ、学習が容易なほど少ない基本コンポーネントで構成されていること。
2. すぐに使い始められるが、動作を細かくカスタマイズできること。
SDK の主な機能は次のとおりです。
SDK の主な特徴は以下の通りです。
- エージェントループ: ツールの呼び出し、LLM への結果の送信、LLM が完了するまでのループを処理する組み込みのエージェントループ。
- Python ファースト: 新しい抽象化を学ぶ必要なく、組み込みの言語機能を使用してエージェントを編成し、連鎖させる。
- ハンドオフ: 複数のエージェント間で調整し、委任するための強力な機能。
- ガードレール: エージェントと並行して入力検証とチェックを実行し、チェックが失敗した場合は早期に中断。
- 関数ツール: 任意の Python 関数をツールに変換し、自動スキーマ生成と Pydantic による検証を行う。
- トレーシング: ワークフローを視覚化、デバッグ、監視するための組み込みのトレーシング、および OpenAI の評価、微調整、蒸留ツールを使用。
- エージェントループ： tools の呼び出し、LLM への実行結果の送信、LLM が完了するまでのループ処理を自動で行います。
- Python ファースト：新しい抽象化を学ぶ必要なく、Python の言語機能でエージェントのオーケストレーションや連携が可能です。
- ハンドオフ：複数のエージェント間での調整や委任を実現する強力な機能です。
- ガードレール：エージェントと並行して入力検証やチェックを実行し、チェックに失敗した場合は早期に処理を中断します。
- 関数ツール：任意の Python 関数を自動でスキーマ生成・Pydantic ベースのバリデーション付きツールに変換できます。
- トレーシング：組み込みのトレーシングでワークフローの可視化・デバッグ・モニタリングができ、OpenAI の評価・ファインチューニング・蒸留ツールも利用可能です。
## インストール
@ -30,7 +30,7 @@ SDK の主な機能は次のとおりです。
pip install openai-agents
```
## Hello World の例
## Hello World サンプル
```python
from agents import Agent, Runner
@ -45,7 +45,7 @@ print(result.final_output)
# Infinite loop's dance.
```
(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_)
(_実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_)
```bash
export OPENAI_API_KEY=sk-...

34
docs/ja/mcp.md
View file

@ -1,21 +1,21 @@
# Model context protocol (MCP)
[Model context protocol](https://modelcontextprotocol.io/introduction) (別名 MCP) は、LLM にツールとコンテキストを提供する方法です。MCP ドキュメントからの引用:
[Model context protocol](https://modelcontextprotocol.io/introduction)（通称 MCP）は、 LLM にツールやコンテキストを提供するための方法です。MCP ドキュメントからの引用です：
> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーションのための USB-C ポートのように考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリーに接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。
> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーションのための USB-C ポートのようなものと考えてください。USB-C がさまざまな周辺機器やアクセサリにデバイスを接続する標準的な方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準的な方法を提供します。
エージェント SDK は MCP をサポートしています。これにより、エージェントにツールを提供するために幅広い MCP サーバーを使用できます。
Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを利用して、エージェントにツールを提供することができます。
## MCP サーバー
現在、MCP 仕様は使用するトランスポートメカニズムに基づいて2種類のサーバーを定義しています:
現在、MCP 仕様では、使用するトランスポートメカニズムに基づいて 2 種類のサーバーが定義されています：
1. **stdio** サーバーは、アプリケーションのサブプロセスとして実行されます。これらは「ローカルで」実行されると考えることができます。
1. **stdio** サーバーは、アプリケーションのサブプロセスとして実行されます。ローカルで実行されるものと考えることができます。
2. **HTTP over SSE** サーバーはリモートで実行されます。URL を介して接続します。
これらのサーバーに接続するには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] と [`MCPServerSse`][agents.mcp.server.MCPServerSse] クラスを使用できます。
これらのサーバーに接続するには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] および [`MCPServerSse`][agents.mcp.server.MCPServerSse] クラスを使用できます。
例えば、[公式 MCP ファイルシステムサーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を使用する方法は次のとおりです。
例えば、[公式 MCP ファイルシステムサーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を使用する場合は、次のようになります。
```python
async with MCPServerStdio(
@ -27,9 +27,9 @@ async with MCPServerStdio(
tools = await server.list_tools()
```
## MCP サーバーの使用
## MCP サーバーの利用
MCP サーバーはエージェントに追加できます。エージェント SDK は、エージェントが実行されるたびに MCP サーバーで `list_tools()` を呼び出します。これにより、LLM は MCP サーバーのツールを認識します。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーで `call_tool()` を呼び出します。
MCP サーバーはエージェントに追加できます。Agents SDK は、エージェントが実行されるたびに MCP サーバーの `list_tools()` を呼び出します。これにより、LLM は MCP サーバーのツールを認識できるようになります。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を呼び出します。
```python
@ -40,21 +40,21 @@ agent=Agent(
)
```
## キャッシング
## キャッシュ
エージェントが実行されるたびに、MCP サーバーで `list_tools()` を呼び出します。これは、特にサーバーがリモートサーバーの場合、レイテンシーの影響を受ける可能性があります。ツールのリストを自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] と [`MCPServerSse`][agents.mcp.server.MCPServerSse] に `cache_tools_list=True` を渡すことができます。ツールリストが変更されないことが確実な場合にのみこれを行うべきです。
エージェントが実行されるたびに、MCP サーバーの `list_tools()` が呼び出されます。特にサーバーがリモートの場合、これはレイテンシの原因となることがあります。ツールリストを自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] および [`MCPServerSse`][agents.mcp.server.MCPServerSse] の両方に `cache_tools_list=True` を渡すことができます。ツールリストが変更されないことが確実な場合のみ、この設定を行ってください。
キャッシュを無効にしたい場合は、サーバーで `invalidate_tools_cache()` を呼び出すことができます。
キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出すことができます。
## エンドツーエンドの例
## エンドツーエンドの code examples
[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) で完全な動作例を確認してください。
[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) で、完全な動作 code examples をご覧いただけます。
## トレーシング
[トレーシング](./tracing.md) は、MCP 操作を自動的にキャプチャします。これには以下が含まれます:
[トレーシング](../tracing.md) は、以下を含む MCP の操作を自動的に記録します：
1. ツールをリストするための MCP サーバーへの呼び出し
1. MCP サーバーへのツールリスト取得の呼び出し
2. 関数呼び出しに関する MCP 関連情報
![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg)
![MCP トレーシングのスクリーンショット](../assets/images/mcp-tracing.jpg)

60
docs/ja/models.md
View file

@ -1,21 +1,21 @@
# モデル
Agents SDK は、OpenAI モデルを次の 2 つの形式でサポートしています。
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]。
- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は、新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。
- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は、[Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。
## モデルの組み合わせ
1 つのワークフロー内で、各エージェントに異なるモデルを使用したい場合があります。たとえば、トリアージには小さくて高速なモデルを使用し、複雑なタスクにはより大きくて高機能なモデルを使用することができます。[`Agent`][agents.Agent] を設定する際に、次の方法で特定のモデルを選択できます。
1 つのワークフロー内で、各エージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小型で高速なモデルを使い、複雑なタスクにはより大きく高性能なモデルを使うことができます。[`Agent`][agents.Agent] を設定する際、以下のいずれかの方法で特定のモデルを選択できます。
1. OpenAI モデルの名前を渡す。
2. モデル名とその名前をモデルインスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。
3. 直接 [`Model`][agents.models.interface.Model] 実装を提供する。
1. OpenAI モデル名を直接渡す。
2. 任意のモデル名と、その名前を Model インスタンスにマッピングできる [`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 つの形状は異なる機能とツールをサポートしているためです。ワークフローでモデル形状を組み合わせる必要がある場合は、使用しているすべての機能が両方で利用可能であることを確認してください。
SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、各ワークフローで 1 つのモデル形状のみを使うことを推奨します。なぜなら、2 つの形状はサポートする機能やツールが異なるためです。ワークフローでモデル形状を組み合わせて使う場合は、利用するすべての機能が両方で利用可能かご確認ください。
```python
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
@ -48,10 +48,10 @@ async def main():
print(result.final_output)
```
1. OpenAI モデルの名前を直接設定します。
2. [`Model`][agents.models.interface.Model] 実装を提供します。
1. OpenAI モデル名を直接設定します。
2. [`Model`][agents.models.interface.Model] 実装を指定します。
エージェントに使用するモデルをさらに設定したい場合は、`temperature` などのオプションのモデル設定パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡すことができます。
エージェントで使用するモデルをさらに細かく設定したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡すことができます。これにより、temperature などのオプションのモデル設定パラメーターを指定できます。
```python
from agents import Agent, ModelSettings
@ -64,43 +64,43 @@ english_agent = Agent(
)
```
## 他の LLM プロバイダーの使用
## 他の LLM プロバイダーの利用
他の LLM プロバイダーを 3 つの方法で使用できます（例は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。
他の LLM プロバイダーは、3 つの方法で利用できます（[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) に code examples があります）。
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) に設定可能な例があります。
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)を設定することをお勧めします。
`platform.openai.com` の API キーがない場合は、`set_tracing_disabled()` でトレーシングを無効にするか、[別のトレーシングプロセッサー](tracing.md) を設定することを推奨します。
!!! note
これらの例では、Chat Completions API/モデルを使用しています。なぜなら、ほとんどの LLM プロバイダーはまだ Responses API をサポートしていないからです。LLM プロバイダーがそれをサポートしている場合は、Responses を使用することをお勧めします。
これらの code examples では Chat Completions API/モデルを使っています。なぜなら、ほとんどの LLM プロバイダーはまだ Responses API をサポートしていないためです。もし LLM プロバイダーが Responses API をサポートしている場合は、Responses の利用を推奨します。
## 他の LLM プロバイダーを使用する際の一般的な問題
## 他の LLM プロバイダー利用時のよくある問題
### トレーシングクライアントエラー 401
### Tracing クライアントの 401 エラー
トレーシングに関連するエラーが発生した場合、これはトレースが OpenAI サーバーにアップロードされ、OpenAI API キーを持っていないためです。これを解決するには、次の 3 つのオプションがあります。
トレーシングに関連するエラーが発生した場合、これはトレースが 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)を参照してください。
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 つのオプションがあります。
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/)にあります。
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/) に code examples があります。
### 適切な形式のデータのサポート
### structured outputs サポート
一部のモデルプロバイダーは、[適切な形式のデータ](https://platform.openai.com/docs/guides/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 のために頻繁に壊れることになります。
これは一部のモデルプロバイダーの制限で、JSON 出力には対応していても、出力に使う `json_schema` を指定できない場合があります。現在この問題の修正に取り組んでいますが、JSON schema 出力をサポートしているプロバイダーの利用を推奨します。そうでない場合、不正な JSON によりアプリが頻繁に動作しなくなる可能性があります。

44
docs/ja/multi_agent.md
View file

@ -1,37 +1,37 @@
# 複数エージェントのオーケストレーション
# 複数のエージェントのオーケストレーション
オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが実行され、どの順序で、次に何が起こるかをどのように決定するかです。エージェントをオーケストレーションする主な方法は2つあります。
オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが、どの順番で実行され、次に何が起こるかをどのように決定するかということです。エージェントをオーケストレーションする主な方法は 2 つあります。
1. LLM に決定を任せる: これは LLM の知能を利用して、計画、推論し、それに基づいてどのステップを取るかを決定します。
2. コードによるオーケストレーション: コードを通じてエージェントの流れを決定します。
1. LLM に意思決定を任せる方法：これは LLM の知能を活用し、計画・推論・意思決定を行わせるものです。
2. コードによるオーケストレーション：コードでエージェントの流れを制御する方法です。
これらのパターンを組み合わせて使用することができます。それぞれに独自のトレードオフがあり、以下で説明します。
これらのパターンは組み合わせて使うこともできます。それぞれにメリット・デメリットがあり、以下で説明します。
## LLM によるオーケストレーション
エージェントは、指示、ツール、ハンドオフを備えた LLM です。これにより、オープンエンドなタスクが与えられた場合、LLM は自律的にタスクに取り組む方法を計画し、ツールを使用してアクションを実行し、データを取得し、ハンドオフを使用してサブエージェントにタスクを委任できます。例えば、リサーチエージェントは次のようなツールを備えることができます。
エージェントとは、instructions、tools、handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられた場合、LLM は自律的にタスクへの取り組み方を計画し、tools を使ってアクションを実行・データを取得し、handoffs を使ってサブエージェントにタスクを委任できます。たとえば、リサーチエージェントには以下のような tools を持たせることができます。
- Web 検索でオンライン情報を見つける
- ファイル検索と取得で独自データや接続を検索する
- コンピュータ操作でコンピュータ上でアクションを実行する
- Web 検索でオンライン情報を探す
- ファイル検索やリトリーバルで独自データや接続先を検索する
- コンピュータ操作でコンピュータ上のアクションを実行する
- コード実行でデータ分析を行う
- 計画やレポート作成に優れた専門エージェントへのハンドオフ
- 計画やレポート作成などに特化したエージェントへの handoffs
このパターンは、タスクがオープンエンドであり、LLM の知能に依存したい場合に最適です。ここでの最も重要な戦術は次のとおりです。
このパターンは、タスクがオープンエンドで LLM の知能に頼りたい場合に最適です。ここで重要なポイントは次のとおりです。
1. 良いプロンプトに投資する。利用可能なツール、使用方法、および操作するパラメーターを明確にします。
2. アプリを監視し、反復する。問題が発生する箇所を確認し、プロンプトを改善します。
3. エージェントに内省と改善を許可する。例えば、ループで実行し、自己批評させるか、エラーメッセージを提供して改善させます。
4. 一つのタスクに優れた専門エージェントを持つこと。何でも得意とされる汎用エージェントを持つのではなく。
5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これにより、エージェントを訓練してタスクの改善と向上を図ることができます。
1. 良いプロンプトに投資しましょう。利用可能な tools、使い方、守るべきパラメーターを明確に伝えます。
2. アプリをモニタリングし、改善を繰り返しましょう。問題が発生した箇所を確認し、プロンプトを改善します。
3. エージェントに内省と改善を促しましょう。たとえばループで実行し、自己批評させたり、エラーメッセージを与えて改善させたりします。
4. 何でもできる汎用エージェントではなく、1 つのタスクに特化したエージェントを用意しましょう。
5. [evals](https://platform.openai.com/docs/guides/evals) に投資しましょう。これによりエージェントを訓練し、タスクの精度を向上させることができます。
## コードによるオーケストレーション
LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度、コスト、パフォーマンスの面でタスクをより決定的で予測可能にします。ここでの一般的なパターンは次のとおりです。
LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・パフォーマンスの面でより決定的かつ予測可能になります。よく使われるパターンは次のとおりです。
- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用して、コードで検査できる適切な形式のデータを生成します。例えば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選択することができます。
- 複数のエージェントをチェーンして、一つの出力を次の入力に変換します。ブログ記事を書くタスクを、リサーチ、アウトライン作成、記事執筆、批評、改善という一連のステップに分解できます。
- `while` ループでタスクを実行するエージェントと、評価とフィードバックを提供するエージェントを実行し、評価者が出力が特定の基準を満たすと判断するまで続けます。
- 複数のエージェントを並行して実行します。例えば、Python の基本コンポーネントである `asyncio.gather` を使用します。これは、互いに依存しない複数のタスクがある場合に速度のために役立ちます。
- [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) には多くのコード例があります。
[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) には、さまざまな code examples をご用意しています。

32
docs/ja/quickstart.md
View file

@ -2,7 +2,7 @@
## プロジェクトと仮想環境の作成
これは一度だけ行えば大丈夫です。
この作業は一度だけ行えば十分です。
```bash
mkdir my_project
@ -10,9 +10,9 @@ cd my_project
python -m venv .venv
```
### 仮想環境をアクティブにする
### 仮想環境の有効化
新しいターミナルセッションを開始するたびに行ってください。
新しいターミナルセッションを開始するたびに、これを実行してください。
```bash
source .venv/bin/activate
@ -26,7 +26,7 @@ pip install openai-agents # or `uv add openai-agents`, etc
### OpenAI API キーの設定
お持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。
まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。
```bash
export OPENAI_API_KEY=sk-...
@ -34,7 +34,7 @@ export OPENAI_API_KEY=sk-...
## 最初のエージェントを作成する
エージェントは、instructions、名前、オプションの設定（`model_config` など）で定義されます。
エージェントは instructions、名前、およびオプションの設定（例： `model_config` ）で定義します。
```python
from agents import Agent
@ -47,7 +47,7 @@ agent = Agent(
## さらにエージェントを追加する
追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフルーティングを決定するための追加のコンテキストを提供します。
追加のエージェントも同様の方法で定義できます。 `handoff_descriptions` は、ハンドオフのルーティングを判断するための追加コンテキストを提供します。
```python
from agents import Agent
@ -67,7 +67,7 @@ math_tutor_agent = Agent(
## ハンドオフを定義する
各エージェントで、タスクを進める方法を決定するための送信ハンドオフオプションのインベントリを定義できます。
各エージェントで、タスクを進めるために選択できる送信先ハンドオフオプションのインベントリを定義できます。
```python
triage_agent = Agent(
@ -77,9 +77,9 @@ triage_agent = Agent(
)
```
## エージェントオーケストレーションを実行する
## エージェントのオーケストレーションを実行する
ワークフローが実行され、トリアージエージェントが2つの専門エージェント間を正しくルーティングするか確認しましょう。
ワークフローが正しく動作し、トリアージエージェントが 2 つの専門エージェント間で正しくルーティングするか確認しましょう。
```python
from agents import Runner
@ -91,7 +91,7 @@ async def main():
## ガードレールを追加する
入力または出力に対してカスタムガードレールを定義できます。
入力または出力に対して実行するカスタムガードレールを定義できます。
```python
from agents import GuardrailFunctionOutput, Agent, Runner
@ -118,7 +118,7 @@ async def homework_guardrail(ctx, agent, input_data):
## すべてをまとめる
すべてをまとめて、ハンドオフと入力ガードレールを使用して全体のワークフローを実行しましょう。
すべてを組み合わせて、ハンドオフと入力ガードレールを使ったワークフロー全体を実行してみましょう。
```python
from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner
@ -176,14 +176,14 @@ if __name__ == "__main__":
asyncio.run(main())
```
## トレースを表示する
## トレースを確認する
エージェントの実行中に何が起こったかを確認するには、[OpenAI ダッシュボードのトレースビューア](https://platform.openai.com/traces)に移動して、エージェント実行のトレースを表示してください。
エージェントの実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) にアクセスして、エージェント実行のトレースを表示してください。
## 次のステップ
より複雑なエージェントフローの構築方法を学びましょう：
- [エージェント](agents.md)の設定方法を学ぶ。
- [エージェントの実行](running_agents.md)について学ぶ。
- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models.md)について学ぶ。
- [エージェント](agents.md) の設定方法について学ぶ
- [エージェントの実行](running_agents.md) について学ぶ
- [tools](tools.md)、[guardrails](guardrails.md)、[models](models.md) について学ぶ

38
docs/ja/results.md
View file

@ -1,52 +1,52 @@
# 結果
`Runner.run` メソッドを呼び出すと、次のいずれかが得られます：
`Runner.run` メソッドを呼び出すと、以下のいずれかが返されます:
- `run` または `run_sync` を呼び出すと [`RunResult`][agents.result.RunResult]
- `run_streamed` を呼び出すと [`RunResultStreaming`][agents.result.RunResultStreaming]
- `run` または `run_sync` を呼び出した場合は、[`RunResult`][agents.result.RunResult]
- `run_streamed` を呼び出した場合は、[`RunResultStreaming`][agents.result.RunResultStreaming]
これらはどちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここにあります。
これらはどちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれています。
## 最終出力
[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれています。これは次のいずれかです：
[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が格納されます。これは以下のいずれかです:
- `output_type` が定義されていない場合は `str`
- エージェントに出力タイプが定義されている場合は `last_agent.output_type` のオブジェクト
- 最後のエージェントに `output_type` が定義されていない場合は `str`
- エージェントに `output_type` が定義されている場合は、`last_agent.output_type` 型のオブジェクト
!!! note
`final_output` は `Any` 型です。ハンドオフのため、静的に型を指定することはできません。ハンドオフが発生すると、どのエージェントが最後になるか分からないため、可能な出力タイプのセットを静的に知ることはできません。
`final_output` の型は `Any` です。ハンドオフのため、静的に型を決定することはできません。ハンドオフが発生した場合、どのエージェントが最後になるか分からないため、出力型の集合を静的に知ることができません。
## 次のターンの入力
## 次のターンへの入力
[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使用して、結果を入力リストに変換できます。これにより、提供した元の入力をエージェント実行中に生成されたアイテムに連結します。これにより、1つのエージェント実行の出力を別の実行に渡したり、ループで実行して毎回新しいユーザー入力を追加したりするのが便利になります。
[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うことで、実行結果を入力リストに変換できます。これは、あなたが提供した元の入力と、エージェント実行中に生成されたアイテムを連結したものです。これにより、あるエージェント実行の出力を別の実行に渡したり、ループで実行して毎回新しいユーザー入力を追加したりするのが簡単になります。
## 最後のエージェント
[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが含まれています。アプリケーションによっては、次回ユーザーが何かを入力する際に役立つことがよくあります。たとえば、フロントラインのトリアージエージェントが言語特定のエージェントにハンドオフする場合、最後のエージェントを保存し、次回ユーザーがエージェントにメッセージを送信する際に再利用できます。
[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが格納されます。アプリケーションによっては、次回ユーザーが何か入力した際にこれが役立つことがよくあります。たとえば、フロントラインのトリアージエージェントが言語特化エージェントにハンドオフする場合、最後のエージェントを保存しておき、次回ユーザーがエージェントにメッセージを送る際に再利用できます。
## 新しいアイテム
[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれています。アイテムは [`RunItem`][agents.items.RunItem] です。実行アイテムは LLM によって生成された raw アイテムをラップします。
[`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 アイテムはハンドオフツール呼び出しへのツール応答です。アイテムからソース/ターゲットエージェントにもアクセスできます。
- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフツールを呼び出したことを示します。raw アイテムは LLM からのツールコールアイテムです。
- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。raw アイテムはハンドオフツールコールへのツールレスポンスです。また、アイテムからソース/ターゲットエージェントにもアクセスできます。
- [`ToolCallItem`][agents.items.ToolCallItem] は LLM がツールを呼び出したことを示します。
- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが呼び出されたことを示します。raw アイテムはツール応答です。アイテムからツール出力にもアクセスできます。
- [`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] プロパティには、ガードレールの結果が含まれています。ガードレール結果には、ログや保存に役立つ情報が含まれることがあるため、これらを利用可能にしています。
[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] および [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの結果（存在する場合）が格納されます。ガードレール結果には、ログや保存に役立つ有用な情報が含まれることがあるため、これらを利用できるようにしています。
### Raw 応答
### raw レスポンス
[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれています。
[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が格納されます。
### 元の入力
[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに提供した元の入力が含まれています。ほとんどの場合、これを必要としませんが、必要な場合に備えて利用可能です。
[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに提供した元の入力が格納されます。ほとんどの場合これは必要ありませんが、必要な場合のために利用可能です。

70
docs/ja/running_agents.md
View file

@ -1,10 +1,10 @@
# エージェントの実行
エージェントは [`Runner`][agents.run.Runner] クラスを通じて実行できます。3つのオプションがあります：
エージェントは [`Runner`][agents.run.Runner] クラスを使って実行できます。3 つのオプションがあります。
1. 非同期で実行し、[`RunResult`][agents.result.RunResult] を返す [`Runner.run()`][agents.run.Runner.run]。
2. 同期メソッドで、内部で `.run()` を実行する [`Runner.run_sync()`][agents.run.Runner.run_sync]。
3. 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返す [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。ストリーミングモードで LLM を呼び出し、受信したイベントをストリームします。
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
@ -19,53 +19,53 @@ async def main():
# Infinite loop's dance.
```
詳細は[結果ガイド](results.md)をご覧ください。
詳細は [results guide](results.md) をご覧ください。
## エージェントループ
`Runner` の実行メソッドを使用する際、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージと見なされる）または OpenAI Responses API のアイテムリストのいずれかです。
`Runner` の run メソッドを使用する際、開始するエージェントと入力を渡します。入力は文字列（ユーザーメッセージと見なされます）または入力アイテムのリスト（OpenAI Responses API のアイテム）を指定できます。
ランナーは次のループを実行します：
runner は次のようなループを実行します。
1. 現在のエージェントと入力で LLM を呼び出します。
2. LLM が出力を生成します。
1. LLM が `final_output` を返すと、ループは終了し、結果を返します。
2. LLM がハンドオフを行う場合、現在のエージェントと入力を更新し、ループを再実行します。
3. LLM がツール呼び出しを生成する場合、それらを実行し、結果を追加し、ループを再実行します。
1. LLM が `final_output` を返した場合、ループは終了し、結果を返します。
2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。
3. LLM がツール呼び出しを生成した場合、それらのツール呼び出しを実行し、結果を追加してループを再実行します。
3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を発生させます。
!!! note
LLM の出力が「最終出力」と見なされるかどうかのルールは、望ましいタイプのテキスト出力を生成し、ツール呼び出しがないことです。
LLM の出力が「final output」と見なされるルールは、希望する型のテキスト出力が生成され、ツール呼び出しがない場合です。
## ストリーミング
ストリーミングを使用すると、LLM が実行される際にストリーミングイベントを受け取ることができます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] は実行に関する完全な情報を含み、生成されたすべての新しい出力を含みます。ストリーミングイベントには `.stream_events()` を呼び出せます。[ストリーミングガイド](streaming.md)で詳細を確認してください。
ストリーミングを利用すると、LLM の実行中にストリーミングイベントを受け取ることができます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に実行に関するすべての情報（新たに生成されたすべての出力を含む）が格納されます。ストリーミングイベントは `.stream_events()` で取得できます。詳細は [streaming guide](streaming.md) をご覧ください。
## 実行設定
## Run config
`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]: すべてのトレースに含めるメタデータ。
- [`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]：すべてのトレースに含めるメタデータです。
## 会話/チャットスレッド
## 会話・チャットスレッド
いずれかの実行メソッドを呼び出すと、1つ以上のエージェントが実行される可能性があります（したがって、1つ以上の LLM 呼び出しが行われます）が、チャット会話の単一の論理ターンを表します。例えば：
いずれかの run メソッドを呼び出すと、1 つまたは複数のエージェント（および 1 つまたは複数の LLM 呼び出し）が実行されますが、チャット会話における 1 回の論理的なターンを表します。例：
1. ユーザーターン：ユーザーがテキストを入力
2. ランナー実行：最初のエージェントが LLM を呼び出し、ツールを実行し、2番目のエージェントにハンドオフし、2番目のエージェントがさらにツールを実行し、出力を生成します。
1. ユーザーのターン：ユーザーがテキストを入力
2. Runner の実行：最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントにハンドオフ、2 番目のエージェントがさらにツールを実行し、出力を生成
エージェント実行の終了時に、ユーザーに何を表示するかを選択できます。例えば、エージェントによって生成されたすべての新しいアイテムをユーザーに表示するか、最終出力のみを表示するかです。いずれにせよ、ユーザーがフォローアップの質問をする可能性があり、その場合は再度実行メソッドを呼び出すことができます。
エージェントの実行が終わったら、ユーザーに何を表示するか選択できます。たとえば、エージェントが生成したすべての新しいアイテムをユーザーに見せることも、最終出力だけを見せることもできます。いずれの場合も、ユーザーが追加の質問をした場合は、再度 run メソッドを呼び出せます。
次のターンの入力を取得するには、基本の [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用できます。
次のターンの入力を取得するには、ベースの [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用できます。
```python
async def main():
@ -86,10 +86,10 @@ async def main():
## 例外
SDK は特定のケースで例外を発生させます。完全なリストは [`agents.exceptions`][] にあります。概要は以下の通りです：
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)が作動した場合に発生します。
- [`AgentsException`][agents.exceptions.AgentsException]：SDK で発生するすべての例外の基底クラスです。
- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]：run メソッドに渡した `max_turns` を超えた場合に発生します。
- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：モデルが不正な出力（例：不正な JSON や存在しないツールの使用）を生成した場合に発生します。
- [`UserError`][agents.exceptions.UserError]：SDK を使用する際に、あなた（SDK を使ってコードを書く人）がエラーを起こした場合に発生します。
- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]：[ガードレール](guardrails.md) が作動した場合に発生します。

16
docs/ja/streaming.md
View file

@ -1,14 +1,14 @@
# ストリーミング
ストリーミングを使用すると、エージェントの実行が進行する際の更新を購読できます。これは、エンドユーザーに進捗状況の更新や部分的な応答を表示するのに役立ちます。
ストリーミングを利用すると、エージェントの実行が進行するにつれて、その更新情報を購読できます。これは、エンドユーザーに進捗状況や部分的な応答を表示するのに役立ちます。
ストリーミングを行うには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより、[`RunResultStreaming`][agents.result.RunResultStreaming] が得られます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。
ストリーミングを行うには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより、[`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。`result.stream_events()` を呼び出すと、下記で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。
## Raw response events
## raw response events
[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API フォーマットであり、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。これらのイベントは、生成され次第、ユーザーに応答メッセージをストリーミングしたい場合に便利です。
[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API フォーマットであり、各イベントには type（例：`response.created`、`response.output_text.delta` など）とデータが含まれます。これらのイベントは、応答メッセージが生成され次第、ユーザーにストリーミングしたい場合に便利です。
例えば、これは LLM によってトークンごとに生成されたテキストを出力します。
例えば、以下の例では LLM が生成したテキストをトークンごとに出力します。
```python
import asyncio
@ -31,11 +31,11 @@ if __name__ == "__main__":
asyncio.run(main())
```
## 実行アイテムイベントとエージェントイベント
## Run item イベントとエージェントイベント
[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたときに通知します。これにより、「メッセージが生成された」、「ツールが実行された」などのレベルで進捗状況を更新することができます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例えば、ハンドオフの結果として）に更新を提供します。
[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルなイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、「メッセージが生成された」「ツールが実行された」など、各トークン単位ではなく、進捗状況をまとめてユーザーに伝えることができます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例：ハンドオフの結果として）に更新情報を提供します。
例えば、これは raw イベントを無視し、ユーザーに更新をストリーミングします。
例えば、以下の例では raw イベントを無視し、ユーザーに更新情報のみをストリーミングします。
```python
import asyncio

70
docs/ja/tools.md
View file

@ -1,18 +1,18 @@
# ツール
ツールはエージェントがアクションを実行するためのものです。データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などが含まれます。Agent SDK には3つのクラスのツールがあります。
ツールは エージェント がアクションを実行するためのものです。たとえば、データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などが含まれます。Agents SDK には 3 種類のツールクラスがあります。
- ホストされたツール: これらは LLM サーバー上で AI モデルと一緒に実行されます。OpenAI は、リトリーバル、Web 検索、コンピュータ操作をホストされたツールとして提供しています。
- 関数呼び出し: 任意の Python 関数をツールとして使用できます。
- エージェントをツールとして使用: エージェントをツールとして使用し、エージェントが他のエージェントをハンドオフせずに呼び出すことができます。
- Hosted tools: これらは LLM サーバー上で AI モデルとともに実行されます。OpenAI は retrieval、Web 検索、コンピュータ操作を Hosted tools として提供しています。
- Function calling: 任意の Python 関数をツールとして利用できます。
- Agents as tools: エージェントをツールとして利用でき、エージェントが他のエージェントをハンドオフせずに呼び出すことができます。
## ホストされたツール
## Hosted tools
OpenAI は、[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際にいくつかの組み込みツールを提供しています。
OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供しています。
- [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントが Web 検索を行うことを可能にします。
- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得することを可能にします。
- [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化することを可能にします。
- [`WebSearchTool`][agents.tool.WebSearchTool] は、エージェントが Web 検索を行うことを可能にします。
- [`FileSearchTool`][agents.tool.FileSearchTool] は、OpenAI ベクトルストアから情報を取得できます。
- [`ComputerTool`][agents.tool.ComputerTool] は、コンピュータ操作タスクの自動化を可能にします。
```python
from agents import Agent, FileSearchTool, Runner, WebSearchTool
@ -33,16 +33,16 @@ async def main():
print(result.final_output)
```
## 関数ツール
## Function tools
任意の Python 関数をツールとして使用できます。Agents SDK はツールを自動的にセットアップします。
任意の Python 関数をツールとして利用できます。Agents SDK が自動的にツールをセットアップします。
- ツールの名前は Python 関数の名前になります（または名前を指定できます）
- ツールの説明は関数の docstring から取得されます（または説明を指定できます）
- 関数入力のスキーマは関数の引数から自動的に作成されます
- 各入力の説明は、無効にしない限り、関数の docstring から取得されます
- ツール名は Python 関数名になります（または任意の名前を指定できます）
- ツールの説明は関数の docstring から取得されます（または任意の説明を指定できます）
- 関数の引数から自動的に入力スキーマが作成されます
- 各入力の説明は、関数の docstring から取得されます（無効化も可能です）
Python の `inspect` モジュールを使用して関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) を使用して docstring を解析し、`pydantic` を使用してスキーマを作成します。
Python の `inspect` モジュールを使って関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、`pydantic` でスキーマを作成します。
```python
import json
@ -94,12 +94,12 @@ for tool in agent.tools:
```
1. 任意の Python 型を関数の引数として使用でき、関数は同期または非同期であることができます。
2. Docstring が存在する場合、説明や引数の説明を取得するために使用されます。
3. 関数はオプションで `context` を取ることができ（最初の引数である必要があります）、ツールの名前、説明、使用する docstring スタイルなどのオーバーライドを設定できます。
4. デコレートされた関数をツールのリストに渡すことができます。
1. 関数の引数には任意の Python 型を利用でき、同期・非同期どちらの関数も利用可能です。
2. docstring があれば、説明や引数の説明として利用されます。
3. 関数はオプションで `context` を最初の引数として受け取れます。また、ツール名や説明、docstring スタイルの指定などのオーバーライドも可能です。
4. デコレートした関数をツールのリストに渡すことができます。
??? note "出力を表示するには展開してください"
??? note "出力を展開して表示"
```
fetch_weather
@ -169,14 +169,14 @@ for tool in agent.tools:
}
```
### カスタム関数ツール
### カスタム function tools
時には、Python 関数をツールとして使用したくない場合もあります。その場合、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。以下を提供する必要があります。
場合によっては、Python 関数をツールとして使いたくないこともあります。その場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。必要な情報は以下の通りです。
- `name`
- `description`
- `params_json_schema`（引数の JSON スキーマ）
- `on_invoke_tool`（コンテキストと引数を JSON 文字列として受け取り、ツールの出力を文字列として返す非同期関数）
- `on_invoke_tool`（context と引数（JSON 文字列）を受け取り、ツールの出力を文字列で返す async 関数）
```python
from typing import Any
@ -211,16 +211,16 @@ tool = FunctionTool(
### 引数と docstring の自動解析
前述のように、ツールのスキーマを抽出するために関数シグネチャを自動的に解析し、ツールおよび個々の引数の説明を抽出するために docstring を解析します。以下の点に注意してください。
前述の通り、関数シグネチャを自動解析してツールのスキーマを抽出し、docstring からツールや各引数の説明を抽出します。主なポイントは以下の通りです。
1. シグネチャの解析は `inspect` モジュールを通じて行われます。引数の型を理解するために型注釈を使用し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本コンポーネント、Pydantic モデル、TypedDict など、ほとんどの型をサポートしています。
2. `griffe` を使用して docstring を解析します。サポートされている docstring フォーマットは `google`、`sphinx`、`numpy` です。docstring フォーマットを自動的に検出しようとしますが、これはベストエフォートであり、`function_tool` を呼び出す際に明示的に設定できます。`use_docstring_info` を `False` に設定することで docstring 解析を無効にすることもできます。
1. シグネチャの解析は `inspect` モジュールで行います。型アノテーションを利用して引数の型を把握し、Pydantic モデルを動的に構築して全体のスキーマを表現します。Python の基本コンポーネント、Pydantic モデル、TypedDict など、ほとんどの型をサポートしています。
2. docstring の解析には `griffe` を使用します。サポートされている docstring フォーマットは `google`、`sphinx`、`numpy` です。docstring フォーマットは自動検出を試みますが、`function_tool` 呼び出し時に明示的に指定することもできます。`use_docstring_info` を `False` に設定することで docstring 解析を無効化できます。
スキーマ抽出のコードは [`agents.function_schema`][] にあります。
## エージェントをツールとして使用
## Agents as tools
一部のワークフローでは、中央のエージェントが専門エージェントのネットワークをオーケストレーションすることを望むかもしれません。これを行うには、エージェントをツールとしてモデル化します。
一部のワークフローでは、ハンドオフせずに中央のエージェントが専門エージェントのネットワークをオーケストレーションしたい場合があります。その場合、エージェントをツールとしてモデル化することで実現できます。
```python
from agents import Agent, Runner
@ -259,12 +259,12 @@ async def main():
print(result.final_output)
```
## 関数ツールでのエラー処理
## Function tools でのエラー処理
`@function_tool` を使用して関数ツールを作成する際、`failure_error_function` を渡すことができます。これは、ツール呼び出しがクラッシュした場合に LLM にエラーレスポンスを提供する関数です。
`@function_tool` で function tool を作成する際、`failure_error_function` を渡すことができます。これは、ツール呼び出しがクラッシュした場合に LLM へエラー応答を提供する関数です。
- デフォルトでは（何も渡さない場合）、`default_tool_error_function` が実行され、LLM にエラーが発生したことを伝えます。
- 独自のエラー関数を渡した場合、それが実行され、LLM にレスポンスが送信されます。
- 明示的に `None` を渡した場合、ツール呼び出しエラーは再度発生し、処理する必要があります。モデルが無効な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などが考えられます。
- デフォルト（何も渡さない場合）では、`default_tool_error_function` が実行され、LLM にエラーが発生したことを伝えます。
- 独自のエラー関数を渡した場合は、それが実行され、その応答が LLM に送信されます。
- 明示的に `None` を渡した場合、ツール呼び出し時のエラーは再スローされ、ユーザー側で処理できます。たとえば、モデルが無効な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などです。
`FunctionTool` オブジェクトを手動で作成する場合、`on_invoke_tool` 関数内でエラーを処理する必要があります。
`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラー処理を行う必要があります。

128
docs/ja/tracing.md
View file

@ -1,51 +1,51 @@
# トレーシング
Agents SDK には組み込みのトレーシング機能があり、エージェント実行中のイベント（LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、カスタムイベントなど）の包括的な記録を収集します。[Traces ダッシュボード](https://platform.openai.com/traces)を使用して、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。
Agents SDK にはトレーシング機能が組み込まれており、エージェントの実行中に発生するイベント（ LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、カスタムイベントなど）の包括的な記録を収集します。[Traces ダッシュボード](https://platform.openai.com/traces) を使用することで、開発中や本番環境でワークフローのデバッグ、可視化、監視が可能です。
!!!note
トレーシングはデフォルトで有効です。トレーシングを無効にする方法は2つあります:
トレーシングはデフォルトで有効になっています。トレーシングを無効にする方法は 2 つあります:
1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効にすることができます。
2. [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して、単一の実行でトレーシングを無効にすることができます。
1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定することで、グローバルにトレーシングを無効化できます。
2. 単一の実行に対しては [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定することで無効化できます。
***OpenAI の API を使用している Zero Data Retention (ZDR) ポリシーの下で運営されている組織では、トレーシングは利用できません。***
***OpenAI の API を使用し、Zero Data Retention (ZDR) ポリシーの下で運用している組織では、トレーシングは利用できません。***
## トレースとスパン
- **トレース** は「ワークフロー」の単一のエンドツーエンドの操作を表します。スパンで構成されています。トレースには以下のプロパティがあります:
- `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service"。
- `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` でなければなりません。
- `group_id`: 同じ会話からの複数のトレースをリンクするためのオプションのグループ ID。例: チャットスレッド ID。
- `disabled`: True の場合、トレースは記録されません。
- `metadata`: トレースのオプションのメタデータ。
- **スパン** は開始時間と終了時間を持つ操作を表します。スパンには以下があります:
- `started_at` と `ended_at` のタイムスタンプ。
- 所属するトレースを表す `trace_id`
- 親スパンを指す `parent_id`（ある場合）
- スパンに関する情報を含む `span_data`。例: `AgentSpanData` はエージェントに関する情報を含み、`GenerationSpanData` は LLM の生成に関する情報を含みます。
- **トレース** は 1 つの「ワークフロー」のエンドツーエンドの操作を表します。トレースはスパンで構成されます。トレースには以下のプロパティがあります:
- `workflow_name`: 論理的なワークフローやアプリ名です。例: "Code generation" や "Customer service" など。
- `trace_id`: トレースの一意な ID です。指定しない場合は自動生成されます。フォーマットは `trace_<32_alphanumeric>` である必要があります。
- `group_id`: オプションのグループ ID で、同じ会話からの複数のトレースをリンクするために使用します。例: チャットスレッド ID など。
- `disabled`: True の場合、このトレースは記録されません。
- `metadata`: トレースに付加するオプションのメタデータです。
- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには以下があります:
- `started_at` および `ended_at` タイムスタンプ
- 所属するトレースを示す `trace_id`
- このスパンの親スパンを指す `parent_id`（存在する場合）
- スパンに関する情報を含む `span_data`。例: `AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報など。
## デフォルトのトレーシング
デフォルトで、SDK は以下をトレースします:
デフォルトでは、 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()` の下に配置されることがあります。
- `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] で名前やその他のプロパティを設定できます。
デフォルトでは、トレース名は "Agent trace" です。`trace` を使用する場合、この名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定することも可能です。
さらに、[カスタムトレースプロセッサー](#custom-tracing-processors)を設定して、トレースを他の宛先に送信することもできます（置き換えまたは二次的な宛先として）。
さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを他の宛先に送信することもできます（置き換えや追加の宛先として）。
## 高レベルのトレース
## より高レベルのトレース
時には、複数の `run()` 呼び出しを単一のトレースの一部にしたいことがあります。これを行うには、コード全体を `trace()` でラップします。
複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合、コード全体を `trace()` でラップしてください。
```python
from agents import Agent, Runner, trace
@ -60,57 +60,57 @@ async def main():
print(f"Rating: {second_result.final_output}")
```
1. `Runner.run` への2つの呼び出しが `with trace()` でラップされているため、個々の実行は2つのトレースを作成するのではなく、全体のトレースの一部になります。
1. 2 回の `Runner.run` 呼び出しが `with trace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部となります。
## トレースの作成
[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。以下の2つの方法があります:
[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります:
1. **推奨**: トレースをコンテキストマネージャーとして使用します。つまり、`with trace(...) as my_trace` とします。これにより、トレースが自動的に適切なタイミングで開始および終了します。
2. 手動で [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を呼び出すこともできます。
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` を渡して現在のトレースを更新する必要があります。
現在のトレースは 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] 関数が利用可能です。
さまざまな [`*_span()`][agents.tracing.create] メソッドを使ってスパンを作成できます。通常、スパンを手動で作成する必要はありません。カスタムスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数も用意されています。
スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を介して追跡される最も近い現在のスパンの下にネストされます。
スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの下にネストされます。これは 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] を使用してそのデータのキャプチャを無効にすることができます。
`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] を設定します。
同様に、音声スパンはデフォルトで入力・出力音声の base64 エンコード PCM データを含みます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定することで、この音声データの記録を無効化できます。
## カスタムトレーシングプロセッサー
## カスタムトレースプロセッサー
トレーシングの高レベルアーキテクチャは次のとおりです:
トレーシングの高レベルなアーキテクチャは以下の通りです:
- 初期化時に、トレースを作成する責任を持つグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。
- `TraceProvider` を [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成し、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信し、OpenAI バックエンドにバッチでスパンとトレースをエクスポートします。
- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、トレースの生成を担当します。
- `TraceProvider` は [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成されており、トレースやスパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。これにより、スパンやトレースが OpenAI バックエンドにバッチでエクスポートされます。
このデフォルトのセットアップをカスタマイズして、トレースを代替または追加のバックエンドに送信したり、エクスポーターの動作を変更したりするには、次の2つのオプションがあります:
このデフォルト設定をカスタマイズし、トレースを別のバックエンドや追加のバックエンドに送信したり、エクスポーターの動作を変更したりするには、2 つの方法があります:
1. [`add_trace_processor()`][agents.tracing.add_trace_processor] を使用して、トレースとスパンが準備できたときに受け取る**追加の**トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドにトレースを送信することに加えて、独自の処理を行うことができます。
2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を使用して、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換える**ことができます。これにより、`TracingProcessor` を含めない限り、トレースは OpenAI バックエンドに送信されません。
1. [`add_trace_processor()`][agents.tracing.add_trace_processor] を使うと、**追加の** トレースプロセッサーを追加できます。これにより、トレースやスパンが準備できた時点で独自の処理を行うことができ、OpenAI バックエンドへの送信に加えて独自の処理が可能です。
2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を使うと、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換える**ことができます。この場合、OpenAI バックエンドにトレースが送信されるのは、`TracingProcessor` を含めた場合のみです。
## 外部トレーシングプロセッサーリスト
## 外部トレースプロセッサー一覧
- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents)
- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk)
- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing)
- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk)
- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents)
- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk)
- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration)
- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent)
- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk)
- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk)
- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents)
- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents)
- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk)
- [Okahu-Monocle](https://github.com/monocle2ai/monocle)
- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents)
- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk)
- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing)
- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk)
- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents)
- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk)
- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration)
- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent)
- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk)
- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk)
- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents)
- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents)
- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk)
- [Okahu-Monocle](https://github.com/monocle2ai/monocle)

27
docs/ja/visualization.md
View file

@ -1,10 +1,10 @@
# エージェントの可視化
エージェントの可視化では、**Graphviz** を使用してエージェントとその関係の構造化されたグラフィカル表現を生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。
エージェントの可視化では、 **Graphviz** を使用してエージェントとその関係性を構造的にグラフィカルに表現できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用しているかを理解するのに役立ちます。
## インストール
オプションの `viz` 依存関係グループをインストールします:
オプションの `viz` 依存グループをインストールします:
```bash
pip install "openai-agents[viz]"
@ -12,11 +12,11 @@ pip install "openai-agents[viz]"
## グラフの生成
`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は、以下のような有向グラフを作成します:
`draw_graph` 関数を使ってエージェントの可視化を生成できます。この関数は、以下のような有向グラフを作成します:
- **エージェント** は黄色のボックスで表されます。
- **ツール** は緑色の楕円で表されます。
- **ハンドオフ** はあるエージェントから別のエージェントへの有向エッジです。
- **ハンドオフ** は、あるエージェントから別のエージェントへの有向エッジで表されます。
### 使用例
@ -50,31 +50,32 @@ draw_graph(triage_agent)
![Agent Graph](../assets/images/graph.png)
これにより、**トリアージエージェント** の構造とサブエージェントおよびツールへの接続を視覚的に表現するグラフが生成されます。
これにより、 **triage agent** の構造とサブエージェントやツールとの接続が視覚的に表現されたグラフが生成されます。
## 可視化の理解
生成されたグラフには以下が含まれます:
- エントリーポイントを示す **開始ノード** (`__start__`)。
- 黄色で塗りつぶされた **長方形** で表されるエージェント。
- 緑色で塗りつぶされた **楕円** で表されるツール。
- エントリーポイントを示す **start node** (`__start__`)
- 黄色で塗りつぶされた **長方形** で表されるエージェント
- 緑色で塗りつぶされた **楕円** で表されるツール
- 相互作用を示す有向エッジ:
- エージェント間のハンドオフには **実線の矢印**。
- ツール呼び出しには **点線の矢印**。
- 実行が終了する場所を示す **終了ノード** (`__end__`)。
- エージェント間のハンドオフには **実線の矢印**
- ツール呼び出しには **点線の矢印**
- 実行が終了する場所を示す **end node** (`__end__`)
## グラフのカスタマイズ
### グラフの表示
デフォルトでは、`draw_graph` はグラフをインラインで表示します。別ウィンドウでグラフを表示するには、次のように記述します:
デフォルトでは、`draw_graph` はグラフをインラインで表示します。グラフを別ウィンドウで表示したい場合は、次のように記述します:
```python
draw_graph(triage_agent).view()
```
### グラフの保存
デフォルトでは、`draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します:
デフォルトでは、`draw_graph` はグラフをインラインで表示します。ファイルとして保存したい場合は、ファイル名を指定します:
```python
draw_graph(triage_agent, filename="agent_graph.png")

30
docs/ja/voice/pipeline.md
View file

@ -1,6 +1,6 @@
# パイプラインとワークフロー
[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントのワークフローを音声アプリに変換するのを簡単にするクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声の終了検出、適切なタイミングでのワークフロー呼び出し、ワークフロー出力の音声化を行います。
[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントワークフローを音声アプリに簡単に変換できるクラスです。実行したいワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、ワークフロー出力の音声化までを自動で処理します。
```mermaid
graph LR
@ -30,28 +30,28 @@ graph LR
## パイプラインの設定
パイプラインを作成する際に、以下のことを設定できます：
パイプラインを作成する際、以下の項目を設定できます。
1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]：新しい音声が文字起こしされるたびに実行されるコード。
2. 使用する [`speech-to-text`][agents.voice.model.STTModel] および [`text-to-speech`][agents.voice.model.TTSModel] モデル。
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 モデルの設定：プロンプト、言語、使用するデータ型など。
- モデルプロバイダー：モデル名をモデルにマッピングできます
- トレーシング：トレーシングの有効/無効、音声ファイルのアップロード有無、ワークフロー名、トレース ID など
- TTS および STT モデルの設定：プロンプト、言語、使用するデータ型など
## パイプラインの実行
パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドを通じて実行できます。これにより、2 つの形式で音声入力を渡すことができます：
パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は 2 つの形式で渡せます。
1. [`AudioInput`][agents.voice.input.AudioInput]：完全な音声トランスクリプトがある場合に使用し、その結果を生成するだけです。これは、話者が話し終わったときの検出が不要な場合に便利です。例えば、事前録音された音声や、ユーザーが話し終わったことが明確なプッシュ・トゥ・トークアプリで使用します。
2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]：ユーザーが話し終わったときの検出が必要な場合に使用します。音声チャンクを検出時にプッシュでき、音声パイプラインが自動的にエージェントワークフローを適切なタイミングで実行します。これは「アクティビティ検出」と呼ばれるプロセスを通じて行われます。
1. [`AudioInput`][agents.voice.input.AudioInput]：完全な音声トランスクリプトがある場合に使用し、その内容に対する結果のみを生成します。話者が話し終えたタイミングを検出する必要がない場合（例：事前録音音声や push-to-talk アプリなど、ユーザーが話し終えたことが明確な場合）に便利です。
2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]：ユーザーが話し終えたタイミングを検出する必要がある場合に使用します。音声チャンクを検出ごとにプッシュでき、VoicePipeline が「アクティビティ検出」と呼ばれるプロセスを通じて、適切なタイミングでエージェントワークフローを自動実行します。
## 結果
音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、イベントが発生するたびにストリーミングできるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があります：
VoicePipeline 実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、イベントが発生するたびにストリーミングで受け取れるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があります。
1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]：音声チャンクを含むイベント。
2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]：ターンの開始や終了などのライフサイクルイベントを通知します。
1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]：音声チャンクを含みます。
2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]：ターンの開始や終了など、ライフサイクルイベントを通知します。
3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]：エラーイベントです。
```python
@ -70,6 +70,6 @@ async for event in result.stream():
## ベストプラクティス
### 中断
### 割り込み
Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの中断サポートを提供していません。代わりに、検出されたターンごとにワークフローの別の実行をトリガーします。アプリケーション内で中断を処理したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視できます。`turn_started` は新しいターンが文字起こしされ、処理が始まったことを示します。`turn_ended` は、関連するすべての音声が送信された後にトリガーされます。これらのイベントを使用して、モデルがターンを開始したときにスピーカーのマイクをミュートし、関連する音声をすべてフラッシュした後にアンミュートすることができます。
Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートを提供していません。そのため、検出された各ターンごとにワークフローの個別実行がトリガーされます。アプリケーション内で割り込みを処理したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントをリッスンできます。`turn_started` は新しいターンが文字起こしされ、処理が開始されたことを示します。`turn_ended` は該当ターンのすべての音声が送信された後にトリガーされます。これらのイベントを利用して、モデルがターンを開始した際に話者のマイクをミュートし、ターンに関連するすべての音声を送信し終えた後にアンミュートする、といった制御が可能です。

18
docs/ja/voice/quickstart.md
View file

@ -2,7 +2,7 @@
## 前提条件
Agents SDK の基本的な[クイックスタート手順](../quickstart.md)に従い、仮想環境を設定してください。その後、SDK からオプションの音声依存関係をインストールします。
Agents SDK の[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしてください。その後、SDK からオプションの音声依存関係をインストールします。
```bash
pip install 'openai-agents[voice]'
@ -10,11 +10,11 @@ pip install 'openai-agents[voice]'
## コンセプト
知っておくべき主なコンセプトは、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは3ステップのプロセスです。
主なコンセプトは [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 ステップのプロセスです：
1. 音声をテキストに変換する音声認識モデルを実行します。
2. 通常はエージェントワークフローであるコードを実行して、結果を生成します。
3. 結果のテキストを音声に戻すテキスト読み上げモデルを実行します。
1. 音声をテキストに変換する音声認識モデル（speech-to-text）を実行します。
2. 通常はエージェント的なワークフローであるあなたのコードを実行し、結果を生成します。
3. 結果のテキストを音声に戻す音声合成モデル（text-to-speech）を実行します。
```mermaid
graph LR
@ -44,7 +44,7 @@ graph LR
## エージェント
まず、いくつかのエージェントを設定しましょう。この SDK でエージェントを構築したことがある場合、これは馴染みがあるはずです。エージェント、ハンドオフ、ツールを用意します。
まず、いくつかのエージェントをセットアップしましょう。この SDK でエージェントを作成したことがあれば、馴染みがあるはずです。ここでは、複数のエージェント、ハンドオフ、ツールを用意します。
```python
import asyncio
@ -88,14 +88,14 @@ agent = Agent(
## 音声パイプライン
[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用して、シンプルな音声パイプラインを設定します。
[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使い、シンプルな音声パイプラインをセットアップします。
```python
from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline
pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
```
## パイプラインを実行する
## パイプラインの実行
```python
import numpy as np
@ -191,4 +191,4 @@ if __name__ == "__main__":
asyncio.run(main())
```
この例を実行すると、エージェントがあなたに話しかけます！ [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例をチェックして、自分でエージェントと話すデモを見てください。
この例を実行すると、エージェントがあなたに話しかけます！[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) のコード例をチェックして、実際にエージェントと会話できるデモをご覧ください。

18
docs/ja/voice/tracing.md
View file

@ -1,14 +1,14 @@
# トレーシング
[エージェントがトレースされる](../tracing.md)のと同様に、音声パイプラインも自動的にトレースされます。
[エージェントのトレーシング](../tracing.md)と同様に、音声パイプラインも自動的にトレーシングされます。
基本的なトレーシング情報については上記のトレーシングドキュメントを参照できますが、パイプラインのトレーシングは [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じて追加で設定できます。
基本的なトレーシング情報については上記のトレーシングドキュメントをご参照いただけますが、さらに [`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]: トレースに含める追加のメタデータです。
- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。
- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]：トレースに音声の書き起こしなど、機密性の高いデータを含めるかどうかを制御します。これは特に音声パイプライン用であり、Workflow 内部で発生する内容には適用されません。
- [`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]：トレースに追加するメタデータです。

21
docs/scripts/translate_docs.py
View file

@ -7,7 +7,7 @@ from concurrent.futures import ThreadPoolExecutor
# logging.basicConfig(level=logging.INFO)
# logging.getLogger("openai").setLevel(logging.DEBUG)
OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "gpt-4o")
OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "gpt-4.1")
# Define the source and target directories
source_dir = "docs"
@ -94,18 +94,17 @@ def built_instructions(target_language: str, lang_code: str) -> str:
)
return f"""You are an expert technical translator.
Your task: translate the markdown passed as a user input from English into {target_language}.
Your task: translate the markdown passed as a user input from English into {target_language}.
The inputs are the official OpenAI Agents SDK framework documentation, and your translation outputs'll be used for serving the official {target_language} version of them. Thus, accuracy, clarity, and fidelity to the original are critical.
############################
## OUTPUT REQUIREMENTS ##
############################
- Return **only** the translated markdown, with the original markdown structure preserved.
- Do **not** add explanations, comments, or metadata.
You must return **only** the translated markdown. Do not include any commentary, metadata, or explanations. The original markdown structure must be strictly preserved.
#########################
## GENERAL RULES ##
#########################
- The output quality must be great enough to be used for public documentation.
- Be professional and polite.
- Keep the tone **natural** and concise.
- Do not omit any content. If a segment should stay in English, copy it verbatim.
@ -149,9 +148,17 @@ Translate these terms exactly as provided (no extra spaces):
If you are uncertain about a term, leave the original English term in parentheses after your translation.
#########################
## FINAL REMINDER ##
## WORKFLOW ##
#########################
Return **only** the translated markdown text. No extra commentary.
Follow the following workflow to translate the given markdown text data:
1. Read the input markdown text given by the user.
2. Translate the markdown file into {target_language}, carefully following the requirements above.
3. Perform a self-review to evaluate the quality of the translation, focusing on naturalness, accuracy, and consistency in detail.
4. If improvements are necessary, refine the content without changing the original meaning.
5. Continue improving the translation until you are fully satisfied with the result.
6. Once the final output is ready, return **only** the translated markdown text. No extra commentary.
"""

2
mkdocs.yml
View file

@ -127,7 +127,7 @@ plugins:
nav:
- はじめに: index.md
- クイックスタート: quickstart.md
- サンプル例: examples.md
- コード例: examples.md
- ドキュメント:
- agents.md
- running_agents.md