From 240475a8633621778a2901919f20ea6f5de912e7 Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Thu, 14 Aug 2025 21:02:29 +0900 Subject: [PATCH] Migrate translation script to gpt-5 --- .github/workflows/update-docs.yml | 3 + .../src/content/docs/ja/extensions/ai-sdk.mdx | 34 +++-- .../src/content/docs/ja/extensions/twilio.mdx | 48 ++++--- docs/src/content/docs/ja/guides/agents.mdx | 116 +++++++++------- docs/src/content/docs/ja/guides/config.mdx | 28 ++-- docs/src/content/docs/ja/guides/context.mdx | 30 ++-- .../src/content/docs/ja/guides/guardrails.mdx | 44 +++--- docs/src/content/docs/ja/guides/handoffs.mdx | 28 ++-- .../docs/ja/guides/human-in-the-loop.mdx | 42 +++--- docs/src/content/docs/ja/guides/mcp.mdx | 85 ++++++------ docs/src/content/docs/ja/guides/models.mdx | 84 ++++++------ .../src/content/docs/ja/guides/multi-agent.md | 50 +++---- .../src/content/docs/ja/guides/quickstart.mdx | 51 +++---- docs/src/content/docs/ja/guides/release.mdx | 18 +-- docs/src/content/docs/ja/guides/results.mdx | 79 ++++++----- .../content/docs/ja/guides/running-agents.mdx | 128 +++++++++--------- docs/src/content/docs/ja/guides/streaming.mdx | 111 ++++++++++++--- docs/src/content/docs/ja/guides/tools.mdx | 102 +++++++------- docs/src/content/docs/ja/guides/tracing.mdx | 101 +++++++------- .../docs/ja/guides/troubleshooting.mdx | 34 ++--- .../content/docs/ja/guides/voice-agents.mdx | 16 +-- .../docs/ja/guides/voice-agents/build.mdx | 82 ++++++----- .../ja/guides/voice-agents/quickstart.mdx | 47 ++++--- .../docs/ja/guides/voice-agents/transport.mdx | 32 ++--- docs/src/content/docs/ja/index.mdx | 38 +++--- docs/src/scripts/translate.ts | 3 +- 26 files changed, 773 insertions(+), 661 deletions(-) diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml index 32f81c95..077875ac 100644 --- a/.github/workflows/update-docs.yml +++ b/.github/workflows/update-docs.yml @@ -30,6 +30,9 @@ jobs: - name: Install dependencies run: pnpm install + - name: Build workspace packages + run: pnpm build + - name: Translate docs env: OPENAI_API_KEY: ${{ secrets.PROD_OPENAI_API_KEY }} diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index 2726291d..e75ac3f9 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -7,30 +7,30 @@ 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 ``` -2. [Vercel の AI SDK](https://sdk.vercel.ai/docs/models/overview) から目的のモデル パッケージを選択してインストールします: +2. 使用したいモデルパッケージを [Vercel の AI SDK](https://sdk.vercel.ai/docs/models/overview) から選んでインストールします: ```bash - npm install @ai-sdk/openai + npm install @ai-sdk/openai@"^1.0.0" ``` -3. アダプターとモデルをインポートし、エージェントに接続します: +3. アダプターとモデルをインポートしてエージェントに接続します: ```typescript import { openai } from '@ai-sdk/openai'; @@ -45,13 +45,23 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk + + ## 例 - + -## プロバイダー メタデータの渡し方 +## プロバイダー メタデータの受け渡し -メッセージと一緒にプロバイダー固有のオプションを送信する必要がある場合は、`providerMetadata` に渡してください。値はそのまま基盤となる AI SDK モデルに転送されます。たとえば Agents SDK で次の `providerData` を指定すると +メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` を介して渡します。値は基盤となる AI SDK モデルにそのまま転送されます。たとえば、Agents SDK における次の `providerData` ```ts providerData: { @@ -63,7 +73,7 @@ providerData: { } ``` -AI SDK 連携使用時には +は、AI SDK 連携を使用する場合には次のようになります ```ts providerMetadata: { @@ -74,5 +84,3 @@ providerMetadata: { } } ``` - -のようになります。 diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index 614f771c..02c14f3d 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,33 +7,36 @@ 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 に接続できます。デフォルトの Realtime Session トランスポートを `websocket` モードで使用し、Twilio から届くイベントを Realtime Session に接続することも可能です。ただし、適切なオーディオ形式を設定し、電話通話は Web ベースの会話よりも遅延が大きいため、割り込みタイミングを調整する必要があります。 +Twilio は、電話の通話からの 元 の音声を WebSocket サーバーに送る [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しています。このセットアップは、あなたの [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続するために利用できます。Twilio から送られてくるイベントを Realtime Session に接続するには、`websocket` モードのデフォルトの Realtime Session transport を使えます。ただし、電話の通話は Web ベースの会話よりも自然にレイテンシーが増えるため、適切な音声フォーマットの設定と、割り込みタイミングの調整を自前で行う必要があります。 -セットアップ体験を向上させるために、割り込み処理や音声転送を含め、Twilio との接続を代行する専用のトランスポートレイヤーを用意しました。 +セットアップ体験を向上させるために、Twilio への接続、割り込み処理、音声の転送などを代わりに扱う専用のトランスポート層を用意しました。 ## セットアップ -1. **Twilio アカウントと Twilio 電話番号を所有していることを確認します。** +1. **Twilio のアカウントと Twilio の電話番号を用意する** -2. **Twilio からのイベントを受信できる WebSocket サーバーをセットアップします。** +2. **Twilio からのイベントを受け取れる WebSocket サーバーを用意する** - ローカルで開発している場合は、[`ngrok`](https://ngrok.io/) や [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) などのローカルトンネルを設定し、ローカルサーバーを Twilio からアクセス可能にする必要があります。`TwilioRealtimeTransportLayer` を使用して Twilio に接続できます。 + ローカル開発の場合、[`ngrok`](https://ngrok.io/) や + [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) + のようなローカルトンネルの設定が必要です。ローカルサーバーを Twilio からアクセス可能にします。Twilio に接続するには `TwilioRealtimeTransportLayer` を使えます。 -3. **拡張パッケージをインストールして Twilio アダプターを導入します:** +3. **extensions パッケージをインストールして Twilio アダプターを導入する** ```bash npm install @openai/agents-extensions ``` -4. **`RealtimeSession` に接続するためにアダプターとモデルをインポートします:** +4. **アダプターとモデルをインポートして `RealtimeSession` に接続する** -5. **`RealtimeSession` を Twilio に接続します:** +5. **`RealtimeSession` を Twilio に接続する** ```typescript session.connect({ apiKey: 'your-openai-api-key' }); @@ -51,28 +54,31 @@ Twilio には [Media Streams API](https://www.twilio.com/docs/voice/media-stream -`RealtimeSession` から期待されるすべてのイベントや動作（ツール呼び出し、ガードレールなど）がそのまま利用できます。`RealtimeSession` を音声エージェントで使う方法については [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 +`RealtimeSession` に期待されるあらゆるイベントや動作は、ツール呼び出しや ガードレール などを含め、そのまま動作します。`RealtimeSession` を音声エージェントで使う方法の詳細は、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 ## ヒントと考慮事項 -1. **スピードが鍵です。** +1. **最重要なのはスピード** - Twilio から必要なすべてのイベントと音声を受け取るには、WebSocket 接続への参照を取得したらすぐに `TwilioRealtimeTransportLayer` インスタンスを作成し、直ちに `session.connect()` を呼び出してください。 + Twilio から必要なイベントと音声をすべて受け取るため、WebSocket 接続の参照を得たらすぐに + `TwilioRealtimeTransportLayer` インスタンスを生成し、直後に `session.connect()` を呼び出してください。 -2. **Twilio の元イベントにアクセスします。** +2. **Twilio の 元 イベントにアクセスする** - Twilio から送信される元イベントにアクセスしたい場合は、`RealtimeSession` インスタンスの `transport_event` をリッスンできます。Twilio からの各イベントは `twilio_message` という type と、生のイベントデータが入った `message` プロパティを持ちます。 + Twilio から送られる 元 のイベントにアクセスしたい場合は、`RealtimeSession` インスタンスの + `transport_event` をリッスンします。Twilio からの各イベントは `twilio_message` という type と、元 のイベントデータを含む `message` プロパティを持ちます。 -3. **デバッグログを確認します。** +3. **デバッグログを確認する** - 詳細を確認したい場合は、`DEBUG=openai-agents*` 環境変数を使用すると Agents SDK のすべてのデバッグログを表示できます。あるいは `DEBUG=openai-agents:extensions:twilio*` を使って Twilio アダプターのログのみに絞ることも可能です。 + 何が起きているかの詳細が必要な場合があります。環境変数 `DEBUG=openai-agents*` を使うと Agents SDK のすべてのデバッグログを表示できます。あるいは、Twilio アダプターに限定してデバッグログを有効化するには + `DEBUG=openai-agents:extensions:twilio*` を使用します。 -## フルサーバー例 +## 完全なサーバー例 -以下は、Twilio からのリクエストを受け取り `RealtimeSession` に転送する WebSocket サーバーのエンドツーエンド例です。 +以下は、Twilio からのリクエストを受け取り、それを `RealtimeSession` に転送する WebSocket サーバーのエンドツーエンドの完全な例です。 diff --git a/docs/src/content/docs/ja/guides/agents.mdx b/docs/src/content/docs/ja/guides/agents.mdx index b607229e..6dc55354 100644 --- a/docs/src/content/docs/ja/guides/agents.mdx +++ b/docs/src/content/docs/ja/guides/agents.mdx @@ -14,130 +14,148 @@ import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agen import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw'; import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw'; -エージェントは、OpenAI Agents SDK の主要な構成要素です。**Agent** とは、次の設定が施された Large Language Model (LLM) です。 +エージェント は OpenAI Agents SDK の主要な構成要素です。 ** Agent ** は、以下で構成された Large Language Model (LLM) です: -- **Instructions** – モデルに _自身が何者で、どのように応答すべきか_ を伝えるシステムプロンプト -- **Model** – 呼び出す OpenAI モデル名と、任意のモデルチューニングパラメーター -- **Tools** – タスクを達成するために LLM が呼び出せる関数や API の一覧 +- ** Instructions ** – モデルに _ 自分が何者か _ と _ どのように応答すべきか _ を伝えるシステムプロンプト +- ** Model ** – 呼び出す OpenAI モデルと、任意のモデル調整パラメーター +- ** Tools ** – LLM がタスク達成のために呼び出せる関数や API の一覧 - + -このページでは、エージェントのすべての機能を順に詳しく説明します。 +このページでは、Agent の各機能を詳しく説明します。 --- ## 基本設定 -`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。よく使用されるプロパティは次のとおりです。 +`Agent` コンストラクターは単一の設定オブジェクトを受け取ります。もっとも一般的に使われる +プロパティは次のとおりです。 -| Property | Required | 説明 | -| --------------- | -------- | --------------------------------------------------------------------------------------------------------- | -| `name` | yes | 短い人間が読みやすい識別子 | -| `instructions` | yes | システムプロンプト（文字列 **または** 関数。詳細は [Dynamic instructions](#dynamic-instructions) を参照） | -| `model` | no | モデル名 **または** カスタム [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | -| `modelSettings` | no | temperature、top_p などのチューニングパラメーター | -| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | +| Property | Required | Description | +| --------------- | -------- | -------------------------------------------------------------------------------------------------- | +| `name` | yes | 人が読める短い識別子 | +| `instructions` | yes | システムプロンプト（文字列 **または** 関数 – [動的 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 では次が使用できます。 +デフォルトでは、Agent は **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返してほしい場合は +`outputType` プロパティを指定します。SDK は次を受け付けます: 1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`） -2. JSON-schema 互換オブジェクト +2. JSON スキーマ互換の任意のオブジェクト -`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) をご覧ください。 --- -## Dynamic instructions +## 動的 instructions -`instructions` は文字列の代わりに **関数** にすることもできます。関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列または `Promise` を返します。 +`instructions` は文字列の代わりに **関数** にできます。関数は現在の `RunContext` と Agent インスタンスを受け取り、 +文字列 _または_ `Promise` を返せます。 -同期関数と `async` 関数のどちらもサポートされています。 +同期・`async` 関数のどちらにも対応しています。 --- ## ライフサイクルフック -高度なユースケースでは、イベントをリッスンしてエージェントのライフサイクルを監視できます。 +高度なユースケースでは、イベントをリッスンして Agent のライフサイクルを観測できます --- ## ガードレール -ガードレールを使用すると、ユーザー入力やエージェント出力を検証・変換できます。`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'`） – LLM はそのツールを必ず呼び出す +1. `'auto'`（デフォルト）– ツールを使うかどうかは LLM が判断 +2. `'required'` – LLM は _必ず_ いずれかのツールを呼び出す（どれを使うかは選べる） +3. `'none'` – LLM はツールを **呼び出してはならない** +4. 特定のツール名（例: `'calculator'`）– LLM はその特定のツールを呼び出す必要がある - + ### 無限ループの防止 -ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツールを繰り返し呼び出す無限ループに陥るのを防ぎます。この動作は `resetToolChoice` フラグや `toolUseBehavior` の設定で上書きできます。 +ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツールを繰り返し +呼び出そうとして無限ループに陥るのを防ぎます。この動作は `resetToolChoice` フラグ、または +`toolUseBehavior` の設定で上書きできます: -- `'run_llm_again'`（デフォルト） – ツール結果をもとに LLM を再実行 +- `'run_llm_again'`（デフォルト）– ツール結果を使って LLM をもう一度実行する - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う -- `{ stopAtToolNames: ['my_tool'] }` – 指定したツールが呼び出された時点で停止 -- `(context, toolResults) => ...` – 実行を終了するかどうかを返すカスタム関数 +- `{ stopAtToolNames: ['my_tool'] }` – 指定したいずれかのツールが呼ばれた時点で停止する +- `(context, toolResults) => ...` – 実行を終了すべきかどうかを返すカスタム関数 ```typescript const agent = new Agent({ @@ -150,6 +168,6 @@ const agent = new Agent({ ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を学ぶ +- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) の方法を学ぶ - [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) を詳しく見る -- サイドバーの **@openai/agents** にある完全な TypeDoc リファレンスを参照する +- サイドバーの ** @openai/agents ** にある TypeDoc リファレンス全体を参照する diff --git a/docs/src/content/docs/ja/guides/config.mdx b/docs/src/content/docs/ja/guides/config.mdx index d450a6e5..6fad06ba 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,34 +13,34 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## API キーとクライアント -デフォルトでは、SDK は最初にインポートされた際に `OPENAI_API_KEY` 環境変数を読み込みます。環境変数を設定できない場合は、`setDefaultOpenAIKey()` を手動で呼び出してください。 +既定では、 SDK は初回にインポートされたときに `OPENAI_API_KEY` 環境変数を読み込みます。環境変数を設定できない場合は、`setDefaultOpenAIKey()` を手動で呼び出せます。 -独自の `OpenAI` クライアント インスタンスを渡すこともできます。渡さない場合、SDK は前述のキーを用いて自動的にクライアントを生成します。 +独自の `OpenAI` クライアント インスタンスを渡すこともできます。それ以外の場合は、 SDK が既定のキーを使って自動的に作成します。 -最後に、Responses API と Chat Completions API を切り替えることも可能です。 +最後に、 Responses API と Chat Completions API を切り替えることができます。 - + ## トレーシング -トレーシングはデフォルトで有効になっており、前述の OpenAI キーを使用します。別のキーを使用したい場合は `setTracingExportApiKey()` で設定できます。 +トレーシングは既定で有効になっており、上のセクションの OpenAI キーを使用します。別のキーを使う場合は、`setTracingExportApiKey()` で設定できます。 トレーシングを完全に無効化することもできます。 @@ -48,12 +48,12 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## デバッグログ -SDK は [`debug`](https://www.npmjs.com/package/debug) パッケージを使用してデバッグログを出力します。詳細ログを表示するには、`DEBUG` 環境変数に `openai-agents*` を設定してください。 +SDK はデバッグログに [`debug`](https://www.npmjs.com/package/debug) パッケージを使用します。詳細ログを表示するには、`DEBUG` 環境変数を `openai-agents*` に設定してください。 ```bash export DEBUG=openai-agents* @@ -61,19 +61,19 @@ export DEBUG=openai-agents* `@openai/agents` の `getLogger(namespace)` を使うと、自分のモジュール用に名前空間付きロガーを取得できます。 - + ### ログ内の機微データ -一部のログにはユーザーデータが含まれる場合があります。以下の環境変数を設定することで無効化できます。 +一部のログにはユーザー データが含まれる場合があります。以下の環境変数を設定して無効化できます。 -LLM への入力と出力のログを無効化するには: +LLM の入出力のロギングを無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールへの入力と出力のログを無効化するには: +ツールの入出力のロギングを無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/src/content/docs/ja/guides/context.mdx b/docs/src/content/docs/ja/guides/context.mdx index 4525c0ca..dd503fd9 100644 --- a/docs/src/content/docs/ja/guides/context.mdx +++ b/docs/src/content/docs/ja/guides/context.mdx @@ -6,39 +6,39 @@ 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 コンテキスト** — LLM が応答を生成する際に参照できるもの +1. **ローカルコンテキスト** — 実行中にコードがアクセスできるもの。ツールに必要な依存関係やデータ、`onHandoff` のようなコールバック、ライフサイクルフック +2. **エージェント/ LLM のコンテキスト** — 言語モデルが応答を生成するときに参照できる情報 ## ローカルコンテキスト -ローカルコンテキストは `RunContext` 型で表されます。状態や依存関係を保持する任意のオブジェクトを作成し、それを `Runner.run()` に渡します。すべてのツール呼び出しとフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み書きできます。 +ローカルコンテキストは `RunContext` 型で表現します。状態や依存関係を保持する任意のオブジェクトを作成し、それを `Runner.run()` に渡します。すべてのツール呼び出しとフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み書きできます。 -1 回の実行に参加するすべてのエージェント、ツール、フックは同じ **型** のコンテキストを使う必要があります。 +単一の実行に参加するすべてのエージェント、ツール、フックは、同じ **型** のコンテキストを使用する必要があります。 -ローカルコンテキストは次のような用途に適しています。 +ローカルコンテキストは次のような用途に使います: - 実行に関するデータ（ユーザー名、 ID など） - ロガーやデータフェッチャーなどの依存関係 - ヘルパー関数 -## エージェント／ LLM コンテキスト +## エージェント/ LLM のコンテキスト -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` に追加する（システムまたは開発者メッセージとも呼ばれます）。これは静的な文字列でも、コンテキストを受け取って文字列を返す関数でも構いません。 +2. `Runner.run()` を呼び出すときの `input` に含める。これは instructions の手法に似ていますが、メッセージを [指揮系統 (chain of command)](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます。 +3. 関数ツールで公開し、 LLM がオンデマンドでデータを取得できるようにする +4. リトリーバルや Web 検索ツールを使い、ファイルやデータベース、または Web からの関連データに基づいて応答をグラウンディングする diff --git a/docs/src/content/docs/ja/guides/guardrails.mdx b/docs/src/content/docs/ja/guides/guardrails.mdx index 4292a412..f9736494 100644 --- a/docs/src/content/docs/ja/guides/guardrails.mdx +++ b/docs/src/content/docs/ja/guides/guardrails.mdx @@ -7,47 +7,47 @@ import { Code } from '@astrojs/starlight/components'; import inputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-input.ts?raw'; import outputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-output.ts?raw'; -ガードレールはエージェントと _並列で_ 実行され、ユーザー入力やエージェント出力に対してチェックやバリデーションを行えます。たとえば、コストの高いモデルを呼び出す前に軽量モデルをガードレールとして実行することができます。ガードレールが悪意のある利用を検出した場合、エラーを発生させて高価なモデルの実行を停止できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力やエージェントの出力に対してチェックやバリデーションを行えます。例えば、コストの高いモデルを呼び出す前に軽量モデルをガードレールとして実行できます。ガードレールが悪意ある利用を検知した場合、エラーを発生させ、コストの高いモデルの実行を停止できます。 ガードレールには 2 種類あります: -1. **入力ガードレール** は最初のユーザー入力に対して実行されます -2. **出力ガードレール** は最終的なエージェント出力に対して実行されます +1. **入力ガードレール** は初回のユーザー入力に対して実行されます +2. **出力ガードレール** はエージェントの最終出力に対して実行されます ## 入力ガードレール -入力ガードレールは次の 3 ステップで動作します: +入力ガードレールは 3 段階で実行されます: -1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、その戻り値として [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップして返します -3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます +1. ガードレールはエージェントに渡されたのと同じ入力を受け取ります。 +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) でラップしたものを返します。 +3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます。 -> **Note** -> 入力ガードレールはユーザー入力を対象としているため、ワークフロー内で _最初_ のエージェントに対してのみ実行されます。ガードレールはエージェントごとに設定します。エージェントごとに必要なガードレールが異なることが多いためです。 +> **注記** +> 入力ガードレールはユーザー入力を対象としているため、ワークフローでエージェントが _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。なぜなら、エージェントごとに必要なガードレールが異なることが多いからです。 ## 出力ガードレール 出力ガードレールも同じパターンに従います: -1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、その戻り値として [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップして返します -3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます +1. ガードレールはエージェントに渡されたのと同じ入力を受け取ります。 +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) でラップしたものを返します。 +3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます。 -> **Note** -> 出力ガードレールはワークフロー内で _最後_ のエージェントに対してのみ実行されます。リアルタイム音声インタラクションについては [音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails) を参照してください。 +> **注記** +> 出力ガードレールは、ワークフローでエージェントが _最後_ のエージェントである場合にのみ実行されます。リアルタイムの音声対話については [音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails) を参照してください。 -## トリップワイヤ +## トリップワイヤー -ガードレールが失敗すると、トリップワイヤを通じてそれを通知します。トリップワイヤが発火すると直ちに Runner が該当エラーをスローし、実行を停止します。 +ガードレールが失敗すると、トリップワイヤーを介してそれを通知します。トリップワイヤーがトリガーされるとすぐに、ランナーは対応するエラーをスローし、実行を停止します。 ## ガードレールの実装 -ガードレールは `GuardrailFunctionOutput` を返すシンプルな関数です。以下は、内部で別のエージェントを利用して、ユーザーが数学の宿題を求めているかをチェックする最小例です。 +ガードレールは、`GuardrailFunctionOutput` を返す単なる関数です。以下は、内部で別のエージェントを実行して、ユーザーが数学の宿題の手助けを求めているかどうかを確認する最小の例です。 出力ガードレールも同様に動作します。 @@ -55,10 +55,10 @@ import outputGuardrailExample from '../../../../../../examples/docs/guardrails/g -1. `guardrailAgent` はガードレール関数内で使用されます +1. `guardrailAgent` はガードレール関数内で使用します 2. ガードレール関数はエージェントの入力または出力を受け取り、結果を返します -3. 追加情報をガードレール結果に含めることもできます -4. `agent` がガードレールを適用する実際のワークフローを定義します +3. ガードレールの結果に追加情報を含めることができます +4. `agent` はガードレールが適用される実際のワークフローを定義します diff --git a/docs/src/content/docs/ja/guides/handoffs.mdx b/docs/src/content/docs/ja/guides/handoffs.mdx index d5d31afe..ebbb04be 100644 --- a/docs/src/content/docs/ja/guides/handoffs.mdx +++ b/docs/src/content/docs/ja/guides/handoffs.mdx @@ -10,28 +10,28 @@ import handoffInputExample from '../../../../../../examples/docs/handoffs/handof import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw'; import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw'; -ハンドオフを使うと、あるエージェントが会話の一部を別のエージェントに委任できます。異なるエージェントが特定分野を専門にしている場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、 FAQ を担当するエージェントを分けることができます。 +ハンドオフは、あるエージェントが会話の一部を別のエージェントに委任できるようにします。これは、異なるエージェントが特定の領域に特化している場合に便利です。たとえばカスタマーサポートのアプリでは、予約、返金、FAQ を担当するエージェントがいるかもしれません。 -ハンドオフは LLM にはツールとして表現されます。たとえば `Refund Agent` にハンドオフすると、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM に対してはツールとして表現されます。`Refund Agent` というエージェントにハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントは `handoffs` オプションを受け付けます。ここには他の `Agent` インスタンスや `handoff()` ヘルパーが返す `Handoff` オブジェクトを含めることができます。 +すべてのエージェントは `handoffs` オプションを受け付けます。ここには他の `Agent` インスタンスや、`handoff()` ヘルパーが返す `Handoff` オブジェクトを含められます。 -### 基本的な使用例 +### 基本的な使い方 ### `handoff()` によるハンドオフのカスタマイズ -`handoff()` 関数を使うと、生成されるツールを調整できます。 +`handoff()` 関数を使うと、生成されるツールを微調整できます。 - `agent` – ハンドオフ先のエージェント - `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き - `toolDescriptionOverride` – 既定のツール説明を上書き -- `onHandoff` – ハンドオフ発生時に呼び出されるコールバック。 `RunContext` と、必要に応じて解析済み入力を受け取る -- `inputType` – ハンドオフで期待される入力スキーマ -- `inputFilter` – 次のエージェントに渡す履歴をフィルタリング +- `onHandoff` – ハンドオフが発生したときのコールバック。`RunContext` と、必要に応じてパース済みの入力を受け取る +- `inputType` – ハンドオフに期待される入力スキーマ +- `inputFilter` – 次のエージェントに渡す履歴のフィルター -## ハンドオフ入力 +## ハンドオフの入力 -ハンドオフを呼び出す際に LLM からデータを受け取りたい場合があります。その場合は入力スキーマを定義し、それを `handoff()` で使用します。 +ハンドオフの呼び出し時に、LLM にデータを提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 - + ## 入力フィルター -デフォルトでは、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更したい場合は `inputFilter` を指定します。 -よく使われるヘルパーは `@openai/agents-core/extensions` にあります。 +既定では、ハンドオフ先には会話履歴全体が渡されます。次のエージェントに何を渡すかを変更するには、`inputFilter` を指定します。 +一般的なヘルパーは `@openai/agents-core/extensions` にあります。 ## 推奨プロンプト -プロンプトにハンドオフを明示すると、 LLM がより安定して応答します。SDK では `RECOMMENDED_PROMPT_PREFIX` として推奨のプレフィックスを提供しています。 +LLM は、プロンプトでハンドオフに言及しておくと、より確実に応答します。SDK は、`RECOMMENDED_PROMPT_PREFIX` 経由で推奨のプレフィックスを提供します。 -動作するエンドツーエンドの例は [完全なスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 +エンドツーエンドで動作するバージョンについては、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 -## 長時間の承認待ちに対処する +## 長時間の承認待ちへの対応 -Human in the loop のフローは、サーバーを稼働し続けなくても長時間中断できるように設計されています。リクエストを終了して後で再開する必要がある場合は、状態をシリアライズして再開できます。 +Human in the loop (人間の介入) フローは、サーバーを稼働させ続けなくても、長時間中断できるように設計されています。リクエストを終了して後で再開する必要がある場合は、状態をシリアライズして、後で再開できます。 -`JSON.stringify(result.state)` を使用して状態をシリアライズし、後で `RunState.fromString(agent, serializedState)` にシリアライズ済み状態を渡して再開します。ここで `agent` は実行を開始したエージェントのインスタンスです。 +状態は `JSON.stringify(result.state)` を使ってシリアライズでき、後で `RunState.fromString(agent, serializedState)` にシリアライズした状態を渡すことで再開できます。ここで `agent` は、全体の実行をトリガーしたエージェントのインスタンスです。 -この方法でシリアライズ済み状態をデータベースやリクエストと一緒に保存できます。 +この方法で、シリアライズした状態をデータベースに、またはリクエストと一緒に保存できます。 ### 保留タスクのバージョニング -承認リクエストに時間がかかり、エージェント定義を意味のある形でバージョン管理したり Agents SDK のバージョンを上げたりする予定がある場合は、パッケージエイリアスを使って複数バージョンの Agents SDK を並行してインストールし、独自のブランチロジックを実装することを推奨します。 +承認リクエストに時間がかかり、エージェントの定義のバージョン管理を意味のある形で行いたい、あるいは Agents SDK のバージョンを上げたい場合には、現在のところ、パッケージエイリアスを使って Agents SDK を 2 つのバージョンを並行インストールし、独自のブランチングロジックを実装することをおすすめします。 -実際には、自分のコードにバージョン番号を割り当て、それをシリアライズ済み状態と一緒に保存し、デシリアライズ時に正しいコードバージョンへ誘導するという運用になります。 +実務的には、独自コードにバージョン番号を割り当て、シリアライズした状態と一緒に保存し、デシリアライズ時に自分のコードの正しいバージョンへ誘導することを意味します。 diff --git a/docs/src/content/docs/ja/guides/mcp.mdx b/docs/src/content/docs/ja/guides/mcp.mdx index dba8822b..72531a02 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -10,94 +10,101 @@ import hostedStreamExample from '../../../../../../examples/docs/mcp/hostedStrea import hostedHITLExample from '../../../../../../examples/docs/mcp/hostedHITL.ts?raw'; import streamableHttpExample from '../../../../../../examples/docs/mcp/streamableHttp.ts?raw'; import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; +import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; -[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP ドキュメントからの引用: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより: -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションにおける USB-C ポートのようなものだと考えてください。USB-C がさまざまな周辺機器やアクセサリを接続するための標準化された方法を提供するのと同様に、MCP は AI モデルを多様なデータソースやツールへ接続するための標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションのための USB‑C ポートのようなものだと考えてください。USB‑C がデバイスをさまざまな周辺機器やアクセサリに接続するための標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。 -この SDK がサポートする MCP サーバーには 3 種類あります。 +この SDK がサポートする MCP サーバーは 3 種類あります: -1. **リモート MCP サーバーツール** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) からツールとして呼び出されるリモート MCP サーバー -2. **Streamable HTTP MCP サーバー** – [Streamable HTTP トランスポート](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートサーバー -3. **Stdio MCP サーバー** – 標準入力 / 出力でアクセスするサーバー（最もシンプル） +1. **リモート MCP サーバーツール** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) によってツールとして使用されるリモート MCP サーバー +2. **Streamable HTTP MCP サーバー** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートのサーバー +3. **Stdio MCP サーバー** – 標準入出力でアクセスするサーバー（最もシンプルな選択肢） -ユースケースに応じてサーバータイプを選択してください。 +ユースケースに応じてサーバータイプを選択してください: -| 必要なこと | 推奨オプション | -| ---------------------------------------------------------------------------------------- | -------------------------- | -| 既定の OpenAI Responses モデルで、公開アクセス可能なリモートサーバーを呼び出したい | **1. リモート MCP ツール** | -| 公開アクセス可能なリモートサーバーを使用しつつ、ツール呼び出しをローカルでトリガーしたい | **2. Streamable HTTP** | -| ローカルで稼働する Streamable HTTP サーバーを使用したい | **2. Streamable HTTP** | -| OpenAI Responses 以外のモデルで Streamable HTTP サーバーを使用したい | **2. Streamable HTTP** | -| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーを使用したい | **3. Stdio** | +| 要件 | 推奨オプション | +| -------------------------------------------------------------------------------------- | ---------------------------------- | +| 公開アクセス可能なリモートサーバーを既定の OpenAI Responses モデルで呼び出す | **1. リモート MCP サーバーツール** | +| 公開アクセス可能なリモートサーバーを使いつつ、ツール呼び出しはローカルでトリガーしたい | **2. Streamable HTTP** | +| ローカルで稼働する Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| OpenAI Responses 以外のモデルで任意の Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーで作業する | **3. Stdio** | ## 1. リモート MCP サーバーツール -リモートツールでは、往復の処理全体がモデル内部で行われます。あなたのコードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートツールのエンドポイントを呼び出し、その結果をモデルへストリームします。 +リモート MCP サーバーツールは、ラウンドトリップ全体をモデル側で完結させます。コードから MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルへストリーミングします。 -以下はリモート MCP サーバーツールを使用する最もシンプルな例です。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡すことで、リモート MCP サーバーツールを簡単に作成できます。 +以下はリモート MCP サーバーツールの最も簡単な使用例です。リモート MCP サーバーの label と URL を `hostedMcpTool` ユーティリティ関数に渡すことで、リモート MCP サーバーツールを簡単に作成できます。 -その後、`run` 関数（もしくはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行できます。 +続いて、`run` 関数（またはカスタマイズしたご自身の `Runner` インスタンスの `run` メソッド）でエージェントを実行できます: -インクリメンタルな MCP 実行結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します。 +増分的な MCP の結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します: -#### 承認フロー（オプション） +#### 任意の承認フロー -機密性の高い操作については、個々のツール呼び出しに人間の承認を要求できます。`requireApproval: 'always'` または、ツール名ごとに `'never'` / `'always'` を指定するオブジェクトを渡してください。 +センシティブな操作に対しては、個々のツール呼び出しに人による承認を必須にできます。`requireApproval: 'always'`、またはツール名を `'never'`/`'always'` に対応付ける詳細なオブジェクトのいずれかを渡してください。 -ツール呼び出しが安全かどうかをプログラムで判断できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使用して承認 / 拒否できます。人間の承認が必要な場合は、ローカルの関数ツールと同様に `interruptions` を利用した [人間の介入（HITL）アプローチ](/openai-agents-js/ja/guides/human-in-the-loop/) を使えます。 +ツール呼び出しの安全性をプログラムで判断できる場合は、[`onApproval` callback](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または拒否できます。人による承認が必要な場合は、ローカルの 関数ツール と同様に、`interruptions` を用いた同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) のアプローチを利用できます。 -動作する完全なサンプル（リモートツール / Streamable HTTP / Stdio + ストリーミング、HITL、onApproval）は GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + Streaming、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 ## 2. Streamable HTTP MCP サーバー -エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーと直接やり取りする場合は、サーバーの `url`、`name`、および任意の設定を指定して `MCPServerStreamableHttp` をインスタンス化します。 +エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーと直接通信する場合は、サーバーの `url`、`name`、および任意の設定を指定して `MCPServerStreamableHttp` をインスタンス化します: -コンストラクターでは `authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` など、MCP TypeScript SDK の追加オプションも指定できます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 +コンストラクターは、`authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` といった MCP TypeScript‑SDK の追加オプションも受け付けます。詳細は [MCP TypeScript SDK repository](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントをご覧ください。 ## 3. Stdio MCP サーバー -標準 I/O しか公開していないサーバーの場合は、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します。 +標準入出力のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します: - + + +## その他の情報 + +Streamable HTTP と Stdio のサーバーでは、`Agent` の実行ごとに、利用可能なツールを検出するために `list_tools()` を呼び出す場合があります。このラウンドトリップは（特にリモートサーバーでは）レイテンシーを増やす可能性があるため、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡して、結果をメモリにキャッシュできます。 -## その他の注意点 +ツール一覧が変わらないと確信できる場合にのみ有効にしてください。後でキャッシュを無効化するには、サーバーインスタンスで `invalidateToolsCache()` を呼び出します。 -**Streamable HTTP** と **Stdio** サーバーでは、`Agent` が実行されるたびに `list_tools()` を呼び出して利用可能なツールを取得することがあります。この往復はとくにリモートサーバーではレイテンシーを増加させるため、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡して結果をメモリにキャッシュできます。 +### ツールのフィルタリング -ツール一覧が変更されないと確信できる場合のみ有効にしてください。あとでキャッシュを無効化するには、サーバーインスタンスで `invalidateToolsCache()` を呼び出します。 +`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 08a01d27..680e6edc 100644 --- a/docs/src/content/docs/ja/guides/models.mdx +++ b/docs/src/content/docs/ja/guides/models.mdx @@ -12,29 +12,29 @@ import agentWithModelExample from '../../../../../../examples/docs/models/agentW import runnerWithModelExample from '../../../../../../examples/docs/models/runnerWithModel.ts?raw'; import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw'; -すべてのエージェントは最終的に LLM を呼び出します。SDK はモデルを次の 2 つの軽量インターフェースで抽象化しています。 +すべての エージェント は最終的に LLM を呼び出します。SDK はモデルを次の 2 つの軽量インターフェースの背後に抽象化します: -- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定 API へ _1 回_ のリクエストを行う方法を知っています -- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人が読みやすいモデル **名**（例: `'gpt-4o'`）を `Model` インスタンスへ解決します +- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して _1 件_ のリクエストを行う方法を知っています +- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読めるモデルの **名前**（例: `'gpt‑4o'`）を `Model` インスタンスに解決します -普段の開発では通常、モデル **名** と、ときどき `ModelSettings` のみを扱います。 +日々の開発では、通常はモデルの **名前** と、時折 `ModelSettings` のみを扱います。 --- ## OpenAI プロバイダー -デフォルトの `ModelProvider` は OpenAI API を使ってモデル名を解決します。次の 2 つのエンドポイントをサポートします。 +デフォルトの `ModelProvider` は OpenAI API を使って名前を解決します。2 つの異なるエンドポイントをサポートします: -| API | 用途 | `setOpenAIAPI()` の呼び出し | -| ---------------- | ---------------------------------------------------------------- | ------------------------------------------ | -| Chat Completions | 標準のチャット & 関数呼び出し | `setOpenAIAPI('chat_completions')` | -| Responses | ストリーミング優先の新しい生成 API（ツール呼び出し、柔軟な出力） | `setOpenAIAPI('responses')` _(デフォルト)_ | +| API | 用途 | 呼び出し `setOpenAIAPI()` | +| ---------------- | ------------------------------------------------------------------------ | ------------------------------------------ | +| Chat Completions | 標準的なチャットと関数呼び出し | `setOpenAIAPI('chat_completions')` | +| Responses | 新しい ストリーミング ファーストの生成 API（ツール呼び出し、柔軟な出力） | `setOpenAIAPI('responses')` _(デフォルト)_ | ### 認証 @@ -44,11 +44,11 @@ import setTracingExportApiKeyExample from '../../../../../../examples/docs/confi title="デフォルトの OpenAI キーを設定" /> -ネットワーク設定をカスタマイズしたい場合は、`setDefaultOpenAIClient(client)` で独自の `OpenAI` クライアントを差し替えることもできます。 +カスタムのネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 ### デフォルトモデル -OpenAI プロバイダーのデフォルトは `gpt-4o` です。エージェント単位またはグローバルに上書きできます。 +OpenAI プロバイダーのデフォルトは `gpt‑4o` です。エージェント単位またはグローバルに上書きできます: -`Runner` レベルの設定は、エージェント個別設定と競合した場合に優先されます。 +`Runner` レベルの設定は、エージェントごとの設定と競合する場合にそれらを上書きします。 --- -## Prompt +## プロンプト -エージェントには `prompt` パラメーターを設定できます。これはサーバーに保存されたプロンプト設定を利用してエージェントの挙動を制御するものです。現在、このオプションは OpenAI の -[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみ対応しています。 +エージェントは `prompt` パラメーターで構成でき、エージェントの動作を制御するために使用すべき サーバー 保存のプロンプト設定を指示します。現在、このオプションは OpenAI の +[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみサポートされています。 -| フィールド | 型 | 説明 | -| ----------- | -------- | -------------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | プロンプトの一意な識別子 | -| `version` | `string` | 利用したいプロンプトのバージョン | -| `variables` | `object` | プロンプトに代入するキー／値のペア。値には文字列やテキスト、画像、ファイルなどのコンテンツ入力型を指定できます | +| フィールド | 型 | 注記 | +| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | プロンプトの一意識別子 | +| `version` | `string` | 使用したいプロンプトのバージョン | +| `variables` | `object` | プロンプトに代入する変数のキー / 値の組。値は文字列、またはテキスト・画像・ファイルなどのコンテンツ入力タイプを指定できます | -ツールや instructions など、追加のエージェント設定を行うと、保存済みプロンプトの値を上書きします。 +tools や instructions などの追加のエージェント設定は、保存済みプロンプトで構成した値を上書きします。 --- ## カスタムモデルプロバイダー -独自プロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、`Runner` コンストラクターに渡すだけです。 +独自のプロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、そのプロバイダーを `Runner` のコンストラクターに渡します: -これによりトレースが [OpenAI ダッシュボード](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 ac5c1d9b..fe8b06a8 100644 --- a/docs/src/content/docs/ja/guides/multi-agent.md +++ b/docs/src/content/docs/ja/guides/multi-agent.md @@ -3,46 +3,38 @@ title: マルチエージェント description: Coordinate the flow between several agents --- -オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントを、どの順番で実行し、次に何をすべきかをどのように判断するかということです。エージェントをオーケストレーションする方法は大きく 2 つあります。 +オーケストレーションとは、アプリにおけるエージェントの流れを指します。どのエージェントが、どの順番で実行され、次に何をするかをどう決めるのかということです。エージェントをオーケストレーションする主な方法は 2 つあります。 -1. LLM に意思決定させる: これは LLM の知性を活用し、計画・推論を行い、その結果に基づいて次のステップを決定させる方法です。 -2. コードによるオーケストレーション: コードでエージェントのフローを制御する方法です。 +1. LLM に意思決定させる方法: これは、計画・推論・意思決定を行うために LLM の知能を活用し、それに基づいて次のステップを決めます +2. コードでオーケストレーションする方法: コードによってエージェントのフローを決定します -これらのパターンは組み合わせて使うこともできます。それぞれ長所と短所があり、以下で説明します。 +これらのパターンは組み合わせて使えます。それぞれにトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントとは、 instructions 、 tools 、 handoffs を備えた LLM です。つまり、自由度の高いタスクが与えられた場合でも、 LLM が自律的に計画を立て、 tools を用いてアクションを実行してデータを取得し、 handoffs を使ってサブエージェントにタスクを委譲できます。たとえば、リサーチエージェントには次のようなツールを持たせることができます。 +エージェントとは、instructions、ツール、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、 LLM はツールを用いてアクションを取りデータを取得し、ハンドオフでサブエージェントに委譲しながら、タスクに取り組む計画を自律的に立てられます。たとえば、リサーチ用のエージェントには次のようなツールを備えられます。 -- Web 検索を用いてオンライン情報を取得 -- ファイル検索とリトリーバルで社内データや接続先を検索 -- コンピュータ操作で PC 上のアクションを実行 +- Web 検索でオンラインの情報を見つける +- ファイル検索と取得で社内データや接続先を横断して検索する +- コンピュータ操作でコンピュータ上のアクションを実行する - コード実行でデータ分析を行う -- 計画立案やレポート作成などに長けた専門エージェントへの handoffs +- 計画立案、レポート作成などに優れた専門エージェントへのハンドオフ -このパターンは、タスクが自由形式であり LLM の知性に依存したい場合に最適です。ここで重要となる戦略は次のとおりです。 +このパターンは、タスクがオープンエンドで、 LLM の知能に依存したい場合に有効です。ここで重要な戦術は次のとおりです。 -1. 優れたプロンプトに投資する - 利用可能な tools 、その使い方、動作すべきパラメーターの範囲を明確にします。 -2. アプリを監視し、改善を繰り返す - 問題が発生した箇所を把握し、プロンプトを改善します。 -3. エージェントに内省させ、自己改善させる - 例として、ループで実行して自己批評させたり、エラーメッセージを与えて改善させたりします。 -4. 何でもこなす汎用エージェントより、特定タスクに特化したエージェントを用意する -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する - これにより、エージェントをトレーニングしてタスク遂行能力を向上させられます。 +1. 良いプロンプトに投資する。利用可能なツール、その使い方、およびどのパラメーターの範囲内で動作すべきかを明確にする +2. アプリを監視し、反復改善する。問題が起きる箇所を特定し、プロンプトを改善する +3. エージェントに内省と改善を許す。たとえばループで実行し自己批評させる、またはエラーメッセージを与え改善させる +4. 何でもこなす汎用エージェントではなく、1 つのタスクに特化して優れた能力を発揮する専門エージェントを用意する +5. [評価 (evals)](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練してタスク遂行能力を向上させられます ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードでオーケストレーションすると、速度・コスト・パフォーマンスの面でより決定論的かつ予測可能になります。代表的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度、コスト、パフォーマンスの観点で、より決定的かつ予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用し、コードで検査できる適切な形式のデータを生成する - たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに応じて次のエージェントを選択します。 -- 複数のエージェントを連鎖させる - 1 つのエージェントの出力を次のエージェントの入力に変換します。例えばブログ記事を書くタスクを、リサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善という一連のステップに分割できます。 -- タスクを実行するエージェントと評価・フィードバックを行うエージェントを `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 4c780a05..a1005dd8 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,25 +19,27 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm init -y ``` -2. Agents SDK をインストールします。 +2. Agents SDK をインストールします ```bash npm install @openai/agents 'zod@<=3.25.67' ``` -3. OpenAI API キーを設定します。まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。 +3. OpenAI API キーを設定します。まだ持っていない場合は、[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください ```bash export OPENAI_API_KEY=sk-... ``` - あるいは、`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'; @@ -49,11 +51,11 @@ const agent = new Agent({ }); ``` -## はじめてのエージェントを実行する +## はじめてのエージェントの実行 -`run` メソッドを使ってエージェントを実行できます。実行を開始するには、開始したいエージェントと渡したい入力の両方を渡します。 +`run` メソッドでエージェントを実行できます。開始したいエージェントと渡したい入力の両方を指定して実行を開始します。 -これにより、その実行中に行われた最終出力とすべてのアクションを含む result が返されます。 +これにより、その実行中に行われた最終出力とすべてのアクションを含む 実行結果 が返されます。 ```typescript import { Agent, run } from '@openai/agents'; @@ -69,9 +71,9 @@ const result = await run(agent, 'When did sharks first appear?'); console.log(result.finalOutput); ``` -## エージェントにツールを持たせる +## エージェントへのツールの付与 -エージェントにツールを与えて、情報を検索したりアクションを実行したりさせることができます。 +情報の参照やアクションの実行に使えるツールをエージェントに与えられます。 ```typescript import { Agent, tool } from '@openai/agents'; @@ -98,9 +100,9 @@ const agent = new Agent({ }); ``` -## さらにエージェントを追加する +## いくつかのエージェントの追加 -追加のエージェントを同様に定義して、問題をより小さな部分に分割し、タスクに集中させることができます。また、エージェントごとにモデルを定義することで、異なる問題に異なるモデルを使用できます。 +追加のエージェントを同様に定義して、問題を小さな部分に分割し、エージェントが目の前のタスクにより集中できるようにします。また、エージェントごとにモデルを定義することで、問題ごとに異なるモデルを使うこともできます。 ```typescript const historyTutorAgent = new Agent({ @@ -116,9 +118,9 @@ const mathTutorAgent = new Agent({ }); ``` -## ハンドオフを定義する +## ハンドオフの定義 -複数のエージェント間でオーケストレーションを行うために、エージェントに `handoffs` を定義できます。これにより、実行中に会話が自動的に次のエージェントへ引き継がれます。 +複数のエージェントをオーケストレーションするために、エージェントに `handoffs` を定義できます。これにより、実行の過程で次のエージェントへ会話を自動的に引き継げるようになります。 ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -130,11 +132,11 @@ const triageAgent = Agent.create({ }); ``` -実行後、`finalAgent` プロパティを見ることで、最終的な応答を生成したエージェントを確認できます。 +実行後は、実行結果 の `finalAgent` プロパティを見ることで、どのエージェントが最終応答を生成したかがわかります。 -## エージェントオーケストレーションを実行する +## エージェントオーケストレーションの実行 -Runner は個々のエージェントの実行、ハンドオフの可能性、ツールの実行を管理します。 +Runner は個々のエージェントの実行、必要に応じたハンドオフやツール実行の処理を担当します。 ```typescript import { run } from '@openai/agents'; @@ -147,22 +149,23 @@ async function main() { main().catch((err) => console.error(err)); ``` -## すべてをまとめる +## 全体のまとめ -これまでの内容を 1 つの例にまとめましょう。`index.js` に配置して実行してください。 +すべてを `index.js` にまとめて実行してみましょう。 -## トレースを確認する +## トレースの確認 -Agents SDK はトレースを自動的に生成します。これにより、エージェントがどのように動作したか、どのツールを呼び出したか、どのエージェントへハンドオフしたかを確認できます。 +Agents SDK は自動的にトレースを生成します。これにより、エージェントがどのように動作し、どのツールを呼び出し、どのエージェントにハンドオフしたかを確認できます。 -エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace ビューア](https://platform.openai.com/traces) に移動してください。 +エージェントの実行中に何が起こったかを確認するには、 +[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動してください。 ## 次のステップ より複雑なエージェントフローの構築方法を学びましょう: -- [エージェント](/openai-agents-js/ja/guides/agents) の設定方法を学ぶ +- [エージェント](/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 dcb4f674..132ab852 100644 --- a/docs/src/content/docs/ja/guides/release.mdx +++ b/docs/src/content/docs/ja/guides/release.mdx @@ -5,17 +5,17 @@ description: Learn how we version and release the SDK and recent changes. ## バージョニング -本プロジェクトでは、若干変更したセマンティックバージョニングを採用しており、形式は `0.Y.Z` です。先頭の `0` は SDK がまだ急速に進化していることを示しています。各コンポーネントのインクリメント方法は次のとおりです。 +このプロジェクトは、形式 `0.Y.Z` を用いた、セマンティック バージョニングをやや変更した方式に従います。先頭の `0` は、SDK がまだ急速に進化していることを示します。各コンポーネントの増分は次のとおりです: -## マイナー (`Y`) バージョン +## マイナー（`Y`）バージョン -ベータではない公開インターフェースに **破壊的変更** が入る場合、マイナーバージョン `Y` を増やします。たとえば `0.0.x` から `0.1.x` へのアップデートには破壊的変更が含まれる可能性があります。 +ベータとマークされていない公開インターフェースに対する **後方互換性のない変更** の場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への変更には後方互換性のない変更が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` にピン留めすることをおすすめします。 +後方互換性のない変更を避けたい場合は、プロジェクトで `0.0.x` のバージョンに固定することをおすすめします。 -## パッチ (`Z`) バージョン +## パッチ（`Z`）バージョン -`Z` は非破壊的変更で増やします +後方互換性を損なわない変更では `Z` を増やします: - バグ修正 - 新機能 @@ -24,11 +24,11 @@ description: Learn how we version and release the SDK and recent changes. ## サブパッケージのバージョニング -メインパッケージ `@openai/agents` は、独立して利用できる複数のサブパッケージで構成されています。現時点では、パッケージのバージョンはリンクされており、いずれかのパッケージがバージョンアップすると他も同様に上がります。`1.0.0` に向けて、この戦略を変更する可能性があります。 +メインの `@openai/agents` パッケージは、個別に利用できる複数のサブパッケージで構成されています。現時点では、各パッケージのバージョンは連動しており、あるパッケージのバージョンが上がると他も同様に上がります。`1.0.0` への移行に伴い、この戦略を変更する可能性があります。 -## 変更履歴 (Changelog) +## 変更履歴 -各サブパッケージの変更点を把握できるよう、個別に changelog を生成しています。変更がサブパッケージ内で行われた場合、詳細を確認するには該当する changelog をご覧ください。 +変更点の把握に役立つよう、各サブパッケージごとに変更履歴を生成しています。変更がサブパッケージ内で行われる場合があるため、詳細は該当する変更履歴をご確認ください。 - [`@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 8a5c7629..d59adc86 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -7,84 +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) を行うと、次のいずれかが返されます: -- `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) ガイドも参照してください。 +- [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) は、`stream: true` なしで `run` を呼び出した場合 +- [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult) は、`stream: true` ありで `run` を呼び出した場合。ストリーミングの詳細は [ストリーミング](/openai-agents-js/ja/guides/streaming) も参照してください ## 最終出力 -`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が入ります。内容は次のいずれかです。 +プロパティ `finalOutput` には、最後に実行されたエージェントの最終出力が含まれます。この結果は次のいずれかです: -- `string` — `outputType` が定義されていないエージェントのデフォルト -- `unknown` — 出力タイプとして JSON スキーマが定義されている場合。JSON はパースされていますが、型検証は手動で行う必要があります -- `z.infer` — 出力タイプとして Zod スキーマが定義されている場合。出力は自動でこのスキーマに対してパースされます -- `undefined` — エージェントが出力を生成しなかった場合（たとえば途中で停止した場合など） +- `string` — `outputType` が定義されていないエージェントの既定値 +- `unknown` — エージェントの出力タイプとして JSON スキーマが定義されている場合。この場合 JSON はパースされていますが、型の検証は手動で行う必要があります +- `z.infer` — エージェントの出力タイプとして Zod スキーマが定義されている場合。出力はこのスキーマに対して自動的にパースされます +- `undefined` — エージェントが出力を生成しなかった場合（たとえば、出力を生成する前に停止した場合） -複数の出力タイプを持つハンドオフを使用している場合は、`new Agent()` コンストラクターではなく `Agent.create()` メソッドを使ってエージェントを作成してください。 +異なる出力タイプのハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクタではなく `Agent.create()` メソッドを使用してください。 -これにより SDK がすべてのハンドオフにわたる出力タイプを推論し、`finalOutput` プロパティにユニオン型を提供します。 +これにより SDK が、起こりうるすべてのハンドオフをまたいで出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 例: -## 次のターンへの入力 +## 次のターンの入力 -次のターンに渡す入力は、次の２通りで取得できます。 +次のターンの入力にアクセスする方法は 2 つあります: -- `result.history` — 入力とエージェントの出力の両方を含む履歴のコピー -- `result.output` — エージェント実行全体の出力 +- `result.history` — 入力とエージェントの出力の両方のコピーを含みます +- `result.output` — エージェント全体の実行出力を含みます -チャットのようなユースケースでは `history` を使うと全履歴を簡単に保持できます。 +`history` は、チャットのようなユースケースで完全な履歴を維持するための便利な手段です: - + -## 最後に実行されたエージェント +## 最後のエージェント -`lastAgent` プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、ユーザーが次に入力した際にこれが役立つことがあります。たとえば一次受付エージェントが言語別エージェントへハンドオフする場合、`lastAgent` を保存しておけば次回のユーザーメッセージで再利用できます。 +プロパティ `lastAgent` には、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回 ユーザー が何かを入力する際に役立つことがよくあります。たとえば、一次トリアージ用のエージェントが言語別のエージェントへハンドオフする構成の場合、最後のエージェントを保存しておき、次回 ユーザー がメッセージを送るときに再利用できます。 -ストリーミングモードでは、現在実行中のエージェントを示す `currentAgent` プロパティも便利です。 +ストリーミング モードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスするのも有用です。 -## 新しいアイテム +## 新規アイテム -`newItems` プロパティには、実行中に生成された新しいアイテムが入ります。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) で、LLM が生成した元アイテムをラップしています。これにより、LLM の出力に加え、それぞれのイベントがどのエージェントに紐づくかを確認できます。 +プロパティ `newItems` には、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。ランアイテムは、LLM が生成した 元 のアイテムをラップします。これらを使うと、LLM の出力に加えて、これらのイベントがどのエージェントに関連付けられていたかにもアクセスできます。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元アイテムは生成されたメッセージです -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は 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 がツール呼び出しの承認を求めたことを示します。元アイテムはツール呼び出しアイテムです +- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は、LLM からのメッセージを示します。元のアイテムは生成されたメッセージです +- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は、LLM がハンドオフ ツールを呼び出したことを示します。元のアイテムは LLM からのツール呼び出し項目です +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) は、ハンドオフが発生したことを示します。元のアイテムはハンドオフ ツール呼び出しに対するツールの応答です。アイテムから送信元/宛先のエージェントにもアクセスできます +- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は、LLM がツールを起動したことを示します +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) は、ツールが呼び出されたことを示します。元のアイテムはツールの応答です。アイテムからツールの出力にもアクセスできます +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は、LLM の推論項目を示します。元のアイテムは生成された推論です +- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は、LLM がツール呼び出しの承認を要求したことを示します。元のアイテムは LLM からのツール呼び出し項目です ## 状態 -`state` プロパティには実行の状態が入ります。`result` に付随する情報の多くは `state` から派生していますが、`state` 自体はシリアライズ／デシリアライズ可能で、[エラーから復旧](/openai-agents-js/ja/guides/running-agents#exceptions) する場合や [`interruption`](#interruptions) に対処する場合に、次回の `run` 呼び出しへの入力としても利用できます。 +プロパティ `state` には、実行の状態が含まれます。`result` に付随する多くは `state` から導出されていますが、`state` はシリアライズ/デシリアライズ可能で、[エラーから復旧する](/openai-agents-js/ja/guides/running-agents#exceptions) 必要がある場合や、[`interruption`](#interruptions) に対処する場合に、後続の `run` 呼び出しの入力としても使用できます。 ## 割り込み -エージェントで `needsApproval` を使用している場合、`run` は進行前に処理すべき `interruptions` を発生させることがあります。その場合 `interruptions` は割り込みを引き起こした `ToolApprovalItem` の配列になります。割り込みの扱いについて詳しくは [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) ガイドをご覧ください。 +エージェントで `needsApproval` を使用している場合、続行前に処理が必要な `interruptions` が `run` をトリガーすることがあります。その場合、`interruptions` は割り込みの原因となった `ToolApprovalItem` の配列になります。割り込みの扱い方については、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) を参照してください。 ## その他の情報 -### Raw responses +### 元のレスポンス -`rawResponses` プロパティには、エージェント実行中にモデルが生成した生の LLM レスポンスが入ります。 +プロパティ `rawResponses` には、エージェントの実行中にモデルが生成した LLM の 元 のレスポンスが含まれます。 -### Last response ID +### 最後のレスポンス ID -`lastResponseId` プロパティには、エージェント実行中にモデルが最後に生成したレスポンスの ID が入ります。 +プロパティ `lastResponseId` には、エージェントの実行中にモデルが生成した最後のレスポンスの ID が含まれます。 -### Guardrail results +### ガードレールの実行結果 -`inputGuardrailResults` と `outputGuardrailResults` プロパティには、ガードレールの結果が格納されます（ある場合）。ガードレール結果にはログ保存などに役立つ情報が含まれることがあるため、アクセス可能にしています。 +プロパティ `inputGuardrailResults` と `outputGuardrailResults` には、該当する場合はガードレールの結果が含まれます。ガードレールの結果には、記録や保存したい有用な情報が含まれることがあるため、これらを利用できるようにしています。 -### Original input +### 元の入力 -`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 504e639c..3b66df09 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -9,111 +9,111 @@ import helloWorldExample from '../../../../../../examples/docs/hello-world.ts?ra import runningAgentsExceptionExample from '../../../../../../examples/docs/running-agents/exceptions1.ts?raw'; import chatLoopExample from '../../../../../../examples/docs/running-agents/chatLoop.ts?raw'; -エージェントは単体では何もしません。`Runner` クラスまたは `run()` ユーティリティを使って **実行** します。 +エージェント は単体では何もしません — `Runner` クラスまたは `run()` ユーティリティで **実行** します。 - + -カスタム Runner が不要な場合は `run()` ユーティリティを使用できます。これはシングルトンのデフォルト `Runner` インスタンスでエージェントを実行します。 +カスタム Runner が不要な場合は、シングルトンの既定の `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. 現在の入力で現在のエージェントのモデルを呼び出す -2. LLM の応答を確認する - - **最終出力** → 返却 - - **ハンドオフ** → 新しいエージェントに切り替え、蓄積した会話履歴を保持して 1 に戻る - - **ツール呼び出し** → ツールを実行し、その結果を会話に追加して 1 に戻る -3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローする +1. 現在の入力で現在の エージェント のモデルを呼び出す +2. LLM 応答を検査する + - **最終出力** → 返す + - **ハンドオフ** → 新しい エージェント に切り替え、これまでの会話履歴は保持し、1 に戻る + - **ツール呼び出し** → ツールを実行し、その結果を会話に追加して、1 に戻る +3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を投げる ### Runner のライフサイクル -アプリ起動時に `Runner` を作成し、リクエスト間で再利用してください。このインスタンスはモデルプロバイダーやトレーシング設定などのグローバル設定を保持します。まったく異なる設定が必要な場合のみ別の `Runner` を作成します。簡単なスクリプトでは内部でデフォルト Runner を使う `run()` を呼び出すだけでも構いません。 +アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデル プロバイダーやトレーシング オプションなどのグローバル設定を保持します。完全に異なるセットアップが必要な場合のみ、別の `Runner` を作成してください。簡単なスクリプトでは、内部で既定の Runner を使う `run()` を呼び出すこともできます。 -## Run 引数 +## run の引数 -`run()` メソッドの入力は、開始エージェント・実行入力・オプションのセットです。 +`run()` メソッドへの入力は、開始時の エージェント、実行の入力、そして一連のオプションです。 -入力は文字列、[入力アイテム](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [Human in the loop](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトを指定できます。 +入力は文字列（ユーザー メッセージとして扱われます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) エージェント を構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトを指定できます。 -追加オプション: +追加のオプション: -| Option | Default | 説明 | -| ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `stream` | `false` | `true` の場合、`StreamedRunResult` を返し、モデルから届いたイベントをストリーミングします | -| `context` | – | すべてのツール / ガードレール / ハンドオフに転送されるコンテキストオブジェクト。詳細は [コンテキスト管理](/openai-agents-js/ja/guides/context) | -| `maxTurns` | `10` | 安全上限。到達すると [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローします | -| `signal` | – | キャンセル用の `AbortSignal` | +| Option | Default | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから届くイベントを順次発行します | +| `context` | – | すべてのツール / ガードレール / ハンドオフに転送されるコンテキスト オブジェクト。詳細は [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 | +| `maxTurns` | `10` | セーフティ リミット — 到達すると [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を投げます | +| `signal` | – | キャンセル用の `AbortSignal` | ## ストリーミング -ストリーミングを有効にすると、LLM が実行される間にイベントを逐次受け取れます。ストリーム開始後、`StreamedRunResult` にはすべての新しい出力を含む実行情報が格納されます。`for await` ループでストリーミングイベントを反復処理できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) ガイドを参照してください。 +ストリーミング を使うと、LLM 実行中のストリーミング イベントも受け取れます。ストリーム開始後、`StreamedRunResult` には、生成された新しい出力を含む実行に関する完全な情報が含まれます。`for await` ループを使ってストリーミング イベントを反復処理できます。詳細は [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 ## Run 設定 -独自の `Runner` インスタンスを作成する場合は、`RunConfig` オブジェクトで Runner を設定できます。 - -| Field | Type | 目的 | -| --------------------------- | --------------------- | --------------------------------------------------------------------- | -| `model` | `string \| Model` | すべてのエージェントに対して特定のモデルを強制使用 | -| `modelProvider` | `ModelProvider` | モデル名を解決。デフォルトは OpenAI プロバイダー | -| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルチューニングパラメーター | -| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ時に入力アイテムを変換（ハンドオフ側で未定義の場合） | -| `inputGuardrails` | `InputGuardrail[]` | _初期_ ユーザー入力に適用するガードレール | -| `outputGuardrails` | `OutputGuardrail[]` | _最終_ 出力に適用するガードレール | -| `tracingDisabled` | `boolean` | OpenAI Tracing を完全に無効化 | -| `traceIncludeSensitiveData` | `boolean` | LLM / ツールの入出力をトレースから除外しつつスパンは発行 | -| `workflowName` | `string` | Traces ダッシュボードに表示される名前。関連する実行をまとめる際に便利 | -| `traceId` / `groupId` | `string` | SDK に任せず手動でトレース ID / グループ ID を指定 | -| `traceMetadata` | `Record` | すべてのスパンに付与する任意メタデータ | +独自の `Runner` インスタンスを作成する場合は、Runner を構成するために `RunConfig` オブジェクトを渡せます。 + +| Field | Type | Purpose | +| --------------------------- | --------------------- | -------------------------------------------------------------------------------------- | +| `model` | `string \| Model` | 実行内の **すべて** の エージェント に特定のモデルを強制します | +| `modelProvider` | `ModelProvider` | モデル名を解決します — 既定は OpenAI プロバイダーです | +| `modelSettings` | `ModelSettings` | エージェント ごとの設定を上書きするグローバルなチューニング パラメーター | +| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフの実行時に入力アイテムを変更します（ハンドオフ側で既に定義されていない場合） | +| `inputGuardrails` | `InputGuardrail[]` | _初回_ の ユーザー 入力に適用される ガードレール | +| `outputGuardrails` | `OutputGuardrail[]` | _最終_ 出力に適用される ガードレール | +| `tracingDisabled` | `boolean` | OpenAI Tracing を完全に無効化します | +| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、トレースから LLM / ツール の入力と出力を除外します | +| `workflowName` | `string` | Traces ダッシュボードに表示 — 関連する実行のグルーピングに役立ちます | +| `traceId` / `groupId` | `string` | SDK に生成させず、トレース ID またはグループ ID を手動で指定します | +| `traceMetadata` | `Record` | すべてのスパンに添付する任意のメタデータ | ## 会話 / チャットスレッド -`runner.run()`（または `run()` ユーティリティ）の呼び出しは、アプリケーションレベルで 1 **ターン** を表します。エンドユーザーにどこまで `RunResult` を見せるかは自由です―`finalOutput` のみを表示する場合もあれば、生成されたすべてのアイテムを表示する場合もあります。 +`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーション レベルの会話における 1 回の **ターン** を表します。エンド ユーザー にどの程度 `RunResult` を見せるかは任意で、`finalOutput` のみの場合もあれば、生成されたすべてのアイテムを見せる場合もあります。 - + -対話版は [チャットのコード例](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 +インタラクティブ版は [チャットの sample code](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 cc46e435..e7c72aad 100644 --- a/docs/src/content/docs/ja/guides/streaming.mdx +++ b/docs/src/content/docs/ja/guides/streaming.mdx @@ -9,61 +9,132 @@ import nodeTextStreamExample from '../../../../../../examples/docs/streaming/nod import handleAllEventsExample from '../../../../../../examples/docs/streaming/handleAllEvents.ts?raw'; import streamedHITLExample from '../../../../../../examples/docs/streaming/streamedHITL.ts?raw'; -Agents SDK は、モデルからの出力やその他の実行ステップを段階的に配信できます。ストリーミングを利用すると、UI が応答性を維持し、最終的な実行結果をすべて待たずにユーザーを更新できます。 +Agents SDK は、モデルおよびその他の実行ステップからの出力を段階的に配信できます。ストリーミングにより UI の応答性を保ち、ユーザーの表示を更新する前に最終的な実行結果全体を待つことを避けられます。 ## ストリーミングの有効化 -`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミングオブジェクトが返されます。 +`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミングオブジェクトを取得できます: -ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装しています。各イベントは実行中に発生した内容を示すオブジェクトとして出力されます。ただし多くのアプリケーションはモデルのテキストのみを必要とするため、ストリームには補助メソッドが用意されています。 +ストリーミングを有効にすると、返される `stream` は `AsyncIterable` インターフェースを実装します。生成されるそれぞれのイベントは、実行中に何が起きたかを記述するオブジェクトです。ストリームは 3 種類のイベントタイプのいずれかを出力し、各タイプはエージェントの実行の異なる部分を表します。とはいえ、ほとんどのアプリケーションが必要とするのはモデルのテキストだけなので、ストリームにはそのためのヘルパーが用意されています。 ### テキスト出力の取得 -`stream.toTextStream()` を呼び出すと、生成されたテキストのストリームを取得できます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js `Readable` です。そのまま `process.stdout` などへパイプできます。 +`stream.toTextStream()` を呼び出すと、出力されたテキストのストリームを取得できます。`compatibleWithNodeStreams` が `true` のとき、戻り値は通常の Node.js `Readable` です。`process.stdout` や別の送信先に直接パイプできます。 -`stream.completed` という Promise は、実行とすべての保留中コールバックが完了した時点で解決されます。出力が残っていないことを保証したい場合は必ず await してください。 +`stream.completed` という Promise は、実行と保留中のすべてのコールバックが完了すると解決されます。出力がもうないことを確実にしたい場合は、必ずそれを await してください。 ### すべてのイベントのリッスン -`for await` ループを使用して、到着した各イベントを検査できます。低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などが含まれます。 +`for await` ループを使って、到着した各イベントを検査できます。有用な情報として、低レベルのモデルイベント、エージェントの切り替え、そして SDK 固有の実行情報が含まれます: -完全なスクリプトは、[ストリーミングのコード例](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。プレーンテキストストリームと元イベントストリームの両方を出力します。 - -## ストリーミング中の Human in the loop - -ストリーミングは、実行を一時停止するハンドオフ（たとえばツールの承認が必要な場合）と互換性があります。ストリームオブジェクトの `interruption` フィールドで割り込みを取得し、それぞれに対して `state.approve()` または `state.reject()` を呼び出すことで実行を続行できます。再度 `{ stream: true }` を指定して実行すると、ストリーミング出力が再開されます。 +プレーンテキストのストリームと元のイベントストリームの両方を出力する完全なスクリプトについては、[ストリーミングの sample code](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。 + +## イベントタイプ + +このストリームは 3 種類のイベントタイプを出力します: + +### raw_model_stream_event + +```ts +type RunRawModelStreamEvent = { + type: 'raw_model_stream_event'; + data: ResponseStreamEvent; +}; +``` + +例: + +```json +{ + "type": "raw_model_stream_event", + "data": { + "type": "output_text_delta", + "delta": "Hello" + } +} +``` + +### run_item_stream_event + +```ts +type RunItemStreamEvent = { + type: 'run_item_stream_event'; + name: RunItemStreamEventName; + item: RunItem; +}; +``` + +ハンドオフのペイロード例: + +```json +{ + "type": "run_item_stream_event", + "name": "handoff_occurred", + "item": { + "type": "handoff_call", + "id": "h1", + "status": "completed", + "name": "transfer_to_refund_agent" + } +} +``` + +### agent_updated_stream_event + +```ts +type RunAgentUpdatedStreamEvent = { + type: 'agent_updated_stream_event'; + agent: Agent; +}; +``` + +例: + +```json +{ + "type": "agent_updated_stream_event", + "agent": { + "name": "Refund Agent" + } +} +``` + +## ストリーミング中の Human in the loop (人間の介入) + +ストリーミングは、実行を一時停止するハンドオフと互換性があります（たとえばツールに承認が必要な場合）。ストリームオブジェクト上の `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 f39b579e..12bd3c21 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,107 +10,115 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -ツールを使うと、エージェントは **アクションを実行** できます ― データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータ操作まで行えます。JavaScript / TypeScript SDK では次の 4 つのカテゴリーをサポートしています: +ツールは、エージェント が **アクション** を実行できるようにします — データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの使用まで。JavaScript/TypeScript SDK は次の 4 つの カテゴリー をサポートします: -1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと並行して実行されます (Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成) -2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM から呼び出せるようにします -3. **エージェントをツールとして使用** – エージェント全体を呼び出し可能なツールとして公開します -4. **ローカル MCP サーバー** – お使いのマシンで動作する Model Context Protocol サーバーを接続します +1. **組み込みツール（Hosted）** — モデルと同じ OpenAI サーバー 上で動作します。 _(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_ +2. **関数ツール** — 任意のローカル関数を JSON スキーマでラップし、 LLM が呼び出せるようにします +3. **ツールとしてのエージェント** — エージェント 全体を呼び出し可能なツールとして公開します +4. **ローカル MCP サーバー** — 手元のマシンで動作する Model Context Protocol サーバー を接続します --- ## 1. 組み込みツール（Hosted） -`OpenAIResponsesModel` を使用すると、以下の組み込みツールを追加できます: +`OpenAIResponsesModel` を使うと、次の組み込みツールを追加できます: -| ツール | 型文字列 | 目的 | -| --------------------------- | -------------------- | --------------------------------------- | -| Web 検索 | `'web_search'` | インターネット検索 | -| ファイル / リトリーバル検索 | `'file_search'` | OpenAI がホストするベクトルストアを検索 | -| コンピュータ操作 | `'computer'` | GUI 操作を自動化 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | -| 画像生成 | `'image_generation'` | テキストに基づいて画像を生成 | +| ツール | タイプ文字列 | 目的 | +| --------------------------- | -------------------- | ----------------------------------------- | +| 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` | No | 省略時は関数名 (例: `get_weather`) が使用されます | -| `description` | Yes | LLM に表示される、わかりやすい説明文 | -| `parameters` | Yes | Zod スキーマまたは元の JSON スキーマオブジェクト。Zod スキーマを使うと **strict** モードが自動で有効になります | -| `strict` | No | `true` (デフォルト) で、引数の検証に失敗した場合 SDK はモデルエラーを返します。曖昧な入力を許可したい場合は `false` に設定 | -| `execute` | Yes | `(args, context) => string \| Promise` – ビジネスロジックを実装します。第 2 引数は省略可能な `RunContext` | -| `errorFunction` | No | 内部エラーをユーザー向けメッセージに変換するカスタムハンドラ `(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 スキーマ ツール -無効または部分的な入力をモデルに _推測_ させたい場合は、strict モードを無効にします: +不正確または不完全な入力をモデルに推測させたい場合は、 元 JSON スキーマ 使用時に strict モードを無効化できます: --- -## 3. エージェントをツールとして使用 +## 3. ツールとしてのエージェント -会話を完全にハンドオフすることなく、あるエージェントが別のエージェントを _支援_ してほしい場合は `agent.asTool()` を使います: +会話を完全に ハンドオフ せずに、ある エージェント が別の エージェント を支援してほしい場合があります。`agent.asTool()` を使います: - + -SDK が内部で行う処理: +内部的には、SDK は次を行います: -- `input` という 1 つのパラメーターを持つ関数ツールを生成 -- ツールが呼び出されるとサブエージェントをその入力で実行 -- `customOutputExtractor` があれば抽出した出力を、なければ最後のメッセージを返却 +- 単一の `input` パラメーター を持つ 関数ツール を作成 +- ツールが呼び出されると、その入力でサブ エージェント を実行 +- 最後のメッセージ、または `customOutputExtractor` で抽出した出力を返す --- ## 4. ローカル MCP サーバー -ローカルの [Model Context Protocol](https://modelcontextprotocol.io/) サーバー経由でツールを公開し、エージェントに接続できます。`MCPServerStdio` を使用してサーバーを起動・接続します: +ローカルの [Model Context Protocol](https://modelcontextprotocol.io/) サーバー を通じてツールを公開し、エージェント に接続できます。`MCPServerStdio` を使って サーバー を起動・接続します: - + -完全な例は [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) をご覧ください。 +完全な code examples は [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) を参照してください --- ## ツール使用時の挙動 -モデルがツールを **いつ、どのように** 使用すべきか (`tool_choice`, `toolUseBehavior` など) の制御については、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください。 +モデルがいつ、どのようにツールを使用すべきかを制御する方法は、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください（`tool_choice`、`toolUseBehavior` など） --- ## ベストプラクティス -- **短く明示的な説明** – ツールが _何をするか_ と _いつ使うか_ を記述 -- **入力を検証** – 可能な限り Zod スキーマで厳格な JSON 検証を行う -- **エラーハンドラで副作用を避ける** – `errorFunction` は有用な文字列を返すだけにし、例外を投げない -- **ツールは単一責務** – 小さく構成可能なツールの方がモデルの推論精度が向上 +- **短く明確な説明** — ツールが 何をするか と いつ使うか を記述 +- **入力を検証** — 可能な限り厳密な JSON 検証のために Zod スキーマを使用 +- **エラーハンドラーで副作用を避ける** — `errorFunction` は例外を投げず、有用な文字列を返すべき +- **ツールは 1 つの責務** — 小さく合成可能なツールはモデルの推論を改善 --- ## 次のステップ -- [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) について学ぶ -- [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加してツールの入力または出力を検証 -- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツール型の TypeDoc リファレンスを詳しく読む +- [エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) で強制的なツール使用について学ぶ +- ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 +- [`tool()`](/openai-agents-js/openai/agents/functions/tool) の TypeDoc リファレンスや、各種 組み込みツール（Hosted） の型を参照 diff --git a/docs/src/content/docs/ja/guides/tracing.mdx b/docs/src/content/docs/ja/guides/tracing.mdx index 8066dce6..78e71e09 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` と組み合わせて force flush を呼び出すことで、ワーカーが終了する前にトレースを確実にエクスポートできます。 +例えば Cloudflare Worker では、コードを `try/catch/finally` ブロックでラップし、`waitUntil` と併用して強制フラッシュすることで、ワーカーが終了する前にトレースがエクスポートされるようにします。 -## Trace と Span +## トレースとスパン -- **Trace** は 1 回のワークフロー全体 (end-to-end) の操作を表し、複数の Span で構成されます。Trace には次のプロパティがあります: - - `workflow_name`: 論理的なワークフローまたはアプリ名 例: "Code generation" や "Customer service" - - `trace_id`: Trace の一意 ID。指定しない場合は自動生成され、形式は `trace_<32_alphanumeric>` - - `group_id`: 同じ会話からの複数トレースを関連付けるオプションのグループ ID。たとえばチャットスレッド ID など - - `disabled`: `true` の場合、この Trace は記録されない - - `metadata`: Trace 用の任意メタデータ -- **Span** は開始時刻と終了時刻を持つ操作を表します。Span には次のプロパティがあります: +- **トレース** は「ワークフロー」のエンドツーエンドの 1 回の操作を表します。スパンで構成されます。トレースには次のプロパティがあります: + - `workflow_name`: これは論理的なワークフローまたはアプリです。例えば "Code generation" や "Customer service" + - `trace_id`: トレースの一意の ID。渡さなかった場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります + - `group_id`: オプションのグループ ID。同じ会話からの複数のトレースをリンクするために使用します。例えば、チャットスレッドの ID を使えます + - `disabled`: True の場合、トレースは記録されません + - `metadata`: トレース用のオプションのメタデータ +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります: - `started_at` と `ended_at` のタイムスタンプ - - 所属する Trace を示す `trace_id` - - 親 Span を指す `parent_id`（存在する場合） - - Span の情報を保持する `span_data`。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など + - 所属するトレースを示す `trace_id` + - このスパンの親スパン（存在する場合）を指す `parent_id` + - スパンに関する情報である `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) を設定して、トレースを他の送信先にプッシュできます（置き換えまたはセカンダリの送信先として） ### 音声エージェントのトレーシング -デフォルトの OpenAI Realtime API で `RealtimeAgent` と `RealtimeSession` を使用している場合、`RealtimeSession` で `tracingDisabled: true` を指定するか環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を設定しない限り、トレーシングは Realtime API 側で自動的に実行されます。 +デフォルトの OpenAI Realtime API とともに `RealtimeAgent` および `RealtimeSession` を使用している場合、`RealtimeSession` で `tracingDisabled: true` を指定するか、環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を使用して無効化しない限り、トレーシングは Realtime API 側で自動的に行われます。 -詳細は [音声エージェントの概要](/openai-agents-js/guides/voice-agents) を参照してください。 +詳しくは、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 -## 上位レベルのトレース +## より高レベルのトレース -複数回の `run()` 呼び出しを 1 つの Trace にまとめたい場合は、コード全体を `withTrace()` でラップします。 +複数の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。コード全体を `withTrace()` でラップすれば実現できます。 -1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、それぞれの実行は個別の Trace を作成せず、全体 Trace の一部になります。 +1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります -## Trace の作成 +## トレースの作成 -[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数で Trace を作成できます。あるいは `getGlobalTraceProvider().createTrace()` で新しい Trace を手動作成し、それを `withTrace()` に渡す方法もあります。 +トレースは [`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数で作成できます。あるいは、`getGlobalTraceProvider().createTrace()` を使って手動で新しいトレースを作成し、それを `withTrace()` に渡すこともできます。 -現在の Trace は [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage)（または各環境のポリフィル）で管理されるため、自動的に並行処理に対応します。 +現在のトレースは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルを通じて追跡されます。これにより、並行実行でも自動的に機能します。 -## Span の作成 +## スパンの作成 -`createGenerationSpan()` や `createFunctionSpan()` などの `create*Span()` メソッドで Span を作成できます。通常は手動で Span を作成する必要はありません。カスタム情報を追跡したい場合は [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) を使用できます。 +各種 `create*Span()`（例: `createGenerationSpan()`, `createFunctionSpan()` など）のメソッドでスパンを作成できます。一般的には、手動でスパンを作成する必要はありません。カスタムスパン情報を追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数も利用できます。 -Span は自動的に現在の Trace に属し、最も近い現在の Span の子としてネストされます。この情報も [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) で管理されます。 +スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの下にネストされます。これは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルによって追跡されます。 -## 機密データ +## 機微なデータ -一部の Span では機密データが記録される可能性があります。 +一部のスパンは、機微なデータを取り込む可能性があります。 -`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/) を設定し、Trace / Span をバッチで [`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) - 追加のトレースプロセッサーを登録し、Trace / Span が準備でき次第受け取れるようにします。これにより、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` を含めない限り、トレースは OpenAI のバックエンドに送信されません -## 外部トレースプロセッサー一覧 +## 外部トレーシングプロセッサー一覧 - [AgentOps](https://docs.agentops.ai/v2/usage/typescript-sdk#openai-agents-integration) - [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agents-sdk-js) diff --git a/docs/src/content/docs/ja/guides/troubleshooting.mdx b/docs/src/content/docs/ja/guides/troubleshooting.mdx index ea8a4b12..b2d0872e 100644 --- a/docs/src/content/docs/ja/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ja/guides/troubleshooting.mdx @@ -3,38 +3,38 @@ title: トラブルシューティング description: Learn how to troubleshoot issues with the OpenAI Agents SDK. --- -## 対応環境 +## サポートされる環境 -OpenAI Agents SDK は次のサーバー環境でサポートされています: +OpenAI Agents SDK は次のサーバー環境でサポートされます: - Node.js 22+ - Deno 2.35+ - Bun 1.2.5+ -### 制限付きサポート +### 制限付きのサポート -- **Cloudflare Workers**: Agents SDK は Cloudflare Workers でも利用できますが、現在は次の制限があります: - - SDK では現在 `nodejs_compat` を有効にする必要があります - - リクエストの終了時にトレースを手動でフラッシュする必要があります。詳細は [トレーシング ガイド](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください - - Cloudflare Workers では `AsyncLocalStorage` のサポートが限定的なため、一部のトレースが正確でない可能性があります -- **ブラウザ**: - - ブラウザでは現在トレーシングはサポートされていません +- **Cloudflare Workers**: Agents SDK は Cloudflare Workers で利用できますが、現在いくつかの制限があります: + - 現在、Agents SDK は `nodejs_compat` の有効化が必要です。 + - トレースはリクエストの最後に手動でフラッシュする必要があります。詳細は [トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください。 + - Cloudflare Workers の `AsyncLocalStorage` のサポートが限定的なため、一部のトレースが正確でない場合があります。 +- **Browsers**: + - ブラウザでは現在トレーシングはサポートされていません。 - **v8 isolates**: - - 適切なブラウザ polyfill を含むバンドラを使用すれば v8 isolates 向けに SDK をバンドルできますが、トレーシングは機能しません - - v8 isolates での動作は十分にテストされていません + - 適切なブラウザ用ポリフィルを備えたバンドラを使えば v8 isolates 向けに SDK をバンドルできるはずですが、トレーシングは動作しません。 + - v8 isolates での検証は十分ではありません。 ## デバッグログ -SDK で問題が発生した場合は、デバッグログを有効にして処理状況の詳細を確認できます。 +OpenAI Agents SDK で問題が発生している場合は、デバッグログを有効にして何が起きているかの詳細情報を取得できます。 -`DEBUG` 環境変数に `openai-agents:*` を設定してデバッグログを有効化します。 +環境変数 `DEBUG` を `openai-agents:*` に設定してデバッグログを有効化します。 ```bash DEBUG=openai-agents:* ``` -また、SDK の特定の部分だけに対象を絞ってデバッグを有効にすることもできます: +また、デバッグ対象を SDK の特定の部分に絞り込むこともできます: -- `openai-agents:core` — SDK のメイン実行ロジック -- `openai-agents:openai` — OpenAI API 呼び出し -- `openai-agents:realtime` — Realtime Agents コンポーネント +- `openai-agents:core` — SDK の主要な実行ロジック用 +- `openai-agents:openai` — OpenAI API 呼び出し用 +- `openai-agents:realtime` — リアルタイムエージェントのコンポーネント用 diff --git a/docs/src/content/docs/ja/guides/voice-agents.mdx b/docs/src/content/docs/ja/guides/voice-agents.mdx index b721a8b2..b772bccd 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 クライアントを提供します。 ### 主な機能 - WebSocket または WebRTC で接続 -- ブラウザでもバックエンド接続でも利用可能 +- ブラウザおよびバックエンド接続の双方で利用可能 - 音声および割り込みのハンドリング - ハンドオフによるマルチエージェントのオーケストレーション - ツールの定義と呼び出し -- モデル出力を監視するカスタムガードレール +- モデル出力を監視するカスタム ガードレール - ストリーミングイベント用のコールバック -- テキストエージェントと音声エージェントで同じコンポーネントを再利用 +- テキストと音声のエージェントの両方で同じコンポーネントを再利用 -speech-to-speech モデルを使用すると、テキストへの書き起こしや音声への再変換を行うことなく、モデルのリアルタイム処理能力を活用できます。 +音声対音声モデルを使用することで、モデルが動作した後に音声を書き起こしてテキストを再度音声に変換し直す必要がなく、モデルの音声処理能力をリアルタイムで活用できます。 -![スピーチツースピーチモデル](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) +![音声対音声モデル](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) diff --git a/docs/src/content/docs/ja/guides/voice-agents/build.mdx b/docs/src/content/docs/ja/guides/voice-agents/build.mdx index a9b52bb0..7654b320 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/build.mdx @@ -28,136 +28,134 @@ 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) に一致する任意のパラメーターを渡せます。 +これらのトランスポート層では、[セッション](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` オブジェクトの一部としてそのまま渡されます。 ## ハンドオフ -通常のエージェントと同様に、ハンドオフを使ってエージェントを複数に分割し、それらをオーケストレーションすることでパフォーマンスを向上させたり、問題のスコープをより適切に定義できます。 +通常のエージェントと同様に、ハンドオフを使ってエージェントを複数のエージェントに分割し、それらをオーケストレーションしてエージェントのパフォーマンスを向上させ、問題の範囲をより適切に絞り込めます。 -通常のエージェントとは異なり、リアルタイムエージェントにおけるハンドオフは少し挙動が異なります。ハンドオフが実行されると、進行中のセッションは新しいエージェント設定で更新されます。そのため、エージェントは自動的に進行中の会話履歴へアクセスでき、現時点では入力フィルターは適用されません。 +通常のエージェントと異なり、リアルタイムエージェントにおけるハンドオフの挙動は少し異なります。ハンドオフが実行されると、進行中のセッションが新しいエージェント構成で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 -さらに、`voice` や `model` はハンドオフの一部として変更できません。また、接続先は他のリアルタイムエージェントのみです。別のモデル（例: 推論用モデル `o4-mini`）を使用する必要がある場合は、[ツールによる委任](#delegation-through-tools) を利用してください。 +さらに、`voice` や `model` はハンドオフの一部として変更できないことを意味します。接続できるのは他のリアルタイムエージェントのみです。別のモデル、たとえば `o4-mini` のような推論モデルを使う必要がある場合は、[delegation through tools](#delegation-through-tools) を利用できます。 ## ツール -通常のエージェントと同様に、リアルタイムエージェントでもツールを呼び出してアクションを実行できます。通常のエージェントと同じ `tool()` 関数を使ってツールを定義します。 +通常のエージェントと同様に、リアルタイムエージェントはアクションを実行するためにツールを呼び出せます。通常のエージェントと同じ `tool()` 関数でツールを定義できます。 -リアルタイムエージェントで使用できるのは関数ツールだけで、これらのツールはリアルタイムセッションと同じ場所で実行されます。つまり、ブラウザでリアルタイムセッションを実行している場合、ツールもブラウザで実行されます。よりセンシティブな処理が必要な場合は、ツール内で自分のバックエンドサーバーへ HTTP リクエストを送ることができます。 +リアルタイムエージェントで使用できるのは関数ツールのみで、これらのツールはリアルタイムセッションと同じ場所で実行されます。つまり、ブラウザーでリアルタイムセッションを実行している場合、ツールもブラウザーで実行されます。より機密性の高い操作を行う必要がある場合は、ツール内からバックエンド サーバーへの HTTP リクエストを発行できます。 -ツールが実行されている間、エージェントはユーザーからの新しいリクエストを処理できません。エクスペリエンスを向上させる 1 つの方法として、ツール実行前にエージェントにアナウンスさせたり、時間稼ぎのためのフレーズを言わせたりすると良いでしょう。 +ツールの実行中は、エージェントはユーザーからの新しいリクエストを処理できません。体験を向上させる方法の一つは、ツールを実行しようとしているときにそれをアナウンスする、あるいはツールの実行時間を確保するための特定のフレーズをエージェントに言わせるよう指示することです。 ### 会話履歴へのアクセス -エージェントがツールを呼び出した際の引数に加え、リアルタイムセッションが追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する場合や、[ツールによる委任](#delegation-through-tools) を計画している場合に役立ちます。 +エージェントが特定のツールを呼び出す際に渡した引数に加えて、リアルタイムセッションが追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑な処理を行う必要がある場合や、[tools for delegation](#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 API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使用して、ユーザーが話しているかどうかを自動的に検出し、新しいターンをトリガーします。 +リアルタイムセッションは、ユーザーが話しているタイミングを自動検出し、内蔵の [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()` を明示的に呼び出せます: -いずれの方法でも、リアルタイムセッションはエージェントの生成を中断し、ユーザーに対して話した内容の知識を切り詰め、履歴を更新します。 +いずれの場合も、リアルタイムセッションはエージェントの生成を中断し、ユーザーに対して発話した内容の認識を切り詰め、履歴を更新します。 -WebRTC でエージェントに接続している場合は、音声出力もクリアされます。WebSocket を使用している場合は、キューに入った音声再生を停止する処理を自分で行う必要があります。 +エージェントに接続するのに WebRTC を使用している場合、音声出力もクリアされます。 WebSocket を使用している場合は、再生キューに入っている音声の再生を停止するなど、この処理を自分で行う必要があります。 ## テキスト入力 エージェントにテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用できます。 -これは、ユーザーがエージェントと音声・テキスト両方のモダリティでやり取りできるようにしたり、会話に追加のコンテキストを提供したりする際に役立ちます。 +これは、ユーザーがエージェントと音声・テキストの両モダリティでやり取りできるようにしたい場合や、会話に追加のコンテキストを提供したい場合に便利です。 ## 会話履歴の管理 -`RealtimeSession` は `history` プロパティで会話履歴を自動管理します。 +`RealtimeSession` は会話履歴を `history` プロパティで自動的に管理します: -これを利用して履歴をユーザーに表示したり、追加処理を実行したりできます。会話中に履歴は常に変化するため、`history_updated` イベントを監視できます。 +これを使用して、履歴を顧客に表示したり、追加の処理を行ったりできます。会話の進行中はこの履歴が継続的に変化するため、`history_updated` イベントをリッスンできます。 -履歴を完全に削除したり、書き起こしを更新したりしたい場合は、`updateHistory` メソッドを利用してください。 +メッセージを完全に削除する、書き起こしを更新するなど、履歴を変更したい場合は、`updateHistory` メソッドを使用できます。 ### 制限事項 -1. 現在、関数ツール呼び出しを後から更新・変更することはできません -2. 履歴内のテキスト出力には、書き起こしとテキストモダリティが有効である必要があります -3. 割り込みにより切り詰められたレスポンスには書き起こしがありません +1. 現時点では、関数ツールの呼び出しを後から更新/変更できません +2. 履歴内のテキスト出力には、書き起こしとテキストモダリティを有効にする必要があります +3. 割り込みにより途中で切り詰められた応答には、書き起こしがありません -## ツールによる委任 +## ツールによる委譲 -![Delegation through tools](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) +![ツールによる委譲](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) -会話履歴とツール呼び出しを組み合わせることで、会話を別のバックエンドエージェントに委任してより複雑な処理を行い、その結果をユーザーに返すことができます。 +会話履歴とツール呼び出しを組み合わせることで、会話を別のバックエンドのエージェントに委譲して、より複雑な処理を実行し、その結果をユーザーに返すことができます。 -下記のコードはサーバー側で実行されます。この例では Next.js のサーバーアクションを通じて行います。 +以下のコードはサーバーで実行されます。この例では 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 65709c47..0bc7c9d1 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx @@ -26,25 +26,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t -0. **プロジェクトを作成する** +0. **プロジェクトの作成** - このクイックスタートでは、ブラウザで利用できる音声エージェントを作成します。新しいプロジェクトを試したい場合は、[`Next.js`](https://nextjs.org/docs/getting-started/installation) や [`Vite`](https://vite.dev/guide/installation.html) をお試しください。 + このクイックスタートでは、ブラウザで使える 音声エージェント を作成します。新しいプロジェクトを試したい場合は、[`Next.js`](https://nextjs.org/docs/getting-started/installation) や [`Vite`](https://vite.dev/guide/installation.html) を試してみてください。 ```bash npm create vite@latest my-project --template vanilla-ts ``` -1. **Agents SDK をインストールする** +1. **Agents SDK のインストール** ```bash npm install @openai/agents 'zod@<=3.25.67' ``` - 代わりにブラウザ用の単体パッケージである `@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 を通じてモデルに安全に接続する方法が必要です。そのために、バックエンドのサーバーで生成される [エフェメラルなクライアントキー](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/) の作成は、通常の [`エージェント`](/openai-agents-js/ja/guides/agents) の作成と非常によく似ています。 ```typescript import { RealtimeAgent } from '@openai/agents-realtime'; @@ -70,9 +70,9 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` -4. **セッションを作成する** +4. **セッションの作成** - 通常のエージェントと異なり、Voice エージェントは `RealtimeSession` 内で継続的に動作し、時間をかけてモデルとの会話と接続を管理します。このセッションは音声処理、割り込み、その他のライフサイクル機能も扱います。これらについては後ほど説明します。 + 通常のエージェントと異なり、音声エージェントは会話とモデルへの接続を継続的に管理する `RealtimeSession` の中で常時実行・リスニングします。このセッションは、音声処理や割り込み、その他多くのライフサイクル機能も扱います。これらについては後で説明します。 ```typescript import { RealtimeSession } from '@openai/agents-realtime'; @@ -82,17 +82,17 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` のコンストラクターは最初の引数に `agent` を取ります。このエージェントがユーザーと最初に対話するエージェントになります。 + `RealtimeSession` のコンストラクタは最初の引数として `agent` を受け取ります。このエージェントが、ユーザーが最初に対話できるエージェントになります。 -5. **セッションへ接続する** +5. **セッションへの接続** - 先ほど生成したクライアントのエフェメラルトークンを渡してセッションへ接続します。 + セッションに接続するには、先ほど生成したクライアントのエフェメラルトークンを渡します。 ```typescript await session.connect({ apiKey: '' }); ``` - これによりブラウザで WebRTC を使って Realtime API に接続し、マイクとスピーカーを自動で設定して音声の入出力を行います。`RealtimeSession` をバックエンドサーバー（Node.js など）で実行している場合、SDK は自動で WebSocket を使用します。異なるトランスポート層については [リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドで詳しく学べます。 + これにより、ブラウザで WebRTC を使って Realtime API に接続し、音声の入力と出力のためにマイクとスピーカーを自動的に設定します。`RealtimeSession` をバックエンドのサーバー（例えば Node.js）で実行している場合、SDK は接続方式として自動的に WebSocket を使用します。さまざまなトランスポート層については、[リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドをご覧ください。 6. **すべてをまとめる** @@ -100,7 +100,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 7. **エンジンを起動して話し始める** - Web サーバーを起動し、作成した Realtime エージェントのコードを含むページへアクセスしてください。マイクのアクセス許可を求めるダイアログが表示されます。許可すると、エージェントと会話を始められます。 + Web サーバーを起動し、新しい リアルタイムエージェント のコードを含むページに移動します。マイクへのアクセス許可のリクエストが表示されるはずです。許可すると、エージェントと話し始めることができます。 ```bash npm run dev @@ -110,17 +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) +- さまざまなトランスポート層についてさらに学ぶ + - [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 ce910714..30821720 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` インスタンスを指定してください。 +独自のメディアストリームや audio 要素を使用するには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定します。 -### WebSocket での接続 +### WebSocket 経由の接続 -WebRTC の代わりに WebSocket 接続を使用するには、セッション作成時に `transport: 'websocket'` もしくは `OpenAIRealtimeWebSocket` インスタンスを渡します。これは Twilio を使った電話エージェントのようなサーバーサイドのユースケースに適しています。 +WebRTC の代わりに WebSocket 接続を使用するには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これはサーバーサイドのユースケース、たとえば Twilio で電話エージェントを構築する場合に適しています。 -生の PCM16 オーディオバイトの取り扱いには任意の録音/再生ライブラリを使用できます。 +任意の録音/再生ライブラリを使用して、元の PCM16 音声バイトを扱ってください。 -### 独自トランスポートメカニズムの構築 +### 独自のトランスポート機構の構築 -別の音声―音声 API を利用したい場合や独自のトランスポートメカニズムを用意したい場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` イベントを発火させることで独自実装を作成できます。 +別の speech-to-speech 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 — トランスポート層のみの利用 -自動ツール実行やガードレールなどが不要な場合、トランスポート層を接続と割り込みのみを管理する “薄い” クライアントとして使用することもできます。 +自動ツール実行やガードレールなどが不要であれば、接続と割り込みの管理だけを行う "thin" クライアントとしてトランスポート層を使用することもできます。 diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index ccd3ee4a..9991e51d 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -19,44 +19,44 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概要 -[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) は、きわめて少ない抽象化で軽量かつ使いやすいパッケージとして、エージェント指向の AI アプリを構築できるようにします。これは以前の実験的ライブラリである [Swarm](https://github.com/openai/swarm/tree/main) を本番環境向けにアップグレードしたもので、[Python 版](https://github.com/openai/openai-agents-python) も提供されています。Agents SDK はごく小さな基本コンポーネントを提供します。 +[TypeScript 版 OpenAI Agents SDK](https://github.com/openai/openai-agents-js) は、抽象化が非常に少ない軽量で使いやすいパッケージで、エージェント駆動の AI アプリを構築できます。これは、以前のエージェント向け実験である [Swarm](https://github.com/openai/swarm/tree/main)（[Python 版](https://github.com/openai/openai-agents-python) もあります）の本番運用可能なアップグレードです。Agents SDK には非常に小さな基本コンポーネントのセットがあります: -- **エージェント**: instructions と tools を備えた LLM -- **ハンドオフ**: 特定タスクをほかのエージェントに委任するしくみ -- **ガードレール**: エージェントへの入力を検証するしくみ +- **エージェント** は、instructions と tools を備えた LLM です +- **ハンドオフ** は、エージェントが特定のタスクを他のエージェントに委譲できる仕組みです +- **ガードレール** は、エージェントへの入力を検証できるようにします -TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実用的なアプリケーションを構築できます。さらに SDK には **トレーシング** が組み込まれており、エージェントフローの可視化やデバッグ、評価、さらにはアプリケーション向けモデルのファインチューニングまで行えます。 +TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェントの間の複雑な関係を表現できるほど強力で、急な学習曲線なしに実運用のアプリケーションを構築できます。さらに、この SDK には組み込みの **トレーシング** があり、エージェント駆動のフローを可視化してデバッグでき、評価し、さらにはアプリケーション向けにモデルをファインチューニングすることもできます。 ## Agents SDK を使う理由 -SDK には 2 つの設計原則があります。 +この SDK には、設計上の指針が 2 つあります: -1. 使う価値のある十分な機能を備えつつ、学習が速いように基本コンポーネントは最小限にする -2. デフォルトで高い完成度を持ちながら、動作を細かくカスタマイズできる +1. 使う価値があるだけの十分な機能を備えつつ、学習を素早くできるよう基本コンポーネントは最小限にする +2. そのままでも十分に動作しますが、実際の挙動を細かくカスタマイズできる -主な機能は次のとおりです。 +SDK の主な機能は次のとおりです: -- **エージェントループ**: tool の呼び出し、結果を LLM に送信、LLM が完了するまでループを自動で処理 -- **TypeScript ファースト**: 新しい抽象概念を学ばずに、言語機能だけでエージェントをオーケストレーションおよびチェーン可能 -- **ハンドオフ**: 複数エージェント間での協調・委任を実現する強力な機能 -- **ガードレール**: エージェント実行と並行して入力検証を実施し、失敗時は早期停止 -- **関数ツール**: 任意の TypeScript 関数を自動スキーマ生成と Zod ベース検証付きで tool 化 -- **トレーシング**: フローの可視化・デバッグ・監視に加え、OpenAI の評価・ファインチューニング・蒸留ツールを利用可能 -- **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた高機能音声エージェントを構築 +- **エージェントループ**: ツール呼び出し、結果を LLM に送信、LLM の完了までのループを処理する組み込みのループ +- **TypeScript ファースト**: 新しい抽象を学ぶ必要はなく、言語の組み込み機能でエージェントをオーケストレーションし連鎖させる +- **ハンドオフ**: 複数のエージェント間で調整や委譲を行う強力な機能 +- **ガードレール**: エージェントと並行して入力のバリデーションやチェックを実行し、失敗した場合は早期に中断する +- **関数ツール**: 任意の TypeScript 関数をツールに変換し、スキーマの自動生成と Zod ベースの検証を提供 +- **トレーシング**: ワークフローの可視化・デバッグ・監視ができ、さらに OpenAI の評価、ファインチューニング、蒸留ツール群も活用できる組み込みのトレーシング +- **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 ## インストール -現在、この SDK は `zod@3.25.68` 以降と互換性がありません。必ず `zod@3.25.67`（またはそれ以前のバージョン）を明示的にインストールしてください。この依存関係の問題は近日中に解決予定です。最新情報は [this issue](https://github.com/openai/openai-agents-js/issues/187) をご確認ください。 +この SDK は現在 `zod@3.25.68` 以上では動作しません。明示的に `zod@3.25.67`（またはそれ以前のバージョン）をインストールしてください。依存関係の問題は近日中に解消します。最新情報は [この issue](https://github.com/openai/openai-agents-js/issues/187) をご確認ください。 ```bash npm install @openai/agents 'zod@<=3.25.67' ``` -## Hello World 例 +## Hello World の例 -(_実行する場合は `OPENAI_API_KEY` 環境変数を設定してください_) +( _これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_ ) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/src/scripts/translate.ts b/docs/src/scripts/translate.ts index 9e3bfe57..b851ea4c 100644 --- a/docs/src/scripts/translate.ts +++ b/docs/src/scripts/translate.ts @@ -120,7 +120,7 @@ const languages: Record = { ja: 'Japanese', // Add more languages here }; -const OPENAI_MODEL = process.env.OPENAI_MODEL || 'o3'; +const OPENAI_MODEL = process.env.OPENAI_MODEL || 'gpt-5'; setDefaultOpenAIKey(process.env.OPENAI_API_KEY || ''); const ENABLE_CODE_SNIPPET_EXCLUSION = true; @@ -370,6 +370,7 @@ Follow the following workflow to translate the given markdown text data: 3. Perform a self-review to evaluate the following points: - the quality of the translation, focusing on naturalness, accuracy, and consistency in detail - any errors or rooms for improvements in terms of Markdown text format -- A common error is to have spaces within special syntax like * or _. You must have spaces after special syntax like * or _, but it's NOT the same for the parts inside special syntax (e.g., ** bold ** must be **bold**) + - you should not have any unnecessary spaces outside of tags; especially for the ones you replace with the "TERM-SPECIFIC" list - any parts that are not compatible with *.mdx files -- In the past, you've generated an expression with acorn like {#title-here} in h2 (##) level but it was neither necessary nor valid 4. If improvements are necessary, refine the content without changing the original meaning. 5. Continue improving the translation until you are fully satisfied with the result.