diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index e8f00cbc..ecb3e4e8 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -7,12 +7,12 @@ 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 の AI SDK](https://sdk.vercel.ai/) がサポートする幅広いモデルをこのアダプター経由で Agents SDK に取り込めます。 +標準では、Agents SDK は Responses API または Chat Completions API を通じて OpenAI モデルと動作します。別のモデルを使用したい場合は、[Vercel の AI SDK](https://sdk.vercel.ai/) が幅広い対応モデルを提供しており、このアダプターを通じて Agents SDK に組み込むことができます。 ## セットアップ @@ -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,18 +47,19 @@ Agents SDK は標準で Responses API または Chat Completions API を通じ ## 例 - + -## プロバイダー メタデータの受け渡し +## プロバイダーメタデータの受け渡し -メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` を通して渡します。値はそのまま基盤の AI SDK モデルへ転送されます。例えば、Agents SDK で次の `providerData` +メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` を使用して渡してください。値は基盤の AI SDK モデルにそのまま転送されます。例えば、Agents SDK で次の `providerData` ```ts providerData: { @@ -70,7 +71,7 @@ providerData: { } ``` -は、AI SDK 連携を使用する場合は次のようになります +は、AI SDK 連携を使用すると次のようになります ```ts providerMetadata: { @@ -81,3 +82,5 @@ providerMetadata: { } } ``` + +となります。 diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index 8ba83eb5..b7d4cc5b 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,15 +7,14 @@ 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 は、電話の通話からの元音声を WebSocket サーバーへ送信する [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しています。このセットアップを使って、[音声エージェントの概要](/openai-agents-js/ja/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 トランスポートを使い、Twilio から来るイベントをあなたの Realtime Session に接続できます。ただし、その場合は適切な音声フォーマットの設定と、通話が Web ベースの会話より自然とレイテンシが大きくなるため、独自の割り込みタイミングの調整が必要になります。 -セットアップ体験を改善するために、Twilio への接続、割り込み処理、音声転送などを代わりに処理する専用のトランスポートレイヤーを作成しました。 +セットアップ体験を向上させるために、Twilio への接続、割り込み処理、音声の転送まで行う専用のトランスポートレイヤーを用意しました。 ## セットアップ @@ -24,11 +23,11 @@ Twilio は、電話の通話からの元音声を WebSocket サーバーへ送 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` + ローカル開発の場合は、this will require you to configure a local tunnel like + this will require you to configure a local tunnel like [`ngrok`](https://ngrok.io/) や + [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) を設定して、ローカルサーバーを Twilio からアクセス可能にする必要があります。`TwilioRealtimeTransportLayer` を使って Twilio に接続できます。 3. **extensions パッケージをインストールして Twilio アダプターを導入します:** @@ -37,7 +36,7 @@ Twilio は、電話の通話からの元音声を WebSocket サーバーへ送 npm install @openai/agents-extensions ``` -4. **アダプターとモデルをインポートして `RealtimeSession` に接続します:** +4. **`RealtimeSession` に接続するためにアダプターとモデルをインポートします:** -`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` プロパティを持ちます。 + Twilio が送信する元イベントにアクセスしたい場合は、`RealtimeSession` インスタンスの + `transport_event` を監視してください。Twilio からのすべてのイベントは `twilio_message` という type を持ち、元のイベントデータを含む `message` プロパティがあります。 3. **デバッグログを確認します。** - 状況を詳しく知りたい問題に遭遇することがあります。環境変数 `DEBUG=openai-agents*` を使うと Agents SDK の - すべてのデバッグログが表示されます。あるいは、`DEBUG=openai-agents:extensions:twilio*` - を使って Twilio アダプターのデバッグログだけを有効化できます。 + 状況の詳細を知りたい問題に遭遇することがあります。`DEBUG=openai-agents*` 環境変数を使うと Agents SDK のすべてのデバッグログが表示されます。 + あるいは、Twilio アダプターのデバッグログだけを有効にするには + `DEBUG=openai-agents:extensions:twilio*` を使用します。 ## 完全なサーバー例 -以下は、Twilio からのリクエストを受け取り、`RealtimeSession` に転送する WebSocket サーバーのエンドツーエンドの例です。 +以下は、Twilio からのリクエストを受け取り、それを `RealtimeSession` に転送する WebSocket サーバーのエンドツーエンドの例です。 diff --git a/docs/src/content/docs/ja/guides/agents.mdx b/docs/src/content/docs/ja/guides/agents.mdx index d791d2c4..d73ae1a3 100644 --- a/docs/src/content/docs/ja/guides/agents.mdx +++ b/docs/src/content/docs/ja/guides/agents.mdx @@ -15,29 +15,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 の主な基本コンポーネントです。**エージェント** は、次のように構成された 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 機能を詳しく説明します。 --- ## 基本設定 -`Agent` コンストラクタは 1 つの設定オブジェクトを受け取ります。よく使われるプロパティは次のとおりです。 +`Agent` コンストラクターは単一の設定オブジェクトを受け取ります。よく使われるプロパティは次のとおりです。 -| Property | Required | Description | -| --------------- | -------- | --------------------------------------------------------------------------------------------------- | -| `name` | yes | 短い人間可読の識別子 | -| `instructions` | yes | システムプロンプト（文字列 **または** 関数 – [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/) インスタンスの配列 | +| 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/) インスタンスの配列 | @@ -45,7 +45,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## コンテキスト -エージェントは **コンテキスト型に対してジェネリック** です（例: `Agent`）。コンテキストはあなたが作成し `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザーメタデータ、機能フラグなど）を提供するのに便利です。 +エージェントはそのコンテキスト型に対して**ジェネリック**です（例: `Agent`）。コンテキストは、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザーメタデータ、フィーチャーフラグ、…）の提供に役立ちます。 @@ -56,7 +56,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor デフォルトでは、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は次を受け付けます。 1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`） -2. JSON スキーマ互換の任意のオブジェクト +2. JSON‑schema 互換の任意のオブジェクト -`outputType` が指定されると、SDK はプレーンテキストではなく自動的に +`outputType` が指定されている場合、SDK はプレーンテキストではなく自動的に [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。 --- @@ -73,20 +73,20 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor エージェントを組み合わせる方法は多数あります。プロダクションアプリでよく見られるパターンは次の 2 つです。 -1. **マネージャー（エージェントをツールとして）** – 中央のエージェントが会話を保持し、ツールとして公開された専門エージェントを呼び出します -2. **ハンドオフ** – 最初のエージェントがユーザーの要求を特定したら、会話全体を専門家に委譲します +1. **マネージャー（エージェントをツールとして）** – 中央のエージェントが会話を所有し、ツールとして公開された特化エージェントを呼び出します +2. **ハンドオフ** – 最初のエージェントがユーザーのリクエストを特定した後、会話全体をスペシャリストに委譲します -これらのアプローチは補完的です。マネージャーはガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を持たずに単一タスクに集中できるようにします。 +これらのアプローチは補完的です。マネージャーはガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を保持せずに単一のタスクに集中できるようにします。 ### マネージャー（エージェントをツールとして） -このパターンでは、マネージャーは制御を渡しません。LLM がツールを使用し、マネージャーが最終回答を要約します。詳しくは [ツール](/openai-agents-js/ja/guides/tools#agents-as-tools) を参照してください。 +このパターンでは、マネージャーは決して制御を手放しません—LLM はツールを使用し、マネージャーが最終回答を要約します。詳しくは [ツール](/openai-agents-js/ja/guides/tools#agents-as-tools) を参照してください。 ### ハンドオフ -ハンドオフでは、トリアージエージェントが要求を振り分けますが、いったんハンドオフが発生すると、専門エージェントが最終出力を生成するまで会話を所有します。これによりプロンプトが短くなり、各エージェントを個別に把握しやすくなります。詳しくは [ハンドオフ](/openai-agents-js/ja/guides/handoffs) を参照してください。 +ハンドオフでは、トリアージエージェントがリクエストをルーティングしますが、ハンドオフが発生するとスペシャリストエージェントが最終出力を生成するまで会話を所有します。これによりプロンプトを短く保て、各エージェントを個別に考察できます。詳しくは [ハンドオフ](/openai-agents-js/ja/guides/handoffs) を参照してください。 @@ -94,7 +94,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## 動的 instructions -`instructions` は文字列ではなく **関数** にすることもできます。関数は現在の `RunContext` とエージェントインスタンスを受け取り、文字列 _または_ `Promise` を返せます。 +`instructions` は文字列ではなく**関数**にすることもできます。関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返せます。 @@ -134,23 +134,23 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## ツール使用の強制 -ツールを与えても、LLM が必ず呼び出すとは限りません。`modelSettings.tool_choice` でツール使用を **強制** できます。 +ツールを提供しても、LLM が必ず呼び出すとは限りません。`modelSettings.tool_choice` でツール使用を**強制**できます。 -1. `'auto'`（デフォルト）– ツールを使うかどうかを LLM が判断 -2. `'required'` – LLM はツールを必ず呼び出す（どれを使うかは任意） -3. `'none'` – LLM はツールを呼び出しては **いけない** +1. `'auto'`（デフォルト） – ツールを使うかどうかを LLM が決定 +2. `'required'` – LLM はツールを呼び出す _必要がある_（どれを使うかは選べる） +3. `'none'` – LLM はツールを呼び出しては **ならない** 4. 特定のツール名（例: `'calculator'`）– そのツールを必ず呼び出す ### 無限ループの防止 -ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツールの呼び出しを繰り返す無限ループに入るのを防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 +ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツールを繰り返し呼び出そうとして無限ループに陥るのを防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 - `'run_llm_again'`（デフォルト）– ツール結果を使って LLM を再実行 - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う -- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼び出されたら停止 -- `(context, toolResults) => ...` – 実行を終了すべきかどうかを返すカスタム関数 +- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼ばれたら停止 +- `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数 ```typescript const agent = new Agent({ @@ -164,5 +164,5 @@ 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/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 3b2215bc..4796e2a3 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,7 +13,7 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## API キーとクライアント -既定で SDK は最初のインポート時に環境変数 `OPENAI_API_KEY` を読み込みます。変数を設定できない場合は `setDefaultOpenAIKey()` を手動で呼び出せます。 +デフォルトでは、SDK は初回のインポート時に `OPENAI_API_KEY` 環境変数を読み込みます。変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出せます。 -独自の `OpenAI` クライアント インスタンスを渡すこともできます。そうでない場合は、既定のキーを使って自動的に作成されます。 +独自の `OpenAI` クライアントインスタンスを渡すこともできます。指定しない場合、SDK は既定のキーを使って自動的に作成します。 -最後に Responses API と Chat Completions API を切り替えられます。 +最後に、Responses API と Chat Completions API を切り替えられます。 @@ -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 136ca512..3d8d6539 100644 --- a/docs/src/content/docs/ja/guides/context.mdx +++ b/docs/src/content/docs/ja/guides/context.mdx @@ -6,14 +6,14 @@ 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 コンテキスト** ## ローカルコンテキスト -ローカルコンテキストは `RunContext` 型で表現します。状態や依存関係を保持する任意のオブジェクトを作成し、それを `Runner.run()` に渡します。すべてのツール呼び出しとフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み書きできます。 +ローカルコンテキストは `RunContext` 型で表現されます。状態や依存関係を保持する任意のオブジェクトを作成して `Runner.run()` に渡します。すべてのツール呼び出しとフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み書きできます。 -1 回の実行に参加するすべてのエージェント、ツール、フックは同じ**型**のコンテキストを使用する必要があります。 +単一の実行に参加するすべてのエージェント、ツール、フックは、同じ種類のコンテキスト（同じ **type**）を使用する必要があります。 -ローカルコンテキストの使用例: +ローカルコンテキストの用途例: - 実行に関するデータ（ユーザー名、ID など） - ロガーやデータフェッチャーなどの依存関係 @@ -31,14 +31,14 @@ import localContextExample from '../../../../../../examples/docs/context/localCo ## エージェント/LLM コンテキスト -LLM が呼び出されると、参照できるデータは会話履歴に含まれるものだけです。追加情報を利用可能にするには、次のような方法があります: +LLM が呼び出されるとき、参照できるのは会話履歴からのデータのみです。追加情報を利用可能にするには、次の方法があります。 -1. エージェントの `instructions`（システムまたは開発者メッセージ）に追加する。これは静的な文字列でも、コンテキストを受け取って文字列を返す関数でも可 -2. `Runner.run()` を呼び出すときに `input` に含める。これは instructions の手法に近いですが、メッセージを [chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます +1. エージェントの `instructions` に追加する — system または 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. 関数ツール経由で公開し、LLM がオンデマンドでデータを取得できるようにする -4. リトリーバルや Web 検索ツールを使い、ファイル、データベース、または Web の関連データに基づいて応答をグラウンディングする +4. リトリーバルや Web 検索ツールを使って、ファイル、データベース、Web などの関連データに基づいて応答を根拠づける diff --git a/docs/src/content/docs/ja/guides/guardrails.mdx b/docs/src/content/docs/ja/guides/guardrails.mdx index 9d79d768..0bf312c2 100644 --- a/docs/src/content/docs/ja/guides/guardrails.mdx +++ b/docs/src/content/docs/ja/guides/guardrails.mdx @@ -7,55 +7,55 @@ 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 種類あります: -1. **入力ガードレール** は最初のユーザー入力に対して実行されます -2. **出力ガードレール** は最終的なエージェント出力に対して実行されます +1. **Input guardrails** は最初のユーザー入力に対して実行されます +2. **Output guardrails** は最終的なエージェントの出力に対して実行されます -## 入力ガードレール +## Input guardrails -入力ガードレールは次の 3 段階で実行されます: +Input guardrails は 3 つのステップで動作します: -1. ガードレールはエージェントに渡されたのと同じ入力を受け取ります -2. ガードレール関数が実行され、[`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します +1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります +2. ガードレール関数が実行され、[`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) 内にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します 3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます > **Note** -> 入力ガードレールはユーザー入力を対象としているため、ワークフローの _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。これはエージェントごとに必要なガードレールが異なることが多いためです。 +> Input guardrails はユーザー入力を対象としているため、エージェントがワークフロー内の _最初_ のエージェントである場合にのみ実行されます。多くの場合エージェントごとに必要なガードレールが異なるため、ガードレールはエージェント自体に設定します。 -## 出力ガードレール +## Output guardrails -出力ガードレールも同様のパターンに従います: +Output guardrails も同じパターンに従います: -1. ガードレールはエージェントに渡されたのと同じ入力を受け取ります -2. ガードレール関数が実行され、[`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します +1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります +2. ガードレール関数が実行され、[`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) 内にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します 3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます > **Note** -> 出力ガードレールは、エージェントがワークフローの _最後_ のエージェントである場合にのみ実行されます。リアルタイム音声での対話については [音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails) を参照してください。 +> Output guardrails は、エージェントがワークフロー内の _最後_ のエージェントである場合にのみ実行されます。リアルタイムの音声対話については[音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails)を参照してください。 -## トリップワイヤ +## Tripwires -ガードレールが失敗すると、トリップワイヤによってそれが通知されます。トリップワイヤが発火するとすぐに、ランナーは対応するエラーをスローして実行を停止します。 +ガードレールが失敗すると、トリップワイヤーでそれを通知します。トリップワイヤーが発火した時点で、Runner は対応するエラーをスローし、実行を停止します。 ## ガードレールの実装 -ガードレールは `GuardrailFunctionOutput` を返す単なる関数です。以下は、別のエージェントを内部で実行して、ユーザーが数学の宿題の手伝いを求めているかどうかをチェックする最小の例です。 +ガードレールは `GuardrailFunctionOutput` を返す単純な関数です。以下は、内部で別のエージェントを実行して、ユーザーが数学の宿題の手伝いを求めているかどうかをチェックする最小の例です。 -出力ガードレールも同じように動作します。 +Output guardrails も同様に機能します。 1. `guardrailAgent` はガードレール関数内で使用されます diff --git a/docs/src/content/docs/ja/guides/handoffs.mdx b/docs/src/content/docs/ja/guides/handoffs.mdx index 4bce298a..bab8a409 100644 --- a/docs/src/content/docs/ja/guides/handoffs.mdx +++ b/docs/src/content/docs/ja/guides/handoffs.mdx @@ -10,17 +10,17 @@ 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()` によるハンドオフのカスタマイズ @@ -29,35 +29,35 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r - `agent` – ハンドオフ先のエージェント - `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き - `toolDescriptionOverride` – 既定のツール説明を上書き -- `onHandoff` – ハンドオフ発生時のコールバック。`RunContext` と、必要に応じてパース済みの入力を受け取ります -- `inputType` – ハンドオフに対して期待する入力スキーマ -- `inputFilter` – 次のエージェントへ渡す履歴をフィルタリングします +- `onHandoff` – ハンドオフ発生時のコールバック。`RunContext` と、必要に応じてパース済み入力を受け取ります +- `inputType` – ハンドオフに期待する入力スキーマ +- `inputFilter` – 次のエージェントへ渡す履歴のフィルター -## ハンドオフの入力 +## ハンドオフ入力 -ハンドオフを呼び出す際に LLM からデータを提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 +ハンドオフの呼び出し時に LLM にデータを提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 - + ## 入力フィルター -デフォルトでは、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。 +既定では、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。 一般的なヘルパーは `@openai/agents-core/extensions` にあります。 - + ## 推奨プロンプト -プロンプトでハンドオフに触れていると、LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` を通じて推奨の接頭辞を提供します。 +プロンプト内でハンドオフに言及すると、LLM の応答がより安定します。SDK は `RECOMMENDED_PROMPT_PREFIX` 経由で推奨プレフィックスを提供します。 diff --git a/docs/src/content/docs/ja/guides/human-in-the-loop.mdx b/docs/src/content/docs/ja/guides/human-in-the-loop.mdx index 90963da2..0030075d 100644 --- a/docs/src/content/docs/ja/guides/human-in-the-loop.mdx +++ b/docs/src/content/docs/ja/guides/human-in-the-loop.mdx @@ -7,36 +7,36 @@ import { Aside, Code } from '@astrojs/starlight/components'; import humanInTheLoopExample from '../../../../../../examples/docs/human-in-the-loop/index.ts?raw'; import toolApprovalDefinition from '../../../../../../examples/docs/human-in-the-loop/toolApprovalDefinition.ts?raw'; -このガイドでは、SDK に組み込まれた Human in the loop (人間の介入) サポートを使用して、人的介入に基づきエージェントの実行を一時停止および再開する方法を説明します。 +このガイドでは、SDK に組み込まれた Human in the loop (人間の介入) のサポートを使って、人的介入に基づいてエージェントの実行を一時停止・再開する方法を説明します。 -現在の主なユースケースは、センシティブなツール実行に対する承認を求めることです。 +現在の主なユースケースは、機微なツール実行に対する承認の要求です。 ## 承認リクエスト -`needsApproval` オプションを `true`、または真偽値を返す非同期関数に設定することで、承認が必要なツールを定義できます。 +`needsApproval` オプションを `true`、またはブール値を返す非同期関数に設定することで、承認が必要なツールを定義できます。 ### フロー -1. エージェントがツール（複数の場合あり）を呼び出すと判断した場合、`needsApproval` を評価して、そのツールに承認が必要かを確認します +1. エージェントがツール（または複数）を呼び出すと判断した場合、`needsApproval` を評価してこのツールに承認が必要か確認します 2. 承認が必要な場合、エージェントは承認がすでに許可または拒否されているかを確認します - - 承認が許可または拒否されていない場合、ツールはツール呼び出しを実行できないことを示す静的メッセージをエージェントに返します - - 承認 / 拒否が欠けている場合、ツールの承認リクエストがトリガーされます + - 承認が許可も拒否もされていない場合、ツールは「ツールコールを実行できない」ことを示す固定メッセージをエージェントに返します + - 承認 / 拒否が未設定の場合、ツール承認リクエストがトリガーされます 3. エージェントはすべてのツール承認リクエストを収集し、実行を中断します -4. 中断がある場合、[エージェントの実行結果](/openai-agents-js/ja/guides/results) には、保留中のステップを説明する `interruptions` 配列が含まれます。ツール呼び出しに確認が必要な場合、`type: "tool_approval_item"` の `ToolApprovalItem` が表示されます -5. ツール呼び出しを承認または拒否するには、`result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出します -6. すべての中断を処理した後、`result.state` を `runner.run(agent, state)` に渡して実行を再開できます。ここで `agent` は全体の実行をトリガーした元のエージェントです +4. 中断がある場合、[エージェントの実行結果](/openai-agents-js/ja/guides/results) には、保留中のステップを説明する `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 から再開されます ## 例 -以下は、ターミナルで承認を促し、状態を一時的にファイルに保存する Human in the loop (人間の介入) フローの、より完全な例です。 +以下は、ターミナルで承認を促し、状態を一時的にファイルへ保存する Human in the loop (人間の介入) フローの、より完全な例です。 - これは主に、エージェントに変更を加えながら、シリアライズした状態を長期間保存しようとしている場合に該当します。 + これは主に、エージェントに変更を加えつつ、シリアライズした状態を長期間保存しようとしている場合に該当します。 -承認リクエストに時間がかかり、エージェント定義を意味のある形でバージョン管理したい場合や Agents SDK のバージョンを上げたい場合は、パッケージエイリアスを使用して 2 つのバージョンの Agents SDK を並行してインストールし、独自の分岐ロジックを実装することを現時点では推奨します。 +承認リクエストに時間がかかり、エージェント定義に意味のある形でバージョン管理を行いたい場合や Agents SDK のバージョンを上げたい場合は、パッケージエイリアスを使って 2 つの Agents SDK を並行インストールし、独自のブランチ分岐ロジックを実装することを現時点ではおすすめします。 -実務上は、自身のコードにバージョン番号を付与してシリアライズした状態とともに保存し、デシリアライズを適切なバージョンのコードへ誘導することを意味します。 +実際には、独自のコードにバージョン番号を割り当て、それをシリアライズした状態と一緒に保存し、デシリアライズをコードの正しいバージョンへ誘導することを意味します。 diff --git a/docs/src/content/docs/ja/guides/mcp.mdx b/docs/src/content/docs/ja/guides/mcp.mdx index 91652c49..5d6fe3b1 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -13,35 +13,35 @@ import streamableHttpExample from '../../../../../../examples/docs/mcp/streamabl import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; -The [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP ドキュメントより: -> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。USB‑C がさまざまな周辺機器やアクセサリにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 この SDK がサポートする MCP サーバーには 3 種類あります: -1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) がツールとして使用するリモート MCP サーバー -2. **Streamable HTTP MCP servers** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートのサーバー -3. **Stdio MCP servers** – 標準入出力経由でアクセスするサーバー（最も簡単な選択肢） +1. **リモート MCP サーバーツール** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) によってツールとして利用されるリモート MCP サーバー +2. **Streamable HTTP MCP サーバー** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートのサーバー +3. **Stdio MCP サーバー** – 標準入出力経由でアクセスするサーバー（最もシンプルな選択肢） -ユースケースに応じてサーバータイプを選択してください: +ユースケースに応じてサーバータイプを選んでください: -| 必要なこと | 推奨オプション | -| ------------------------------------------------------------------------------------ | ----------------------- | -| 公開アクセス可能なリモートサーバーを既定の OpenAI Responses モデルで呼び出す | **1. Hosted MCP tools** | -| 公開アクセス可能なリモートサーバーを使いつつ、ツール呼び出しをローカルでトリガーする | **2. Streamable HTTP** | -| ローカルで動作する Streamable HTTP サーバーを使う | **2. Streamable HTTP** | -| OpenAI Responses 以外のモデルで任意の Streamable HTTP サーバーを使う | **2. Streamable HTTP** | -| 標準入出力プロトコルのみをサポートするローカル MCP サーバーを扱う | **3. Stdio** | +| 必要なこと | 推奨オプション | +| -------------------------------------------------------------------------- | -------------------------- | +| 公開アクセス可能なリモートサーバーを既定の OpenAI Responses モデルで呼ぶ | **1. リモート MCP ツール** | +| 公開アクセス可能なリモートサーバーを使うが、ツール呼び出しはローカルで発火 | **2. Streamable HTTP** | +| ローカルで動作する Streamable HTTP サーバーを使用 | **2. Streamable HTTP** | +| OpenAI Responses 以外のモデルで任意の Streamable HTTP サーバーを使用 | **2. Streamable HTTP** | +| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーを利用 | **3. Stdio** | -## 1. Hosted MCP server tools +## 1. リモート MCP サーバーツール -組み込みツール（Hosted）は、往復の処理全体をモデル側で実行します。コードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルへストリーミングします。 +組み込みツール（Hosted）はやり取り全体をモデル側に押し込みます。コードが MCP サーバーを呼ぶ代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルにストリーミングします。 -以下は Hosted MCP ツールを使う最も簡単な例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡します。これは Hosted MCP サーバーツールを作成するのに便利です。 +リモート MCP サーバーツールを使う最も簡単な例です。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡すだけで、リモート MCP サーバーツールを作成できます。 -次に、`run` 関数（または独自にカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行できます: +次に、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行できます: -増分的な MCP の結果をストリーミングするには、`Agent` を実行する際に `stream: true` を渡します: +増分的な MCP 結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します: -### コネクター対応の Hosted サーバー +### コネクタ対応のリモートサーバー -Hosted MCP は OpenAI コネクターにも対応しています。`serverUrl` を提供する代わりに、コネクターの `connectorId` と `authorization` トークンを渡します。Responses API が認証を処理し、Hosted MCP インターフェースを通じてコネクターのツールを公開します。 +リモート MCP は OpenAI コネクタにも対応しています。`serverUrl` を渡す代わりに、コネクタの `connectorId` と `authorization` トークンを渡します。Responses API が認証を処理し、リモート MCP インターフェースを通じてコネクタのツールを公開します。 -この例では、環境変数 `GOOGLE_CALENDAR_AUTHORIZATION` に Google OAuth Playground で取得した OAuth トークンを保持し、コネクター対応サーバーが Calendar API を呼び出せるように承認します。ストリーミングもあわせて実演する実行可能なサンプルは [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors) を参照してください。 +この例では、環境変数 `GOOGLE_CALENDAR_AUTHORIZATION` に Google OAuth Playground で取得した OAuth トークンを保持し、コネクタ対応サーバーが Calendar API を呼び出せるように許可します。ストリーミングも併せて実演する実行可能なサンプルは [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors) を参照してください。 -完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + Streaming、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全に動作するサンプル（リモートツール/Streamable HTTP/stdio + ストリーミング、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 -## 2. Streamable HTTP MCP servers +## 2. Streamable HTTP MCP サーバー -エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーと直接対話する場合は、サーバーの `url`、`name`、および任意の設定とともに `MCPServerStreamableHttp` をインスタンス化します: +エージェントがローカル／リモートの Streamable HTTP MCP サーバーと直接対話する場合は、サーバーの `url`、`name`、および任意の設定を指定して `MCPServerStreamableHttp` をインスタンス化します: -コンストラクターは、`authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの MCP TypeScript SDK の追加オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 +コンストラクタは、`authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの MCP TypeScript SDK の追加オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 -## 3. Stdio MCP servers +## 3. Stdio MCP サーバー -標準入出力のみを公開するサーバーの場合は、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します: +標準 I/O のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します: diff --git a/docs/src/content/docs/ja/guides/models.mdx b/docs/src/content/docs/ja/guides/models.mdx index ec80a8a5..c98ba68b 100644 --- a/docs/src/content/docs/ja/guides/models.mdx +++ b/docs/src/content/docs/ja/guides/models.mdx @@ -12,43 +12,43 @@ 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) – 人間が読めるモデルの**names**（例: `'gpt‑4o'`）を `Model` インスタンスに解決します +- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して _1 回_ のリクエストを実行する方法を知っています +- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読めるモデルの**名前**（例: `'gpt‑4o'`）を `Model` インスタンスに解決します -日常的な作業では、通常はモデルの**names** と、時折 `ModelSettings` のみを扱います。 +日常的には、通常はモデルの**名前**と、必要に応じて `ModelSettings` のみを扱います。 -## デフォルトモデル +## 既定モデル -`Agent` を初期化するときにモデルを指定しない場合、デフォルトモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェントワークフローの予測可能性と低レイテンシのバランスに優れています。 +`Agent` を初期化する際にモデルを指定しない場合は、既定のモデルが使用されます。現在の既定は [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェントワークフローにおける予測可能性と低レイテンシのバランスに優れています。 -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) などの他モデルに切り替えたい場合、エージェントを構成する方法は 2 つあります。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) のような他のモデルに切り替えたい場合は、エージェントを構成する方法が 2 つあります。 -まず、カスタムモデルを設定していないすべての エージェント で特定のモデルを一貫して使用したい場合は、エージェントを実行する前に環境変数 `OPENAI_DEFAULT_MODEL` を設定します。 +まず、カスタムモデルを設定していないすべてのエージェントで一貫して特定のモデルを使いたい場合は、エージェントを実行する前に環境変数 `OPENAI_DEFAULT_MODEL` を設定します。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 node my-awesome-agent.js ``` -次に、`Runner` インスタンスにデフォルトモデルを設定できます。エージェントでモデルを設定しない場合、この `Runner` のデフォルトモデルが使用されます。 +次に、`Runner` インスタンスに既定のモデルを設定できます。エージェント側でモデルを設定しない場合、この `Runner` の既定モデルが使用されます。 -### GPT-5 モデル +### GPT‑5 モデル -この方法で GPT-5 の推論モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用する場合、SDK は既定で妥当な `modelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` の両方を `"low"` に設定します。デフォルトモデルの推論負荷を調整するには、独自の `modelSettings` を渡します: +この方法で GPT‑5 の reasoning モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用する場合、SDK は妥当な `modelSettings` を既定で適用します。具体的には、`reasoning.effort` と `verbosity` をともに `"low"` に設定します。既定モデルの reasoning effort を調整するには、独自の `modelSettings` を渡します: ```ts import { Agent } from '@openai/agents'; @@ -57,31 +57,32 @@ const myAgent = new Agent({ name: 'My Agent', instructions: "You're a helpful agent.", modelSettings: { - reasoning: { effort: 'minimal' }, - text: { verbosity: 'low' }, - }, + providerData: { + reasoning: { effort: 'minimal' }, + text: { verbosity: 'low' }, + }, // If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only modelSettings works. // It's also fine to pass a GPT-5 model name explicitly: // model: 'gpt-5', }); ``` -より低いレイテンシのために、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) を `reasoning.effort="minimal"` で使用すると、既定設定より高速に応答が返ることが多いです。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の推論負荷をサポートしていないため、この Agents SDK の既定値は `"low"` です。 +より低レイテンシを求める場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) において `reasoning.effort="minimal"` を使うと、既定設定よりも速く応答が返ることがよくあります。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の reasoning effort をサポートしていないため、この Agents SDK では既定を `"low"` にしています。 -### 非 GPT-5 モデル +### 非 GPT‑5 モデル -カスタムの `modelSettings` なしで非 GPT-5 のモデル名を渡すと、SDK はあらゆるモデルと互換性のある汎用の `modelSettings` にフォールバックします。 +カスタムの `modelSettings` なしで非 GPT‑5 のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用的な `modelSettings` にフォールバックします。 --- ## OpenAI プロバイダー -デフォルトの `ModelProvider` は OpenAI APIs を使って名前を解決します。2 つの異なるエンドポイントをサポートします: +既定の `ModelProvider` は OpenAI の API を使って名前を解決します。2 つの異なるエンドポイントをサポートします: -| API | 用途 | `setOpenAIAPI()` の呼び出し | -| ---------------- | -------------------------------------------------------------------------- | --------------------------------------- | -| Chat Completions | 標準的なチャットと関数呼び出し | `setOpenAIAPI('chat_completions')` | -| Responses | ツール呼び出しや柔軟な出力を備えた新しい ストリーミング ファースト生成 API | `setOpenAIAPI('responses')` _(default)_ | +| API | 使用方法 | `setOpenAIAPI()` の呼び出し | +| ---------------- | ------------------------------------------------------------------------ | --------------------------------------- | +| Chat Completions | 標準的なチャットと関数呼び出し | `setOpenAIAPI('chat_completions')` | +| Responses | 新しい ストリーミング ファーストの生成 API（ツール呼び出し、柔軟な出力） | `setOpenAIAPI('responses')` _(default)_ | ### 認証 @@ -91,60 +92,60 @@ const myAgent = new Agent({ title="既定の OpenAI キーを設定" /> -ネットワーク設定をカスタマイズする必要がある場合は、`setDefaultOpenAIClient(client)` を介して独自の `OpenAI` クライアントを接続することもできます。 +カスタムのネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 --- -## モデル設定 (ModelSettings) +## ModelSettings -`ModelSettings` は OpenAI の パラメーター を反映しつつ、プロバイダー非依存です。 +`ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダーに依存しません。 -| フィールド | 型 | 注記 | +| 項目 | 型 | 注記 | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ | -| `temperature` | `number` | 創造性と決定性のバランス | +| `temperature` | `number` | 創造性と決定性のトレードオフ | | `topP` | `number` | Nucleus sampling | -| `frequencyPenalty` | `number` | 繰り返しトークンへのペナルティ | -| `presencePenalty` | `number` | 新しいトークンの促進 | +| `frequencyPenalty` | `number` | 繰り返し出現するトークンを抑制 | +| `presencePenalty` | `number` | 新しいトークンの出現を促進 | | `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 | -| `parallelToolCalls` | `boolean` | サポートされる場合に並列の関数呼び出しを許可 | +| `parallelToolCalls` | `boolean` | サポートされる場合に関数呼び出しの並列実行を許可 | | `truncation` | `'auto' \| 'disabled'` | トークンの切り捨て戦略 | -| `maxTokens` | `number` | 応答内の最大トークン数 | -| `store` | `boolean` | 応答を永続化して取得 / RAG ワークフロー向けに保存 | -| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 などの推論負荷 | -| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 などのテキスト冗長度 | +| `maxTokens` | `number` | 応答の最大トークン数 | +| `store` | `boolean` | 応答を保存して取得 / RAG ワークフローに利用 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 などの reasoning effort | +| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 などのテキストの冗長度 | 設定はどちらのレベルにも付与できます: -`Runner` レベルの設定は、競合するエージェント単位の設定より優先されます。 +`Runner` レベルの設定は、競合するエージェントごとの設定を上書きします。 --- ## プロンプト -エージェント には `prompt` パラメーターを設定でき、これは エージェント の挙動を制御するために使用する サーバー 保存のプロンプト構成を示します。現在、このオプションは OpenAI の +エージェントは `prompt` パラメーターで構成でき、エージェントの挙動を制御するために使用すべき サーバー保存のプロンプト構成 を指示します。現在、このオプションは OpenAI の [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみサポートされています。 -| フィールド | 型 | 注記 | -| ----------- | -------- | ------------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | プロンプトの一意の識別子 | -| `version` | `string` | 使用したいプロンプトのバージョン | -| `variables` | `object` | プロンプトに代入する変数のキー/値の組。値は文字列、またはテキスト・画像・ファイルなどのコンテンツ入力型が可能 | +| 項目 | 型 | 注記 | +| ----------- | -------- | --------------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | プロンプトの一意の識別子 | +| `version` | `string` | 使用したいプロンプトのバージョン | +| `variables` | `object` | プロンプトに代入する変数のキー/値ペア。値は文字列またはテキスト・画像・ファイルなどのコンテンツ入力タイプが可能 | -tools や instructions などの追加の エージェント 構成は、保存済みプロンプトで設定している値を上書きします。 +tools や instructions など、追加のエージェント構成は、保存済みプロンプトで設定した値を上書きします。 --- ## カスタムモデルプロバイダー -独自のプロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、そのプロバイダーを `Runner` コンストラクターに渡します: +独自のプロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、プロバイダーを `Runner` のコンストラクタに渡します: -これによりトレースが [OpenAI dashboard](https://platform.openai.com/traces) に送信され、ワークフローの完全な実行グラフを確認できます。 +これによりトレースが [OpenAI dashboard](https://platform.openai.com/traces) に送信され、ワークフローの完全な実行グラフを検査できます。 --- ## 次のステップ - [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を参照 -- [ツール](/openai-agents-js/ja/guides/tools) でモデルにスーパーパワーを付与 +- [ツール](/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 4903b506..2f506954 100644 --- a/docs/src/content/docs/ja/guides/multi-agent.md +++ b/docs/src/content/docs/ja/guides/multi-agent.md @@ -3,38 +3,38 @@ title: マルチエージェント description: Coordinate the flow between several agents --- -オーケストレーションとは、アプリ内での エージェント の流れを指します。どの エージェント が、どの順序で実行され、次に何をするかをどのように決めるのか。エージェント をオーケストレーションする方法は主に 2 つあります。 +オーケストレーションとは、アプリ内のエージェントのフローのことです。どのエージェントが、どの順序で実行され、次に何が起きるかをどう決めるか。エージェントをオーケストレーションする主な方法は 2 つあります。 -1. LLM に意思決定させる: LLM の知能を使って計画・推論し、それに基づいて取るべき手順を決めます -2. コードでオーケストレーションする: コードで エージェント の流れを決めます +1. LLM に意思決定を任せる方法: これは LLM の知能を活用して計画・推論し、それに基づいて次のステップを決めます +2. コードでオーケストレーションする方法: コードでエージェントのフローを決定します -これらのパターンは組み合わせ可能です。以下にそれぞれのトレードオフを説明します。 +これらのパターンは組み合わせることができます。どちらにもトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェント は、instructions、tools、ハンドオフ を備えた LLM です。これは、オープンエンドなタスクが与えられたときに、LLM が自律的に計画を立て、ツールを使ってアクションを実行しデータを取得し、ハンドオフ を使ってサブ エージェント にタスクを委譲できることを意味します。たとえば、リサーチ エージェント には次のようなツールを備えることができます。 +エージェントは、指示、ツール、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられた場合、LLM はツールを使ってアクションやデータ取得を行い、ハンドオフでサブエージェントに委譲しながら、タスクに取り組む計画を自律的に立てられます。例えば、あるリサーチ用エージェントには次のようなツールを備えることができます。 - Web 検索でオンラインの情報を見つける -- ファイル検索 と取得で独自データや接続を検索する -- コンピュータ操作 でコンピュータ上のアクションを実行する -- コード実行 でデータ分析を行う -- 計画、レポート作成などに優れた専門 エージェント へのハンドオフ +- ファイル検索と取得で社内データや接続を検索する +- コンピュータ操作でコンピュータ上のアクションを実行する +- コード実行でデータ分析を行う +- 計画立案、レポート作成などに強い専門エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、LLM の知能に依拠したいときに適しています。重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、LLM の知能に頼りたい場合に有効です。ここで重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーターを明確にする -2. アプリを監視して反復する。問題が起きる箇所を特定し、プロンプトを改善する -3. エージェント に内省と改善を許可する。たとえばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させる -4. 何でもできる汎用 エージェント ではなく、特定のタスクに特化して優れる エージェント を用意する -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これにより エージェント を学習させ、タスクの上達につなげられる +1. 良いプロンプトに投資する。利用可能なツール、その使い方、動作すべきパラメーターを明確にする +2. アプリをモニタリングして改善を重ねる。問題が起きる箇所を把握し、プロンプトを反復改善する +3. エージェントに内省と改善を許可する。例えばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させる +4. 何でもできる汎用エージェントではなく、1 つのタスクに特化して卓越するエージェントを用意する +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練してタスク遂行能力を高められます ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の面でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・パフォーマンスの面でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査可能な 適切な形式のデータ を生成する。たとえば、タスクをいくつかの カテゴリー に分類させ、カテゴリー に基づいて次の エージェント を選ぶ -- 複数の エージェント を連結し、ある エージェント の出力を次の エージェント の入力に変換する。ブログ記事の執筆のようなタスクを、調査、アウトライン作成、本文執筆、批評、改善という一連のステップに分解する -- タスクを実行する エージェント と、それを評価してフィードバックする エージェント を `while` ループで回し、評価者が特定の基準を満たしたと判断するまで繰り返す -- 複数の エージェント を並列実行する（例: `Promise.all` のような JavaScript の基本コンポーネントを使用）。互いに依存しない複数タスクがある場合、速度向上に有用 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。例えば、エージェントにタスクをいくつかの カテゴリー に分類させ、その カテゴリー に基づいて次のエージェントを選ぶ +- あるエージェントの出力を次のエージェントの入力に変換して連結する。ブログ記事作成のようなタスクを、調査、アウトライン作成、本文執筆、批評、改善といった一連のステップに分解する +- あるエージェントがタスクを実行し、別のエージェントが評価とフィードバックを行う `while` ループで実行し、評価者が一定の基準を満たしたと判断するまで繰り返す +- 複数のエージェントを並列実行する（例: `Promise.all` などの JavaScript の基本コンポーネントを使用）。相互依存しない複数タスクがある場合に速度向上に有用 [`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) に多数の code examples があります。 diff --git a/docs/src/content/docs/ja/guides/quickstart.mdx b/docs/src/content/docs/ja/guides/quickstart.mdx index 34950275..98bb4fd8 100644 --- a/docs/src/content/docs/ja/guides/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. プロジェクトを作成して npm を初期化します。この作業は最初の一度だけで大丈夫です +1. プロジェクトを作成して npm を初期化します。これは一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -19,26 +19,26 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm init -y ``` -2. Agents SDK をインストールします +2. Agents SDK をインストールします。 ```bash npm install @openai/agents zod@3 ``` -3. OpenAI API キーを設定します。お持ちでない場合は、OpenAI API キーの作成方法については[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)をご確認ください +3. OpenAI API キーを設定します。まだお持ちでない場合は、[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... ``` - あるいは、`setDefaultOpenAIKey('')` を呼び出してプログラム上でキーを設定し、トレーシングには `setTracingExportApiKey('')` を使用できます。 - 詳細は[SDK の設定](/openai-agents-js/ja/guides/config)をご覧ください + あるいは `setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、トレーシングには `setTracingExportApiKey('')` を使用できます。 + 詳細は[設定ガイド](/openai-agents-js/ja/guides/config)を参照してください。 ## はじめてのエージェントの作成 -エージェントは instructions と name で定義します +エージェントは instructions と name で定義します。 ```typescript import { Agent } from '@openai/agents'; @@ -52,9 +52,9 @@ const agent = new Agent({ ## はじめてのエージェントの実行 -`run` メソッドでエージェントを実行できます。開始したいエージェントと、渡したい入力の両方を渡して実行します +`run` メソッドを使ってエージェントを実行できます。開始したいエージェントと渡したい入力の両方を渡して実行します。 -これにより、その実行中に行われた最終出力とあらゆるアクションを含む execution result が返されます +これにより、最終的な出力と、その実行中に行われたあらゆるアクションを含む実行結果が返されます。 ```typescript import { Agent, run } from '@openai/agents'; @@ -72,7 +72,7 @@ console.log(result.finalOutput); ## エージェントへのツールの付与 -情報の参照やアクションの実行のために、エージェントにツールを与えることができます +情報の参照やアクションの実行のために、エージェントにツールを与えることができます。 ```typescript import { Agent, tool } from '@openai/agents'; @@ -99,9 +99,9 @@ const agent = new Agent({ }); ``` -## いくつかのエージェントの追加 +## さらにいくつかのエージェントの追加 -追加のエージェントを同様に定義することで、問題を小さな部分に分解し、エージェントを目の前のタスクにより集中させることができます。また、エージェントごとに model を定義することで、異なる問題に異なるモデルを使うこともできます +追加のエージェントを同様に定義して、問題を小さな部分に分解し、目の前のタスクにエージェントをより集中させられます。エージェントにモデルを定義することで、問題ごとに異なるモデルを使うことも可能です。 ```typescript const historyTutorAgent = new Agent({ @@ -119,7 +119,7 @@ const mathTutorAgent = new Agent({ ## ハンドオフの定義 -複数のエージェント間をオーケストレーションするために、エージェントに `handoffs` を定義できます。これにより、エージェントは会話を次のエージェントに引き継げます。これは実行の過程で自動的に行われます +複数のエージェントを調整するために、エージェントに `handoffs` を定義できます。これにより、会話を次のエージェントへ引き継げるようになります。これは実行の過程で自動的に発生します。 ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -131,11 +131,11 @@ const triageAgent = Agent.create({ }); ``` -実行後、result の `finalAgent` プロパティを見ることで、どのエージェントが最終応答を生成したかがわかります +実行後、結果の `finalAgent` プロパティを見ると、どのエージェントが最終応答を生成したかがわかります。 ## エージェントオーケストレーションの実行 -Runner は個々のエージェントの実行、潜在的なハンドオフ、およびツール実行の処理を担当します +Runner は、個々のエージェントの実行、発生しうるハンドオフ、およびツールの実行を処理します。 ```typescript import { run } from '@openai/agents'; @@ -148,18 +148,18 @@ async function main() { main().catch((err) => console.error(err)); ``` -## すべての統合 +## すべてを組み合わせる -すべてを 1 つの完全な例にまとめましょう。これを `index.js` に配置して実行します +すべてを 1 つの完全な例にまとめましょう。これを `index.js` ファイルに配置して実行します。 ## トレースの表示 -Agents SDK は自動的にトレースを生成します。これにより、エージェントの動作、呼び出したツール、ハンドオフ先のエージェントを確認できます +Agents SDK は自動的にトレースを生成します。これにより、エージェントがどのように動作したか、どのツールを呼び出したか、どのエージェントにハンドオフしたかを確認できます。 エージェント実行中に何が起きたかを確認するには、 -[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動します +[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動してください。 ## 次のステップ diff --git a/docs/src/content/docs/ja/guides/release.mdx b/docs/src/content/docs/ja/guides/release.mdx index 4e2caf20..b614be71 100644 --- a/docs/src/content/docs/ja/guides/release.mdx +++ b/docs/src/content/docs/ja/guides/release.mdx @@ -5,17 +5,17 @@ description: Learn how we version and release the SDK and recent changes. ## バージョニング -このプロジェクトは、`0.Y.Z` 形式を用いたセマンティック バージョニングを一部変更して採用しています。先頭の `0` は SDK がまだ急速に進化していることを示します。各コンポーネントの増分は次のとおりです。 +本プロジェクトは、`0.Y.Z` 形式を用いた、少し変更されたセマンティック バージョニングに従います。先頭の `0` は SDK がまだ急速に進化していることを示します。各コンポーネントは次のように増分します。 ## マイナー（`Y`）バージョン -ベータと明示されていない公開インターフェースに対する **互換性のない変更（breaking changes）** がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への変更には互換性のない変更が含まれる可能性があります。 +ベータではない公開インターフェースに対する**破壊的変更**がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への移行には破壊的変更が含まれることがあります。 -互換性のない変更を避けたい場合は、プロジェクトで `0.0.x` に固定することをおすすめします。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` に固定することをおすすめします。 ## パッチ（`Z`）バージョン -後方互換な変更の場合は `Z` を増分します。 +後方互換性のある変更には `Z` を増分します。 - バグ修正 - 新機能 @@ -24,11 +24,11 @@ description: Learn how we version and release the SDK and recent changes. ## サブパッケージのバージョニング -メインの `@openai/agents` パッケージは、個別に使用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、どれか 1 つのパッケージがバージョンアップすると他も同様に上がります。`1.0.0` に移行する際には、この方針を変更する可能性があります。 +メインの `@openai/agents` パッケージは、個別に利用可能な複数のサブパッケージで構成されています。現在、これらのパッケージのバージョンは連動しており、いずれかのパッケージのバージョンが上がると、他も同様に上がります。`1.0.0` に移行する際に、この方針を変更する可能性があります。 ## 変更履歴 -何が変更されたかを把握しやすくするため、各サブパッケージごとに変更履歴を生成しています。変更が特定のサブパッケージで行われた場合、その変更の詳細は該当する変更履歴を確認する必要があります。 +各サブパッケージごとに変更履歴を生成しており、何が変更されたかを把握しやすくしています。変更がサブパッケージ内で行われた場合、その変更の詳細は該当パッケージの変更履歴を参照する必要があります。 - [`@openai/agents`](https://github.com/openai/openai-agents-js/blob/main/packages/agents/CHANGELOG.md) - [`@openai/agents-core`](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/CHANGELOG.md) diff --git a/docs/src/content/docs/ja/guides/results.mdx b/docs/src/content/docs/ja/guides/results.mdx index ab3a4b8a..aecdc061 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -9,81 +9,81 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? [エージェントの実行](/openai-agents-js/ja/guides/running-agents)を行うと、次のいずれかを受け取ります: -- [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) — `stream: true` を付けずに `run` を呼び出した場合 -- [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult) — `stream: true` を付けて `run` を呼び出した場合。ストリーミングの詳細は [ストリーミング](/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` プロパティには、最後に実行されたエージェントの最終出力が含まれます。結果は次のいずれかです: -- `string` — `outputType` が定義されていない任意のエージェントのデフォルト -- `unknown` — エージェントが出力タイプとして JSON スキーマを定義している場合。この場合、JSON は解析されていますが、型は手動で検証する必要があります -- `z.infer` — エージェントが出力タイプとして Zod スキーマを定義している場合。出力はこのスキーマに対して自動的に解析されます +- `string` — `outputType` が定義されていないエージェントのデフォルト +- `unknown` — エージェントが出力タイプとして JSON スキーマを定義している場合。この場合、JSON はパースされていますが、型は手動で検証する必要があります +- `z.infer` — エージェントが出力タイプとして Zod スキーマを定義している場合。出力は自動的にこのスキーマでパースされます - `undefined` — エージェントが出力を生成しなかった場合（たとえば、出力を生成する前に停止した場合） -異なる出力タイプを伴う ハンドオフ を使用している場合は、エージェントを作成する際に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用するべきです。 +異なる出力タイプのハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクタではなく `Agent.create()` メソッドを使用してください。 -これにより、SDK が発生しうるすべての ハンドオフ をまたいで出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 +これにより、SDK がすべての可能なハンドオフにわたって出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 例: -## 次ターンへの入力 +## 次ターンの入力 -次のターンに渡す入力へアクセスする方法は 2 つあります: +次のターン用の入力にアクセスする方法は 2 つあります: -- `result.history` — 入力とエージェントの出力の両方のコピーを含む -- `result.output` — エージェントのフル実行の出力を含む +- `result.history` — あなたの入力とエージェントの出力の両方のコピーを含みます +- `result.output` — エージェント全体の実行出力を含みます -`history` はチャットのようなユースケースで完全な履歴を保持するのに便利です: +`history` は、チャットのようなユースケースで完全な履歴を維持するのに便利です: - + ## 最後のエージェント -`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)s です。実行アイテムは、LLM が生成した 元 アイテムをラップします。これらを使用すると、LLM の出力に加えて、どのエージェントに関連付けられたイベントかにアクセスできます。 -- [`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 からの推論アイテムを示します。元アイテムは生成された推論です -- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。元アイテムは LLM からのツール呼び出しアイテムです +- [`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 からの推論アイテムを示します。元 アイテムは生成された推論です +- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。元 アイテムは LLM からのツール呼び出しアイテムです ## 状態 -`state` プロパティには実行の状態が含まれます。`result` に付随するほとんどの情報は `state` から導出されますが、`state` はシリアライズ/デシリアライズ可能で、エラーからの[リカバリー](/openai-agents-js/ja/guides/running-agents#exceptions)や[`interruption`](#interruptions)への対応が必要な場合に、後続の `run` 呼び出しの入力としても使用できます。 +`state` プロパティには、実行の状態が含まれます。`result` に付随する大部分は `state` から導出されていますが、`state` はシリアライズ/デシリアライズ可能で、エラーからの復旧の必要がある場合や、[`interruption`](#interruptions) に対処する必要がある場合に、後続の `run` 呼び出しへの入力としても使用できます。[エラーからの復旧](/openai-agents-js/ja/guides/running-agents#exceptions) -## 割り込み +## 中断 -エージェントで `needsApproval` を使用している場合、続行前に処理すべき `interruptions` が発生することがあります。その場合、`interruptions` は割り込みの原因となった `ToolApprovalItem`s の配列になります。割り込みの扱い方については、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) を参照してください。 +エージェントで `needsApproval` を使用している場合、続行する前に処理する必要がある `interruptions` が `run` でトリガーされることがあります。その場合、`interruptions` は中断の原因となった `ToolApprovalItem`s の配列になります。中断への対処方法の詳細は、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)を参照してください。 ## その他の情報 ### 元レスポンス -`rawResponses` プロパティには、エージェントの実行中にモデルが生成した 元 の LLM レスポンスが含まれます。 +`rawResponses` プロパティには、エージェント実行中にモデルが生成した 元 の LLM レスポンスが含まれます。 ### 最後のレスポンス 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 3f99ff27..e6a7ae0c 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -9,112 +9,107 @@ 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()` ユーティリティでそれらを **実行** します。 - + -カスタムランナーが不要な場合は、シングルトンのデフォルト `Runner` インスタンスを実行する `run()` ユーティリティも使えます。 +カスタム runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスを実行する `run()` ユーティリティも使用できます。 -別の方法として、独自のランナーインスタンスを作成できます: +あるいは、独自の runner インスタンスを作成できます。 - + -エージェントの実行後、最終出力と実行履歴全体を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 +エージェント を実行すると、最終出力と実行の完全な履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 ## エージェントループ -Runner の run メソッドでは、開始するエージェントと入力を渡します。入力は、文字列（ユーザーメッセージとして扱われます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。 +Runner の run メソッドを使用する場合、開始する エージェント と入力を渡します。入力は文字列（ユーザー メッセージとして扱われます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。 -その後、ランナーは次のループを実行します: +runner は次のループを実行します。 -1. 現在の入力で現在のエージェントのモデルを呼び出す -2. LLM 応答を確認する - - **Final output** → 返す - - **Handoff** → 新しいエージェントへ切り替え、蓄積した会話履歴を保持し、1 へ戻る - - **Tool calls** → ツールを実行し、その結果を会話に追加し、1 へ戻る +1. 現在の入力で現在の エージェント のモデルを呼び出す +2. LLM の応答を検査する + - **Final output** → return + - **Handoff** → 新しい エージェント に切り替え、累積した会話履歴を保持し、1 に戻る + - **Tool calls** → ツールを実行し、その結果を会話に追加して、1 に戻る 3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を投げる -### Runner のライフサイクル +### Runner ライフサイクル -アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスは、モデルプロバイダーやトレーシングオプションといったグローバル設定を保持します。まったく異なる設定が必要な場合のみ、別の `Runner` を作成してください。簡単なスクリプトでは、内部でデフォルトランナーを使用する `run()` を呼ぶこともできます。 +アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスは、モデルプロバイダーや トレーシング オプションなどのグローバル設定を保持します。まったく異なるセットアップが必要な場合のみ、別の `Runner` を作成してください。簡単なスクリプトの場合は、内部でデフォルト runner を使用する `run()` を呼び出すこともできます。 ## 実行引数 -`run()` メソッドへの入力は、実行を開始する初期エージェント、実行の入力、およびオプションのセットです。 +`run()` メソッドへの入力は、実行を開始する初期 エージェント、実行の入力、そして一連のオプションです。 -入力は、文字列（ユーザーメッセージとして扱われます）、[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) オブジェクトのいずれかです。 +入力は文字列（ユーザー メッセージとして扱われます）、[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 | Description | -| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着したイベントを逐次発行します | -| `context` | – | すべての tool / guardrail / handoff に転送されるコンテキストオブジェクト。詳細は [コンテキスト管理](/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` | – | すべての tool / guardrail / handoff に転送されるコンテキストオブジェクト。詳しくは [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 | +| `maxTurns` | `10` | セーフティリミット。到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスロー | +| `signal` | – | キャンセル用の `AbortSignal` | ## ストリーミング -ストリーミングでは、LLM の実行中にストリーミングイベントも受け取れます。ストリームが開始されると、`StreamedRunResult` には、新たに生成されたすべての出力を含む実行に関する完全な情報が含まれます。`for await` ループでストリーミングイベントを反復処理できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 +ストリーミング により、LLM の実行中にストリーミングイベントも受け取れるようになります。ストリームが開始されると、`StreamedRunResult` には、新たに生成されたすべての出力を含む実行に関する完全な情報が含まれます。`for await` ループを使用してストリーミングイベントを反復処理できます。詳細は [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 ## 実行設定 -独自の `Runner` インスタンスを作成する場合は、ランナーを構成するために `RunConfig` オブジェクトを渡せます。 - -| Field | Type | Purpose | -| --------------------------- | --------------------- | ----------------------------------------------------------------------- | -| `model` | `string \| Model` | 実行中の **すべて** のエージェントに特定のモデルを強制します | -| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダーです | -| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニングパラメーター | -| `handoffInputFilter` | `HandoffInputFilter` | handoff 実行時に入力アイテムを変更します（handoff 自体で未定義の場合） | -| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | -| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | -| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します | -| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、トレースから LLM/ツールの入出力を除外します | -| `workflowName` | `string` | Traces ダッシュボードに表示され、関連する実行のグルーピングに役立ちます | -| `traceId` / `groupId` | `string` | SDK に生成させず、トレースまたはグループ ID を手動指定します | -| `traceMetadata` | `Record` | すべてのスパンに付与する任意のメタデータ | +独自の `Runner` インスタンスを作成する場合は、runner を構成するために `RunConfig` オブジェクトを渡せます。 + +| Field | Type | Purpose | +| --------------------------- | --------------------- | ------------------------------------------------------------------------------ | +| `model` | `string \| Model` | 実行中の **すべて** の エージェント に特定のモデルを強制適用 | +| `modelProvider` | `ModelProvider` | モデル名を解決するプロバイダー。デフォルトは OpenAI プロバイダー | +| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニングパラメーター | +| `handoffInputFilter` | `HandoffInputFilter` | handoff を行う際に入力アイテムを変換（handoff 自体で既に定義されていない場合） | +| `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) を参照してください。 +インタラクティブなバージョンは [チャットの code examples](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) – 設定またはユーザー入力に基づいてスローされたエラー +- [`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 +120,6 @@ Math homework guardrail tripped ## 次のステップ -- [モデル](/openai-agents-js/ja/guides/models) の構成方法を学ぶ -- エージェントに [ツール](/openai-agents-js/ja/guides/tools) を提供する +- [モデル](/openai-agents-js/ja/guides/models) の設定方法を学ぶ +- エージェント に [ツール](/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/streaming.mdx b/docs/src/content/docs/ja/guides/streaming.mdx index 0e2dd876..5b5a3be5 100644 --- a/docs/src/content/docs/ja/guides/streaming.mdx +++ b/docs/src/content/docs/ja/guides/streaming.mdx @@ -9,48 +9,48 @@ 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` インターフェースを実装します。各イテレーションで、その実行内で何が起きたかを表すオブジェクトがイベントとして渡されます。ストリームは 3 種類のイベントタイプのいずれかを返し、エージェントの実行の異なる部分を説明します。多くのアプリケーションはモデルのテキストだけが必要なため、ストリームにはそのためのヘルパーが用意されています。 +ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イテレートで得られるイベントは、実行内で何が起きたかを表すオブジェクトです。ストリームはエージェントの実行の異なる部分を記述する 3 種類のイベントのいずれかを返します。多くのアプリケーションはモデルのテキストだけを必要とするため、ストリームにはそのためのヘルパーが用意されています。 ### テキスト出力の取得 -`stream.toTextStream()` を呼び出すと、生成されたテキストのストリームを取得できます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js の `Readable` です。`process.stdout` や他の出力先へ直接パイプできます。 +発生したテキストのストリームを得るには `stream.toTextStream()` を呼びます。`compatibleWithNodeStreams` が `true` のとき、戻り値は通常の Node.js `Readable` です。`process.stdout` や他の出力先へ直接パイプできます。 -`stream.completed` の Promise は、実行と保留中のすべてのコールバックが完了すると解決されます。出力がもうないことを確実にする場合は必ず待機してください。 +`stream.completed` の Promise は、実行とすべての保留中のコールバックが完了すると解決されます。出力がもうないことを確実にしたい場合は必ず await してください。 ### すべてのイベントの監視 -到着した各イベントを確認するには、`for await` ループを使用できます。役に立つ情報としては、低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などがあります: +`for await` ループを使えば、到着した各イベントを検査できます。役立つ情報には、低レベルのモデルイベント、任意のエージェントの切り替え、そして SDK 固有の実行情報が含まれます。 -完全なスクリプトについては、[the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。プレーンテキストのストリームと元のイベントストリームの両方を出力します。 +[ストリーミングされた code examples](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照すると、プレーンテキストストリームと元のイベントストリームの両方を出力する完全なスクリプトが見られます。 ## イベントタイプ -ストリームは 3 種類の異なるイベントタイプを返します: +ストリームは 3 種類のイベントタイプを返します。 ### raw_model_stream_event @@ -118,23 +118,23 @@ type RunAgentUpdatedStreamEvent = { } ``` -## ストリーミング中の 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 d1eb5633..c6dba9b9 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,36 +10,36 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -ツールはエージェントが **アクションを実行** する手段です。データ取得、外部 API 呼び出し、コード実行、さらにはコンピュータ操作まで行えます。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします: +ツールはエージェントに **アクションの実行** を可能にします。データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの使用まで。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします: -1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと並行して実行します（Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成） -2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM から呼び出せるようにします -3. **エージェントをツールとして** – エージェント全体を呼び出し可能なツールとして公開します -4. **ローカル MCP サーバー** – 自分のマシン上で動作する Model Context Protocol サーバーを接続します +1. **Hosted tools** – モデルと並行して OpenAI サーバー上で実行されます（Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成） +2. **Function tools** – 任意のローカル関数を JSON スキーマでラップし、LLM が呼び出せるようにします +3. **Agents as tools** – エージェント全体を呼び出し可能なツールとして公開します +4. **Local MCP servers** – ローカルで稼働する Model Context Protocol サーバーを接続します --- -## 1. 組み込みツール（Hosted） +## 1. Hosted tools -`OpenAIResponsesModel` を使用する場合、次の組み込みツールを追加できます: +`OpenAIResponsesModel` を使うと、次の組み込みツールを追加できます: -| ツール | Type 文字列 | 目的 | -| ---------------- | -------------------- | --------------------------------------------- | -| Web 検索 | `'web_search'` | インターネット検索 | -| ファイル / 検索 | `'file_search'` | OpenAI 上でホストされるベクトルストアのクエリ | -| コンピュータ操作 | `'computer'` | GUI 操作の自動化 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | -| 画像生成 | `'image_generation'` | テキストに基づく画像の生成 | +| ツール | Type 文字列 | 目的 | +| ----------------------- | -------------------- | --------------------------------------------- | +| Web search | `'web_search'` | インターネット検索 | +| File / retrieval search | `'file_search'` | OpenAI 上にホストされたベクトルストアのクエリ | +| Computer use | `'computer'` | GUI 操作の自動化 | +| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | +| Image generation | `'image_generation'` | テキストに基づく画像生成 | -正確なパラメーターセットは OpenAI Responses API と一致します。`rankingOptions` やセマンティックフィルタなどの詳細オプションは公式ドキュメントを参照してください。 +正確なパラメーター構成は OpenAI Responses API と一致します。`rankingOptions` やセマンティックフィルタなどの高度なオプションは公式ドキュメントを参照してください。 --- -## 2. 関数ツール +## 2. Function tools -`tool()` ヘルパーで **任意の** 関数をツール化できます。 +`tool()` ヘルパーで、**任意** の関数をツール化できます。 string \| Promise`– ビジネスロジック。2 つ目のオプション引数は `RunContext` | -| `errorFunction` | いいえ | 内部エラーをユーザーに表示する文字列へ変換するカスタムハンドラー `(context, error) => string` | +| フィールド | 必須 | 説明 | +| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `name` | いいえ | デフォルトは関数名（例: `get_weather`） | +| `description` | はい | LLM に表示される明確で人間が読める説明 | +| `parameters` | はい | Zod スキーマまたは raw な JSON スキーマオブジェクトのいずれか。Zod の parameters を使うと自動的に **strict** モードが有効化 | +| `strict` | いいえ | `true`（デフォルト）の場合、引数の検証に失敗すると SDK はモデルエラーを返します。あいまいなマッチングが必要な場合は `false` に設定 | +| `execute` | はい | `(args, context) => string \| Promise` – ビジネスロジック。2 番目の引数は省略可能で、`RunContext` です | +| `errorFunction` | いいえ | 内部エラーをユーザーに見える文字列へ変換するカスタムハンドラー `(context, error) => string` | ### 非 strict な JSON スキーマツール -無効または部分的な入力でもモデルに推測させたい場合は、元の JSON スキーマ使用時に strict モードを無効化できます: +無効または部分的な入力をモデルに推測させたい場合は、raw な JSON スキーマ使用時に strict モードを無効化できます: 内部的に SDK は次を行います: -- 単一の `input` パラメーターを持つ関数ツールを作成 -- ツールが呼ばれたときにその入力でサブエージェントを実行 -- 最後のメッセージ、または `customOutputExtractor` により抽出された出力を返却 +- 単一の `input` パラメーターを持つ function tool を作成 +- ツールが呼び出されたときに、その入力でサブエージェントを実行 +- 最後のメッセージ、または `customOutputExtractor` で抽出した出力を返却 --- -## 4. ローカル MCP サーバー +## 4. Local MCP servers -ローカルの [Model Context Protocol](https://modelcontextprotocol.io/) サーバー経由でツールを公開し、エージェントに接続できます。 -`MCPServerStdio` を使ってサーバーの起動と接続を行います: +ローカルの [Model Context Protocol](https://modelcontextprotocol.io/) サーバー経由でツールを公開し、エージェントに接続できます。`MCPServerStdio` を使ってサーバーを起動・接続します: @@ -95,23 +94,23 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer --- -## ツール使用の挙動 +## ツール使用時の挙動 -モデルがいつ、どのようにツールを使用すべきかを制御する方法は、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください（`tool_choice`、`toolUseBehavior` など）。 +モデルがいつどのようにツールを使用するか（`tool_choice`、`toolUseBehavior` など）の制御は、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください。 --- ## ベストプラクティス - **短く明確な説明** – ツールが何をするか、いつ使うかを記述 -- **入力の検証** – 可能な限り Zod スキーマで厳密な JSON 検証を実施 -- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返すべきで、throw しない -- **1 ツール 1 責務** – 小さく合成可能なツールはモデルの推論精度を高める +- **入力の検証** – 可能であれば Zod スキーマで厳密な JSON 検証を実施 +- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返し、例外を投げない +- **ツールごとに単一責任** – 小さく合成可能なツールはモデルの推論を向上 --- ## 次のステップ -- [エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を学ぶ -- [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加してツールの入力や出力を検証 -- TypeDoc リファレンスの [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツールタイプを参照 +- [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) について学ぶ +- ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 +- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各 Hosted tool タイプの TypeDoc リファレンスを確認 diff --git a/docs/src/content/docs/ja/guides/tracing.mdx b/docs/src/content/docs/ja/guides/tracing.mdx index 1ee34d84..45b1e4d0 100644 --- a/docs/src/content/docs/ja/guides/tracing.mdx +++ b/docs/src/content/docs/ja/guides/tracing.mdx @@ -7,24 +7,24 @@ import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw'; -Agents SDK には組み込みのトレーシングが含まれており、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントも対象です。[Traces ダッシュボード](https://platform.openai.com/traces) を使用して、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みの トレーシング が含まれており、エージェントの実行中に発生するイベントの詳細な記録を収集します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、そして発生するカスタムイベントまでを網羅します。[Traces dashboard](https://platform.openai.com/traces) を使用して、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 ## エクスポートループのライフサイクル -ほとんどの環境では、トレースは定期的に自動エクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。トレースが大量にキューにたまった場合はエクスポートされますが、定期的なエクスポートは行われません。代わりに、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用して手動でエクスポートしてください。 +多くの環境では、トレースは定期的に自動エクスポートされます。ブラウザおよび Cloudflare Workers では、この機能はデフォルトで無効です。大量にキューに溜まった場合はトレースはエクスポートされますが、定期的にはエクスポートされません。代わりに、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用して手動でトレースをエクスポートしてください。 -たとえば Cloudflare Worker では、コード全体を `try/catch/finally` ブロックでラップし、`waitUntil` とあわせて強制フラッシュを使い、ワーカーの終了前にトレースがエクスポートされるようにします。 +たとえば Cloudflare Worker では、コードを `try/catch/finally` ブロックでラップし、`waitUntil` と一緒に強制フラッシュを使用して、ワーカーが終了する前にトレースがエクスポートされるようにします。 ` - - `group_id`: 任意のグループ ID。同じ会話からの複数のトレースを紐づけるために使用。例えばチャットスレッド ID など - - `disabled`: True の場合、このトレースは記録されない +- **Traces** は「ワークフロー」の単一のエンドツーエンドの操作を表します。複数の Span で構成されます。Traces は次のプロパティを持ちます: + - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意の ID。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります + - `group_id`: 同じ会話からの複数のトレースをリンクするための任意のグループ ID。例えばチャットスレッド ID を使用できます + - `disabled`: True の場合、このトレースは記録されません - `metadata`: トレースの任意のメタデータ -- **スパン** は開始時刻と終了時刻を持つ処理を表します。スパンには次があります: +- **Spans** は開始時刻と終了時刻を持つ操作を表します。Spans は次を持ちます: - `started_at` と `ended_at` のタイムスタンプ - - 所属するトレースを示す `trace_id` - - 親スパンを指す `parent_id`（ある場合） - - スパンに関する情報である `span_data`。例えば `AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報など + - 所属するトレースを表す `trace_id` + - 親の Span を指す `parent_id`（ある場合） + - Span に関する情報である `span_data`。例えば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報など ## デフォルトのトレーシング デフォルトで、SDK は次をトレースします: -- `run()` または `Runner.run()` 全体が `Trace` でラップされる -- エージェントが実行されるたびに `AgentSpan` でラップされる -- LLM 生成は `GenerationSpan` でラップされる -- 関数ツールの呼び出しはそれぞれ `FunctionSpan` でラップされる -- ガードレールは `GuardrailSpan` でラップされる -- ハンドオフは `HandoffSpan` でラップされる +- `run()` または `Runner.run()` 全体が `Trace` でラップされます +- エージェントが実行されるたびに、`AgentSpan` でラップされます +- LLM 生成は `GenerationSpan` でラップされます +- 関数ツール呼び出しはそれぞれ `FunctionSpan` でラップされます +- ガードレールは `GuardrailSpan` でラップされます +- ハンドオフは `HandoffSpan` でラップされます -デフォルトではトレース名は "Agent workflow" です。`withTrace` を使ってこの名前を設定できます。または、[`RunConfig.workflowName`](/openai-agents-js/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 trace processors](#custom-tracing-processors) を設定して、トレースを別の送信先へ送る（置き換え、またはセカンダリの送信先として追加）ことができます。 ### 音声エージェントのトレーシング -`RealtimeAgent` と `RealtimeSession` をデフォルトの OpenAI Realtime API と一緒に使用している場合、`RealtimeSession` で `tracingDisabled: true` を設定するか、環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を使用して無効化しない限り、トレーシングは Realtime API 側で自動的に行われます。 +デフォルトの OpenAI Realtime API と `RealtimeAgent` および `RealtimeSession` を使用している場合、`RealtimeSession` で `tracingDisabled: true` を設定するか、環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を使用して無効化しない限り、トレーシングは Realtime API 側で自動的に行われます。 -詳細は[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents)を参照してください。 +詳しくは [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 -## 上位レベルのトレース +## 高レベルのトレース -`run()` の複数回の呼び出しを 1 つのトレースにまとめたい場合があります。その場合はコード全体を `withTrace()` でラップします。 +複数の `run()` 呼び出しを 1 つのトレースに含めたい場合があります。その場合は、コード全体を `withTrace()` でラップします。 -1. 2 回の `run` 呼び出しが `withTrace()` によってラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 +1. `withTrace()` で 2 回の `run` 呼び出しをラップしているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 ## トレースの作成 -[`withTrace()`](/openai-agents-js/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) または該当する環境のポリフィルを通じて追跡されます。これは自動的に並行性に対応することを意味します。 ## スパンの作成 -`create*Span()`（例: `createGenerationSpan()`, `createFunctionSpan()` など）各種メソッドでスパンを作成できます。一般的にはスパンを手動で作成する必要はありません。カスタムスパン情報を追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数が利用できます。 +さまざまな `create*Span()`（例: `createGenerationSpan()`、`createFunctionSpan()` など）メソッドを使用してスパンを作成できます。一般的には、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するための [`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-js/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-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 のバックエンドへバッチでエクスポートします。 +- 初期化時に、トレースの作成を担当し、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) からアクセスできるグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します +- `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 に送信されません。 +1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) は、トレースやスパンが準備できた時点で受け取る、**追加の** トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を実行できます +2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) は、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換え** ることができます。これは、`TracingProcessor` を含めない限り、トレースが OpenAI のバックエンドに送信されないことを意味します ## 外部トレーシングプロセッサー一覧 diff --git a/docs/src/content/docs/ja/guides/troubleshooting.mdx b/docs/src/content/docs/ja/guides/troubleshooting.mdx index 53f5abb0..5dd97f75 100644 --- a/docs/src/content/docs/ja/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ja/guides/troubleshooting.mdx @@ -5,36 +5,36 @@ 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+ +- Node.js 22 以降 +- Deno 2.35 以降 +- Bun 1.2.5 以降 -### 制限付きサポート +### 限定的なサポート -- **Cloudflare Workers**: Agents SDK は Cloudflare Workers で使用できますが、現在いくつかの制限があります: - - 現在の SDK は `nodejs_compat` を有効にする必要があります - - トレースはリクエストの最後に手動でフラッシュする必要があります。詳細は [トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください。 - - Cloudflare Workers の `AsyncLocalStorage` のサポートが限定的なため、一部のトレースが正確でない可能性があります +- **Cloudflare Workers**: Agents SDK は Cloudflare Workers でも使用できますが、現時点ではいくつかの制限があります + - 現在、SDK には `nodejs_compat` を有効にする必要があります + - トレースはリクエストの最後に手動でフラッシュする必要があります。[トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle)を参照してください + - Cloudflare Workers における `AsyncLocalStorage` のサポートが限定的なため、一部のトレースが正確でない可能性があります - **ブラウザ**: - - 現在、ブラウザではトレーシングはサポートされていません + - ブラウザでは現在トレーシングはサポートされていません - **v8 isolates**: - - 適切なブラウザ用ポリフィルを備えたバンドラを使用すれば v8 isolates 向けに SDK をバンドルできるはずですが、トレーシングは動作しません - - v8 isolates は十分な検証がされていません + - 適切なブラウザ用ポリフィルを備えたバンドラを使えば v8 isolates 向けに SDK をバンドルできるはずですが、トレーシングは機能しません + - v8 isolates は十分にテストされていません ## デバッグログ -SDK で問題が発生している場合、デバッグログを有効にして、何が起きているかの詳細を取得できます。 +SDK で問題が発生している場合、デバッグログを有効にすると詳細を確認できます。 -`DEBUG` 環境変数を `openai-agents:*` に設定してデバッグログを有効にします。 +デバッグログは、環境変数 `DEBUG` を `openai-agents:*` に設定すると有効になります。 ```bash DEBUG=openai-agents:* ``` -または、SDK の特定の部分にスコープを絞ってデバッグを有効にできます: +または、SDK の特定部分に範囲を絞ってデバッグできます: -- `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` — リアルタイムエージェント コンポーネント用に diff --git a/docs/src/content/docs/ja/guides/voice-agents.mdx b/docs/src/content/docs/ja/guides/voice-agents.mdx index 987db7fd..69b7b7cb 100644 --- a/docs/src/content/docs/ja/guides/voice-agents.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents.mdx @@ -23,29 +23,29 @@ import websocketSessionExample from '../../../../../../examples/docs/voice-agent import transportEventsExample from '../../../../../../examples/docs/voice-agents/transportEvents.ts?raw'; import thinClientExample from '../../../../../../examples/docs/voice-agents/thinClient.ts?raw'; -![リアルタイムエージェント](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) +![Realtime Agents](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) -音声エージェントは、OpenAI の speech-to-speech モデルを使ってリアルタイムの音声チャットを提供します。これらのモデルは音声やテキスト、ツール呼び出しのストリーミングに対応し、音声/電話のカスタマーサポート、モバイルアプリの体験、音声チャットといった用途に最適です。 +音声エージェントは OpenAI の音声-音声モデルを使って、リアルタイムの音声チャットを提供します。これらのモデルは音声、テキスト、ツール呼び出しのストリーミングに対応しており、音声/電話でのカスタマーサポート、モバイルアプリ体験、音声チャットなどの用途に最適です。 Voice Agents SDK は、[OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) 向けの TypeScript クライアントを提供します。 ### 主な機能 -- WebSocket または WebRTC 経由で接続 -- ブラウザとバックエンド接続の両方で利用可能 +- WebSocket または WebRTC で接続 +- ブラウザとバックエンドの両方で利用可能 - 音声と割り込みのハンドリング - ハンドオフによるマルチエージェントのオーケストレーション - ツールの定義と呼び出し - モデル出力を監視するカスタムガードレール -- ストリーミングされたイベント用のコールバック +- ストリーミングされたイベントのコールバック - テキストと音声のエージェントの両方で同じコンポーネントを再利用 -音声対音声モデルを使用することで、モデルが動作した後にテキストへ文字起こしし、再び音声へ変換し直すことなく、モデルのリアルタイムな音声処理能力を活用できます。 +音声-音声モデルを使用することで、モデルが処理した後にテキストへ文字起こしして再び音声へ変換し直す必要がなく、リアルタイムに音声を処理するモデルの能力を活用できます。 -![音声対音声モデル](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) +![音声-音声モデル](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 5f2a4e3e..80de5709 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/build.mdx @@ -28,129 +28,128 @@ 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 では挙動がやや異なります。ハンドオフが実行されると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 +通常のエージェントと異なり、リアルタイムエージェントではハンドオフの挙動がやや異なります。ハンドオフが実行されると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 -さらに、これはハンドオフの一部として `voice` や `model` を変更できないことを意味します。接続できるのは他の Realtime Agents のみです。別のモデル、たとえば `o4-mini` のような推論モデルを使う必要がある場合は、[ツールによる委譲](#delegation-through-tools) を使用できます。 +また、これによりハンドオフの一環として `voice` や `model` を変更することはできません。接続できるのは他の リアルタイムエージェント のみです。別のモデル、例えば `o4-mini` のような推論モデルを使う必要がある場合は、[ツールによる委譲](#delegation-through-tools) を使用できます。 ## ツール -通常のエージェントと同様に、Realtime Agents はツールを呼び出してアクションを実行できます。通常のエージェントで使用するのと同じ `tool()` 関数でツールを定義できます。 +通常のエージェントと同様に、リアルタイムエージェントはツールを呼び出してアクションを実行できます。通常のエージェントで使用するのと同じ `tool()` 関数を使ってツールを定義できます。 -Realtime Agents で使用できるのは 関数ツール のみで、これらのツールは Realtime セッションと同じ場所で実行されます。つまり、ブラウザで Realtime セッションを実行している場合は、ツールもブラウザで実行されます。より機微な操作を行う必要がある場合は、ツール内からバックエンド サーバー に HTTP リクエストを送ることができます。 +リアルタイムエージェントで使用できるのは関数ツールのみで、これらのツールは Realtime Session と同じ場所で実行されます。つまり、Realtime Session をブラウザで実行している場合、ツールもブラウザで実行されます。より機微なアクションを実行する必要がある場合は、ツール内でバックエンド サーバーへの HTTP リクエストを行ってください。 -ツールの実行中、エージェントは新しいリクエストを処理できません。体験を改善する 1 つの方法は、ツールを実行する直前にアナウンスするようエージェントに指示したり、ツールの実行時間を稼ぐための特定のフレーズを話させることです。 +ツールの実行中、エージェントは新しいユーザーからのリクエストを処理できません。体験を向上させる 1 つの方法は、ツールを実行しようとしていることをエージェントにアナウンスさせたり、ツール実行のための時間を稼ぐために特定のフレーズを言わせたりすることです。 ### 会話履歴へのアクセス -エージェントが特定のツールを呼び出した際の引数に加えて、Realtime セッションが追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[委譲のためのツール](#delegation-through-tools) を使用する予定がある場合に役立ちます。 +エージェントが特定のツールを呼び出す際の引数に加えて、Realtime Session が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[ツールによる委譲](#delegation-through-tools) を使用する予定がある場合に役立ちます。 ### ツール実行前の承認 -ツールを `needsApproval: true` で定義すると、エージェントはツールを実行する前に `tool_approval_requested` イベントを発行します。 +`needsApproval: true` でツールを定義すると、エージェントはツールを実行する前に `tool_approval_requested` イベントを発行します。 -このイベントをリッスンして、ユーザーにツール呼び出しを承認または拒否するための UI を表示できます。 +このイベントをリッスンすることで、ツール呼び出しを承認または拒否する UI をユーザーに表示できます。 ## ガードレール -ガードレールは、エージェントが発話した内容がルールに違反していないかを監視し、違反があれば即座に応答を打ち切る方法を提供します。これらのガードレールのチェックは、エージェントの応答の文字起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効です）。 +ガードレールは、エージェントの発話が一連のルールに違反していないかを監視し、即座に応答を打ち切る方法を提供します。これらのガードレール チェックはエージェントの応答の書き起こしに基づいて行われるため、モデルのテキスト出力が有効になっている必要があります（デフォルトで有効）。 -提供したガードレールは、モデルの応答が返ってくるのと同時に非同期で実行され、たとえば「特定の禁止ワードに言及した」といった、事前に定義された分類トリガーに基づいて応答を打ち切れます。 +提供したガードレールは、モデル応答の返却に合わせて非同期に実行され、あらかじめ定義した分類トリガー（例：「特定の禁止語を述べた」）に基づいて応答を打ち切ることができます。 -ガードレールが発動すると、セッションは `guardrail_tripped` イベントを発行します。イベントはまた、ガードレールをトリガーした `itemId` を含む `details` オブジェクトも提供します。 +ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。イベントには、ガードレールをトリガーした `itemId` を含む `details` オブジェクトも提供されます。 -デフォルトでは、ガードレールは 100 文字ごと、または応答テキストの末尾で実行されます。テキストの発話には通常時間がかかるため、ほとんどの場合、ユーザーがそれを聞く前にガードレールが違反を検知できます。 +デフォルトでは、ガードレールは 100 文字ごと、または応答テキストの生成が完了した時点で実行されます。テキストの読み上げには通常より長い時間がかかるため、ほとんどの場合、ユーザーが聞く前にガードレールが違反を検知できるはずです。 -この挙動を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡してください。 +この挙動を変更したい場合は、セッションに `outputGuardrailSettings` オブジェクトを渡します。 ## ターン検出 / 音声活動検出 -Realtime セッションは、ユーザーが話しているタイミングを自動的に検出し、組み込みの [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 セッションはエージェントの生成を中断し、ユーザーに対して何が話されたかの知識を切り詰め、履歴を更新します。 +いずれの場合も、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. 割り込みにより切り詰められた応答には書き起こしがありません ## ツールによる委譲 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 42b85af8..a2b80186 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx @@ -28,7 +28,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 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 @@ -40,11 +40,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t npm install @openai/agents zod@3 ``` - 代わりに、スタンドアロンのブラウザ用パッケージである `@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 を介してモデルに安全に接続する方法が必要です。そのために、バックエンド サーバー で生成すべき [ephemeral client key](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) を使用できます。テスト目的であれば、`curl` と通常の OpenAI API キーを使ってキーを生成することもできます ```bash export OPENAI_API_KEY="sk-proj-...(your own key here)" @@ -59,11 +59,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - レスポンスにはトップレベルに "value" の文字列が含まれ、"ek\_" プレフィックスで始まります。この一時キーを使用して、後で WebRTC 接続を確立できます。なお、このキーの有効期限は短いため、再生成が必要になります。 + レスポンスにはトップレベルに "value" という文字列が含まれ、"ek\_" プレフィックスで始まります。このエフェメラルキーを使って後で WebRTC 接続を確立できます。このキーは短時間しか有効ではないため、再生成が必要になります -3. **はじめてのエージェントを作成** +3. **最初のエージェントの作成** - 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`Agent`](/openai-agents-js/ja/guides/agents) の作成と非常によく似ています。 + 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`エージェント`](/openai-agents-js/ja/guides/agents) の作成にとてもよく似ています ```typescript import { RealtimeAgent } from '@openai/agents-realtime'; @@ -76,7 +76,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 4. **セッションの作成** - 通常のエージェントとは異なり、音声エージェントは `RealtimeSession` の中で継続的に稼働し、会話とモデルへの接続を時間経過にわたって処理します。このセッションは、音声処理、中断、その他多数のライフサイクル機能も扱います。これらについては後ほど説明します。 + 通常のエージェントと異なり、Voice Agent は `RealtimeSession` の中で継続的に実行され、時間の経過にわたって会話とモデルへの接続を処理します。このセッションは、音声処理、割り込み、その他多くのライフサイクル機能も処理します。これらは後ほど説明します ```typescript import { RealtimeSession } from '@openai/agents-realtime'; @@ -86,25 +86,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` のコンストラクターは最初の引数として `agent` を取ります。このエージェントが、 ユーザー が最初に対話できるエージェントになります。 + `RealtimeSession` のコンストラクタは最初の引数として `agent` を受け取ります。このエージェントが、 ユーザー が最初に対話できるエージェントになります -5. **セッションに接続** +5. **セッションへの接続** - セッションに接続するには、先ほど生成したクライアントの一時トークンを渡す必要があります。 + セッションに接続するには、先ほど生成したクライアントのエフェメラルトークンを渡します ```typescript await session.connect({ apiKey: 'ek_...(put your own key here)' }); ``` - これにより、ブラウザで 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/ja/guides/voice-agents/transport) ガイドで詳しく学べます -6. **すべてをつなぎ合わせる** +6. **すべてを組み合わせる** -7. **エンジンを起動して話し始める** +7. **起動して話してみる** - Web サーバー を起動し、新しい リアルタイムエージェント のコードを含むページに移動します。マイクへのアクセス許可のリクエストが表示されるはずです。許可すると、エージェントと会話を開始できます。 + Web サーバー を起動し、新しい Realtime エージェントのコードを含むページにアクセスします。マイクへのアクセス許可を求めるリクエストが表示されるはずです。許可すると、エージェントと会話を開始できます ```bash npm run dev @@ -114,16 +114,16 @@ 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#audio-interruptions) - [セッション履歴の管理](/openai-agents-js/ja/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) + - [独自のトランスポート機構の構築](/openai-agents-js/ja/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 8d7c08dd..c7bd2899 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx @@ -27,40 +27,40 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t ## デフォルトのトランスポート層 -### WebRTC での接続 +### WebRTC 接続 デフォルトのトランスポート層は WebRTC を使用します。音声はマイクから録音され、自動的に再生されます。 -独自のメディアストリームまたはオーディオ要素を使用するには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定します。 +独自のメディアストリームやオーディオ要素を使用するには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定してください。 -### WebSocket での接続 +### WebSocket 接続 -WebRTC の代わりに WebSocket 接続を使用するには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これは サーバー サイドのユースケース、たとえば Twilio で電話エージェントを構築する場合に適しています。 +WebRTC の代わりに WebSocket 接続を使うには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これはサーバー側のユースケース、例えば Twilio で電話エージェントを構築する場合に適しています。 -任意の録音/再生ライブラリを使用して、元の PCM16 オーディオバイトを処理できます。 +録音/再生ライブラリは任意のものを使用して、元の PCM16 音声バイト列を扱ってください。 ### 独自のトランスポート機構の構築 -別の音声対音声 API を使用する場合や、独自のトランスポート機構を持つ場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` のイベントを発火して独自に作成できます。 +別の音声対音声 API を使いたい場合や独自のトランスポート機構がある場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` イベントを発行して独自のものを作成できます。 -## Realtime API との直接的なやり取り +## Realtime API へのより直接的なアクセス -OpenAI Realtime API を使用しつつ、Realtime API へのより直接的なアクセスが必要な場合は、次の 2 つの方法があります。 +OpenAI Realtime API を使用しつつ、Realtime API へより直接的にアクセスしたい場合は、次の 2 つの方法があります。 ### オプション 1 - トランスポート層へのアクセス -`RealtimeSession` のすべての機能の恩恵を受けたい場合は、`session.transport` を通じてトランスポート層にアクセスできます。 +引き続き `RealtimeSession` のすべての機能を活用したい場合は、`session.transport` を通じてトランスポート層にアクセスできます。 -トランスポート層は受信するすべてのイベントを `*` イベントとして発火し、`sendEvent()` メソッドで元のイベントを送信できます。 +トランスポート層は受信したすべてのイベントを `*` イベントとして発行し、`sendEvent()` メソッドで元のイベントを送信できます。 ### オプション 2 — トランスポート層のみを使用 -自動ツール実行やガードレールなどが不要な場合は、接続と割り込みのみを管理する「薄い」クライアントとしてトランスポート層を使用できます。 +自動ツール実行やガードレールなどが不要であれば、接続や割り込みのみを管理する「薄い」クライアントとしてトランスポート層だけを使用することもできます。 diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index d1b44d22..33c242c9 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -19,30 +19,30 @@ 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 にはごく少数の基本コンポーネントがあります: +[TypeScript 向け OpenAI Agents SDK](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 -- **ハンドオフ**: 特定のタスクについて、エージェントが他のエージェントに委譲できる機能 -- **ガードレール**: エージェントへの入力を検証できる機能 +- **Agents**: instructions と tools を備えた LLM +- **Handoffs**: 特定のタスクを他のエージェントに委譲する仕組み +- **Guardrails**: エージェントへの入力を検証できる仕組み -TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストをかけずに実運用のアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が付属しており、エージェントのフローを可視化・デバッグし、評価したり、アプリケーション向けにモデルをファインチューニングすることもできます。 +これらの基本コンポーネントは TypeScript と組み合わせることで、ツールとエージェント間の複雑な関係を表現し、学習コストを抑えながら実運用アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグし、評価やアプリ向けのモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 -SDK には 2 つの設計原則があります: +SDK の設計原則は次の 2 点です。 -1. 使う価値のある十分な機能を備えつつ、素早く学べるよう基本コンポーネントは少数に抑えること -2. すぐに使えて優れた体験を提供しつつ、実際に何が起こるかを細かくカスタマイズできること +1. 使う価値のある機能は十分に備えつつ、学びやすいよう基本コンポーネントは少数にすること +2. そのままでもよく動作し、必要に応じて挙動を細かくカスタマイズできること -SDK の主な機能は次のとおりです: +主な機能は次のとおりです。 -- **エージェントループ**: ツールの呼び出し、その結果を LLM に渡し、LLM が完了するまでループする処理を内蔵 -- **TypeScript ファースト**: 新しい抽象化を学ぶ必要なく、言語機能でエージェントをオーケストレーションして連鎖させることが可能 -- **ハンドオフ**: 複数のエージェント間での調整と委譲を可能にする強力な機能 -- **ガードレール**: エージェントと並行して入力のバリデーションやチェックを実行し、失敗時は早期に中断 -- **関数ツール**: 任意の TypeScript 関数をツール化し、自動スキーマ生成と Zod による検証を提供 -- **トレーシング**: ワークフローの可視化・デバッグ・監視に加え、OpenAI の評価・ファインチューニング・蒸留ツールを活用可能 -- **リアルタイムエージェント**: 自動割り込み検出、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築可能 +- **エージェントループ**: ツールの呼び出し、結果の LLM への送信、LLM が完了するまでのループを内蔵 +- **TypeScript ファースト**: 新しい抽象を学ぶのではなく、言語の組み込み機能でエージェントをオーケストレーションし連結 +- **Handoffs**: 複数エージェント間での調整と委譲を可能にする強力な機能 +- **Guardrails**: エージェントと並行して入力の検証やチェックを実行し、失敗時は早期に中断 +- **関数ツール**: 任意の TypeScript 関数をツール化し、自動スキーマ生成と Zod ベースの検証を提供 +- **トレーシング**: フローの可視化、デバッグ、監視に加え、OpenAI の評価、ファインチューニング、蒸留のツール群を活用可能 +- **リアルタイムエージェント**: 自動割り込み検出、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 ## インストール @@ -54,7 +54,7 @@ npm install @openai/agents zod@3 -(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) +(_実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) ```bash export OPENAI_API_KEY=sk-...