diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index c4530804..6a8d95b5 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -7,12 +7,12 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -Agents SDK は標準で OpenAI モデルに対して Responses API または Chat Completions API を通じて動作します。別のモデルを使用したい場合は、[Vercel's 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 に組み込めます。 ## セットアップ @@ -24,23 +24,23 @@ Agents SDK は標準で OpenAI モデルに対して Responses API または Cha npm install @openai/agents-extensions ``` -2. [Vercel's 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')); + const model = aisdk(openai('gpt-5-mini')); ``` @@ -48,22 +48,17 @@ Agents SDK は標準で OpenAI モデルに対して Responses API または Cha ## 例 - + -## プロバイダーのメタデータの受け渡し +## プロバイダー メタデータの受け渡し -メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` を通して渡します。値は基盤となる AI SDK モデルへそのまま転送されます。例えば、Agents SDK で次の `providerData` +メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` に渡します。値は基盤となる AI SDK モデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` ```ts providerData: { @@ -86,3 +81,5 @@ providerMetadata: { } } ``` + +となります。 diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index 0d4d4ebc..a4237ba4 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,37 +7,37 @@ 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 transport が使えます。ただし、その場合は適切なオーディオ形式の設定や、Web ベースの会話よりも通話のほうが自然にレイテンシが大きくなるため、割り込みタイミングを自分で調整する必要があります。 +Twilio は、電話の **raw** オーディオを 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 への接続、中断処理、オーディオ転送を代行する専用のトランスポートレイヤーを用意しました。 ## セットアップ -1. **Twilio アカウントと Twilio の電話番号を用意すること** +1. **Twilio アカウントと Twilio の電話番号を用意します。** -2. **Twilio からのイベントを受け取れる WebSocket サーバーをセットアップすること** +2. **Twilio からのイベントを受け取れる WebSocket サーバーを用意します。** - ローカル開発の場合、[`ngrok`](https://ngrok.io/) や + ローカル開発の場合は、[`ngrok`](https://ngrok.io/) や [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - のようなローカルトンネルの設定が必要になり、ローカルサーバーを Twilio からアクセス可能にする必要があります。`TwilioRealtimeTransportLayer` + などでローカルトンネルを設定し、ローカルサーバーを Twilio からアクセス可能にする必要があります。`TwilioRealtimeTransportLayer` を使って Twilio に接続できます。 -3. **エクステンションパッケージをインストールして Twilio アダプターを導入すること:** +3. **extensions パッケージをインストールして Twilio アダプターを導入します:** ```bash npm install @openai/agents-extensions ``` -4. **アダプターとモデルをインポートして、`RealtimeSession` に接続すること:** +4. **アダプターとモデルをインポートして `RealtimeSession` に接続します:** -5. **`RealtimeSession` を Twilio に接続すること:** +5. **`RealtimeSession` を Twilio に接続します:** ```typescript session.connect({ apiKey: 'your-openai-api-key' }); @@ -55,31 +55,32 @@ Twilio は、電話の通話音声の元オーディオを WebSocket サーバ -`RealtimeSession` で期待されるあらゆるイベントや挙動は、ツール呼び出しやガードレールなども含めて期待どおりに動作します。`RealtimeSession` を音声エージェントと使う方法については、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 +`RealtimeSession` に期待されるイベントや動作は、ツール呼び出しやガードレールなどを含めて、そのまま機能します。`RealtimeSession` を音声エージェントで使う方法の詳細は、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 ## ヒントと考慮事項 -1. **スピードがすべてです** +1. **スピードが最重要です。** - Twilio から必要なイベントと音声をすべて受け取るには、WebSocket 接続の参照を取得したらすぐに - `TwilioRealtimeTransportLayer` インスタンスを作成し、その直後に `session.connect()` を呼び出すべきです。 + Twilio から必要なイベントとオーディオを受け取るには、WebSocket 接続の参照を取得したらすぐに + `TwilioRealtimeTransportLayer` インスタンスを作成し、直ちに `session.connect()` を呼び出してください。 -2. **Twilio の生イベントにアクセスする** +2. **Twilio の raw イベントにアクセスします。** - Twilio から送られてくる元のイベントにアクセスしたい場合は、`RealtimeSession` インスタンスの - `transport_event` をリッスンします。Twilio からのすべてのイベントは `twilio_message` という type を持ち、元のイベントデータを含む `message` プロパティがあります。 + Twilio が送信する **raw** イベントにアクセスしたい場合は、`RealtimeSession` インスタンスの + `transport_event` をリッスンします。Twilio からのすべてのイベントは `twilio_message` という type を持ち、 + **raw** イベントデータを含む `message` プロパティを持ちます。 -3. **デバッグログを確認する** +3. **デバッグログを確認します。** - 何が起きているかについて、より多くの情報が必要になることがあります。環境変数 `DEBUG=openai-agents*` を使うと、Agents SDK のすべてのデバッグログが表示されます。あるいは、Twilio アダプターのデバッグログだけを有効にするには - `DEBUG=openai-agents:extensions:twilio*` を使います。 + 状況を詳しく把握したい場合は、環境変数 `DEBUG=openai-agents*` を使うと Agents SDK のすべてのデバッグログが表示されます。 + もしくは、`DEBUG=openai-agents:extensions:twilio*` で Twilio アダプターのデバッグログだけを有効にできます。 ## 完全なサーバー例 -以下は、Twilio からのリクエストを受け取り、`RealtimeSession` に転送するエンドツーエンドの WebSocket サーバーの例です。 +以下は、Twilio からのリクエストを受け取り、`RealtimeSession` に転送する WebSocket サーバーのエンドツーエンドのサンプルです。 diff --git a/docs/src/content/docs/ja/guides/agents.mdx b/docs/src/content/docs/ja/guides/agents.mdx index a4f545c3..e81f9a3b 100644 --- a/docs/src/content/docs/ja/guides/agents.mdx +++ b/docs/src/content/docs/ja/guides/agents.mdx @@ -15,76 +15,80 @@ import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agen import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw'; import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw'; -エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** は、以下で構成された Large Language Model (LLM) です。 +エージェントは OpenAI Agents SDK の主要な構成要素です。**エージェント**は、以下の設定を持つ Large Language Model (LLM) です。 -- **Instructions** – モデルに「自分は誰か」「どのように応答すべきか」を指示する system prompt +- **Instructions** – モデルに対して「自分は何者か」「どのように応答すべきか」を伝えるシステムプロンプト - **Model** – 呼び出す OpenAI モデルと、任意のモデル調整パラメーター - **Tools** – LLM がタスク達成のために呼び出せる関数や API の一覧 - + -このページでは、Agent の各機能を詳しく説明します。 +このページでは、エージェントのすべての機能を詳しく説明します。 --- ## 基本設定 -`Agent` コンストラクターは単一の設定オブジェクトを受け取ります。よく使うプロパティは次のとおりです。 +`Agent` コンストラクターは単一の設定オブジェクトを受け取ります。よく使われるプロパティは以下のとおりです。 -| Property | Required | Description | -| --------------- | -------- | -------------------------------------------------------------------------------------------------- | -| `name` | はい | 短い人間可読の識別子 | -| `instructions` | はい | System prompt（文字列 **または** 関数 – [Dynamic instructions](#dynamic-instructions) を参照） | -| `model` | いいえ | モデル名 **または** カスタム [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | -| `modelSettings` | いいえ | 調整パラメーター（temperature、top_p など） | -| `tools` | いいえ | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | +| Property | Required | Description | +| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | +| `name` | yes | 短い人間向け識別子 | +| `instructions` | yes | システムプロンプト（文字列 **または** 関数 – [Dynamic instructions](#dynamic-instructions) を参照） | +| `model` | no | モデル名 **または** カスタム [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | +| `modelSettings` | no | 調整用パラメーター（temperature、top_p など）。トップレベルにないプロパティは `providerData` の下に含めることができます | +| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | - + --- ## コンテキスト -エージェントはそのコンテキスト型に対して汎用的です（例: `Agent`）。コンテキストは、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザー メタデータ、フィーチャーフラグなど）を提供するのに便利です。 +エージェントはそのコンテキスト型に対して**ジェネリック**です（例: `Agent`）。コンテキストは、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保持や共有サービス（データベース接続、ユーザーのメタデータ、フィーチャーフラグなど）の提供に役立ちます。 --- ## 出力タイプ -デフォルトでは、Agent は**プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は以下を受け付けます。 +デフォルトではエージェントは**プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は `outputType` プロパティを指定します。SDK は以下を受け付けます。 1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`） -2. 任意の JSON‑schema 互換オブジェクト +2. 任意の JSON スキーマ互換オブジェクト -`outputType` が指定されると、SDK はプレーンテキストの代わりに自動的に +`outputType` が指定されると、SDK はプレーンテキストではなく自動的に [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。 --- ## マルチエージェントのシステム設計パターン -エージェント同士を構成する方法は多くあります。本番アプリでよく見られるパターンは次の 2 つです。 +エージェントを組み合わせる方法は多数あります。プロダクションアプリでよく見られるパターンは次の 2 つです。 1. **マネージャー（エージェントをツールとして）** – 中央のエージェントが会話を所有し、ツールとして公開された専門エージェントを呼び出す -2. **ハンドオフ** – 初期エージェントが、ユーザーのリクエストを特定したら会話全体を専門家に委譲する +2. **ハンドオフ** – 最初のエージェントがユーザーのリクエストを特定したら、以降の会話全体を専門エージェントに委譲する -これらのアプローチは補完的です。マネージャーはガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を保持せず単一タスクに集中できるようにします。 +これらの手法は補完的です。マネージャーはガードレールやレート制限を 1 か所で適用でき、ハンドオフは各エージェントが会話の制御を保持せずに単一のタスクに集中できるようにします。 ### マネージャー（エージェントをツールとして） -このパターンでは、マネージャーは制御を手放しません。LLM がツールを使用し、マネージャーが最終回答を要約します。詳しくは [ツール](/openai-agents-js/ja/guides/tools#agents-as-tools) を参照してください。 +このパターンではマネージャーが制御を手放しません。LLM はツールを使い、マネージャーが最終回答を要約します。詳しくは[ツール ガイド](/openai-agents-js/ja/guides/tools#agents-as-tools)をご覧ください。 + --- ## 動的 instructions -`instructions` は文字列の代わりに**関数**にできます。この関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返せます。 +`instructions` は文字列ではなく**関数**にすることもできます。この関数は現在の +`RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返せます。 -同期関数と `async` 関数の両方をサポートします。 +同期関数と `async` 関数のどちらもサポートされています。 --- ## ライフサイクルフック -高度なユースケースでは、イベントをリッスンして Agent のライフサイクルを監視できます +高度なユースケースでは、イベントをリッスンしてエージェントのライフサイクルを監視できます。利用可能な内容は、[こちら](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts) に記載のエージェントフックのイベント名を参照してください。 --- ## ガードレール -ガードレールにより、ユーザー入力やエージェント出力の検証や変換ができます。`inputGuardrails` と `outputGuardrails` 配列で設定します。詳細は -[ガードレール](/openai-agents-js/ja/guides/guardrails) を参照してください。 +ガードレールは、ユーザー入力やエージェント出力を検証・変換できる仕組みです。`inputGuardrails` と `outputGuardrails` 配列で設定します。詳細は[ガードレール ガイド](/openai-agents-js/ja/guides/guardrails)を参照してください。 --- ## エージェントのクローン／コピー -既存のエージェントを少しだけ変更したバージョンが必要ですか？`clone()` メソッドを使用すると、まったく新しい `Agent` インスタンスが返されます。 +既存エージェントの少しだけ変更したバージョンが必要ですか？`clone()` メソッドを使うと、まったく新しい `Agent` インスタンスが返ってきます。 - + --- @@ -145,21 +153,21 @@ 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'`）– LLM はその特定のツールを呼び出す必要がある ### 無限ループの防止 -ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループへ入るのを防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 +ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループに入るのを防ぎます。この挙動は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 -- `'run_llm_again'`（デフォルト）– ツールの結果を用いて LLM を再実行 +- `'run_llm_again'`（デフォルト）– ツール結果を使って LLM を再度実行 - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う -- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼び出されたら停止 -- `(context, toolResults) => ...` – 実行終了可否を返すカスタム関数 +- `{ stopAtToolNames: ['my_tool'] }` – 記載のいずれかのツールが呼ばれたら停止 +- `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数 ```typescript const agent = new Agent({ @@ -172,6 +180,6 @@ const agent = new Agent({ ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を学ぶ -- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) を詳しく見る -- サイドバーの **@openai/agents** から TypeDoc 全リファレンスを参照する +- [エージェントの実行](/openai-agents-js/ja/guides/running-agents)の方法を学ぶ +- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models)をさらに深掘りする +- サイドバーの **@openai/agents** にある TypeDoc リファレンス全体を参照する diff --git a/docs/src/content/docs/ja/guides/config.mdx b/docs/src/content/docs/ja/guides/config.mdx index d1e809a4..e5306b87 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,34 +13,36 @@ 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 を切り替えられます。 - + ## トレーシング -トレーシングはデフォルトで有効で、上記の OpenAI キーを使用します。別のキーは `setTracingExportApiKey()` で設定できます。 +トレーシングは既定で有効で、上記の OpenAI キーを使用します。 + +別のキーは `setTracingExportApiKey()` で設定できます。 トレーシングは完全に無効化することもできます。 @@ -48,32 +50,34 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t +トレーシング機能の詳細は [トレーシング](/openai-agents-js/ja/guides/tracing) をご覧ください。 + ## デバッグログ -SDK はデバッグログ記録に [`debug`](https://www.npmjs.com/package/debug) パッケージを使用します。詳細ログを表示するには、環境変数 `DEBUG` を `openai-agents*` に設定します。 +SDK はデバッグログに [`debug`](https://www.npmjs.com/package/debug) パッケージを使用します。詳細ログを表示するには、環境変数 `DEBUG` を `openai-agents*` に設定します。 ```bash export DEBUG=openai-agents* ``` -`@openai/agents` の `getLogger(namespace)` を使って自分のモジュール用に名前空間付きロガーを取得できます。 +`@openai/agents` の `getLogger(namespace)` を使って、独自モジュール用の名前空間付きロガーを取得できます。 - + -### ログ内の機微情報 +### ログ内の機微データ -一部のログには ユーザー データが含まれる場合があります。次の環境変数を設定して無効化できます。 +一部のログにはユーザー データが含まれる場合があります。以下の環境変数を設定して無効化します。 -LLM の入力と出力のログ記録を無効化するには: +LLM の入力と出力のログを無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力と出力のログ記録を無効化するには: +ツールの入力と出力のログを無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/src/content/docs/ja/guides/context.mdx b/docs/src/content/docs/ja/guides/context.mdx index 12d0e552..55310cf0 100644 --- a/docs/src/content/docs/ja/guides/context.mdx +++ b/docs/src/content/docs/ja/guides/context.mdx @@ -6,14 +6,14 @@ description: Learn how to provide local data via RunContext and expose context t import { Aside, Code } from '@astrojs/starlight/components'; import localContextExample from '../../../../../../examples/docs/context/localContext.ts?raw'; -コンテキストという語は多義的です。ここで重要になるコンテキストは主に 2 つのクラスに分かれます: +コンテキストは多義的な用語です。考慮すべきコンテキストには主に 2 つのクラスがあります。 -1. **ローカルコンテキスト** 実行中にコードからアクセスできるもの: ツールが必要とする依存関係やデータ、`onHandoff` のようなコールバック、ライフサイクルフック -2. **エージェント/LLM コンテキスト** 応答生成時に言語モデルが参照できるもの +1. 実行中にコードからアクセスできる **ローカルコンテキスト**：ツールに必要な依存関係やデータ、`onHandoff` のようなコールバック、ライフサイクルフック +2. 応答生成時に言語モデルが参照できる **エージェント／LLM コンテキスト** ## ローカルコンテキスト -ローカルコンテキストは `RunContext` 型で表されます。状態や依存関係を保持する任意のオブジェクトを作成し、それを `Runner.run()` に渡します。すべてのツール呼び出しとフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み書きできます。 +ローカルコンテキストは `RunContext` 型で表されます。状態や依存関係を保持する任意のオブジェクトを作成して `Runner.run()` に渡します。すべてのツール呼び出しとフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み書きできます。 -単一の実行に参加するすべてのエージェント、ツール、フックは同じ**型**のコンテキストを使用する必要があります。 +単一の実行に参加するすべてのエージェント、ツール、フックは同じコンテキストの**型**を使用する必要があります。 -ローカルコンテキストの用途: +ローカルコンテキストの主な用途: - 実行に関するデータ（ユーザー名、ID など） - ロガーやデータフェッチャーなどの依存関係 @@ -34,11 +34,11 @@ import localContextExample from '../../../../../../examples/docs/context/localCo に送信されません。純粋にローカルであり、自由に読み書きできます。 -## エージェント/LLM コンテキスト +## エージェント／LLM コンテキスト -LLM が呼び出されるとき、参照できるデータは会話履歴のみです。追加情報を利用可能にするには、次の方法があります: +LLM が呼び出されると、参照できるデータは会話履歴のみです。追加情報を利用可能にするには、次の選択肢があります。 -1. エージェントの `instructions` に追加する（system または developer メッセージとも呼ばれます）。これは静的な文字列でも、コンテキストを受け取って文字列を返す関数でも構いません -2. `Runner.run()` 呼び出し時の `input` に含める。instructions と同様の手法ですが、メッセージを [chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます -3. 関数ツールを通じて公開し、LLM がオンデマンドでデータ取得できるようにする -4. リトリーバルや Web 検索ツールを使い、ファイル、データベース、またはウェブの関連データに基づいて応答をグラウンディングする +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 f2536e60..2615d40c 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'; -ガードレールはエージェントと _並行して_ 実行され、ユーザー入力やエージェント出力に対するチェックや検証を行います。たとえば、高価なモデルを呼び出す前に軽量モデルをガードレールとして走らせることができます。ガードレールが悪意ある利用を検知した場合、エラーを発生させて高コストなモデルの実行を停止できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力やエージェント出力に対するチェックや検証を行えます。たとえば、高コストなモデルを呼び出す前にガードレールとして軽量なモデルを走らせることができます。もしガードレールが悪意のある利用を検知した場合、エラーを発生させて高コストなモデルの実行を止められます。 -ガードレールには 2 種類あります。 +ガードレールには 2 種類あります: -1. **入力ガードレール** は最初のユーザー入力に対して実行されます -2. **出力ガードレール** は最終的なエージェント出力に対して実行されます +1. **Input guardrails** は初回のユーザー入力に対して実行されます +2. **Output guardrails** は最終的なエージェント出力に対して実行されます -## 入力ガードレール +## Input guardrails -入力ガードレールは 3 段階で実行されます。 +Input guardrails は次の 3 ステップで動作します: 1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返し、それが [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップされます +2. ガードレール関数が実行され、[`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します 3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます -> **Note** -> 入力ガードレールはユーザー入力向けであり、ワークフロー内でエージェントが _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに構成します。なぜなら、エージェントごとに必要なガードレールが異なることが多いためです。 +> **注意** +> Input guardrails はユーザー入力を対象としているため、ワークフローでエージェントが _最初の_ エージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。異なるエージェントでは必要なガードレールが異なることが多いためです。 -## 出力ガードレール +## Output guardrails -出力ガードレールも同じパターンに従います。 +Output guardrails も同様のパターンに従います: 1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返し、それが [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップされます +2. ガードレール関数が実行され、[`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します 3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます -> **Note** -> 出力ガードレールは、ワークフロー内でエージェントが _最後_ のエージェントである場合にのみ実行されます。リアルタイムの音声対話については[音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails)を参照してください。 +> **注意** +> Output guardrails は、ワークフローでエージェントが _最後の_ エージェントである場合にのみ実行されます。リアルタイムの音声インタラクションについては[音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails)をご覧ください。 ## トリップワイヤー -ガードレールが失敗すると、トリップワイヤーを介してそれを通知します。トリップワイヤーがトリガーされるとすぐに、ランナー (runner) は対応するエラーをスローして実行を停止します。 +ガードレールが失敗すると、トリップワイヤーによってそれを知らせます。トリップワイヤーが作動するとすぐに、ランナーは対応するエラーをスローして実行を停止します。 ## ガードレールの実装 -ガードレールは、`GuardrailFunctionOutput` を返す単純な関数です。以下は、内部で別のエージェントを実行して、ユーザーが数学の宿題の助けを求めているかどうかを確認する最小の例です。 +ガードレールは、`GuardrailFunctionOutput` を返す単なる関数です。以下は、別のエージェントを内部で実行して、ユーザーが数学の宿題の手伝いを求めているかをチェックする最小の例です。 -出力ガードレールも同様に動作します。 +Output guardrails も同じ方法で機能します。 1. `guardrailAgent` はガードレール関数内で使用されます -2. ガードレール関数はエージェントの入力または出力を受け取り、その結果を返します +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 d07258f9..adfa4bd7 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` オブジェクトを含められます。 ### 基本的な使い方 @@ -24,12 +24,12 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r ### `handoff()` によるハンドオフのカスタマイズ -`handoff()` 関数で生成されるツールを調整できます。 +`handoff()` 関数を使うと、生成されるツールを調整できます。 -- `agent` – 引き継ぎ先のエージェント +- `agent` – ハンドオフ先のエージェント - `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き - `toolDescriptionOverride` – 既定のツール説明を上書き -- `onHandoff` – ハンドオフ発生時のコールバック。`RunContext` と、必要に応じてパース済み入力を受け取る +- `onHandoff` – ハンドオフが発生したときのコールバック。`RunContext` と、必要に応じてパース済み入力を受け取ります - `inputType` – ハンドオフに期待する入力スキーマ - `inputFilter` – 次のエージェントに渡す履歴のフィルター @@ -41,20 +41,20 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r ## ハンドオフの入力 -ハンドオフ呼び出し時に LLM にデータを提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 +ハンドオフを呼び出す際に、LLM にデータを提供させたい場合があります。入力スキーマを定義して `handoff()` で使用します。 ## 入力フィルター -既定では、ハンドオフは会話履歴全体を受け取ります。次のエージェントへ渡す内容を変更するには、`inputFilter` を指定します。 +既定では、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。 一般的なヘルパーは `@openai/agents-core/extensions` にあります。 ## 推奨プロンプト -プロンプトにハンドオフを明記すると、LLM の応答はより安定します。SDK は `RECOMMENDED_PROMPT_PREFIX` 経由で推奨のプレフィックスを提供します。 +プロンプトでハンドオフに言及すると、LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` として推奨のプレフィックスを提供しています。 ### フロー -1. エージェントがツール呼び出し（複数可）を決定した場合、`needsApproval` を評価してそのツールに承認が必要か確認します -2. 承認が必要な場合、すでに承認済みか却下済みかを確認します - - 承認または却下がまだ行われていない場合、ツールは「ツール呼び出しを実行できない」という固定メッセージをエージェントに返します - - 承認 / 却下が未処理の場合、ツール承認リクエストがトリガーされます -3. エージェントはすべてのツール承認リクエストを収集し、実行を中断します -4. 中断がある場合、[エージェントの実行結果](/openai-agents-js/ja/guides/results) に保留中のステップを示す `interruptions` 配列が含まれます。ツール呼び出しに確認が必要なときは、`type: "tool_approval_item"` を持つ `ToolApprovalItem` が現れます -5. ツール呼び出しを承認または却下するには、`result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出します -6. すべての中断を処理したら、`result.state` を `runner.run(agent, state)` に渡して実行を再開します。ここで `agent` は全体の実行をトリガーした元のエージェントです -7. フローは手順 1 から再開します +1. エージェントがツール（複数可）を呼び出すと判断した場合、`needsApproval` を評価してそのツールが承認を必要とするか確認します。 +2. 承認が必要な場合、すでに承認または却下されているかを確認します。 + - 承認または却下がまだ行われていない場合、ツールは「このツール呼び出しは実行できない」という固定メッセージをエージェントに返します。 + - 承認 / 却下が欠けている場合、ツール承認リクエストがトリガーされます。 +3. エージェントはすべてのツール承認リクエストを収集し、実行を中断します。 +4. 中断がある場合、[エージェントの実行結果](/openai-agents-js/ja/guides/results) には保留中のステップを表す `interruptions` 配列が含まれます。ツール呼び出しに確認が必要なときは、`type: "tool_approval_item"` を持つ `ToolApprovalItem` が現れます。 +5. ツール呼び出しを承認または却下するには、`result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出します。 +6. すべての中断を処理したら、`result.state` を元の全体実行を開始したエージェント `agent` とともに `runner.run(agent, state)` に渡して実行を再開できます。 +7. フローは手順 1 から再開されます。 ## 例 @@ -44,22 +44,22 @@ import toolApprovalDefinition from '../../../../../../examples/docs/human-in-the title="Human in the loop" /> -エンドツーエンドで動作する版は、[完全なサンプルスクリプト](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 のバージョンを上げる予定がある場合は、パッケージの別名を使って 2 つの Agents SDK バージョンを並行インストールし、独自のブランチロジックを実装することを現在は推奨します。 -実務的には、自分のコードにバージョン番号を割り当て、それをシリアライズ済み状態と一緒に保存し、復元時に正しいコードバージョンへ誘導するという意味になります。 +実装上は、独自のコードにバージョン番号を割り当て、それをシリアライズ済み状態と一緒に保存し、デシリアライズ時に適切なコードのバージョンへ誘導することを意味します。 diff --git a/docs/src/content/docs/ja/guides/mcp.mdx b/docs/src/content/docs/ja/guides/mcp.mdx index 97c64d00..6c000e89 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -13,107 +13,112 @@ import streamableHttpExample from '../../../../../../examples/docs/mcp/streamabl import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; -[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより: +The [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLMs にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP のドキュメントより: -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションのための USB‑C ポートのようなものだと考えてください。USB‑C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 +> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。USB‑C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 この SDK がサポートする MCP サーバーには 3 種類あります: 1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) がツールとして利用するリモート MCP サーバー 2. **Streamable HTTP MCP servers** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートのサーバー -3. **Stdio MCP servers** – 標準入出力でアクセスするサーバー（最もシンプルな選択肢） +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** | -| 標準入出力プロトコルのみ対応のローカル 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 がリモートのツールエンドポイントを呼び出し、その結果をモデルへストリーミング返却します。 -以下は Hosted MCP ツールを使う最も簡単な例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡すことで、Hosted MCP サーバーツールを作成できます。 +Hosted MCP ツールを使う最も簡単な例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡すことで、Hosted MCP サーバーツールの作成に役立ちます。 -続いて、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）で Agent を実行できます: +その後、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）で Agent を実行できます: - + -増分的な MCP の結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します: +増分的な MCP の結果をストリーミングするには、`Agent` を実行する際に `stream: true` を渡します: #### 任意の承認フロー -機微な操作に対しては、個々のツール呼び出しに人による承認を必須にできます。`requireApproval: 'always'` または、ツール名を `'never'`/`'always'` にマッピングするきめ細かなオブジェクトを渡します。 +機微な操作では、個々のツール呼び出しに対して人手による承認を必須にできます。`requireApproval: 'always'` または、ツール名ごとに `'never'`/`'always'` を指定する詳細なオブジェクトを渡します。 -プログラム的にツール呼び出しの安全性を判断できる場合は、[`onApproval` callback](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または拒否できます。人による承認が必要な場合は、ローカルの 関数ツール と同様に `interruptions` を使った同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) のアプローチを使えます。 +ツール呼び出しの安全性をプログラムで判断できる場合は、[`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 サーバー +### コネクタ対応の Hosted サーバー -Hosted MCP は OpenAI コネクターにも対応しています。`serverUrl` を指定する代わりに、コネクターの `connectorId` と `authorization` トークンを渡します。Responses API が認証を処理し、Hosted MCP インターフェース経由でコネクターのツールを公開します。 +Hosted MCP は OpenAI connectors にも対応しています。`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 + ストリーミング、HITL、onApproval）は、私たちの GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全な動作サンプル（Hosted ツール/Streamable HTTP/stdio + Streaming、HITL、onApproval）は、当社の GitHub リポジトリ内の [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 ## 2. Streamable HTTP MCP servers -Agent がローカルまたはリモートの Streamable HTTP MCP サーバーと直接通信する場合は、サーバーの `url`、`name`、任意の設定を指定して `MCPServerStreamableHttp` をインスタンス化します: +Agent がローカル・リモートいずれかの 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 -標準入出力のみを公開するサーバーには、`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 6adfeff3..e01fb322 100644 --- a/docs/src/content/docs/ja/guides/models.mdx +++ b/docs/src/content/docs/ja/guides/models.mdx @@ -14,10 +14,10 @@ import setTracingExportApiKeyExample from '../../../../../../examples/docs/confi すべてのエージェントは最終的に LLM を呼び出します。SDK はモデルを 2 つの軽量インターフェースの背後に抽象化します: -- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して _1 回_ のリクエストを行う方法を知っています -- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読めるモデルの **名前**（例: `'gpt‑4o'`）を `Model` インスタンスに解決します +- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して _1 回_ のリクエストを実行する方法を知っています +- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読めるモデルの**名前**（例: `'gpt‑4o'`）を `Model` インスタンスに解決します -日々の作業では通常、モデルの **名前** と、場合によっては `ModelSettings` のみに触れます。 +日々の開発では、通常はモデルの**名前**と、ときどき `ModelSettings` のみを扱います。 -## 既定のモデル +## 既定モデル -`Agent` を初期化する際にモデルを指定しない場合は、既定のモデルが使用されます。現在の既定値は [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェントワークフローの予測可能性と低レイテンシのバランスに優れています。 +`Agent` を初期化する際にモデルを指定しない場合、既定のモデルが使用されます。現在の既定は [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェントワークフローの予測可能性と低レイテンシのバランスに優れています。 -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) などの他のモデルに切り替えたい場合、エージェントの設定方法は 2 つあります。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) などの他のモデルへ切り替えたい場合、エージェントの設定方法は 2 つあります。 -まず、カスタムモデルを設定していないすべてのエージェントで特定のモデルを一貫して使用したい場合は、エージェントを実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定します。 +まず、カスタムモデルを設定していないすべてのエージェントで常に特定のモデルを使いたい場合は、エージェントを実行する前に環境変数 `OPENAI_DEFAULT_MODEL` を設定します。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 node my-awesome-agent.js ``` -次に、`Runner` インスタンスに既定のモデルを設定できます。エージェントでモデルを設定しない場合、この `Runner` の既定モデルが使用されます。 +次に、`Runner` インスタンスに既定モデルを設定できます。エージェントでモデルを設定しなければ、この `Runner` の既定モデルが使われます。 ### GPT-5 モデル -この方法で GPT‑5 の reasoning モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、[`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用すると、SDK は既定で適切な `modelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` の両方を `"low"` に設定します。既定モデルの reasoning effort を調整するには、独自の `modelSettings` を渡します: +この方法で GPT-5 の reasoning モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、[`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用する場合、SDK は妥当な `modelSettings` を既定で適用します。具体的には、`reasoning.effort` と `verbosity` の両方を `"low"` に設定します。既定モデルの reasoning effort を調整するには、独自の `modelSettings` を渡します: ```ts import { Agent } from '@openai/agents'; @@ -67,22 +67,22 @@ 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 effort をサポートしていないため、本 Agents SDK は既定で `"low"` にしています。 +より低レイテンシを求める場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を指定すると、既定設定より高速に応答が返ることが多いです。ただし、Responses API にある一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の reasoning effort をサポートしていないため、この Agents SDK の既定は `"low"` になっています。 ### 非 GPT-5 モデル -カスタムの `modelSettings` なしで非 GPT‑5 のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用的な `modelSettings` にフォールバックします。 +カスタムの `modelSettings` なしで GPT-5 以外のモデル名を渡した場合、SDK は任意のモデルで互換性のある汎用的な `modelSettings` にフォールバックします。 --- ## OpenAI プロバイダー -既定の `ModelProvider` は OpenAI APIs を使って名前を解決します。2 つの異なるエンドポイントをサポートします: +既定の `ModelProvider` は OpenAI API を使って名前を解決します。次の 2 つの異なるエンドポイントをサポートします: -| API | 使い方 | `setOpenAIAPI()` の呼び出し | -| ---------------- | ---------------------------------------------------------------- | --------------------------------------- | -| Chat Completions | 標準のチャット & 関数呼び出し | `setOpenAIAPI('chat_completions')` | -| Responses | 新しいストリーミング優先の生成 API（ツール呼び出し、柔軟な出力） | `setOpenAIAPI('responses')` _(default)_ | +| API | 用途 | `setOpenAIAPI()` を呼び出す | +| ---------------- | ------------------------------------------------------------------- | --------------------------------------- | +| Chat Completions | 標準的なチャット & Function Calling | `setOpenAIAPI('chat_completions')` | +| Responses | ツール呼び出しや柔軟な出力に対応した新しい streaming‑first 生成 API | `setOpenAIAPI('responses')` _(default)_ | ### 認証 @@ -92,7 +92,7 @@ const myAgent = new Agent({ title="既定の OpenAI キーを設定" /> -ネットワーク設定をカスタマイズする必要がある場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを挿し替えることもできます。 +カスタムのネットワーキング設定が必要な場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 --- @@ -100,38 +100,38 @@ const myAgent = new Agent({ `ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダーに依存しません。 -| Field | Type | Notes | +| フィールド | 型 | メモ | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ | -| `temperature` | `number` | 創造性と決定性のトレードオフ | -| `topP` | `number` | nucleus sampling | -| `frequencyPenalty` | `number` | 繰り返し出現するトークンを抑制 | -| `presencePenalty` | `number` | 新しいトークンの出現を促進 | +| `temperature` | `number` | 創造性と決定性のバランス | +| `topP` | `number` | Nucleus サンプリング | +| `frequencyPenalty` | `number` | 繰り返し出現するトークンの抑制 | +| `presencePenalty` | `number` | 新しいトークンの促進 | | `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 | -| `parallelToolCalls` | `boolean` | サポートされている場合に関数呼び出しの並列化を許可 | -| `truncation` | `'auto' \| 'disabled'` | トークンの切り詰め戦略 | +| `parallelToolCalls` | `boolean` | サポートされる場合に並列の関数呼び出しを許可 | +| `truncation` | `'auto' \| 'disabled'` | トークン切り詰め戦略 | | `maxTokens` | `number` | 応答内の最大トークン数 | -| `store` | `boolean` | 応答を保存して取得 / RAG ワークフローで利用 | -| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 など向けの reasoning effort | -| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 など向けのテキスト冗長度 | +| `store` | `boolean` | 応答を永続化し、取得 / RAG ワークフローで使用 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 などの reasoning effort | +| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 などのテキスト冗長度 | 設定はどちらのレベルにも付与できます: -`Runner` レベルの設定は、競合するエージェント個別の設定を上書きします。 +`Runner` レベルの設定は、競合するエージェント単位の設定より優先されます。 --- ## プロンプト -エージェントには `prompt` パラメーターを設定でき、サーバーに保存されたプロンプト構成を使用してエージェントの動作を制御します。現在、このオプションは OpenAI の +エージェントは `prompt` パラメーターで構成でき、エージェントの動作を制御するために使用すべき サーバー保存のプロンプト設定を指定します。現在、このオプションは OpenAI の [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみサポートされています。 -| Field | Type | Notes | -| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | -| `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) でモデルに強力な能力を付与 -- 必要に応じて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加 +- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を探索する +- [ツール](/openai-agents-js/ja/guides/tools) でモデルに強力な機能を追加する +- 必要に応じて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加する diff --git a/docs/src/content/docs/ja/guides/multi-agent.md b/docs/src/content/docs/ja/guides/multi-agent.md index cc965845..46fb3456 100644 --- a/docs/src/content/docs/ja/guides/multi-agent.md +++ b/docs/src/content/docs/ja/guides/multi-agent.md @@ -3,38 +3,38 @@ title: マルチエージェント description: Coordinate the flow between several agents --- -オーケストレーションとは、アプリ内でのエージェントのフローを指します。どのエージェントがどの順序で実行され、次に何をするかをどのように決めるのかということです。エージェントをオーケストレーションする主な方法は 2 つあります。 +オーケストレーションとは、アプリ内のエージェントのフローのことです。どのエージェントを、どの順序で実行し、次に何をするかをどう決めるのか。エージェントをオーケストレーションする主な方法は 2 つあります。 -1. LLM に意思決定させる方法：LLM の知能を使って計画・推論し、それに基づき次のステップを決めます -2. コードでオーケストレーションする方法：コードでエージェントのフローを決めます +1. LLM に意思決定させる方法: LLM の知能を使って計画・推論し、次に取るべき手順を決めます +2. コードでオーケストレーションする方法: コードでエージェントの流れを決定します -これらは組み合わせて使うことができます。各手法には以下のようなトレードオフがあります。 +これらは組み合わせて使えます。どちらにもトレードオフがあります。 ## LLM によるオーケストレーション -エージェントは、instructions、tools、ハンドオフを備えた LLM です。これは、オープンエンドなタスクが与えられたとき、LLM が自律的に計画を立て、ツールを使ってアクションやデータ取得を行い、ハンドオフでサブエージェントにタスクを委譲できることを意味します。例えば、リサーチ用のエージェントには次のようなツールを備えられます。 +エージェントは、instructions、ツール、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられた場合、LLM は自律的に計画し、ツールで行動やデータ取得を行い、ハンドオフでサブエージェントに委譲できます。たとえば、リサーチ用エージェントには次のようなツールを備えられます。 -- Web 検索でオンライン情報を探す -- ファイル検索と取得で独自データや接続先を検索する -- コンピュータ操作でコンピュータ上のアクションを実行する -- コード実行でデータ分析を行う -- 計画、レポート作成などに長けた特化エージェントへのハンドオフ +- Web 検索でオンライン情報を取得 +- ファイル検索とリトリーバルで独自データや接続を検索 +- コンピュータ操作でコンピュータ上のアクションを実行 +- コード実行でデータ分析を実施 +- 計画、レポート作成などに優れた特化エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、LLM の知能に依拠したい場合に有効です。重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで LLM の知能に依存したいときに適しています。重要な戦術は次のとおりです。 -1. 良いプロンプトに投資すること。利用可能なツール、その使い方、運用上のパラメーターを明確にすること -2. アプリを監視し反復改善すること。問題が起きる箇所を把握し、プロンプトを改善すること -3. エージェントに内省と改善を許可すること。例えばループで実行して自己批評させる、エラーメッセージを提供して改善させる、など -4. 何でもできる汎用エージェントではなく、1 つのタスクに特化して卓越するエージェントを用意すること -5. [evals](https://platform.openai.com/docs/guides/evals) に投資すること。これによりエージェントを訓練し、タスク達成能力を向上できます +1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーターを明確にする +2. アプリを監視して反復改善する。問題が起きる箇所を見つけ、プロンプトを改善する +3. エージェントが内省・改善できるようにする。たとえばループで実行して自己批評させる、エラーメッセージを与えて改善させる +4. 何でもできる汎用エージェントではなく、単一タスクに特化して卓越したエージェントを用意する +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。エージェントを訓練してタスク適性を高められます ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・パフォーマンスの観点で、より決定論的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の面でより決定的かつ予測可能にできます。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査可能な適切な形式のデータを生成する。例えば、エージェントにタスクをいくつかのカテゴリーに分類させ、カテゴリーに応じて次のエージェントを選ぶ -- 複数のエージェントを、前の出力を次の入力に変換して連鎖させる。ブログ記事作成のようなタスクを、リサーチ、アウトライン作成、本文作成、批評、改善といった一連のステップに分解する -- 実行役のエージェントを `while` ループで回し、評価とフィードバックを行うエージェントと組み合わせ、評価者が基準を満たしたと判断するまで繰り返す -- 複数のエージェントを並列実行する（例：JavaScript の基本コンポーネントである `Promise.all` を使用）。相互依存しない複数タスクがある場合、速度面で有効 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。たとえば、タスクをいくつかのカテゴリーに分類させ、カテゴリーに基づいて次のエージェントを選ぶ +- あるエージェントの出力を次のエージェントの入力に変換して連結する。ブログ記事の執筆を、リサーチ → アウトライン作成 → 本文執筆 → 批評 → 改善の一連のステップに分解する +- タスク実行エージェントと、評価とフィードバックを行うエージェントを組み合わせて `while` ループで回し、評価者が一定の基準を満たしたと判断するまで実行する +- 複数のエージェントを並列実行する。たとえば `Promise.all` などの JavaScript の基本コンポーネントを使う。依存関係のない複数タスクを高速化できる -[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) に複数の code examples があります。 +[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) に多数の code examples があります。 diff --git a/docs/src/content/docs/ja/guides/quickstart.mdx b/docs/src/content/docs/ja/guides/quickstart.mdx index 59035aa0..6c0ba626 100644 --- a/docs/src/content/docs/ja/guides/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. プロジェクトを作成して npm を初期化します。これは一度だけで大丈夫です +1. プロジェクトを作成し、npm を初期化します。一度だけ実行すれば大丈夫です ```bash mkdir my_project @@ -25,14 +25,14 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. 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 キーを設定します。まだ持っていない場合は、OpenAI API キーを作成するために[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従ってください ```bash export OPENAI_API_KEY=sk-... ``` - あるいは `setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、トレーシングには `setTracingExportApiKey('')` を使用できます。 - 詳細は[SDK の設定](/openai-agents-js/ja/guides/config)を参照してください。 + あるいは `setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、トレーシングには `setTracingExportApiKey('')` を使うこともできます。 + 詳細は[SDK の設定](/openai-agents-js/ja/guides/config)をご覧ください @@ -52,7 +52,7 @@ const agent = new Agent({ ## はじめてのエージェントの実行 -`run` メソッドでエージェントを実行できます。開始するエージェントと渡したい入力を指定して実行します。 +`run` メソッドでエージェントを実行できます。開始したいエージェントと渡したい入力の両方を渡すと、実行が開始されます。 これにより、その実行中に行われた最終出力とアクションを含む実行結果が返されます。 @@ -72,7 +72,7 @@ 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,22 +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 viewer](https://platform.openai.com/traces) に移動してください。 ## 次のステップ -より複雑なエージェントフローの作り方を学びましょう。 +より複雑なエージェントフローの構築方法を学びましょう。 - [エージェント](/openai-agents-js/ja/guides/agents)の設定について学ぶ - [エージェントの実行](/openai-agents-js/ja/guides/running-agents)について学ぶ diff --git a/docs/src/content/docs/ja/guides/release.mdx b/docs/src/content/docs/ja/guides/release.mdx index 532556c9..45252cb9 100644 --- a/docs/src/content/docs/ja/guides/release.mdx +++ b/docs/src/content/docs/ja/guides/release.mdx @@ -5,30 +5,30 @@ description: Learn how we version and release the SDK and recent changes. ## バージョン管理 -このプロジェクトは `0.Y.Z` 形式の、わずかに調整したセマンティックバージョニングに従います。先頭の `0` は、SDK がまだ急速に進化していることを示します。各コンポーネントの増分は次のとおりです。 +本プロジェクトは `0.Y.Z` 形式の、やや変更を加えたセマンティックバージョニングに従います。先頭の `0` は SDK がまだ急速に進化中であることを示します。各コンポーネントの増分は以下のとおりです。 ## マイナー（`Y`）バージョン -ベータとマークされていない公開インターフェースに対する**破壊的変更**がある場合、マイナーバージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への移行には破壊的変更が含まれる可能性があります。 +ベータではない公開インターフェースに対する**破壊的変更**がある場合に、マイナーバージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への変更に破壊的変更が含まれることがあります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` にピン留めすることをおすすめします。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` にバージョンを固定することをおすすめします。 ## パッチ（`Z`）バージョン -互換性を壊さない変更では `Z` を増やします: +後方互換性を壊さない変更には `Z` を増分します。 - バグ修正 - 新機能 -- プライベートインターフェースの変更 -- ベータ機能の更新 +- 非公開インターフェースの変更 +- beta 機能の更新 ## サブパッケージのバージョン管理 -メインの `@openai/agents` パッケージは、独立して使用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、1 つのパッケージのバージョンが上がると他も上がります。`1.0.0` への移行に伴い、この方針を変更する可能性があります。 +メインの `@openai/agents` パッケージは、独立して利用可能な複数のサブパッケージで構成されています。現時点ではパッケージのバージョンは連動しており、いずれかのパッケージのバージョンが上がると他も上がります。`1.0.0` に移行する際に、この方針を変更する可能性があります。 ## 変更履歴 -何が変わったかを把握しやすいよう、各サブパッケージの変更履歴を生成しています。変更はサブパッケージ内で起きている場合があるため、詳細は該当する変更履歴をご確認ください。 +何が変わったかを把握しやすくするため、各サブパッケージごとに変更履歴を生成しています。変更がサブパッケージ内で行われた場合は、該当する変更履歴で詳細を確認する必要があります。 - [`@openai/agents`](https://github.com/openai/openai-agents-js/blob/main/packages/agents/CHANGELOG.md) - [`@openai/agents-core`](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/CHANGELOG.md) diff --git a/docs/src/content/docs/ja/guides/results.mdx b/docs/src/content/docs/ja/guides/results.mdx index a7d6bcd2..ab18faba 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -9,81 +9,81 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? [エージェントの実行](/openai-agents-js/ja/guides/running-agents)を行うと、次のいずれかを受け取ります: -- `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)も参照してください +- `stream: true` を付けずに `run` を呼び出した場合は [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) +- `stream: true` を付けて `run` を呼び出した場合は [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。ストリーミングの詳細は[ストリーミング](/openai-agents-js/ja/guides/streaming)も参照してください ## 最終出力 -`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が含まれます。結果は次のいずれかです: +`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が入ります。結果は次のいずれかです: -- `string` — `outputType` が定義されていないエージェントのデフォルト -- `unknown` — エージェントが出力タイプとして JSON スキーマを定義している場合。この場合、JSON はパースされていますが型の検証は手動で行う必要があります -- `z.infer` — エージェントが出力タイプとして Zod スキーマを定義している場合。出力はこのスキーマに自動的にパースされます -- `undefined` — エージェントが出力を生成しなかった場合（たとえば、出力を生成する前に停止した場合） +- `string` — `outputType` を定義していないエージェントのデフォルト +- `unknown` — エージェントが出力型として JSON スキーマを定義している場合。この場合 JSON はパースされていますが、型の検証は手動で行う必要があります +- `z.infer` — エージェントが出力型として Zod スキーマを定義している場合。出力は自動的にこのスキーマでパースされます +- `undefined` — エージェントが出力を生成しなかった場合（たとえば出力前に停止した場合） -異なる出力タイプを伴うハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 +異なる出力型を持つハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 -これにより、SDK があらゆるハンドオフの可能性をまたいで出力タイプを推論し、`finalOutput` プロパティにユニオン型を提供できるようになります。 +これにより、SDK がすべての可能なハンドオフにわたる出力型を推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 例: ## 次ターンの入力 -次のターンの入力にアクセスする方法は 2 つあります: +次のターンの入力には、以下の 2 通りでアクセスできます: -- `result.history` — 入力とエージェントの出力の両方のコピーを含みます -- `result.output` — エージェントの全実行の出力を含みます +- `result.history` — 入力とエージェントの出力の両方のコピーを保持 +- `result.output` — エージェントのフル実行の出力を保持 -`history` は、チャットのようなユースケースで完全な履歴を維持するのに便利です: +`history` は、チャット用途で完全な履歴を維持するのに便利です: ## 最後のエージェント -`lastAgent` プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回 ユーザー が何かを入力する際に有用です。たとえば、フロントラインのトリアージ エージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存して、次回 ユーザー がメッセージを送ったときに再利用できます。 +`lastAgent` プロパティには、最後に実行されたエージェントが入ります。アプリによっては、次回 ユーザー が入力するときに便利です。たとえば、言語別エージェントへハンドオフする一次トリアージのエージェントがある場合、最後のエージェントを保存しておき、次回 ユーザー がメッセージを送るときに再利用できます。 -ストリーミング モードでは、現在実行中のエージェントに対応する `currentAgent` プロパティにアクセスするのも有用です。 +ストリーミングモードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスするのも有用です。 ## 新規アイテム -`newItems` プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。実行アイテムは、LLM が生成した元アイテムをラップします。これにより、LLM の出力に加えて、どのエージェントに関連付けられたイベントかにもアクセスできます。 +`newItems` プロパティには、実行中に生成された新規アイテムが入ります。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。Run item は LLM が生成した元アイテムをラップします。どのエージェントに紐づくイベントかなど、LLM の出力に加えて参照できます。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元アイテムは生成されたメッセージです -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフ ツールを呼び出したことを示します。元アイテムは LLM のツール呼び出しアイテムです -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。元アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます -- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを呼び出したことを示します -- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。元アイテムはツールの応答です。アイテムからツールの出力にもアクセスできます -- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM からの推論アイテムを示します。元アイテムは生成された推論です -- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。元アイテムは LLM のツール呼び出しアイテムです +- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを表します。元アイテムは生成されたメッセージです +- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフ ツールを呼び出したことを表します。元アイテムは LLM からのツール呼び出しアイテムです +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを表します。元アイテムはハンドオフ ツール呼び出しに対するツールのレスポンスです。アイテムからソース/ターゲットのエージェントにもアクセスできます +- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを起動したことを表します +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを表します。元アイテムはツールのレスポンスです。アイテムからツールの出力にもアクセスできます +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM の reasoning アイテムを表します。元アイテムは生成された reasoning です +- [`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`s の配列になります。割り込みの扱い方については、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)を参照してください。 ## その他の情報 ### 元レスポンス -`rawResponses` プロパティには、エージェントの実行中にモデルが生成した元の LLM レスポンスが含まれます。 +`rawResponses` プロパティには、エージェント実行中にモデルが生成した元の LLM レスポンスが入ります。 -### 最後のレスポンス ID +### 最終レスポンス 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 49b3095c..c5c8d2d1 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -11,109 +11,109 @@ import chatLoopExample from '../../../../../../examples/docs/running-agents/chat エージェントは単体では何もしません。`Runner` クラスまたは `run()` ユーティリティで実行します。 - + -カスタム runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスで動作する `run()` ユーティリティも使えます。 +カスタム Runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスで動作する `run()` ユーティリティも使えます。 -あるいは独自の runner インスタンスを作成できます。 +別途 Runner インスタンスを作成することもできます: - + -エージェントの実行後、最終出力と実行履歴全体を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 +エージェントを実行すると、最終的な出力と実行の完全な履歴を含む [実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 -## エージェント ループ +## エージェントループ -Runner の run メソッドでは、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）または入力アイテムのリスト（OpenAI Responses API のアイテム）を指定できます。 +Runner の run メソッドでは、開始エージェントと入力を渡します。入力は文字列（ユーザーのメッセージとして扱われます）か、OpenAI Responses API の項目に対応する入力アイテムのリストのいずれかです。 -runner は次のループを実行します。 +Runner は次のループを実行します: 1. 現在の入力で現在のエージェントのモデルを呼び出す -2. LLM の応答を確認する - - **Final output** → 返す - - **Handoff** → 新しいエージェントに切り替え、蓄積された会話履歴を保持して 1 に戻る - - **Tool calls** → ツールを実行し、その結果を会話に追加して 1 に戻る +2. LLM の応答を検査する + - **最終出力** → 返す + - **ハンドオフ** → 新しいエージェントに切り替え、蓄積された会話履歴を保持し、1 に戻る + - **ツール呼び出し** → ツールを実行し、その結果を会話に追加して、1 に戻る 3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローする ### Runner のライフサイクル -アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスは -モデルプロバイダーやトレーシング設定などのグローバル設定を保持します。まったく異なる構成が必要な場合のみ -別の `Runner` を作成してください。簡単なスクリプトでは、内部でデフォルト runner を使う `run()` を呼び出すこともできます。 +アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシング設定などのグローバル設定を保持します。完全に異なる構成が必要な場合のみ別の `Runner` を作成してください。シンプルなスクリプトでは、内部でデフォルト Runner を使う `run()` を呼び出すこともできます。 -## 実行引数 +## Run 引数 -`run()` メソッドの入力は、実行を開始する初期エージェント、実行の入力、オプションのセットです。 +`run()` メソッドの入力は、実行を開始する初期エージェント、実行の入力、そして一連のオプションです。 -入力は文字列（ユーザー メッセージと見なされます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [Human in the loop (人間の介入)](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 +入力は、文字列（ユーザーのメッセージとして扱われます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、もしくは [Human in the loop（人間の介入）](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 -追加のオプションは次のとおりです。 +追加のオプションは次のとおりです: -| Option | Default | Description | -| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから届くイベントを順次発行します | -| `context` | – | すべての tool / guardrail / handoff に転送されるコンテキスト オブジェクト。詳しくは [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 | -| `maxTurns` | `10` | セーフティ リミット。到達すると [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスロー | -| `signal` | – | キャンセル用の `AbortSignal` | +| Option | Default | Description | +| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着するイベントを逐次発行します | +| `context` | – | すべての tool / guardrail / handoff に転送されるコンテキストオブジェクト。詳細は [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 | +| `maxTurns` | `10` | セーフティ上限。到達すると [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスロー | +| `signal` | – | キャンセル用の `AbortSignal` | ## ストリーミング -ストリーミングでは、LLM の実行に伴うストリーミング イベントも受け取れます。ストリーム開始後、`StreamedRunResult` には実行に関する完全な情報（新しい出力を含む）が含まれます。`for await` ループでストリーミング イベントを反復処理できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 +ストリーミングにより、LLM の実行中にイベントを逐次受け取れます。ストリームが開始されると、`StreamedRunResult` には新規出力を含む実行に関する完全な情報が格納されます。`for await` ループを使ってストリーミングイベントを反復処理できます。詳細は [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 -## 実行設定 +## Run 設定 -独自の `Runner` インスタンスを作成する場合、runner を構成するために `RunConfig` オブジェクトを渡せます。 +独自の `Runner` インスタンスを作成する場合、`RunConfig` オブジェクトを渡して Runner を構成できます。 -| Field | Type | Purpose | -| --------------------------- | --------------------- | ----------------------------------------------------------------------- | -| `model` | `string \| Model` | 実行中の **すべての** エージェントに特定のモデルを強制適用 | -| `modelProvider` | `ModelProvider` | モデル名を解決。デフォルトは OpenAI プロバイダー | -| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニング パラメーター | -| `handoffInputFilter` | `HandoffInputFilter` | handoff 実行時に入力アイテムを変更（handoff 自体で未定義の場合） | -| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | -| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | -| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化 | -| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、LLM/ツールの入出力をトレースから除外 | -| `workflowName` | `string` | Traces ダッシュボードに表示。関連する実行をグルーピングするのに役立つ | -| `traceId` / `groupId` | `string` | SDK に生成させる代わりに、トレース ID またはグループ ID を手動指定 | -| `traceMetadata` | `Record` | すべてのスパンに付与する任意のメタデータ | +| 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` のみの場合もあれば、生成されたすべての項目を見せる場合もあります。 -インタラクティブ版は [the chat example](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 +インタラクティブ版は[チャットの例](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts)を参照してください。 ## 例外 -SDK は捕捉可能な少数のエラーをスローします。 +SDK は捕捉可能な少数のエラーをスローします: - [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` に到達 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが不正な出力を生成（例: 不正な JSON、未知のツール） +- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが無効な出力を生成（例: 不正な JSON、不明なツール） - [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) – ガードレール違反 - [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールの実行が失敗 - [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 関数ツール呼び出しのいずれかが失敗 -- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 構成またはユーザー入力に基づいてスローされたエラー +- [`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 +124,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 fa739a75..0fa70d57 100644 --- a/docs/src/content/docs/ja/guides/streaming.mdx +++ b/docs/src/content/docs/ja/guides/streaming.mdx @@ -9,48 +9,48 @@ import nodeTextStreamExample from '../../../../../../examples/docs/streaming/nod import handleAllEventsExample from '../../../../../../examples/docs/streaming/handleAllEvents.ts?raw'; import streamedHITLExample from '../../../../../../examples/docs/streaming/streamedHITL.ts?raw'; -Agents SDK は、モデルやその他の実行ステップの出力を段階的に配信できます。ストリーミングにより UI を応答性よく保ち、最終的な実行結果全体を待たずに ユーザー を更新できます。 +Agents SDK は、モデルおよびその他の実行ステップからの出力を段階的に配信できます。ストリーミングにより UI を応答性よく保ち、最終的な実行結果全体を待たずにユーザーを更新できます。 ## ストリーミングの有効化 -`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミングオブジェクトを取得できます: +`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な結果ではなくストリーミングオブジェクトが得られます: -ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、実行内で何が起きたかを表すオブジェクトです。ストリームは、エージェントの実行の異なる部分を表す 3 種類のイベントのいずれかを出力します。多くのアプリケーションが欲しいのはモデルのテキストだけなので、ストリームにはそのためのヘルパーがあります。 +ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、その実行中に何が起きたかを記述するオブジェクトです。ストリームはエージェントの実行の異なる部分を表す 3 種類のイベントのいずれかを生成します。とはいえ、ほとんどのアプリケーションはモデルのテキストだけが必要なので、ストリームにはヘルパーが用意されています。 ### テキスト出力の取得 -`stream.toTextStream()` を呼び出すと、発行されたテキストのストリームを取得できます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js の `Readable` です。`process.stdout` などの出力先へそのままパイプできます。 +`stream.toTextStream()` を呼び出すと、生成されたテキストのストリームを取得できます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js `Readable` です。これを `process.stdout` や他の出力先に直接パイプできます。 -`stream.completed` の Promise は、実行と保留中のコールバックがすべて完了した時点で解決します。出力がもうないことを保証したい場合は、必ず待機してください。 +`stream.completed` の Promise は、実行と保留中のコールバックがすべて完了すると解決します。出力がもうないことを確実にするには必ず await してください。 ### すべてのイベントの監視 -`for await` ループを使って、到着した各イベントを検査できます。役立つ情報として、低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などがあります: +`for await` ループを使って、到着した各イベントを確認できます。役立つ情報には、低レベルなモデルイベント、エージェントの切り替え、および SDK 固有の実行情報が含まれます: -完全なスクリプトについては、[the streamed example](https://github.com/openai/openai-agents-js/ja/tree/main/examples/agent-patterns/streamed.ts) を参照してください。プレーンテキストストリームと 元 のイベントストリームの両方を出力します。 +[ストリーミングの code examples](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) では、プレーンテキストストリームと元のイベントストリームの両方を出力する完全なスクリプトを確認できます。 ## イベントタイプ -ストリームは 3 種類の異なるイベントタイプを出力します: +ストリームは 3 種類のイベントを生成します: ### raw_model_stream_event @@ -83,7 +83,7 @@ type RunItemStreamEvent = { }; ``` -ハンドオフペイロードの例: +ハンドオフのペイロード例: ```json { @@ -118,23 +118,23 @@ type RunAgentUpdatedStreamEvent = { } ``` -## ストリーミング中の Human in the loop +## ストリーミング中の Human in the loop (人間の介入) -ストリーミングは、実行を一時停止するハンドオフ（たとえば、ツールに承認が必要な場合）と両立します。ストリームオブジェクトの `interruption` フィールドで割り込みにアクセスでき、それぞれに対して `state.approve()` または `state.reject()` を呼び出すことで実行を継続できます。`{ stream: true }` で再実行すると、ストリーミング出力が再開します。 +ストリーミングは、実行を一時停止するハンドオフ（たとえばツールに承認が必要な場合）と両立します。ストリームオブジェクトの `interruption` フィールドで割り込みにアクセスでき、各割り込みに対して `state.approve()` または `state.reject()` を呼び出すことで実行を継続できます。`{ stream: true }` で再実行するとストリーミング出力が再開します。 -ユーザー と対話する、より充実した例は -[`human-in-the-loop-stream.ts`](https://github.com/openai/openai-agents-js/ja/tree/main/examples/agent-patterns/human-in-the-loop-stream.ts) にあります。 +ユーザーと対話する、より包括的な例は +[`human-in-the-loop-stream.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop-stream.ts) です。 ## ヒント -- すべての出力がフラッシュされたことを確実にするため、終了前に `stream.completed` を待機すること -- 最初の `{ stream: true }` オプションは、その呼び出しにのみ適用されます。`RunState` で再実行する場合は、オプションを再度指定する必要があります -- アプリケーションがテキスト結果だけを必要とする場合は、個々のイベントオブジェクトを扱わずに済むよう `toTextStream()` を優先すること +- すべての出力がフラッシュされるように、終了前に `stream.completed` を待つことを忘れないでください +- 最初の `{ stream: true }` オプションは、それを指定した呼び出しにのみ適用されます。`RunState` で再実行する場合は、再度オプションを指定する必要があります +- アプリケーションがテキスト結果だけを気にする場合は、個々のイベントオブジェクトを扱わずに済むように `toTextStream()` を優先してください -ストリーミングとイベントシステムを使えば、エージェントをチャットインターフェース、ターミナルアプリケーション、または段階的な更新が ユーザー の利点になるあらゆる場所に統合できます。 +ストリーミングとイベントシステムを使えば、エージェントをチャットインターフェース、ターミナルアプリケーション、またはユーザーが段階的な更新の恩恵を受けるあらゆる場所に統合できます。 diff --git a/docs/src/content/docs/ja/guides/tools.mdx b/docs/src/content/docs/ja/guides/tools.mdx index fc017f50..6ce8e7f5 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,12 +10,12 @@ 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 が呼び出せるようにします +1. **組み込みツール（Hosted）** – モデルと同じ OpenAI サーバー上で実行します。_(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_ +2. **関数ツール** – 任意のローカル関数を JSON スキーマで包み、LLM が呼び出せるようにします 3. **エージェントをツールとして** – エージェント全体を呼び出し可能なツールとして公開します -4. **ローカル MCP サーバー** – ローカルで動作する Model context protocol サーバーを接続します +4. **ローカル MCP サーバー** – あなたのマシン上で動作する Model Context Protocol サーバーを接続します --- @@ -23,44 +23,48 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer `OpenAIResponsesModel` を使う場合、次の組み込みツールを追加できます。 -| ツール | 型文字列 | 目的 | -| ---------------------------- | -------------------- | --------------------------------------------- | -| Web 検索 | `'web_search'` | インターネット検索 | -| ファイル / 検索（retrieval） | `'file_search'` | OpenAI 上でホストされるベクトルストアをクエリ | -| コンピュータ操作 | `'computer'` | GUI 操作を自動化 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | -| 画像生成 | `'image_generation'` | テキストから画像を生成 | +| Tool | Type string | Purpose | +| ----------------------- | -------------------- | --------------------------------------------- | +| Web search | `'web_search'` | インターネット検索 | +| File / retrieval search | `'file_search'` | OpenAI 上でホストされる ベクトルストア を照会 | +| Computer use | `'computer'` | GUI 操作を自動化 | +| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | +| Image generation | `'image_generation'` | テキストに基づいて画像を生成 | - + -各パラメーターの構成は OpenAI Responses API に一致します。`rankingOptions` やセマンティックフィルタなどの高度なオプションは公式ドキュメントを参照してください。 +正確なパラメーター群は OpenAI Responses API と一致します。`rankingOptions` やセマンティックフィルタのような高度なオプションは公式ドキュメントを参照してください。 --- ## 2. 関数ツール -`tool()` ヘルパーを使えば、**あらゆる**関数をツールにできます。 +`tool()` ヘルパーを使えば、**任意の** 関数をツールにできます。 ### オプションリファレンス -| フィールド | 必須 | 説明 | -| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `name` | いいえ | 省略時は関数名（例: `get_weather`） | -| `description` | はい | LLM に表示される明確で人が読める説明 | -| `parameters` | はい | Zod スキーマまたは raw の JSON スキーマオブジェクトのいずれか。Zod の parameters を使うと自動的に **strict** モードが有効 | -| `strict` | いいえ | `true`（デフォルト）の場合、引数が検証に失敗すると SDK はモデルエラーを返す。曖昧なマッチングにするには `false` | -| `execute` | はい | `(args, context) => string \| Promise`– ビジネスロジック。2 番目の引数は省略可能で、`RunContext` | -| `errorFunction` | いいえ | 内部エラーをユーザーに見える文字列へ変換するカスタムハンドラー `(context, error) => string` | +| Field | Required | Description | +| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | No | 既定は関数名（例: `get_weather`） | +| `description` | Yes | LLM に表示する明確で人間が読める説明 | +| `parameters` | Yes | Zod スキーマまたは 元 JSON スキーマオブジェクトのいずれか。Zod の parameters は自動的に **strict** モードを有効化 | +| `strict` | No | `true`（デフォルト）の場合、引数が検証に通らないと SDK はモデルエラーを返します。あいまいなマッチングにするには `false` に設定 | +| `execute` | Yes | `(args, context) => string \| Promise`– ビジネスロジック。2 番目の引数は省略可能で `RunContext` | +| `errorFunction` | No | 内部エラーを ユーザー に見える文字列へ変換するためのカスタムハンドラー `(context, error) => string` | -### 非 strict な JSON スキーマ ツール +### 非 strict な JSON スキーマツール -無効または不完全な入力をモデルに推測させたい場合は、raw の JSON スキーマ使用時に strict モードを無効化できます。 +無効または不完全な入力をモデルに推測させたい場合は、元 JSON スキーマを使う際に strict モードを無効化できます。 -このとき SDK は内部で次を行います。 +SDK の内部動作: - 単一の `input` パラメーターを持つ関数ツールを作成 - ツールが呼ばれたときに、その入力でサブエージェントを実行 -- 最後のメッセージ、または `customOutputExtractor` で抽出した出力を返却 +- 最後のメッセージ、または `customOutputExtractor` で抽出された出力を返却 + +エージェントをツールとして実行すると、Agents SDK はデフォルト設定のランナーを作成し、関数実行内でそのランナーを使ってエージェントを実行します。`runConfig` や `runOptions` のプロパティを指定したい場合は、`asTool()` に渡してランナーの動作をカスタマイズできます。 --- -## 4. ローカル MCP サーバー +## 4. MCP サーバー -ローカルの [Model Context Protocol](https://modelcontextprotocol.io/) サーバー経由でツールを公開し、エージェントに接続できます。`MCPServerStdio` を使用してサーバーを起動・接続します。 +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) サーバー経由でツールを公開し、エージェントに接続できます。 +例えば、`MCPServerStdio` を使って stdio MCP サーバーを起動・接続できます。 - + -完全な例は [`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-openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) を参照してください。また、MCP サーバーツール連携の包括的なガイドを探している場合は、[MCP 連携](/openai-agents-js/ja/guides/mcp) を参照してください。 --- ## ツール使用時の動作 -モデルがツールをいつどのように使うかの制御については、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください（`tool_choice`、`toolUseBehavior` など）。 +モデルがいつ・どのようにツールを使うべきかの制御は、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください（`tool_choice`、`toolUseBehavior` など）。 --- ## ベストプラクティス -- **短く明示的な説明** – ツールが何をするか、いつ使うかを記述 -- **入力の検証** – 可能な限り Zod スキーマで厳密な JSON 検証を行う -- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返すべきで、例外を投げない -- **ツールは単一責任** – 小さく合成可能なツールはモデルの推論が向上 +- **短く明確な説明** – ツールが「何をするか」と「いつ使うか」を記述 +- **入力の検証** – 可能なら Zod スキーマで厳密な JSON 検証を実施 +- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返し、throw しない +- **ツールは単一責務で** – 小さく合成可能なツールはモデルの推論精度を高める --- ## 次のステップ -- [エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) で強制的なツール使用について学ぶ -- [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加してツールの入力または出力を検証 +- [ツール使用の強制](/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 4abf68a6..6d60c7f6 100644 --- a/docs/src/content/docs/ja/guides/tracing.mdx +++ b/docs/src/content/docs/ja/guides/tracing.mdx @@ -7,14 +7,14 @@ 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 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで収集します。[トレース ダッシュボード](https://platform.openai.com/traces)を使って、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みのトレーシングが含まれており、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで対象です。[Traces ダッシュボード](https://platform.openai.com/traces)を使うと、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。