diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index 2f9b3569..2f2c131d 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -7,13 +7,13 @@ 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に組み込めます。 ## セットアップ @@ -25,13 +25,13 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk npm install @openai/agents-extensions ``` -2. [Vercel の AI SDK](https://sdk.vercel.ai/docs/models/overview) から目的のモデルパッケージを選び、インストールします: +2. [Vercel の AI SDK](https://sdk.vercel.ai/docs/models/overview) から目的のモデルパッケージを選んでインストールします: ```bash npm install @ai-sdk/openai@"^1.0.0" ``` -3. アダプターとモデルをインポートして、エージェントに接続します: +3. アダプターとモデルをインポートしてエージェントに接続します: ```typescript import { openai } from '@ai-sdk/openai'; @@ -47,18 +47,22 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk ## 例 - + -## プロバイダーのメタデータの受け渡し +## プロバイダー メタデータの受け渡し -メッセージにプロバイダー固有のオプションを添えて送信する必要がある場合は、`providerMetadata` を通して渡します。値は基盤の AI SDK モデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` は +メッセージと一緒にプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` に渡します。値は基盤の AI SDK モデルにそのまま転送されます。例えば、Agents SDKで次の `providerData` は ```ts providerData: { @@ -70,7 +74,7 @@ providerData: { } ``` -AI SDK 連携を使用する場合は +次のようになります ```ts providerMetadata: { @@ -82,4 +86,4 @@ providerMetadata: { } ``` -になります。 +AI SDK 連携を使用する場合 diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index 1ca2584c..013499fa 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,37 +7,39 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio は [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しており、電話の通話からの元音声を WebSocket サーバーへ送信します。これは、あなたの [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続するために利用できます。Twilio から届くイベントを Realtime Session に接続するには、`websocket` モードのデフォルトの Realtime Session トランスポートを使えます。ただし、Web ベースの会話よりも電話では自然とレイテンシが増えるため、適切な音声フォーマットの設定や、割り込みタイミングの調整が必要になります。 +Twilio は [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しており、電話の通話音声の 元 データを WebSocket サーバーに送信します。このセットアップは、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続するために使用できます。Twilio から届くイベントを Realtime Session に接続するには、`websocket` モードの既定の Realtime Session トランスポートを使用できます。ただし、その場合は適切な音声フォーマットの設定や、Web ベースの会話よりも通話では自然とレイテンシが大きくなるため、独自の割り込みタイミングの調整が必要になります。 -セットアップ体験を向上させるために、割り込み処理や音声転送を含め、Twilio への接続を代わりに処理する専用のトランスポートレイヤーを作成しました。 +セットアップ体験を改善するために、割り込み処理や音声のフォワーディングも含め、Twilio への接続を処理する専用のトランスポートレイヤーを用意しました。 ## セットアップ -1. ** Twilio のアカウントと Twilio の電話番号を用意します ** +1. **Twilio アカウントと Twilio の電話番号を用意してください** -2. ** Twilio からのイベントを受け取れる WebSocket サーバーを用意します ** +2. **Twilio からのイベントを受け取れる WebSocket サーバーをセットアップします** - ローカルで開発している場合、これはローカルトンネルの設定が必要になり、 - これはローカルトンネルの設定が必要になり、[`ngrok`](https://ngrok.io/) や + ローカルで開発している場合、これは [`ngrok`](https://ngrok.io/) や [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - などを使ってローカルサーバーを Twilio からアクセス可能にします。Twilio への接続には - `TwilioRealtimeTransportLayer` を使えます。 + のようなローカルトンネルを設定する必要があり、これは [`ngrok`](https://ngrok.io/) や + [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) + のようなローカルトンネルを設定する必要があります。これはローカル サーバーを Twilio からアクセス可能にするためです。Twilio への接続には `TwilioRealtimeTransportLayer` + を使用できます。 -3. ** 拡張パッケージをインストールして Twilio アダプターを導入します ** +3. **extensions パッケージをインストールして Twilio アダプターを導入します:** ```bash npm install @openai/agents-extensions ``` -4. ** `RealtimeSession` に接続するためのアダプターとモデルをインポートします ** +4. **アダプターとモデルをインポートして `RealtimeSession` に接続します:** -5. ** `RealtimeSession` を Twilio に接続します ** +5. **`RealtimeSession` を Twilio に接続します:** ```typescript session.connect({ apiKey: 'your-openai-api-key' }); @@ -55,30 +57,25 @@ Twilio は [Media Streams API](https://www.twilio.com/docs/voice/media-streams) -`RealtimeSession` に期待されるあらゆるイベントや動作は、ツール呼び出し、ガードレールなどを含め、想定どおりに機能します。`RealtimeSession` を音声エージェントで使う方法の詳細は、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 +`RealtimeSession` で期待されるあらゆるイベントや動作は期待どおりに機能します。ツール呼び出し、ガードレールなども含まれます。`RealtimeSession` を音声エージェントと併用する方法の詳細は、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 ## ヒントと考慮事項 -1. ** スピードが命です ** +1. **スピードが肝心です。** - Twilio から必要なすべてのイベントや音声を受け取るため、WebSocket 接続を参照できるようになったらすぐに - `TwilioRealtimeTransportLayer` インスタンスを作成し、その直後に `session.connect()` を呼び出してください。 + Twilio から必要なイベントや音声をすべて受け取るために、WebSocket 接続の参照を取得したらすぐに `TwilioRealtimeTransportLayer` インスタンスを作成し、直ちに `session.connect()` を呼び出してください。 -2. ** Twilio の元イベントにアクセスする ** +2. **元 の Twilio イベントにアクセスします。** - Twilio が送信する元イベントにアクセスしたい場合は、`RealtimeSession` インスタンスで `transport_event` - をリッスンします。Twilio からのすべてのイベントは `twilio_message` という type と、元イベントデータを含む - `message` プロパティを持ちます。 + Twilio が送信している 元 のイベントにアクセスしたい場合は、`RealtimeSession` インスタンスで `transport_event` イベントを監視します。Twilio からのすべてのイベントは `twilio_message` という type を持ち、 元 のイベントデータを含む `message` プロパティがあります。 -3. ** デバッグログを確認する ** +3. **デバッグログを確認します。** - 状況をより詳しく知りたい問題に遭遇することがあります。環境変数 `DEBUG=openai-agents*` を使うと、 - Agents SDK からのすべてのデバッグログが表示されます。あるいは、Twilio アダプターだけのデバッグログを有効にするには - `DEBUG=openai-agents:extensions:twilio*` を使用できます。 + 何が起こっているかを詳しく知りたいときがあります。環境変数 `DEBUG=openai-agents*` を使うと、Agents SDK からのすべてのデバッグログが表示されます。あるいは、`DEBUG=openai-agents:extensions:twilio*` を使って Twilio アダプターのデバッグログだけを有効にできます。 -## 完全なサーバー例 +## 完全なサーバーの例 -以下は、Twilio からのリクエストを受け取り、`RealtimeSession` にフォワードする、WebSocket サーバーの完全な end-to-end の例です。 +以下は、Twilio からのリクエストを受け取り、それを `RealtimeSession` にフォワードする WebSocket サーバーのエンドツーエンドの完全な例です。 -このページの残りでは、エージェントのすべての機能を詳しく説明します。 +このページの残りでは、エージェントのすべての機能をより詳しく説明します。 --- ## 基本設定 -`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。最も一般的に使用される -プロパティは次のとおりです。 +`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。最もよく使うプロパティは次のとおりです。 -| Property | Required | Description | -| --------------- | -------- | -------------------------------------------------------------------------------------------------- | -| `name` | yes | 短い人間が読める識別子 | -| `instructions` | yes | システムプロンプト（文字列 **or** 関数 – [動的 instructions](#dynamic-instructions) を参照） | -| `model` | no | モデル名 **or** カスタムの [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | -| `modelSettings` | no | 調整パラメーター（temperature、top_p など） | -| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | +| プロパティ | 必須 | 説明 | +| --------------- | ---- | -------------------------------------------------------------------------------------------------- | +| `name` | yes | 短い人間可読の識別子 | +| `instructions` | yes | システムプロンプト（文字列 **または** 関数 – [動的 instructions](#dynamic-instructions) を参照） | +| `model` | no | モデル名 **または** カスタムの [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | +| `modelSettings` | no | 調整用パラメーター（temperature、top_p など） | +| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | - + --- ## コンテキスト -エージェントは **コンテキスト型に対してジェネリック** です — すなわち `Agent`。この _コンテキスト_ は -あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフ などに転送され、 -状態の保存や共有サービス（データベース接続、ユーザー メタデータ、機能フラグ、…）の提供に役立ちます。 +エージェントは **コンテキスト型に対してジェネリック** です（例: `Agent`）。コンテキストはあなたが作成して `Runner.run()` に渡す依存性注入のオブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザーメタデータ、機能フラグなど）を提供するのに便利です。 --- ## 出力タイプ -デフォルトでは、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、 -`outputType` プロパティを指定できます。SDK は次を受け付けます: +デフォルトでは、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定できます。SDK は次を受け付けます: 1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`） -2. 任意の JSON‑schema 互換オブジェクト +2. JSON スキーマ互換の任意のオブジェクト -`outputType` を指定すると、SDK はプレーンテキストではなく structured outputs を自動的に使用します。 +`outputType` が指定されると、SDK はプレーンテキストの代わりに自動的に +[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。 --- ## ハンドオフ -エージェントは `handoffs` プロパティを介して他のエージェントに **委譲** できます。一般的なパターンは、 -会話をより専門的なサブエージェントに振り分ける トリアージ エージェント を使うことです。 +エージェントは `handoffs` プロパティを介して他のエージェントに **委譲** できます。よくあるパターンは、会話をより専門的なサブエージェントに振り分ける _トリアージエージェント_ を使う方法です。 -このパターンの詳細は、[ハンドオフ](/openai-agents-js/ja/guides/handoffs) をご覧ください。 +このパターンの詳細は、[ハンドオフ](/openai-agents-js/ja/guides/handoffs) を参照してください。 --- ## 動的 instructions -`instructions` は文字列の代わりに **関数** にできます。この関数は現在の -`RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返すことができます。 +`instructions` は文字列の代わりに **関数** にできます。この関数は現在の `RunContext` とエージェントインスタンスを受け取り、文字列 _または_ `Promise` を返せます。 -同期関数と `async` 関数の両方がサポートされます。 +同期関数と `async` 関数のどちらもサポートされています。 --- ## ライフサイクルフック -高度なユースケースでは、イベントをリッスンすることでエージェントのライフサイクルを観察できます +高度なユースケースでは、イベントをリッスンしてエージェントのライフサイクルを観測できます --- ## ガードレール -ガードレールを使うと、ユーザー入力やエージェント出力を検証・変換できます。`inputGuardrails` と -`outputGuardrails` 配列で設定します。詳細は +ガードレールは、ユーザー入力やエージェント出力を検証・変換できる仕組みです。`inputGuardrails` と `outputGuardrails` の配列で設定します。詳しくは [ガードレール](/openai-agents-js/ja/guides/guardrails) を参照してください。 --- -## エージェントのクローン/コピー +## エージェントの複製／コピー -既存のエージェントを少しだけ変更した版が必要ですか？ `clone()` メソッドを使うと、完全に新しい `Agent` インスタンスが返ります。 +既存のエージェントに少しだけ手を加えたバージョンが必要ですか？`clone()` メソッドを使うと、まったく新しい `Agent` インスタンスが返されます。 ### 無限ループの防止 -ツール呼び出し後、SDK は `tool_choice` を自動的に `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返して -無限ループに入るのを防ぎます。この挙動は `resetToolChoice` フラグで上書きするか、`toolUseBehavior` を設定して変更できます: +ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツールを繰り返し呼び出し続ける無限ループに入るのを防ぎます。この動作は `resetToolChoice` フラグ、または +`toolUseBehavior` の設定で上書きできます: -- `'run_llm_again'`（デフォルト）– ツール結果を使って LLM をもう一度実行 +- `'run_llm_again'`（デフォルト） – ツール結果を使って LLM を再実行 - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う -- `{ stopAtToolNames: ['my_tool'] }` – 指定したいずれかのツールが呼ばれたら停止 -- `(context, toolResults) => ...` – 実行を終了すべきかどうかを返すカスタム関数 +- `{ stopAtToolNames: ['my_tool'] }` – 指定したツールのいずれかが呼ばれたら停止 +- `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数 ```typescript const agent = new Agent({ @@ -173,6 +163,6 @@ const agent = new Agent({ ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を学ぶ +- [エージェントの実行](/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** 配下にある TypeDoc リファレンス全体を参照する diff --git a/docs/src/content/docs/ja/guides/config.mdx b/docs/src/content/docs/ja/guides/config.mdx index 3a5bb680..c1cf34a0 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,34 +13,34 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## API キーとクライアント -デフォルトでは、 SDK は最初にインポートされたときに `OPENAI_API_KEY` 環境変数を読み込みます。変数を設定できない場合は、`setDefaultOpenAIKey()` を手動で呼び出せます。 +デフォルトで SDK は、最初にインポートされたときに `OPENAI_API_KEY` 環境変数を読み取ります。環境変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出してください。 -また、独自の `OpenAI` クライアントインスタンスを渡すこともできます。指定しない場合は、 SDK がデフォルトのキーを使って自動的に作成します。 +独自の `OpenAI` クライアント インスタンスを渡すこともできます。そうしない場合は、 SDK が既定のキーを使用して自動的に作成します。 -最後に、 Responses API と Chat Completions API を切り替えることができます。 +最後に、 Responses API と Chat Completions API を切り替えられます。 - + ## トレーシング -トレーシングはデフォルトで有効で、上記のセクションの OpenAI キーを使用します。別のキーは `setTracingExportApiKey()` で設定できます。 +トレーシングは既定で有効になっており、上記セクションの OpenAI キーを使用します。別のキーは `setTracingExportApiKey()` で設定できます。 トレーシングは完全に無効化することもできます。 @@ -48,32 +48,32 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## デバッグログ -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 ed5883dc..71296860 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 回の実行に参加するすべてのエージェント、ツール、フックは同じ型のコンテキストを使用する必要があります。 +単一の実行に参加するすべてのエージェント、ツール、フックは、同じ **型** のコンテキストを使用する必要があります。 ローカルコンテキストの用途例: -- 実行に関するデータ（ユーザー名、ID など） +- 実行に関するデータ（ユーザー名、 ID など） - ロガーやデータフェッチャーなどの依存関係 -- ヘルパー関数 +- 補助関数 -## エージェント/LLM コンテキスト +## エージェント / LLM コンテキスト -LLM を呼び出すと、参照できるデータは会話履歴に由来するものだけです。追加情報を利用可能にするには次の選択肢があります: +LLM が呼び出されると、参照できるデータは会話履歴から来るものだけです。追加情報を利用可能にするには、次のような選択肢があります: -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 の関連データに基づいて応答を根拠づける +1. エージェントの `instructions` に追加できます — システムまたは開発者メッセージとも呼ばれます。これは静的な文字列、またはコンテキストを受け取って文字列を返す関数にできます。 +2. `Runner.run()` を呼び出すときに `input` に含めることができます。これは instructions の手法に似ていますが、メッセージを [指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます。 +3. 関数ツール経由で公開して、 LLM が必要に応じてデータを取得できるようにできます。 +4. ファイル、データベース、または Web からの関連データに基づいて応答を裏付けるために、リトリーバルや Web 検索ツールを使用できます。 diff --git a/docs/src/content/docs/ja/guides/guardrails.mdx b/docs/src/content/docs/ja/guides/guardrails.mdx index 2b05b170..46afd7ae 100644 --- a/docs/src/content/docs/ja/guides/guardrails.mdx +++ b/docs/src/content/docs/ja/guides/guardrails.mdx @@ -7,42 +7,42 @@ 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. **入力ガードレール** は最初の ユーザー 入力に対して実行されます +2. **出力ガードレール** は最終的な エージェント の出力に対して実行されます ## 入力ガードレール -入力ガードレールは 3 つのステップで動作します: +入力ガードレールは 3 つのステップで実行されます: -1. ガードレールは、エージェントに渡されたものと同じ入力を受け取ります。 -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) でラップして返します。 -3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます。 +1. ガードレールは エージェント に渡されたものと同じ入力を受け取ります +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) に内包して返します +3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます -> **注意** -> 入力ガードレールはユーザー入力向けであるため、エージェントがワークフローの _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェント自体に設定します。これは、エージェントごとに必要なガードレールが異なることが多いためです。 +> **注記** +> 入力ガードレールは ユーザー 入力を対象としているため、エージェントがワークフローで _最初_ のエージェントである場合にのみ実行されます。異なるエージェントで必要なガードレールが異なることが多いため、ガードレールはエージェント自体に設定します。 ## 出力ガードレール 出力ガードレールも同じパターンに従います: -1. ガードレールは、エージェントに渡されたものと同じ入力を受け取ります。 -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) でラップして返します。 -3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます。 +1. ガードレールは エージェント に渡されたものと同じ入力を受け取ります +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) に内包して返します +3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます -> **注意** -> 出力ガードレールは、エージェントがワークフローの _最後_ のエージェントである場合にのみ実行されます。リアルタイムの音声対話については、[音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails) を参照してください。 +> **注記** +> 出力ガードレールは、エージェントがワークフローで _最後_ のエージェントである場合にのみ実行されます。リアルタイム音声での対話については [音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails) を参照してください。 -## トリップワイヤ +## トリップワイヤー -ガードレールが失敗すると、トリップワイヤを介してそれを知らせます。トリップワイヤが作動した時点で、 Runner は対応するエラーをスローし、実行を停止します。 +ガードレールが失敗すると、トリップワイヤーを介してそれを通知します。トリップワイヤーがトリガーされるとすぐに、ランナーは対応するエラーをスローして実行を停止します。 ## ガードレールの実装 -ガードレールは、`GuardrailFunctionOutput` を返す単純な関数です。以下は、内部で別のエージェントを実行して、ユーザーが数学の宿題の手伝いを求めているかどうかを確認する最小の例です。 +ガードレールは、`GuardrailFunctionOutput` を返す単純な関数です。以下は、内部で別のエージェントを実行して、ユーザーが数学の宿題の手助けを求めているかどうかを確認する最小の例です。 -1. `guardrailAgent` はガードレール関数の内部で使用されます。 -2. ガードレール関数はエージェントの入力または出力を受け取り、結果を返します。 -3. 追加情報をガードレールの結果に含めることができます。 -4. `agent` はガードレールが適用される実際のワークフローを定義します。 +1. `guardrailAgent` はガードレール関数内で使用されます +2. ガードレール関数はエージェントの入力または出力を受け取り、結果を返します +3. ガードレールの結果に追加情報を含めることができます +4. `agent` はガードレールを適用する実際のワークフローを定義します diff --git a/docs/src/content/docs/ja/guides/handoffs.mdx b/docs/src/content/docs/ja/guides/handoffs.mdx index 50831c9f..f26d6792 100644 --- a/docs/src/content/docs/ja/guides/handoffs.mdx +++ b/docs/src/content/docs/ja/guides/handoffs.mdx @@ -10,13 +10,13 @@ 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` オブジェクトを含められます。 ### 基本的な使い方 @@ -29,9 +29,9 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r - `agent` – ハンドオフ先のエージェント - `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き - `toolDescriptionOverride` – 既定のツール説明を上書き -- `onHandoff` – ハンドオフ時のコールバック。`RunContext` と、必要に応じてパース済みの入力を受け取る -- `inputType` – ハンドオフの期待される入力スキーマ -- `inputFilter` – 次のエージェントへ渡す履歴をフィルタリング +- `onHandoff` – ハンドオフが発生したときのコールバック。`RunContext` と、必要に応じてパース済み入力を受け取ります +- `inputType` – ハンドオフの想定入力スキーマ +- `inputFilter` – 次のエージェントへ渡す履歴のフィルター ## 入力フィルター -デフォルトでは、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。よく使うヘルパーは `@openai/agents-core/extensions` にあります。 +既定では、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。 +一般的なヘルパーは `@openai/agents-core/extensions` にあります。 ## 推奨プロンプト -プロンプトでハンドオフに言及していると、 LLM はより安定して応答します。この SDK は、`RECOMMENDED_PROMPT_PREFIX` から利用できる推奨プレフィックスを提供します。 +プロンプトでハンドオフに言及すると、 LLM がより安定して応答します。 SDK は `RECOMMENDED_PROMPT_PREFIX` を通じて推奨のプレフィックスを提供します。 -動作するエンドツーエンド版については、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 +エンドツーエンドで動作する完全版については、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 -## 承認に時間がかかる場合の対処 +## 長時間の承認待ちへの対応 -Human in the loop (人間の介入) フローは、サーバーを稼働させ続けなくても、長時間中断できるように設計されています。リクエストをいったん終了して後で続行する必要がある場合は、状態をシリアライズして、後で再開できます。 +Human in the loop (人間の介入) フローは、サーバーを稼働させ続けることなく長時間中断できるよう設計されています。リクエストを終了して後で続行する必要がある場合、状態をシリアライズして後から再開できます。 -状態は `JSON.stringify(result.state)` を使ってシリアライズでき、シリアライズ済みの状態を `RunState.fromString(agent, serializedState)` に渡すことで後から再開できます。ここで `agent` は、全体の実行をトリガーしたエージェントのインスタンスです。 +状態は `JSON.stringify(result.state)` を使ってシリアライズでき、後で再開する際は、シリアライズ済み状態を `RunState.fromString(agent, serializedState)` に渡します。ここで `agent` は全体の実行をトリガーしたエージェントのインスタンスです。 -この方法なら、シリアライズした状態をデータベースやリクエストと一緒に保存できます。 +この方法で、シリアライズした状態をデータベースやリクエストと一緒に保存できます。 -### 保留タスクのバージョニング +### 保留中のタスクのバージョニング -承認リクエストに時間がかかり、エージェント定義を意味のある形でバージョン管理したい、または Agents SDK のバージョンを上げたい場合は、現時点では、パッケージエイリアスを使って Agents SDK の 2 つのバージョンを並行インストールし、独自のブランチングロジックを実装することをおすすめします。 +承認リクエストに時間がかかり、エージェント定義を意味のある形でバージョン管理したい、または Agents SDK のバージョンを上げたい場合は、現時点では、パッケージエイリアスを使って Agents SDK の 2 つのバージョンを並行インストールし、独自のブランチングロジックを実装することを推奨します。 -実際には、独自コードにバージョン番号を割り当ててシリアライズ済み状態と一緒に保存し、逆シリアル化時に正しいコードバージョンへ誘導することを意味します。 +実務的には、独自コードにバージョン番号を割り当て、シリアライズした状態と一緒に保存し、デシリアライズ時に自分のコードの正しいバージョンへ誘導する、ということを意味します。 diff --git a/docs/src/content/docs/ja/guides/mcp.mdx b/docs/src/content/docs/ja/guides/mcp.mdx index e7336af2..584924af 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -12,35 +12,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'; -[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP ドキュメントより: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールやコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより： -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP は AI アプリケーションの USB-C ポートのようなものだと考えてください。USB-C がさまざまな周辺機器やアクセサリーへの接続方法を標準化するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続するための標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP は AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。USB‑C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 -この SDK がサポートする MCP サーバーには 3 種類あります: +この SDK がサポートする MCP サーバーは 3 種類あります： 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 サーバー** – 標準入出力経由でアクセスするサーバー（最もシンプルな選択肢） +2. **Streamable HTTP MCP サーバー** – [Streamable HTTP トランスポート](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートのサーバー +3. **Stdio MCP サーバー** – 標準入出力でアクセスされるサーバー（最も簡単な選択肢） -ユースケースに応じてサーバーの種類を選択してください: +ユースケースに応じてサーバータイプを選択してください： -| 必要なこと | 推奨オプション | -| ----------------------------------------------------------------------------------- | ---------------------------------- | -| 既定の OpenAI Responses モデルで公開アクセス可能なリモート サーバーを呼び出す | **1. リモート MCP サーバーツール** | -| 公開アクセス可能なリモート サーバーを使うが、ツール呼び出しはローカルでトリガーする | **2. Streamable HTTP** | -| ローカルで稼働する Streamable HTTP サーバーを使う | **2. Streamable HTTP** | -| OpenAI Responses 以外のモデルで任意の Streamable HTTP サーバーを使う | **2. Streamable HTTP** | -| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーを使う | **3. Stdio** | +| 必要なこと | 推奨オプション | +| -------------------------------------------------------------------------- | ----------------------- | +| 一般公開のリモートサーバーを既定の OpenAI Responses モデルで呼び出す | **1. Hosted MCP tools** | +| 一般公開のリモートサーバーを使うがツール呼び出しはローカルでトリガーしたい | **2. Streamable HTTP** | +| ローカルで動作する Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| OpenAI Responses 以外のモデルで任意の Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| 標準入出力プロトコルのみをサポートするローカル MCP サーバーを扱う | **3. Stdio** | ## 1. リモート MCP サーバーツール -組み込みツール（Hosted）は、往復処理全体をモデル側で完結させます。あなたのコードから MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートのツール エンドポイントを呼び出し、その結果をモデルへストリーム返却します。 +リモート ツールでは、往復の処理全体をモデル側で完結させます。あなたのコードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルへストリーミングで返します。 -リモート MCP サーバーツールを使う最も簡単な例です。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡すことで、リモート MCP サーバーツールを簡単に作成できます。 +以下はリモート MCP サーバーツールを使う最も簡単な例です。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡すことで、リモート MCP サーバーツールの作成に便利です。 -その後、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行できます: +次に、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）で エージェント を実行できます： -増分の MCP 実行結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します: +増分の MCP 結果を ストリーミング するには、`Agent` を実行するときに `stream: true` を渡します： -#### 任意の承認フロー +#### 承認フロー（オプション） -機微な操作については、個々のツール呼び出しに人の承認を要求できます。`requireApproval: 'always'` を渡すか、ツール名を `'never'`/`'always'` にマッピングするきめ細かなオブジェクトを渡してください。 +センシティブな操作については、個々のツール呼び出しに人間による承認を要求できます。`requireApproval: 'always'` を渡すか、ツール名を `'never'`/`'always'` にマッピングするきめ細かなオブジェクトを渡してください。 -ツール呼び出しが安全かどうかをプログラムで判定できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts)を使ってツール呼び出しを承認または拒否できます。人の承認を要求する場合は、ローカルの関数ツールと同様に `interruptions` を用いた同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) の方法を利用できます。 +プログラムでツール呼び出しの安全性を判定できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または却下できます。人による承認が必要な場合は、ローカルの 関数ツール と同様に `interruptions` を使った同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) のアプローチを使えます。 -完全に動作するサンプル（リモート ツール/Streamable HTTP/stdio + ストリーミング、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全に動作するサンプル（Hosted tools / Streamable HTTP / stdio + Streaming、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 ## 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 サーバー -標準入出力のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します: +標準入出力のみを公開するサーバーの場合は、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します： -## その他の知っておくべきこと +## 知っておくとよいこと -Streamable HTTP と Stdio のサーバーでは、`Agent` が実行されるたびに、利用可能なツールを検出するために `list_tools()` を呼び出す場合があります。特にリモート サーバーでは、この往復がレイテンシを増やす可能性があるため、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡して結果をメモリにキャッシュできます。 +Streamable HTTP と Stdio のサーバーでは、`Agent` が実行されるたびに、利用可能なツールを見つけるために `list_tools()` を呼び出すことがあります。この往復はレイテンシを追加する可能性があり（特にリモートサーバーに対して）、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡してメモリ内に結果をキャッシュできます。 -ツール一覧が変更されないと確信できる場合にのみ有効化してください。後でキャッシュを無効化するには、サーバー インスタンスで `invalidateToolsCache()` を呼び出します。 +ツールリストが変わらない自信がある場合にのみ有効化してください。後からキャッシュを無効化するには、サーバーインスタンスで `invalidateToolsCache()` を呼び出します。 ### ツールのフィルタリング -`createMCPToolStaticFilter` による静的フィルター、またはカスタム関数を渡すことで、各サーバーから公開されるツールを制限できます。以下は両方のアプローチを組み合わせた例です: +各サーバーから公開するツールを制限するには、`createMCPToolStaticFilter` による静的フィルター、またはカスタム関数を渡します。両方のアプローチを示す統合例を次に示します： -## 参考情報 +## 参考資料 - [Model Context Protocol](https://modelcontextprotocol.io/) – 公式仕様 -- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上で参照した実行可能なデモ +- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上記で参照した実行可能なデモ diff --git a/docs/src/content/docs/ja/guides/models.mdx b/docs/src/content/docs/ja/guides/models.mdx index a444f21b..01f094f4 100644 --- a/docs/src/content/docs/ja/guides/models.mdx +++ b/docs/src/content/docs/ja/guides/models.mdx @@ -12,12 +12,12 @@ import agentWithModelExample from '../../../../../../examples/docs/models/agentW import runnerWithModelExample from '../../../../../../examples/docs/models/runnerWithModel.ts?raw'; import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw'; -すべてのエージェントは最終的に LLM を呼び出します。SDK はモデルを次の 2 つの軽量なインターフェースの背後に抽象化します: +すべてのエージェントは最終的に LLM を呼び出します。この SDK はモデルを 2 つの軽量なインターフェースの背後に抽象化します: -- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して _1 回_ のリクエストを実行できます -- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読めるモデルの **名前**（例: 'gpt‑4o'）を `Model` インスタンスに解決します +- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して _1 回_ のリクエストを行う方法を知っています +- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読みやすいモデルの **名前** （例: `'gpt‑4o'`）を `Model` インスタンスに解決します -日常の開発では通常、モデルの **名前** と、ときどき `ModelSettings` にだけ触れます。 +日常的な作業では通常、モデルの **名前** と、ときどき `ModelSettings` にしか触れません。 -独自のネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 +ネットワーク設定をカスタマイズする必要がある場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 ### デフォルトモデル -OpenAI プロバイダーの既定は `gpt‑4o` です。エージェント単位またはグローバルに上書きできます: +OpenAI プロバイダーのデフォルトは `gpt‑4o` です。エージェント単位またはグローバルに上書きできます: --- ## ModelSettings -`ModelSettings` は OpenAI のパラメーターを反映しますが、プロバイダーに依存しません。 +`ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダー非依存です。 -| 項目 | 型 | 注記 | +| フィールド | 型 | 補足 | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ | -| `temperature` | `number` | 創造性と決定性のバランス | -| `topP` | `number` | Nucleus サンプリング | -| `frequencyPenalty` | `number` | 繰り返しトークンにペナルティ | -| `presencePenalty` | `number` | 新しいトークンを促す | +| `temperature` | `number` | 創造性と決定論のトレードオフ | +| `topP` | `number` | ニュークリアスサンプリング | +| `frequencyPenalty` | `number` | 繰り返しトークンの抑制 | +| `presencePenalty` | `number` | 新しいトークンの促進 | | `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 | -| `parallelToolCalls` | `boolean` | サポートされる環境での並列関数呼び出しを許可 | -| `truncation` | `'auto' \| 'disabled'` | トークン切り詰めの戦略 | -| `maxTokens` | `number` | レスポンス内の最大トークン数 | -| `store` | `boolean` | レスポンスを永続化して検索 / RAG ワークフローで再利用 | +| `parallelToolCalls` | `boolean` | 対応している場合は並列の関数呼び出しを許可 | +| `truncation` | `'auto' \| 'disabled'` | トークン切り詰め戦略 | +| `maxTokens` | `number` | 応答内の最大トークン数 | +| `store` | `boolean` | 応答を永続化し、取得や RAG ワークフローに利用 | 設定はどちらのレベルにも付与できます: -`Runner` レベルの設定は、競合するエージェント単位の設定を上書きします。 +`Runner` レベルの設定は、競合するエージェント単位の設定よりも優先されます。 --- ## プロンプト -エージェントは `prompt` パラメーターで構成できます。これは、エージェントの振る舞いを制御するために使用すべき、サーバーに保存されたプロンプト構成を指示します。現在、このオプションは OpenAI -[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみサポートされます。 +エージェントは `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 プロバイダー使用時、API キーを指定すると自動トレースエクスポートを有効化できます: +OpenAI プロバイダー使用時には、API キーを指定することで自動トレースエクスポートを有効化できます: -これによりトレースは [OpenAI ダッシュボード](https://platform.openai.com/traces) に送信され、ワークフローの完全な実行グラフを確認できます。 +これによりトレースが [OpenAI ダッシュボード](https://platform.openai.com/traces) に送信され、ワークフローの完全な実行グラフを確認できます。 --- ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を探索 -- [ツール](/openai-agents-js/ja/guides/tools) でモデルに強力な機能を付与 -- 必要に応じて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加 +- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を確認する +- [ツール](/openai-agents-js/ja/guides/tools) でモデルに強力な機能を与える +- 必要に応じて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加する diff --git a/docs/src/content/docs/ja/guides/multi-agent.md b/docs/src/content/docs/ja/guides/multi-agent.md index ea84a65d..9ac9d824 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 が自律的にタスクの進め方を計画し、tools でアクションやデータ取得を行い、ハンドオフでサブエージェントにタスクを委譲できることを意味します。例えば、調査用エージェントには次のようなツールを備えられます。 +エージェントは、 instructions、 tools、 ハンドオフ を備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、 LLM は自律的に計画を立て、ツールを使って行動したりデータを取得したりし、ハンドオフ によってサブエージェントにタスクを委譲できます。例えば、リサーチ用のエージェントには次のようなツールを備えることができます。 -- Web 検索でオンライン情報を見つける -- ファイル検索と取得で独自データや接続を横断的に検索する -- コンピュータ操作でコンピュータ上のアクションを実行する -- コード実行でデータ分析を行う -- 計画立案、レポート作成などに長けた特化エージェントへのハンドオフ +- Web 検索でオンラインの情報を見つける +- ファイル検索と取得で独自データや接続を横断して検索する +- コンピュータ操作 でコンピュータ上のアクションを実行する +- コード実行 でデータ分析を行う +- 計画立案やレポート作成などが得意な特化エージェントへの ハンドオフ -このパターンはタスクがオープンエンドで、LLM の知性に頼りたい場合に有効です。重要なポイントは次のとおりです。 +このパターンは、タスクがオープンエンドで、 LLM の知性に依拠したい場合に有効です。ここで重要なポイントは次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、どのパラメーターの範囲で動作すべきかを明確にする -2. アプリを監視して反復する。どこで問題が起きるかを観察し、プロンプトを改善する -3. エージェントに内省と改善を許可する。例えばループで実行し自己批評させる、あるいはエラーメッセージを与えて改善させる -4. 何でもこなす汎用エージェントではなく、特定の 1 つのタスクに秀でた特化エージェントを用意する -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスク遂行能力を高められる +1. 良いプロンプトを作り込みましょう。利用可能な tools、使い方、そして動作させるべきパラメーターの範囲を明確にします。 +2. アプリを監視し、継続的に改善しましょう。どこで問題が起きるかを見極め、プロンプトを反復改善します。 +3. エージェントが自己内省して改善できるようにしましょう。例えば、ループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させるなどです。 +4. 何でもこなす汎用エージェントにするのではなく、1 つのタスクに特化して卓越したエージェントを用意しましょう。 +5. [評価 ( evals )](https://platform.openai.com/docs/guides/evals) に投資しましょう。これによりエージェントを訓練し、タスクの熟達度を高められます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・性能の観点でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、スピード、コスト、性能の観点でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。例えば、エージェントにタスクをいくつかの カテゴリー に分類させ、カテゴリー に応じて次のエージェントを選ぶ -- あるエージェントの出力を次のエージェントの入力へと変換して連鎖させる。例えばブログ記事作成タスクを、調査、アウトライン作成、本文執筆、批評、改善といった一連のステップに分割する -- タスクを実行するエージェントと、その結果を評価してフィードバックするエージェントを `while` ループで回し、評価者が出力が一定の基準を満たしたと判断するまで繰り返す -- 複数のエージェントを並列に実行する。例えば、 JavaScript の基本コンポーネントである `Promise.all` などを用いる。相互依存しない複数タスクがある場合に速度面で有効 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。例えば、エージェントにタスクをいくつかの カテゴリー に分類させ、カテゴリー に基づいて次のエージェントを選ぶことができます。 +- あるエージェントの出力を次のエージェントの入力に変換して、複数のエージェントを連鎖させる。例えば、ブログ記事の作成を、リサーチ、アウトライン作成、本文執筆、批評、改善という一連のステップに分解できます。 +- 実行役のエージェントと、評価・フィードバックを行うエージェントを組み合わせ、評価者が出力が一定の基準を満たしたと判断するまで、`while` ループで実行する。 +- 複数のエージェントを並列実行する。例えば、`Promise.all` のような JavaScript の基本コンポーネント ( primitives ) を利用する方法は、互いに依存しない複数タスクがあるときにスピード面で有効です。 -`examples/agent-patterns` に複数の code examples があります。 +[`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 e552f861..3ddc6d16 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 @@ -25,20 +25,20 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm install @openai/agents 'zod@<=3.25.67' ``` -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('')` を使用できます。 + また、プログラムからキーを設定するには `setDefaultOpenAIKey('')` を呼び出し、トレーシングには `setTracingExportApiKey('')` を使用できます。 詳しくは [SDK の設定](/openai-agents-js/ja/guides/config) を参照してください。 -## 最初のエージェントの作成 +## はじめてのエージェントの作成 -エージェントは instructions と名前で定義します。 +エージェントは instructions と name で定義します。 ```typescript import { Agent } from '@openai/agents'; @@ -50,11 +50,11 @@ const agent = new Agent({ }); ``` -## 最初のエージェントの実行 +## はじめてのエージェントの実行 -エージェントの実行には `run` メソッドを使用します。開始したいエージェントと渡したい入力の両方を指定して、実行をトリガーします。 +エージェントの実行には `run` メソッドを使用します。開始したいエージェントと渡したい入力の両方を指定すると、実行が開始されます。 -これにより、その実行の最終出力と実行されたあらゆるアクションを含む実行結果が返されます。 +これにより、最終出力と、その実行中に行われたあらゆるアクションを含む実行結果が返されます。 ```typescript import { Agent, run } from '@openai/agents'; @@ -70,9 +70,9 @@ const result = await run(agent, 'When did sharks first appear?'); console.log(result.finalOutput); ``` -## エージェントへのツール付与 +## エージェントへの tools の付与 -情報の検索やアクションの実行に使えるツールをエージェントに与えられます。 +情報の検索やアクションの実行に使える tools をエージェントに与えることができます。 ```typescript import { Agent, tool } from '@openai/agents'; @@ -99,9 +99,9 @@ const agent = new Agent({ }); ``` -## いくつかのエージェントの追加 +## エージェントの追加 -追加のエージェントを同様に定義することで、問題を小さく分割し、手元のタスクにより集中させられます。また、エージェントごとにモデルを定義することで、課題に応じて異なるモデルを使い分けられます。 +追加のエージェントも同様に定義でき、問題を小さな部分に分割して、エージェントを目の前のタスクにより集中させられます。また、エージェントごとに model を指定することで、課題ごとに異なるモデルを使うこともできます。 ```typescript const historyTutorAgent = new Agent({ @@ -119,23 +119,13 @@ const mathTutorAgent = new Agent({ ## ハンドオフの定義 -複数のエージェント間をオーケストレーションするために、エージェントに対して `handoffs` を定義できます。これにより、エージェントは会話を次のエージェントへ引き継げます。これは実行の過程で自動的に行われます。 +複数のエージェント間をオーケストレーションするために、エージェントに対して `handoffs` を定義できます。これにより、エージェントは会話を次のエージェントに引き継げます。これは実行の過程で自動的に行われます。 -```typescript -// Using the Agent.create method to ensures type safety for the final output -const triageAgent = Agent.create({ - name: 'Triage Agent', - instructions: - "You determine which agent to use based on the user's homework question", - handoffs: [historyTutorAgent, mathTutorAgent], -}); -``` - -実行後、実行結果の `finalAgent` プロパティを見ることで、どのエージェントが最終応答を生成したかを確認できます。 +実行後、実行結果の `finalAgent` プロパティを確認すると、最終応答を生成したエージェントが分かります。 -## エージェントのオーケストレーションの実行 +## エージェントオーケストレーションの実行 -Runner は、個々のエージェントの実行、必要に応じたハンドオフ、およびツールの実行を処理します。 +Runner は、各エージェントの実行、必要になり得るハンドオフ、およびツールの実行を処理します。 ```typescript import { run } from '@openai/agents'; @@ -148,22 +138,22 @@ 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 ビューアー](https://platform.openai.com/traces) にアクセスしてください。 ## 次のステップ -より複雑なエージェント フローの構築方法を学びましょう: +より複雑なエージェントフローの構築方法を学びましょう。 - [エージェント](/openai-agents-js/ja/guides/agents) の設定について学ぶ - [エージェントの実行](/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-js/ja/guides/tools)、 [ガードレール](/openai-agents-js/ja/guides/guardrails)、および [モデル](/openai-agents-js/ja/guides/models) について学ぶ diff --git a/docs/src/content/docs/ja/guides/release.mdx b/docs/src/content/docs/ja/guides/release.mdx index 50d33c01..241ba4ac 100644 --- a/docs/src/content/docs/ja/guides/release.mdx +++ b/docs/src/content/docs/ja/guides/release.mdx @@ -3,32 +3,32 @@ title: リリースプロセス description: Learn how we version and release the SDK and recent changes. --- -## バージョニング +## バージョン管理 -このプロジェクトは、セマンティック バージョニングをやや変更した `0.Y.Z` 形式に従います。先頭の `0` は、この SDK がまだ急速に進化していることを示します。各コンポーネントの増分は次のとおりです: +このプロジェクトは、`0.Y.Z` という形式のセマンティックバージョニングに軽微な変更を加えた方式に従います。先頭の `0` は、 SDK がまだ急速に進化していることを示します。各コンポーネントは次のように増やします: -## マイナー (`Y`) バージョン +## マイナー（`Y`）バージョン -ベータとしてマークされていない任意のパブリック インターフェースに対する破壊的変更がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への変更には破壊的変更が含まれる場合があります。 +ベータとしてマークされていない公開インターフェースに対する **破壊的変更** において、マイナーバージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への移行には破壊的変更が含まれる場合があります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。 +破壊的変更を避けたい場合は、プロジェクトのバージョンを `0.0.x` に固定することをおすすめします。 -## パッチ (`Z`) バージョン +## パッチ（`Z`）バージョン -破壊的ではない変更には `Z` を増やします: +互換性を壊さない変更では、`Z` を上げます: - バグ修正 - 新機能 -- プライベート インターフェースへの変更 +- 非公開インターフェースの変更 - ベータ機能の更新 -## サブパッケージのバージョニング +## サブパッケージのバージョン管理 -メインの `@openai/agents` パッケージは、独立して使用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、どれか 1 つのパッケージでバージョンが上がると、他も同様に上がります。`1.0.0` への移行に伴い、この方針を変更する可能性があります。 +メインの `@openai/agents` パッケージは、個別に使用できる複数のサブパッケージで構成されています。現時点では、各パッケージのバージョンは連動しており、どれか 1 つのパッケージがバージョンアップすると、他も同様に上がります。`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 5fba9faf..8d9d6f64 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -9,36 +9,36 @@ 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) も参照してください +- [`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) も参照してください。 ## 最終出力 -`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が入ります。結果は次のいずれかです: +`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.output` — エージェント全体の実行の出力を含みます `history` は、チャットのようなユースケースで完全な履歴を維持するのに便利です: @@ -46,44 +46,44 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? ## 最後のエージェント -`lastAgent` プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、次回 ユーザー が何かを入力するときに役立つことがよくあります。たとえば、フロントラインのトリアージ エージェントが言語別エージェントに ハンドオフ する場合、最後のエージェントを保存しておき、次回 ユーザー がメッセージを送ったときに再利用できます。 +`lastAgent` プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、これはユーザーが次に入力するときに役立ちます。たとえば、言語別のエージェントにハンドオフする一次トリアージ エージェントがある場合、最後のエージェントを保存し、ユーザーが次にエージェントにメッセージを送るときに再利用できます。 -ストリーミングモードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスするのも有用です。 +ストリーミング モードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスすることも有用です。 -## 新しいアイテム +## 新規アイテム -`newItems` プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。実行アイテムは、 LLM が生成した元のアイテムをラップします。これらを使うと、 LLM の出力に加えて、どのエージェントに紐づくイベントかにもアクセスできます。 +`newItems` プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。ラン アイテムは、 LLM が生成した元のアイテムをラップします。これらを使うと、 LLM の出力に加えて、これらのイベントがどのエージェントに関連付けられていたかにもアクセスできます。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元のアイテムは生成されたメッセージです -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は、 LLM が ハンドオフ ツールを呼び出したことを示します。元のアイテムは LLM からのツール呼び出しアイテムです -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) は、ハンドオフが発生したことを示します。元のアイテムはハンドオフ ツール呼び出しへのツールレスポンスです。アイテムから送信元/送信先のエージェントにもアクセスできます +- [`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) は、ツールが呼び出されたことを示します。元のアイテムはツールのレスポンスです。アイテムからツール出力にもアクセスできます +- [`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` 呼び出しの入力としても使用できます。詳しくは [recover from an error](/openai-agents-js/ja/guides/running-agents#exceptions) を参照してください。 -## 中断 +## 割り込み -エージェントで `needsApproval` を使用している場合、継続する前に処理が必要な `interruptions` がトリガーされることがあります。この場合、`interruptions` は中断を引き起こした `ToolApprovalItem` の配列になります。中断への対処方法については、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) を参照してください。 +エージェントで `needsApproval` を使用している場合、`run` の途中で続行前に対処が必要な `interruptions` が発生することがあります。その場合、`interruptions` には割り込みを引き起こした `ToolApprovalItem` の配列が入ります。割り込みの扱い方については、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) を参照してください。 ## その他の情報 -### 元のレスポンス +### 元の応答 -`rawResponses` プロパティには、エージェントの実行中にモデルが生成した 元 の LLM レスポンスが含まれます。 +`rawResponses` プロパティには、エージェントの実行中にモデルが生成した LLM の元の応答が含まれます。 ### 最後のレスポンス ID -`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 367f9868..69ce9e2e 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -9,13 +9,13 @@ 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` インスタンスで実行します。 -または、自分で runner インスタンスを作成することもできます: +または、独自の Runner インスタンスを作成できます: LLM - の出力が「最終出力」と見なされる条件は、目的の型でテキスト出力を生成し、ツール呼び出しが存在しないことです。 + 出力を「最終出力」と見なす条件は、望ましい型のテキスト出力を生成し、かつツール呼び出しが + 1 つもないことです。 ### Runner のライフサイクル -アプリの起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダやトレーシングのオプションといったグローバル設定を保持します。完全に別のセットアップが必要な場合にのみ別の `Runner` を作成してください。簡単なスクリプトでは、内部でデフォルトの runner を使う `run()` を呼ぶこともできます。 +アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシングオプションなどのグローバル設定を保持します。まったく異なる構成が必要な場合のみ別の `Runner` を作成してください。簡単なスクリプトでは、内部でデフォルト Runner を使う `run()` を呼び出しても構いません。 ## 実行引数 -`run()` メソッドには、実行を開始する初期エージェント、実行用の入力、一連のオプションを渡します。 +`run()` メソッドへの入力は、実行を開始する初期エージェント、実行の入力、および各種オプションです。 -入力は、文字列（ユーザーのメッセージとして扱われます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は `RunState` オブジェクトのいずれかです。 +入力は、文字列（ユーザーのメッセージとして扱われます）、[入力アイテム](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 -追加のオプションは次のとおりです: +追加オプションは次のとおりです: -| オプション | デフォルト | 説明 | -| ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着したイベントを逐次発行します | -| `context` | – | すべてのツール / ガードレール / ハンドオフに転送される Context オブジェクト。詳しくは [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 | -| `maxTurns` | `10` | セーフティリミット — 到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスロー | -| `signal` | – | キャンセル用の `AbortSignal` | +| オプション | 既定値 | 説明 | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着したイベントを逐次発行します | +| `context` | – | すべてのツール / ガードレール / ハンドオフに転送されるコンテキストオブジェクト。詳しくは [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 | +| `maxTurns` | `10` | セーフティ上限。到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローします | +| `signal` | – | 取り消し用の `AbortSignal` | ## ストリーミング -ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリームが開始されると、`StreamedRunResult` に新しい出力を含む実行の完全な情報が含まれます。`for await` ループでストリーミングイベントを反復処理できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 +ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリームが開始されると、`StreamedRunResult` には実行に関する完全な情報（新しく生成されたすべての出力を含む）が含まれます。`for await` ループでストリーミングイベントを反復処理できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 ## 実行設定 -独自の `Runner` インスタンスを作成する場合、`RunConfig` オブジェクトを渡して runner を設定できます。 - -| フィールド | 型 | 目的 | -| --------------------------- | --------------------- | ------------------------------------------------------------------------------------ | -| `model` | `string \| Model` | 実行中の **すべて** のエージェントに対して特定のモデルを強制します | -| `modelProvider` | `ModelProvider` | モデル名を解決します — 既定は OpenAI プロバイダです | -| `modelSettings` | `ModelSettings` | 各エージェントの設定を上書きするグローバルな調整パラメーター | -| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ を実行する際に入力アイテムを変更します（ハンドオフ 自体で定義がない場合） | -| `inputGuardrails` | `InputGuardrail[]` | _最初_ の ユーザー入力に適用される ガードレール | -| `outputGuardrails` | `OutputGuardrail[]` | _最終_ 出力に適用される ガードレール | -| `tracingDisabled` | `boolean` | OpenAI Tracing を完全に無効化します | -| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、トレースから LLM/ツール の入力と出力を除外します | -| `workflowName` | `string` | Traces ダッシュボードに表示 — 関連する実行のグループ化に役立ちます | -| `traceId` / `groupId` | `string` | SDK による自動生成ではなく、トレースまたはグループ ID を手動で指定します | -| `traceMetadata` | `Record` | 各スパンに付与する任意のメタデータ | +独自の `Runner` インスタンスを作成する場合は、`RunConfig` オブジェクトを渡して Runner を構成できます。 + +| 項目 | 型 | 目的 | +| --------------------------- | --------------------- | --------------------------------------------------------------------------- | +| `model` | `string \| Model` | 実行中のすべてのエージェントに特定のモデルを強制します | +| `modelProvider` | `ModelProvider` | モデル名を解決します。既定は OpenAI プロバイダーです | +| `modelSettings` | `ModelSettings` | 各エージェントの設定を上書きするグローバルなチューニングパラメーター | +| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ時に入力アイテムを変換します（ハンドオフ自体で未定義の場合） | +| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | +| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | +| `tracingDisabled` | `boolean` | OpenAI Tracing を完全に無効化します | +| `traceIncludeSensitiveData` | `boolean` | トレースから LLM/ツールの入力と出力を除外しつつ、スパンは引き続き発行します | +| `workflowName` | `string` | Traces ダッシュボードに表示され、関連する実行をまとめるのに役立ちます | +| `traceId` / `groupId` | `string` | SDK に生成させず、トレース ID またはグループ ID を手動で指定します | +| `traceMetadata` | `Record` | すべてのスパンに付与する任意のメタデータ | ## 会話 / チャットスレッド -`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における 1 回の **ターン** を表します。エンドユーザーに `RunResult` のどこまでを見せるかは任意です — `finalOutput` のみを見せる場合もあれば、生成されたアイテムをすべて見せる場合もあります。 +`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における 1 回のターンを表します。エンドユーザーに `RunResult` のどこまでを見せるかは任意です。`finalOutput` だけの場合もあれば、生成されたすべてのアイテムを見せる場合もあります。 -インタラクティブ版は [チャットのサンプルコード](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 +インタラクティブな版は [チャットのサンプルコード](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 ## 例外 -この SDK は、捕捉可能な少数のエラーをスローします: +この SDK は捕捉可能な少数のエラーをスローします: - [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` に到達 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが無効な出力を生成（例: 不正な形式の JSON、未知のツール） +- [`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) – 設定やユーザー入力に基づき発生したエラー +- [`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` プロパティを提供する場合があります。 -`GuardrailExecutionError` を処理するサンプルコードは次のとおりです: +以下は `GuardrailExecutionError` を処理するサンプルコードです: -上記の例を実行すると、次の出力が表示されます: +上の例を実行すると、次の出力が表示されます: ``` Guardrail execution failed: Error: Input guardrail failed to complete: Error: Something is wrong! @@ -124,6 +125,6 @@ Math homework guardrail tripped ## 次のステップ -- [モデル](/openai-agents-js/ja/guides/models) の設定方法を学びます -- エージェントに [ツール](/openai-agents-js/ja/guides/tools) を提供します -- 本番対応のために [ガードレール](/openai-agents-js/ja/guides/guardrails) または [トレーシング](/openai-agents-js/ja/guides/tracing) を追加します +- [モデル](/openai-agents-js/ja/guides/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 e4da5b27..ac2766e0 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 は、実行および未完了のコールバックがすべて完了すると解決されます。これ以上出力がないことを確実にするには必ず await してください。 +実行と未処理のコールバックがすべて完了すると、`stream.completed` の Promise が解決されます。出力がもうないことを確実にしたい場合は、必ずこれを await してください。 -### すべてのイベントの受信 +### すべてのイベントの監視 -`for await` ループを使うと、到着した各イベントを検査できます。有用な情報として、低レベルのモデルイベント、エージェントの切り替え、そして SDK 固有の実行情報などがあります: +`for await` ループを使って、到着した各イベントを検査できます。便利な情報としては、低レベルのモデルイベント、エージェントの切り替え、そして SDK 固有の実行情報などがあります: -両方、つまりプレーンテキストのストリームと raw イベントストリームを出力する完全なスクリプトについては、[ストリーミングのサンプルコード](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。 +プレーンテキストのストリームと 元 のイベントストリームの両方を出力する、完成したスクリプトについては [ストリーミングのサンプルコード](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。 ## イベントタイプ -ストリームは 3 種類のイベントタイプを返します: +このストリームは 3 種類のイベントタイプを生成します: ### raw_model_stream_event @@ -118,23 +118,22 @@ 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) です。 +ユーザー と対話する、より充実した例としては [`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 7ccdc6b8..17add625 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,107 +10,115 @@ 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. OpenAI がホストするツール – モデルと同じ OpenAI サーバー上で動作します。_(Web 検索、ファイル検索、コンピュータ操作、code interpreter、画像生成)_ +2. 関数ツール – 任意のローカル関数を JSON スキーマでラップして LLM が呼び出せるようにします +3. ツールとしての エージェント – エージェント全体を呼び出し可能なツールとして公開します +4. ローカル MCP サーバー – マシン上で動作する Model Context Protocol サーバーを接続します --- ## 1. 組み込みツール（Hosted） -`OpenAIResponsesModel` を使用する場合、次の組み込みツールを追加できます: +`OpenAIResponsesModel` を使うと、次の組み込みツールを追加できます: -| ツール | タイプ文字列 | 目的 | -| --------------------------- | -------------------- | ------------------------------------------ | -| Web 検索 | `'web_search'` | インターネット検索 | -| ファイル / リトリーバル検索 | `'file_search'` | OpenAIがホストする ベクトルストア をクエリ | -| コンピュータ操作 | `'computer'` | GUI の操作を自動化 | -| Code Interpreter | `'code_interpreter'` | サンドボックス化された環境でコードを実行 | -| 画像生成 | `'image_generation'` | テキストに基づいて画像を生成 | +| ツール | Type string | 目的 | +| ----------------------- | -------------------- | ------------------------------------------- | +| 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. 関数ツール -`tool()` ヘルパーを使うと、任意の関数をツールにできます。 +`tool()` ヘルパーで任意の関数をツールにできます。 ### オプションリファレンス -| フィールド | 必須 | 説明 | -| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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` | +| 項目 | 必須 | 説明 | +| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `name` | いいえ | 関数名が既定値になります（例: `get_weather`） | +| `description` | はい | LLM に表示される、わかりやすい人間向けの説明 | +| `parameters` | はい | Zod スキーマ、または 元 の JSON スキーマオブジェクトのいずれか。Zod のパラメーターを使うと **strict** モードが自動的に有効になります | +| `strict` | いいえ | `true`（既定）で、引数が検証に失敗した場合は SDK が model エラーを返します。曖昧一致にしたい場合は `false` にします | +| `execute` | はい | `(args, context) => string \| Promise` – ビジネスロジック。2 番目の引数は省略可能で、`RunContext` です | +| `errorFunction` | いいえ | 内部エラーをユーザーに見える文字列へ変換するためのカスタムハンドラー `(context, error) => string` | -### 非 strict な JSON スキーマ ツール +### 非 strict JSON スキーマのツール -無効または不完全な入力をモデルに推測させたい場合は、raw JSON スキーマ使用時に strict モードを無効化できます: +モデルに無効または不完全な入力を推測させたい場合は、元 の JSON スキーマを使う際に strict モードを無効化できます: --- -## 3. エージェントをツールとして +## 3. ツールとしてのエージェント -会話を完全にハンドオフせずに、ある エージェント に別の エージェント を支援させたい場合があります。`agent.asTool()` を使用します: +会話を完全にハンドオフすることなく、ある エージェント が別の エージェント を支援してほしい場合があります。`agent.asTool()` を使います: - + -内部的に SDK は次を行います: +内部的には SDK は次を行います: -- 単一の `input` パラメーターをもつ関数ツールを作成 +- 単一の `input` パラメーターを持つ関数ツールを作成 - ツールが呼び出されたときに、その入力でサブエージェントを実行 -- 最後のメッセージ、または `customOutputExtractor` で抽出された出力を返却 +- 最後のメッセージ、または `customOutputExtractor` で抽出した出力を返却 --- ## 4. ローカル MCP サーバー -ローカルの [Model Context Protocol](https://modelcontextprotocol.io/) サーバーを通じてツールを公開し、エージェントにアタッチできます。`MCPServerStdio` を使ってサーバーを起動して接続します: +ローカルの [Model Context Protocol](https://modelcontextprotocol.io/) サーバー経由でツールを公開し、エージェントに接続できます。`MCPServerStdio` を使ってサーバーを起動・接続します: - + 完全な code examples は [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) を参照してください。 --- -## ツール使用の挙動 +## ツール使用時の挙動 -モデルがいつどのようにツールを必ず使用すべきかを制御する方法については、[エージェント](/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 しない -- **ツールは単一責務** — 小さく合成可能なツールはモデルの推論を改善 +- **短く明確な説明** – ツールが何をするか、いつ使うかを記述 +- **入力の検証** – 可能であれば Zod スキーマで厳密な JSON 検証を実施 +- **エラーハンドラーで副作用を避ける** – `errorFunction` は例外を投げず、有用な文字列を返す +- **ツールごとに責務は 1 つ** – 小さく合成しやすいツールのほうがモデルの推論が良くなる --- ## 次のステップ - [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) について学ぶ -- ツールの入力または出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 -- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種 組み込みツール（Hosted）の型について TypeDoc リファレンスを参照 +- ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 +- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種の 組み込みツール（Hosted）タイプの TypeDoc リファレンスを読む diff --git a/docs/src/content/docs/ja/guides/tracing.mdx b/docs/src/content/docs/ja/guides/tracing.mdx index 18db1854..7431d7f4 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 ダッシュボード](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 の場合、このトレースは記録されません -- `metadata`: トレースの任意のメタデータ -- **スパン** は開始時刻と終了時刻を持つ処理を表します。スパンには以下があります: +- **トレース** は「ワークフロー」の単一のエンドツーエンドの処理を表します。これはスパンで構成されます。トレースには次のプロパティがあります: +- `workflow_name`: 論理的なワークフローやアプリ名です。例: "Code generation" や "Customer service" +- `trace_id`: トレースの一意な ID。指定しない場合は自動生成。形式は `trace_<32_alphanumeric>` である必要があります +- `group_id`: 同一の会話に属する複数のトレースを紐づけるためのオプションのグループ ID。たとえばチャットスレッドの ID を使えます +- `disabled`: True の場合、トレースは記録されません +- `metadata`: トレース用の任意のメタデータ +- **スパン** は開始時刻と終了時刻を持つ処理を表します。スパンには次の情報があります: - `started_at` と `ended_at` のタイムスタンプ - 所属するトレースを表す `trace_id` -- このスパンの親スパン（あれば）を指す `parent_id` -- スパンに関する情報である `span_data`。たとえば `AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報などを含みます +- 親スパンを指す `parent_id`（ある場合） +- スパンに関する情報である `span_data`。たとえば `AgentSpanData` にはエージェントの情報、`GenerationSpanData` には LLM 生成に関する情報などが含まれます ## 既定のトレーシング -既定では、SDK は以下をトレースします: +デフォルトでは、SDK は次をトレースします: - 全体の `run()` または `Runner.run()` は `Trace` でラップされます -- エージェントが実行されるたびに `AgentSpan` でラップされます +- エージェントの実行ごとに `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 側で自動的に行われます。 +`RealtimeAgent` と `RealtimeSession` をデフォルトの OpenAI Realtime API と併用している場合、`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()` でラップします。 @@ -77,34 +77,34 @@ Agents SDK には組み込みのトレーシングが含まれており、エー ## トレースの作成 -[`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 のバックエンドにバッチでエクスポートします +- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレースの作成を担い、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) 経由でアクセスできます +- `TraceProvider` は [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) で構成され、トレース/スパンをバッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に送ります。エクスポーターは OpenAI バックエンドへバッチでスパンとトレースを送信します -この既定のセットアップをカスタマイズして、別のバックエンドに送信したり、追加の送信先に送ったり、エクスポーターの動作を変更するには、次の 2 つの方法があります: +この既定の構成をカスタマイズして、別または追加のバックエンドへトレースを送信したり、エクスポーターの動作を変更したりするには、次の 2 つの方法があります: -1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) は、トレースとスパンが準備できたタイミングで受け取る、追加のトレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて、独自の処理を行えます -2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) は、既定のプロセッサーを独自のトレースプロセッサーで置き換えられます。つまり、OpenAI のバックエンドにトレースを送信する `TracingProcessor` を含めない限り、トレースは OpenAI のバックエンドに送信されません +1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) は、トレースとスパンが準備できた段階で受け取る **追加** のトレースプロセッサーを追加できます。これにより、OpenAI のバックエンドに送るのに加えて、独自の処理を行えます +2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) は、既定のプロセッサーを独自のトレースプロセッサーに **置き換え** られます。つまり、OpenAI バックエンドへは、そうする `TracingProcessor` を含めない限りトレースは送られません ## 外部トレーシングプロセッサー一覧 diff --git a/docs/src/content/docs/ja/guides/troubleshooting.mdx b/docs/src/content/docs/ja/guides/troubleshooting.mdx index 80cca5c9..3f9e1fac 100644 --- a/docs/src/content/docs/ja/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ja/guides/troubleshooting.mdx @@ -3,38 +3,38 @@ title: トラブルシューティング description: Learn how to troubleshoot issues with the OpenAI Agents SDK. --- -## サポート環境 +## サポートされている環境 -OpenAI Agents SDK は、以下のサーバー環境でサポートされています: +OpenAI Agents SDK は次のサーバー環境でサポートされます: - Node.js 22+ - Deno 2.35+ - Bun 1.2.5+ -### 限定サポート +### 制限付きサポート -- ** Cloudflare Workers ** : Agents SDK は Cloudflare Workers でも利用できますが、現在いくつかの制限があります: - - 現在 SDK では `nodejs_compat` の有効化が必要です - - リクエストの終了時にトレースを手動でフラッシュする必要があります。詳細は [トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください - - Cloudflare Workers における `AsyncLocalStorage` のサポートが限定的なため、一部のトレースが正確でない可能性があります -- ** ブラウザ ** : - - ブラウザでは現在トレーシングはサポートされていません -- ** v8 isolates ** : - - 適切なブラウザ用ポリフィルを含むバンドラを使えば v8 isolates 向けに SDK をバンドルできるはずですが、トレーシングは動作しません - - v8 isolates については十分なテストを行っていません +- **Cloudflare Workers**: Agents SDK は Cloudflare Workers で使用できますが、現時点ではいくつかの制限があります: + - 現状、この SDK では `nodejs_compat` を有効にする必要があります + - リクエストの最後にトレースを手動でフラッシュする必要があります。詳細は [トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください + - Cloudflare Workers の `AsyncLocalStorage` サポートが限定的なため、一部のトレースが正確でない場合があります +- **ブラウザ**: + - 現在、ブラウザではトレーシングはサポートされていません +- **v8 アイソレート**: + - 適切なブラウザポリフィルを備えたバンドラを使えば v8 アイソレート向けに SDK をバンドルできるはずですが、トレーシングは機能しません + - v8 アイソレートは十分な検証が行われていません ## デバッグログ -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 3fb26eee..004a7554 100644 --- a/docs/src/content/docs/ja/guides/voice-agents.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents.mdx @@ -25,27 +25,27 @@ import thinClientExample from '../../../../../../examples/docs/voice-agents/thin ![Realtime Agents](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) -音声エージェントは、 OpenAI の音声から音声へのモデルを使用してリアルタイム音声チャットを提供します。これらのモデルは、音声のストリーミング、テキスト、およびツール呼び出しをサポートし、音声/電話によるカスタマーサポート、モバイルアプリでの体験、音声チャットなどのアプリケーションに最適です。 +音声エージェントは、 OpenAI の speech-to-speech モデルを使用してリアルタイムの音声チャットを提供します。これらのモデルは、ストリーミング音声、テキスト、ツール呼び出しをサポートし、音声/電話によるカスタマーサポート、モバイルアプリでの体験、音声チャットといった用途に最適です。 Voice Agents SDK は、[OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) 向けの TypeScript クライアントを提供します。 ### 主な機能 -- WebSocket または WebRTC 経由で接続 -- ブラウザとバックエンド接続の両方で利用可能 -- 音声と割り込みの処理 +- WebSocket または WebRTC で接続 +- ブラウザおよびバックエンド接続の両方で利用可能 +- 音声および割り込み処理 - ハンドオフによるマルチエージェントのオーケストレーション - ツールの定義と呼び出し -- モデル出力の監視のためのカスタム ガードレール +- モデル出力を監視するためのカスタム ガードレール - ストリーミング イベントのコールバック - テキストと音声のエージェントの両方で同じコンポーネントを再利用 -音声から音声へのモデルを使用すると、モデルが動作した後にテキストを文字起こしして再度音声へ変換する必要がなく、モデルのリアルタイムな音声処理能力を活用できます。 +speech-to-speech モデルを使うことで、モデルが動作した後に音声を書き起こしてテキストを再度音声に変換し直す必要がなく、リアルタイムで音声を処理するモデルの能力を活用できます。 -![音声から音声へのモデル](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) +![Speech-to-speech モデル](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 6f4d6469..9f2a4156 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/build.mdx @@ -30,135 +30,136 @@ import turnDetectionExample from '../../../../../../../examples/docs/voice-agent ## 音声の取り扱い -デフォルトの `OpenAIRealtimeWebRTC` のような一部のトランスポート層は、音声の入力と出力を自動で処理します。`OpenAIRealtimeWebSocket` のようなその他のトランスポート メカニズムでは、セッション音声を自分で処理する必要があります: +デフォルトの `OpenAIRealtimeWebRTC` のような一部のトランスポート層は、音声の入出力を自動的に処理します。`OpenAIRealtimeWebSocket` のような他のトランスポート機構では、セッションの音声を自分で扱う必要があります: -## セッションの設定 +## セッション設定 -セッションは、構築時に [`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) に追加のオプションを渡すか、`connect(...)` を呼び出すときに構成できます。 +[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) の構築時、または `connect(...)` を呼び出すときに追加オプションを渡すことで、セッションを設定できます。 -これらのトランスポート層では、[セッション](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` を変更することはできません。また、接続できるのは他の リアルタイムエージェント のみです。別のモデル、たとえば `o4-mini` のような推論モデルを使用する必要がある場合は、[ツールによる委譲](#delegation-through-tools) を使用できます。 +さらに、ハンドオフの一環として `voice` や `model` を変更することはできません。また、接続できるのは他の Realtime Agents のみです。別のモデル、たとえば `o4-mini` のような推論モデルを使用する必要がある場合は、[ツールによる委譲](#delegation-through-tools) を使用できます。 ## ツール -通常の エージェント と同様に、リアルタイムエージェント はアクションを実行するためにツールを呼び出せます。通常の エージェント で使用するのと同じ `tool()` 関数でツールを定義できます。 +通常のエージェントと同様に、Realtime Agents はツールを呼び出してアクションを実行できます。通常のエージェントで使用するのと同じ `tool()` 関数でツールを定義できます。 -リアルタイムエージェント で使えるのは 関数ツール のみで、これらのツールは リアルタイム セッション と同じ場所で実行されます。つまり、ブラウザで リアルタイム セッション を実行している場合、ツールもブラウザで実行されます。よりセンシティブな処理が必要な場合は、ツール内からバックエンド サーバー へ HTTP リクエストを行ってください。 +Realtime Agents で使用できるのは関数ツールのみで、これらのツールは Realtime セッション と同じ場所で実行されます。つまり、Realtime セッション をブラウザで実行している場合、ツールもブラウザで実行されます。より機微な処理が必要な場合は、ツール内からバックエンド サーバー への HTTP リクエストを行ってください。 -ツールの実行中、エージェント は ユーザー からの新しいリクエストを処理できません。体験を向上させる 1 つの方法は、ツールを実行しようとしていることを事前に エージェント に告げさせる、または特定のフレーズを話させてツール実行のための時間を稼がせることです。 +ツールの実行中、エージェント は新しい ユーザー リクエストを処理できません。体験を改善する 1 つの方法は、ツールの実行直前にアナウンスさせたり、ツールの実行時間を稼ぐための特定のフレーズを話すようにエージェントに指示することです。 ### 会話履歴へのアクセス -エージェント が特定のツールを呼び出す際に渡した引数に加えて、リアルタイム セッション が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[委譲のためのツール](#delegation-through-tools) を使う予定がある場合に役立ちます。 +エージェントが特定のツールを呼び出す際の引数に加えて、Realtime セッション が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[ツールによる委譲](#delegation-through-tools) を利用する予定がある場合に役立ちます。 ### ツール実行前の承認 ツールを `needsApproval: true` で定義すると、エージェント はツールを実行する前に `tool_approval_requested` イベントを発行します。 -このイベントをリッスンすることで、ツール呼び出しを承認または拒否するための UI を ユーザー に表示できます。 +このイベントを監視することで、ツール呼び出しの承認または拒否を ユーザー に求める UI を表示できます。 ## ガードレール -ガードレール は、エージェント の発話が一連のルールに違反していないかを監視し、違反していれば即座に応答を打ち切る手段を提供します。これらの ガードレール チェックは、エージェント の応答の書き起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効です）。 +ガードレールは、エージェントの発話が一連のルールに違反していないかを監視し、違反した場合に応答を即時に打ち切る手段を提供します。これらのガードレールのチェックはエージェントの応答の書き起こしに基づいて行われるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効）。 -提供した ガードレール は、モデルの応答が返ってくるのに合わせて非同期に実行され、たとえば「特定の禁止ワードに言及した」など事前に定義した分類トリガーに基づいて応答を打ち切れます。 +提供したガードレールは、モデルの応答が返ってくるのに合わせて非同期に実行され、たとえば「特定の禁止語を言及した」など、あらかじめ定義した分類トリガーに基づいて応答を打ち切れるようにします。 -ガードレール が作動すると、セッションは `guardrail_tripped` イベントを発行します。イベントには、ガードレール を作動させた `itemId` を含む `details` オブジェクトも含まれます。 +ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。このイベントには、ガードレールをトリガーした `itemId` を含む `details` オブジェクトも提供されます。 -デフォルトでは ガードレール は 100 文字ごと、または応答テキストの生成が終わった時点で実行されます。音声で話すほうが通常は時間がかかるため、ほとんどの場合 ユーザー がそれを聞く前に ガードレール が違反を検知できます。 +デフォルトでは、ガードレールは 100 文字ごと、またはレスポンスのテキストが生成し終わった時点で実行されます。テキストを話し終える方が通常は時間がかかるため、ほとんどの場合、ユーザーが聞く前にガードレールが違反を検知できます。 -この動作を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡します。 +この挙動を変更したい場合は、セッションに `outputGuardrailSettings` オブジェクトを渡してください。 ## ターン検出 / 音声活動検出 -リアルタイム セッション は、ビルトインの [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使って ユーザー が話しているタイミングを自動検出し、新しいターンをトリガーします。 +Realtime セッション は、ユーザーが話し始めたことを自動検出し、組み込みの[Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad)を使って新しいターンを開始します。 -音声活動検出モードは、`turnDetection` オブジェクトをセッションに渡すことで変更できます。 +セッションに `turnDetection` オブジェクトを渡すことで、音声活動検出モードを変更できます。 -ターン検出の設定を調整すると、不要な割り込みの較正や無音への対処に役立ちます。さまざまな設定の詳細は [Realtime API のドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください +ターン検出の設定を調整することで、意図しない割り込みや無音への対処を改善できます。さまざまな設定の詳細は、[Realtime API documentation for more details on the different settings](https://platform.openai.com/docs/guides/realtime-vad) を参照してください ## 割り込み -ビルトインの音声活動検出を使用している場合、エージェント の発話にかぶせて話すと、エージェント は自動的にそれを検知し、発話内容に基づいてコンテキストを更新します。また、`audio_interrupted` イベントも発行します。これはすべての音声再生を即座に停止するために使用できます（WebSocket 接続にのみ適用） +組み込みの音声活動検出を使用している場合、エージェント の発話に被せて話すと、発話内容に基づいてエージェント が自動的に検出し、コンテキストを更新します。また、`audio_interrupted` イベントも発行されます。これは、すべての音声再生を即座に停止するために使用できます（WebSocket 接続にのみ適用）。 -UI に「停止」ボタンを用意するなど、手動で割り込みを行いたい場合は、`interrupt()` を手動で呼び出せます: +手動で割り込みたい場合、たとえば UI に「停止」ボタンを用意したいときは、`interrupt()` を手動で呼び出せます: -いずれの場合も、リアルタイム セッション は エージェント の生成の割り込み、ユーザー に対して何が話されたかに関する エージェント の知識の切り詰め、履歴の更新の両方を処理します。 +いずれの場合も、Realtime セッション はエージェントの生成を中断し、ユーザーに話した内容の認識を切り詰め、履歴を更新します。 -エージェント への接続に WebRTC を使用している場合は、音声出力もクリアされます。WebSocket を使用している場合は、再生キューにある音声の再生を停止するなど、この処理を自分で行う必要があります。 +エージェントへの接続に WebRTC を使用している場合は、音声出力もクリアされます。WebSocket を使用している場合は、再生キューに入っている音声の再生を停止するなど、これを自分で処理する必要があります。 ## テキスト入力 -エージェント にテキスト入力を送信する場合は、`RealtimeSession` の `sendMessage` メソッドを使用できます。 +エージェントにテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用できます。 -エージェント とのやり取りを 2 つのモダリティで有効にしたい場合や、会話に追加のコンテキストを提供したい場合に便利です。 +これは、ユーザーがエージェントと複数のモダリティでやり取りできるようにしたい場合や、会話に追加のコンテキストを提供したい場合に便利です。 ## 会話履歴の管理 -`RealtimeSession` は会話履歴を `history` プロパティで自動管理します: +`RealtimeSession` は、`history` プロパティで会話履歴を自動的に管理します: -これを使って顧客向けに履歴を表示したり、追加の処理を行ったりできます。この履歴は会話の進行中に絶えず変化するため、`history_updated` イベントをリッスンできます。 +これを使って履歴をユーザーに表示したり、追加のアクションを実行したりできます。会話の進行中はこの履歴が継続的に変化するため、`history_updated` イベントを監視できます。 -履歴を修正したい場合（メッセージを完全に削除する、またはその書き起こしを更新するなど）は、`updateHistory` メソッドを使用できます。 +履歴を変更したい場合（メッセージを完全に削除したり、その書き起こしを更新したりするなど）は、`updateHistory` メソッドを使用できます。 ### 制限事項 -1. 現在、関数ツールの呼び出しを後から更新/変更することはできません -2. 履歴内のテキスト出力には、トランスクリプトとテキスト モダリティを有効にする必要があります -3. 割り込みにより切り詰められた応答にはトランスクリプトがありません +1. 現時点では、一度行われた関数ツールの呼び出しを更新・変更できません +2. 履歴のテキスト出力には、書き起こしとテキストモダリティの有効化が必要です +3. 割り込みによって切り詰められたレスポンスには書き起こしがありません ## ツールによる委譲 ![ツールによる委譲](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) -会話履歴とツール呼び出しを組み合わせることで、会話を別のバックエンド エージェントに委譲して、より複雑な処理を実行し、その結果を ユーザー に返せます。 +会話履歴とツール呼び出しを組み合わせることで、より複雑なアクションを実行するために会話を別のバックエンド エージェント に委譲し、その結果を ユーザー へ返すことができます。 -以下のコードは サーバー 上で実行されます。この例では Next.js の Server Actions を通じて実行します。 +以下のコードは サーバー 側で実行されます。この例では Next.js の Server Actions を使用します。 diff --git a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx index 0f33c0bc..d17aef4b 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.25.67' ``` - あるいは、スタンドアロンのブラウザ用パッケージとして `@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 curl -X POST https://api.openai.com/v1/realtime/sessions \ @@ -55,11 +55,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - レスポンスには、後で接続に使用できる `client_secret.value` の値が含まれます。このキーは短時間しか有効ではないため、再生成が必要になります。 + レスポンスには、後で接続に使用できる `client_secret.value` の値が含まれます。なお、このキーは短時間しか有効ではないため、再生成が必要になります。 -3. **最初のエージェントの作成** +3. **はじめてのエージェントの作成** - 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`Agent`](/openai-agents-js/ja/guides/agents) を作成するのとほぼ同じです。 + 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`Agent`](/openai-agents-js/ja/guides/agents) の作成と非常によく似ています。 ```typescript import { RealtimeAgent } from '@openai/agents-realtime'; @@ -72,7 +72,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 4. **セッションの作成** - 通常のエージェントと異なり、音声エージェントは会話とモデルへの接続を継続的に処理する `RealtimeSession` 内で常時実行・リッスンします。このセッションは、音声処理、割り込み、その他多くのライフサイクル機能も扱います。 + 通常のエージェントとは異なり、音声エージェントは会話とモデルへの長期的な接続を処理する `RealtimeSession` の内部で、継続的に実行・待機します。このセッションは、音声処理や割り込み、後ほど取り上げる多くのライフサイクル機能も扱います。 ```typescript import { RealtimeSession } from '@openai/agents-realtime'; @@ -86,21 +86,21 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 5. **セッションへの接続** - セッションに接続するには、先ほど生成したクライアント用エフェメラル トークンを渡します。 + セッションに接続するには、先ほど生成したクライアント用のエフェメラルトークンを渡します。 ```typescript await session.connect({ apiKey: '' }); ``` - これにより、ブラウザで WebRTC を使用して Realtime API に接続し、音声の入力と出力のためにマイクとスピーカーが自動的に設定されます。`RealtimeSession` をバックエンド サーバー（例: Node.js）で実行している場合、 SDK は接続に WebSocket を自動的に使用します。さまざまなトランスポート層については、[リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドで詳しく学べます。 + これにより、ブラウザでは WebRTC を使用して Realtime API に接続し、音声の入出力用にマイクとスピーカーが自動的に構成されます。`RealtimeSession` をバックエンド サーバー（例: Node.js）で実行している場合、 SDK は接続として WebSocket を自動的に使用します。異なるトランスポート層については、[リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドで詳しく学べます。 -6. **統合** +6. **ここまでのまとめ** -7. **起動と会話の開始** +7. **エンジンを起動して話してみる** - Web サーバーを起動し、新しい リアルタイムエージェント のコードを含むページに移動します。マイクへのアクセス許可を求めるリクエストが表示されるはずです。許可すると、エージェントと話し始めることができます。 + Web サーバーを起動し、新しい Realtime Agent のコードを含むページに移動します。マイクへのアクセス許可のリクエストが表示されます。許可すると、エージェントと話し始めることができます。 ```bash npm run dev @@ -110,16 +110,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 b46b161f..fe276f6c 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx @@ -25,42 +25,42 @@ import websocketSessionExample from '../../../../../../../examples/docs/voice-ag import transportEventsExample from '../../../../../../../examples/docs/voice-agents/transportEvents.ts?raw'; import thinClientExample from '../../../../../../../examples/docs/voice-agents/thinClient.ts?raw'; -## デフォルトのトランスポートレイヤー +## 既定のトランスポート層 -### WebRTC での接続 +### WebRTC 経由での接続 -デフォルトのトランスポートレイヤーは WebRTC を使用します。音声はマイクから録音され、自動的に再生されます。 +既定のトランスポート層は WebRTC を使用します。音声はマイクから録音され、自動的に再生されます。 -独自のメディアストリームや audio 要素を使用するには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定します。 +独自のメディアストリームや audio 要素を使う場合は、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定します。 -### WebSocket での接続 +### WebSocket 経由での接続 WebRTC の代わりに WebSocket 接続を使用するには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これはサーバーサイドのユースケース、たとえば Twilio で電話エージェントを構築する場合に適しています。 -録音/再生ライブラリは任意のものを使用でき、元の PCM16 音声バイトを扱えます。 +raw PCM16 オーディオのバイト列を扱うには、任意の録音/再生ライブラリを使用してください。 -### 独自のトランスポート機構の構築 +### 独自トランスポート機構の構築 -別の speech-to-speech API を使用したい、または独自のトランスポート機構を持ちたい場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` イベントを発行することで独自のものを作成できます。 +別の speech-to-speech API を使いたい場合や独自のトランスポート機構がある場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` イベントを送出して独自のものを作成できます。 ## Realtime API とのより直接的なやり取り -OpenAI Realtime API を使いつつ、Realtime API へのより直接的なアクセスが必要な場合は、次の 2 つの方法があります: +OpenAI Realtime API を使いつつ、Realtime API へより直接的にアクセスしたい場合は、次の 2 つの方法があります。 -### オプション 1 - トランスポートレイヤーへのアクセス +### オプション 1 - トランスポート層へのアクセス -引き続き `RealtimeSession` のすべての機能を活用したい場合は、`session.transport` を通じてトランスポートレイヤーにアクセスできます。 +`RealtimeSession` のすべての機能を引き続き活用したい場合は、`session.transport` を介してトランスポート層にアクセスできます。 -トランスポートレイヤーは受信したすべてのイベントを `*` イベントとして発行し、`sendEvent()` メソッドで元のイベントを送信できます。 +トランスポート層は、受信したすべてのイベントをワイルドカードの `*` イベントとして発火し、`sendEvent()` メソッドで raw なイベントを送信できます。 -### オプション 2 — トランスポートレイヤーのみの使用 +### オプション 2 — トランスポート層のみの利用 -自動ツール実行や ガードレール などが不要な場合は、接続と割り込みの管理だけを行う「薄い」クライアントとしてトランスポートレイヤーを使用することもできます。 +ツールの自動実行やガードレールなどが不要な場合は、接続と割り込みだけを管理する「薄い」クライアントとしてトランスポート層のみを使うこともできます。 diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index 9006d2fb..f5473204 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -19,34 +19,36 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概要 -[TypeScript 向け OpenAI Agents SDK](https://github.com/openai/openai-agents-js) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型 AI アプリを構築できます。本 SDK は、以前のエージェントに関する実験である Swarm の本番運用対応版で、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 -- **ハンドオフ**: エージェントが特定のタスクを他のエージェントに委譲できる -- **ガードレール**: エージェントへの入力を検証できる +- **エージェント** 、LLM に 指示とツールを備えたもの +- **ハンドオフ** 、特定のタスクについて他のエージェントへ委譲できる機能 +- **ガードレール** 、エージェントへの入力を検証できる機能 -これらの基本コンポーネントは TypeScript と組み合わせると、ツールとエージェント間の複雑な関係を表現でき、急な学習曲線なしに実世界のアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が付属しており、エージェントのフローを可視化・デバッグできるほか、評価やアプリケーション向けのモデルのファインチューニングにも活用できます。 +TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェントの間にある複雑な関係を表現できるほど強力で、急な学習コストなしに実運用アプリケーションを構築できます。さらに、この SDK には組み込みの **トレーシング** があり、エージェント フローの可視化とデバッグに加えて、評価やアプリ向けのモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 この SDK は次の 2 つの設計原則に基づいています: -1. 使う価値があるだけの機能を備えつつ、学習が素早く進むよう基本コンポーネントは最小限 -2. そのままでも高い完成度で動作しつつ、挙動を細かくカスタマイズ可能 +1. 使う価値があるだけの機能を備えつつ、学習を素早くするために基本コンポーネントは少数にとどめること +2. すぐに使えてうまく動作する一方で、挙動を細かくカスタマイズできること 主な機能は次のとおりです: -- **エージェントループ**: ツールの呼び出し、結果を LLM に渡す処理、LLM の完了までのループを内蔵で処理 -- **TypeScript ファースト**: 新しい抽象化を覚えるのではなく、言語の機能でエージェントのオーケストレーションやチェーンを記述 +- **エージェントループ**: ツールの呼び出し、結果の LLM への送信、LLM の完了までのループ処理を内蔵 +- **TypeScript ファースト**: 新しい抽象を学ぶのではなく、言語の機能を使ってエージェントをオーケストレーションし連鎖させる - **ハンドオフ**: 複数のエージェント間の調整と委譲を可能にする強力な機能 -- **ガードレール**: エージェントと並行して入力の検証やチェックを実行し、失敗時は早期に打ち切り -- **関数ツール**: 任意の TypeScript 関数をツール化し、スキーマ自動生成と Zod ベースの検証を提供 -- **トレーシング**: 可視化・デバッグ・監視のためのトレーシングを内蔵し、OpenAI の評価、ファインチューニング、蒸留ツール群も活用可能 -- **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 +- **ガードレール**: エージェントと並行して入力の検証やチェックを実行し、失敗時は早期に中断 +- **関数ツール**: 任意の TypeScript 関数をツール化し、スキーマ生成と Zod による検証を自動化 +- **トレーシング**: ワークフローの可視化、デバッグ、監視に加えて、OpenAI の評価・ファインチューニング・蒸留ツール群を利用可能 +- **リアルタイムエージェント**: 自動割り込み検出、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 ## インストール -この SDK は現在 `zod@3.25.68` 以降では動作しません。明示的に `zod@3.25.67`（またはそれ以前のバージョン）をインストールしてください。この依存関係の問題は近日中に解決します。更新情報は [this issue](https://github.com/openai/openai-agents-js/issues/187) をご確認ください。 +この SDK は現在 `zod@3.25.68` 以上では動作しません。明示的に `zod@3.25.67`（またはそれ以前のバージョン）をインストールしてください。依存関係の問題はまもなく解決します。最新情報は [this issue](https://github.com/openai/openai-agents-js/issues/187) をご確認ください。 ```bash npm install @openai/agents 'zod@<=3.25.67'