diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index 9e160a20..0a0a5924 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -7,18 +7,18 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -Agents SDK は、標準で Responses API または Chat Completions API を通じて OpenAI モデルと動作します。別のモデルを使用したい場合は、[Vercel's AI SDK](https://sdk.vercel.ai/) がサポートするさまざまなモデルを、このアダプター経由で Agents SDK に組み込むことができます。 +初期状態で Agents SDK は Responses API または Chat Completions API を通じて OpenAI モデルと連携します。ただし別のモデルを使用したい場合は、[Vercel's AI SDK](https://sdk.vercel.ai/) が対応する多様なモデルを提供しており、このアダプター経由で Agents SDK に組み込むことができます。 ## セットアップ -1. extensions パッケージをインストールして AI SDK アダプターを追加します: +1. 拡張パッケージをインストールして AI SDK アダプターを追加します: ```bash npm install @openai/agents-extensions @@ -30,7 +30,7 @@ Agents SDK は、標準で Responses API または Chat Completions API を通 npm install @ai-sdk/openai ``` -3. エージェントに接続するためにアダプターとモデルをインポートします: +3. エージェントに接続するため、アダプターとモデルをインポートします: ```typescript import { openai } from '@ai-sdk/openai'; @@ -47,4 +47,4 @@ Agents SDK は、標準で Responses API または Chat Completions API を通 ## 例 - + diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index ad0e89d5..c43cf7db 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,27 +7,27 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio は [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しており、通話の元音声を WebSocket サーバーへ送信できます。これを利用して、あなたの[音声エージェント](../guides/voice-agents) を Twilio に接続できます。`websocket` モードのデフォルト Realtime Session トランスポートを使えば、Twilio からのイベントを Realtime Session に接続できます。しかし、正しいオーディオ形式の設定と、Web ベースの会話よりも遅延が大きい電話通話に合わせた割り込みタイミングの調整が必要になります。 +Twilio は、電話通話の元音声を WebSocket サーバーへ送信する [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しています。このセットアップを利用して、あなたの [音声エージェント](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続できます。`websocket` モードの既定の Realtime Session transport を使って、Twilio から送られてくるイベントを Realtime Session に接続することもできます。しかし、電話通話は Web ベースの会話よりも遅延が大きくなるため、正しいオーディオ形式を設定し、割り込みタイミングを調整する必要があります。 -このセットアップを簡単にするために、Twilio への接続、割り込み処理、音声転送を自動で行う専用のトランスポートレイヤーを作成しました。 +セットアップ体験を向上させるために、Twilio への接続、割り込み処理、オーディオ転送をすべて自動で行う専用のトランスポートレイヤーを用意しました。 ## セットアップ -1. **Twilio アカウントと Twilio 電話番号を用意してください。** +1. **Twilio アカウントと Twilio 電話番号を用意します。** -2. **Twilio からのイベントを受信できる WebSocket サーバーをセットアップします。** +2. **Twilio からのイベントを受信できる WebSocket サーバーを設定します。** - ローカルで開発する場合は、[`ngrok`](https://ngrok.io/) や - [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) のようなローカルトンネルを設定し、ローカルサーバーを Twilio からアクセス可能にする必要があります。`TwilioRealtimeTransportLayer` を使って Twilio に接続できます。 + ローカル開発の場合、Twilio からアクセスできるように [`ngrok`](https://ngrok.io/) や + [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) などでローカルトンネルを構成する必要があります。`TwilioRealtimeTransportLayer` を使用して Twilio に接続できます。 3. **extensions パッケージをインストールして Twilio アダプターを追加します:** @@ -53,21 +53,18 @@ Twilio は [Media Streams API](https://www.twilio.com/docs/voice/media-streams) -`RealtimeSession` で期待できるすべてのイベントや挙動 ― ツール呼び出し、ガードレール など ― がそのまま機能します。`RealtimeSession` を音声エージェントで使用する方法は、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 +`RealtimeSession` から期待できるイベントや動作は、ツール呼び出しやガードレールなどを含め、すべてそのまま利用できます。`RealtimeSession` を音声エージェントで使用する方法については、[音声エージェント](/openai-agents-js/ja/guides/voice-agents) ガイドを参照してください。 -## ヒントと注意事項 +## ヒントと考慮事項 -1. **速度が最重要です。** +1. **速度が最重要です。** + Twilio から必要なすべてのイベントとオーディオを受け取るために、WebSocket 接続の参照を取得したらすぐに `TwilioRealtimeTransportLayer` インスタンスを作成し、その直後に `session.connect()` を呼び出すようにしてください。 - 必要なイベントと音声を Twilio から受け取るためには、WebSocket 接続を取得したらすぐに `TwilioRealtimeTransportLayer` インスタンスを生成し、直後に `session.connect()` を呼び出してください。 +2. **Twilio の元イベントへアクセスする。** + Twilio から送信される生のイベントにアクセスしたい場合、`RealtimeSession` インスタンスの `transport_event` をリッスンできます。Twilio のすべてのイベントは `twilio_message` タイプと、生のイベントデータを含む `message` プロパティを持っています。 -2. **元の Twilio イベントへアクセスする。** - - Twilio から送信される生イベントを取得したい場合は、`RealtimeSession` インスタンスで `transport_event` をリッスンしてください。Twilio からの各イベントは `type: twilio_message` を持ち、`message` プロパティに元イベントデータが入っています。 - -3. **デバッグログを確認する。** - - 状況を詳しく確認したい場合は、環境変数 `DEBUG=openai-agents*` を設定すると Agents SDK のすべてのデバッグログが表示されます。Twilio アダプターのログだけを有効にする場合は `DEBUG=openai-agents:extensions:twilio*` を使用してください。 +3. **デバッグログを確認する。** + 何が起こっているかを詳しく知りたい場合があります。環境変数 `DEBUG=openai-agents*` を使用すると、Agents SDK のすべてのデバッグログが表示されます。あるいは `DEBUG=openai-agents:extensions:twilio*` を使って Twilio アダプターのデバッグログだけを有効にできます。 ## 完全なサーバー例 @@ -76,5 +73,5 @@ Twilio は [Media Streams API](https://www.twilio.com/docs/voice/media-streams) diff --git a/docs/src/content/docs/ja/guides/agents.mdx b/docs/src/content/docs/ja/guides/agents.mdx index 9937bf53..a0ca2bc3 100644 --- a/docs/src/content/docs/ja/guides/agents.mdx +++ b/docs/src/content/docs/ja/guides/agents.mdx @@ -14,29 +14,29 @@ import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agen import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw'; import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw'; -OpenAI Agents SDK の主要な構成要素は **エージェント** です。**Agent** とは、次のように設定された Large Language Model (LLM) を指します。 +エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** とは、以下の設定を行った Large Language Model (LLM) です。 -- **Instructions** – モデルに _自分が何者であるか_ と _どのように応答すべきか_ を伝えるシステムプロンプト -- **Model** – 呼び出す OpenAI モデル名と、任意のモデルチューニングパラメーター -- **Tools** – タスクを達成するために LLM が呼び出せる関数や API の一覧 +- **Instructions** – モデルに _自身が何者で、どのように応答すべきか_ を伝える system prompt +- **Model** – 呼び出す OpenAI モデル名と、任意のモデル調整パラメーター +- **Tools** – タスクを達成するために LLM が呼び出せる関数や API のリスト -以下では、エージェントの各機能を詳しく説明します。 +このページでは、エージェントの各機能について詳しく解説します。 --- ## 基本設定 -`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。よく利用されるプロパティは次のとおりです。 +`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。よく使うプロパティは以下のとおりです。 -| Property | Required | Description | -| --------------- | -------- | -------------------------------------------------------------------------------------------------- | -| `name` | yes | 人間が読みやすい短い識別子 | -| `instructions` | yes | システムプロンプト (文字列 **または** 関数 – [動的 instructions](#dynamic-instructions) を参照) | -| `model` | no | モデル名 **または** カスタム [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | -| `modelSettings` | no | チューニングパラメーター (temperature, top_p など) | -| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | +| Property | Required | Description | +| --------------- | -------- | ----------------------------------------------------------------------------------------------------- | +| `name` | yes | 人が読める短い識別子 | +| `instructions` | yes | System prompt（文字列 **または** 関数 – 詳細は [Dynamic instructions](#dynamic-instructions) を参照） | +| `model` | no | モデル名 **または** カスタム [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | +| `modelSettings` | no | 調整パラメーター（temperature、top_p など） | +| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | @@ -44,7 +44,7 @@ OpenAI Agents SDK の主要な構成要素は **エージェント** です。** ## コンテキスト -エージェントは **コンテキスト型をジェネリック** として受け取ります。つまり `Agent` です。_コンテキスト_ はあなたが作成し `Runner.run()` に渡す依存性注入オブジェクトで、すべてのツール、ガードレール、ハンドオフなどに転送されます。状態の保持や共有サービス（データベース接続、ユーザーメタデータ、フィーチャーフラグなど）の提供に便利です。 +エージェントは **コンテキスト型をジェネリック引数** として受け取ります（例: `Agent`）。コンテキストはあなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに渡され、状態の保持や共有サービス（データベース接続、ユーザーメタデータ、フラグ機能 …）を提供するのに便利です。 @@ -52,7 +52,7 @@ OpenAI Agents SDK の主要な構成要素は **エージェント** です。** ## 出力タイプ -デフォルトでは、エージェントは **プレーンテキスト** (`string`) を返します。モデルに構造化オブジェクトを返させたい場合は `outputType` プロパティを指定します。SDK では次のいずれかを受け付けます。 +デフォルトでは、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は `outputType` プロパティを指定します。SDK では次の形式を受け付けます。 1. [Zod](https://github.com/colinhacks/zod) スキーマ (`z.object({...})`) 2. JSON-schema 互換オブジェクト @@ -63,23 +63,24 @@ OpenAI Agents SDK の主要な構成要素は **エージェント** です。** title="Structured output with Zod" /> -`outputType` が指定されると、SDK はプレーンテキストの代わりに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を自動的に使用します。 +`outputType` が指定されている場合、SDK はプレーンテキストの代わりに +[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を自動的に使用します。 --- ## ハンドオフ -エージェントは `handoffs` プロパティを通じて他のエージェントへ **委譲** できます。一般的なパターンとして、_トリアージエージェント_ が会話をより専門的なサブエージェントへルーティングします。 +エージェントは `handoffs` プロパティを介して他のエージェントに **委譲** できます。一般的なパターンとして、_トリアージエージェント_ が会話をより専門的なサブエージェントへルーティングします。 -このパターンの詳細は [ハンドオフ](/openai-agents-js/ja/guides/handoffs) を参照してください。 +このパターンの詳細は [ハンドオフ](/openai-agents-js/ja/guides/handoffs) ガイドをご覧ください。 --- ## 動的 instructions -`instructions` は文字列の代わりに **関数** を受け取ることもできます。この関数には現在の `RunContext` と Agent インスタンスが渡され、文字列 _または_ `Promise` を返せます。 +`instructions` は文字列の代わりに **関数** を指定できます。この関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列または `Promise` を返せます。 -同期関数と `async` 関数の両方をサポートしています。 +同期関数と `async` 関数の両方に対応しています。 --- ## ライフサイクルフック -高度なユースケース向けに、イベントリスナーを通じてエージェントのライフサイクルを監視できます。 +高度なユースケースでは、イベントをリッスンしてエージェントのライフサイクルを観測できます。 --- -## ツール使用の強制 +## ツール呼び出しの強制 -ツールを提供しても、LLM が必ずしも呼び出すとは限りません。`modelSettings.tool_choice` でツール使用を **強制** できます。 +ツールを渡しても、LLM が必ずしも呼び出すとは限りません。`modelSettings.tool_choice` でツール使用を **強制** できます。 -1. `'auto'` (デフォルト) – ツールを使うかどうかは LLM が判断 -2. `'required'` – LLM は必ずツールを呼び出す (どのツールかは選択可) -3. `'none'` – LLM はツールを呼び出してはならない -4. 具体的なツール名 (例: `'calculator'`) – LLM はそのツールを必ず呼び出す +1. `'auto'`（デフォルト） – LLM がツールを使うかどうかを決定 +2. `'required'` – LLM はツールを _必ず_ 呼び出す（どのツールかは選択可） +3. `'none'` – LLM はツールを **呼び出さない** +4. 特定のツール名（例: `'calculator'`） – LLM はそのツールを必ず呼び出す ### 無限ループの防止 -ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツールを繰り返し呼び出す無限ループを防ぎます。この挙動は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 +ツール呼び出し後、SDK は `tool_choice` を自動的に `'auto'` にリセットします。これにより、モデルがツールを繰り返し呼び出す無限ループを防ぎます。この動作は `resetToolChoice` フラグや `toolUseBehavior` の設定で上書きできます。 -- `'run_llm_again'` (デフォルト) – ツール結果を用いて再度 LLM を実行 +- `'run_llm_again'`（デフォルト） – ツール結果を使って LLM を再実行 - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う -- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールが呼び出されたら停止 +- `{ stopAtToolNames: ['my_tool'] }` – 指定したツールが呼び出された時点で停止 - `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数 ```typescript @@ -148,6 +149,6 @@ const agent = new Agent({ ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を学ぶ -- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) をさらに深掘り -- サイドバーの **@openai/agents** で TypeDoc 全リファレンスを確認 +- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) 方法を学ぶ +- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) を詳しく探る +- サイドバーの **@openai/agents** で TypeDoc 参照全体を確認する diff --git a/docs/src/content/docs/ja/guides/config.mdx b/docs/src/content/docs/ja/guides/config.mdx index 5c3c8f5d..19272db6 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,34 +13,34 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## API キーとクライアント -デフォルトでは SDK は最初のインポート時に `OPENAI_API_KEY` 環境変数を読み込みます。環境変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出せます。 +デフォルトでは、SDK は初回インポート時に環境変数 `OPENAI_API_KEY` を読み込みます。環境変数を設定できない場合は、`setDefaultOpenAIKey()` を手動で呼び出してください。 -独自の `OpenAI` クライアントインスタンスを渡すことも可能です。渡さない場合は、SDK がデフォルトキーを使って自動的に作成します。 +独自の `OpenAI` クライアントインスタンスを渡すこともできます。何もしなければ、SDK が上記のデフォルトキーを使用して自動的に作成します。 -最後に Responses API と Chat Completions API を切り替えることもできます。 +最後に、Responses API と Chat Completions API を切り替えることもできます。 ## トレーシング -トレーシングはデフォルトで有効になっており、上記の OpenAI キーを使用します。別のキーを使用したい場合は `setTracingExportApiKey()` で設定できます。 +トレーシングはデフォルトで有効になっており、前述の OpenAI キーを使用します。`setTracingExportApiKey()` で別のキーを設定することも可能です。 トレーシングを完全に無効化することもできます。 @@ -51,29 +51,29 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t title="トレーシングを無効化" /> -## デバッグログ出力 +## デバッグログ -SDK はデバッグログ出力に [`debug`](https://www.npmjs.com/package/debug) パッケージを使用します。詳細なログを表示するには `DEBUG` 環境変数に `openai-agents*` を設定してください。 +SDK は [`debug`](https://www.npmjs.com/package/debug) パッケージを使用してデバッグログを出力します。詳細ログを表示するには、環境変数 `DEBUG` に `openai-agents*` を設定してください。 ```bash export DEBUG=openai-agents* ``` -`@openai/agents` の `getLogger(namespace)` を使うと、独自モジュール用に名前空間付きロガーを取得できます。 +自身のモジュール用に名前空間付きロガーが必要な場合は、`@openai/agents` の `getLogger(namespace)` を使用してください。 -### ログ内の機微データ +### ログ中の機微データ -一部のログにはユーザーのデータが含まれる可能性があります。次の環境変数を設定して無効化できます。 +一部のログにはユーザーデータが含まれる可能性があります。次の環境変数を設定して出力を無効化できます。 -LLM の入力と出力のログを無効にするには: +LLM 入出力のログを無効化する場合: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力と出力のログを無効にするには: +ツールの入出力のログを無効化する場合: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/src/content/docs/ja/guides/context.mdx b/docs/src/content/docs/ja/guides/context.mdx index 6f40af71..a9169afb 100644 --- a/docs/src/content/docs/ja/guides/context.mdx +++ b/docs/src/content/docs/ja/guides/context.mdx @@ -6,12 +6,10 @@ description: Learn how to provide local data via RunContext and expose context t import { Aside, Code } from '@astrojs/starlight/components'; import localContextExample from '../../../../../../examples/docs/context/localContext.ts?raw'; -コンテキストという言葉には複数の意味があります。主に次の 2 種類のコンテキストを扱います: +コンテキストという語は多義的です。気にすべきコンテキストには、大きく 2 つの種類があります: -1. **ローカルコンテキスト** - 実行中にコードからアクセスできる依存関係やデータ、`onHandoff` のようなコールバック、ライフサイクルフック -2. **エージェント／LLM コンテキスト** - 言語モデルが応答を生成するときに参照できる情報 +1. **ローカルコンテキスト** – 実行中にコードがアクセスできる依存関係やツールが必要とするデータ、`onHandoff` のようなコールバック、ライフサイクルフックなど +2. **エージェント / LLM コンテキスト** – 言語モデルが応答を生成するときに参照できるもの ## ローカルコンテキスト @@ -20,29 +18,27 @@ import localContextExample from '../../../../../../examples/docs/context/localCo -同じ実行に参加するすべてのエージェント、ツール、フックは同じ **型** のコンテキストを使用する必要があります。 +同一の実行に参加するすべてのエージェント、ツール、フックは同じ **型** のコンテキストを共有する必要があります。 -ローカルコンテキストは次のような用途に適しています: +ローカルコンテキストの主な用途: -- 実行に関するデータ (ユーザー名、ID など) -- ロガーやデータフェッチャーなどの依存関係 +- 実行に関するデータ（ユーザー名、ID など） +- ロガーやデータフェッチャーのような依存関係 - ヘルパー関数 -## エージェント／LLM コンテキスト +## エージェント / LLM コンテキスト -LLM が呼び出されるとき、モデルが参照できるのは会話履歴だけです。追加情報を利用可能にする方法はいくつかあります: +LLM が呼び出されるとき、参照できるデータは会話履歴のみです。追加情報を渡すには、いくつか方法があります: -1. Agent の `instructions` に追加する - システムメッセージや開発者メッセージとしても知られます。静的文字列を指定するか、コンテキストを受け取って文字列を返す関数を指定できます。 -2. `Runner.run()` 呼び出し時の `input` に含める - `instructions` と似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)の下位にメッセージを配置できます。 -3. 関数ツールを介して公開し、LLM が必要に応じてデータを取得できるようにする -4. リトリーバルや Web 検索ツールを使用して、ファイル、データベース、Web から取得した関連データをもとに回答を補強する +1. Agent の `instructions` に追加する – システムまたは developer メッセージとも呼ばれます。固定文字列でも、コンテキストを受け取って文字列を返す関数でもかまいません。 +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. function tools 経由で公開し、 LLM が必要に応じてデータを取得できるようにする +4. retrieval ツールや Web 検索ツールを使い、ファイルやデータベース、Web から取得した関連データに基づいて回答を補強する diff --git a/docs/src/content/docs/ja/guides/guardrails.mdx b/docs/src/content/docs/ja/guides/guardrails.mdx index d430ff3d..7ac8a8a0 100644 --- a/docs/src/content/docs/ja/guides/guardrails.mdx +++ b/docs/src/content/docs/ja/guides/guardrails.mdx @@ -7,58 +7,58 @@ import { Code } from '@astrojs/starlight/components'; import inputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-input.ts?raw'; import outputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-output.ts?raw'; -ガードレールは _並行して_ エージェントと動作し、ユーザー入力やエージェント出力に対してチェックやバリデーションを実行できます。たとえば、高コストなモデルを呼び出す前に軽量モデルをガードレールとして実行し、悪意のある利用を検知した場合にエラーを発生させて高コストなモデルの実行を防ぐことができます。 +ガードレールはエージェントと _並列で_ 実行され、 ユーザー入力やエージェント出力に対してチェックとバリデーションを行えます。たとえば、高価なモデルを呼び出す前に軽量モデルをガードレールとして動かすことができます。ガードレールが悪意のある利用を検知した場合、エラーを発生させて高価なモデルの実行を停止できます。 -ガードレールには 2 種類あります。 +ガードレールには 2 種類あります: -1. **Input guardrails** は初期ユーザー入力に対して実行されます +1. **Input guardrails** は最初のユーザー入力に対して実行されます 2. **Output guardrails** は最終的なエージェント出力に対して実行されます ## Input guardrails -Input guardrails は次の 3 ステップで実行されます。 +Input guardrails は次の 3 ステップで実行されます: 1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップして返します -3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます +2. ガードレール関数が実行され、 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップして返します +3. `tripwireTriggered` が `true` の場合、 [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます > **Note** -> Input guardrails はユーザー入力を対象としているため、ワークフローでエージェントが _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。異なるエージェントでは必要なガードレールが異なることが多いためです。 +> Input guardrails はユーザー入力向けであるため、ワークフロー内でエージェントが _最初の_ エージェントである場合にのみ実行されます。ガードレールはエージェント自身に設定します。エージェントごとに必要なガードレールが異なることが多いためです。 ## Output guardrails -Output guardrails も同じパターンで動作します。 +Output guardrails も同じパターンに従います: 1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップして返します -3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます +2. ガードレール関数が実行され、 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップして返します +3. `tripwireTriggered` が `true` の場合、 [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます > **Note** -> Output guardrails はワークフローでエージェントが _最後_ のエージェントである場合にのみ実行されます。リアルタイム音声インタラクションについては [the voice agents guide](/openai-agents-js/ja/guides/voice-agents#guardrails) を参照してください。 +> Output guardrails はワークフロー内でエージェントが _最後の_ エージェントである場合にのみ実行されます。リアルタイム音声インタラクションについては [音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails) を参照してください。 ## Tripwires -ガードレールが失敗すると、トリップワイヤーでそれを通知します。トリップワイヤーが発火した時点で、Runner は該当するエラーをスローし、実行を停止します。 +ガードレールが失敗すると、トリップワイヤーによってそれが通知されます。トリップワイヤーが作動すると直ちにランナーが対応するエラーをスローし、実行を停止します。 -## ガードレールの実装 +## Implementing a guardrail -ガードレールは `GuardrailFunctionOutput` を返す単なる関数です。以下は、別のエージェントを内部で呼び出してユーザーが数学の宿題の手助けを求めているかを判定する最小例です。 +ガードレールは `GuardrailFunctionOutput` を返す単なる関数です。以下は、内部で別のエージェントを実行してユーザーが数学の宿題の助けを求めているかどうかを判定する最小限の例です。 -Output guardrails も同様に動作します。 +Output guardrails も同じ方法で動作します。 1. `guardrailAgent` はガードレール関数内で使用されます 2. ガードレール関数はエージェントの入力または出力を受け取り、結果を返します -3. ガードレール結果には追加情報を含めることができます +3. 追加情報を guardrail 結果に含めることができます 4. `agent` がガードレールを適用する実際のワークフローを定義します diff --git a/docs/src/content/docs/ja/guides/handoffs.mdx b/docs/src/content/docs/ja/guides/handoffs.mdx index 05f454c6..0aeafae8 100644 --- a/docs/src/content/docs/ja/guides/handoffs.mdx +++ b/docs/src/content/docs/ja/guides/handoffs.mdx @@ -10,28 +10,28 @@ import handoffInputExample from '../../../../../../examples/docs/handoffs/handof import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw'; import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw'; -ハンドオフを利用すると、あるエージェントが会話の一部を別のエージェントに委任できます。異なるエージェントが特定の分野を専門としている場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、FAQ を担当するエージェントを用意できます。 +ハンドオフを使用すると、あるエージェントが会話の一部を別のエージェントに委任できます。これは、エージェントごとに得意分野が異なる場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、FAQ を担当するエージェントを用意できます。 -ハンドオフは LLM から見るとツールとして表現されます。たとえば `Refund Agent` にハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM にはツールとして表現されます。`Refund Agent` というエージェントへハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントは `handoffs` オプションを受け取ります。このオプションには、ほかの `Agent` インスタンスや `handoff()` ヘルパーが返す `Handoff` オブジェクトを含められます。 +すべてのエージェントは `handoffs` オプションを受け取れます。ここには、他の `Agent` インスタンスや `handoff()` ヘルパーが返す `Handoff` オブジェクトを含められます。 -### 基本的な使用方法 +### 基本的な使い方 -### handoff() によるハンドオフのカスタマイズ +### `handoff()` によるハンドオフのカスタマイズ -`handoff()` 関数を使うと、生成されるツールを調整できます。 +`handoff()` 関数を使うと、生成されるツールを細かく調整できます。 - `agent` – ハンドオフ先のエージェント - `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き - `toolDescriptionOverride` – 既定のツール説明を上書き -- `onHandoff` – ハンドオフ時に呼び出されるコールバック。`RunContext` と（必要に応じて）解析済み入力を受け取る -- `inputType` – ハンドオフで期待される入力スキーマ -- `inputFilter` – 次のエージェントに渡す履歴をフィルターする +- `onHandoff` – ハンドオフ発生時に呼び出されるコールバック。`RunContext` と、オプションで解析済み入力を受け取る +- `inputType` – ハンドオフ時に期待される入力スキーマ +- `inputFilter` – 次のエージェントに渡す履歴をフィルタリング -## ハンドオフ入力 +## ハンドオフの入力 -ハンドオフを呼び出す際に、LLM からデータを受け取りたい場合があります。その場合は入力スキーマを定義し、`handoff()` で使用します。 +ハンドオフを呼び出す際に LLM にデータを渡してほしい場合があります。その場合は入力スキーマを定義し、`handoff()` で指定します。 ## 入力フィルター -デフォルトでは、ハンドオフには会話履歴の全体が渡されます。次のエージェントに渡す内容を調整したい場合は `inputFilter` を指定します。 -一般的なヘルパーは `@openai/agents-core/extensions` に用意されています。 +デフォルトでは、ハンドオフ先は会話履歴全体を受け取ります。次のエージェントに渡す内容を変更したい場合は `inputFilter` を提供します。共通のヘルパーは `@openai/agents-core/extensions` に含まれています。 ## 推奨プロンプト -プロンプトにハンドオフの情報を含めると、LLM はより確実に応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` で推奨される接頭辞を提供しています。 +プロンプトにハンドオフを明示すると、LLM の応答が安定します。SDK では `RECOMMENDED_PROMPT_PREFIX` として推奨のプレフィックスを提供しています。 ### フロー -1. エージェントがツール（複数可）を呼び出そうとすると、`needsApproval` を評価してそのツールが承認を必要とするか確認します -2. 承認が必要な場合、エージェントは承認がすでに許可・拒否されているかを確認します - - まだ許可・拒否されていない場合、ツールは「ツール呼び出しを実行できない」という固定メッセージをエージェントに返します - - 許可 / 拒否が未決の場合、ツール承認リクエストをトリガーします -3. エージェントはすべてのツール承認リクエストを集め、実行を中断します -4. 中断がある場合、[実行結果](/openai-agents-js/ja/guides/result) には保留中のステップを示す `interruptions` 配列が含まれます。ツール呼び出しに確認が必要なときは `type: "tool_approval_item"` の `ToolApprovalItem` が現れます -5. `result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出してツール呼び出しを許可・拒否できます -6. すべての中断を処理したら、`result.state` を `runner.run(agent, state)` に渡して実行を再開します。ここで `agent` は最初に実行を開始させたエージェントです -7. フローは 1 に戻ります +1. エージェントがツール（複数可）を呼び出そうとすると、まず `needsApproval` を評価してそのツールに承認が必要か確認します。 +2. 承認が必要な場合、エージェントはすでに承認済みか拒否済みかを確認します。 + - 承認も拒否もされていない場合、ツールは「実行できない」という固定メッセージをエージェントへ返します。 + - 承認／拒否が未決定の場合、ツール承認リクエストを発行します。 +3. エージェントはすべてのツール承認リクエストを収集し、実行を中断します。 +4. 中断がある場合、[エージェントの実行結果](/openai-agents-js/ja/guides/result) には保留中のステップを示す `interruptions` 配列が含まれます。ツール呼び出しに確認が必要なときは、`type: "tool_approval_item"` を持つ `ToolApprovalItem` が挿入されます。 +5. `result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出してツール呼び出しを承認または拒否できます。 +6. すべての中断を処理したら、`result.state` を `runner.run(agent, state)` に渡して実行を再開します。ここで `agent` は元のエージェントです。 +7. 以上のフローがステップ 1 から再開されます。 ## 例 -以下は、ターミナルで承認を促し、一時的に state をファイルへ保存する Human-in-the-loop フローの、より完全な例です。 +以下は、ターミナルで承認を求め、状態を一時的にファイルへ保存する Human in the loop フローのより完全な例です。 -動作するエンドツーエンド版は [完全なスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 +エンドツーエンドで動作する完全版は、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 -## 長時間の承認待ちへの対応 +## 承認まで時間がかかる場合の対応 -Human-in-the-loop フローは、サーバーを起動し続けなくても長時間一時停止できるよう設計されています。リクエストを終了して後で続行したい場合、state をシリアライズして後で再開できます。 +Human in the loop フローは、サーバーを常時稼働させなくても長時間中断できるよう設計されています。リクエストを一旦終了し、後で続行する必要がある場合は、状態をシリアライズしてから再開できます。 -`JSON.stringify(result.state)` で state をシリアライズし、後で `RunState.fromString(agent, serializedState)` にシリアライズ済みの state を渡して再開します。ここで `agent` は実行を開始させたエージェントのインスタンスです。 +`JSON.stringify(result.state)` で状態をシリアライズし、後で `RunState.fromString(agent, serializedState)` にシリアライズ済み状態を渡して再開します。ここで `agent` は元のエージェントのインスタンスです。 -この方法で、シリアライズした state をデータベースやリクエストと一緒に保存できます。 +この方法で、シリアライズした状態をデータベースやリクエストと一緒に保存できます。 -### 保留タスクのバージョニング +### 保留中タスクのバージョン管理 -承認に時間がかかり、エージェント定義を意味のある形でバージョン管理したい、または Agents SDK のバージョンを上げたい場合、現時点では package alias を使って 2 つの Agents SDK を並行インストールし、独自にブランチロジックを実装することを推奨します。 +承認に時間がかかり、エージェント定義を意味のある形でバージョン管理したい、または Agents SDK のバージョンを上げたい場合は、パッケージエイリアスを使って Agents SDK を 2 つ並行インストールし、独自のブランチロジックを実装することを推奨します。 -実際には、独自にコードのバージョン番号を割り当て、それをシリアライズした state と一緒に保存し、デシリアライズ時に正しいコードバージョンへ誘導する形になります。 +実際には、独自のコードにバージョン番号を割り当て、それをシリアライズした状態と共に保存し、デシリアライズ時に正しいコードバージョンへ誘導する形になります。 diff --git a/docs/src/content/docs/ja/guides/models.mdx b/docs/src/content/docs/ja/guides/models.mdx index 1da7dd9c..c77c1fc8 100644 --- a/docs/src/content/docs/ja/guides/models.mdx +++ b/docs/src/content/docs/ja/guides/models.mdx @@ -11,12 +11,12 @@ import agentWithModelExample from '../../../../../../examples/docs/models/agentW import runnerWithModelExample from '../../../../../../examples/docs/models/runnerWithModel.ts?raw'; import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw'; -最終的にすべての エージェント は LLM を呼び出します。SDK はモデルを次の 2 つの軽量インターフェースの背後に抽象化します: +すべてのエージェントは最終的に LLM を呼び出します。SDK はモデルを次の 2 つの軽量インターフェースの背後に抽象化します: -- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定 API への _1 回_ のリクエスト方法を知っています -- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読みやすいモデル **名** (例: `'gpt-4o'`) を `Model` インスタンスへ解決します +- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して _1 回_ のリクエストを行う方法を知っています +- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読めるモデル **名**（例: `'gpt-4o'`）を `Model` インスタンスに解決します -日常的にはモデル **名** と、時折 `ModelSettings` のみを扱います。 +日常的な開発では、通常モデル **名** と必要に応じて `ModelSettings` のみを扱います。 -カスタムのネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` で独自の `OpenAI` クライアントを差し込むこともできます。 +独自のネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` で自前の `OpenAI` クライアントを差し込むこともできます。 ### デフォルトモデル @@ -61,23 +61,23 @@ OpenAI プロバイダーのデフォルトは `gpt-4o` です。エージェン `ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダー非依存です。 -| フィールド | 型 | メモ | -| ------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | -| `temperature` | `number` | 創造性と決定論のバランス | -| `topP` | `number` | ニュークリアスサンプリング | -| `frequencyPenalty` | `number` | 繰り返しトークンのペナルティ | -| `presencePenalty` | `number` | 新しいトークンを促進 | -| `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [ツールの使用を強制する](/openai-agents-js/ja/guides/agents#forcing-tool-use) | -| `parallelToolCalls` | `boolean` | 対応している場合に並列関数呼び出しを許可 | -| `truncation` | `'auto' \| 'disabled'` | トークン切り詰め戦略 | -| `maxTokens` | `number` | 応答内の最大トークン数 | -| `store` | `boolean` | 応答を永続化し、取得 / RAG ワークフローで利用 | +| Field | Type | 説明 | +| ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ | +| `temperature` | `number` | 創造性と決定論的挙動のバランス | +| `topP` | `number` | ニュークリアスサンプリング | +| `frequencyPenalty` | `number` | 繰り返しトークンのペナルティ | +| `presencePenalty` | `number` | 新しいトークンを促進 | +| `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 | +| `parallelToolCalls` | `boolean` | サポートされていれば関数呼び出しを並列実行 | +| `truncation` | `'auto' \| 'disabled'` | トークン切り捨て戦略 | +| `maxTokens` | `number` | レスポンスの最大トークン数 | +| `store` | `boolean` | 取得/RAG ワークフローのためにレスポンスを永続化 | -設定はどちらのレベルにも添付できます: +設定はどちらのレベルにも紐付け可能です: -`Runner` レベルの設定は、競合するエージェント単位の設定を上書きします。 +`Runner` レベルの設定は、エージェント固有の設定より優先されます。 --- @@ -88,14 +88,14 @@ OpenAI プロバイダーのデフォルトは `gpt-4o` です。エージェン --- ## トレーシングエクスポーター -OpenAI プロバイダー使用時に API キーを渡せば、自動トレースエクスポートをオプトインできます: +OpenAI プロバイダーを使用している場合、API キーを指定すると自動トレース送信を有効化できます: -これによりトレースが [OpenAI ダッシュボード](https://platform.openai.com/traces) へ送信され、ワークフローの完全な実行グラフを確認できます。 +これにより、[OpenAI ダッシュボード](https://platform.openai.com/traces) にトレースが送信され、ワークフローの完全な実行グラフを確認できます。 --- ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を確認 -- [ツール](/openai-agents-js/ja/guides/tools) でモデルにスーパーパワーを付与 +- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を試してみましょう +- [ツール](/openai-agents-js/ja/guides/tools) でモデルに超能力を付与 - 必要に応じて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加 diff --git a/docs/src/content/docs/ja/guides/multi-agent.md b/docs/src/content/docs/ja/guides/multi-agent.md index 7c8f56f4..38220c02 100644 --- a/docs/src/content/docs/ja/guides/multi-agent.md +++ b/docs/src/content/docs/ja/guides/multi-agent.md @@ -3,48 +3,45 @@ title: マルチエージェント description: Coordinate the flow between several agents --- -「オーケストレーション」とは、アプリ内で エージェント がどのように流れ、どの エージェント をどの順番で実行し、次に何をするかを決定するかを指します。 エージェント をオーケストレーションする方法は大きく 2 つあります。 +オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントをどの順序で実行するか、そして次に何を行うかをどのように決定するかということです。エージェントをオーケストレーションする方法は大きく 2 つあります。 -1. LLM に意思決定させる - これにより LLM の知能を活用して計画・推論し、その結果に基づいて次のステップを決定できます。 -2. コードによるオーケストレーション - コードで エージェント の流れを制御します。 +1. LLM に意思決定させる方法: これは、LLM の知性を活用して計画・推論し、それに基づいて次に取るべきステップを決定します +2. コードによるオーケストレーション: コードでエージェントの流れを決定します -これらのパターンは組み合わせて利用できます。それぞれにトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせることができ、それぞれにトレードオフがあります。以下で説明します。 ## LLM によるオーケストレーション -エージェント とは、instructions、tools、handoffs を備えた LLM です。オープンエンドなタスクが与えられたとき、 LLM は自律的に計画を立て、tools を使ってアクションを実行しデータを取得し、handoffs でサブ エージェント にタスクを委任できます。たとえば、リサーチ エージェント には次のようなツールを用意できます。 +エージェントとは、 instructions、tools、handoffs を備えた LLM です。つまり、オープンエンドなタスクに対して、LLM が自律的に計画を立て、ツールを使ってアクションを実行・データを取得し、handoffs を用いてサブエージェントへタスクを委任できます。たとえば、リサーチエージェントは次のようなツールを備えられます。 -- Web 検索によるオンライン情報取得 -- ファイル検索および取得での社内データや接続の検索 -- コンピュータ操作 を用いたアクション実行 -- コード実行 によるデータ分析 -- 計画立案やレポート作成に長けた専門 エージェント へのハンドオフ +- Web 検索でオンライン情報を探す +- ファイル検索と取得でプロプライエタリデータや接続先を検索する +- コンピュータ操作でコンピュータ上のアクションを実行する +- コード実行でデータ分析を行う +- ハンドオフで、計画やレポート作成などを得意とする専門エージェントに委任する -このパターンはタスクがオープンエンドで、 LLM の知能に頼りたい場合に最適です。重要なポイントは次のとおりです。 +このパターンはタスクがオープンエンドで、LLM の知性に頼りたい場合に最適です。ここで重要な戦術は次のとおりです。 1. 良いプロンプトに投資する - 利用可能なツール、その使い方、守るべきパラメーターを明確に示します。 -2. アプリを監視しイテレーションを重ねる - 問題が起きた箇所を確認し、プロンプトを改良します。 -3. エージェント に内省と改善を許可する - たとえばループで実行し自己批評させる、あるいはエラーメッセージを与えて改善させます。 -4. 何でもこなす汎用 エージェント ではなく、一つのタスクに特化した エージェント を用意する + ツールの一覧、使い方、守るべきパラメーターを明確にします +2. アプリをモニタリングしてイテレーションを重ねる + 問題が起きた箇所を確認し、プロンプトを改善します +3. エージェントに内省させて改善させる + 例としてループで実行し、自己批評させる／エラーメッセージを渡して自己改善させる +4. 何でもできる汎用エージェントより、特定タスクに特化したエージェントを用意する 5. [evals](https://platform.openai.com/docs/guides/evals) に投資する - これにより エージェント を訓練し、タスク遂行能力を向上させられます。 + これによりエージェントを訓練し、タスク遂行能力を向上させられます ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードで制御すると速度・コスト・性能の面でより決定論的かつ予測可能になります。代表的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・パフォーマンスの面でより決定論的かつ予測可能になります。代表的なパターンは以下のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を用いて、コードで検査可能な 適切な形式のデータ を生成する - 例: タスクをいくつかの カテゴリー に分類し、その カテゴリー に基づいて次の エージェント を選ぶ -- 複数の エージェント を連鎖させ、一方の出力を次の入力に変換する - 例: ブログ記事を書くタスクを、リサーチ → アウトライン作成 → 執筆 → クリティーク → 改善 の一連のステップに分解 -- タスクを実行する エージェント を `while` ループで回し、評価・フィードバックを行う エージェント と組み合わせる - 評価者が基準を満たしたと判断するまで繰り返します -- JavaScript の `Promise.all` などを使って複数の エージェント を並列実行する - 相互依存のない複数タスクを高速に処理したいときに有効 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用して、コードで検査できる適切な形式のデータを生成する + 例として、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに応じて次のエージェントを選ぶ +- 複数のエージェントを連結し、あるエージェントの出力を次のエージェントの入力に変換する + 例: ブログ記事執筆を「リサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善」という一連のステップに分割 +- タスクを実行するエージェントと、その出力を評価・フィードバックするエージェントを `while` ループで回し、評価者が基準を満たしたと判断するまで繰り返す +- JavaScript プリミティブである `Promise.all` などを使い、複数エージェントを並列実行する + 相互依存しない複数タスクを高速に処理したい場合に有効 -[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) に多数のサンプルがあります。 +[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) に多数のコード例があります。 diff --git a/docs/src/content/docs/ja/guides/quickstart.mdx b/docs/src/content/docs/ja/guides/quickstart.mdx index e554c4c3..0e82d646 100644 --- a/docs/src/content/docs/ja/guides/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/quickstart.mdx @@ -7,11 +7,11 @@ import { Steps } from '@astrojs/starlight/components'; import { Code } from '@astrojs/starlight/components'; import quickstartExample from '../../../../../../examples/docs/quickstart/index.ts?raw'; -## プロジェクト設定 +## プロジェクトセットアップ -1. プロジェクトを作成し、npm を初期化します。これは一度だけで構いません。 +1. プロジェクトを作成して npm を初期化します。これは一度だけで構いません。 ```bash mkdir my_project @@ -25,7 +25,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm install @openai/agents ``` -3. OpenAI API キーを設定します。キーがない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 +3. OpenAI API キーを設定します。まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... @@ -35,7 +35,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. ## 最初のエージェントの作成 -エージェントは instructions と name で定義します。 +エージェントは instructions と名前で定義します。 ```typescript import { Agent } from '@openai/agents'; @@ -49,9 +49,9 @@ const agent = new Agent({ ## 最初のエージェントの実行 -`run` メソッドを使用してエージェントを実行できます。開始したいエージェントと渡したい入力を両方指定して実行します。 +`run` メソッドを使ってエージェントを実行できます。開始したいエージェントと渡したい入力を指定して実行をトリガーします。 -これにより、最終出力とその実行中に実行されたアクションを含む result が返されます。 +これにより、最終出力と実行中に実行されたアクションを含む実行結果が返されます。 ```typescript import { Agent, run } from '@openai/agents'; @@ -67,7 +67,7 @@ const result = await run(agent, 'When did sharks first appear?'); console.log(result.finalOutput); ``` -## エージェントにツールを提供 +## エージェントへのツール追加 エージェントに情報を検索したりアクションを実行したりするためのツールを与えることができます。 @@ -94,9 +94,9 @@ const agent = new Agent({ }); ``` -## さらなるエージェントの追加 +## エージェントの追加 -追加のエージェントを同様に定義して、問題をより小さな部分に分割し、各エージェントが現在のタスクに集中できるようにします。また、エージェントごとにモデルを指定することで、異なる問題に対して異なるモデルを使用できます。 +問題をより小さな部分に分割し、エージェントがタスクに集中できるように、追加のエージェントを同様に定義できます。また、エージェントごとにモデルを指定することで、異なる問題に対して異なるモデルを使用できます。 ```typescript const historyTutorAgent = new Agent({ @@ -114,7 +114,7 @@ const mathTutorAgent = new Agent({ ## ハンドオフの定義 -複数のエージェントをオーケストレーションするために、エージェントに `handoffs` を定義できます。これにより、実行中に自動的に次のエージェントへ会話を引き継げるようになります。 +複数のエージェント間をオーケストレーションするために、エージェントに対して `handoffs` を定義できます。これにより、実行中に自動的に次のエージェントへ会話を引き継げます。 ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -126,11 +126,11 @@ const triageAgent = Agent.create({ }); ``` -実行後、result の `finalAgent` プロパティを確認すると、最終応答を生成したエージェントがわかります。 +実行後、`finalAgent` プロパティを見ることで、どのエージェントが最終応答を生成したかを確認できます。 ## エージェントオーケストレーションの実行 -Runner は各エージェントの実行、ハンドオフ、ツール実行を処理します。 +Runner は個々のエージェントの実行、ハンドオフ、ツール実行を処理します。 ```typescript import { run } from '@openai/agents'; @@ -143,17 +143,18 @@ async function main() { main().catch((err) => console.error(err)); ``` -## まとめ +## 総まとめ -すべてを一つにまとめた完全な例を示します。`index.js` に貼り付けて実行してください。 +すべてをまとめて 1 つの完全なサンプルにしましょう。`index.js` に以下を配置して実行してください。 -## トレースの閲覧 +## トレースの表示 -Agents SDK はトレースを自動生成します。これにより、エージェントがどのように動作したか、どのツールを呼び出したか、どのエージェントにハンドオフしたかを確認できます。 +Agents SDK はトレースを自動生成します。これにより、エージェントがどのように動作し、どのツールを呼び出し、どのエージェントへハンドオフしたかを確認できます。 -エージェントの実行内容を確認するには、[OpenAI ダッシュボードの Trace ビューア](https://platform.openai.com/traces)にアクセスしてください。 +エージェント実行中に何が起こったかを確認するには、 +[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動してください。 ## 次のステップ diff --git a/docs/src/content/docs/ja/guides/results.mdx b/docs/src/content/docs/ja/guides/results.mdx index ff774f5b..cfd47eb4 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -7,23 +7,24 @@ import { Code } from '@astrojs/starlight/components'; import handoffFinalOutputTypes from '../../../../../../examples/docs/results/handoffFinalOutputTypes.ts?raw'; import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts?raw'; -[エージェントの実行](/openai-agents-js/ja/guides/running-agents) を行うと、結果として次のいずれかを受け取ります。 +[エージェントの実行](/openai-agents-js/ja/guides/running-agents) を行うと、次のいずれかが返されます。 -- `stream: true` を付けずに `run` を呼び出した場合 — [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) -- `stream: true` を付けて `run` を呼び出した場合 — [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。ストリーミングの詳細は [ストリーミング](/openai-agents-js/ja/guides/streaming) も参照してください。 +- `stream: true` を付けずに `run` を呼び出した場合は [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) +- `stream: true` を付けて `run` を呼び出した場合は [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult) + ストリーミングの詳細については [ストリーミング](/openai-agents-js/ja/guides/streaming) ガイドも参照してください。 ## 最終出力 -`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が入ります。型は次のいずれかです。 +`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が入ります。この結果は次のいずれかです。 - `string` — `outputType` が定義されていないエージェントのデフォルト -- `unknown` — エージェントが JSON スキーマを出力タイプとして定義している場合。JSON はパースされますが、型の確認は手動で行う必要があります -- `z.infer` — エージェントが Zod スキーマを出力タイプとして定義している場合。出力は自動的にこのスキーマでパースされます -- `undefined` — エージェントが出力を生成しなかった場合（たとえば途中で停止した場合） +- `unknown` — エージェントに JSON スキーマが `outputType` として定義されている場合。この場合 JSON はパースされますが、型の検証は手動で行う必要があります +- `z.infer` — エージェントに Zod スキーマが `outputType` として定義されている場合。出力は自動でこのスキーマに対してパースされます +- `undefined` — エージェントが出力を生成しなかった場合（例: 出力を生成する前に停止した場合） -複数の異なる出力タイプでハンドオフを使用する場合は、`new Agent()` コンストラクターではなく `Agent.create()` メソッドでエージェントを作成してください。 +異なる `outputType` を持つハンドオフを使用する場合は、エージェントを作成する際に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 -これにより、SDK はすべてのハンドオフでの出力タイプを推論し、`finalOutput` プロパティにユニオン型を提供します。 +これにより SDK がすべてのハンドオフでの出力型を推論し、`finalOutput` プロパティにユニオン型を提供します。 例: @@ -33,57 +34,57 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? title="Handoff final output types" /> -## 次ターンへの入力 +## 次のターンへの入力 -次ターン用の入力には 2 通りの取得方法があります。 +次のターンで使用できる入力を取得する方法は 2 つあります。 -- `result.history` — 入力とエージェントの出力の両方をコピーして保持します -- `result.output` — エージェント実行全体の出力を保持します +- `result.history` — 入力とエージェントの出力の両方を含む履歴のコピー +- `result.output` — エージェント実行全体の出力 -チャットのようなユースケースでは、`history` を使うと完全な履歴を簡単に保持できます。 +`history` はチャットのようなユースケースで完全な履歴を保持するのに便利です。 -## 最後に実行したエージェント +## 最後に実行されたエージェント -`lastAgent` プロパティには最後に実行されたエージェントが入ります。たとえばフロントラインのトリアージ エージェントが言語別エージェントへハンドオフする場合、`lastAgent` を保存しておき、次回ユーザーからメッセージが来た際に再利用できます。 +`lastAgent` プロパティには最後に実行されたエージェントが入ります。アプリケーションによっては、次回ユーザーが入力した際にこれを利用すると便利です。たとえば、最前線のトリアージを行うエージェントが言語別のエージェントにハンドオフする場合、`lastAgent` を保存しておき、ユーザーが次にメッセージを送った際に再利用できます。 -ストリーミング モードでは、現在実行中のエージェントを示す `currentAgent` プロパティを参照するのが便利なこともあります。 +ストリーミング モードでは、現在実行中のエージェントを示す `currentAgent` プロパティにアクセスすることも有用です。 -## 新規アイテム +## 新しいアイテム -`newItems` プロパティには実行中に生成された新しいアイテムが入ります。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) で、LLM が生成した元アイテムをラップしています。これにより、LLM の出力に加え、そのイベントがどのエージェントに紐づくかを取得できます。 +`newItems` プロパティには実行中に生成された新しいアイテムが入ります。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) で、LLM が生成した元のアイテムをラップしています。これにより、LLM の出力に加え、そのイベントがどのエージェントに関連しているかを取得できます。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) — LLM からのメッセージ。`raw` は生成されたメッセージ -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) — LLM がハンドオフ ツールを呼び出したことを示します。`raw` はツール呼び出しアイテム -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) — ハンドオフが発生したことを示します。`raw` はツールのレスポンス。ソース／ターゲット エージェントにもアクセス可能 -- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) — LLM がツールを呼び出したことを示します -- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) — ツールが呼び出されたことを示します。`raw` はツールのレスポンス。ツール出力にもアクセス可能 -- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) — LLM からの推論アイテム。`raw` は生成された推論 -- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) — LLM がツール呼び出しの承認を要求したことを示します。`raw` はツール呼び出しアイテム +- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元のアイテムは生成されたメッセージです +- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフ ツールを呼び出したことを示します。元のアイテムは LLM のツール呼び出しアイテムです +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。元のアイテムはハンドオフ ツール呼び出しへの応答です。ソース／ターゲットのエージェントにもアクセスできます +- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを呼び出したことを示します +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。元のアイテムはツールの応答です。ツール出力にもアクセスできます +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM の reasoning アイテムを示します。元のアイテムは生成された reasoning です +- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を求めたことを示します。元のアイテムは LLM のツール呼び出しアイテムです ## 状態 -`state` プロパティには実行の状態が入ります。`result` に付随する多くの情報は `state` から導出されていますが、`state` はシリアライズ／デシリアライズ可能で、[エラーからの復旧](/openai-agents-js/ja/guides/running-agents#exceptions) や [`割り込み`](#interruptions) に対処するために、後続の `run` 呼び出しの入力として利用できます。 +`state` プロパティには実行の状態が入ります。`result` に付随するほとんどの情報は `state` から派生していますが、`state` はシリアライズ／デシリアライズ可能で、[エラーからの復旧](/openai-agents-js/ja/guides/running-agents#exceptions) が必要な場合や [`interruption`](#interruptions) を処理する必要がある場合に、後続の `run` 呼び出しへの入力としても使用できます。 -## 割り込み +## 中断 (Interruption) -エージェントで `needsApproval` を使用している場合、`run` 中に処理すべき `interruptions` が発生することがあります。その場合、`interruptions` は割り込みを引き起こした `ToolApprovalItem` の配列になります。割り込みの扱いについては [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) を参照してください。 +エージェントで `needsApproval` を使用している場合、`run` が継続する前に処理すべき `interruptions` が発生することがあります。その場合、`interruptions` には中断を引き起こした `ToolApprovalItem` の配列が入ります。中断の扱い方については [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) ガイドを参照してください。 ## その他の情報 -### 元レスポンス +### 元の応答 -`rawResponses` プロパティには、エージェント実行中にモデルが生成した元の LLM レスポンスが入ります。 +`rawResponses` プロパティには、エージェント実行中にモデルが生成した元の LLM 応答が入ります。 -### 最後のレスポンス ID +### 最後の応答 ID -`lastResponseId` プロパティには、エージェント実行中にモデルが最後に生成したレスポンスの ID が入ります。 +`lastResponseId` プロパティには、エージェント実行中にモデルが生成した最後の応答の ID が入ります。 ### ガードレール結果 -`inputGuardrailResults` と `outputGuardrailResults` には、ガードレールの結果が入ります（存在する場合）。ログや保存に役立つ情報が含まれていることがあるため、これらを利用できます。 +`inputGuardrailResults` および `outputGuardrailResults` プロパティには、ガードレールが存在する場合その結果が入ります。ガードレール結果にはログや保存に有用な情報が含まれることがあるため、これらを利用できるようにしています。 -### 元入力 +### 元の入力 -`input` プロパティには `run` メソッドに渡した元の入力が入ります。通常は不要ですが、必要な場合のために提供しています。 +`input` プロパティには `run` メソッドに渡した元の入力が入ります。ほとんどの場合は不要ですが、必要に応じて利用できます。 diff --git a/docs/src/content/docs/ja/guides/running-agents.mdx b/docs/src/content/docs/ja/guides/running-agents.mdx index c59996ec..3563fdac 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -9,112 +9,112 @@ import helloWorldExample from '../../../../../../examples/docs/hello-world.ts?ra import runningAgentsExceptionExample from '../../../../../../examples/docs/running-agents/exceptions1.ts?raw'; import chatLoopExample from '../../../../../../examples/docs/running-agents/chatLoop.ts?raw'; -エージェントは単体では何もしません — `Runner` クラスまたは `run()` ユーティリティで **実行** します。 +エージェントはそれ単体では何もしません。`Runner` クラスまたは `run()` ユーティリティで **実行** します。 - + -独自のランナーが不要な場合は、`run()` ユーティリティを使用できます。これはシングルトンのデフォルト `Runner` インスタンスを実行します。 +カスタム Runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスで実行される `run()` ユーティリティを利用できます。 -または独自の `Runner` インスタンスを作成できます。 +また、自分で Runner インスタンスを生成することもできます。 - + -エージェントを実行すると、最終出力と実行の完全な履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトが返されます。 +エージェントを実行すると、最終出力と実行履歴が含まれる [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 ## エージェントループ -`Runner` の `run` メソッドを使用する際は、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）か、OpenAI Responses API のアイテムである入力アイテムのリストのどちらかです。 +Runner の `run` メソッドを使うときは、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージとみなされます）または OpenAI Responses API の項目である input items のリスト、のいずれかです。 -ランナーは次のループを実行します。 +Runner は次のループを実行します。 1. 現在の入力で現在のエージェントのモデルを呼び出す -2. LLM のレスポンスを確認 +2. LLM 応答を検査する - **最終出力** → 返却 - - **ハンドオフ** → 新しいエージェントに切り替え、これまでの会話履歴を保持して 1 へ + - **ハンドオフ** → 新しいエージェントへ切り替え、これまでの会話履歴を保持して 1 へ - **ツール呼び出し** → ツールを実行し、その結果を会話に追加して 1 へ -3. `maxTurns` に達すると [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスロー +3. `maxTurns` に達した場合は [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスロー -### Runner ライフサイクル +### Runner のライフサイクル -アプリ起動時に `Runner` を作成し、リクエスト間で再利用してください。このインスタンスにはモデル プロバイダーやトレーシング オプションなどのグローバル設定が保存されます。まったく異なる設定が必要な場合のみ別の `Runner` を作成します。簡単なスクリプトであれば、内部でデフォルト ランナーを使う `run()` を呼び出しても構いません。 +アプリ起動時に `Runner` を作成し、リクエスト間で再利用してください。このインスタンスはモデルプロバイダーやトレーシング設定などのグローバル設定を保持します。まったく異なる設定が必要な場合のみ、新しい `Runner` を作成します。簡単なスクリプトでは内部でデフォルト Runner を使用する `run()` を呼び出すこともできます。 -## 実行引数 +## Run 引数 -`run()` メソッドには、開始エージェント、実行入力、およびオプションを渡します。 +`run()` メソッドへの入力は、実行開始エージェント、実行入力、およびオプションのセットです。 -入力は文字列、[入力アイテム](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [Human in the loop](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築する場合の [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 +入力は文字列、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [Human in the loop](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築する場合の [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 -追加オプションは次のとおりです。 +追加オプションは以下のとおりです。 -| Option | Default | 説明 | -| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `stream` | `false` | `true` の場合、`StreamedRunResult` が返り、モデルから届くイベントを随時受け取ります | -| `context` | – | すべてのツール / ガードレール / ハンドオフに転送されるコンテキスト オブジェクト。詳しくは [コンテキスト管理](/openai-agents-js/ja/guides/context) | -| `maxTurns` | `10` | セーフティ制限 — 到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスロー | -| `signal` | – | キャンセル用の `AbortSignal` | +| Option | Default | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `stream` | `false` | `true` の場合、`StreamedRunResult` を返し、モデルから到着したイベントを随時発火します。 | +| `context` | – | すべてのツール / ガードレール / ハンドオフに転送されるコンテキストオブジェクト。詳細は [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照。 | +| `maxTurns` | `10` | セーフティリミット – 到達すると [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローします。 | +| `signal` | – | キャンセル用の `AbortSignal` | ## ストリーミング -ストリーミングを有効にすると、LLM 実行中にイベントを逐次受け取れます。ストリームが開始されると、`StreamedRunResult` には実行に関する完全な情報（新しく生成された出力を含む）が入ります。`for await` ループでストリーミング イベントを反復処理できます。詳細は [ストリーミング](/ja/guides/streaming) ガイドをご覧ください。 +ストリーミングを有効にすると、LLM 実行中のイベントを逐次受け取れます。ストリームが開始されると、`StreamedRunResult` に実行に関する完全な情報（新たな出力を含む）が格納されます。`for await` ループでストリーミングイベントを反復できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) ガイドを参照してください。 -## 実行設定 +## Run 設定 -独自の `Runner` インスタンスを作成する場合、`RunConfig` オブジェクトで設定できます。 +独自の `Runner` インスタンスを作成する場合は、`RunConfig` オブジェクトで Runner を設定できます。 -| Field | Type | 目的 | -| --------------------------- | --------------------- | ---------------------------------------------------------------------------- | -| `model` | `string \| Model` | 実行中の **すべて** のエージェントに対して特定のモデルを強制します | -| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダー | -| `modelSettings` | `ModelSettings` | 各エージェント設定を上書きするグローバルなチューニング パラメーター | -| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ時に入力アイテムを変換します（ハンドオフ側で定義されていない場合） | -| `inputGuardrails` | `InputGuardrail[]` | _最初の_ ユーザー入力に適用されるガードレール | -| `outputGuardrails` | `OutputGuardrail[]` | _最終_ 出力に適用されるガードレール | -| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化 | -| `traceIncludeSensitiveData` | `boolean` | LLM / ツールの入出力を除外しつつスパンを送信 | -| `workflowName` | `string` | Traces ダッシュボードに表示され、関連実行をグループ化する際に役立ちます | -| `traceId` / `groupId` | `string` | SDK に生成させず手動でトレース ID やグループ ID を指定 | -| `traceMetadata` | `Record` | すべてのスパンに付与される任意のメタデータ | +| Field | Type | Purpose | +| --------------------------- | --------------------- | -------------------------------------------------------------------------------- | +| `model` | `string \| Model` | すべてのエージェントに対して特定モデルを強制指定します。 | +| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダーです。 | +| `modelSettings` | `ModelSettings` | エージェント単位の設定を上書きするグローバルチューニングパラメーター。 | +| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ時に入力項目を変換します（ハンドオフ自体で既に定義されていない場合）。 | +| `inputGuardrails` | `InputGuardrail[]` | 初期ユーザー入力に適用されるガードレール。 | +| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール。 | +| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します。 | +| `traceIncludeSensitiveData` | `boolean` | スパンは生成しつつ、トレースから LLM/ツール入出力を除外します。 | +| `workflowName` | `string` | Traces ダッシュボードに表示され、関連実行をグループ化するのに役立ちます。 | +| `traceId` / `groupId` | `string` | SDK による自動生成ではなく、トレース ID またはグループ ID を手動指定します。 | +| `traceMetadata` | `Record` | すべてのスパンに付与する任意のメタデータ。 | ## 会話 / チャットスレッド -`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーション レベルの会話における 1 **ターン** を表します。 -エンドユーザーに `RunResult` のどこまでを表示するかは自由です — `finalOutput` だけを見せる場合もあれば、生成されたすべてのアイテムを見せる場合もあります。 +`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における **1 ターン** を表します。 +エンドユーザーにどの程度の `RunResult` を表示するかは自由です。`finalOutput` のみを表示する場合もあれば、生成されたすべての項目を表示する場合もあります。 - + -インタラクティブ版は [チャットのコード例](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 +対話型バージョンは [チャットのコード例](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) をご覧ください。 ## 例外 -SDK は次の少数のエラーをスローします。必要に応じてキャッチしてください。 +SDK は次の少数のエラーをスローします（捕捉可能）。 -- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) — `maxTurns` に到達 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) — モデルが無効な出力を生成（例: JSON 形式不正、未知のツール） -- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) — ガードレール違反 -- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) — ガードレールの実行に失敗 -- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) — 関数ツール呼び出しが失敗 -- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) — 設定やユーザー入力に基づくエラー +- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` に到達 +- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが無効な出力を生成（例: 不正な JSON、未知のツール） +- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) – ガードレール違反 +- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールの実行失敗 +- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – いずれかの関数ツール呼び出しが失敗 +- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 設定またはユーザー入力に基づくエラー -これらはすべて基底クラス `AgentsError` を継承しており、現在の実行状態にアクセスできる `state` プロパティを提供する場合があります。 +すべて基底クラス `AgentsError` を継承しており、現在の実行状態にアクセスできる `state` プロパティを持つ場合があります。 -以下は `GuardrailExecutionError` を処理する例です。 +以下は `GuardrailExecutionError` を処理するコード例です。 -上記を実行すると次の出力が得られます。 +上記を実行すると、次のような出力が得られます。 ``` Guardrail execution failed: Error: Input guardrail failed to complete: Error: Something is wrong! @@ -125,6 +125,6 @@ Math homework guardrail tripped ## 次のステップ -- [モデル](/openai-agents-js/ja/guides/models) の設定方法を学ぶ +- [モデル](/openai-agents-js/ja/guides/models) を設定する - エージェントに [ツール](/openai-agents-js/ja/guides/tools) を提供する -- 本番環境に向けて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加する +- 本番運用に向けて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加する diff --git a/docs/src/content/docs/ja/guides/streaming.mdx b/docs/src/content/docs/ja/guides/streaming.mdx index e315b37a..b533bd64 100644 --- a/docs/src/content/docs/ja/guides/streaming.mdx +++ b/docs/src/content/docs/ja/guides/streaming.mdx @@ -9,19 +9,19 @@ import nodeTextStreamExample from '../../../../../../examples/docs/streaming/nod import handleAllEventsExample from '../../../../../../examples/docs/streaming/handleAllEvents.ts?raw'; import streamedHITLExample from '../../../../../../examples/docs/streaming/streamedHITL.ts?raw'; -Agents SDK はモデルからの出力やその他の実行ステップの結果を段階的に配信できます。ストリーミングにより UI の応答性を保ち、最終的な実行結果がそろうまで待たずにユーザーを更新できます。 +Agents SDK は、モデルの出力やその他の実行ステップをインクリメンタルに配信できます。ストリーミングを利用すると、UI が常にレスポンシブになり、最終的な実行結果をすべて受け取るまで待たずに ユーザー を更新できます。 ## ストリーミングの有効化 -`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミング オブジェクトを取得できます。 +`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果の代わりにストリーミングオブジェクトが返されます。 -ストリーミングが有効になると、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは実行中に発生した内容を示すオブジェクトです。多くのアプリケーションが必要とするのはモデルのテキストだけなので、ストリームには補助メソッドが用意されています。 +ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イテレーションで、実行中に発生したイベントを表すオブジェクトが得られます。多くのアプリケーションはモデルのテキストだけを必要とするため、ストリームには補助メソッドが用意されています。 ### テキスト出力の取得 @@ -30,42 +30,42 @@ Agents SDK はモデルからの出力やその他の実行ステップの結果 -`stream.completed` という Promise は、実行と保留中のすべてのコールバックが完了すると解決します。追加出力がないことを保証したい場合は必ず待機してください。 +`stream.completed` という Promise は、実行と保留中のすべてのコールバックが完了した時点で解決されます。出力がもう増えないことを保証したい場合は必ず await してください。 -### すべてのイベントの監視 +### すべてのイベントを監視 -`for await` ループを使って、到着した各イベントを確認できます。低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などが含まれます。 +`for await` ループを使って、到着したイベントを逐次確認できます。低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などが含まれます。 -プレーンテキスト ストリームと raw イベント ストリームの両方を出力する完全なスクリプトは、[the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。 +完全なスクリプトは、[ストリーミングの例](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。プレーンテキストストリームと元のイベントストリームの両方を出力します。 -## ストリーミング中の Human in the loop（人間の介入） +## ストリーミング中の Human in the loop -ストリーミングは、実行を一時停止するハンドオフ（例: ツールの承認が必要な場合）とも互換性があります。ストリーム オブジェクトの `interruption` フィールドで中断を検出でき、各中断に対して `state.approve()` または `state.reject()` を呼び出して実行を続行できます。再度 `{ stream: true }` を指定して実行するとストリーミング出力が再開します。 +ストリーミングは、実行を一時停止するハンドオフ（たとえばツールの承認待ち）と互換性があります。ストリームオブジェクトの `interruption` フィールドで割り込みを確認し、それぞれに対して `state.approve()` または `state.reject()` を呼び出すことで実行を継続できます。再度 `{ stream: true }` を指定して実行すると、ストリーミング出力が再開されます。 -ユーザーと対話するより完全な例は +ユーザーと対話するより詳細な例は [`human-in-the-loop-stream.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop-stream.ts) を参照してください。 ## ヒント -- すべての出力がフラッシュされるのを確実にするため、終了前に `stream.completed` を必ず待機してください -- 最初の `{ stream: true }` オプションは指定した呼び出しにのみ適用されます。`RunState` で再実行する場合は再度このオプションを指定してください -- テキスト結果だけが必要なアプリケーションでは、個々のイベントを扱わずに済むよう `toTextStream()` を使用してください +- プロセスを終了する前に `stream.completed` を待機し、すべての出力がフラッシュされたことを確認する +- 最初の `{ stream: true }` オプションは、指定した呼び出しにのみ適用される。`RunState` で再実行する場合は再度オプションを指定する +- テキスト結果のみが必要な場合は、個々のイベントオブジェクトを扱わずに済む `toTextStream()` を使用する -ストリーミングとイベント システムを利用すれば、エージェントをチャット インターフェース、ターミナル アプリケーションなど、段階的な更新がユーザーの利点となるあらゆる場所に統合できます。 +ストリーミングとイベントシステムを組み合わせることで、チャットインターフェースやターミナルアプリケーションなど、インクリメンタルな更新が有用なあらゆる場所にエージェントを組み込めます。 diff --git a/docs/src/content/docs/ja/guides/tools.mdx b/docs/src/content/docs/ja/guides/tools.mdx index ff23986b..d4a4b0e4 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -9,36 +9,35 @@ import toolsHostedToolsExample from '../../../../../../examples/docs/tools/hoste import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStrictSchemaTools.ts?raw'; import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; -ツールを使うとエージェントが **アクションを実行** できます。たとえばデータ取得、外部 API 呼び出し、コード実行、さらにはコンピュータ操作まで行えます。JavaScript / TypeScript SDK では次の 3 つのカテゴリーをサポートしています。 +ツールを使うことで、エージェントは **行動を実行** できます。たとえばデータの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータ操作まで可能です。JavaScript / TypeScript SDK は次の 3 カテゴリーをサポートします: -1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと一緒に動作 - _(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_ -2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM が呼び出せるようにする -3. **エージェントをツールとして公開** – エージェント全体を呼び出し可能なツールとして公開 +1. **組み込みツール（Hosted）** – モデルと同じ OpenAI サーバー上で動作します。 _(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_ +2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM から呼び出せるようにします。 +3. **エージェントをツールとして使用** – エージェント全体を呼び出し可能なツールとして公開します。 --- ## 1. 組み込みツール（Hosted） -`OpenAIResponsesModel` を使用する際、以下のビルトインツールを追加できます。 +`OpenAIResponsesModel` を使用すると、次の組み込みツールを追加できます: -| ツール | type 文字列 | 目的 | -| ---------------- | -------------------- | --------------------------------------- | -| Web 検索 | `'web_search'` | インターネット検索 | -| ファイル / 検索 | `'file_search'` | OpenAI がホストするベクトルストアの検索 | -| コンピュータ操作 | `'computer'` | GUI 操作を自動化 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | -| 画像生成 | `'image_generation'` | テキストから画像を生成 | +| ツール | 型文字列 | 目的 | +| ----------------------- | -------------------- | ------------------------------------------- | +| Web 検索 | `'web_search'` | インターネット検索 | +| File / retrieval search | `'file_search'` | OpenAI がホストするベクトルストアへのクエリ | +| コンピュータ操作 | `'computer'` | GUI 操作を自動化 | +| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | +| 画像生成 | `'image_generation'` | テキストに基づいて画像を生成 | -各ツールのパラメーターは OpenAI Responses API と同一です。`rankingOptions` やセマンティックフィルターなど詳細は公式ドキュメントをご覧ください。 +パラメーターの詳細は OpenAI Responses API と一致します。`rankingOptions` やセマンティックフィルタなど高度なオプションは公式ドキュメントをご覧ください。 --- ## 2. 関数ツール -`tool()` ヘルパーを使えば **どんな** 関数でもツールに変換できます。 +`tool()` ヘルパーを使うと **どんな** 関数でもツールに変換できます。 string \| Promise` – ビジネスロジック。第 2 引数は省略可能で `RunContext` | -| `errorFunction` | いいえ | 内部エラーをユーザー可視の文字列へ変換するカスタムハンドラー `(context, error) => string` | +| フィールド | 必須 | 説明 | +| --------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | No | 省略時は関数名 (例: `get_weather`) が使用されます | +| `description` | Yes | LLM に表示される、わかりやすい説明 | +| `parameters` | Yes | Zod スキーマまたは raw JSON スキーマオブジェクト。Zod を使用すると **strict** モードが自動で有効になります | +| `strict` | No | `true` (デフォルト) の場合、引数の検証に失敗すると SDK はモデルエラーを返します。曖昧なマッチングを許可する場合は `false` に設定します | +| `execute` | Yes | `(args, context) => string \| Promise` – ビジネスロジック。第 2 引数には省略可能な `RunContext` が渡されます | +| `errorFunction` | No | 内部エラーをユーザー向けメッセージへ変換するカスタムハンドラー `(context, error) => string` | -### 非 strict JSON スキーマツール +### 非 strict な JSON スキーマツール -無効または部分的な入力をモデルに _推測_ させたい場合は、raw JSON スキーマ使用時に strict モードを無効化できます。 +モデルに無効あるいは部分的な入力を **推測** させたい場合は、raw JSON スキーマ使用時に strict モードを無効化できます: -SDK 内部では以下を行います。 +SDK は内部で次の処理を行います: -- `input` パラメーター 1 つだけの関数ツールを作成 -- ツール呼び出し時にその入力でサブエージェントを実行 -- 最後のメッセージ、または `customOutputExtractor` が抽出した出力を返却 +- 単一の `input` パラメーターを持つ関数ツールを生成 +- ツール呼び出し時にサブエージェントをその入力で実行 +- 最後のメッセージ、または `customOutputExtractor` で抽出した出力を返却 --- ## ツール使用の挙動 -モデルにツール使用を必須化する方法などは [エージェント](/openai-agents-js/guides/agents#forcing-tool-use) を参照してください (`tool_choice`、`toolUseBehavior` など)。 +ツールを **いつ・どのように** 使うかを制御する方法は、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください (`tool_choice`、`toolUseBehavior` など)。 --- ## ベストプラクティス -- **短く明確な説明** – ツールが _何を行い、いつ使うか_ を具体的に記述 -- **入力を検証** – 可能なら Zod スキーマで厳格な JSON 検証を実施 -- **エラーハンドラーで副作用を避ける** – `errorFunction` は有益な文字列を返すだけにし、例外を投げない -- **ツールは単一責務** – 小さく再利用可能なツールはモデルの推論を助けます +- **短く明確な説明** – ツールが _何をするか_、_いつ使うか_ を明確に記述する +- **入力を検証** – 可能な限り Zod スキーマで厳格な JSON 検証を行う +- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返すだけにし、例外は投げない +- **ツールは単一責務** – 小さく再利用可能なツールに分割するとモデルの推論精度が向上 --- ## 次のステップ -- [ツール使用の強制](/openai-agents-js/guides/agents#forcing-tool-use) を学習 -- [ガードレール](/openai-agents-js/guides/guardrails) を追加してツールの入力・出力を検証 -- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツール型の TypeDoc リファレンスを掘り下げる +- [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) について学ぶ +- ツールの入力・出力を検証する [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加する +- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツール型の TypeDoc リファレンスを参照する diff --git a/docs/src/content/docs/ja/guides/tracing.mdx b/docs/src/content/docs/ja/guides/tracing.mdx index 6315da86..9ef7019e 100644 --- a/docs/src/content/docs/ja/guides/tracing.mdx +++ b/docs/src/content/docs/ja/guides/tracing.mdx @@ -6,91 +6,91 @@ description: Learn how to trace your agent runs import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; -Agents SDK には組み込みのトレーシング機能があり、エージェント実行中に発生するイベントの網羅的な記録を収集します。これには LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまでも含まれます。[Traces ダッシュボード](https://platform.openai.com/traces)を使うと、開発時や本番環境でワークフローをデバッグ・可視化・モニタリングできます。 +Agents SDK にはトレーシング機能が組み込まれており、エージェントの実行中に発生する LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで、あらゆるイベントを詳細に記録します。 +[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発時および本番環境でワークフローをデバッグ、可視化、監視できます。 ## トレースとスパン -- **トレース (Trace)** は「ワークフロー」の単一のエンドツーエンド操作を表します。トレースは Span で構成され、次のプロパティを持ちます - - `workflow_name`: 「コード生成」「カスタマーサービス」など、論理的なワークフローまたはアプリの名前 - - `trace_id`: トレースの一意 ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` - - `group_id`: 会話の複数トレースをリンクするためのオプション ID。例としてチャットスレッド ID など +- **トレース**: 1 つの「ワークフロー」のエンドツーエンドの操作を表します。トレースはスパンで構成され、次のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリ名。例: 「Code generation」や「Customer service」 + - `trace_id`: トレースの一意 ID。指定しない場合は自動生成。形式は `trace_<32_alphanumeric>` + - `group_id`: 省略可。同じ会話からの複数トレースを関連付けるためのグループ ID。例: チャットスレッド ID など - `disabled`: `true` の場合、このトレースは記録されません - `metadata`: トレースに付与する任意のメタデータ -- **スパン (Span)** は開始時刻と終了時刻を持つ操作を表します - - `started_at` と `ended_at` のタイムスタンプ - - 所属するトレースを示す `trace_id` - - 親 Span を指す `parent_id`（存在する場合） - - `span_data`: Span の情報。たとえば `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など +- **スパン**: 開始時刻と終了時刻を持つ操作を表します。スパンには次があります: + - `started_at` と `ended_at` タイムスタンプ + - 所属トレースを示す `trace_id` + - 親スパンを指す `parent_id`（存在する場合） + - スパンに関する情報を保持する `span_data`。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など ## デフォルトのトレーシング -デフォルトでは、SDK は次をトレースします。 +デフォルトでは、SDK は次をトレースします: -- `run()` または `Runner.run()` 全体を 1 つの `Trace` でラップ -- エージェント実行ごとに `AgentSpan` でラップ -- LLM 生成は `GenerationSpan` でラップ -- 関数ツール呼び出しはそれぞれ `FunctionSpan` でラップ -- ガードレールは `GuardrailSpan` でラップ -- ハンドオフは `HandoffSpan` でラップ +- `run()` または `Runner.run()` 全体を `Trace` でラップ +- エージェントが実行されるたびに `AgentSpan` でラップ +- LLM 生成を `GenerationSpan` でラップ +- 関数ツール呼び出しをそれぞれ `FunctionSpan` でラップ +- ガードレールを `GuardrailSpan` でラップ +- ハンドオフを `HandoffSpan` でラップ -トレース名はデフォルトで "Agent workflow" です。`withTrace` を使う、または [`RunConfig.workflowName`](/openai/agents-core/type-aliases/runconfig/#workflowname) で名前や他のプロパティを設定できます。 +トレース名はデフォルトで 「Agent workflow」 です。`withTrace` を使用して名前を設定するか、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他プロパティを設定できます。 -さらに、[カスタムトレースプロセッサ](#custom-tracing-processors)を設定して、トレースを別の宛先へ送信（置換または追加）することもできます。 +さらに、[カスタムトレースプロセッサ](#custom-tracing-processors) を設定して、他の送信先へトレースを送信（置換または追加）することもできます。 ### 音声エージェントのトレーシング -既定の OpenAI Realtime API で `RealtimeAgent` と `RealtimeSession` を使用している場合、トレーシングは Realtime API 側で自動的に行われます。トレーシングを無効化するには `RealtimeSession` の `tracingDisabled: true` か、環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を設定してください。 +`RealtimeAgent` と `RealtimeSession` を OpenAI Realtime API のデフォルト設定で使用している場合、トレーシングは Realtime API 側で自動的に行われます。`RealtimeSession` で `tracingDisabled: true` を設定するか、`OPENAI_AGENTS_DISABLE_TRACING` 環境変数を使用すると無効化できます。 -詳細は[音声エージェントの概要](/ja/guides/voice-agents)を参照してください。 +詳細は [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 -## より高いレベルのトレース +## 上位トレース -複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合は、コード全体を `withTrace()` でラップします。 +複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合、コード全体を `withTrace()` でラップします。 -1. `run` の 2 回の呼び出しが `withTrace()` に包まれているため、それぞれが個別のトレースを作らず、全体のトレースに含まれます +1. `withTrace()` で 2 回の `run` 呼び出しをラップしているため、各実行は個別にトレースを作成せず、全体のトレースに含まれます。 ## トレースの作成 -[`withTrace()`](/openai/agents-core/functions/withtrace/) 関数を使ってトレースを作成できます。あるいは `getGlobalTraceProvider().createTrace()` でトレースを手動作成し、`withTrace()` に渡すことも可能です。 +[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数でトレースを作成できます。あるいは `getGlobalTraceProvider().createTrace()` で手動で新しいトレースを生成し、それを `withTrace()` に渡すことも可能です。 -現在のトレースは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) またはそれに相当するポリフィルで追跡されるため、並行実行時にも自動で機能します。 +現在のトレースは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または同等の環境ポリフィルにより追跡されるため、並列処理でも自動的に機能します。 ## スパンの作成 -`createGenerationSpan()` や `createFunctionSpan()` などの `create*Span()` メソッドでスパンを作成できます。通常は手動で作成する必要はありません。独自のスパンを追跡したい場合は [`createCustomSpan()`](/openai/agents-core/functions/createcustomspan/) が利用できます。 +`createGenerationSpan()` や `createFunctionSpan()` など、各種 `create*Span()` メソッドでスパンを作成できます。通常は手動でスパンを作成する必要はありません。カスタムスパンを追跡するには [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) を使用してください。 -スパンは自動的に現在のトレースに属し、最も近い親スパンの下にネストされます。これは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応するポリフィルで管理されています。 +スパンは自動的に現在のトレースに含まれ、最も近い現在のスパンの下にネストされます。これも [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または同等の環境ポリフィルで追跡されます。 -## 機微なデータ +## 機微データ -一部のスパンは機微なデータを含む可能性があります。 +一部のスパンは機微なデータを収集する可能性があります。 -`createGenerationSpan()` は LLM 生成の入出力を、`createFunctionSpan()` は関数呼び出しの入出力を保存します。機微なデータを含む場合があるため、[`RunConfig.traceIncludeSensitiveData`](/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) で保存を無効化できます。 +`createGenerationSpan()` は LLM 生成の入力／出力、`createFunctionSpan()` は関数呼び出しの入力／出力を保存します。これらに機微データが含まれる場合があるため、[`RunConfig.traceIncludeSensitiveData`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) でデータ収集を無効化できます。 -## カスタムトレーシングプロセッサ +## カスタムトレースプロセッサ -トレーシングの高レベルアーキテクチャは次のとおりです。 +トレーシングの高レベル構成は次のとおりです: -- 初期化時にグローバルな [`TraceProvider`](/openai/agents-core/classes/traceprovider) を生成し、[`getGlobalTraceProvider()`](/openai/agents-core/functions/getglobaltraceprovider/) からアクセスします -- `TraceProvider` には [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) を設定し、これがトレース／スパンをバッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に送信します -- `OpenAITracingExporter` はバッチで OpenAI バックエンドへエクスポートします +- 初期化時にグローバル [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレースを作成し、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) で取得できます。 +- `TraceProvider` は [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) を介してトレース／スパンをバッチ送信し、[`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) がそれらをバッチで OpenAI バックエンドへエクスポートします。 -このデフォルト設定をカスタマイズし、別のバックエンドへ送信したりエクスポーターの動作を変更したりするには 2 つの方法があります。 +デフォルト設定を変更し、別のバックエンドへの送信やエクスポーターの挙動を変更する場合、次の 2 つの方法があります: 1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) - デフォルトの処理に **追加** して、準備が整ったトレースやスパンを受け取る独自のトレースプロセッサを追加します。これにより、OpenAI バックエンドに送信しつつ独自処理を行えます。 + 既定の送信先に加えて、トレース／スパンが準備完了時に受け取れる **追加** のトレースプロセッサを登録できます。 2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) - デフォルトのプロセッサを **置換** し、独自のトレースプロセッサのみを使用します。OpenAI バックエンドへは `TracingProcessor` を含めない限り送信されません。 + 既定のプロセッサを **置換** し、独自のトレースプロセッサのみを使用できます。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含める必要があります。 diff --git a/docs/src/content/docs/ja/guides/troubleshooting.mdx b/docs/src/content/docs/ja/guides/troubleshooting.mdx index fd332c11..1efde504 100644 --- a/docs/src/content/docs/ja/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ja/guides/troubleshooting.mdx @@ -3,29 +3,29 @@ title: トラブルシューティング description: Learn how to troubleshoot issues with the OpenAI Agents SDK. --- -## サポートされている環境 +## 対応環境 -OpenAI Agents SDK は次のサーバー環境でサポートされています: +OpenAI Agents SDK は、以下のサーバー環境でサポートされます: - Node.js 22+ - Deno 2.35+ - Bun 1.2.5+ -### 限定サポート +### 制限付きサポート -- **Cloudflare Workers**: Agents SDK は Cloudflare Workers で使用できますが、現在はいくつかの制限があります: - - 現在、この SDK を使用するには `nodejs_compat` を有効にする必要があります - - SDK は動的インポート `await import('@openai/agents')` でのみ読み込むことができます - - `AsyncLocalStorage` へのサポートが限定的なため、一部のトレースが正確にならない可能性があります -- **ブラウザ**: - - ブラウザでは現在トレーシングはサポートされていません +- **Cloudflare Workers**: Agents SDK は Cloudflare Workers でも利用できますが、現在以下の制限があります: + - SDK では `nodejs_compat` を有効にする必要があります + - SDK は動的インポート `await import('@openai/agents')` でのみ読み込めます + - Cloudflare Workers の `AsyncLocalStorage` の限定的なサポートにより、トレースが正確でない場合があります +- **ブラウザー**: + - ブラウザーではトレーシングは現在サポートされていません - **v8 isolates**: - - 適切なブラウザ用ポリフィルを備えたバンドラーを使用すれば v8 isolates 向けに SDK をバンドルできますが、トレーシングは機能しません + - 適切なブラウザーポリフィルを持つバンドラーを使用すれば v8 isolates 向けに SDK をバンドルできますが、トレーシングは機能しません - v8 isolates での動作は十分にテストされていません ## デバッグログ -SDK の使用で問題が発生した場合、デバッグログを有効にすると状況の詳細が確認できます。 +SDK の利用中に問題が発生した場合は、デバッグログを有効にして詳細情報を取得できます。 `DEBUG` 環境変数に `openai-agents:*` を設定するとデバッグログが有効になります。 @@ -33,8 +33,8 @@ SDK の使用で問題が発生した場合、デバッグログを有効にす DEBUG=openai-agents:* ``` -また、以下のように対象を限定してデバッグすることもできます: +特定のコンポーネントだけをデバッグすることも可能です: -- `openai-agents:core` — SDK の主な実行ロジック用 -- `openai-agents:openai` — OpenAI API 呼び出し用 -- `openai-agents:realtime` — Realtime Agents コンポーネント用 +- `openai-agents:core` — SDK のメイン実行ロジック +- `openai-agents:openai` — OpenAI API 呼び出し +- `openai-agents:realtime` — Realtime Agents コンポーネント diff --git a/docs/src/content/docs/ja/guides/voice-agents.mdx b/docs/src/content/docs/ja/guides/voice-agents.mdx index 08760c4d..cee28229 100644 --- a/docs/src/content/docs/ja/guides/voice-agents.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents.mdx @@ -25,27 +25,27 @@ import thinClientExample from '../../../../../../examples/docs/voice-agents/thin ![Realtime Agents](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) -Voice Agents は OpenAI の speech-to-speech モデルを利用してリアルタイムの音声チャットを実現します。これらのモデルは音声・テキスト・ツール呼び出しをストリーミングで扱え、音声／電話のカスタマーサポートやモバイルアプリでの音声体験、音声チャットなどに最適です。 +音声エージェントは、OpenAI の音声 to 音声モデルを利用してリアルタイムの音声チャットを提供します。これらのモデルはストリーミング音声・テキスト・ツール呼び出しをサポートしており、音声／電話のカスタマーサポート、モバイルアプリ体験、音声チャットなどの用途に最適です。 -Voice Agents SDK は [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) 用の TypeScript クライアントを提供します。 +Voice Agents SDK は、OpenAI Realtime API 向けの TypeScript クライアントを提供します。 -### 主要機能 +### 主な機能 -- WebSocket もしくは WebRTC で接続 -- ブラウザとバックエンドの両方で利用可能 -- オーディオおよび割り込み処理 -- ハンドオフによるマルチエージェントのオーケストレーション -- ツール定義と呼び出し +- WebSocket または WebRTC 経由で接続 +- ブラウザでもバックエンド接続でも利用可能 +- 音声と割り込みのハンドリング +- ハンドオフによるマルチエージェントオーケストレーション +- ツールの定義と呼び出し - モデル出力を監視するカスタムガードレール - ストリーミングイベント用のコールバック - テキストエージェントと音声エージェントで同じコンポーネントを再利用 -speech-to-speech モデルを使用することで、音声をテキストに書き起こして再度音声に変換し直す手間なく、モデルがオーディオをリアルタイムで処理できます。 +音声 to 音声モデルを使用することで、モデルが音声をリアルタイムに処理できるため、テキストへ文字起こししてから再び音声に変換し直す必要がありません。 -![Speech-to-speech model](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) +![音声 to 音声モデル](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) diff --git a/docs/src/content/docs/ja/guides/voice-agents/build.mdx b/docs/src/content/docs/ja/guides/voice-agents/build.mdx index 1892ba71..cc53d0a1 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/build.mdx @@ -28,46 +28,45 @@ import serverAgentExample from '../../../../../../../examples/docs/voice-agents/ import delegationAgentExample from '../../../../../../../examples/docs/voice-agents/delegationAgent.ts?raw'; import turnDetectionExample from '../../../../../../../examples/docs/voice-agents/turnDetection.ts?raw'; -## オーディオ処理 +## 音声処理 -デフォルトの `OpenAIRealtimeWebRTC` など一部のトランスポートレイヤーは、オーディオの入出力を自動で処理します。 -`OpenAIRealtimeWebSocket` のようなその他のトランスポートを使用する場合は、セッションのオーディオを自前で処理する必要があります。 +デフォルトの `OpenAIRealtimeWebRTC` のような一部のトランスポートレイヤーは、音声の入出力を自動的に処理します。`OpenAIRealtimeWebSocket` など別のトランスポートを使用する場合は、セッションの音声を自分で処理する必要があります。 ## セッション設定 -[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) を生成するとき、または `connect(...)` を呼び出すときに追加オプションを渡すことでセッションを設定できます。 +[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) のコンストラクター、または `connect(...)` を呼び出す際に追加オプションを渡すことで、セッションを設定できます。 -これらのトランスポートレイヤーでは、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) と一致する任意のパラメーターを渡せます。 +これらのトランスポートレイヤーでは、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 -[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に対応するパラメーターがまだ存在しない場合は `providerData` を使用してください。`providerData` に渡した内容は `session` オブジェクトの一部としてそのまま送信されます。 +[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に存在しない新しいパラメーターを渡したい場合は `providerData` を使用してください。`providerData` に渡された内容は `session` オブジェクトの一部としてそのまま転送されます。 ## ハンドオフ -通常のエージェントと同様に、ハンドオフを利用してエージェントを複数のエージェントに分割し、相互にオーケストレーションすることでパフォーマンスを向上させたり、問題のスコープを絞り込んだりできます。 +通常のエージェントと同様に、ハンドオフを利用してエージェントを複数に分割し、それらをオーケストレーションしてパフォーマンスを向上させたり、問題のスコープを絞り込んだりできます。 -Realtime Agents ではハンドオフの挙動が通常のエージェントと少し異なります。ハンドオフが実行されると、進行中のセッションは新しいエージェント構成で更新されます。そのためエージェントは会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 +Realtime Agent では、ハンドオフの動作が少し異なります。ハンドオフが行われると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは自動的に現在の会話履歴へアクセスでき、入力フィルターは適用されません。 -さらに、ハンドオフの一部として `voice` や `model` を変更することはできません。また、接続できるのは他の Realtime Agent のみです。`o4-mini` のような推論モデルを使用したい場合は、[ツールによる委任](#delegation-through-tools) をご利用ください。 +また、`voice` や `model` はハンドオフの一環として変更できません。接続できるのは他の Realtime Agent のみです。たとえば推論用モデル `o4-mini` など別モデルを使う必要がある場合は、[ツールによる委任](#delegation-through-tools) をご利用ください。 ## ツール -通常のエージェントと同様に、Realtime Agents でもツールを呼び出してアクションを実行できます。ツールは通常のエージェントと同じ `tool()` 関数で定義します。 +通常のエージェントと同じく、Realtime Agent でもツールを呼び出してアクションを実行できます。ツールは通常のエージェントと同じ `tool()` 関数で定義します。 -Realtime Agents で使用できるのは関数ツールのみで、これらのツールは Realtime Session と同じ場所で実行されます。つまり、ブラウザで Realtime Session を実行している場合はツールもブラウザで実行されます。より機密性の高い処理が必要な場合は、ツール内でバックエンドサーバーへの HTTP リクエストを送信してください。 +Realtime Agent で使用できるのは関数ツールのみで、これらのツールは Realtime Session と同じ場所で実行されます。そのため、ブラウザで Realtime Session を実行している場合、ツールもブラウザで実行されます。よりセンシティブな処理が必要な場合は、ツール内からバックエンドサーバーへ HTTP リクエストを送ってください。 -ツール実行中はエージェントが新しい user からのリクエストを処理できません。エージェントに「これからツールを実行します」とアナウンスさせたり、時間稼ぎのフレーズを言わせたりすると体験を向上できます。 +ツールが実行されている間、エージェントは新しいユーザーリクエストを処理できません。体験を向上させる方法として、ツール実行前にエージェントにアナウンスさせたり、処理時間を稼ぐために特定のフレーズを話させたりできます。 ### 会話履歴へのアクセス -エージェントがツールを呼び出す際に渡された引数に加え、Realtime Session が管理している現在の会話履歴のスナップショットにもアクセスできます。会話の状態に基づいてより複雑なアクションを行う場合や、[ツールによる委任](#delegation-through-tools) を計画している場合に便利です。 +エージェントが特定のツールを呼び出した際の引数に加え、Realtime Session が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の状態に応じた複雑な処理を行ったり、[ツールによる委任](#delegation-through-tools) を計画している場合に便利です。 @@ -77,88 +76,88 @@ Realtime Agents で使用できるのは関数ツールのみで、これらの ### ツール実行前の承認 -`needsApproval: true` でツールを定義すると、ツール実行前に `tool_approval_requested` イベントが発火します。 +`needsApproval: true` でツールを定義すると、ツール実行前に `tool_approval_requested` イベントが発行されます。 -このイベントを監視して、ツール呼び出しを承認または拒否する UI をユーザーに提示できます。 +このイベントをリッスンして、ユーザーにツール呼び出しを承認または拒否させる UI を表示できます。 ## ガードレール -ガードレールは、エージェントの発話がルール違反をしたかどうかを監視し、違反があれば直ちにレスポンスを打ち切る仕組みです。チェックはエージェントのレスポンスの文字起こしに基づいて行われるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効）。 +ガードレールは、エージェントが発話した内容がルールに違反していないか監視し、違反時に即座に応答を打ち切る仕組みです。これらのチェックはエージェントの応答の文字起こしに基づいて行われるため、モデルのテキスト出力が有効になっている必要があります（デフォルトで有効）。 -ガードレールはモデルレスポンスが返されると同時に非同期で実行されます。たとえば「特定の禁止ワードを含む」など、あらかじめ定義した分類トリガーに基づきレスポンスを打ち切れます。 +提供したガードレールは、モデルの応答が返されると同時に非同期で実行され、たとえば「特定の禁止ワードを含む」などの分類トリガーに基づいて応答を打ち切れます。 -ガードレールが作動するとセッションは `guardrail_tripped` イベントを発火します。 +ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。 -デフォルトでは、ガードレールは 100 文字ごと、またはレスポンス生成が完了したときに実行されます。読み上げには通常それ以上の時間がかかるため、ほとんどの場合ユーザーが聞く前に違反を検知できます。 +ガードレールはデフォルトで 100 文字ごと、または応答テキスト生成完了時に実行されます。音声での読み上げは通常それより時間がかかるため、ほとんどの場合ユーザーが聞く前に違反を検知できます。 この挙動を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡してください。 -## 発話検出 / 音声アクティビティ検出 +## ターン検出 / 音声活動検出 -Realtime Session は、組み込みの [Realtime API の音声アクティビティ検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使用してユーザーの発話を自動検出し、ターンを開始します。 +Realtime Session は、組み込みの [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使用してユーザーが話しているかを自動的に検知し、新しいターンを開始します。 -`turnDetection` オブジェクトをセッションに渡すことで、音声アクティビティ検出モードを変更できます。 +`turnDetection` オブジェクトをセッションに渡すことで音声活動検出モードを変更できます。 -ターン検出設定を調整すると、不要な割り込みや無音への対応を最適化できます。詳細は [Realtime API ドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください。 +ターン検出設定を調整することで、不要な割り込みや無音への対応を最適化できます。各設定の詳細は [Realtime API ドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください。 ## 割り込み -組み込みの音声アクティビティ検出を使用している場合、エージェントが話している最中にユーザーが話し始めると、自動的に割り込みが検知され、コンテキストが更新されます。また `audio_interrupted` イベントも発火します。これは（ WebSocket 接続時のみ）すべてのオーディオ再生を即時停止する際に利用できます。 +組み込みの音声活動検出を使用している場合、ユーザーがエージェントの発話中に話し始めると、自動的に割り込みが検知され、発話内容に基づいてコンテキストが更新されます。また `audio_interrupted` イベントが発行されます。これは（WebSocket 接続時のみ）すべての音声再生を即座に停止する際に利用できます。 -UI に「ストップ」ボタンを用意するなど手動で割り込みたい場合は、`interrupt()` を手動で呼び出します。 +UI に「停止」ボタンなど手動で割り込みを行う機能を提供したい場合は、`interrupt()` を直接呼び出してください。 -いずれの場合も、Realtime Session はエージェントの生成を中断し、ユーザーへ話した内容を切り捨てて履歴を更新します。 +いずれの場合も、Realtime Session はエージェントの生成を中断し、ユーザーへ話した内容の知識を切り捨て、履歴を更新します。 -WebRTC でエージェントに接続している場合は、オーディオ出力もクリアされます。WebSocket を使用している場合は、キューに入っている音声再生を停止する処理を自前で行ってください。 +WebRTC でエージェントに接続している場合、音声出力もクリアされます。WebSocket を使用している場合は、再生キューにある音声の停止を自分で処理する必要があります。 ## テキスト入力 -エージェントにテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用します。 +エージェントへテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用します。 -ユーザーが音声とテキストの両方でエージェントと対話できるようにしたり、会話へ追加のコンテキストを提供したりする際に便利です。 +これは、ユーザーがエージェントと音声・テキストの両モダリティでやり取りできるようにしたり、追加のコンテキストを提供したりする場合に便利です。 ## 会話履歴管理 -`RealtimeSession` は `history` プロパティで会話履歴を自動管理します。 +`RealtimeSession` は `history` プロパティで会話履歴を自動的に管理します。 -これを利用して履歴をユーザーに表示したり、追加処理を行ったりできます。会話中に履歴は常に変化するため、`history_updated` イベントを監視してください。 +これを利用して履歴をユーザーに表示したり、追加の処理を行ったりできます。履歴は会話中に絶えず変化するため、`history_updated` イベントをリッスンすると便利です。 -履歴からメッセージを削除したり文字起こしを更新したりしたい場合は、`updateHistory` メソッドを使用します。 +履歴を変更したい場合（メッセージを完全に削除したり、文字起こしを更新したりするなど）は、`updateHistory` メソッドを使用してください。 ### 制限事項 -1. 既存の関数ツール呼び出しを後から更新・変更することはできません -2. 履歴にテキスト出力を表示するには、文字起こしとテキストモダリティが有効である必要があります -3. 割り込みにより切り詰められたレスポンスには文字起こしがありません +1. 現時点では、実行済みの関数ツール呼び出しを後から更新・変更できません +2. 履歴でテキストを表示するには、文字起こしおよびテキストモダリティを有効にする必要があります +3. 割り込みで切り捨てられた応答には文字起こしがありません ## ツールによる委任 -![Delegation through tools](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) +![ツールによる委任](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) -会話履歴とツール呼び出しを組み合わせることで、より複雑な処理を別のバックエンドエージェントに委任し、その結果を user に返すことができます。 +会話履歴とツール呼び出しを組み合わせることで、より複雑な処理を別のバックエンドエージェントに委任し、その結果をユーザーへ返すことができます。 -以下のコードはサーバー側で実行されます。この例では Next.js の server actions を利用しています。 +以下のコードはサーバー側で実行されます。この例では Next.js の server actions を使用しています。 diff --git a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx index f24a414e..1aea7bf5 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx @@ -26,25 +26,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t -0. **プロジェクトを作成する** +0. **プロジェクトの作成** - このクイックスタートでは、ブラウザで利用できる音声エージェントを作成します。新しいプロジェクトを試したい場合は、 [`Next.js`](https://nextjs.org/docs/getting-started/installation) や [`Vite`](https://vite.dev/guide/installation.html) を使用してみてください。 + このクイックスタートでは、ブラウザ上で利用できる音声エージェントを作成します。新しいプロジェクトをチェックしたい場合は、[`Next.js`](https://nextjs.org/docs/getting-started/installation) や [`Vite`](https://vite.dev/guide/installation.html) を試すこともできます。 ```bash npm create vite@latest my-project --template vanilla-ts ``` -1. **Agents SDK をインストールする** +1. **Agents SDK のインストール** ```bash npm install @openai/agents ``` - ブラウザ専用パッケージとして `@openai/agents-realtime` をインストールすることもできます。 + 代わりにブラウザ向けのスタンドアロン パッケージである `@openai/agents-realtime` をインストールすることもできます。 -2. **クライアントのエフェメラルトークンを生成する** +2. **クライアント一時トークンの生成** - このアプリケーションはユーザーのブラウザで動作するため、Realtime API を介してモデルへ安全に接続する方法が必要です。そのために、バックエンドサーバーで生成される [ephemeral client key](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) を使用します。テスト目的であれば、`curl` と通常の OpenAI API キーを使ってキーを生成することも可能です。 + このアプリケーションはユーザーのブラウザで動作するため、Realtime API を介してモデルに安全に接続する必要があります。そのために、[一時クライアントキー](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) をバックエンドサーバーで生成します。テスト目的であれば、`curl` と通常の OpenAI API キーを使ってキーを生成することも可能です。 ```bash curl -X POST https://api.openai.com/v1/realtime/sessions \ @@ -55,11 +55,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - レスポンスには後で接続に使用する `client_secret.value` が含まれます。このキーは短時間しか有効ではないため、再生成が必要になります。 + レスポンスには後で接続に使用する `client_secret.value` が含まれます。このキーは短時間のみ有効で、再生成が必要になる点に注意してください。 -3. **最初のエージェントを作成する** +3. **最初のエージェントを作成** - 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成方法は、通常の [`Agent`](/openai-agents-js/guides/agents) とほとんど同じです。 + 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`エージェント`](/openai-agents-js/guides/agents) の作成とほとんど同じです。 ```typescript import { RealtimeAgent } from '@openai/agents-realtime'; @@ -70,9 +70,9 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` -4. **セッションを作成する** +4. **セッションの作成** - 通常のエージェントと異なり、Voice Agent は `RealtimeSession` 内で継続的に動作し、会話やモデルへの接続を管理します。このセッションは音声処理、割り込み処理など、後ほど説明する多くのライフサイクル機能も担います。 + 通常のエージェントと異なり、Voice Agent は会話を継続的に処理する `RealtimeSession` 内で実行・待機します。このセッションは、時間を越えたモデルとの接続や音声処理、中断処理など、多くのライフサイクル機能を担当します。 ```typescript import { RealtimeSession } from '@openai/agents-realtime'; @@ -82,25 +82,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` のコンストラクターは最初の引数として `agent` を受け取ります。このエージェントがユーザーと最初に対話できるエージェントになります。 + `RealtimeSession` のコンストラクターは最初の引数として `agent` を取ります。このエージェントが、ユーザーが最初に対話できるエージェントになります。 -5. **セッションに接続する** +5. **セッションへの接続** - 先ほど生成したクライアントのエフェメラルトークンを渡してセッションに接続します。 + 先ほど生成したクライアント一時トークンを渡してセッションに接続します。 ```typescript await session.connect({ apiKey: '' }); ``` - これによりブラウザで WebRTC を使用して Realtime API に接続し、マイクとスピーカーが自動的に設定されます。`RealtimeSession` をバックエンドサーバー（Node.js など）で実行している場合、SDK は自動的に WebSocket を利用します。さまざまなトランスポートレイヤーについては [リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドを参照してください。 + これによりブラウザで WebRTC を使用して Realtime API に接続し、マイクとスピーカーが自動的に設定されます。`RealtimeSession` をバックエンドサーバー（Node.js など）で実行している場合、SDK は自動的に WebSocket を使用します。異なるトランスポート層については [リアルタイムトランスポート](/openai-agents-js/guides/voice-agents/transport) ガイドをご覧ください。 6. **すべてをまとめる** -7. **エンジンを起動して話しかける** +7. **エンジンを始動して話しかける** - Web サーバーを起動し、新しい Realtime Agent のコードを含むページへアクセスしてください。マイクのアクセス許可を求めるダイアログが表示されるはずです。許可すると、エージェントと会話を始められます。 + Web サーバーを起動し、新しい Realtime Agent のコードを含むページへアクセスします。マイクへのアクセス許可を求めるリクエストが表示されるはずです。許可すると、エージェントに話しかけられるようになります。 ```bash npm run dev @@ -110,17 +110,18 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t ## 次のステップ -ここからは独自の音声エージェントを設計・構築できます。音声エージェントは通常のエージェントと多くの共通機能を持ちつつ、独自の機能も備えています。 +ここからは独自の音声エージェントを設計・構築してみてください。音声エージェントは通常のエージェントと多くの共通機能を持ちますが、独自の機能も備えています。 -- 音声エージェントに次の機能を追加する方法 +- あなたの音声エージェントに以下を追加する方法を学ぶ - - [ツール](/openai-agents-js/ja/guides/voice-agents/build#tools) - - [ハンドオフ](/openai-agents-js/ja/guides/voice-agents/build#handoffs) - - [ガードレール](/openai-agents-js/ja/guides/voice-agents/build#guardrails) - - [音声割り込みへの対応](/openai-agents-js/ja/guides/voice-agents/build#audio-interruptions) - - [セッション履歴の管理](/openai-agents-js/ja/guides/voice-agents/build#session-history) + - [ツール](/openai-agents-js/guides/voice-agents/build#tools) + - [ハンドオフ](/openai-agents-js/guides/voice-agents/build#handoffs) + - [ガードレール](/openai-agents-js/guides/voice-agents/build#guardrails) + - [音声の中断処理](/openai-agents-js/guides/voice-agents/build#audio-interruptions) + - [セッション履歴の管理](/openai-agents-js/guides/voice-agents/build#session-history) -- さまざまなトランスポートレイヤーについて詳しく学ぶ - - [WebRTC](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-webrtc) - - [WebSocket](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-websocket) - - [独自のトランスポート機構を構築する](/openai-agents-js/ja/guides/voice-agents/transport#building-your-own-transport-mechanism) +- 異なるトランスポート層についてさらに学ぶ + + - [WebRTC](/openai-agents-js/guides/voice-agents/transport#connecting-over-webrtc) + - [WebSocket](/openai-agents-js/guides/voice-agents/transport#connecting-over-websocket) + - [独自のトランスポート機構の構築](/openai-agents-js/guides/voice-agents/transport#building-your-own-transport-mechanism) diff --git a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx index 5c48c1d3..964d6c13 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx @@ -25,42 +25,42 @@ import websocketSessionExample from '../../../../../../../examples/docs/voice-ag import transportEventsExample from '../../../../../../../examples/docs/voice-agents/transportEvents.ts?raw'; import thinClientExample from '../../../../../../../examples/docs/voice-agents/thinClient.ts?raw'; -## 既定のトランスポート層 +## デフォルトのトランスポートレイヤー -### WebRTC での接続 +### WebRTC 経由の接続 -既定のトランスポート層は WebRTC を使用します。マイクから音声を録音し、自動で再生します。 +デフォルトのトランスポートレイヤーは WebRTC を使用します。音声はマイクから録音され、自動で再生されます。 -独自のメディアストリームや audio 要素を使用したい場合は、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを渡してください。 +独自のメディアストリームや audio 要素を使用する場合は、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを渡してください。 -### WebSocket での接続 +### WebSocket 経由の接続 -`transport: 'websocket'` または `OpenAIRealtimeWebSocket` インスタンスをセッション作成時に指定すると、 WebRTC の代わりに WebSocket 接続を使用します。これは、たとえば Twilio で電話エージェントを構築するようなサーバーサイドのユースケースに適しています。 +WebRTC の代わりに WebSocket 接続を使用する場合は、セッション作成時に `transport: 'websocket'` もしくは `OpenAIRealtimeWebSocket` のインスタンスを渡します。これは サーバーサイドのユースケース、たとえば Twilio で電話エージェントを構築する際に有効です。 -生の PCM16 オーディオバイトを処理するために、任意の録音／再生ライブラリを使用してください。 +生の PCM16 オーディオバイトを扱うには、任意の録音／再生ライブラリを使用してください。 ### 独自のトランスポートメカニズムの構築 -別の speech-to-speech API を利用したい場合や独自のトランスポートメカニズムを持っている場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTranportEventTypes` イベントを発行することで独自実装を作成できます。 +別の speech-to-speech API を使用したい場合や独自のトランスポートメカニズムを持っている場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTranportEventTypes` イベントを発火することで独自実装が可能です。 -## Realtime API をより直接的に操作する +## Realtime API との直接的なインタラクション -OpenAI Realtime API を利用しつつ、より低レベルで API にアクセスしたい場合は、次の 2 つの方法があります: +OpenAI Realtime API を使用しつつ、より直接的に操作したい場合は次の 2 つの方法があります。 -### オプション 1 ‐ トランスポート層へアクセス +### オプション 1 ― トランスポートレイヤーへのアクセス -`RealtimeSession` の機能をすべて活用しつつトランスポート層にアクセスしたい場合は、`session.transport` からアクセスできます。 +`RealtimeSession` のすべての機能を活用したい場合は、`session.transport` からトランスポートレイヤーにアクセスできます。 -トランスポート層は受信したすべてのイベントを `*` イベントとして発行し、`sendEvent()` メソッドで生のイベントを送信できます。 +トランスポートレイヤーは受信したすべてのイベントを `*` イベントで発火し、`sendEvent()` メソッドで元イベントを送信できます。 -### オプション 2 ‐ トランスポート層のみを使用 +### オプション 2 ― トランスポートレイヤーのみを使用 -自動ツール実行やガードレールなどが不要な場合、トランスポート層を接続と割り込みだけを管理する「薄い」クライアントとして利用できます。 +自動ツール実行やガードレールが不要な場合は、接続と割り込みだけを管理する「薄い」クライアントとしてトランスポートレイヤーを使用できます。 diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index bb331275..f84959a1 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -11,35 +11,36 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; クイックスタート - 数分で最初のエージェントを構築します。 - 作ってみよう + + 数分で最初のエージェントを構築しましょう。 + + 作ってみましょう -[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) は、きわめて少ない抽象化でエージェント指向の AI アプリを簡単かつ軽量に構築できるパッケージです。これは以前のエージェント向け実験 -[Swarm](https://github.com/openai/swarm/tree/main) を本番利用向けにアップグレードしたもので、[Python 版](https://github.com/openai/openai-agents-python) も提供されています。Agents SDK にはごく少数の基本コンポーネントがあります。 +[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) は、ごく少ない抽象化で軽量かつ使いやすいパッケージとして、エージェント指向の AI アプリを構築できるようにします。これは以前のエージェント向け実験プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main)（[Python 版も提供](https://github.com/openai/openai-agents-python)）を、プロダクションレベルへアップグレードしたものです。Agents SDK にはごく小さな基本コンポーネントが用意されています。 -- ** エージェント **: instructions と tools を備えた LLM -- ** ハンドオフ **: 特定タスクを別のエージェントに委任 -- ** ガードレール **: エージェントへの入力を検証 +- **エージェント**: instructions とツールを備えた LLM +- **ハンドオフ**: 特定タスクを他のエージェントへ委任 +- **ガードレール**: エージェントへの入力を検証 -TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストを抑えつつ実運用アプリを構築できます。さらに SDK には ** トレーシング ** が組み込まれており、エージェントフローの可視化とデバッグ、評価、さらにはモデルのファインチューニングまで行えます。 +これらのプリミティブは、 TypeScript と組み合わせることでツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実運用レベルのアプリを構築できます。さらに SDK には組み込み **トレーシング** があり、エージェントフローの可視化やデバッグ、評価、さらにはモデルのファインチューニングまで行えます。 ## Agents SDK を使用する理由 -SDK の設計原則は次の 2 つです。 +SDK には次の 2 つの設計原則があります。 -1. 使う価値のある十分な機能を備えつつ、学習が容易な最小限の基本コンポーネント -2. デフォルトで優れた動作を提供しつつ、細部を自由にカスタマイズ可能 +1. 十分に使う価値がある機能を備えつつ、学習が容易な最小限のプリミティブ +2. デフォルトで高い使いやすさを提供しつつ、処理内容を細かくカスタマイズ可能 主な機能は以下のとおりです。 -- ** エージェントループ **: tool を呼び出し、その結果を LLM に送り、LLM が完了するまでループ処理 -- ** TypeScript ファースト **: 新しい抽象化を覚えることなく、言語機能でエージェントを編成・連鎖 -- ** ハンドオフ **: 複数エージェント間の調整と委任を実現する強力な機能 -- ** ガードレール **: 入力検証やチェックをエージェントと並行して実行し、不合格なら早期終了 -- ** 関数ツール **: 任意の TypeScript 関数を自動スキーマ生成と Zod 検証付きで tool 化 -- ** トレーシング **: ワークフローを可視化・デバッグ・監視し、OpenAI の評価、ファインチューニング、蒸留ツールを活用 -- ** Realtime Agents **: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた高機能音声エージェントを構築 +- **エージェントループ**: ツール呼び出し、結果の LLM への送信、LLM が完了するまでのループ処理を自動で実行 +- **TypeScript ファースト**: 新しい抽象化を学ばずに、言語機能だけでエージェントのオーケストレーションやチェーン化が可能 +- **ハンドオフ**: 複数エージェント間の協調・委任を行う強力な機能 +- **ガードレール**: 入力検証をエージェントと並行して実行し、失敗時は早期終了 +- **関数ツール**: 任意の TypeScript 関数を自動スキーマ生成と Zod ベースの検証付きツールに変換 +- **トレーシング**: ワークフローの可視化・デバッグ・モニタリングに加え、OpenAI の評価・ファインチューニング・蒸留ツールを利用可能 +- **Realtime Agents**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた高機能な音声エージェントを構築 ## インストール @@ -47,11 +48,11 @@ SDK の設計原則は次の 2 つです。 npm install @openai/agents ``` -## Hello World コード例 +## Hello World の例 -(_実行する場合は、環境変数 `OPENAI_API_KEY` を設定してください_) +(_実行する場合は `OPENAI_API_KEY` 環境変数を設定してください_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/src/scripts/translate.ts b/docs/src/scripts/translate.ts index 9d13d1cc..261ce60d 100644 --- a/docs/src/scripts/translate.ts +++ b/docs/src/scripts/translate.ts @@ -362,12 +362,13 @@ 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 ${targetLanguage}, 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. Perform a self-review to detect any errors or rooms for improvements in terms of Markdown text format. A common error is to have spaces within special syntax like * or _. You must have spaces after special syntax like * or _, but it's not the same for the parts within special syntax. -5. Perform a self-review to detect any parts that are not compatible with *.mdx files. In the past, you've generated {#dynamic-instructions} but it was neither necessary nor valid. -6. If improvements are necessary, refine the content without changing the original meaning. -7. Continue improving the translation until you are fully satisfied with the result. -8. Once the final output is ready, return **only** the translated markdown text. No extra commentary. +3. Perform a self-review to evaluate the following points: + - the quality of the translation, focusing on naturalness, accuracy, and consistency in detail + - any errors or rooms for improvements in terms of Markdown text format -- A common error is to have spaces within special syntax like * or _. You must have spaces after special syntax like * or _, but it's NOT the same for the parts inside special syntax (e.g., ** bold ** must be **bold**) + - any parts that are not compatible with *.mdx files -- In the past, you've generated an expression with acorn like {#title-here} in h2 (##) level but it was neither necessary nor valid +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. `; }