diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index 371191b3..67c31498 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -7,19 +7,18 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -標準で Agents SDK は Responses API または Chat Completions API を通じて OpenAI モデルと連携します。ただし、別のモデルを使用したい場合は、[Vercel の 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 に組み込めます。 ## セットアップ -1. extensions パッケージをインストールして AI SDK アダプターを導入します: +1. 拡張パッケージをインストールして AI SDK アダプターを導入します: ```bash npm install @openai/agents-extensions @@ -31,7 +30,7 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk npm install @ai-sdk/openai@"^1.0.0" ``` -3. アダプターとモデルをインポートして、エージェントに接続します: +3. アダプターとモデルをインポートし、エージェントに接続します: ```typescript import { openai } from '@ai-sdk/openai'; @@ -47,18 +46,18 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk ## 例 - + -## プロバイダー メタデータの受け渡し +## プロバイダーのメタデータの受け渡し -メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` を通して渡します。値は基盤の AI SDK モデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` +メッセージにプロバイダー固有のオプションを送る必要がある場合、`providerMetadata` を通して渡してください。値は基盤の AI SDK モデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` は ```ts providerData: { @@ -70,7 +69,7 @@ providerData: { } ``` -は、AI SDK 連携を使用すると +AI SDK 連携を使用する場合、次のようになります ```ts providerMetadata: { @@ -81,5 +80,3 @@ providerMetadata: { } } ``` - -のようになります。 diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index fbd4c5e9..9e9f58b3 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,32 +7,30 @@ 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 に接続するために使用できます。`websocket` モードの既定の Realtime Session トランスポートを使用して、Twilio から来るイベントを 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 サーバーを用意します。** - ローカルで開発している場合、this will require you to configure a local tunnel like - this will require you to configure a local tunnel like [`ngrok`](https://ngrok.io/) または + ローカル開発の場合、Twilio からローカルサーバーへアクセスできるよう、 + this will require you to configure a local tunnel like [`ngrok`](https://ngrok.io/) or [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - のようなローカルトンネルを設定して、ローカルのサーバーを Twilio からアクセスできるようにする必要があります。Twilio への接続には `TwilioRealtimeTransportLayer` - を使用できます。 + を設定する必要があります。`TwilioRealtimeTransportLayer` を使って Twilio に接続できます。 -3. **extensions パッケージをインストールして Twilio アダプターを導入します:** +3. **拡張パッケージをインストールして Twilio アダプターを導入します:** ```bash npm install @openai/agents-extensions @@ -56,33 +54,28 @@ 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` で、元のイベントデータを含む `message` プロパティを持ちます。 + Twilio から送られてくる元イベントにアクセスしたい場合は、`RealtimeSession` インスタンスの `transport_event` イベントを監視します。Twilio のすべてのイベントは `twilio_message` の type を持ち、元イベントデータを含む `message` プロパティがあります。 3. **デバッグログを確認します。** - 何が起きているかをより詳しく知りたい問題に遭遇することがあります。`DEBUG=openai-agents*` 環境変数を使うと、 - Agents SDK のすべてのデバッグログが表示されます。あるいは、`DEBUG=openai-agents:extensions:twilio*` を使って - Twilio アダプターのデバッグログだけを有効にできます。 + 状況を詳しく知りたい場合があります。`DEBUG=openai-agents*` 環境変数を使うと Agents SDK からのすべてのデバッグログが表示されます。あるいは、`DEBUG=openai-agents:extensions:twilio*` を使用して Twilio アダプターのデバッグログだけを有効にできます。 -## 完全なサーバー例 +## 完全なサーバーの例 -以下は、Twilio からのリクエストを受け取り、`RealtimeSession` に転送する、エンドツーエンドの完全な WebSocket サーバーの例のサンプルです。 +以下は、Twilio からのリクエストを受け取り、それを `RealtimeSession` に転送する WebSocket サーバーのエンドツーエンドの例です。 diff --git a/docs/src/content/docs/ja/guides/agents.mdx b/docs/src/content/docs/ja/guides/agents.mdx index 569469f9..20f5e011 100644 --- a/docs/src/content/docs/ja/guides/agents.mdx +++ b/docs/src/content/docs/ja/guides/agents.mdx @@ -14,144 +14,131 @@ import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agen import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw'; import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw'; -エージェントは OpenAI Agents SDK の主要な構成要素です。 ** エージェント ** は、次の設定を施した大規模言語モデル (LLM) です: +エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** は、次のように構成された Large Language Model (LLM) です。 -- ** Instructions ** – モデルに _ 自分が何者か _ と _ どのように応答すべきか _ を伝えるシステムプロンプト -- ** Model ** – どの OpenAI モデルを呼び出すか、任意のモデル調整パラメーター -- ** Tools ** – LLM がタスクを達成するために呼び出せる関数や API の一覧 +- **Instructions** – モデルに _自分は誰か_、_どのように応答すべきか_ を伝える system prompt +- **Model** – 呼び出す OpenAI モデルと、任意のモデル調整パラメーター +- **Tools** – LLM がタスクを達成するために呼び出せる関数または API のリスト - + -このページの残りではエージェントの各機能を詳しく説明します。 +このページでは、すべての Agent 機能を詳しく説明します。 --- ## 基本設定 -`Agent` コンストラクタは 1 つの設定オブジェクトを受け取ります。よく使われるプロパティを以下に示します。 +`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。最も一般的に使用されるプロパティは次のとおりです。 -| プロパティ | 必須 | 説明 | -| --------------- | ------ | -------------------------------------------------------------------------------------------- | -| `name` | はい | 短い人間可読の識別子 | -| `instructions` | はい | システムプロンプト（文字列 **or** 関数 – [動的 instructions](#dynamic-instructions) を参照） | -| `model` | いいえ | モデル名 **or** カスタムの [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | -| `modelSettings` | いいえ | チューニング パラメーター（temperature、top_p など） | -| `tools` | いいえ | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) の配列 | +| Property | Required | Description | +| --------------- | -------- | -------------------------------------------------------------------------------------------------- | +| `name` | yes | 短い人間可読の識別子 | +| `instructions` | yes | System prompt（文字列 **または** 関数 – [Dynamic instructions](#dynamic-instructions) を参照） | +| `model` | no | モデル名 **または** カスタムの [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | +| `modelSettings` | no | 調整パラメーター（temperature、top_p など） | +| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | - + --- ## コンテキスト -エージェントはコンテキスト型に対してジェネリックです（例: `Agent`）。この _ コンテキスト _ は、あなたが作成して `Runner.run()` に渡す依存性注入用のオブジェクトです。すべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーーメタデータ、フィーチャーフラグ など）を提供するのに役立ちます。 +エージェントは **コンテキスト型に対してジェネリック**（例: `Agent`）です。_コンテキスト_ は、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザーのメタデータ、フラグ機能、…）の提供に役立ちます。 - + --- ## 出力タイプ -既定では、エージェントは ** プレーンテキスト **（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定できます。SDK は次を受け付けます: +デフォルトでは、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は次を受け付けます。 -1. [Zod](https://github.com/colinhacks/zod) のスキーマ（`z.object({...})`） -2. 任意の JSON Schema 互換オブジェクト +1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`） +2. JSON Schema 互換の任意のオブジェクト -`outputType` が指定されると、SDK はプレーンテキストではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を自動的に使用します。 +`outputType` が指定されると、SDK はプレーンテキストではなく自動的に +[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。 --- ## ハンドオフ -エージェントは `handoffs` プロパティを介して他のエージェントへ ** 委譲 ** できます。よくあるパターンは、会話をより特化したサブエージェントへ振り分ける _ トリアージ エージェント _ を使うことです。 +エージェントは `handoffs` プロパティを通じて他のエージェントへ **委譲** できます。一般的なパターンは、会話をより専門的なサブエージェントに振り分ける _トリアージエージェント_ を使用することです。 - + -このパターンの詳細は [ハンドオフ](/openai-agents-js/ja/guides/handoffs) ガイドをご覧ください。 +このパターンの詳細は [ハンドオフガイド](/openai-agents-js/ja/guides/handoffs) を参照してください。 --- -## 動的 instructions +## Dynamic instructions -`instructions` は文字列の代わりに ** 関数 ** にすることもできます。この関数は現在の `RunContext` とエージェント インスタンスを受け取り、文字列 _ または _ `Promise` を返せます。 +`instructions` は文字列の代わりに **関数** にすることもできます。この関数は現在の `RunContext` とエージェントインスタンスを受け取り、文字列 _または_ `Promise` を返すことができます。 -同期関数と `async` 関数の両方をサポートします。 +同期関数と `async` 関数の両方がサポートされています。 --- ## ライフサイクルフック -高度なユースケースでは、イベントをリッスンしてエージェントのライフサイクルを観測できます。 +高度なユースケースでは、イベントをリッスンしてエージェントのライフサイクルを監視できます --- ## ガードレール -ガードレールを使うと、ユーザー入力やエージェント出力の検証や変換ができます。`inputGuardrails` と `outputGuardrails` の配列で設定します。詳細は [ガードレール](/openai-agents-js/ja/guides/guardrails) ガイドをご覧ください。 +ガードレールにより、ユーザー入力やエージェント出力を検証・変換できます。`inputGuardrails` と `outputGuardrails` 配列で設定します。詳しくは +[ガードレールガイド](/openai-agents-js/ja/guides/guardrails) を参照してください。 --- -## エージェントのクローン/コピー +## エージェントのクローン／コピー -既存のエージェントを少しだけ変更した版が必要ですか？`clone()` メソッドを使うと、完全に新しい `Agent` インスタンスが返されます。 +既存のエージェントを少しだけ変更したバージョンが必要ですか？`clone()` メソッドを使用すると、まったく新しい `Agent` インスタンスが返されます。 - + --- ## ツール使用の強制 -ツールを渡しても、LLM が必ず呼び出すとは限りません。`modelSettings.tool_choice` でツール使用を ** 強制 ** できます: +ツールを提供しても、LLM が必ず呼び出すとは限りません。`modelSettings.tool_choice` を使ってツール使用を **強制** できます。 -1. `'auto'`（既定）– ツールを使うかどうかを LLM が判断します -2. `'required'` – LLM は必ずツールを呼び出します（どれを使うかは選べます） -3. `'none'` – LLM はツールを呼び出してはいけません -4. 特定のツール名（例: `'calculator'`）– そのツールを必ず呼び出します +1. `'auto'`（デフォルト）– ツールを使うかどうかは LLM が判断 +2. `'required'` – LLM はツールを _必ず_ 呼び出す（どれを使うかは選択可） +3. `'none'` – LLM はツールを呼び出しては **ならない** +4. 特定のツール名（例: `'calculator'`）– そのツールを必ず呼び出す - + ### 無限ループの防止 -ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返して無限ループに陥るのを防ぎます。この挙動は `resetToolChoice` フラグや `toolUseBehavior` の設定で上書きできます: +ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループに入るのを防ぎます。この挙動は `resetToolChoice` フラグ、または +`toolUseBehavior` の設定で上書きできます。 -- `'run_llm_again'`（既定）– ツール結果を使って LLM を再実行する +- `'run_llm_again'`（デフォルト）– ツール結果を用いて LLM をもう一度実行 - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う -- `{ stopAtToolNames: ['my_tool'] }` – 指定したツールのいずれかが呼び出されたら停止する -- `(context, toolResults) => ...` – 実行を終了すべきかどうかを返すカスタム関数 +- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼ばれたら停止 +- `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数 ```typescript const agent = new Agent({ @@ -164,6 +151,6 @@ const agent = new Agent({ ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) の方法を学ぶ -- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) をさらに深掘りする -- サイドバーの ** @openai/agents ** 直下にある TypeDoc リファレンス全体を参照する +- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を学ぶ +- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) を掘り下げる +- サイドバーの **@openai/agents** 配下にある TypeDoc リファレンス全体を参照する diff --git a/docs/src/content/docs/ja/guides/config.mdx b/docs/src/content/docs/ja/guides/config.mdx index e21aa570..5559865e 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,7 +13,7 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## API キーとクライアント -既定では、 SDK は初回のインポート時に `OPENAI_API_KEY` 環境変数を読み込みます。変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出せます。 +既定では SDK は最初のインポート時に `OPENAI_API_KEY` 環境変数を読み込みます。変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出せます。 -独自の `OpenAI` クライアントインスタンスを渡すこともできます。そうしない場合、 SDK は既定のキーを使って自動的に作成します。 +独自の `OpenAI` クライアントインスタンスを渡すこともできます。そうでない場合、SDK は既定のキーを使って自動的に作成します。 -最後に、 Responses API と Chat Completions API を切り替えることができます。 +最後に、Responses API と Chat Completions API を切り替えられます。 ## トレーシング -トレーシングは既定で有効で、上記の OpenAI キーを使用します。別のキーは `setTracingExportApiKey()` で設定できます。 +トレーシングは既定で有効で、上のセクションの OpenAI キーを使用します。別のキーは `setTracingExportApiKey()` で設定できます。 -トレーシングは完全に無効化することもできます。 +トレーシングを完全に無効化することもできます。 -### ログ内の機微データ +### ログ中の機微なデータ -一部のログにはユーザーデータが含まれる場合があります。以下の環境変数を設定して無効化できます。 +いくつかのログにはユーザーデータが含まれる場合があります。次の環境変数を設定して無効化できます。 -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 00825666..35fd2efa 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 回の実行に参加するすべてのエージェント、ツール、フックは、同じ型のコンテキストを使う必要があります。 +単一の実行に参加するすべてのエージェント、ツール、フックは、同じコンテキストの **型** を使用する必要があります。 ローカルコンテキストの用途例: @@ -30,15 +30,15 @@ import localContextExample from '../../../../../../examples/docs/context/localCo - ヘルパー関数 ## エージェント/ LLM コンテキスト -LLM が呼び出されると、参照できるデータは会話履歴に由来するものだけです。追加情報を利用可能にする方法はいくつかあります: +LLM が呼び出されると、参照できるデータは会話履歴のみです。追加情報を利用可能にするには、次の選択肢があります: -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 からの関連データに基づいて応答をグラウンディングする +1. エージェントの `instructions` に追加する（system または developer メッセージとも呼ばれます）。これは静的な文字列でも、コンテキストを受け取って文字列を返す関数でもかまいません +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 fd0c23e1..1d8cda9f 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) でラップして返します +1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります +2. ガードレール関数が実行され、[`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) でラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します 3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます -> **注意** -> 入力ガードレールはユーザー入力を対象としているため、エージェントがワークフローの _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。エージェントによって必要なガードレールが異なることが多いためです +> **注** +> 入力ガードレールはユーザー入力を対象としているため、ワークフロー内でエージェントが _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェント自体に設定します。これは、エージェントによって必要なガードレールが異なることが多いためです。 ## 出力ガードレール -出力ガードレールも同じ流れです: +出力ガードレールも同じパターンに従います: -1. ガードレールはエージェントに渡されたのと同じ入力を受け取ります -2. ガードレール関数を実行し、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) でラップして返します +1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります +2. ガードレール関数が実行され、[`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) でラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します 3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます -> **注意** -> 出力ガードレールは、エージェントがワークフローの _最後_ のエージェントである場合にのみ実行されます。リアルタイムの音声対話については、[音声エージェントの構築](/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 d0972ab4..dc8fbb19 100644 --- a/docs/src/content/docs/ja/guides/handoffs.mdx +++ b/docs/src/content/docs/ja/guides/handoffs.mdx @@ -10,54 +10,54 @@ import handoffInputExample from '../../../../../../examples/docs/handoffs/handof import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw'; import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw'; -ハンドオフにより、あるエージェントが会話の一部を別のエージェントに委譲できます。これは、異なるエージェントが特定の分野に特化している場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、 FAQ を担当するエージェントを用意できます。 +ハンドオフは、ある エージェント が会話の一部を別の エージェント に委譲できるようにします。これは、異なる エージェント が特定分野を専門にしている場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、FAQ を担当する エージェント を用意できます。 -ハンドオフは LLM にとってはツールとして表現されます。`Refund Agent` というエージェントにハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM に対してツールとして表現されます。`Refund Agent` という エージェント にハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントは `handoffs` オプションを受け付けます。これは、他の `Agent` インスタンスや、`handoff()` ヘルパーが返す `Handoff` オブジェクトを含めることができます。 +すべての エージェント は `handoffs` オプションを受け付けます。ここには、他の `Agent` インスタンスや、`handoff()` ヘルパーが返す `Handoff` オブジェクトを含められます。 ### 基本的な使い方 - + ### `handoff()` によるハンドオフのカスタマイズ -`handoff()` 関数を使うと、生成されるツールを調整できます。 +`handoff()` 関数を使うと、生成されるツールを微調整できます。 -- `agent` – ハンドオフ先のエージェント -- `toolNameOverride` – デフォルトの `transfer_to_` ツール名を上書き -- `toolDescriptionOverride` – デフォルトのツール説明を上書き -- `onHandoff` – ハンドオフ時のコールバック。`RunContext` と、必要に応じてパース済み入力を受け取る +- `agent` – ハンドオフ先の エージェント +- `toolNameOverride` – 既定の `transfer_to_` ツール名の上書き +- `toolDescriptionOverride` – 既定のツール説明の上書き +- `onHandoff` – ハンドオフ発生時のコールバック。`RunContext` と、必要に応じてパース済み入力を受け取ります - `inputType` – ハンドオフの期待される入力スキーマ -- `inputFilter` – 次のエージェントに渡す履歴のフィルター +- `inputFilter` – 次の エージェント に渡す履歴のフィルター ## ハンドオフの入力 -ハンドオフを呼び出す際に、 LLM にデータの提供を求めたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 +ハンドオフを呼び出す際に、LLM にデータを提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 - + ## 入力フィルター -デフォルトでは、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。 +既定では、ハンドオフは会話履歴全体を受け取ります。次の エージェント に渡す内容を変更するには、`inputFilter` を指定します。 共通のヘルパーは `@openai/agents-core/extensions` にあります。 - + ## 推奨プロンプト -プロンプトでハンドオフに言及すると、 LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` を通じて推奨のプレフィックスを提供します。 +プロンプトでハンドオフについて言及すると、LLM はより確実に応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` を介して推奨のプレフィックスを提供します。 diff --git a/docs/src/content/docs/ja/guides/human-in-the-loop.mdx b/docs/src/content/docs/ja/guides/human-in-the-loop.mdx index 71a2cdb8..fac16350 100644 --- a/docs/src/content/docs/ja/guides/human-in-the-loop.mdx +++ b/docs/src/content/docs/ja/guides/human-in-the-loop.mdx @@ -7,32 +7,32 @@ import { Aside, Code } from '@astrojs/starlight/components'; import humanInTheLoopExample from '../../../../../../examples/docs/human-in-the-loop/index.ts?raw'; import toolApprovalDefinition from '../../../../../../examples/docs/human-in-the-loop/toolApprovalDefinition.ts?raw'; -このガイドでは、 SDK に組み込まれた Human in the loop (人間の介入) サポートを使用して、人による介入に基づいてエージェントの実行を一時停止および再開する方法を紹介します。 +このガイドでは、SDK に組み込まれた Human in the loop (人間の介入) サポートを使って、人による介入に基づきエージェントの実行を一時停止・再開する方法を説明します。 -現時点での主なユースケースは、機微なツール実行について承認を求めることです。 +現在の主なユースケースは、機密性の高いツール実行に対する承認を求めることです。 ## 承認リクエスト -承認が必要なツールは、`needsApproval` オプションを `true` に設定するか、真偽値を返す非同期関数を指定して定義できます。 +`needsApproval` オプションを `true` または真偽値を返す非同期関数に設定することで、承認が必要なツールを定義できます。 ### フロー -1. エージェントが 1 つ以上のツール呼び出しを決定した場合、`needsApproval` を評価してそのツールに承認が必要かどうかを確認します。 -2. 承認が必要な場合、エージェントは承認がすでに許可または却下されているかを確認します。 - - 承認がまだ許可も却下もされていない場合、ツールはツール呼び出しを実行できないことを示す固定メッセージをエージェントに返します。 - - 承認／却下が未決の場合は、ツール承認リクエストがトリガーされます。 -3. エージェントはすべてのツール承認リクエストを収集し、実行を中断します。 -4. 中断がある場合、[エージェントの実行結果](/openai-agents-js/ja/guides/result) には、保留中のステップを説明する `interruptions` 配列が含まれます。ツール呼び出しに確認が必要なときは、`type: "tool_approval_item"` を持つ `ToolApprovalItem` が現れます。 -5. ツール呼び出しを承認または拒否するには、`result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出せます。 -6. すべての中断を処理した後、`result.state` を `runner.run(agent, state)` に渡し直すことで実行を再開できます。ここで `agent` は全体の実行を開始した元のエージェントです。 -7. フローは手順 1 から再開します。 +1. エージェントがツール（複数の可能性あり）を呼び出すと判断した場合、`needsApproval` を評価してそのツールに承認が必要か確認します +2. 承認が必要な場合、エージェントはすでに承認または却下されているかを確認します + - 承認または却下が行われていない場合、ツール呼び出しを実行できない旨の固定メッセージがエージェントに返されます + - 承認 / 却下が未処理である場合、ツール承認リクエストが発火します +3. エージェントはすべてのツール承認リクエストを収集し、実行を中断します +4. 中断がある場合、[実行結果](/openai-agents-js/ja/guides/result) には保留中のステップを表す `interruptions` 配列が含まれます。ツール呼び出しに確認が必要な場合、`type: "tool_approval_item"` の `ToolApprovalItem` が現れます +5. ツール呼び出しを承認または却下するには、`result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出します +6. すべての中断を処理した後、`result.state` を `runner.run(agent, state)` に渡して実行を再開できます。ここで `agent` は全体の実行を開始した元のエージェントです +7. フローは手順 1 から再開されます ## 例 @@ -41,25 +41,26 @@ import toolApprovalDefinition from '../../../../../../examples/docs/human-in-the -動作するエンドツーエンド版については [完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 +動作するエンドツーエンド版は [the full example script](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 のバージョンを上げたい場合は、現在のところ、パッケージエイリアスを使って 2 つの Agents SDK のバージョンを並行インストールし、独自のブランチングロジックを実装することを推奨します。 +承認リクエストに時間がかかり、エージェント定義を意味のある形でバージョン管理したい、または Agents SDK のバージョンを上げたい場合は、パッケージのエイリアスを使用して 2 つの Agents SDK バージョンを並行インストールし、独自の分岐ロジックを実装することを現時点では推奨します。 -実務上は、独自コードにバージョン番号を付与してシリアライズ済みの状態と一緒に保存し、復元時に自分のコードの正しいバージョンへ誘導することを意味します。 +実務的には、自身のコードにバージョン番号を割り当て、それをシリアライズした状態とともに保存し、デシリアライズ時に適切なコードのバージョンへ誘導することを意味します。 diff --git a/docs/src/content/docs/ja/guides/mcp.mdx b/docs/src/content/docs/ja/guides/mcp.mdx index 0047e0d3..33f8f4d8 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -12,96 +12,99 @@ 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) は、アプリケーションが LLMs にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP のドキュメントより: -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP は AI アプリケーション向けの USB-C ポートのようなものだと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。 +> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. -この 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 トランスポート](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモート サーバー -3. **Stdio MCP サーバー** – 標準入出力でアクセスするサーバー（最も簡単な選択肢） +1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) によってツールとして利用されるリモート MCP サーバー +2. **Streamable HTTP MCP servers** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートのサーバー +3. **Stdio MCP servers** – 標準入出力でアクセスするサーバー（最も簡単な選択肢） -ユースケースに応じてサーバータイプを選んでください: +ユースケースに応じてサーバータイプを選択してください: -| 必要なこと | 推奨オプション | -| ------------------------------------------------------------------------------------- | ---------------------------------- | -| 公開アクセス可能なリモート サーバーを OpenAI Responses のデフォルト モデルで呼び出す | **1. リモート MCP サーバーツール** | -| 公開アクセス可能なリモート サーバーを使いつつ、ツール呼び出しはローカルでトリガーする | **2. Streamable HTTP** | -| ローカルで動作する Streamable HTTP サーバーを使う | **2. Streamable HTTP** | -| OpenAI Responses 以外のモデルと任意の Streamable HTTP サーバーを使う | **2. Streamable HTTP** | -| 標準入出力プロトコルのみをサポートするローカル 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 サーバーツール +## 1. Hosted MCP server tools -Hosted ツールは、往復のやり取り全体をモデル内に押し込みます。あなたのコードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートのツール エンドポイントを起動し、その結果をモデルにストリーミングで返します。 +組み込みツール（Hosted）は、往復の処理全体をモデル内で完結させます。あなたのコードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルへストリーミングします。 -以下は Hosted MCP ツールを使う最も簡単な例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡すことで、Hosted MCP サーバーツールを簡単に作成できます。 +以下は hosted MCP ツールを使う最も簡単な例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡すことで、hosted MCP サーバーツールの作成に便利です。 -次に、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行できます: +その後、`run` 関数（またはカスタマイズした自分の `Runner` インスタンスの `run` メソッド）でエージェントを実行できます: - + 増分の 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/) アプローチを利用できます。 -完全に動作するサンプル（Hosted tools / Streamable HTTP / stdio + Streaming, HITL, onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + Streaming、HITL、onApproval）は、私たちの GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 -## 2. Streamable HTTP MCP サーバー +## 2. Streamable HTTP MCP servers -エージェントがローカルまたはリモートの 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 repository](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 -## 3. Stdio MCP サーバー +## 3. Stdio MCP servers -標準入出力のみを公開するサーバーには、`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 123d89ed..bc30f103 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) – 人間が読めるモデルの **names**（例: `'gpt‑4o'`）を `Model` インスタンスに解決します -日常的な作業では、通常はモデルの名前と、時折 ModelSettings だけを扱います。 +日常的な作業では、通常はモデルの **names** と、時には `ModelSettings` にだけ触れます。 -カスタムのネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` で独自の OpenAI クライアントを差し替えることもできます。 +カスタムのネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` で独自の `OpenAI` クライアントを差し込むこともできます。 ### デフォルトモデル -OpenAI プロバイダーの既定は gpt‑4o です。エージェントごと、またはグローバルに上書きできます: +OpenAI プロバイダーのデフォルトは `gpt‑4o` です。エージェント単位またはグローバルに上書きできます: -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) を使用している場合にのみサポートされます。 -| Field | Type | Notes | -| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | プロンプトの一意な識別子 | -| `version` | `string` | 使用したいプロンプトのバージョン | -| `variables` | `object` | プロンプトに代入する変数のキー／値ペア。値は文字列、またはテキスト・画像・ファイルなどのコンテンツ入力タイプを指定できます | +| Field | Type | Notes | +| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | プロンプトの一意の識別子 | +| `version` | `string` | 使用したいプロンプトのバージョン | +| `variables` | `object` | プロンプトに差し込む変数のキー/値のペア。値は文字列またはテキスト・画像・ファイルなどのコンテンツ入力タイプにできます | -tools や instructions などの追加のエージェント設定は、保存済みプロンプトで設定した値を上書きします。 +tools や instructions のような追加のエージェント構成は、保存されたプロンプトで設定した値を上書きします。 --- ## カスタムモデルプロバイダー -独自のプロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、そのプロバイダーを `Runner` のコンストラクターに渡します: +独自のプロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、`Runner` コンストラクターにプロバイダーを渡します: --- -## トレーシング エクスポーター +## トレーシングエクスポーター -OpenAI プロバイダーを使用する場合、 API キーを指定すると自動トレース エクスポートを有効にできます: +OpenAI プロバイダーを使用する場合、API キーを指定して自動トレースエクスポートをオプトインできます: -これはトレースを [OpenAI dashboard](https://platform.openai.com/traces) に送信し、ワークフローの完全な実行グラフを確認できます。 +これにより、[OpenAI dashboard](https://platform.openai.com/traces) にトレースが送信され、ワークフローの完全な実行グラフを確認できます。 --- ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を参照 -- [ツール](/openai-agents-js/ja/guides/tools) でモデルを強化 -- 必要に応じて [ガードレール](/openai-agents-js/ja/guides/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 f1a562de..205ad1bf 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 は自律的にタスクへの取り組み方を計画し、ツールを使ってアクションを実行してデータを取得し、ハンドオフでサブエージェントにタスクを委譲できます。たとえば、リサーチ用のエージェントには次のようなツールを備えられます。 +エージェントは、instructions、tools、ハンドオフを備えた LLM です。これは、オープンエンドなタスクが与えられたときに、LLM が自律的に計画を立て、ツールでアクションやデータ取得を行い、ハンドオフでサブエージェントに委譲できることを意味します。例えば、リサーチエージェントには次のようなツールを備えられます。 -- オンラインで情報を見つけるための Web 検索 -- プロプライエタリなデータや接続を横断して検索するための ファイル検索 と取得 -- コンピュータ操作 によるコンピュータ上でのアクション実行 -- データ分析のためのコード実行 -- 計画立案、レポート執筆などが得意な特化型エージェントへのハンドオフ +- Web 検索によるオンライン情報の収集 +- ファイル検索と取得による自社データや接続先の検索 +- コンピュータ操作によるコンピュータ上でのアクション実行 +- コード実行によるデータ分析 +- 計画立案やレポート作成などに長けた専門エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、 LLM の知能に依存したいときに適しています。ここで重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、LLM の知能に依拠したい場合に適しています。重要な戦術は次のとおりです。 -1. 良いプロンプトに投資します。利用可能なツール、その使い方、そしてどのパラメーター内で動作すべきかを明確にします -2. アプリを監視し、反復します。うまくいかない箇所を特定し、プロンプトを改善します -3. エージェントが内省し、改善できるようにします。たとえばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させます -4. 何でもできる汎用エージェントではなく、 1 つのタスクに特化して優れた性能を発揮するエージェントを用意します -5. [評価 (evals)](https://platform.openai.com/docs/guides/evals) に投資します。これによりエージェントを訓練し、タスクの上達を図れます +1. 良いプロンプトに投資すること。利用可能なツール、その使い方、遵守すべきパラメーターを明確にします +2. アプリを監視し、反復すること。問題箇所を見極め、プロンプトを改善します +3. エージェントに内省と改善を許可すること。例えばループで実行して自己批評させる、またはエラーメッセージを与えて改善させます +4. 何でもこなす汎用エージェントではなく、1 つのタスクに特化して卓越したエージェントを用意すること +5. [評価 (evals)](https://platform.openai.com/docs/guides/evals) に投資すること。これによりエージェントを訓練してタスク熟達度を高められます ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度、コスト、パフォーマンスの観点で、より決定的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の観点で、より決定的で予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選ぶ -- あるエージェントの出力を次のエージェントの入力に変換して連鎖させる。ブログ記事の執筆のようなタスクを、リサーチ、アウトライン作成、本文執筆、批評、改善という一連のステップに分解する -- タスクを実行するエージェントを、評価とフィードバックを行うエージェントとともに `while` ループで走らせ、評価者が出力が一定の基準を満たしたと判断するまで繰り返す -- 複数のエージェントを並列で実行する（例: `Promise.all` のような JavaScript の基本コンポーネントを使用）。相互に依存しない複数のタスクがあるときに高速化に有用 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を用いて、コードで検査できる適切な形式のデータを生成する。例えば、エージェントにタスクをいくつかのカテゴリーに分類させ、カテゴリーに基づいて次のエージェントを選ぶ +- 複数のエージェントを、あるエージェントの出力を次のエージェントの入力に変換して連結する。ブログ記事作成のようなタスクを、リサーチ→アウトライン作成→本文執筆→批評→改善という一連のステップに分解する +- 実行役のエージェントと、それを評価してフィードバックするエージェントを `while` ループで回し、評価者が基準を満たしたと判断するまで繰り返す +- 複数のエージェントを並列に実行する（例：JavaScript の基本コンポーネントである `Promise.all` を使用）。互いに依存しない複数タスクがある場合に速度面で有用 -[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) には多数のサンプルコードがあります。 +[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) に多数の例があります。 diff --git a/docs/src/content/docs/ja/guides/quickstart.mdx b/docs/src/content/docs/ja/guides/quickstart.mdx index ec2fe316..b681b3f4 100644 --- a/docs/src/content/docs/ja/guides/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. プロジェクトを作成して npm を初期化します。これは一度だけ行えば十分です。 +1. プロジェクトを作成し、npm を初期化します。これは一度だけ実行すれば大丈夫です ```bash mkdir my_project @@ -19,27 +19,26 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm init -y ``` -2. Agents SDK をインストールします。 +2. Agents SDK をインストールします ```bash npm install @openai/agents zod@3 ``` -3. OpenAI API キーを設定します。お持ちでない場合は、OpenAI API キーの作成方法については [these instructions](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) を参照してください。 +3. OpenAI API key を設定します。まだ持っていない場合は、OpenAI API key を作成するために[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従ってください ```bash export OPENAI_API_KEY=sk-... ``` - あるいは、`setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、 - トレーシングには `setTracingExportApiKey('')` を使用できます。 - 詳しくは [SDK の設定](/openai-agents-js/ja/guides/config) を参照してください。 + 代わりに、`setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、トレーシングには `setTracingExportApiKey('')` を使用できます。 + 詳細は[SDK の設定](/openai-agents-js/ja/guides/config)を参照してください ## はじめてのエージェントの作成 -エージェントは instructions と名前で定義します。 +エージェントは instructions と name で定義します ```typescript import { Agent } from '@openai/agents'; @@ -53,9 +52,9 @@ const agent = new Agent({ ## はじめてのエージェントの実行 -`run` メソッドを使ってエージェントを実行できます。開始したいエージェントと渡したい入力の両方を渡すことで実行をトリガーします。 +`run` メソッドを使ってエージェントを実行できます。開始するエージェントと、渡したい入力の両方を渡すことで実行をトリガーします -これにより、最終出力と、その実行中に実行されたすべてのアクションを含む実行結果が返されます。 +これにより、その実行中に行われた最終出力とアクションを含む実行結果が返ります ```typescript import { Agent, run } from '@openai/agents'; @@ -73,7 +72,7 @@ console.log(result.finalOutput); ## エージェントへのツール付与 -エージェントにツールを与えて、情報の検索やアクションの実行をさせることができます。 +情報の参照やアクションの実行のために、エージェントにツールを与えることができます ```typescript import { Agent, tool } from '@openai/agents'; @@ -100,9 +99,9 @@ const agent = new Agent({ }); ``` -## エージェントの追加 +## いくつかのエージェントの追加 -追加のエージェントを同様に定義して、問題をより小さな部分に分解し、エージェントが目の前のタスクにより集中できるようにできます。また、エージェントごとにモデルを定義することで、問題ごとに異なるモデルを使うこともできます。 +追加のエージェントを同様に定義して、問題を小さな部分に分解し、エージェントを目の前のタスクにより集中させることができます。また、エージェントでモデルを定義することで、異なる問題に対して異なるモデルを使用することもできます ```typescript const historyTutorAgent = new Agent({ @@ -120,7 +119,7 @@ const mathTutorAgent = new Agent({ ## ハンドオフの定義 -複数のエージェント間をオーケストレーションするために、エージェントに対して `handoffs` を定義できます。これにより、実行の過程で会話を次のエージェントへ自動的に引き継げるようになります。 +複数のエージェント間をオーケストレーションするために、エージェントに `handoffs` を定義できます。これにより、エージェントは会話を次のエージェントへ引き継げます。これは実行の過程で自動的に行われます ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -132,11 +131,11 @@ const triageAgent = Agent.create({ }); ``` -実行後は、実行結果の `finalAgent` プロパティを見ることで、どのエージェントが最終応答を生成したかを確認できます。 +実行後、結果の `finalAgent` プロパティを見ることで、どのエージェントが最終応答を生成したかを確認できます ## エージェントオーケストレーションの実行 -Runner は、個々のエージェントの実行、必要になり得るハンドオフ、およびツールの実行を処理します。 +Runner は個々のエージェントの実行、潜在的なハンドオフ、ツールの実行を処理します ```typescript import { run } from '@openai/agents'; @@ -149,23 +148,23 @@ 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 ダッシュボードのトレースビューア](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/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)について学ぶ diff --git a/docs/src/content/docs/ja/guides/release.mdx b/docs/src/content/docs/ja/guides/release.mdx index 813f14f6..032743bf 100644 --- a/docs/src/content/docs/ja/guides/release.mdx +++ b/docs/src/content/docs/ja/guides/release.mdx @@ -5,30 +5,30 @@ description: Learn how we version and release the SDK and recent changes. ## バージョニング -このプロジェクトは、`0.Y.Z` 形式を用いたセマンティック バージョニングを一部調整した形に従います。先頭の `0` は、 SDK がまだ急速に進化していることを示します。各コンポーネントは次の方針でインクリメントします: +本プロジェクトは、`0.Y.Z` 形式のセマンティック バージョニングを一部変更した方式に従います。先頭の `0` は、 SDK が依然として急速に進化していることを示します。各コンポーネントの増分は次のとおりです: ## マイナー（`Y`）バージョン -ベータとマークされていない公開インターフェースに対する **破壊的変更** の場合、マイナー バージョン `Y` を上げます。例えば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 +ベータとマークされていないパブリック インターフェースに **互換性を破る変更** がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への移行には互換性を破る変更が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトのバージョンを `0.0.x` に固定することを推奨します。 +互換性を破る変更を避けたい場合は、プロジェクトでは `0.0.x` に固定することを推奨します。 ## パッチ（`Z`）バージョン -後方互換性を壊さない変更の場合は `Z` を増やします: +非破壊的な変更については `Z` を増やします: - バグ修正 - 新機能 -- 非公開インターフェースの変更 +- プライベート インターフェースの変更 - ベータ機能の更新 ## サブパッケージのバージョニング -メインの `@openai/agents` パッケージは、個別に利用できる複数のサブパッケージで構成されています。現時点ではパッケージのバージョンは連動しており、あるパッケージのバージョンを上げると、他のパッケージも同様に上がります。`1.0.0` への移行に向けて、この方針を変更する可能性があります。 +メインの `@openai/agents` パッケージは、独立して使用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、いずれかのパッケージのバージョンが上がると、他も同様に上がります。`1.0.0` に移行する際にこの方針を変更する可能性があります。 ## 変更履歴 -変更点の把握に役立てるため、各サブパッケージごとに変更履歴を生成しています。変更がサブパッケージ内で行われている場合があるため、詳細は該当する変更履歴をご確認ください。 +変更点の把握を助けるため、各サブパッケージごとに変更履歴を生成しています。変更がサブパッケージ内で行われた場合、その変更の詳細は該当する変更履歴を参照する必要があります。 - [`@openai/agents`](https://github.com/openai/openai-agents-js/blob/main/packages/agents/CHANGELOG.md) - [`@openai/agents-core`](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/CHANGELOG.md) diff --git a/docs/src/content/docs/ja/guides/results.mdx b/docs/src/content/docs/ja/guides/results.mdx index 75c2e59c..b0e6b3ef 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -7,83 +7,83 @@ import { Code } from '@astrojs/starlight/components'; import handoffFinalOutputTypes from '../../../../../../examples/docs/results/handoffFinalOutputTypes.ts?raw'; import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts?raw'; -[エージェントの実行](/openai-agents-js/ja/guides/running-agents) を行うと、次のいずれかを受け取ります： +[エージェントの実行](/openai-agents-js/ja/guides/running-agents)を行うと、次のいずれかを受け取ります: -- [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) は、`stream: true` なしで `run` を呼び出した場合 -- [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult) は、`stream: true` を指定して `run` を呼び出した場合。ストリーミング の詳細は、[ストリーミング](/openai-agents-js/ja/guides/streaming) も参照してください +- `stream: true` を指定せずに `run` を呼び出した場合は [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) +- `stream: true` を指定して `run` を呼び出した場合は [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。ストリーミングの詳細は[ストリーミング](/openai-agents-js/ja/guides/streaming)も参照してください ## 最終出力 -`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が含まれます。この結果は次のいずれかです： +`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が入ります。結果は次のいずれかです: - `string` — `outputType` が定義されていない任意のエージェントのデフォルト -- `unknown` — エージェントに出力タイプとして JSON スキーマが定義されている場合。この場合、JSON はパースされていますが、型を手動で検証する必要があります -- `z.infer` — エージェントに出力タイプとして Zod スキーマが定義されている場合。出力は自動的にこのスキーマに照らしてパースされます -- `undefined` — エージェントが出力を生成しなかった場合（たとえば、出力を生成する前に停止した場合） +- `unknown` — エージェントに出力タイプとして JSON スキーマが定義されている場合。この場合、JSON はパースされていますが、型は手動で検証する必要があります +- `z.infer` — エージェントに出力タイプとして Zod スキーマが定義されている場合。出力は自動的にこのスキーマに対してパースされます +- `undefined` — エージェントが出力を生成しなかった場合（たとえば出力を生成する前に停止した場合） -異なる出力タイプのハンドオフを使用する場合は、エージェントの作成に `new Agent()` コンストラクタではなく `Agent.create()` メソッドを使用してください。 +異なる出力タイプのハンドオフを使用している場合は、エージェントを作成する際に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 -これにより、 SDK が起こり得るすべてのハンドオフにまたがって出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 +これにより SDK が、考え得るすべてのハンドオフをまたいで出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 -例： +例: -## 次ターンの入力 +## 次のターンの入力 -次のターンの入力にアクセスする方法は 2 つあります： +次のターンの入力へアクセスする方法は 2 つあります: -- `result.history` — 入力とエージェントの出力の両方のコピーを含む -- `result.output` — エージェントのフル実行の出力を含む +- `result.history` — あなたの入力とエージェントの出力の両方のコピーを含みます +- `result.output` — エージェントのフル実行の出力を含みます -`history` は、チャットのようなユースケースで完全な履歴を保持する便利な方法です： +`history` は、チャットのようなユースケースで完全な履歴を維持するのに便利です: ## 最後のエージェント -`lastAgent` プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次に ユーザー が何かを入力するときに役立つことがよくあります。たとえば、言語別のエージェントにハンドオフする一次トリアージ エージェントがある場合、最後のエージェントを保存しておき、次回 ユーザー がメッセージを送ったときに再利用できます。 +`lastAgent` プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、次回 ユーザー が入力するときに役立つことがよくあります。たとえば、一次トリアージのフロントライン エージェントから言語別エージェントへハンドオフする場合、最後のエージェントを保存しておき、次に ユーザー がエージェントへメッセージを送る際に再利用できます。 -ストリーミング モードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスするのも有用です。 +ストリーミングモードでは、実行中の現在のエージェントを指す `currentAgent` プロパティにアクセスするのも有用です。 ## 新規アイテム -`newItems` プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。ラン アイテムは、LLM が生成した元のアイテムをラップします。これらは、LLM の出力に加えて、これらのイベントがどのエージェントに関連付けられていたかにアクセスするためにも利用できます。 +`newItems` プロパティには、実行中に生成された新規アイテムが入ります。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。実行アイテムは、LLM が生成した元のアイテムをラップします。これにより、LLM の出力に加えて、これらのイベントがどのエージェントに関連付けられていたかにもアクセスできます。 - [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元のアイテムは生成されたメッセージです - [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフ ツールを呼び出したことを示します。元のアイテムは LLM からのツール呼び出しアイテムです -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。元のアイテムはハンドオフ ツール呼び出しに対するツールのレスポンスです。また、このアイテムからソース／ターゲットのエージェントにもアクセスできます -- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを呼び出したことを示します -- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。元のアイテムはツールのレスポンスです。また、このアイテムからツールの出力にもアクセスできます -- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM からの推論アイテムを示します。元のアイテムは生成された推論です +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。元のアイテムはハンドオフ ツール呼び出しに対するツールの応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます +- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを起動したことを示します +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。元のアイテムはツールの応答です。アイテムからツールの出力にもアクセスできます +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM のリースニング項目を示します。元のアイテムは生成されたリースニングです - [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。元のアイテムは LLM からのツール呼び出しアイテムです ## 状態 -`state` プロパティには、実行の状態が含まれます。`result` に付随する多くの情報は `state` から導出されていますが、`state` はシリアライズ／デシリアライズ可能で、[エラーから復旧する](/openai-agents-js/ja/guides/running-agents#exceptions) 必要がある場合や、[`interruption`](#interruptions) に対処する場合に、後続の `run` 呼び出しの入力としても使用できます。 +`state` プロパティには実行の状態が入ります。`result` に付随するほとんどの情報は `state` から導出されていますが、`state` はシリアライズ/デシリアライズ可能で、[エラーからの復旧](/openai-agents-js/ja/guides/running-agents#exceptions)や[`interruption`](#interruptions)への対応が必要な場合に、後続の `run` 呼び出しの入力としても使用できます。 -## 割り込み +## 中断 -エージェントで `needsApproval` を使用している場合、続行する前に処理が必要な `interruptions` が発生することがあります。その場合、`interruptions` は中断の原因となった `ToolApprovalItem` の配列になります。割り込みの扱い方の詳細は、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) を参照してください。 +エージェントで `needsApproval` を使用している場合、続行する前に処理が必要な `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 bfef2067..267757ec 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 が不要な場合は、シングルトンのデフォルト `Runner` インスタンスで実行する `run()` ユーティリティも使えます。 +カスタム runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスで動作する `run()` ユーティリティも使えます。 -または、自分で runner インスタンスを作成することもできます: +あるいは、独自の runner インスタンスを作成できます。 -エージェント を実行すると、最終出力と実行の完全な履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 +エージェントを実行すると、最終出力と実行の完全な履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 -## エージェントのループ +## エージェントループ -Runner で run メソッドを使うときは、開始するエージェント と入力を渡します。入力は文字列（ ユーザー メッセージと見なされます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。 +Runner で run メソッドを使うと、開始するエージェントと入力を渡します。入力は文字列（ユーザーのメッセージと見なされます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。 -その後、runner は次のループを実行します: +runner は次のループを実行します。 -1. 現在の入力で現在のエージェント のモデルを呼び出す +1. 現在の入力で現在のエージェントのモデルを呼び出す 2. LLM 応答を検査する - - **最終出力** → 返す - - **ハンドオフ** → 新しいエージェント に切り替え、蓄積された会話履歴を保持し、1 に戻る - - **ツール呼び出し** → ツールを実行し、その結果を会話に追加して、1 に戻る -3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を送出する + - **Final output** → return + - **Handoff** → 新しいエージェントに切り替え、蓄積された会話履歴を保持し、1 へ + - **Tool calls** → ツールを実行し、その結果を会話に追加して、1 へ +3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を投げる ### Runner のライフサイクル -アプリ起動時に `Runner` を作成し、リクエスト間で使い回してください。インスタンスには、モデルプロバイダーやトレーシングのオプションといったグローバル設定が保存されます。まったく別の構成が必要な場合のみ、別の `Runner` を作成してください。シンプルなスクリプトでは、内部でデフォルト runner を使う `run()` を呼び出すこともできます。 +アプリ起動時に `Runner` を作成し、リクエスト間で使い回します。このインスタンスはモデルプロバイダやトレーシングオプションなどのグローバル設定を保持します。まったく別の構成が必要な場合のみ別の `Runner` を作成してください。簡単なスクリプトでは、内部でデフォルト runner を使う `run()` を呼び出すこともできます。 ## 実行引数 -`run()` メソッドの入力は、実行を開始する初期エージェント、実行のための入力、およびオプションのセットです。 +`run()` メソッドへの入力は、実行を開始する初期エージェント、実行用の入力、そしてオプションのセットです。 -入力は文字列（ ユーザー メッセージと見なされます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) エージェント を構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/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` | – | すべての tool / ガードレール / ハンドオフに転送されるコンテキストオブジェクト。詳しくは [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 | -| `maxTurns` | `10` | セーフティリミット — 到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を送出します | -| `signal` | – | 取り消し用の `AbortSignal` | +| Option | Default | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着したイベントを逐次発行します | +| `context` | – | すべての tool / guardrail / handoff に転送されるコンテキストオブジェクト。詳しくは [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 | +| `maxTurns` | `10` | セーフティリミット。到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を投げます | +| `signal` | – | キャンセル用の `AbortSignal` | ## ストリーミング -ストリーミング を使うと、LLM の実行中にストリーミングイベントを受け取れます。ストリームが開始されると、`StreamedRunResult` は、生成された新しい出力を含め、実行に関する完全な情報を保持します。`for await` ループを使ってストリーミングイベントを反復処理できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 +ストリーミングを使うと、LLM の実行中にストリーミングイベントを受け取れます。ストリームが開始されると、`StreamedRunResult` には、新しく生成されたすべての出力を含む実行に関する完全な情報が含まれます。`for await` ループを使ってストリーミングイベントを反復処理できます。詳細は [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 ## 実行設定 -独自の `Runner` インスタンスを作成する場合、`RunConfig` オブジェクトを渡して runner を構成できます。 - -| フィールド | 型 | 目的 | -| --------------------------- | --------------------- | ---------------------------------------------------------------------------------------- | -| `model` | `string \| Model` | 実行中の **すべての** エージェント に特定のモデルを強制します | -| `modelProvider` | `ModelProvider` | モデル名を解決します — デフォルトは OpenAI プロバイダーです | -| `modelSettings` | `ModelSettings` | エージェント ごとの設定を上書きするグローバルな調整パラメーター | -| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフの実行時に入力アイテムを変換します（ハンドオフ自体で既に定義されていない場合） | -| `inputGuardrails` | `InputGuardrail[]` | ガードレールは _最初の_ ユーザー入力に適用されます | -| `outputGuardrails` | `OutputGuardrail[]` | ガードレールは _最終_ 出力に適用されます | -| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します | -| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、トレースから LLM / ツールの入力と出力を除外します | -| `workflowName` | `string` | Traces ダッシュボードに表示 — 関連する実行をグルーピングするのに役立ちます | -| `traceId` / `groupId` | `string` | SDK に生成させる代わりに、トレース ID またはグループ ID を手動で指定します | -| `traceMetadata` | `Record` | 各スパンに付与する任意のメタデータ | +独自の `Runner` インスタンスを作成する場合は、runner を構成するために `RunConfig` オブジェクトを渡せます。 + +| Field | Type | Purpose | +| --------------------------- | --------------------- | ------------------------------------------------------------------------------------ | +| `model` | `string \| Model` | 実行中の **すべて** のエージェントに特定のモデルを強制します | +| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダです | +| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルな調整パラメーター | +| `handoffInputFilter` | `HandoffInputFilter` | handoff を実行する際に入力アイテムを変換します（handoff 自体で定義されていない場合） | +| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | +| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | +| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します | +| `traceIncludeSensitiveData` | `boolean` | スパンは出しつつ、LLM/ツールの入出力をトレースから除外します | +| `workflowName` | `string` | Traces ダッシュボードに表示。関連する実行をグルーピングするのに役立ちます | +| `traceId` / `groupId` | `string` | SDK に生成させず、手動で trace または group 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) を参照してください。 +インタラクティブ版は [chat のコード例](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 ## 例外 -SDK は捕捉可能な少数のエラーをスローします: +SDK はキャッチ可能な少数のエラーを投げます。 -- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) — `maxTurns` に到達 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) — モデルが不正な出力を生成（例: 不正な JSON、未知のツール） -- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) — ガードレール違反 -- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) — ガードレールが完了に失敗 -- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) — 関数ツール 呼び出しのいずれかが失敗 -- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) — 設定または ユーザー 入力に基づいて送出されたエラー +- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` に到達 +- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが無効な出力を生成（例: 不正な JSON、未知のツール） +- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) – ガードレール違反 +- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールが完了に失敗 +- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 関数ツール呼び出しのいずれかが失敗 +- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 構成またはユーザー入力に基づいて投げられるエラー -いずれも基底の `AgentsError` クラスを継承しており、現在の実行状態にアクセスするための `state` プロパティを提供する場合があります。 +すべて基底の `AgentsError` クラスを拡張しており、現在の実行状態にアクセスするための `state` プロパティを提供する場合があります。 -以下は `GuardrailExecutionError` を処理するサンプルコードです: +以下は `GuardrailExecutionError` を処理するサンプルコードです。 -上記の例を実行すると、次の出力が表示されます: +上記の例を実行すると、次の出力が表示されます。 ``` Guardrail execution failed: Error: Input guardrail failed to complete: Error: Something is wrong! @@ -125,5 +125,5 @@ 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/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 97079c7d..6ef34b36 100644 --- a/docs/src/content/docs/ja/guides/streaming.mdx +++ b/docs/src/content/docs/ja/guides/streaming.mdx @@ -9,11 +9,11 @@ import nodeTextStreamExample from '../../../../../../examples/docs/streaming/nod import handleAllEventsExample from '../../../../../../examples/docs/streaming/handleAllEvents.ts?raw'; import streamedHITLExample from '../../../../../../examples/docs/streaming/streamedHITL.ts?raw'; -Agents SDKは、モデルからの出力や他の実行ステップの結果を段階的に配信できます。ストリーミングは UI を応答性良く保ち、最終的な実行結果のすべてが揃うまで ユーザー を更新できないという待ち時間を避けます。 +Agents SDK は、モデルやその他の実行ステップからの出力を段階的に配信できます。ストリーミングにより UI を応答性よく保ち、最終的な実行結果のすべてを待たずに ユーザー 表示を更新できます。 ## ストリーミングの有効化 -`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果の代わりにストリーミング用のオブジェクトが得られます: +`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミングオブジェクトを取得できます: -ストリーミングを有効にすると、返される `stream` は `AsyncIterable` インターフェースを実装します。生成される各イベントは、実行内で何が起きたかを記述するオブジェクトです。ストリームは 3 種類のイベントタイプを生成し、それぞれがエージェントの実行の異なる部分を表します。多くのアプリケーションはモデルのテキストだけを必要とするため、ストリームにはそのためのヘルパーがあります。 +ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、その実行内で起きたことを記述するオブジェクトです。ストリームは エージェント の実行の異なる部分を表す 3 種類のイベントのいずれかを順に生成します。多くのアプリケーションはモデルのテキストだけが必要なので、ストリームはそのためのヘルパーを提供します。 ### テキスト出力の取得 -`stream.toTextStream()` を呼ぶと、生成されたテキストのストリームを取得できます。`compatibleWithNodeStreams` が `true` のとき、戻り値は通常の Node.js `Readable` です。`process.stdout` など任意の出力先に直接パイプできます。 +`stream.toTextStream()` を呼び出すと、出力されたテキストのストリームを取得できます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js の `Readable` です。`process.stdout` などの出力先へ直接パイプできます。 -`stream.completed` の Promise は、実行と未処理のコールバックがすべて完了すると解決されます。出力がもうないことを確実にしたい場合は、必ず待機してください。 +`stream.completed` の Promise は、実行と保留中のコールバックがすべて完了したら解決されます。もう出力がないことを確実にする場合は、必ず待機してください。 ### すべてのイベントの監視 -`for await` ループを使って、到着した各イベントを確認できます。役立つ情報には、低レベルのモデルイベント、エージェントの切り替え、そして SDK 固有の実行情報などが含まれます: +`for await` ループを使って、到着した各イベントを検査できます。役立つ情報として、低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などがあります: -プレーンテキストのストリームと 元 のイベントストリームの両方を出力する完成したスクリプトは、[ストリーミングのサンプルコード](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。 +[ストリーミングの code examples](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。プレーンなテキストストリームと 元 のイベントストリームの両方を出力する完全なスクリプトです。 ## イベントタイプ -このストリームは 3 種類のイベントタイプを生成します: +ストリームは 3 種類のイベントタイプを生成します: ### raw_model_stream_event @@ -118,9 +118,9 @@ 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 c1d51cf7..b75c266f 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,26 +10,26 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -ツールはエージェントに **アクションを実行** させます — データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータ操作まで。 JavaScript/TypeScript SDK は 4 つのカテゴリーをサポートします: +ツールは、エージェントが **アクションを実行** できるようにします。データ取得、外部 API 呼び出し、コード実行、さらにはコンピュータの使用まで対応します。JavaScript/TypeScript SDK は次の 4 つの カテゴリー をサポートします: -1. **組み込みツール（Hosted）** — モデルと同じ OpenAI サーバー上で動作します。 _(Web 検索、ファイル検索、コンピュータ操作、code interpreter、画像生成)_ -2. **関数ツール** — 任意のローカル関数を JSON スキーマでラップして、 LLM が呼び出せるようにします。 -3. **ツールとしてのエージェント** — エージェント全体を呼び出し可能なツールとして公開します。 -4. **ローカル MCP サーバー** — ローカルで動作する Model Context Protocol サーバーを接続します。 +1. **組み込みツール（Hosted）** – OpenAI サーバー上でモデルと並行して実行されます。_(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_ +2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM が呼び出せるようにします +3. **エージェントをツールとして** – エージェント全体を呼び出し可能なツールとして公開します +4. **ローカル MCP サーバー** – マシン上で動作する Model Context Protocol サーバーを接続します --- ## 1. 組み込みツール（Hosted） -`OpenAIResponsesModel` を使用する場合、次の組み込みツールを追加できます: +`OpenAIResponsesModel` を使用すると、次の組み込みツールを追加できます: -| ツール | Type 文字列 | 目的 | -| --------------------------- | -------------------- | --------------------------------------------- | -| Web 検索 | `'web_search'` | インターネット検索 | -| ファイル / リトリーバル検索 | `'file_search'` | OpenAI でホストされる ベクトルストア をクエリ | -| コンピュータ操作 | `'computer'` | GUI 操作を自動化 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | -| 画像生成 | `'image_generation'` | テキストに基づいて画像を生成 | +| ツール | 型文字列 | 目的 | +| ------------------- | -------------------- | ----------------------------------------------- | +| Web 検索 | `'web_search'` | インターネット検索 | +| ファイル / 取得検索 | `'file_search'` | OpenAI にホストされた ベクトルストア へのクエリ | +| コンピュータ操作 | `'computer'` | GUI 操作の自動化 | +| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | +| 画像生成 | `'image_generation'` | テキストに基づく画像生成 | -正確なパラメーターセットは OpenAI Responses API に一致します。`rankingOptions` やセマンティックフィルターなどの高度なオプションは、公式ドキュメントを参照してください。 +正確なパラメーターセットは OpenAI Responses API と一致します。`rankingOptions` やセマンティックフィルターなどの高度なオプションは公式ドキュメントを参照してください。 --- ## 2. 関数ツール -`tool()` ヘルパーを使うと、 **任意** の関数をツールにできます。 +`tool()` ヘルパーで、**任意** の関数をツールにできます。 ### オプションリファレンス -| 項目 | 必須 | 説明 | -| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | いいえ | 関数名が既定値（例: `get_weather`） | -| `description` | はい | LLM に提示する、明確で人が読める説明 | -| `parameters` | はい | Zod スキーマまたは 元 の JSON スキーマオブジェクトのいずれか。Zod のパラメーターは自動的に **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 はモデルエラーを返します。あいまい一致にするには `false` に設定します | +| `execute` | はい | `(args, context) => string \| Promise` – ビジネスロジック。2 番目の引数は任意で、`RunContext` です | +| `errorFunction` | いいえ | 内部エラーを ユーザー に見える文字列に変換するためのカスタムハンドラー `(context, error) => string` | -### 非 strict JSON スキーマツール +### 非 strict の JSON スキーマツール -無効または不完全な入力をモデルに推測させたい場合は、 元 の JSON スキーマを使う際に strict モードを無効にできます: +無効または不完全な入力をモデルに推測させたい場合は、 元 JSON スキーマ を使うときに strict モードを無効化できます: -内部的には、SDK は次を行います: +内部的に SDK は次を行います: -- 単一の `input` パラメーターを持つ 関数ツール を作成 -- ツールが呼ばれたときに、その入力でサブエージェントを実行 -- `customOutputExtractor` によって抽出された出力、または最後のメッセージを返却 +- 単一の `input` パラメーターを持つ関数ツールを作成 +- ツールが呼び出されたら、その入力でサブエージェントを実行 +- 最後のメッセージ、または `customOutputExtractor` で抽出された出力を返却 --- @@ -104,21 +104,21 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer ## ツール使用の挙動 -モデルがいつ、どのようにツールを使用すべきかの制御については、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください（`tool_choice`、`toolUseBehavior` など）。 +モデルがツールをいつどのように使用すべきか（`tool_choice`、`toolUseBehavior` など）を制御するには、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください。 --- ## ベストプラクティス -- **短く明確な説明** — ツールが何をするか、いつ使うかを記述 -- **入力の検証** — 可能な限り、厳密な JSON 検証のために Zod スキーマを使用 -- **エラーハンドラーでの副作用を避ける** — `errorFunction` は例外を投げず、有用な文字列を返すべき -- **1 ツール 1 責務** — 小さく合成可能なツールは、モデルの推論を向上 +- **短く明示的な説明** – ツールが _何をするか_ と _いつ使うか_ を記述 +- **入力の検証** – 可能な限り Zod スキーマで厳格な JSON 検証を実施 +- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返し、throw しない +- **ツールごとに単一責務** – 小さく合成可能なツールはモデルの推論を向上 --- ## 次のステップ -- [エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) でツール使用の強制について学ぶ +- [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) について学ぶ - ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 -- [`tool()`](/openai-agents-js/openai/agents/functions/tool) の TypeDoc リファレンスや各種 組み込みツール（Hosted） タイプを確認 +- [`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 c508e51b..a402d7f0 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` + - 所属するトレースを表す `trace_id` - このスパンの親スパンを指す `parent_id`（ある場合） - - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報を含みます + - スパンに関する情報である `span_data`。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成に関する情報など ## デフォルトのトレーシング -デフォルトでは、SDK は次の項目をトレースします: +デフォルトで SDK は次をトレースします: -- `run()` または `Runner.run()` 全体が `Trace` でラップされる -- エージェントが実行されるたびに `AgentSpan` でラップされる -- LLM 生成は `GenerationSpan` でラップされる -- 関数ツールの呼び出しはそれぞれ `FunctionSpan` でラップされる -- ガードレールは `GuardrailSpan` でラップされる -- ハンドオフは `HandoffSpan` でラップされる +- 全体の `run()` または `Runner.run()` は `Trace` でラップ +- エージェントが実行されるたびに `AgentSpan` でラップ +- LLM 生成は `GenerationSpan` でラップ +- 関数ツール呼び出しごとに `FunctionSpan` でラップ +- ガードレールは `GuardrailSpan` でラップ +- ハンドオフは `HandoffSpan` でラップ -デフォルトでは、トレース名は "Agent workflow" です。`withTrace` を使用する場合にこの名前を設定できますし、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを構成することもできます。 +デフォルトでは、トレース名は "Agent workflow" です。`withTrace` を使用する場合はこの名前を設定できます。または [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを設定できます。 -さらに、[カスタムトレーシングプロセッサー](#custom-tracing-processors) を設定して、トレースを別の宛先へ送信する（置き換えまたはセカンダリ宛先として）こともできます。 +さらに、[カスタムトレーシングプロセッサー](#custom-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()` でラップします。 -1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります +1. `withTrace()` で 2 回の `run` 呼び出しをラップしているため、個々の実行は 2 つのトレースを作るのではなく、全体のトレースの一部になります ## トレースの作成 -[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数を使ってトレースを作成できます。あるいは、`getGlobalTraceProvider().createTrace()` を使って手動で新しいトレースを作成し、それを `withTrace()` に渡すこともできます。 +[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数でトレースを作成できます。あるいは、`getGlobalTraceProvider().createTrace()` を使って手動で新しいトレースを作成し、それを `withTrace()` に渡すこともできます。 -現在のトレースは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルを通じて追跡されます。これは、自動的に並行実行と連携して動作することを意味します。 +現在のトレースは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルで追跡されます。つまり、並行処理でも自動的に機能します。 ## スパンの作成 -`create*Span()`（例: `createGenerationSpan()`、`createFunctionSpan()` など）メソッドでスパンを作成できます。一般的には、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数も用意されています。 +各種 `create*Span()`（例: `createGenerationSpan()`, `createFunctionSpan()` など）でスパンを作成できます。一般的には手動でスパンを作成する必要はありません。カスタムのスパン情報を追跡するために [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数も利用できます。 -スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの下にネストされます。これは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルを通じて追跡されます。 +スパンは自動的に現在のトレースの一部になり、[Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルで追跡される最も近い現在のスパンの下にネストされます。 ## 機微なデータ -一部のスパンは、機微なデータを取り得る情報を捕捉する場合があります。 +特定のスパンは機微なデータを取得する可能性があります。 -`createGenerationSpan()` は LLM 生成の入力/出力を、`createFunctionSpan()` は関数呼び出しの入力/出力を保存します。これらには機微なデータが含まれる可能性があるため、[`RunConfig.traceIncludeSensitiveData -`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) でそれらのデータの取得を無効化できます。 +`createGenerationSpan()` は LLM 生成の入出力を、`createFunctionSpan()` は関数呼び出しの入出力を保存します。機微なデータを含む可能性があるため、[`RunConfig.traceIncludeSensitiveData +`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) でそのデータの取得を無効化できます。 ## カスタムトレーシングプロセッサー -トレーシングの高レベルなアーキテクチャは次のとおりです: +トレーシングのハイレベルなアーキテクチャは次のとおりです: -- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレースの作成を担当し、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) を介してアクセスできます -- `TraceProvider` に [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) を設定します。これはトレース/スパンをバッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に送信し、OpenAI のバックエンドへバッチでエクスポートします +- 初期化時にグローバルな [`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` を含めない限りトレースは送信されません +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 6b28e4d5..24abf9b9 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** : +- **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 は十分なテストが行われていません + - トレースはリクエストの最後に手動でフラッシュする必要があります。詳しくは [トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください + - Cloudflare Workers の `AsyncLocalStorage` サポートが限定的なため、一部のトレースが正確でない可能性があります +- **Browsers**: + - ブラウザでは現在 トレーシング はサポートされていません +- **v8 isolates**: + - 適切なブラウザ用ポリフィルを備えたバンドラを使えば SDK を v8 isolates 向けにバンドルできますが、トレーシングは動作しません + - v8 isolates は広範にはテストされていません -## デバッグ ロギング +## デバッグログ -SDK で問題が発生している場合、デバッグ ロギングを有効化して、何が起きているかの詳細を確認できます。 +SDK の利用時に問題が発生した場合、デバッグログを有効にすると、内部で何が起きているかの情報を得られます。 -`DEBUG` 環境変数を `openai-agents:*` に設定すると、デバッグ ロギングを有効化できます。 +デバッグログは、環境変数 `DEBUG` を `openai-agents:*` に設定して有効化します。 ```bash DEBUG=openai-agents:* ``` -また、デバッグ対象を SDK の特定部分に限定することもできます: +また、SDK の特定部分にデバッグ対象を絞り込むこともできます: -- `openai-agents:core` — SDK の主な実行ロジック用 -- `openai-agents:openai` — OpenAI API 呼び出し用 -- `openai-agents:realtime` — Realtime Agents のコンポーネント用 +- `openai-agents:core` — SDK のメイン実行ロジック +- `openai-agents:openai` — OpenAI API 呼び出し +- `openai-agents:realtime` — Realtime Agents コンポーネント diff --git a/docs/src/content/docs/ja/guides/voice-agents.mdx b/docs/src/content/docs/ja/guides/voice-agents.mdx index 82e9521f..0daff9fe 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 の speech-to-speech モデルを使って、リアルタイムの音声チャットを提供します。これらのモデルは音声、テキスト、ツール呼び出しのストリーミングをサポートし、音声／電話でのカスタマーサポート、モバイルアプリ体験、音声チャットなどの用途に最適です。 +音声エージェントは OpenAI の音声対音声モデルを使って、リアルタイムの音声チャットを提供します。これらのモデルは音声、テキスト、ツール呼び出しのストリーミングをサポートし、音声/電話でのカスタマーサポート、モバイルアプリでの体験、音声チャットなどの用途に最適です。 -Voice Agents SDK は、[OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) のための TypeScript クライアントを提供します。 +Voice Agents SDK は [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) のための TypeScript クライアントを提供します。 ### 主な機能 - WebSocket または WebRTC で接続 -- ブラウザとバックエンド接続の両方で利用可能 -- 音声と割り込みの処理 +- ブラウザおよびバックエンド接続の両方で使用可能 +- 音声および割り込みのハンドリング - ハンドオフによるマルチエージェントのオーケストレーション - ツールの定義と呼び出し -- モデル出力を監視するカスタム ガードレール -- ストリーミングされたイベント用のコールバック -- テキスト エージェントと音声エージェントの両方で同じコンポーネントを再利用 +- モデル出力を監視するカスタムガードレール +- ストリーミングイベント用コールバック +- テキストと音声のエージェントで同じコンポーネントを再利用 -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 ad8dea09..3f44ac36 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/build.mdx @@ -28,137 +28,138 @@ import serverAgentExample from '../../../../../../../examples/docs/voice-agents/ import delegationAgentExample from '../../../../../../../examples/docs/voice-agents/delegationAgent.ts?raw'; import turnDetectionExample from '../../../../../../../examples/docs/voice-agents/turnDetection.ts?raw'; -## 音声の処理 +## 音声の取り扱い -デフォルトの `OpenAIRealtimeWebRTC` のような一部のトランスポート層は、音声の入力と出力を自動で処理します。`OpenAIRealtimeWebSocket` のような他のトランスポート機構では、セッションの音声を自分で処理する必要があります: +デフォルトの `OpenAIRealtimeWebRTC` のような一部のトランスポートレイヤーは、音声の入力と出力を自動で処理します。`OpenAIRealtimeWebSocket` のような他のトランスポート機構では、セッション音声を自分で扱う必要があります: ## セッション設定 -[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) のコンストラクター、または `connect(...)` を呼び出す際に追加のオプションを渡すことで、セッションを設定できます。 +[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) の構築時、または `connect(...)` を呼び出すときに追加オプションを渡すことで、セッションを設定できます。 -これらのトランスポート層では、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 +これらのトランスポートレイヤーでは、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 -[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) にまだ対応するパラメーターがない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡したものは `session` オブジェクトの一部としてそのまま渡されます。 +[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に対応するパラメーターがまだない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡したものは `session` オブジェクトの一部としてそのまま渡されます。 ## ハンドオフ -通常のエージェントと同様に、ハンドオフを使ってエージェントを複数のエージェントに分割し、それらをオーケストレーションすることで、エージェントのパフォーマンスを改善し、問題のスコープをより適切に絞り込むことができます。 +通常のエージェントと同様に、ハンドオフを使用してエージェントを複数のエージェントに分割し、それらをオーケストレーションすることで、エージェントのパフォーマンスを向上させ、問題の範囲を適切に絞り込めます。 -通常のエージェントとは異なり、Realtime Agents ではハンドオフの挙動が少し異なります。ハンドオフが実行されると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 +通常のエージェントと異なり、Realtime Agents におけるハンドオフはやや挙動が異なります。ハンドオフが行われると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 -さらに、ハンドオフの一環として `voice` や `model` を変更することはできません。また、接続先は他の Realtime Agents のみです。別のモデル、たとえば `o4-mini` のような推論モデルを使う必要がある場合は、[ツールによる委譲](#delegation-through-tools) を使用できます。 +加えて、ハンドオフの一部として `voice` や `model` を変更することはできません。また、接続できるのは他の Realtime Agents のみです。別のモデル、例えば `o4-mini` のような推論モデルを使用する必要がある場合は、[ツールによる委譲](#delegation-through-tools) を利用できます。 ## ツール -通常のエージェントと同様に、Realtime Agents はアクションを実行するためにツールを呼び出せます。通常のエージェントで使用するのと同じ `tool()` 関数を使ってツールを定義できます。 +通常のエージェントと同様に、Realtime Agents はツールを呼び出してアクションを実行できます。通常のエージェントで使用するのと同じ `tool()` 関数を使ってツールを定義できます。 -Realtime Agents では関数ツールのみを使用でき、これらのツールは Realtime Session と同じ場所で実行されます。つまり、Realtime Session をブラウザで実行している場合、ツールもブラウザで実行されます。より機微なアクションを実行する必要がある場合は、ツール内からバックエンド サーバーへの HTTP リクエストを発行できます。 +Realtime Agents で使用できるのは関数ツールのみで、これらのツールは Realtime Session と同じ場所で実行されます。つまり、Realtime Session をブラウザで実行している場合、ツールもブラウザで実行されます。より機密性の高い操作を行う必要がある場合は、ツール内でバックエンド サーバーへの HTTP リクエストを行うことができます。 -ツールの実行中、エージェントはユーザーからの新しいリクエストを処理できません。体験を向上させる 1 つの方法は、エージェントにツールを実行しようとしていることを宣言させたり、ツールの実行時間を稼ぐための特定のフレーズを話させたりするよう指示することです。 +ツールの実行中、エージェントはユーザーからの新しいリクエストを処理できません。体験を改善する方法の一つは、エージェントに対してツールを実行しようとしていることを告知させたり、ツール実行のための時間を稼ぐ特定のフレーズを話すように指示することです。 ### 会話履歴へのアクセス -エージェントが特定のツールを呼び出した際の引数に加えて、Realtime Session が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、現在の会話状態に基づいてより複雑なアクションを実行する必要がある場合や、[ツールによる委譲](#delegation-through-tools) を使用する予定がある場合に役立ちます。 +エージェントが特定のツールを呼び出したときの引数に加えて、Realtime Session が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[委譲のためのツール](#delegation-through-tools) を使う予定がある場合に有用です。 ### ツール実行前の承認 -ツールを `needsApproval: true` で定義すると、エージェントはツールを実行する前に `tool_approval_requested` イベントを発行します。 +`needsApproval: true` でツールを定義すると、エージェントはツールを実行する前に `tool_approval_requested` イベントを発行します。 -このイベントをリッスンすることで、ユーザーにツール呼び出しの承認または拒否を促す UI を表示できます。 +このイベントを監視することで、ツール呼び出しを承認または拒否するための UI をユーザーに表示できます。 ## ガードレール -ガードレールは、エージェントが話した内容が一連のルールに違反していないかを監視し、即座にレスポンスを遮断する手段を提供します。これらのガードレール チェックはエージェントのレスポンスの書き起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効です）。 +ガードレールは、エージェントの発話が一連のルールに違反したかを監視し、即座に応答を遮断する方法を提供します。これらのガードレール検査はエージェントの応答の文字起こしに基づいて行われるため、モデルのテキスト出力が有効になっている必要があります（デフォルトで有効）。 -提供したガードレールは、モデルのレスポンスが返ってくるのと同時に非同期で実行され、たとえば「特定の禁止ワードに言及した」など、あらかじめ定義した分類トリガーに基づいてレスポンスを遮断できます。 +提供したガードレールは、モデルの応答が返されるのと非同期に実行され、例えば「特定の禁止語を言及した」といった事前定義の分類トリガーに基づいて応答を遮断できます。 -ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。このイベントには、ガードレールをトリガーした `itemId` を含む `details` オブジェクトも含まれます。 +ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。このイベントは、ガードレールを作動させた `itemId` を含む `details` オブジェクトも提供します。 -デフォルトでは、ガードレールはレスポンス テキストの生成が終了するか、または 100 文字ごとに実行されます。テキストの発話には通常それより時間がかかるため、ほとんどの場合、ユーザーが聞く前にガードレールが違反を検知できるはずです。 +デフォルトでは、ガードレールは 100 文字ごと、または応答テキストの生成が完了した時点で実行されます。音声での読み上げは通常それより時間がかかるため、たいていの場合、ユーザーが聞く前に違反を検知できます。 -この挙動を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡せます。 +この動作を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡せます。 ## ターン検出 / 音声活動検出 -Realtime Session は、ユーザーが話しているタイミングを自動検出し、組み込みの [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使って新しいターンをトリガーします。 +Realtime Session は、ユーザーが話しているタイミングを自動的に検出し、組み込みの [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使用して新しいターンを開始します。 -`turnDetection` オブジェクトをセッションに渡すことで、音声活動検出モードを変更できます。 +音声活動検出モードは、`turnDetection` オブジェクトをセッションに渡すことで変更できます。 -ターン検出の設定を調整すると、不要な割り込みの較正や無音への対処に役立ちます。各種設定の詳細は [Realtime API ドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください +ターン検出設定を調整することで、不要な割り込みの調整や無音への対処に役立ちます。各種設定の詳細は [Realtime API ドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください ## 割り込み -組み込みの音声活動検出を使用している場合、エージェントの発話中に話しかけると、発話内容に基づいてエージェントが自動的に検出してコンテキストを更新します。同時に `audio_interrupted` イベントも発行されます。これはすべての音声再生を即座に停止するために使用できます（WebSocket 接続にのみ適用）。 +組み込みの音声活動検出を使用している場合、エージェントの発話中に話し始めると、自動的にエージェントがそれを検出し、発話内容に基づいてコンテキストを更新します。また、`audio_interrupted` イベントを発行します。これは、すべての音声再生を即時停止するために使用できます（WebSocket 接続にのみ適用）。 -たとえば UI に「停止」ボタンを用意するなど、手動で割り込みを行いたい場合は、`interrupt()` を手動で呼び出せます: +手動で割り込みを行いたい場合、例えば UI に「停止」ボタンを用意したいときは、`interrupt()` を手動で呼び出せます: -いずれの場合も、Realtime Session はエージェントの生成の割り込み、ユーザーに対して話した内容の知識の切り詰め、履歴の更新を処理します。 +いずれの場合も、Realtime Session はエージェントの生成の割り込み、ユーザーに対して話された内容の切り詰め、履歴の更新を処理します。 -エージェントへの接続に WebRTC を使用している場合は、音声出力もクリアされます。WebSocket を使用している場合は、キューに入っている音声の再生を停止するなど、これを自分で処理する必要があります。 +エージェントに接続するのに WebRTC を使用している場合は、音声出力もクリアされます。WebSocket を使用している場合は、キューに入って再生予定の音声の再生停止などを自分で処理する必要があります。 ## テキスト入力 エージェントにテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用できます。 -これは、ユーザーがエージェントと両方のモダリティでやり取りできるようにしたい場合や、会話に追加のコンテキストを提供したい場合に役立ちます。 +ユーザーがエージェントと両方のモダリティでやりとりできるようにしたい場合や、会話に追加のコンテキストを提供したい場合に有用です。 ## 会話履歴の管理 -`RealtimeSession` は、`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) +![Delegation through tools](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 24553945..d1a149ea 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx @@ -28,23 +28,23 @@ 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 ``` -1. **Agents SDKのインストール** +1. **Agents SDK のインストール** ```bash npm install @openai/agents zod@3 ``` - 代わりに、スタンドアロンのブラウザ用パッケージとして `@openai/agents-realtime` をインストールすることもできます。 + 代わりにスタンドアロンのブラウザ用パッケージである `@openai/agents-realtime` をインストールすることもできます。 -2. **クライアント用のエフェメラルトークンの生成** +2. **クライアントのエフェメラルトークンを生成** - このアプリケーションはユーザーのブラウザで実行されるため、Realtime APIを介してモデルに安全に接続する方法が必要です。そのために、バックエンドサーバーで生成する必要がある [エフェメラルクライアントキー](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` の内部で常時実行・リッスンします。このセッションは、オーディオ処理や割り込み、その他多くのライフサイクル機能も処理します。これらについては後ほど説明します。 + 通常のエージェントと異なり、Voice Agent は会話とモデルへの継続的な接続を扱う `RealtimeSession` の内部で常時実行・リスニングします。このセッションは、音声の処理、中断、その他多くのライフサイクル機能もあわせて処理します。 ```typescript import { RealtimeSession } from '@openai/agents-realtime'; @@ -82,25 +82,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` のコンストラクタは、最初の引数として `agent` を受け取ります。このエージェントが、ユーザーが最初に対話できるエージェントになります。 + `RealtimeSession` のコンストラクターは、最初の引数として `agent` を受け取ります。このエージェントが ユーザー が最初に対話できるエージェントになります。 5. **セッションへの接続** - セッションに接続するには、先ほど生成したクライアント エフェメラルトークンを渡します。 + セッションに接続するには、先ほど生成したクライアントのエフェメラルトークンを渡します。 ```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) 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 e0e8ea29..7e5b8c2f 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 を使用します。音声はマイクから録音され、自動で再生されます。 -独自のメディアストリームやオーディオ要素を使用するには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定します。 +独自のメディアストリームやオーディオ要素を使うには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定します。 -### WebSocket 経由での接続 +### WebSocket 接続 -WebRTC の代わりに WebSocket 接続を使うには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これはサーバーサイドのユースケースに適しており、たとえば Twilio で電話エージェントを構築する場合などに有効です。 +WebRTC の代わりに WebSocket 接続を使うには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これはサーバーサイドのユースケース、たとえば Twilio で電話エージェントを構築する場合に適しています。 -元の PCM16 オーディオバイトを扱うには、任意の録音／再生ライブラリを使用してください。 +任意の録音/再生ライブラリを使って、元の PCM16 オーディオバイトを処理してください。 -### 独自のトランスポート機構の構築 +### 独自トランスポート機構の構築 -別の 音声対音声 API を使いたい場合や、独自のカスタム トランスポート機構を持ちたい場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` イベントを発行して独自に作成できます。 +別の音声対音声 API を使いたい、または独自のトランスポート機構が必要な場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` のイベントを発行して独自に作成できます。 -## Realtime APIとより直接的なやり取り +## Realtime API への直接的なアクセス -OpenAI Realtime APIを使いつつ、Realtime APIへより直接的にアクセスしたい場合は、次の 2 つの方法があります。 +OpenAI Realtime API を使いつつ、より直接的に Realtime API にアクセスしたい場合は、次の 2 つの方法があります。 -### オプション 1 - トランスポート層へのアクセス +### オプション 1 - トランスポートレイヤーへのアクセス -引き続き `RealtimeSession` のすべての機能を活用したい場合は、`session.transport` を介してトランスポート層にアクセスできます。 +`RealtimeSession` のあらゆる機能を活かしつつ、`session.transport` からトランスポートレイヤーにアクセスできます。 -トランスポート層は、受信したすべてのイベントを `*` イベントとして発行し、`sendEvent()` メソッドで元のイベントを送信できます。 +トランスポートレイヤーは受信したすべてのイベントを `*` イベントで発行し、`sendEvent()` メソッドで元のイベントを送信できます。 -### オプション 2 — トランスポート層のみの利用 +### オプション 2 — トランスポートレイヤーのみの利用 -ツールの自動実行やガードレールなどが不要な場合は、接続と割り込みのみを管理する「薄い」クライアントとしてトランスポート層を利用することもできます。 +自動ツール実行やガードレールなどが不要な場合は、接続と割り込みの管理だけを行う「薄い」クライアントとして、トランスポートレイヤーのみを使用できます。 diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index 6b92aa4f..0f21b60e 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -19,33 +19,32 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概要 -[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 はごく少数の基本コンポーネントを備えています: +[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 には非常に小さな基本コンポーネントのセットがあります。 -- **エージェント**: 指示とツールを備えた LLM -- **ハンドオフ**: エージェント が特定のタスクを他の エージェント に委譲できる機能 -- **ガードレール**: エージェント への入力を検証できる機能 +- **エージェント**: instructions と tools を備えた LLMs +- **ハンドオフ**: 特定のタスクを他のエージェントに委譲する仕組み +- **ガードレール**: エージェントへの入力を検証できる仕組み -TypeScript と組み合わせることで、これらの基本コンポーネントはツールと エージェント の間の複雑な関係を表現でき、急な学習曲線なしに実運用アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェント フローの可視化やデバッグ、評価に加えて、アプリケーション向けにモデルをファインチューニングすることもできます。 +TypeScript と組み合わせることで、これらの基本コンポーネントは tools とエージェント間の複雑な関係を表現でき、学習コストなしに実アプリケーションを構築できます。さらに、この SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグし、評価したり、アプリ向けにモデルをファインチューニングすることもできます。 ## Agents SDK を使う理由 -この SDK には 2 つの設計原則があります: +この SDK は 2 つの設計原則に基づいています。 -1. 使う価値があるだけの十分な機能を備えつつ、学習が速くなるよう基本コンポーネントは少数に保つ -2. すぐに使えて高い性能を発揮しつつ、動作内容を細部までカスタマイズできる +1. 使う価値があるだけの機能を備えつつ、学習を速くするために基本コンポーネントは少なく +2. すぐに使えてもうまく動作しつつ、実際に何が起きるかを正確にカスタマイズ可能 -主な機能は次のとおりです: +主な機能は次のとおりです。 -- **エージェントループ**: ツールの呼び出し、結果を LLM に送信、 LLM の完了までループを行う組み込みループ -- **TypeScript ファースト**: 新しい抽象化を学ばずに、言語の機能で エージェント をオーケストレーションして連携させる -- **ハンドオフ**: 複数の エージェント 間での調整と委譲を可能にする強力な機能 -- **ガードレール**: エージェント と並行して入力の検証やチェックを実行し、チェックが失敗した場合は早期に中断 -- **関数ツール**: 任意の TypeScript 関数をツールに変換し、自動スキーマ生成と Zod によるバリデーションを提供 -- **トレーシング**: フローの可視化・デバッグ・監視に加え、OpenAI の評価・ファインチューニング・蒸留ツールを活用可能 -- **リアルタイムエージェント**: 自動割り込み検出、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 +- **エージェントループ**: tools の呼び出し、結果を LLM に渡す処理、LLM が完了するまでのループを内蔵 +- **TypeScript ファースト**: 新しい抽象を学ばずに、言語機能でエージェントのオーケストレーションや連鎖を実現 +- **ハンドオフ**: 複数エージェント間の調整や委譲を可能にする強力な機能 +- **ガードレール**: エージェントと並行して入力の検証やチェックを実行し、失敗時には早期に中断 +- **関数ツール**: 任意の TypeScript 関数をツール化し、自動スキーマ生成と Zod ベースの検証を提供 +- **トレーシング**: ワークフローの可視化・デバッグ・監視に加え、OpenAI の評価、ファインチューニング、蒸留ツールを活用可能 +- **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 ## インストール