From 63b6499dcab17405354896b9cfaa677f788132ae Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 9 Sep 2025 09:57:25 +0000 Subject: [PATCH] Update all translated document pages --- .../src/content/docs/ja/extensions/ai-sdk.mdx | 28 ++--- .../src/content/docs/ja/extensions/twilio.mdx | 41 +++--- docs/src/content/docs/ja/guides/agents.mdx | 110 +++++++++------- docs/src/content/docs/ja/guides/config.mdx | 16 +-- docs/src/content/docs/ja/guides/context.mdx | 28 ++--- .../src/content/docs/ja/guides/guardrails.mdx | 36 +++--- docs/src/content/docs/ja/guides/handoffs.mdx | 18 +-- .../docs/ja/guides/human-in-the-loop.mdx | 40 +++--- docs/src/content/docs/ja/guides/mcp.mdx | 78 ++++++------ docs/src/content/docs/ja/guides/models.mdx | 74 +++++------ .../src/content/docs/ja/guides/multi-agent.md | 42 +++---- .../src/content/docs/ja/guides/quickstart.mdx | 47 ++++--- docs/src/content/docs/ja/guides/release.mdx | 16 +-- docs/src/content/docs/ja/guides/results.mdx | 64 +++++----- .../content/docs/ja/guides/running-agents.mdx | 118 +++++++++--------- docs/src/content/docs/ja/guides/streaming.mdx | 47 ++++--- docs/src/content/docs/ja/guides/tools.mdx | 72 +++++------ docs/src/content/docs/ja/guides/tracing.mdx | 80 ++++++------ .../docs/ja/guides/troubleshooting.mdx | 30 ++--- .../content/docs/ja/guides/voice-agents.mdx | 16 +-- .../docs/ja/guides/voice-agents/build.mdx | 74 ++++++----- .../ja/guides/voice-agents/quickstart.mdx | 32 ++--- .../docs/ja/guides/voice-agents/transport.mdx | 28 ++--- docs/src/content/docs/ja/index.mdx | 34 ++--- 24 files changed, 593 insertions(+), 576 deletions(-) diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index 5c9c292f..51d5eb76 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -8,36 +8,36 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk -標準で 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. 拡張パッケージをインストールして AI SDK アダプターを導入します: +1. 拡張機能パッケージをインストールして AI SDK アダプターを導入します: ```bash npm install @openai/agents-extensions ``` -2. [Vercel の AI SDK](https://ai-sdk.dev/docs/foundations/providers-and-models) から使いたいモデルパッケージを選び、インストールします: +2. [Vercel の AI SDK](https://ai-sdk.dev/docs/foundations/providers-and-models) から使用したいモデルのパッケージを選び、インストールします: ```bash npm install @ai-sdk/openai ``` -3. アダプターとモデルをインポートし、エージェントに接続します: +3. アダプターとモデルをインポートして、エージェントに接続します: ```typescript import { openai } from '@ai-sdk/openai'; import { aisdk } from '@openai/agents-extensions'; ``` -4. エージェントが使用するモデルのインスタンスを初期化します: +4. エージェントで使用するモデルのインスタンスを初期化します: ```typescript const model = aisdk(openai('o4-mini')); @@ -46,10 +46,10 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk ## 例 @@ -60,9 +60,9 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk title="AI SDK のセットアップ" /> -## プロバイダー メタデータの指定 +## プロバイダーのメタデータの指定 -メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` に渡します。値は基盤の AI SDK モデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` +メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` に渡します。値は基盤となる AI SDK モデルにそのままフォワードされます。例えば、Agents SDK で次の `providerData` ```ts providerData: { @@ -74,7 +74,7 @@ providerData: { } ``` -は、AI SDK 連携を使用する場合は次のようになります +は、AI SDK 連携を使用する場合は次のように ```ts providerMetadata: { diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index 619d8530..2c61b9a0 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,14 +7,15 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio は、電話の通話音声の 元 オーディオを WebSocket サーバーに送る [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しています。このセットアップは、あなたの [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続するために使えます。Twilio から届くイベントを Realtime Session に接続するには、`websocket` モードのデフォルトの 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 トランスポートを使えます。ただし、通話は Web ベースの会話より遅延が大きくなりがちなため、適切な音声フォーマットの設定と、割り込みタイミングの調整が必要です。 -セットアップ体験を改善するため、Twilio への接続、割り込み処理、音声のフォワーディングまで対応する専用のトランスポートレイヤーを用意しました。 +セットアップ体験を向上させるため、Twilio への接続、割り込み処理、音声転送を代行する専用のトランスポートレイヤーを用意しました。 ## セットアップ @@ -25,13 +26,12 @@ Twilio は、電話の通話音声の 元 オーディオを WebSocket サーバ 2. **Twilio からのイベントを受け取れる WebSocket サーバーを用意します。** - ローカル開発の場合、Twilio からローカルサーバーにアクセスできるよう、 - [`ngrok`](https://ngrok.io/) や + ローカル開発中は、[`ngrok`](https://ngrok.io/) や [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - などのローカルトンネルを構成する必要があります。`TwilioRealtimeTransportLayer` + などでローカルトンネルを設定して、ローカルサーバーを Twilio から参照できるようにする必要があります。`TwilioRealtimeTransportLayer` を使って Twilio に接続できます。 -3. **extensions パッケージをインストールして Twilio アダプターを導入します:** +3. **拡張パッケージをインストールして Twilio アダプターを導入します:** ```bash npm install @openai/agents-extensions @@ -55,33 +55,32 @@ Twilio は、電話の通話音声の 元 オーディオを WebSocket サーバ -`RealtimeSession` に期待されるあらゆるイベントや挙動（ツール呼び出し、ガードレールなど）はそのまま動作します。`RealtimeSession` を音声エージェントと併用する方法の詳細は、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 +`RealtimeSession` に期待されるあらゆるイベントや動作は、ツール呼び出し、ガードレールなどを含め、期待どおりに動作します。音声エージェントとの併用方法は、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 ## ヒントと考慮事項 1. **スピードが最重要です。** - Twilio から必要なイベントと音声をすべて受け取るには、WebSocket 接続の参照を取得したらすぐに + Twilio から必要なイベントと音声をすべて受け取るには、WebSocket 接続の参照を得たらすぐに `TwilioRealtimeTransportLayer` インスタンスを作成し、その直後に `session.connect()` を呼び出してください。 -2. **Twilio の 元 イベントにアクセスします。** +2. **Twilio の元イベントにアクセスします。** - Twilio から送られてくる 元 のイベントにアクセスしたい場合は、`RealtimeSession` インスタンスで - `transport_event` をリッスンします。Twilio からのすべてのイベントは `twilio_message` タイプを持ち、 - 元 イベントデータを含む `message` プロパティがあります。 + Twilio が送信する元イベントにアクセスしたい場合は、`RealtimeSession` インスタンスの `transport_event` + をリッスンします。Twilio からの各イベントは `twilio_message` の type を持ち、元イベントデータを含む + `message` プロパティがあります。 3. **デバッグログを確認します。** - 状況を詳しく知りたい問題に遭遇することがあります。`DEBUG=openai-agents*` 環境変数を使うと、 - Agents SDK のすべてのデバッグログが出力されます。あるいは、Twilio アダプターのデバッグログだけを - 有効にするには `DEBUG=openai-agents:extensions:twilio*` を使います。 + 状況を詳しく把握したい場合は、環境変数 `DEBUG=openai-agents*` を使うと Agents SDK のすべてのデバッグログが表示されます。 + あるいは、`DEBUG=openai-agents:extensions:twilio*` で Twilio アダプターのデバッグログだけを有効化できます。 -## フルサンプルサーバー +## サーバーのフルサンプル -以下は、Twilio からのリクエストを受け取り、それを `RealtimeSession` にフォワードする、エンドツーエンドの WebSocket サーバーのサンプルです。 +以下は、Twilio からのリクエストを受け取り、`RealtimeSession` に転送する WebSocket サーバーのエンドツーエンドのサンプルです。 diff --git a/docs/src/content/docs/ja/guides/agents.mdx b/docs/src/content/docs/ja/guides/agents.mdx index a44ebf33..fa463973 100644 --- a/docs/src/content/docs/ja/guides/agents.mdx +++ b/docs/src/content/docs/ja/guides/agents.mdx @@ -8,73 +8,99 @@ import simpleAgent from '../../../../../../examples/docs/agents/simpleAgent.ts?r import agentWithTools from '../../../../../../examples/docs/agents/agentWithTools.ts?raw'; import agentWithContext from '../../../../../../examples/docs/agents/agentWithContext.ts?raw'; import agentWithAodOutputType from '../../../../../../examples/docs/agents/agentWithAodOutputType.ts?raw'; +import agentsAsTools from '../../../../../../examples/docs/agents/agentsAsTools.ts?raw'; import agentWithHandoffs from '../../../../../../examples/docs/agents/agentWithHandoffs.ts?raw'; import agentWithDynamicInstructions from '../../../../../../examples/docs/agents/agentWithDynamicInstructions.ts?raw'; import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agentWithLifecycleHooks.ts?raw'; 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** は、次の設定を持つ大規模言語モデル（LLM）です。 -- **Instructions** – モデルに「自分は誰か」「どう応答すべきか」を伝える システムプロンプト -- **Model** – 呼び出す OpenAI モデルと、任意のモデル調整パラメーター -- **Tools** – LLM がタスク達成のために呼び出せる関数や API の一覧 +- **Instructions** – モデルに対して「自分は誰か」「どのように応答すべきか」を伝える system prompt +- **Model** – 呼び出す OpenAI モデルと任意のモデル調整パラメーター +- **Tools** – タスクを達成するために LLM が呼び出せる関数や API の一覧 - + -このページでは、すべての Agent 機能を詳しく説明します。 +このページでは、あらゆる Agent 機能を詳しく説明します。 --- ## 基本設定 -`Agent` のコンストラクタは 1 つの設定オブジェクトを受け取ります。最も一般的に使われるプロパティは次のとおりです。 +`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。よく使われるプロパティは次のとおりです。 -| Property | Required | Description | -| --------------- | -------- | --------------------------------------------------------------------------------------------------- | -| `name` | yes | 短い人間可読の識別子 | -| `instructions` | yes | システムプロンプト（文字列 **または** 関数 – [Dynamic instructions](#dynamic-instructions) を参照） | -| `model` | no | モデル名 **または** カスタムの [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | -| `modelSettings` | no | 調整パラメーター（temperature、top_p など） | -| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) の配列 | +| Property | Required | Description | +| --------------- | -------- | -------------------------------------------------------------------------------------------------- | +| `name` | yes | 短い人間向けの識別子 | +| `instructions` | yes | System prompt（文字列 **または** 関数 – [Dynamic instructions](#dynamic-instructions) を参照） | +| `model` | no | モデル名 **または** カスタム [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | +| `modelSettings` | no | 調整パラメーター（temperature、top_p など） | +| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | - + --- ## コンテキスト -エージェントは **コンテキスト型に対して総称的** です（例: `Agent`）。このコンテキストは、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。すべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共通サービス（データベース接続、ユーザーメタデータ、機能フラグ など）を提供するのに役立ちます。 +エージェントは **コンテキスト型に対してジェネリック** です（例: `Agent`）。コンテキストは、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザーのメタデータ、機能フラグなど）を提供するのに役立ちます。 - + --- ## 出力タイプ -既定では、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は次を受け付けます。 +デフォルトでは、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は次を受け付けます。 1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`） -2. JSON スキーマ互換のオブジェクト +2. JSON Schema 互換のオブジェクト -`outputType` が与えられると、SDK はプレーンテキストではなく自動的に +`outputType` が指定されている場合、SDK はプレーンテキストではなく自動的に [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。 --- -## ハンドオフ +## マルチエージェントの設計パターン + +エージェントを組み合わせる方法は多数あります。プロダクションのアプリでよく見られる 2 つのパターンは次のとおりです。 -エージェントは `handoffs` プロパティを介して他のエージェントに **委譲** できます。一般的なパターンは、会話をより専門的なサブエージェントに振り分ける トリアージエージェント を使うことです。 +1. **マネージャー（エージェントをツールとして扱う）** – 中央のエージェントが会話を所有し、ツールとして公開された特化エージェントを呼び出す +2. **ハンドオフ** – 最初のエージェントがユーザーのリクエストを特定したら、会話全体を専門エージェントに委譲する - +これらは補完的なアプローチです。マネージャーはガードレールやレート制限を 1 か所で適用できます。一方、ハンドオフでは各エージェントが会話の制御を保持せず単一のタスクに集中できます。 -このパターンの詳細は [ハンドオフ](/openai-agents-js/ja/guides/handoffs) を参照してください。 +### マネージャー（エージェントをツールとして扱う） + +このパターンでは、マネージャーは決して制御を手放しません。LLM がツールを使い、マネージャーが最終回答を要約します。詳しくは [ツール](/openai-agents-js/ja/guides/tools#agents-as-tools) を参照してください。 + + + +### ハンドオフ + +ハンドオフでは、トリアージ用エージェントがリクエストを振り分けますが、ハンドオフが発生すると、専門エージェントが最終出力を生成するまで会話を所有します。これによりプロンプトが短くなり、各エージェントを独立して考えることができます。詳しくは [ハンドオフ](/openai-agents-js/ja/guides/handoffs) を参照してください。 + + --- @@ -85,37 +111,37 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor -同期関数と `async` 関数の両方をサポートしています。 +同期関数と `async` 関数のどちらもサポートされています。 --- ## ライフサイクルフック -高度なユースケースでは、イベントをリッスンして Agent のライフサイクルを観察できます +高度なユースケース向けに、イベントをリッスンして Agent のライフサイクルを監視できます --- ## ガードレール -ガードレールにより、ユーザー入力とエージェント出力を検証または変換できます。`inputGuardrails` および `outputGuardrails` 配列で設定します。詳細は +ガードレールは、ユーザー入力やエージェント出力を検証・変換できます。`inputGuardrails` と `outputGuardrails` 配列で設定します。詳細は [ガードレール](/openai-agents-js/ja/guides/guardrails) を参照してください。 --- -## エージェントの複製/コピー +## エージェントのクローン／コピー -既存のエージェントを少しだけ変更したい場合は、まったく新しい `Agent` インスタンスを返す `clone()` メソッドを使用します。 +既存のエージェントを少しだけ変更したい場合は、`clone()` メソッドを使います。これは完全に新しい `Agent` インスタンスを返します。 - + --- @@ -123,20 +149,20 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ツールを提供しても、LLM が必ず呼び出すとは限りません。`modelSettings.tool_choice` でツール使用を **強制** できます。 -1. `'auto'`（既定）– LLM がツールを使うかどうかを判断 -2. `'required'` – LLM はツールを呼び出さなければならない（どれにするかは選べる） +1. `'auto'`（デフォルト） – ツールを使うかどうかは LLM が決定 +2. `'required'` – LLM はツールを呼び出す必要がある（どれを使うかは選べる） 3. `'none'` – LLM はツールを呼び出してはならない -4. 具体的なツール名（例: `'calculator'`）– LLM はそのツールを呼び出さなければならない +4. 特定のツール名（例 `'calculator'`） – そのツールを必ず呼び出す - + ### 無限ループの防止 -ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループに陥るのを防ぎます。`resetToolChoice` フラグや `toolUseBehavior` の設定でこの挙動を上書きできます。 +ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループへ入るのを防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 -- `'run_llm_again'`（既定）– ツール結果を用いて LLM を再実行 +- `'run_llm_again'`（デフォルト） – ツール結果を用いて再度 LLM を実行 - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う -- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼ばれたら停止 +- `{ stopAtToolNames: ['my_tool'] }` – 指定したいずれかのツールが呼ばれたら停止 - `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数 ```typescript @@ -151,5 +177,5 @@ const agent = new Agent({ ## 次のステップ - [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を学ぶ -- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) を深掘りする -- サイドバーの **@openai/agents** にある TypeDoc リファレンス全体を参照する +- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) を詳しく学ぶ +- サイドバーの **@openai/agents** 配下で TypeDoc リファレンス全体を参照する diff --git a/docs/src/content/docs/ja/guides/config.mdx b/docs/src/content/docs/ja/guides/config.mdx index 5e18ed81..a0e2e3af 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,7 +13,7 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## API キーとクライアント -デフォルトで SDK は初回インポート時に環境変数 `OPENAI_API_KEY` を読み込みます。変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出せます。 +デフォルトでは、SDK は初回のインポート時に環境変数 `OPENAI_API_KEY` を読み取ります。変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出せます。 -独自の `OpenAI` クライアントインスタンスを渡すこともできます。指定しない場合、SDK は既定のキーで自動的に作成します。 +独自の `OpenAI` クライアントインスタンスを渡すこともできます。指定しない場合、SDK は既定のキーを使って自動的に作成します。 -最後に、Responses API と Chat Completions API を切り替えられます。 +最後に、Responses API と Chat Completions API を切り替えることができます。 ## トレーシング -トレーシングは既定で有効で、上記の OpenAI キーを使用します。別のキーは `setTracingExportApiKey()` で設定できます。 +トレーシングはデフォルトで有効で、上のセクションの OpenAI キーを使用します。別のキーは `setTracingExportApiKey()` で設定できます。 ` 型で表現されます。状態や依存関係を保持する任意のオブジェクトを作成し、それを `Runner.run()` に渡します。すべてのツール呼び出しやフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み取ったり変更したりできます。 +ローカルコンテキストは `RunContext` 型で表現します。状態や依存関係を保持する任意のオブジェクトを作成して、それを `Runner.run()` に渡します。すべてのツール呼び出しとフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み取ったり変更したりできます。 -単一の実行に参加するすべてのエージェント、ツール、フックは、同じ **型** のコンテキストを使用する必要があります。 +単一の実行に参加するすべてのエージェント、ツール、フックは、同じコンテキストの **型** を使用する必要があります。 -ローカルコンテキストの用途例: +ローカルコンテキストの用途: - 実行に関するデータ（ユーザー名、ID など） - ロガーやデータフェッチャーなどの依存関係 - ヘルパー関数 -## エージェント / LLM コンテキスト +## エージェント/LLM のコンテキスト -LLM が呼び出されるとき、参照できるのは会話履歴から来るデータのみです。追加情報を利用可能にするには、次の選択肢があります: +LLM が呼び出されるとき、参照できるデータは会話履歴に由来するものだけです。追加情報を利用可能にするには、次の選択肢があります: -1. エージェントの `instructions` に追加する（システムメッセージまたは開発者メッセージとも呼ばれます）。これは静的文字列でも、コンテキストを受け取って文字列を返す関数でもかまいません -2. `Runner.run()` を呼び出す際の `input` に含める。これは `instructions` 手法に近いですが、メッセージを [chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます -3. 関数ツール経由で公開し、LLM がオンデマンドでデータを取得できるようにする -4. ファイル、データベース、または Web の関連データに基づかせるために、リトリーバルや Web 検索ツールを使用する +1. エージェントの `instructions`（システムまたは開発者メッセージ）に追加する。これは静的な文字列でも、コンテキストを受け取って文字列を返す関数でも可 +2. `Runner.run()` 呼び出し時の `input` に含める。instructions の手法に似ていますが、メッセージを [指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます +3. 関数ツールを通じて公開し、LLM がオンデマンドでデータを取得できるようにする +4. リトリーバルや Web 検索ツールを使い、ファイル、データベース、または Web の関連データに基づいて応答をグラウンディングする diff --git a/docs/src/content/docs/ja/guides/guardrails.mdx b/docs/src/content/docs/ja/guides/guardrails.mdx index 99cb6e2d..d641ddd3 100644 --- a/docs/src/content/docs/ja/guides/guardrails.mdx +++ b/docs/src/content/docs/ja/guides/guardrails.mdx @@ -7,58 +7,58 @@ import { Code } from '@astrojs/starlight/components'; import inputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-input.ts?raw'; import outputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-output.ts?raw'; -ガードレールはエージェントと並行して実行され、ユーザー入力やエージェント出力に対するチェックや検証を行います。たとえば、コストの高いモデルを呼び出す前に、軽量モデルをガードレールとして実行できます。悪意ある利用を検出した場合、エラーを発生させて高価なモデルの実行を停止できます。 +ガードレールはエージェントと _in parallel_ で動作し、ユーザー入力やエージェント出力に対してチェックやバリデーションを実行できます。たとえば、高コストのモデルを呼び出す前に軽量なモデルをガードレールとして実行できます。ガードレールが悪意のある使用を検知した場合、エラーを発生させて高コストのモデルの実行を停止できます。 ガードレールには 2 種類あります: -1. **Input guardrails** は最初のユーザー入力に対して実行されます -2. **Output guardrails** は最終的なエージェントの出力に対して実行されます +1. **Input guardrails** は初期のユーザー入力に対して実行されます +2. **Output guardrails** は最終的なエージェント出力に対して実行されます -## Input guardrails +## 入力ガードレール -Input guardrails は 3 段階で実行されます: +入力ガードレールは 3 段階で動作します: 1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返し、これは [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップされます +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) 内にラップして返します 3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます > **Note** -> Input guardrails はユーザー入力向けであり、ワークフローでエージェントが最初のエージェントの場合にのみ実行されます。ガードレールはエージェント自体に設定します。これは、エージェントごとに必要なガードレールが異なることが多いためです。 +> 入力ガードレールはユーザー入力を対象としているため、エージェントがワークフローの _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。なぜならエージェントによって必要なガードレールが異なることが多いためです。 -## Output guardrails +## 出力ガードレール -Output guardrails も同様のパターンに従います: +出力ガードレールも同様のパターンに従います: 1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返し、これは [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップされます +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) 内にラップして返します 3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます > **Note** -> Output guardrails は、ワークフローでエージェントが最後のエージェントの場合にのみ実行されます。リアルタイム音声対話については[音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails)を参照してください。 +> 出力ガードレールは、エージェントがワークフローの _最後_ のエージェントである場合にのみ実行されます。リアルタイムの音声対話については[音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails)を参照してください。 -## トリップワイヤー (tripwire) +## トリップワイヤー -ガードレールが失敗すると、トリップワイヤーでそれを通知します。トリップワイヤーが発火した時点で、ランナー (runner) は対応するエラーをスローし、実行を停止します。 +ガードレールが失敗すると、トリップワイヤーを通じてそれを通知します。トリップワイヤーが作動するとすぐに、Runner は対応するエラーをスローし、実行を停止します。 ## ガードレールの実装 -ガードレールは、`GuardrailFunctionOutput` を返す単なる関数です。以下は、別のエージェントを内部で実行して、ユーザーが算数の宿題の手助けを求めているかどうかをチェックする最小の例です。 +ガードレールは `GuardrailFunctionOutput` を返す関数にすぎません。以下は、別のエージェントを内部で実行して、ユーザーが数学の宿題の支援を求めているかどうかを確認する最小例です。 -Output guardrails も同様に動作します。 +出力ガードレールも同様に動作します。 -1. `guardrailAgent` はガードレール関数内で使用されます +1. `guardrailAgent` はガードレール関数の内部で使用されます 2. ガードレール関数はエージェントの入力または出力を受け取り、結果を返します 3. 追加情報をガードレール結果に含めることができます 4. `agent` はガードレールが適用される実際のワークフローを定義します diff --git a/docs/src/content/docs/ja/guides/handoffs.mdx b/docs/src/content/docs/ja/guides/handoffs.mdx index 542a391f..88285599 100644 --- a/docs/src/content/docs/ja/guides/handoffs.mdx +++ b/docs/src/content/docs/ja/guides/handoffs.mdx @@ -10,13 +10,13 @@ import handoffInputExample from '../../../../../../examples/docs/handoffs/handof import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw'; import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw'; -ハンドオフは、ある エージェント が会話の一部を別の エージェント に委譲できるようにします。これは、異なる エージェント が特定分野を専門としている場合に有用です。たとえばカスタマーサポート アプリでは、予約、返金、FAQ を担当する エージェント を用意できます。 +ハンドオフは、会話の一部を別の エージェント に委譲します。これは、異なる エージェント が特定分野を専門とする場合に有用です。たとえばカスタマーサポートアプリでは、予約、返金、FAQ を担当する エージェント を用意できます。 -ハンドオフは LLM に ツール として表現されます。`Refund Agent` という エージェント にハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM に対してツールとして表現されます。`Refund Agent` という エージェント にハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべての エージェント は `handoffs` オプションを受け付けます。ここには他の `Agent` インスタンスや、`handoff()` ヘルパーが返す `Handoff` オブジェクトを含められます。 +すべての エージェント は `handoffs` オプションを受け付けます。ここには他の `Agent` インスタンス、または `handoff()` ヘルパーが返す `Handoff` オブジェクトを含められます。 ### 基本的な使い方 @@ -29,8 +29,8 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r - `agent` – ハンドオフ先の エージェント - `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き - `toolDescriptionOverride` – 既定のツール説明を上書き -- `onHandoff` – ハンドオフ発生時のコールバック。`RunContext` と、場合により構造化入力を受け取る -- `inputType` – ハンドオフに期待される入力スキーマ +- `onHandoff` – ハンドオフ発生時のコールバック。`RunContext` と必要に応じて解析済み入力を受け取る +- `inputType` – ハンドオフに期待する入力スキーマ - `inputFilter` – 次の エージェント に渡す履歴のフィルター -## ハンドオフ入力 +## ハンドオフの入力 -ハンドオフを呼び出す際に LLM にデータを提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 +ハンドオフを呼び出す際に LLM にデータ提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 ## 入力フィルター 既定では、ハンドオフは会話履歴全体を受け取ります。次の エージェント に渡す内容を変更するには、`inputFilter` を指定します。 -共通のヘルパーは `@openai/agents-core/extensions` にあります。 +共通ヘルパーは `@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 のバージョンを上げたい場合は、パッケージエイリアスを使って並行して 2 つの 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 48cc6257..544dfd6f 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -13,111 +13,115 @@ import streamableHttpExample from '../../../../../../examples/docs/mcp/streamabl import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; -The [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより引用: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP のドキュメントより: -> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションにおける USB‑C ポートのような存在だと考えてください。USB‑C がさまざまな周辺機器やアクセサリにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。 この SDK がサポートする MCP サーバーには 3 種類あります: -1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) がツールとして利用するリモート MCP サーバー +1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) によってツールとして利用されるリモート MCP サーバー 2. **Streamable HTTP MCP servers** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートのサーバー -3. **Stdio MCP servers** – 標準入出力でアクセスするサーバー（最も簡単な選択肢） +3. **Stdio MCP servers** – 標準入出力経由でアクセスするサーバー（最もシンプルな選択肢） ユースケースに応じてサーバータイプを選択してください: -| 必要なこと | 推奨オプション | -| ------------------------------------------------------------------------------ | ----------------------- | -| 公開アクセス可能なリモートサーバーをデフォルトの OpenAI responses モデルで呼ぶ | **1. Hosted MCP tools** | -| 公開アクセス可能なリモートサーバーを使いつつ、ツール呼び出しはローカルで発火 | **2. Streamable HTTP** | -| ローカルで動作する Streamable HTTP サーバーを使う | **2. Streamable HTTP** | -| OpenAI-Responses 以外のモデルで任意の Streamable HTTP サーバーを使う | **2. Streamable HTTP** | -| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーを使う | **3. Stdio** | +| 必要なこと | 推奨オプション | +| -------------------------------------------------------------------------------- | ----------------------- | +| 公開アクセス可能なリモートサーバーをデフォルトの OpenAI Responses モデルで呼ぶ | **1. Hosted MCP tools** | +| 公開アクセス可能なリモートサーバーを使いつつ、ツール呼び出しはローカルでトリガー | **2. Streamable HTTP** | +| ローカルで動作する Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| OpenAI Responses 以外のモデルで任意の Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| 標準入出力プロトコルのみをサポートするローカル MCP サーバーを扱う | **3. Stdio** | ## 1. Hosted MCP server tools -Hosted ツールは往復の処理全体をモデル側に委ねます。あなたのコードが MCP サーバーを呼ぶ代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルへストリーミングします。 +Hosted ツールは、往復処理全体をモデル側に押し込みます。あなたのコードが MCP サーバーを呼ぶ代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルにストリーミングで返します。 -以下はリモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数へ渡して、リモート MCP サーバーツールを作成する最も簡単な例です。 +Hosted MCP ツールを使う最も簡単な例がこちらです。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡します。これは hosted MCP サーバーツールを作成するのに便利です。 -次に、`run` 関数（または独自にカスタマイズした `Runner` インスタンスの `run` メソッド）で Agent を実行できます: +その後、`run` 関数（またはカスタマイズした自分の `Runner` インスタンスの `run` メソッド）でエージェントを実行できます: -インクリメンタルな MCP の結果をストリーミングするには、`Agent` を実行する際に `stream: true` を渡します: +増分的な MCP の結果をストリーミングするには、`Agent` を実行する際に `stream: true` を渡します: -#### 承認フロー（任意） +#### オプションの承認フロー -機微な操作については、個々のツール呼び出しに人間の承認を要求できます。`requireApproval: 'always'` または、ツール名から `'never'`/`'always'` への詳細なマッピングオブジェクトを渡してください。 +機密性の高い操作では、個々のツール呼び出しに対して人間の承認を必須にできます。`requireApproval: 'always'` または、ツール名を `'never'`/`'always'` に細かく対応付けるオブジェクトを渡します。 -プログラム的にツール呼び出しの安全性を判定できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または拒否できます。人間の承認が必要な場合は、ローカルの 関数ツール と同様に `interruptions` を使った同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) 手法を使用できます。 +プログラム的にツール呼び出しが安全か判断できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または拒否できます。人間の承認が必要な場合は、ローカルの 関数ツール と同様に `interruptions` を用いた同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) アプローチを使えます。 -### コネクタ対応の Hosted MCP サーバー +### コネクタ対応の hosted サーバー -Hosted MCP は OpenAI コネクタにも対応しています。`serverUrl` を指定する代わりに、コネクタの `connectorId` と `authorization` トークンを渡します。Responses API は認証を処理し、コネクタのツールを hosted MCP インターフェース経由で公開します。 +Hosted MCP は OpenAI コネクタにも対応しています。`serverUrl` を指定する代わりに、コネクタの `connectorId` と `authorization` トークンを渡します。Responses API が認証を処理し、コネクタのツールを hosted MCP インターフェース経由で公開します。 -この例では、環境変数 `GOOGLE_CALENDAR_AUTHORIZATION` に Google OAuth Playground で取得した OAuth トークンが格納されており、コネクタ対応サーバーが Calendar API を呼び出すことを許可します。ストリーミングもあわせて実演する実行可能なサンプルは [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors) を参照してください。 +この例では、`GOOGLE_CALENDAR_AUTHORIZATION` 環境変数に Google OAuth Playground で取得した OAuth トークンが格納されており、コネクタ対応サーバーが Calendar API を呼び出すことを許可します。ストリーミングもあわせて示す実行可能なサンプルは [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors) を参照してください。 -完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + Streaming、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + ストリーミング、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 ## 2. Streamable HTTP MCP servers -Agent がローカル・リモートの Streamable HTTP MCP サーバーと直接通信する場合は、サーバーの `url`、`name`、任意の設定を指定して `MCPServerStreamableHttp` を生成します: +エージェントがローカル/リモートの Streamable HTTP MCP サーバーと直接対話する場合は、サーバーの `url`、`name`、任意の設定を指定して `MCPServerStreamableHttp` をインスタンス化します: -コンストラクタは、`authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの追加の MCP TypeScript‑SDK オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) およびそのドキュメントを参照してください。 +コンストラクタは、`authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの追加の MCP TypeScript‑SDK オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 ## 3. Stdio MCP servers -標準 I/O のみを公開するサーバーの場合は、`fullCommand` を指定して `MCPServerStdio` を生成します: +標準入出力のみを公開するサーバーの場合は、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します: -## 補足事項 +## 知っておくとよいこと -**Streamable HTTP** と **Stdio** のサーバーでは、`Agent` が実行されるたびに使用可能なツールを検出するために `list_tools()` を呼ぶ場合があります。この往復は特にリモートサーバーではレイテンシーを増やす可能性があるため、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡して結果をメモリにキャッシュできます。 +**Streamable HTTP** と **Stdio** のサーバーでは、`Agent` が実行されるたびに、利用可能なツールを検出するために `list_tools()` を呼ぶ場合があります。特にリモートサーバーでは、この往復がレイテンシーを増やす可能性があるため、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡してメモリ内に結果をキャッシュできます。 -ツール一覧が変更されないと確信できる場合にのみ有効化してください。後でキャッシュを無効化するには、サーバーインスタンスの `invalidateToolsCache()` を呼び出します。 +ツールリストが変わらないと確信できる場合にのみ有効化してください。のちにキャッシュを無効化するには、サーバーインスタンスで `invalidateToolsCache()` を呼び出します。 ### ツールのフィルタリング -`createMCPToolStaticFilter` による静的フィルター、またはカスタム関数を渡すことで、各サーバーから公開されるツールを制限できます。両方のアプローチを示す複合例を次に示します: +`createMCPToolStaticFilter` による静的フィルター、またはカスタム関数を渡すことで、各サーバーから公開されるツールを制限できます。両方の方法を示す複合例は次のとおりです: - + ## 参考資料 - [Model Context Protocol](https://modelcontextprotocol.io/) – 公式仕様 -- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上記で参照した実行可能なデモ +- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上で参照した実行可能デモ diff --git a/docs/src/content/docs/ja/guides/models.mdx b/docs/src/content/docs/ja/guides/models.mdx index c555306e..5df8e2cf 100644 --- a/docs/src/content/docs/ja/guides/models.mdx +++ b/docs/src/content/docs/ja/guides/models.mdx @@ -12,12 +12,12 @@ import agentWithModelExample from '../../../../../../examples/docs/models/agentW import runnerWithModelExample from '../../../../../../examples/docs/models/runnerWithModel.ts?raw'; import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw'; -最終的にすべての エージェント は LLM を呼び出します。SDK は、モデルを次の 2 つの軽量インターフェースの背後に抽象化します: +すべての エージェント は最終的に LLM を呼び出します。SDK はモデルを 2 つの軽量なインターフェースの背後に抽象化します: -- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して _one_ 回のリクエストを行う方法を知っています -- [`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` のみを扱います。 ### GPT-5 モデル -この方法で GPT-5 の reasoning モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、[`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用する場合、SDK は既定で妥当な `modelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` の両方を `"low"` に設定します。デフォルトモデルの reasoning 努力度を調整するには、独自の `modelSettings` を渡してください: +この方法で GPT-5 の推論モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、[`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用する場合、SDK はデフォルトで妥当な `modelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` をともに `"low"` に設定します。デフォルトモデルの推論負荷を調整するには、独自の `modelSettings` を指定します: ```ts import { Agent } from '@openai/agents'; @@ -66,11 +66,11 @@ const myAgent = new Agent({ }); ``` -より低いレイテンシを求める場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を指定すると、デフォルト設定より高速に応答が返ることが多いです。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の reasoning 努力度をサポートしていないため、この Agents SDK ではデフォルトを `"low"` にしています。 +レイテンシをさらに下げるには、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) を `reasoning.effort="minimal"` とともに使用すると、デフォルト設定より高速に応答が返ることがよくあります。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の推論負荷をサポートしていないため、この Agents SDK ではデフォルトを `"low"` にしています。 ### 非 GPT-5 モデル -カスタムの `modelSettings` なしで GPT-5 以外のモデル名を渡すと、SDK は任意のモデルと互換性のある汎用 `modelSettings` に戻します。 +カスタムの `modelSettings` なしで非 GPT-5 のモデル名を指定した場合、SDK はあらゆるモデルと互換性のある汎用の `modelSettings` にフォールバックします。 --- @@ -78,10 +78,10 @@ const myAgent = new Agent({ デフォルトの `ModelProvider` は OpenAI API を使って名前を解決します。2 つの異なるエンドポイントをサポートします: -| API | 用途 | `setOpenAIAPI()` の呼び出し | -| ---------------- | --------------------------------------------------------------- | --------------------------------------- | -| Chat Completions | 標準的なチャット & function calls | `setOpenAIAPI('chat_completions')` | -| Responses | 新しい streaming‑first の生成 API（ツール呼び出し、柔軟な出力） | `setOpenAIAPI('responses')` _(default)_ | +| API | 用途 | `setOpenAIAPI()` の呼び出し | +| ---------------- | ------------------------------------------------------------------------ | --------------------------------------- | +| Chat Completions | 標準的なチャットと関数呼び出し | `setOpenAIAPI('chat_completions')` | +| Responses | 新しい ストリーミング ファーストの生成 API（ツール呼び出し、柔軟な出力） | `setOpenAIAPI('responses')` _(default)_ | ### 認証 @@ -91,46 +91,46 @@ const myAgent = new Agent({ title="既定の OpenAI キーを設定" /> -カスタムのネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 +ネットワーク設定をカスタマイズする必要がある場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 --- ## ModelSettings -`ModelSettings` は OpenAI のパラメーターを反映しますが、プロバイダーに依存しません。 +`ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダーに依存しません。 | フィールド | 型 | メモ | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ | | `temperature` | `number` | 創造性と決定性のバランス | -| `topP` | `number` | Nucleus sampling | -| `frequencyPenalty` | `number` | 繰り返しトークンを減点 | +| `topP` | `number` | nucleus sampling | +| `frequencyPenalty` | `number` | 繰り返しトークンを抑制 | | `presencePenalty` | `number` | 新しいトークンの出現を促進 | | `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 | -| `parallelToolCalls` | `boolean` | サポートされている場合に関数の並列呼び出しを許可 | -| `truncation` | `'auto' \| 'disabled'` | トークン切り詰め戦略 | -| `maxTokens` | `number` | 応答の最大トークン数 | -| `store` | `boolean` | 応答を永続化して取得 / RAG ワークフローで利用 | -| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 などの reasoning 努力度 | +| `parallelToolCalls` | `boolean` | サポートされる場合に関数呼び出しの並列実行を許可 | +| `truncation` | `'auto' \| 'disabled'` | トークンの切り捨て戦略 | +| `maxTokens` | `number` | 応答内の最大トークン数 | +| `store` | `boolean` | 応答を保存して取得 / RAG ワークフローで使用 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 などの推論負荷 | | `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 などのテキスト冗長度 | -設定はどちらのレベルにも適用できます: +設定はどちらのレベルにも付与できます: -`Runner` レベルの設定は、競合するエージェントごとの設定を上書きします。 +`Runner` レベルの設定は、競合するエージェント単位の設定を上書きします。 --- ## プロンプト -エージェントは `prompt` パラメーターで構成できます。これは エージェント の動作を制御するために使用すべき、サーバー保存のプロンプト構成を指示します。現在、このオプションは OpenAI の +エージェントには `prompt` パラメーターを設定でき、エージェントの振る舞いを制御するために使用すべき サーバー保存 のプロンプト構成を示します。現在、このオプションは OpenAI の [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみサポートされています。 -| フィールド | 型 | メモ | -| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | プロンプトの一意識別子 | -| `version` | `string` | 使用したいプロンプトのバージョン | -| `variables` | `object` | プロンプトに代入する変数のキー/値ペア。値は文字列、またはテキスト・画像・ファイルなどのコンテンツ入力タイプを指定可能 | +| フィールド | 型 | メモ | +| ----------- | -------- | ----------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | プロンプトの一意の識別子 | +| `version` | `string` | 使用したいプロンプトのバージョン | +| `variables` | `object` | プロンプトに差し込む変数のキー/値。値は文字列またはテキスト・画像・ファイルなどのコンテンツ入力型を指定可能 | -これにより、[OpenAI ダッシュボード](https://platform.openai.com/traces) にトレースが送信され、ワークフローの実行グラフ全体を確認できます。 +これによりトレースが [OpenAI ダッシュボード](https://platform.openai.com/traces) に送信され、ワークフローの完全な実行グラフを確認できます。 --- -## 次のステップ +## 次の手順 - [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を探索する - [ツール](/openai-agents-js/ja/guides/tools) でモデルに強力な機能を付与する diff --git a/docs/src/content/docs/ja/guides/multi-agent.md b/docs/src/content/docs/ja/guides/multi-agent.md index b9590e10..2936f9a5 100644 --- a/docs/src/content/docs/ja/guides/multi-agent.md +++ b/docs/src/content/docs/ja/guides/multi-agent.md @@ -3,38 +3,38 @@ title: マルチエージェント description: Coordinate the flow between several agents --- -オーケストレーションとは、アプリ内のエージェントの流れを指します。どのエージェントがどの順序で動き、次に何をするかをどう決めるか。エージェントをオーケストレーションする方法は主に 2 つあります。 +オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが、どの順番で実行され、次に何をするかをどのように決めるのか。エージェントをオーケストレーションする主な方法は 2 つあります。 -1. LLM に意思決定させる: これは LLM の知能を使って計画・推論し、それに基づいて次のステップを決めます -2. コードでオーケストレーションする: コードでエージェントの流れを決めます +1. LLM に意思決定させる方法: LLM の知能を使い、計画・推論し、次に取るべきステップを決定します +2. コードでオーケストレーションする方法: コードでエージェントの流れを決定します -これらのパターンは組み合わせて使えます。以下にそれぞれのトレードオフを記載します。 +これらのパターンは組み合わせて使えます。各手法にはトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントは、instructions、ツール、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたときに、LLM はツールを使って行動したりデータを取得したり、ハンドオフでサブエージェントに委譲したりしながら、タスクへの取り組み方を自律的に計画できます。たとえば、リサーチ用エージェントには次のようなツールを備えられます。 +エージェントは、指示・ツール・ハンドオフを備えた LLM です。これは、オープンエンドなタスクに対して、LLM が自律的に計画を立て、ツールで行動・データ収集を行い、ハンドオフでサブエージェントに委譲できることを意味します。たとえば、リサーチエージェントは次のようなツールを備えられます。 -- オンライン情報を見つけるための Web 検索 -- プロプライエタリデータや接続先を横断的に探すためのファイル検索と取得 -- コンピュータ操作でコンピュータ上のアクションを実行 -- データ分析を行うためのコード実行 -- 計画、レポート作成などに長けた専門エージェントへのハンドオフ +- Web 検索でオンライン情報を見つける +- ファイル検索と取得で社内データや接続を横断して検索する +- コンピュータ操作でコンピュータ上のアクションを実行する +- コード実行でデータ分析を行う +- 計画立案、レポート作成などに長けた専門エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで LLM の知能に頼りたいときに有効です。ここで重要な戦術は次のとおりです。 +このパターンはタスクがオープンエンドで、LLM の知能に頼りたい場合に有効です。重要な戦術は次のとおりです。 -1. 良いプロンプトに投資すること。利用可能なツール、その使い方、準拠すべきパラメーターを明確にする -2. アプリを監視して改善を回すこと。問題が起きる箇所を見極め、プロンプトを反復改善する -3. エージェントに内省と改善を許すこと。たとえばループで実行して自己批評させる、エラーメッセージを与えて改善させる -4. なんでもこなす汎用エージェントではなく、1 つのタスクに特化して卓越したエージェントを用意する -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練してタスク遂行能力を高められます +1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーターを明確にする +2. アプリを監視して反復する。問題が起きる箇所を見つけ、プロンプトを改善する +3. エージェントに内省と改善を許可する。たとえばループで実行し自己批評させる、またはエラーメッセージを与えて改善させる +4. なんでもこなす汎用エージェントではなく、1 つのタスクに特化して優れる専門エージェントを用意する +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスク遂行能力を高められます ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度、コスト、性能の面でより決定的かつ予測可能にできます。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の観点で、より決定論的かつ予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。たとえば、タスクをいくつかのカテゴリーに分類するようエージェントに依頼し、そのカテゴリーに基づいて次のエージェントを選ぶ -- あるエージェントの出力を次のエージェントの入力に変換して、複数のエージェントを連鎖させる。ブログ記事執筆のようなタスクを、調査→アウトライン作成→本文作成→批評→改善という一連のステップに分解する -- タスクを実行するエージェントと、それを評価してフィードバックを返すエージェントを `while` ループで回し、評価者が出力が一定の基準を満たしたと判断するまで続ける -- 複数のエージェントを並列実行する。たとえば `Promise.all` のような JavaScript の basic components を使う。相互依存しない複数タスクがある場合に速度面で有用 +- [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) に多数の code examples があります。 diff --git a/docs/src/content/docs/ja/guides/quickstart.mdx b/docs/src/content/docs/ja/guides/quickstart.mdx index 4bb0671a..245085bb 100644 --- a/docs/src/content/docs/ja/guides/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. プロジェクトを作成して npm を初期化します。これは一度だけ実行すれば大丈夫です。 +1. プロジェクトを作成して npm を初期化します。これは一度だけで大丈夫です ```bash mkdir my_project @@ -19,26 +19,26 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm init -y ``` -2. Agents SDK をインストールします。 +2. Agents SDK をインストールします ```bash npm install @openai/agents zod@3 ``` -3. OpenAI API key を設定します。まだお持ちでない場合は、OpenAI API key を作成するために[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従ってください。 +3. OpenAI API キーを設定します。お持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください ```bash export OPENAI_API_KEY=sk-... ``` - あるいは、`setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、トレーシング用に `setTracingExportApiKey('')` を使用できます。 - 詳細は [SDK の設定](/openai-agents-js/ja/guides/config) をご覧ください。 + または `setDefaultOpenAIKey('')` を呼び出してプログラムでキーを設定し、トレーシングには `setTracingExportApiKey('')` を使用できます。 + 詳細は[SDK の設定](/openai-agents-js/ja/guides/config)を参照してください ## 最初のエージェントの作成 -エージェントは instructions と名前で定義します。 +エージェントは instructions と name で定義します ```typescript import { Agent } from '@openai/agents'; @@ -52,9 +52,9 @@ const agent = new Agent({ ## 最初のエージェントの実行 -`run` メソッドを使ってエージェントを実行できます。開始するエージェントと、渡したい入力の両方を渡して実行をトリガーします。 +`run` メソッドを使ってエージェントを実行できます。開始するエージェントと、渡したい入力の両方を渡して実行をトリガーします -これにより、その実行中に行われた最終出力と任意のアクションを含む結果が返されます。 +これにより、その実行中に行われた最終出力とアクションを含む実行結果が返されます ```typescript import { Agent, run } from '@openai/agents'; @@ -70,9 +70,9 @@ const result = await run(agent, 'When did sharks first appear?'); console.log(result.finalOutput); ``` -## エージェントにツールを付与 +## エージェントへのツールの付与 -情報を参照したりアクションを実行したりするためのツールをエージェントに付与できます。 +情報の検索やアクションの実行に使えるツールをエージェントに与えることができます ```typescript import { Agent, tool } from '@openai/agents'; @@ -101,7 +101,7 @@ const agent = new Agent({ ## いくつかのエージェントの追加 -追加のエージェントを同様に定義して、問題を小さな部分に分割し、エージェントを目の前のタスクにより集中させることができます。また、エージェント上でモデルを定義することで、異なる問題に対して異なるモデルを使用することもできます。 +追加のエージェントを同様に定義して、問題をより小さな部分に分割し、エージェントを目の前のタスクにより集中させることができます。また、エージェントにモデルを定義することで、問題ごとに異なるモデルを使用できます ```typescript const historyTutorAgent = new Agent({ @@ -119,7 +119,7 @@ const mathTutorAgent = new Agent({ ## ハンドオフの定義 -複数のエージェント間でオーケストレーションするために、エージェントに対して `handoffs` を定義できます。これにより、エージェントは次のエージェントに会話を渡せるようになります。これは実行の過程で自動的に行われます。 +複数のエージェント間をオーケストレーションするために、エージェントに `handoffs` を定義できます。これにより、エージェントは会話を次のエージェントに引き継げるようになります。これは実行の過程で自動的に行われます ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -131,11 +131,11 @@ const triageAgent = Agent.create({ }); ``` -実行後、結果の `finalAgent` プロパティを見ると、どのエージェントが最終応答を生成したかがわかります。 +実行後、結果の `finalAgent` プロパティを見ることで、どのエージェントが最終応答を生成したかを確認できます ## エージェントオーケストレーションの実行 -Runner は、個々のエージェントの実行、必要に応じたハンドオフ、ツールの実行を処理します。 +Runner は個々のエージェントの実行、潜在的なハンドオフ、ツール実行の処理を行います ```typescript import { run } from '@openai/agents'; @@ -148,23 +148,22 @@ async function main() { main().catch((err) => console.error(err)); ``` -## まとめ +## すべての統合 -すべてを 1 つの完全な例にまとめましょう。これを `index.js` ファイルに配置して実行します。 +すべてを 1 つの完全な例にまとめましょう。これを `index.js` ファイルに配置して実行します - + ## トレースの表示 -Agents SDK は自動的にトレースを生成します。これにより、エージェントがどのように動作したか、どのツールを呼び出したか、どのエージェントにハンドオフしたかを確認できます。 +Agents SDK は自動的にトレースを生成します。これにより、エージェントがどのように動作し、どのツールを呼び出し、どのエージェントにハンドオフしたかを確認できます -エージェントの実行中に何が起きたかを確認するには、 -[OpenAI Dashboard の Trace viewer](https://platform.openai.com/traces) に移動します。 +エージェントの実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace ビューアー](https://platform.openai.com/traces)に移動します ## 次のステップ -より複雑なエージェント フローの構築方法を学びましょう: +より複雑なエージェントフローの構築方法を学びましょう -- [エージェント](/openai-agents-js/ja/guides/agents) の設定について学ぶ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) について学ぶ -- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) について学ぶ +- [エージェント](/openai-agents-js/ja/guides/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 9f5e6ed3..ac889098 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`）バージョン -ベータではない公開インターフェースに対する **breaking changes** に対して、マイナーバージョン `Y` を増やします。例えば、`0.0.x` から `0.1.x` への更新には breaking changes が含まれる可能性があります。 +ベータではない公開インターフェースに **互換性を壊す変更** がある場合、マイナーバージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への更新には互換性を壊す変更が含まれることがあります。 -breaking changes を避けたい場合は、プロジェクトで `0.0.x` にピン留めすることを推奨します。 +互換性を壊す変更を避けたい場合は、プロジェクトで `0.0.x` にピン留めすることをおすすめします。 -## パッチ (`Z`) バージョン +## パッチ（`Z`）バージョン -非破壊的な変更に対して `Z` を増やします。 +後方互換な変更では `Z` を増やします。 - バグ修正 - 新機能 @@ -24,11 +24,11 @@ breaking changes を避けたい場合は、プロジェクトで `0.0.x` にピ ## サブパッケージのバージョニング -メインの `@openai/agents` パッケージは、個別に利用可能な複数のサブパッケージで構成されています。現時点では、パッケージ間でバージョンは連動しており、いずれかのパッケージでバージョンが上がると他も同様に上がります。`1.0.0` への移行にあたって、この方針を変更する可能性があります。 +メインの `@openai/agents` パッケージは、個別に使用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、いずれかのパッケージのバージョンが上がると他も同様に上がります。`1.0.0` に移行する際には、この方針を変更する可能性があります。 ## 変更履歴 -各サブパッケージごとに変更履歴を生成しており、変更内容の把握に役立てることができます。変更がサブパッケージ内で起きている場合、その該当する変更履歴を参照する必要があります。 +変更点の把握を助けるため、各サブパッケージごとに変更履歴を生成しています。変更がサブパッケージ内で行われた場合、その変更の詳細は該当する変更履歴を参照する必要があります。 - [`@openai/agents`](https://github.com/openai/openai-agents-js/blob/main/packages/agents/CHANGELOG.md) - [`@openai/agents-core`](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/CHANGELOG.md) diff --git a/docs/src/content/docs/ja/guides/results.mdx b/docs/src/content/docs/ja/guides/results.mdx index 4e41364b..cbca7ef8 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -7,23 +7,23 @@ import { Code } from '@astrojs/starlight/components'; import handoffFinalOutputTypes from '../../../../../../examples/docs/results/handoffFinalOutputTypes.ts?raw'; import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts?raw'; -[エージェントの実行](/openai-agents-js/ja/guides/running-agents)を行うと、次のいずれかを受け取ります: +[エージェントを実行](/openai-agents-js/ja/guides/running-agents)すると、次のいずれかを受け取ります: -- [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) — `stream: true` なしで `run` を呼び出した場合 -- [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult) — `stream: true` ありで `run` を呼び出した場合。ストリーミングの詳細は[ストリーミング](/openai-agents-js/ja/guides/streaming)も参照してください +- `stream: true` を指定せずに `run` を呼び出した場合は [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) +- `stream: true` を指定して `run` を呼び出した場合は [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。ストリーミングの詳細は [ストリーミング](/openai-agents-js/ja/guides/streaming) も参照してください ## 最終出力 -`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が入ります。結果は次のいずれかです: +`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が含まれます。結果は次のいずれかです: -- `string` — `outputType` が未定義の任意のエージェントのデフォルト -- `unknown` — 出力タイプとして JSON スキーマが定義されている場合。この場合 JSON はパースされていますが、型は手動で検証する必要があります -- `z.infer` — 出力タイプとして Zod スキーマが定義されている場合。出力は自動的にこのスキーマでパースされます +- `string` — `outputType` が定義されていないエージェントのデフォルト +- `unknown` — エージェントが出力タイプとして JSON スキーマを定義している場合。この場合は JSON がパースされていますが、型の検証は手動で行う必要があります +- `z.infer` — エージェントが出力タイプとして Zod スキーマを定義している場合。出力は自動的にこのスキーマに対してパースされます - `undefined` — エージェントが出力を生成しなかった場合（たとえば出力を生成する前に停止した場合） -異なる出力タイプのハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 +異なる出力タイプを持つハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 -これにより、SDK がすべての可能なハンドオフにわたって出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 +これにより、SDK がすべての可能なハンドオフにわたる出力タイプを推論し、`finalOutput` プロパティに対して共用型を提供できるようになります。 例: @@ -33,57 +33,57 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? title="Handoff final output types" /> -## 次のターンへの入力 +## 次ターンの入力 -次のターン用の入力には 2 つの方法でアクセスできます: +次のターンの入力にアクセスする方法は 2 つあります: -- `result.history` — 入力とエージェントの出力の両方のコピーを保持 -- `result.output` — エージェント全体の実行結果の出力を保持 +- `result.history` — 入力とエージェントの出力の両方のコピーを含みます +- `result.output` — エージェントの全実行の出力を含みます -`history` は、チャットのようなユースケースで完全な履歴を維持するのに便利です: +`history` はチャットのようなユースケースで完全な履歴を維持するのに便利です: ## 最後のエージェント -`lastAgent` プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、次回のユーザー入力時に有用です。たとえば、一次トリアージのエージェントが言語別のエージェントへハンドオフする場合、最後のエージェントを保存して、次回ユーザーがメッセージを送ったときに再利用できます。 +`lastAgent` プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回の ユーザー 入力時に有用です。たとえば、一次トリアージのエージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存して、次に ユーザー がメッセージを送ったときに再利用できます。 -ストリーミングモードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスするのも有用です。 +ストリーミング モードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスするのも有用です。 -## 新しいアイテム +## 新規アイテム -`newItems` プロパティには、実行中に生成された新しいアイテムが入ります。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。ランアイテムは、LLM が生成した元のアイテムをラップします。これにより、LLM の出力に加えて、これらのイベントがどのエージェントに関連付けられていたかにアクセスできます。 +`newItems` プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。実行アイテムは、LLM が生成した元アイテムをラップします。これにより、LLM の出力に加えて、これらのイベントがどのエージェントに関連付けられていたかにアクセスできます。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元のアイテムは生成されたメッセージです -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフツールを呼び出したことを示します。元のアイテムは LLM からのツール呼び出しアイテムです -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。元のアイテムはハンドオフツール呼び出しへのツールレスポンスです。アイテムからソース/ターゲットのエージェントにもアクセスできます -- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを呼び出したことを示します -- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。元のアイテムはツールレスポンスです。アイテムからツール出力にもアクセスできます -- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM の reasoning アイテムを示します。元のアイテムは生成された reasoning です -- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。元のアイテムは LLM からのツール呼び出しアイテムです +- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元アイテムは生成されたメッセージです +- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は、LLM がハンドオフ ツールを呼び出したことを示します。元アイテムは LLM からのツール呼び出しアイテムです +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) は、ハンドオフが発生したことを示します。元アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます +- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は、LLM がツールを呼び出したことを示します +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) は、ツールが呼び出されたことを示します。元アイテムはツールの応答です。アイテムからツール出力にもアクセスできます +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は、LLM からのリースニング項目を示します。元アイテムは生成されたリースニングです +- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は、LLM がツール呼び出しの承認を要求したことを示します。元アイテムは LLM からのツール呼び出しアイテムです ## 状態 -`state` プロパティには実行の状態が入ります。`result` に付随するほとんどの情報は `state` から導出されますが、`state` はシリアライズ/デシリアライズ可能で、[エラーからの復旧](/openai-agents-js/ja/guides/running-agents#exceptions)や[`interruption`](#interruptions)に対処する必要がある場合に、後続の `run` 呼び出しの入力としても使用できます。 +`state` プロパティには実行の状態が含まれます。`result` に付随する情報の大半は `state` から導出されますが、`state` はシリアライズ/デシリアライズ可能で、[エラーから復旧](/openai-agents-js/ja/guides/running-agents#exceptions) する必要がある場合や、[`interruption`](#interruptions) に対処する必要がある場合に `run` への後続の呼び出しの入力としても使用できます。 ## 中断 -エージェントで `needsApproval` を使用している場合、続行前に処理する必要がある `interruptions` が `run` によりトリガーされることがあります。この場合、`interruptions` は中断の原因となった `ToolApprovalItem` の配列になります。中断への対処方法の詳細は、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)を参照してください。 +エージェントで `needsApproval` を使用している場合、続行する前に処理が必要な `interruptions` が発生することがあります。その場合、`interruptions` は中断を引き起こした `ToolApprovalItem` の配列になります。中断への対処方法の詳細は、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) を参照してください。 ## その他の情報 -### 元レスポンス +### raw レスポンス -`rawResponses` プロパティには、エージェント実行中にモデルが生成した元の LLM レスポンスが入ります。 +`rawResponses` プロパティには、エージェントの実行中にモデルが生成した元の LLM レスポンスが含まれます。 ### 最後のレスポンス ID -`lastResponseId` プロパティには、エージェント実行中にモデルが生成した最後のレスポンスの ID が入ります。 +`lastResponseId` プロパティには、エージェントの実行中にモデルが生成した最後のレスポンスの ID が含まれます。 ### ガードレールの結果 -`inputGuardrailResults` と `outputGuardrailResults` プロパティには、存在する場合にガードレールの結果が入ります。ガードレール結果には、記録や保存に有用な情報が含まれることがあるため、利用できるようにしています。 +`inputGuardrailResults` と `outputGuardrailResults` プロパティには、存在する場合はガードレールの結果が含まれます。ガードレールの結果には、ログや保存を行いたい有用な情報が含まれることがあるため、ここで参照できるようにしています。 ### 元の入力 -`input` プロパティには、run メソッドに渡した元の入力が入ります。ほとんどのケースでは不要ですが、必要な場合に参照できます。 +`input` プロパティには、run メソッドに渡した元の入力が含まれます。ほとんどの場合これは不要ですが、必要に応じて利用できます。 diff --git a/docs/src/content/docs/ja/guides/running-agents.mdx b/docs/src/content/docs/ja/guides/running-agents.mdx index bd782c66..af3619ba 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -9,111 +9,107 @@ import helloWorldExample from '../../../../../../examples/docs/hello-world.ts?ra import runningAgentsExceptionExample from '../../../../../../examples/docs/running-agents/exceptions1.ts?raw'; import chatLoopExample from '../../../../../../examples/docs/running-agents/chatLoop.ts?raw'; -エージェントは自分からは何もしません。`Runner` クラスまたは `run()` ユーティリティで実行 **run** します。 +エージェントはそれ自体では何もしません。`Runner` クラスまたは `run()` ユーティリティでそれらを **run** します。 - + -カスタム runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスで動作する `run()` ユーティリティも使えます。 +カスタム runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスを実行する `run()` ユーティリティも使えます。 -別途 runner インスタンスを作成することもできます: +あるいは、独自の runner インスタンスを作成できます。 - + -エージェントの実行後、最終出力と実行の完全な履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 +エージェントの実行後、最終出力と実行の全履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 ## エージェントループ -Runner の run メソッドを使うときは、開始エージェントと入力を渡します。入力は文字列（ユーザーのメッセージと見なされます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。 +Runner の run メソッドを使うときは、開始するエージェントと入力を渡します。入力は、文字列（ユーザー メッセージとして扱われます）か、OpenAI Responses API の項目である入力アイテムのリストのいずれかです。 -runner は次のループを実行します: +runner は次のループを実行します。 1. 現在の入力で現在のエージェントのモデルを呼び出す -2. LLM の応答を確認する - - **最終出力** → 返す - - **ハンドオフ** → 新しいエージェントに切り替え、累積された会話履歴を保持し、1 に戻る - - **ツール呼び出し** → ツールを実行し、その結果を会話に追加し、1 に戻る -3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を投げる +2. LLM レスポンスを検査する + - **Final output** → return + - **Handoff** → 新しいエージェントに切り替え、蓄積された会話履歴を保持して、1 に戻る + - **Tool calls** → ツールを実行し、その結果を会話に追加して、1 に戻る +3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローする -### Runner のライフサイクル +### Runner ライフサイクル -アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシング設定などのグローバル設定を保持します。まったく異なるセットアップが必要な場合のみ別の `Runner` を作成します。簡単なスクリプトでは、内部でデフォルト runner を使う `run()` を呼び出すこともできます。 +アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダやトレーシングオプションなどのグローバル設定を保持します。まったく別のセットアップが必要な場合のみ、別の `Runner` を作成してください。簡単なスクリプトでは、内部でデフォルト runner を使う `run()` を呼ぶこともできます。 -## Run 引数 +## 実行引数 -`run()` メソッドの入力は、実行を開始する初期エージェント、実行の入力、および一連のオプションです。 +`run()` メソッドへの入力は、実行を開始する初期エージェント、実行用の入力、そして一連のオプションです。 -入力は、文字列（ユーザーのメッセージと見なされます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 +入力は、文字列（ユーザー メッセージとして扱われます）、[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 | 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` | +| Option | Default | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着したイベントを順次発行します | +| `context` | – | すべての tool / guardrail / handoff に転送されるコンテキスト オブジェクト。詳細は [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 | +| `maxTurns` | `10` | 安全制限。到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローします | +| `signal` | – | キャンセル用の `AbortSignal` | ## ストリーミング -ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリームが開始されると、`StreamedRunResult` には、生成されたすべての新しい出力を含む、実行に関する完全な情報が含まれます。`for await` ループでストリーミングイベントを反復処理できます。詳しくは[ストリーミング](/openai-agents-js/ja/guides/streaming)を参照してください。 +ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリーム開始後、`StreamedRunResult` には、新たに生成されたすべての出力を含め、実行に関する完全な情報が含まれます。`for await` ループでストリーミングイベントを反復処理できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 -## Run 設定 +## 実行設定 -独自の `Runner` インスタンスを作成する場合、runner を構成するために `RunConfig` オブジェクトを渡せます。 +独自の `Runner` インスタンスを作成する場合は、runner を構成するために `RunConfig` オブジェクトを渡せます。 -| Field | Type | Purpose | -| --------------------------- | --------------------- | -------------------------------------------------------------------------- | -| `model` | `string \| Model` | 実行中の **すべて** のエージェントに特定のモデルを強制します | -| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダーです | -| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニングパラメーター | -| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ時に入力アイテムを変換します（ハンドオフ自体に定義がない場合） | -| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | -| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | -| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します | -| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、LLM/ツールの入出力をトレースから除外します | -| `workflowName` | `string` | Traces ダッシュボードに表示され、関連する実行のグルーピングに役立ちます | -| `traceId` / `groupId` | `string` | SDK に生成させる代わりに、トレース ID またはグループ ID を手動で指定します | -| `traceMetadata` | `Record` | すべてのスパンに添付する任意のメタデータ | +| Field | Type | Purpose | +| --------------------------- | --------------------- | ------------------------------------------------------------------------- | +| `model` | `string \| Model` | 実行中の **すべて** のエージェントに特定のモデルを強制します | +| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダです | +| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニングパラメーター | +| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ時に入力アイテムを変換します（ハンドオフ自体で未定義の場合） | +| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | +| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | +| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します | +| `traceIncludeSensitiveData` | `boolean` | スパンは出しつつ、トレースから LLM/ツールの入力と出力を除外します | +| `workflowName` | `string` | Traces ダッシュボードに表示。関連する実行をグルーピングするのに役立ちます | +| `traceId` / `groupId` | `string` | SDK に生成させず、トレース ID またはグループ ID を手動で指定します | +| `traceMetadata` | `Record` | すべてのスパンに付与する任意のメタデータ | ## 会話 / チャットスレッド -`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における 1 回の **ターン** を表します。エンドユーザーにどれだけの `RunResult` を見せるかは任意です。`finalOutput` のみの場合もあれば、生成されたすべてのアイテムを見せる場合もあります。 +`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における 1 回の **ターン** を表します。エンドユーザーに `RunResult` のどこまでを見せるかは任意で、`finalOutput` だけのときもあれば、生成されたすべてのアイテムを見せるときもあります。 - + -インタラクティブ版は[チャットのコード例](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts)を参照してください。 +インタラクティブ版は[チャットのサンプル](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts)を参照してください。 ## 例外 -SDK はキャッチ可能な少数のエラーを投げます: +SDK は捕捉可能な少数のエラーをスローします。 - [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` に到達 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが無効な出力を生成（例: 不正な JSON、未知のツール） +- [`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) – ガードレールが完了に失敗 +- [`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) – 設定またはユーザー入力に基づいて投げられるエラー +- [`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! @@ -124,6 +120,6 @@ Math homework guardrail tripped ## 次のステップ -- [モデル](/openai-agents-js/ja/guides/models)の設定方法を学ぶ -- エージェントに[ツール](/openai-agents-js/ja/guides/tools)を提供する -- 本番対応のために[ガードレール](/openai-agents-js/ja/guides/guardrails)や[トレーシング](/openai-agents-js/ja/guides/tracing)を追加する +- [モデルの構成](/openai-agents-js/ja/guides/models) を学ぶ +- エージェントに [ツール](/openai-agents-js/ja/guides/tools) を提供する +- 本番対応のために [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加する diff --git a/docs/src/content/docs/ja/guides/streaming.mdx b/docs/src/content/docs/ja/guides/streaming.mdx index dcacd68a..b4b8e1c3 100644 --- a/docs/src/content/docs/ja/guides/streaming.mdx +++ b/docs/src/content/docs/ja/guides/streaming.mdx @@ -9,51 +9,48 @@ import nodeTextStreamExample from '../../../../../../examples/docs/streaming/nod import handleAllEventsExample from '../../../../../../examples/docs/streaming/handleAllEvents.ts?raw'; import streamedHITLExample from '../../../../../../examples/docs/streaming/streamedHITL.ts?raw'; -Agents SDK は、モデルおよびその他の実行ステップからの出力を段階的に配信できます。ストリーミングにより UI を応答性良く保ち、エンドユーザーへ更新を行う前に最終結果全体を待つ必要がなくなります。 +Agents SDK は、モデルや他の実行ステップの出力を増分で届けます。ストリーミングにより UI を応答性良く保ち、ユーザー更新の前に最終結果全体を待つ必要がなくなります。 ## ストリーミングの有効化 -`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミングオブジェクトを取得します: +`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミングオブジェクトを取得できます: -ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、その実行中に何が起きたかを説明するオブジェクトです。ストリームは、エージェントの実行の異なる部分を表す 3 種類のイベントのいずれかを生成します。 -ただし多くのアプリケーションはモデルのテキストだけを必要とするため、ストリームにはそのためのヘルパーが用意されています。 +ストリーミングを有効にすると、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、実行中に何が起きたかを表すオブジェクトです。ストリームはエージェントの実行の異なる部分を表す 3 種類のイベントのいずれかを返します。ほとんどのアプリケーションはモデルのテキストだけが必要なので、ストリームにはヘルパーが用意されています。 ### テキスト出力の取得 -発行されたテキストのストリームを取得するには `stream.toTextStream()` を呼びます。 -`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js の `Readable` です。`process.stdout` や別の出力先にそのままパイプできます。 +発行されたテキストのストリームを得るには `stream.toTextStream()` を呼びます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js の `Readable` です。`process.stdout` などの出力先に直接パイプできます。 -`stream.completed` の Promise は、実行と保留中のすべてのコールバックが完了すると解決します。出力がもうないことを確実にするには、常にこれを await してください。 +`stream.completed` の Promise は、実行と未処理のコールバックがすべて完了した時に解決されます。出力がもうないことを確実にする場合は必ず await してください。 -### すべてのイベントの監視 +### すべてのイベントのリッスン -`for await` ループを使って、到着した各イベントを検査できます。 -有用な情報には、低レベルのモデルイベント、エージェントの切り替え、そして SDK 固有の実行情報などが含まれます: +`for await` ループで、到着した各イベントを検査できます。役立つ情報には、低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などがあります: -両方のストリーム（プレーンテキストのストリームと raw イベントストリーム）を出力する完全なスクリプトは、[ストリーミングの code examples](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。 +完全なプレーンテキストストリームと元のイベントストリームの両方を出力するスクリプトは、[the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。 ## イベントタイプ -ストリームは 3 種類のイベントタイプを生成します: +ストリームは 3 種類のイベントタイプを返します: ### raw_model_stream_event @@ -121,25 +118,23 @@ type RunAgentUpdatedStreamEvent = { } ``` -## ストリーミング中の Human in the loop（人間の介入） +## ストリーミング中の Human in the loop -ストリーミングは、実行を一時停止するハンドオフ（たとえばツールが承認を必要とする場合）と両立します。ストリームオブジェクトの `interruption` フィールドで割り込みにアクセスでき、各割り込みに対して `state.approve()` または `state.reject()` を呼ぶことで実行を継続できます。 -`{ stream: true }` で再実行するとストリーミング出力が再開します。 +ストリーミングは、実行を一時停止するハンドオフ（たとえばツールに承認が必要な場合）と両立します。ストリームオブジェクトの `interruption` フィールドは中断を公開しており、各中断に対して `state.approve()` または `state.reject()` を呼ぶことで実行を継続できます。`{ stream: true }` で再実行するとストリーミング出力が再開されます。 ユーザーと対話する、より充実した例は -[`human-in-the-loop-stream.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop-stream.ts) -にあります。 +[`human-in-the-loop-stream.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop-stream.ts) を参照してください。 -## ヒント +## Tips -- すべての出力がフラッシュされたことを確実にするため、終了前に `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 b2cc9242..9cdf1a39 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,36 +10,36 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -ツールはエージェントが **アクションを実行** する手段です。データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの使用まで可能にします。JavaScript/TypeScript SDK は次の 4 つのカテゴリーに対応します: +ツールは、エージェントが **アクションを実行** できるようにします。データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの使用まで対応します。JavaScript/TypeScript SDK は 4 つのカテゴリーをサポートします: -1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと並行して実行（Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成） -2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップして LLM が呼び出せるようにする -3. **ツールとしてのエージェント** – エージェント全体を呼び出し可能なツールとして公開 -4. **ローカル MCP サーバー** – あなたのマシン上で動作する Model Context Protocol サーバーを接続 +1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと並行して実行します（Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成） +2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM が呼び出せるようにします +3. **エージェントをツールとして使用** – エージェント全体を呼び出し可能なツールとして公開します +4. **ローカル MCP サーバー** – お使いのマシン上で動作する Model context protocol のサーバーを接続します --- ## 1. 組み込みツール（Hosted） -`OpenAIResponsesModel` を使う場合、次の組み込みツールを追加できます: +`OpenAIResponsesModel` を使用する場合、次の組み込みツールを追加できます: -| ツール | 型文字列 | 目的 | -| ----------------------- | -------------------- | --------------------------------------------- | -| Web search | `'web_search'` | インターネット検索 | -| File / retrieval search | `'file_search'` | OpenAI 上でホストされるベクトルストアのクエリ | -| Computer use | `'computer'` | GUI 操作を自動化 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | -| Image generation | `'image_generation'` | テキストに基づいて画像を生成 | +| ツール | Type 文字列 | 目的 | +| ------------------- | -------------------- | ------------------------------------------------- | +| 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()` ヘルパーで **任意** の関数をツール化できます。 string \| Promise`– ビジネスロジック本体。2 番目の引数は任意で `RunContext` | -| `errorFunction` | いいえ | 内部エラーをユーザーに見える文字列に変換するためのカスタムハンドラ `(context, error) => string` | +| フィールド | 必須 | 説明 | +| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `name` | いいえ | デフォルトは関数名（例: `get_weather`） | +| `description` | はい | LLM に表示される明確で人間が読める説明 | +| `parameters` | はい | Zod スキーマまたは raw の JSON スキーマオブジェクトのいずれか。Zod の parameters を使うと自動的に **strict** モードが有効になります | +| `strict` | いいえ | `true`（デフォルト）の場合、引数が検証に通らないと SDK はモデルエラーを返します。あいまい一致にするには `false` に設定します | +| `execute` | はい | `(args, context) => string \| Promise` – ビジネスロジック。2 つ目の引数は省略可能で、`RunContext` です | +| `errorFunction` | いいえ | 内部エラーをユーザーに見える文字列へ変換するカスタムハンドラー `(context, error) => string` | -### 非厳密 JSON スキーマのツール +### 非 strict な JSON スキーマツール -無効または不完全な入力をモデルに推測させたい場合は、元の JSON スキーマを使う際に strict モードを無効化できます: +無効または不完全な入力をモデルに推測させたい場合は、raw の JSON スキーマ使用時に strict モードを無効化できます: 内部的に SDK は次を行います: - 単一の `input` パラメーターを持つ関数ツールを作成 -- ツールが呼び出されたときにその入力でサブエージェントを実行 -- 最後のメッセージ、または `customOutputExtractor` により抽出された出力を返却 +- ツールが呼び出されたときに、その入力でサブエージェントを実行 +- 最終メッセージ、または `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) を参照してください。 +完全な例については [`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) を参照してください。 +モデルがいつどのようにツールを使用するか（`tool_choice`、`toolUseBehavior` など）を制御するには、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください。 --- ## ベストプラクティス -- **短く明確な説明** – ツールが何をするのか、いつ使うのかを記述 +- **短く明確な説明** – ツールが何をするか、いつ使うかを記述する - **入力を検証** – 可能な限り Zod スキーマで厳密な JSON 検証を行う -- **エラーハンドラで副作用を避ける** – `errorFunction` は役立つ文字列を返し、throw しない -- **ツールは単一責務** – 小さく合成可能なツールはモデルの推論精度を高める +- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返し、例外は投げない +- **ツールごとに 1 つの責務** – 小さく合成可能なツールはモデルの推論を改善する --- ## 次のステップ -- [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) について学ぶ +- [エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) で強制的なツール使用について学ぶ - ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 - [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種 組み込みツール（Hosted）タイプの TypeDoc リファレンスを読む diff --git a/docs/src/content/docs/ja/guides/tracing.mdx b/docs/src/content/docs/ja/guides/tracing.mdx index edf84e7a..06876642 100644 --- a/docs/src/content/docs/ja/guides/tracing.mdx +++ b/docs/src/content/docs/ja/guides/tracing.mdx @@ -7,24 +7,24 @@ import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw'; -Agents SDK にはトレーシングが組み込まれており、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらに発生したカスタムイベントまで含まれます。[Traces ダッシュボード](https://platform.openai.com/traces)を使って、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みのトレーシングが含まれており、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントも対象です。[Traces dashboard](https://platform.openai.com/traces) を使うと、開発時や本番環境でワークフローをデバッグ、可視化、監視できます。 ## エクスポートループのライフサイクル -多くの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。キューが溜まりすぎた場合にはトレースはエクスポートされますが、定期的なエクスポートは行われません。代わりに、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使ってトレースを手動でエクスポートしてください。 +多くの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。キューが溜まりすぎた場合はエクスポートされますが、定期的には行われません。代わりに、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用して手動でトレースをエクスポートしてください。 -たとえば Cloudflare Worker では、コードを `try/catch/finally` ブロックで包み、`waitUntil` と併用して強制フラッシュを使い、ワーカーが終了する前にトレースがエクスポートされるようにします。 +たとえば Cloudflare Worker では、コードを `try/catch/finally` ブロックでラップし、`waitUntil` と併用して強制フラッシュを実行し、ワーカー終了前にトレースがエクスポートされるようにします。 ` - - `group_id`: 任意のグループ ID。同じ会話からの複数トレースをリンクするために使用。例: チャットスレッド ID - - `disabled`: True の場合、このトレースは記録されない - - `metadata`: 任意のメタデータ -- **Spans** は開始と終了時間を持つ操作を表します。スパンには以下があります: + - `trace_id`: トレースの一意な ID。未指定の場合は自動生成。形式は `trace_<32_alphanumeric>` + - `group_id`: 任意のグループ ID。同じ会話の複数トレースを関連付けるために使用。例: チャットスレッド ID + - `disabled`: True の場合、トレースは記録されない + - `metadata`: トレースの任意のメタデータ +- **Spans** は開始時刻と終了時刻を持つ操作を表します。スパンには以下があります - `started_at` と `ended_at` のタイムスタンプ - 所属するトレースを表す `trace_id` - - 親スパンを指す `parent_id`（ある場合） - - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM の生成に関する情報など + - 親スパンを指す `parent_id`（存在する場合） + - スパンに関する情報である `span_data`。例えば `AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報など ## デフォルトのトレーシング -デフォルトでは、SDK は以下をトレースします: +デフォルトで SDK は次をトレースします: -- `run()` または `Runner.run()` 全体は `Trace` でラップされる -- エージェントが実行されるたびに `AgentSpan` でラップされる -- 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-agents-js/ja/guides/voice-agents) をご覧ください。 +詳しくは [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 -## 上位レベルのトレース +## 高レベルのトレース -複数回の `run()` 呼び出しを 1 つのトレースにまとめたいことがあります。その場合は、コード全体を `withTrace()` でラップしてください。 +`run()` への複数回の呼び出しを 1 つのトレースにまとめたい場合があります。その場合は、コード全体を `withTrace()` でラップします。 -1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 +1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります ## トレースの作成 -[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数でトレースを作成できます。あるいは、`getGlobalTraceProvider().createTrace()` を使って手動で新しいトレースを作成し、それを `withTrace()` に渡すこともできます。 +[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数でトレースを作成できます。あるいは、`getGlobalTraceProvider().createTrace()` で手動で新しいトレースを作成し、`withTrace()` に渡すこともできます。 -現在のトレースは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルによって追跡されます。これにより、並行処理でも自動的に機能します。 +現在のトレースは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルで追跡されます。これにより自動的に並行処理に対応します。 ## スパンの作成 -各種 `create*Span()`（例: `createGenerationSpan()`, `createFunctionSpan()` など）メソッドでスパンを作成できます。一般的には、手動でスパンを作成する必要はありません。カスタムのスパン情報を追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数も用意されています。 +各種 `create*Span()`（例: `createGenerationSpan()`, `createFunctionSpan()` など）メソッドでスパンを作成できます。一般的にはスパンを手動で作成する必要はありません。カスタムスパン情報を追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数も利用できます。 -スパンは自動的に現在のトレースに属し、[Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルで追跡される、直近の現在スパンの下にネストされます。 +スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの下にネストされます。これは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルで追跡されます。 ## 機微データ -一部のスパンは機微なデータを含む可能性があります。 +一部のスパンは機微なデータを取得する可能性があります。 -`createGenerationSpan()` は LLM 生成の入出力を保存し、`createFunctionSpan()` は関数呼び出しの入出力を保存します。これらには機微データが含まれる場合があるため、[`RunConfig.traceIncludeSensitiveData +`createGenerationSpan()` は LLM 生成の入出力を、`createFunctionSpan()` は関数呼び出しの入出力を保存します。これらには機微なデータが含まれる可能性があるため、[`RunConfig.traceIncludeSensitiveData `](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) でその取得を無効化できます。 ## カスタムトレーシングプロセッサー -トレーシングの上位アーキテクチャは次のとおりです: +トレーシングの高レベルなアーキテクチャは次のとおりです: -- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレースの作成を担い、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) でアクセスできます -- `TraceProvider` は [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) で構成され、これがトレース／スパンをバッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に送信し、OpenAI のバックエンドにバッチでエクスポートします +- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレースの作成を担当し、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) からアクセスできます +- `TraceProvider` を [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) で構成し、これはトレース/スパンをバッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に送信し、OpenAI のバックエンドへバッチエクスポートします -このデフォルト構成をカスタマイズし、別のバックエンドへの送信や追加のバックエンドへの送信、エクスポーターの挙動変更を行うには、次の 2 つの方法があります: +このデフォルト構成をカスタマイズして、別のバックエンドや追加のバックエンドに送信したり、エクスポーターの挙動を変更したりするには、次の 2 つの方法があります: -1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) は、トレースやスパンが準備でき次第受け取る、**追加の** トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を行えます -2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) は、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換え**られます。OpenAI のバックエンドにトレースを送信するには、そのための `TracingProcessor` を含める必要があります +1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) は、トレースやスパンの準備ができ次第受け取る **追加** のトレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を行えます +2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) は、デフォルトのプロセッサーを独自のトレースプロセッサーに **置き換え** られます。OpenAI のバックエンドに送信する `TracingProcessor` を含めない限り、トレースは OpenAI のバックエンドへ送信されません ## 外部トレーシングプロセッサー一覧 diff --git a/docs/src/content/docs/ja/guides/troubleshooting.mdx b/docs/src/content/docs/ja/guides/troubleshooting.mdx index 62f311d5..d355cf64 100644 --- a/docs/src/content/docs/ja/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ja/guides/troubleshooting.mdx @@ -5,36 +5,36 @@ description: Learn how to troubleshoot issues with the OpenAI Agents SDK. ## 対応環境 -OpenAI Agents SDK は次の サーバー 環境でサポートされています。 +OpenAI Agents SDK は次のサーバー環境でサポートされています。 - Node.js 22+ - Deno 2.35+ - Bun 1.2.5+ -### 制限付きサポート +### 限定的なサポート -- **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 でも利用できますが、いくつかの制限があります。 + - 現在は `nodejs_compat` の有効化が必要です + - リクエストの終わりにトレースを手動でフラッシュする必要があります。詳しくは [トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください + - Cloudflare Workers における `AsyncLocalStorage` のサポートが限定的なため、トレースが正確でない場合があります +- **Browsers**: - ブラウザでは現在トレーシングはサポートされていません - **v8 isolates**: - - 適切なブラウザ用ポリフィルを備えたバンドラを使用すれば v8 isolates 向けに SDK をバンドルできるはずですが、トレーシングは動作しません - - v8 isolates は広範なテストが行われていません + - 適切なブラウザ用ポリフィルを備えたバンドラを使えば v8 isolates 向けに SDK をバンドルできるはずですが、トレーシングは機能しません + - v8 isolates は広範にはテストされていません ## デバッグログ -SDK の利用中に問題が発生している場合は、デバッグログを有効にして詳細な情報を取得できます。 +SDK で問題が発生している場合、デバッグログを有効にすると詳細な情報を得られます。 -`DEBUG` 環境変数を `openai-agents:*` に設定すると、デバッグログが有効になります。 +`DEBUG` 環境変数を `openai-agents:*` に設定してデバッグログを有効化します。 ```bash DEBUG=openai-agents:* ``` -または、SDK の特定部分にスコープを絞ってデバッグすることもできます。 +また、SDK の特定の部分に限定してデバッグを有効化することもできます。 -- `openai-agents:core` — SDK の主要な実行ロジック -- `openai-agents:openai` — OpenAI API 呼び出し -- `openai-agents:realtime` — Realtime Agents コンポーネント +- `openai-agents:core` — SDK の主要な実行ロジック向け +- `openai-agents:openai` — OpenAI API 呼び出し向け +- `openai-agents:realtime` — リアルタイムエージェント コンポーネント向け diff --git a/docs/src/content/docs/ja/guides/voice-agents.mdx b/docs/src/content/docs/ja/guides/voice-agents.mdx index 9282ef93..6e1e091c 100644 --- a/docs/src/content/docs/ja/guides/voice-agents.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents.mdx @@ -23,29 +23,29 @@ import websocketSessionExample from '../../../../../../examples/docs/voice-agent import transportEventsExample from '../../../../../../examples/docs/voice-agents/transportEvents.ts?raw'; import thinClientExample from '../../../../../../examples/docs/voice-agents/thinClient.ts?raw'; -![Realtime Agents](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) +![リアルタイムエージェント](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) -Voice Agents は OpenAI の speech-to-speech モデルを使用して、リアルタイム音声チャットを提供します。これらのモデルは音声のストリーミング、テキスト、ツール呼び出しをサポートし、音声/電話カスタマーサポート、モバイル アプリでの体験、音声チャットなどの用途に最適です。 +Voice Agents は 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) 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 e50c8bb9..1c8a86ba 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/build.mdx @@ -28,111 +28,109 @@ 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) に一致する任意のパラメーターを渡せます。 -[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に存在しない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡した内容は `session` オブジェクトの一部としてそのまま渡されます。 +[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に対応するパラメーターがまだない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡したものは `session` オブジェクトの一部としてそのまま渡されます。 ## ハンドオフ -通常のエージェントと同様に、ハンドオフを使ってエージェントを複数のエージェントに分割し、間をオーケストレーションして、エージェントのパフォーマンス向上や問題のスコープを適切に絞り込めます。 +通常のエージェントと同様に、ハンドオフを使ってエージェントを複数に分割し、それらの間をオーケストレーションしてエージェントのパフォーマンスを向上させ、問題の範囲を適切に絞り込めます。 -通常のエージェントと異なり、Realtime Agents ではハンドオフの挙動が少し異なります。ハンドオフが実行されると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは進行中の会話履歴へ自動的にアクセスでき、入力フィルターは現在適用されません。 +通常のエージェントと異なり、ハンドオフは Realtime Agents では少し異なる挙動になります。ハンドオフが行われると、進行中のセッションが新しいエージェント設定で更新されます。これにより、エージェントは進行中の会話履歴に自動的にアクセスでき、現時点では入力フィルターは適用されません。 -また、このことはハンドオフの一部として `voice` や `model` を変更できないことも意味します。接続できるのは他の Realtime Agents のみです。別のモデル、たとえば `o4-mini` のような推論モデルが必要な場合は、[ツールによる委譲](#delegation-through-tools) を使用できます。 +さらに、ハンドオフの一部として `voice` や `model` を変更することはできません。また、接続できるのは他の Realtime Agents のみです。別のモデル、例えば `o4-mini` のような推論モデルを使う必要がある場合は、[ツールによる委譲](#delegation-through-tools) を利用できます。 ## ツール -通常のエージェントと同じように、Realtime Agents はツールを呼び出してアクションを実行できます。通常のエージェントで使用するのと同じ `tool()` 関数でツールを定義できます。 +通常のエージェントと同様に、Realtime Agents はツールを呼び出してアクションを実行できます。通常のエージェントで使うのと同じ `tool()` 関数を使ってツールを定義できます。 -Realtime Agents で使用できるのは 関数ツール のみで、これらのツールは Realtime Session と同じ場所で実行されます。つまり、ブラウザーで Realtime Session を実行している場合、ツールもブラウザーで実行されます。より機微な操作が必要な場合は、ツール内からバックエンド サーバー への HTTP リクエストを行ってください。 +Realtime Agents では使用できるのは 関数ツール のみで、これらのツールは Realtime Session と同じ場所で実行されます。つまり、Realtime Session をブラウザで実行している場合、ツールもブラウザで実行されます。より機微な処理が必要な場合は、ツール内からバックエンド サーバー への HTTP リクエストを発行してください。 -ツールの実行中、エージェントはユーザーからの新しいリクエストを処理できません。体験を改善する方法の一つは、ツールを実行しようとしていることをアナウンスする、またはツールの実行時間を稼ぐために特定のフレーズを言うようエージェントに指示することです。 +ツールの実行中は、エージェントはユーザーからの新しいリクエストを処理できません。体験を改善する 1 つの方法は、ツールを実行する直前にアナウンスする、あるいは特定のフレーズを話してツール実行のための時間を稼ぐようにエージェントへ指示することです。 ### 会話履歴へのアクセス -エージェントが特定のツールを呼び出した際の引数に加えて、Realtime Session が追跡している現在の会話履歴のスナップショットにもアクセスできます。現在の会話状態に基づいてより複雑なアクションを実行する必要がある場合や、[委譲のためのツール](#delegation-through-tools) を使う予定がある場合に有用です。 +エージェントが特定のツールを呼び出す際に渡される引数に加え、Realtime Session が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[委譲のためのツール](#delegation-through-tools) を使う予定がある場合に有用です。 ### ツール実行前の承認 `needsApproval: true` でツールを定義すると、エージェントはツールを実行する前に `tool_approval_requested` イベントを発行します。 -このイベントをリッスンして、ユーザーにツール呼び出しの承認・拒否を行う UI を表示できます。 +このイベントをリッスンして、ツール呼び出しを承認または拒否する UI をユーザーに表示できます。 ## ガードレール -ガードレールは、エージェントの発話が一連のルールに違反していないかを監視し、違反時に即座に応答を遮断する方法を提供します。これらのガードレールチェックはエージェントの応答の書き起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効）。 +ガードレールは、エージェントの発話が規則に違反していないかを監視し、即座に応答を遮断する手段を提供します。これらのガードレールチェックはエージェントの応答の書き起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（既定で有効）。 -提供したガードレールは、モデル応答の返却中に非同期で実行され、あらかじめ定義した分類トリガー（例：「特定の禁止ワードに言及」）に基づいて応答を遮断できます。 +提供したガードレールは、モデルの応答が返ってくるのと並行して非同期に実行され、例えば「特定の禁止ワードの言及」など、事前定義の分類トリガーに基づいて応答を遮断できます。 -ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。イベントには、ガードレールをトリガーした `itemId` を含む `details` オブジェクトが含まれます。 +ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。このイベントは、ガードレールをトリガーした `itemId` を含む `details` オブジェクトも提供します。 -デフォルトでは、ガードレールは 100 文字ごと、または応答テキストの生成が終了した時点で実行されます。テキストの読み上げは通常それより長くかかるため、多くの場合、ユーザーが聞く前にガードレールが違反を検出できるはずです。 +既定では、ガードレールは 100 文字ごと、または応答テキストの生成が終了した時点で実行されます。テキストを音声として読み上げる方が通常は時間がかかるため、多くの場合、ユーザーが聞く前にガードレールが違反を検知できます。 -この挙動を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡せます。 +この挙動を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡してください。 -## ターン検出 / 音声アクティビティ検出 +## ターン検出／音声活動検出 -Realtime Session は、ユーザーが話しているタイミングを自動検出し、内蔵の [Realtime API の音声アクティビティ検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使って新しいターンをトリガーします。 +Realtime Session は、ユーザーが話しているタイミングを自動的に検出し、内蔵の [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使って新しいターンをトリガーします。 -`turnDetection` オブジェクトをセッションに渡すことで、音声アクティビティ検出モードを変更できます。 +`turnDetection` オブジェクトをセッションに渡すことで、音声活動検出モードを変更できます。 -ターン検出設定を調整することで、不要な割り込みや無音への対処をキャリブレーションできます。各種設定の詳細は [Realtime API ドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください。 +ターン検出設定を調整すると、望ましくない割り込みや無音への対処をチューニングできます。異なる設定の詳細は [Realtime API のドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください ## 割り込み -内蔵の音声アクティビティ検出を使用している場合、エージェントの発話に被せて話すと、自動的にエージェントが発話内容に基づきコンテキストを更新し、`audio_interrupted` イベントを発行します。これはすべての音声再生を即座に停止するのに使用できます（WebSocket 接続にのみ適用）。 +内蔵の音声活動検出を使用している場合、エージェントの発話に被せて話すと、自動的にエージェントがそれを検知し、発話内容に基づいてコンテキストを更新します。また、`audio_interrupted` イベントが発行されます。これはすべての音声再生を即座に停止するために使えます（WebSocket 接続にのみ適用）。 -UI に「停止」ボタンを提供するなど、手動で割り込みを行いたい場合は、`interrupt()` を手動で呼び出せます。 +手動で割り込みを行いたい場合、例えば UI に「停止」ボタンを用意したいときは、`interrupt()` を手動で呼び出せます。 -いずれの場合も、Realtime Session はエージェントの生成を中断し、ユーザーに対して話した内容の認識を切り詰め、履歴を更新します。 +いずれの場合も、Realtime Session はエージェントの生成の割り込み、ユーザーに伝えた内容の切り詰め、履歴の更新を処理します。 -エージェントに WebRTC で接続している場合は、音声出力もクリアされます。WebSocket を使用している場合は、キューに入っている音声の再生停止を自分で処理する必要があります。 +エージェントへの接続に WebRTC を使用している場合は、音声出力もクリアされます。WebSocket を使用している場合は、キューに入っている音声の再生停止を自分で処理する必要があります。 ## テキスト入力 -エージェントにテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用します。 +エージェントへテキスト入力を送るには、`RealtimeSession` の `sendMessage` メソッドを使用します。 -これは、ユーザーがエージェントと複数のモダリティでやり取りできるようにしたい場合や、会話に追加のコンテキストを提供したい場合に有用です。 +ユーザーがエージェントと 2 つのモダリティでやり取りできるようにしたい場合や、会話に追加のコンテキストを提供したい場合に有用です。 @@ -140,26 +138,26 @@ UI に「停止」ボタンを提供するなど、手動で割り込みを行 `RealtimeSession` は `history` プロパティで会話履歴を自動管理します。 -これを使って、履歴をユーザーに表示したり、追加の処理を行ったりできます。会話の進行中は履歴が継続的に変化するため、`history_updated` イベントをリッスンできます。 +これを使って、履歴をカスタマーに表示したり、追加の処理を行ったりできます。会話中、この履歴は継続的に変化するため、`history_updated` イベントをリッスンできます。 -履歴を変更したい場合（メッセージを完全に削除する、書き起こしを更新するなど）は、`updateHistory` メソッドを使用します。 +履歴を変更したい場合（メッセージを完全に削除する、文字起こしを更新するなど）は、`updateHistory` メソッドを使用します。 -### 制限事項 +### 制限 -1. 現時点では、関数ツールの呼び出しを事後に更新・変更できません -2. 履歴でのテキスト出力には、書き起こしとテキストモダリティの有効化が必要です +1. 現時点では、関数ツールの呼び出しを後から更新・変更できません +2. 履歴でのテキスト出力には、書き起こしとテキストモダリティが有効である必要があります 3. 割り込みにより切り詰められた応答には書き起こしがありません ## ツールによる委譲 ![ツールによる委譲](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) -会話履歴とツール呼び出しを組み合わせることで、より複雑な処理を別のバックエンド エージェントに委譲し、その結果をユーザーに返せます。 +会話履歴とツール呼び出しを組み合わせることで、会話を別のバックエンド エージェントに委譲して、より複雑なアクションを実行し、その結果をユーザーに返すことができます。 -以下のコードは サーバー 上で実行されます。この例では Next.js の server actions を使用しています。 +以下のコードは サーバー 上で実行されます。この例では Next.js の Server Actions を通じて実行します。 diff --git a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx index 155783d1..26bb2afd 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx @@ -28,7 +28,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 0. **プロジェクトの作成** - このクイックスタートでは、ブラウザで使える音声エージェントを作成します。新しいプロジェクトを試したい場合は、[`Next.js`](https://nextjs.org/docs/getting-started/installation) や [`Vite`](https://vite.dev/guide/installation.html) をお試しください。 + この クイックスタート では、ブラウザで使える音声エージェントを作成します。新規プロジェクトを試したい場合は、[`Next.js`](https://nextjs.org/docs/getting-started/installation) や [`Vite`](https://vite.dev/guide/installation.html) を試すことができます。 ```bash npm create vite@latest my-project --template vanilla-ts @@ -42,9 +42,9 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 代わりに、スタンドアロンのブラウザ向けパッケージである `@openai/agents-realtime` をインストールすることもできます。 -2. **クライアント向けエフェメラルトークンの生成** +2. **クライアント用エフェメラルトークンの生成** - このアプリケーションは ユーザー のブラウザで実行されるため、Realtime API を通じてモデルに安全に接続する方法が必要です。そのために、バックエンド サーバー で生成すべき [ephemeral client key](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) を使用できます。テスト目的であれば、`curl` と通常の OpenAI API キーを使ってキーを生成しても構いません。 + このアプリケーションは ユーザー のブラウザ内で実行されるため、Realtime API を通してモデルに安全に接続する必要があります。そのために、バックエンド サーバー 上で生成される [ephemeral client key](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) を使用します。テスト用途では、`curl` と通常の OpenAI API キーを使ってキーを生成することもできます。 ```bash curl -X POST https://api.openai.com/v1/realtime/client_secrets \ @@ -58,11 +58,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - レスポンスには、後で接続に使用できる `client_secret.value` が含まれます。このキーは短時間のみ有効で、再生成が必要になる点に注意してください。 + レスポンスには、後で接続に使用できる `client_secret.value` の値が含まれます。このキーは短時間のみ有効で、再生成が必要になる点に注意してください。 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'; @@ -75,7 +75,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 4. **セッションの作成** - 通常のエージェントと異なり、音声エージェントは `RealtimeSession` 内で継続的に稼働し、会話とモデルへの接続を継続的に処理します。このセッションは、音声の処理、割り込み、その他多くのライフサイクル機能も扱います。これらは後ほど説明します。 + 通常のエージェントと異なり、Voice Agent は会話とモデルへの接続を継続的に扱う `RealtimeSession` 内で常時実行・待機します。このセッションは、音声処理、割り込み、その他多くのライフサイクル機能も処理します。これらは後で詳しく説明します。 ```typescript import { RealtimeSession } from '@openai/agents-realtime'; @@ -85,25 +85,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` コンストラクターは、最初の引数として `agent` を受け取ります。このエージェントが、 ユーザー が最初に対話できるエージェントになります。 + `RealtimeSession` のコンストラクターは、最初の引数として `agent` を受け取ります。このエージェントが ユーザー が最初に対話できるエージェントになります。 5. **セッションへの接続** - セッションに接続するには、先ほど生成したクライアント向けエフェメラルトークンを渡します。 + セッションに接続するには、先ほど生成したクライアント用エフェメラルトークンを渡します。 ```typescript await session.connect({ apiKey: '' }); ``` - これにより、ブラウザで WebRTC を使って Realtime API に接続し、音声の入出力のためにマイクとスピーカーを自動的に設定します。`RealtimeSession` をバックエンド サーバー（例えば Node.js）で実行している場合、SDK は接続として自動的に WebSocket を使用します。さまざまなトランスポート層の詳細は、[リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドをご覧ください。 + これにより、ブラウザでは WebRTC を用いて Realtime API に接続し、マイクとスピーカーが自動的に音声入出力に設定されます。`RealtimeSession` をバックエンド サーバー（たとえば Node.js）で実行している場合、SDK は自動的に WebSocket を接続に使用します。異なるトランスポート層の詳細は、[リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドをご覧ください。 -6. **全体の組み立て** +6. **まとめ** -7. **起動して会話を開始** +7. **起動して話しかける** - Web サーバー を起動し、新しい Realtime Agent のコードを含むページにアクセスします。マイクへのアクセス許可を求めるリクエストが表示されるはずです。許可すると、エージェントと話し始めることができます。 + Web サーバー を起動し、新しい Realtime Agent のコードを含むページに移動します。マイクへのアクセス許可を求めるリクエストが表示されるはずです。許可すると、エージェントに話しかけられるようになります。 ```bash npm run dev @@ -113,16 +113,16 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t ## 次のステップ -ここからは、独自の音声エージェントの設計と構築を始められます。音声エージェントは通常のエージェントと多くの機能を共有しますが、固有の機能もいくつかあります。 +ここからは、独自の音声エージェントの設計と構築を始められます。音声エージェントは通常のエージェントと多くの機能を共有しますが、独自の機能もいくつか備えています。 -- 音声エージェントに次の機能を追加する方法を学ぶ +- 音声エージェントに以下を追加する方法を学ぶ - [ツール](/openai-agents-js/ja/guides/voice-agents/build#tools) - [ハンドオフ](/openai-agents-js/ja/guides/voice-agents/build#handoffs) - [ガードレール](/openai-agents-js/ja/guides/voice-agents/build#guardrails) - - [音声の割り込み処理](/openai-agents-js/ja/guides/voice-agents/build#audio-interruptions) + - [音声の割り込みへの対応](/openai-agents-js/ja/guides/voice-agents/build#audio-interruptions) - [セッション履歴の管理](/openai-agents-js/ja/guides/voice-agents/build#session-history) - さまざまなトランスポート層についてさらに学ぶ - [WebRTC](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-webrtc) - [WebSocket](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-websocket) - - [独自のトランスポートメカニズムの構築](/openai-agents-js/ja/guides/voice-agents/transport#building-your-own-transport-mechanism) + - [独自のトランスポート機構の構築](/openai-agents-js/ja/guides/voice-agents/transport#building-your-own-transport-mechanism) diff --git a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx index 7a4be057..039948f1 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 - トランスポート層へのアクセス -`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 a7beaab4..deeb1a81 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -19,30 +19,30 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概要 -[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型 AI アプリを構築できるようにします。これは、以前のエージェントに関する実験である [Swarm](https://github.com/openai/swarm/tree/main) をプロダクション向けにアップグレードしたもので、[Python でも利用可能](https://github.com/openai/openai-agents-python) です。Agents SDK には非常に少数の基本コンポーネントがあります: +[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 はごく少数の基本コンポーネントを提供します: -- **Agents**: instructions と tools を備えた LLM -- **Handoffs**: あるエージェントが特定のタスクを他のエージェントに委譲できる機能 -- **Guardrails**: エージェントへの入力を検証できる機能 +- **エージェント**: instructions と tools を備えた LLM +- **ハンドオフ**: 特定のタスクを他のエージェントに委譲する仕組み +- **ガードレール**: エージェントへの入力を検証する仕組み -TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習曲線なしに実運用アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化してデバッグし、評価したり、アプリケーション向けにモデルをファインチューニングすることもできます。 +TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実運用レベルのアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が付属しており、エージェントフローの可視化とデバッグ、評価、さらにはアプリケーション向けのモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 -SDK には 2 つの設計原則があります: +この SDK は 2 つの設計原則に基づいています: -1. 使う価値があるだけの十分な機能を備えつつ、学習を素早くするために基本コンポーネントは少数に保つ -2. そのままでも優れた動作をするが、何が起きるかを正確にカスタマイズできる +1. 使う価値があるだけの機能を備えつつ、学習が速いよう基本コンポーネントは少数にとどめる +2. すぐに使えて優れた体験を提供しつつ、挙動を細部までカスタマイズ可能にする -SDK の主な機能は次のとおりです: +主な機能は次のとおりです: -- **Agent loop**: ツールの呼び出し、結果の LLM への送信、LLM の完了までのループを処理する組み込みのエージェントループ -- **TypeScript ファースト**: 新しい抽象化を学ぶのではなく、言語の組み込み機能でエージェントをオーケストレーションして連携 -- **Handoffs**: 複数のエージェント間で調整・委譲する強力な機能 -- **Guardrails**: エージェントと並行して入力の検証とチェックを実行し、チェックに失敗した場合は早期に中断 -- **Function tools**: 任意の TypeScript 関数をツールに変換し、自動スキーマ生成と Zod ベースの検証を提供 -- **Tracing**: OpenAI の評価、ファインチューニング、蒸留ツールを利用できるほか、ワークフローの可視化・デバッグ・監視が可能な組み込みトレーシング -- **Realtime Agents**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 +- **エージェントループ**: ツールの呼び出し、結果の LLM への送信、LLM の完了までのループを内蔵 +- **TypeScript ファースト**: 新しい抽象化を学ぶ必要なく、言語の機能でエージェントのオーケストレーションと連携を実現 +- **ハンドオフ**: 複数エージェント間の調整と委譲を可能にする強力な機能 +- **ガードレール**: エージェントと並行して入力の検証やチェックを実行し、失敗時は早期に中断 +- **関数ツール**: 任意の TypeScript 関数をツール化し、自動スキーマ生成と Zod による検証を提供 +- **トレーシング**: ワークフローの可視化・デバッグ・監視に加え、OpenAI の評価、ファインチューニング、蒸留ツールを活用可能 +- **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた高機能な音声エージェントを構築可能 ## インストール @@ -50,7 +50,7 @@ SDK の主な機能は次のとおりです: npm install @openai/agents zod@3 ``` -## Hello World のコード例 +## Hello World の例