diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index 4ba98023..8c45953e 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -7,30 +7,30 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -Agents SDK は標準で Responses API または Chat Completions API を通じて OpenAI モデルと連携します。ですが、別のモデルを使いたい場合は、[Vercel の AI SDK](https://sdk.vercel.ai/) がサポートする幅広いモデルを、このアダプターを介して Agents SDK で利用できます。 +Agents SDK は標準で Responses API または Chat Completions API を介して OpenAI モデルと連携します。別のモデルを使用したい場合は、[Vercel の AI SDK](https://sdk.vercel.ai/) がサポートする幅広いモデルを、このアダプターを通じて Agents SDK に取り込むことができます。 ## セットアップ -1. extensions パッケージをインストールして AI SDK アダプターを導入します: +1. 拡張パッケージをインストールして AI SDK アダプターを導入します: ```bash npm install @openai/agents-extensions ``` -2. [Vercel の AI SDK](https://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'; @@ -46,19 +46,19 @@ Agents SDK は標準で Responses API または Chat Completions API を通じ ## 例 - + ## プロバイダー メタデータの受け渡し -メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` を通して渡します。値は基盤となる AI SDK モデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` +メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` に渡します。値は基盤となる AI SDK のモデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` ```ts providerData: { @@ -70,7 +70,7 @@ providerData: { } ``` -は、AI SDK 連携を使用すると +は、AI SDK 連携を使用する場合は次のようになります ```ts providerMetadata: { @@ -81,5 +81,3 @@ providerMetadata: { } } ``` - -になります。 diff --git a/docs/src/content/docs/ja/extensions/cloudflare.mdx b/docs/src/content/docs/ja/extensions/cloudflare.mdx index 40d261a2..14188240 100644 --- a/docs/src/content/docs/ja/extensions/cloudflare.mdx +++ b/docs/src/content/docs/ja/extensions/cloudflare.mdx @@ -6,12 +6,13 @@ description: Connect your Agents SDK agents from Cloudflare Workers/workerd usin import { Aside, Steps, Code } from '@astrojs/starlight/components'; import cloudflareBasicExample from '../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw'; -Cloudflare Workers とその他の workerd ランタイムは、グローバル `WebSocket` コンストラクタを使って外向き WebSocket を開くことができません。これらの環境から リアルタイムエージェント に簡単に接続できるようにするため、extensions パッケージは `fetch()` ベースのアップグレードを内部で実行する専用のトランスポートを提供します。 +Cloudflare Workers とその他の workerd ランタイムは、グローバルな `WebSocket` コンストラクターを使って外向きの WebSocket を開くことができません。これらの環境から リアルタイムエージェント への接続を簡単にするために、extensions パッケージは内部で `fetch()` ベースのアップグレードを実行する専用のトランスポートを提供します。 @@ -29,7 +30,7 @@ Cloudflare Workers とその他の workerd ランタイムは、グローバル -3. **`RealtimeSession` を接続します。** +3. **`RealtimeSession` に接続します。** ```typescript await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' }); @@ -39,6 +40,6 @@ Cloudflare Workers とその他の workerd ランタイムは、グローバル ## 注意事項 -- Cloudflare トランスポートは内部的に `fetch()` と `Upgrade: websocket` を使用し、ソケットの `open` イベント待ちをスキップして workerd API に合わせます -- このトランスポート使用時も、`RealtimeSession` のすべての機能（tools、ガードレール など）は通常どおり動作します +- Cloudflare 用トランスポートは内部的に `Upgrade: websocket` 付きの `fetch()` を使用し、ソケットの `open` イベント待機を省略します。これは workerd の API に合わせた挙動です +- このトランスポート使用時も、すべての `RealtimeSession` 機能（ツール、ガードレールなど）が通常どおり動作します - 開発時の詳細ログ確認には `DEBUG=openai-agents*` を使用します diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index 0eed17cf..54dc87eb 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,36 +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 に接続できます。デフォルトの Realtime Session トランスポートを `websocket` モードで使い、Twilio から来るイベントを Realtime Session に接続することも可能です。ただし、その場合は適切なオーディオ形式の設定や、Web ベースの会話よりも通話では遅延が大きくなるため、割り込みタイミングの調整が必要になります。 +Twilio は、電話の通話からの元音声を WebSocket サーバーへ送信する [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しています。このセットアップを使って、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続できます。Twilio からのイベントを Realtime Session に接続するには、`websocket` モードのデフォルトの Realtime Session トランスポートを使用できます。ただし、通話は Web ベースの会話よりも遅延が大きくなるため、適切な音声フォーマットの設定と、割り込みタイミングの調整が必要です。 -セットアップ体験を改善するために、Twilio への接続、割り込み処理、オーディオ転送を代わりに扱う専用のトランスポート層を用意しました。 +セットアップ体験を改善するために、Twilio への接続、割り込み処理、音声転送を代わりに処理する専用のトランスポートレイヤーを用意しました。 ## セットアップ -1. **Twilio アカウントと Twilio の電話番号を用意する** +1. **Twilio アカウントと Twilio の電話番号を用意します。** -2. **Twilio からのイベントを受け取れる WebSocket サーバーを用意する** +2. **Twilio からのイベントを受信できる WebSocket サーバーをセットアップします。** ローカル開発の場合は、[`ngrok`](https://ngrok.io/) や [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - などのローカルトンネルを設定して、ローカル サーバーを Twilio からアクセス可能にする必要があります。`TwilioRealtimeTransportLayer` + のようなローカルトンネルの設定が必要になり、Twilio からローカルサーバーへアクセスできるようにします。`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' }); @@ -54,25 +55,28 @@ 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 の元イベントにアクセスします。** - Twilio から送られてくる 元 イベントにアクセスしたい場合は、`RealtimeSession` インスタンスの `transport_event` を購読します。Twilio の各イベントは `twilio_message` タイプで、 元 イベントデータを含む `message` プロパティを持ちます。 + Twilio から送信される元のイベントにアクセスしたい場合は、`RealtimeSession` インスタンスの + `transport_event` をリッスンします。Twilio からのすべてのイベントは `twilio_message` という type と、元イベントデータを含む `message` プロパティを持ちます。 -3. **デバッグログを確認する** +3. **デバッグログを確認します。** - 何が起きているかを詳しく知りたい場合があります。環境変数 `DEBUG=openai-agents*` を使うと Agents SDK からのすべてのデバッグログが表示されます。あるいは、`DEBUG=openai-agents:extensions:twilio*` を使って Twilio アダプターのデバッグログだけを有効にできます。 + 状況を詳しく知りたい場合があります。環境変数 `DEBUG=openai-agents*` を使うと Agents SDK のすべてのデバッグログが表示されます。あるいは、Twilio アダプターのデバッグログだけを有効化するには + `DEBUG=openai-agents:extensions:twilio*` を使用します。 -## フルサーバー例 +## サーバーの完全な例 -以下は、Twilio からのリクエストを受け取り、それを `RealtimeSession` に転送する WebSocket サーバーのエンドツーエンドの例です。 +以下は、Twilio からのリクエストを受け取り、`RealtimeSession` に転送する end-to-end の WebSocket サーバー例です。 + -このページの残りでは、すべての Agent 機能を詳しく説明します。 +このページでは、エージェントの各機能を詳しく説明します。 --- ## 基本設定 -`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。よく使用されるプロパティは以下のとおりです。 +`Agent` のコンストラクターは 1 つの設定オブジェクトを受け取ります。よく使われるプロパティは次のとおりです。 -| Property | Required | Description | -| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `name` | yes | 短い人間可読の識別子 | -| `instructions` | yes | System prompt（文字列 **または** 関数 – [動的 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/) インスタンスの配列 | +| 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 など）。トップレベルにないプロパティが必要な場合は `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 互換の任意のオブジェクト @@ -65,49 +61,45 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor -`outputType` が指定されると、SDK はプレーンテキストの代わりに自動的に +`outputType` が指定されると、SDK はプレーンテキストではなく自動的に [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。 --- -## マルチエージェントの設計パターン +## マルチエージェントのシステム設計パターン -エージェントを組み合わせる方法は多数あります。プロダクションアプリでよく見られる 2 つのパターンは次のとおりです。 +エージェントを組み合わせる方法はたくさんあります。本番アプリでよく見られる 2 つのパターンは次のとおりです。 -1. **マネージャー（エージェントをツールとして）** – 会話を中央のエージェントが所有し、ツールとして公開された専門エージェントを呼び出します -2. **ハンドオフ** – 初期エージェントがユーザーのリクエストを特定した後、会話全体を専門エージェントに委譲します +1. **マネージャー（エージェントをツールとして）** – 中央のエージェントが会話を所有し、ツールとして公開された専門エージェントを呼び出す +2. **ハンドオフ** – 最初のエージェントがユーザーの要求を特定したら、会話全体を専門家に委譲する -これらのアプローチは補完的です。マネージャーはガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を保持せずに単一タスクに集中できるようにします。 +これらのアプローチは補完的です。マネージャーはガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を保持せずに単一タスクに集中できます。 ### マネージャー（エージェントをツールとして） -このパターンではマネージャーは制御を手放しません—LLM がツールを使い、マネージャーが最終的な回答を要約します。詳しくは [ツール](/openai-agents-js/ja/guides/tools#agents-as-tools) を参照してください。 +このパターンではマネージャーが制御を手放しません。LLM がツールを使用し、最終的な回答をマネージャーが要約します。詳しくは[ツール](/openai-agents-js/ja/guides/tools#agents-as-tools)を参照してください。 - + ### ハンドオフ -ハンドオフではトリアージ用エージェントがリクエストを振り分けますが、ハンドオフが発生すると専門エージェントが最終出力を生成するまで会話を所有します。これによりプロンプトを短く保ち、各エージェントを独立して考察できます。詳しくは [ハンドオフ](/openai-agents-js/ja/guides/handoffs) を参照してください。 +ハンドオフでは、トリアージ用エージェントがリクエストをルーティングしますが、ハンドオフが発生すると専門エージェントが最終出力を生成するまで会話を所有します。これによりプロンプトが短くなり、各エージェントを個別に考えやすくなります。詳しくは[ハンドオフ](/openai-agents-js/ja/guides/handoffs)をご覧ください。 - + --- -## 動的 instructions +## Dynamic instructions -`instructions` は文字列ではなく**関数**にすることもできます。関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列または `Promise` を返せます。 +`instructions` は文字列の代わりに **関数** にできます。この関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返せます。 同期関数と `async` 関数の両方がサポートされています。 @@ -116,48 +108,48 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## ライフサイクルフック -高度なユースケースでは、イベントをリッスンして Agent のライフサイクルを観測できます。利用可能な内容は、[こちら](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts) に記載のエージェントフックのイベント名を参照してください。 +高度なユースケースでは、イベントをリッスンして 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` インスタンスが返されます。 - + --- ## ツール使用の強制 -ツールを提供しても、LLM が必ず呼び出すとは限りません。`modelSettings.tool_choice` でツール使用を**強制**できます。 +ツールを提供しても、LLM が必ずしも呼び出すとは限りません。`modelSettings.tool_choice` でツール使用を**強制**できます。 -1. `'auto'`（デフォルト）– ツールを使うかどうかを LLM が判断 -2. `'required'` – LLM はツールを呼び出す「必要がある」（どれを使うかは選べる） -3. `'none'` – LLM はツールを呼び出しては**ならない** -4. 特定のツール名（例: `'calculator'`）– LLM はその特定のツールを呼び出す必要がある +1. `'auto'`（デフォルト） – ツールを使うかどうかを LLM が決定 +2. `'required'` – LLM はツールを呼び出す _必要がある_（どれを使うかは選択可） +3. `'none'` – LLM はツールを呼び出しては **ならない** +4. 特定のツール名（例: `'calculator'`） – LLM はその特定のツールを呼び出す必要がある - + ### 無限ループの防止 -ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループに入るのを防ぎます。この挙動は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 +ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツールを繰り返し呼び出そうとして無限ループに入るのを防ぎます。この挙動は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 -- `'run_llm_again'`（デフォルト）– ツール結果で再度 LLM を実行 +- `'run_llm_again'`（デフォルト） – ツール結果を使って LLM を再実行 - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う -- `{ stopAtToolNames: ['my_tool'] }` – リスト内のいずれかのツールが呼ばれた時点で停止 +- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼ばれたら停止 - `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数 ```typescript @@ -171,6 +163,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 ca1ed24c..4b248002 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,20 +13,20 @@ 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 を切り替えることができます。 @@ -35,7 +35,7 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## トレーシング -トレーシングは既定で有効で、上記の OpenAI キーを使用します。 +トレーシングはデフォルトで有効で、上記の OpenAI キーを使用します。 別のキーは `setTracingExportApiKey()` で設定できます。 @@ -53,31 +53,31 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t title="トレーシングを無効化" /> -トレーシング機能の詳細は [トレーシング](/openai-agents-js/ja/guides/tracing) をご覧ください。 +トレーシング機能の詳細は、[トレーシング](/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)` を使用して、独自モジュール用の名前空間付きロガーを取得できます。 ### ログ内の機微データ -一部のログには user データが含まれる場合があります。以下の環境変数を設定して無効化できます。 +特定のログには ユーザー データが含まれる場合があります。以下の環境変数を設定して無効化できます。 -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 c0677a75..8d7ce517 100644 --- a/docs/src/content/docs/ja/guides/context.mdx +++ b/docs/src/content/docs/ja/guides/context.mdx @@ -6,10 +6,10 @@ 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 コンテキスト** ## ローカルコンテキスト @@ -21,9 +21,9 @@ import localContextExample from '../../../../../../examples/docs/context/localCo title="ローカルコンテキストの例" /> -単一の実行に参加するすべてのエージェント、ツール、フックは、同じ **タイプ** のコンテキストを使用する必要があります。 +単一の実行に参加するすべてのエージェント、ツール、フックは同じコンテキストの **型** を使用しなければなりません。 -ローカルコンテキストの用途: +ローカルコンテキストのユースケース: - 実行に関するデータ（ユーザー名、ID など） - ロガーやデータフェッチャーなどの依存関係 @@ -34,11 +34,11 @@ import localContextExample from '../../../../../../examples/docs/context/localCo **送信されません**。純粋にローカルであり、自由に読み書きできます。 -## エージェント/LLM のコンテキスト +## エージェント/LLM コンテキスト -LLM が呼び出されると、参照できるデータは会話履歴のみです。追加情報を利用可能にするには、次のいずれかの方法があります: +LLM が呼び出されるとき、参照できるデータは会話履歴のみです。追加情報を利用可能にするには次の方法があります。 -1. エージェントの `instructions` に追加する（システムまたはデベロッパーメッセージとも呼ばれます）。これは静的な文字列、またはコンテキストを受け取って文字列を返す関数にできます -2. `Runner.run()` を呼ぶ際の `input` に含める。これは instructions の手法に似ていますが、メッセージを [指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます -3. 関数ツール経由で公開し、LLM がオンデマンドでデータを取得できるようにする -4. リトリーバルや Web 検索ツールを使い、ファイル、データベース、または Web の関連データに基づいて応答を裏付ける +1. エージェントの `instructions`（システムまたは開発者メッセージ）に追加する。これは静的な文字列でも、コンテキストを受け取って文字列を返す関数でもかまいません +2. `Runner.run()` を呼び出す際の `input` に含める。これは instructions と似ていますが、メッセージを [指揮系統](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 af9906e4..24738ae9 100644 --- a/docs/src/content/docs/ja/guides/guardrails.mdx +++ b/docs/src/content/docs/ja/guides/guardrails.mdx @@ -7,42 +7,42 @@ import { Code } from '@astrojs/starlight/components'; import inputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-input.ts?raw'; import outputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-output.ts?raw'; -ガードレールは _並行して_ エージェント と動作し、ユーザー入力やエージェント出力に対するチェックと検証を行えます。たとえば、高価なモデルを呼び出す前に軽量なモデルをガードレールとして実行できます。悪意のある利用をガードレールが検知した場合、エラーを発生させて高コストなモデルの実行を停止できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力やエージェント出力に対するチェックとバリデーションを行えます。たとえば、コストの高いモデルを呼び出す前に軽量モデルをガードレールとして実行できます。ガードレールが不正使用を検知した場合、エラーを発生させて高コストなモデルの実行を停止できます。 ガードレールには 2 種類あります: -1. **入力ガードレール** は初回のユーザー入力に対して実行されます -2. **出力ガードレール** は最終的なエージェント出力に対して実行されます +1. **Input guardrails** は初回のユーザー入力に対して実行されます +2. **Output guardrails** は最終的なエージェント出力に対して実行されます ## 入力ガードレール -入力ガードレールは次の 3 段階で動作します: +入力ガードレールは次の 3 ステップで実行されます: -1. ガードレールはエージェントに渡されるのと同じ入力を受け取ります -2. ガードレール関数が実行され、[`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します +1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) に包んで返します 3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます > **Note** -> 入力ガードレールはユーザー入力を対象としているため、エージェントがワークフローの _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。これは、エージェントによって必要なガードレールが異なることが多いためです。 +> 入力ガードレールはユーザー入力向けであり、エージェントがワークフロー内の _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。これはエージェントごとに必要なガードレールが異なることが多いためです。 ## 出力ガードレール -出力ガードレールは次の 3 段階で動作します: +出力ガードレールは次の 3 ステップで実行されます: 1. ガードレールはエージェントが生成した出力を受け取ります -2. ガードレール関数が実行され、[`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) に包んで返します 3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます > **Note** -> 出力ガードレールは、エージェントがワークフローの _最後_ のエージェントである場合にのみ実行されます。リアルタイム音声での対話については[音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails)を参照してください。 +> 出力ガードレールは、エージェントがワークフロー内の _最後_ のエージェントである場合にのみ実行されます。リアルタイム音声対話については[音声エージェントの構築](/openai-agents-js/ja/guides/voice-agents/build#guardrails)を参照してください。 ## トリップワイヤー -ガードレールが失敗すると、トリップワイヤーによってそれを知らせます。トリップワイヤーが作動した時点で、ランナーは対応するエラーをスローし、実行を停止します。 +ガードレールが失敗すると、トリップワイヤーでそれを通知します。トリップワイヤーが発火した時点で、Runner は対応するエラーをスローして実行を停止します。 ## ガードレールの実装 -ガードレールは、`GuardrailFunctionOutput` を返す関数にすぎません。以下は、別のエージェントを内部で動かして、ユーザーが数学の宿題の助けを求めているかどうかを確認する最小の例です。 +ガードレールは `GuardrailFunctionOutput` を返す単なる関数です。以下は、内部で別のエージェントを実行して、ユーザーが数学の宿題の手伝いを求めているかどうかをチェックする最小の例です。 -1. `guardrailAgent` はガードレール関数の内部で使用されます +1. `guardrailAgent` はガードレール関数内で使用されます 2. ガードレール関数はエージェントの入力または出力を受け取り、結果を返します -3. 追加情報をガードレール結果に含めることができます +3. 追加情報をガードレールの結果に含めることができます 4. `agent` はガードレールが適用される実際のワークフローを定義します diff --git a/docs/src/content/docs/ja/guides/handoffs.mdx b/docs/src/content/docs/ja/guides/handoffs.mdx index f572483e..3b4265ed 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,13 +24,13 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r ### `handoff()` によるハンドオフのカスタマイズ -`handoff()` 関数を使うと、生成されるツールを調整できます。 +`handoff()` 関数で生成されるツールを調整できます。 - `agent` – ハンドオフ先のエージェント - `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き - `toolDescriptionOverride` – 既定のツール説明を上書き -- `onHandoff` – ハンドオフ時のコールバック。`RunContext` と、必要に応じてパース済み入力を受け取ります -- `inputType` – ハンドオフに期待する入力スキーマ +- `onHandoff` – ハンドオフ発生時のコールバック。`RunContext` と、必要に応じて解析済み入力を受け取ります +- `inputType` – ハンドオフで想定する入力スキーマ - `inputFilter` – 次のエージェントへ渡す履歴のフィルター ## 入力フィルター -既定では、ハンドオフは会話の全履歴を受け取ります。次のエージェントへ渡す内容を変更するには、`inputFilter` を指定します。 -共通ヘルパーは `@openai/agents-core/extensions` にあります。 +既定では、ハンドオフは会話履歴全体を受け取ります。次のエージェントへ渡す内容を変更するには、`inputFilter` を指定します。 +一般的なヘルパーは `@openai/agents-core/extensions` にあります。 ## 推奨プロンプト -プロンプトでハンドオフに言及すると、LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` 経由で推奨のプレフィックスを提供しています。 +プロンプトでハンドオフに言及すると、LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` を通じて推奨のプレフィックスを提供します。 -エンドツーエンドで動作する完全版は、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 +エンドツーエンドで動作するバージョンは、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 -## 長時間の承認対応 +## 長時間の承認への対応 -Human in the loop (人間の介入) フローは、サーバーを起動し続けることなく、長時間の中断が可能なように設計されています。リクエストを一旦終了して後で続行する必要がある場合、状態をシリアライズして後から再開できます。 +Human in the loop (人間の介入) フローは、サーバーを起動し続けることなく長時間中断できるように設計されています。リクエストをいったん終了して後で再開する必要がある場合は、状態をシリアライズして後から再開できます。 -`JSON.stringify(result.state)` を使って状態をシリアライズし、後から `RunState.fromString(agent, serializedState)` にシリアライズ済み状態を渡して再開できます。ここで `agent` は全体の実行をトリガーしたエージェントのインスタンスです。 +`JSON.stringify(result.state)` を使って状態をシリアライズし、後で `RunState.fromString(agent, serializedState)` にシリアライズした状態を渡すことで再開できます。`agent` は全体の実行をトリガーしたエージェントのインスタンスです。 この方法により、シリアライズした状態をデータベースやリクエストと一緒に保存できます。 -### 保留タスクのバージョニング +### 保留タスクのバージョン管理 -承認リクエストに長い時間がかかり、エージェント定義の有意義なバージョニングや Agents SDK のバージョン更新を行いたい場合は、パッケージエイリアスを用いて 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 74b72afd..d4b5725b 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -13,105 +13,109 @@ 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) は、アプリケーションが LLMs にツールとコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP のドキュメントより: -> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンなプロトコルです。AI アプリケーションにとっての USB‑C ポートのようなものだと考えてください。USB‑C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するように、MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。 +> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. -この SDK がサポートする MCP サーバーには 3 種類あります: +この SDK がサポートする MCP サーバーには 3 つのタイプがあります: -1. **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. リモート MCP サーバーツール** | -| 公開アクセス可能なリモートサーバーを使いつつツール呼び出しはローカルで | **2. Streamable HTTP** | -| ローカルで動作する Streamable HTTP サーバーを利用 | **2. Streamable HTTP** | -| OpenAI Responses 以外のモデルで任意の Streamable HTTP サーバーを利用 | **2. Streamable HTTP** | -| 標準入出力プロトコルのみをサポートするローカル MCP サーバーと連携 | **3. Stdio** | +| 必要なこと | 推奨オプション | +| ---------------------------------------------------------------------------------- | ----------------------- | +| 公開アクセス可能なリモートサーバーを既定の OpenAI Responses モデルで呼び出す | **1. Hosted MCP tools** | +| 公開アクセス可能なリモートサーバーを使うが、ツール呼び出しはローカルでトリガーする | **2. Streamable HTTP** | +| ローカルで稼働する Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| OpenAI-Responses 以外のモデルで任意の Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| 標準入出力プロトコルのみをサポートするローカル MCP サーバーで作業する | **3. Stdio** | -## 1. リモート MCP サーバーツール +## 1. Hosted MCP server tools -組み込みツール（Hosted）は、往復の処理全体をモデル側に寄せます。コードが MCP サーバーを呼ぶ代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルにストリーミングします。 +Hosted tools は往復処理全体をモデル内に押し込みます。あなたのコードが MCP サーバーを呼ぶ代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルへストリーミングします。 -以下は Hosted MCP ツールを使う最も簡単な例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡すことで、Hosted MCP サーバーツールを簡単に作成できます。 +以下は hosted MCP tools を使う最も簡単な例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡して、hosted MCP サーバーツールを作成できます。 -次に、`run` 関数（または独自にカスタマイズした `Runner` インスタンスの `run` メソッド）で Agent を実行できます: +その後、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行できます: - + 増分的な MCP の結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します: #### 任意の承認フロー -機微な操作では、個々のツール呼び出しに対する人間による承認を必須にできます。`requireApproval: 'always'` または、ツール名から `'never'`/`'always'` への詳細なマッピングオブジェクトを渡します。 +機微な操作では、個々のツール呼び出しに人間による承認を要求できます。`requireApproval: 'always'` か、ツール名を `'never'`/`'always'` にマッピングするきめ細かいオブジェクトを渡します。 -プログラムによってツール呼び出しの安全性を判定できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または拒否できます。人間の承認が必要な場合は、ローカルの関数ツールと同様に `interruptions` を使う [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) のアプローチを利用できます。 +ツール呼び出しが安全かどうかをプログラムで判断できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使用して承認または拒否できます。人間の承認が必要な場合は、ローカルの関数ツールと同様に `interruptions` を使った同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) アプローチを使用できます。 -### コネクタ対応の Hosted サーバー +### コネクタ対応の 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 + ストリーミング、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全に動作するサンプル（Hosted tools/Streamable HTTP/stdio + Streaming、HITL、onApproval）は、私たちの GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 -## 2. Streamable HTTP MCP サーバー +## 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 repository](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 -## 3. Stdio MCP サーバー +## 3. Stdio MCP servers -標準入出力のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` を初期化します: +標準入出力のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します: - + -## 知っておくと良いこと +## その他の知っておくべきこと -**Streamable HTTP** と **Stdio** サーバーでは、`Agent` の各実行時に利用可能なツールを検出するために `list_tools()` を呼び出す場合があります。この往復はレイテンシーを増やす可能性があり（特にリモートサーバー）、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡すことで結果をメモリにキャッシュできます。 +**Streamable HTTP** と **Stdio** の各サーバーでは、`Agent` の実行ごとに利用可能なツールを発見するために `list_tools()` を呼び出す場合があります。特にリモートサーバーでは、この往復によりレイテンシが増える可能性があるため、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡して、結果をメモリにキャッシュできます。 -ツール一覧が変わらないと確信できる場合のみ有効化してください。後でキャッシュを無効化するには、サーバーインスタンスで `invalidateToolsCache()` を呼び出します。 +ツール一覧が変わらないと確信できる場合にのみ有効化してください。後でキャッシュを無効化するには、サーバーインスタンスで `invalidateToolsCache()` を呼び出します。 ### ツールのフィルタリング -`createMCPToolStaticFilter` による静的フィルター、またはカスタム関数を渡して、各サーバーから公開するツールを制限できます。以下は両方のアプローチを組み合わせた例です: +`createMCPToolStaticFilter` による静的フィルター、またはカスタム関数を渡すことで、各サーバーから公開するツールを制限できます。両方のアプローチを示す統合例は次のとおりです: - + ## 参考資料 diff --git a/docs/src/content/docs/ja/guides/models.mdx b/docs/src/content/docs/ja/guides/models.mdx index d61d5704..d6b2919e 100644 --- a/docs/src/content/docs/ja/guides/models.mdx +++ b/docs/src/content/docs/ja/guides/models.mdx @@ -13,12 +13,12 @@ import runnerWithModelExample from '../../../../../../examples/docs/models/runne import gpt5DefaultModelSettingsExample from '../../../../../../examples/docs/models/gpt5DefaultModelSettings.ts?raw'; import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw'; -最終的にすべてのエージェントは LLM を呼び出します。SDK はモデルを 2 つの軽量なインターフェースの背後に抽象化します。 +最終的にすべての エージェント は LLM を呼び出します。SDK はモデルを 2 つの軽量なインターフェースの背後に抽象化します。 -- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して*1 回*のリクエストを行う方法を知っています +- [`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-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-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` にフォールバックします。 --- ## OpenAI プロバイダー -既定の `ModelProvider` は OpenAI API を使って名前を解決します。次の 2 つの明確に異なるエンドポイントをサポートします。 +既定の `ModelProvider` は OpenAI APIs を使って名前を解決します。2 つの異なるエンドポイントをサポートします。 -| API | 用途 | `setOpenAIAPI()` の呼び出し | -| ---------------- | ---------------------------------------------------------------------- | ------------------------------------ | -| Chat Completions | 標準的なチャット & 関数呼び出し | `setOpenAIAPI('chat_completions')` | -| Responses | ツール呼び出しや柔軟な出力に対応した新しいストリーミング優先の生成 API | `setOpenAIAPI('responses')` _(既定)_ | +| API | 用途 | `setOpenAIAPI()` の呼び出し | +| ---------------- | ------------------------------------------------------------------------ | --------------------------------------- | +| Chat Completions | 標準的なチャットと Function Calling | `setOpenAIAPI('chat_completions')` | +| Responses | 新しい ストリーミング ファーストの生成 API（ツール呼び出し、柔軟な出力） | `setOpenAIAPI('responses')` _(default)_ | ### 認証 @@ -82,7 +82,7 @@ node my-awesome-agent.js title="既定の OpenAI キーを設定" /> -ネットワーク設定をカスタムにする必要がある場合は、`setDefaultOpenAIClient(client)` で独自の `OpenAI` クライアントを差し込むこともできます。 +独自のネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` で独自の `OpenAI` クライアントを差し込むこともできます。 --- @@ -90,21 +90,21 @@ node my-awesome-agent.js `ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダーに依存しません。 -| フィールド | 型 | 注記 | +| フィールド | 型 | 備考 | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ | -| `temperature` | `number` | クリエイティビティと決定性のバランス | -| `topP` | `number` | nucleus サンプリング | -| `frequencyPenalty` | `number` | 繰り返し出現するトークンにペナルティを課す | -| `presencePenalty` | `number` | 新しいトークンの出現を促す | +| `temperature` | `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'` | トークン切り詰め戦略 | +| `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 などのテキスト冗長度 | +| `store` | `boolean` | 応答を永続化して取得/RAG ワークフローに利用 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 など向けの推論負荷 | +| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 など向けのテキスト冗長度 | -設定はどちらのレベルにも付与できます。 +設定はどちらのレベルにもアタッチできます。 @@ -114,14 +114,14 @@ node my-awesome-agent.js ## プロンプト -エージェントは `prompt` パラメーターで構成できます。これは、エージェントの挙動を制御するために使用すべき サーバー保存のプロンプト構成を示します。現在、このオプションは OpenAI の -[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみサポートされています。 +エージェントは `prompt` パラメーターで構成できます。これは エージェント の挙動を制御するために使用される、サーバーに保存されたプロンプト構成を示します。現在、このオプションは OpenAI の +[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合のみサポートされています。 -| フィールド | 型 | 注記 | -| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | プロンプトの一意識別子 | -| `version` | `string` | 使用したいプロンプトのバージョン | -| `variables` | `object` | プロンプトに代入する変数のキー/値ペア。値は文字列またはテキスト、画像、ファイルなどのコンテンツ入力タイプが使用可能 | +| フィールド | 型 | 備考 | +| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | プロンプトの一意な識別子 | +| `version` | `string` | 使用したいプロンプトのバージョン | +| `variables` | `object` | プロンプトに代入する変数のキー/値ペア。値は文字列、またはテキスト・画像・ファイルなどのコンテンツ入力タイプを使用可能 | -これによりトレースが [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/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 25c58f9a..438fade6 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、handoffs を備えた LLM です。つまり、オープンエンドなタスクに対して、LLM は自律的に計画し、ツールで行動してデータを取得し、ハンドオフでサブエージェントに委譲できます。たとえば、リサーチ用のエージェントには次のようなツールを備えられます。 +エージェントは、instructions、ツール、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたときに、LLM は自律的にタスクに取り組む計画を立て、ツールを使ってアクションを取りデータを取得し、ハンドオフを使ってサブエージェントにタスクを委任できます。たとえば、リサーチエージェントには次のようなツールを備えられます。 -- Web 検索でオンライン情報を見つける -- ファイル検索と取得で独自データや接続を横断して検索する -- コンピュータ操作で PC 上のアクションを取る +- Web 検索でオンラインの情報を見つける +- ファイル検索と取得でプロプライエタリデータや接続先を検索する +- コンピュータ操作でコンピュータ上のアクションを実行する - コード実行でデータ分析を行う -- 計画、レポート執筆などに長けた専門エージェントへのハンドオフ +- 計画立案やレポート作成などに長けた専門エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで LLM の知性に任せたいときに有効です。重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで LLM の知性に依拠したい場合に適しています。ここで重要な戦術は次のとおりです。 1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーターを明確にする -2. アプリを監視し反復する。問題点を見つけ、プロンプトを改善する -3. エージェントに内省と改善を許可する。ループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させる -4. 何でもできる汎用エージェントではなく、1 つのタスクに特化して卓越するエージェントを用意する -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。エージェントの学習とタスク性能の向上に役立つ +2. アプリをモニタリングし、反復改善する。問題が起きる箇所を把握し、プロンプトを改善する +3. エージェントに内省と改善を許可する。たとえばループで実行して自己批評させる、あるいはエラーメッセージを提供して改善させる +4. 何でもこなす汎用エージェントではなく、1 つのタスクに秀でた専門エージェントを用意する +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。エージェントの学習とタスク遂行能力の向上に役立つ ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の面でより決定論的かつ予測可能になります。一般的なパターンは以下です。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・パフォーマンスの観点で、より決定的で予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査可能な 適切な形式のデータ を生成する。たとえば、タスクをいくつかのカテゴリーに分類させ、そのカテゴリーに応じて次のエージェントを選ぶ -- あるエージェントの出力を次のエージェントの入力に変換して連鎖させる。ブログ記事執筆を「調査→アウトライン作成→本文執筆→批評→改善」といった一連のステップに分解する -- タスク実行エージェントを `while` ループで動かし、評価とフィードバックを行うエージェントと組み合わせ、評価者が一定の基準を満たしたと判断するまで繰り返す -- 複数のエージェントを並列実行する（例: `Promise.all` のような JavaScript の基本コンポーネントを利用）。相互依存のない複数タスクを高速化できる +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選ぶ +- 複数のエージェントを、前段の出力を次段の入力に変換する形で連鎖させる。ブログ記事作成のようなタスクを、リサーチ、アウトライン作成、本文作成、批評、改善といった一連のステップに分解する +- タスクを実行するエージェントとそれを評価してフィードバックするエージェントを `while` ループで実行し、評価者が基準を満たしたと判断するまで繰り返す +- 複数のエージェントを並列実行する（例: JavaScript の基本コンポーネントである `Promise.all`）。相互依存しない複数タスクがある場合の高速化に有用 [`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) に多数の code examples があります。 diff --git a/docs/src/content/docs/ja/guides/quickstart.mdx b/docs/src/content/docs/ja/guides/quickstart.mdx index c10b821c..0b63f68a 100644 --- a/docs/src/content/docs/ja/guides/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/quickstart.mdx @@ -7,11 +7,11 @@ import { Steps } from '@astrojs/starlight/components'; import { Code } from '@astrojs/starlight/components'; import quickstartExample from '../../../../../../examples/docs/quickstart/index.ts?raw'; -## プロジェクトのセットアップ +## プロジェクトセットアップ -1. プロジェクトを作成して npm を初期化します。一度だけ実行すれば大丈夫です +1. プロジェクトを作成して npm を初期化します。これは 1 回だけ必要です。 ```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 key を設定します。まだお持ちでない場合は、OpenAI API key を作成するために[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従ってください。 ```bash export OPENAI_API_KEY=sk-... ``` - あるいは、`setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、トレーシングには `setTracingExportApiKey('')` を使用できます。 - 詳細は[SDK の設定](/openai-agents-js/ja/guides/config)をご覧ください + 代わりに `setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、トレーシングには `setTracingExportApiKey('')` を使用できます。 + 詳細は[SDK の設定](/openai-agents-js/ja/guides/config)を参照してください。 -## はじめてのエージェントの作成 +## 最初のエージェントの作成 -エージェントは instructions と名前で定義します。 +エージェントは instructions と名前で定義されます。 ```typescript import { Agent } from '@openai/agents'; @@ -50,11 +50,11 @@ const agent = new Agent({ }); ``` -## はじめてのエージェントの実行 +## 最初のエージェントの実行 -`run` メソッドでエージェントを実行できます。開始したいエージェントと、それに渡したい入力の両方を渡して実行します。 +`run` メソッドを使用してエージェントを実行できます。開始したいエージェントと渡したい入力の両方を渡すことで実行をトリガーします。 -これにより、最終的な出力と、その実行中に実行されたアクションを含む実行結果が返されます。 +これにより、その実行中に実行された最終出力とアクションを含む実行結果が返されます。 ```typescript import { Agent, run } from '@openai/agents'; @@ -72,7 +72,7 @@ console.log(result.finalOutput); ## エージェントにツールを付与 -情報の参照やアクションの実行に使えるツールをエージェントに与えられます。 +エージェントにツールを与えて、情報の検索やアクションの実行を行わせることができます。 ```typescript import { Agent, tool } from '@openai/agents'; @@ -99,9 +99,9 @@ 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'; @@ -150,20 +150,21 @@ main().catch((err) => console.error(err)); ## まとめ -すべてを 1 つの完全な例にまとめましょう。これを `index.js` ファイルに配置して実行します。 +これまでの内容を 1 つの完全なサンプルにまとめましょう。これを `index.js` に配置して実行します。 - + -## トレースの表示 +## トレースの確認 -Agents SDK はトレースを自動生成します。これにより、エージェントの動作、呼び出したツール、引き継いだ相手などを確認できます。 +Agents SDK は自動でトレースを生成します。これにより、エージェントがどのように動作したか、どのツールを呼び出したか、どのエージェントにハンドオフしたかを確認できます。 -エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces)に移動します。 +エージェントの実行中に何が起きたかを確認するには、 +[OpenAI ダッシュボードの Trace viewer](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 8da18818..bb01ec3f 100644 --- a/docs/src/content/docs/ja/guides/release.mdx +++ b/docs/src/content/docs/ja/guides/release.mdx @@ -3,32 +3,32 @@ title: リリースプロセス description: Learn how we version and release the SDK and recent changes. --- -## バージョン管理 +## バージョニング -本プロジェクトは `0.Y.Z` 形式を用いた、やや修正を加えたセマンティック バージョニングに従います。先頭の `0` は SDK がまだ急速に進化中であることを示します。各コンポーネントの増分は次のとおりです。 +本プロジェクトは、`0.Y.Z` 形式のセマンティックバージョニングを少し変更したルールに従います。先頭の `0` は SDK がまだ急速に進化中であることを示します。各コンポーネントの増分は次のとおりです。 ## マイナー（`Y`）バージョン -ベータと明示されていない公開インターフェースへの**破壊的変更**がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 +ベータとマークされていない公開インターフェースに対する **破壊的変更** がある場合、マイナーバージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への変更には破壊的変更が含まれることがあります。 破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。 ## パッチ（`Z`）バージョン -以下のような破壊的でない変更の場合は `Z` を増やします。 +後方互換性のある変更では `Z` を増分します。 - バグ修正 - 新機能 - 非公開インターフェースの変更 - ベータ機能の更新 -## サブパッケージのバージョン管理 +## サブパッケージのバージョニング -メインの `@openai/agents` パッケージは、個別に利用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、いずれかのパッケージでバージョンが上がると他も同様に上がります。`1.0.0` への移行に伴い、この方針を変更する可能性があります。 +メインの `@openai/agents` パッケージは、独立して使用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、どれか 1 つのパッケージでバージョンが上がると他も同様に上がります。`1.0.0` へ移行する際にこの方針を変更する可能性があります。 ## 変更履歴 -各サブパッケージごとに変更履歴（changelog）を生成しており、何が変わったかを把握できます。変更がサブパッケージ内で発生している場合は、該当する変更履歴を参照してください。 +各サブパッケージについて、変更点を把握できるように変更履歴を生成しています。変更はサブパッケージ内で行われる場合があるため、詳細は該当する変更履歴を参照してください。 - [`@openai/agents`](https://github.com/openai/openai-agents-js/blob/main/packages/agents/CHANGELOG.md) - [`@openai/agents-core`](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/CHANGELOG.md) diff --git a/docs/src/content/docs/ja/guides/results.mdx b/docs/src/content/docs/ja/guides/results.mdx index 13540593..5dc9a66a 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -10,80 +10,80 @@ 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` を呼び出した場合は [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。ストリーミングの詳細は[ストリーミング](/openai-agents-js/ja/guides/streaming)も参照してください ## 最終出力 `finalOutput` プロパティには、最後に実行されたエージェントの最終出力が含まれます。この結果は次のいずれかです: -- `string` — `outputType` が定義されていないエージェントのデフォルト -- `unknown` — エージェントが出力タイプとして JSON スキーマを定義している場合。この場合、JSON はパースされていますが、型の検証は手動で行う必要があります -- `z.infer` — エージェントが出力タイプとして Zod スキーマを定義している場合。出力は自動的にこのスキーマに対してパースされます +- `string` — `outputType` が定義されていない任意のエージェントのデフォルト +- `unknown` — エージェントが出力タイプとして JSON スキーマを定義している場合。この場合、JSON は解析されていますが、型は手動で検証する必要があります +- `z.infer` — エージェントが出力タイプとして Zod スキーマを定義している場合。このスキーマに対して自動的に解析されます - `undefined` — エージェントが出力を生成しなかった場合（たとえば、出力を生成する前に停止した場合） -異なる出力タイプのハンドオフを使用している場合は、エージェントを作成する際に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 +異なる出力タイプを持つハンドオフを使用する場合は、エージェントを作成する際に `new Agent()` コンストラクタではなく `Agent.create()` メソッドを使用するべきです。 -これにより、SDK が考え得るすべてのハンドオフにわたって出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 +これにより、SDK があらゆるハンドオフにわたる出力タイプを推論し、`finalOutput` プロパティに対してユニオンタイプを提供できるようになります。 例: -## 次ターンへの入力 +## 次ターンの入力 -次ターン用の入力にアクセスする方法は 2 つあります: +次のターンで使用する入力にアクセスする方法は 2 つあります: - `result.history` — あなたの入力とエージェントの出力の両方のコピーを含みます -- `result.output` — エージェント実行全体の出力を含みます +- `result.output` — エージェントのフル実行の出力を含みます -`history` は、チャット風のユースケースで完全な履歴を維持するのに便利です: +`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` がトリガーされることがあります。その場合、`interruptions` は中断を引き起こした `ToolApprovalItem`s の配列になります。中断の扱い方については、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)を確認してください。 +エージェントで `needsApproval` を使用している場合、続行前に処理する必要がある `interruptions` が `run` によってトリガーされることがあります。その場合、`interruptions` は中断を引き起こした `ToolApprovalItem` の配列になります。中断への対処方法の詳細は、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)ガイドを参照してください。 ## その他の情報 -### 元レスポンス +### 元のレスポンス -`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 aed85d20..c7f57f4d 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -11,137 +11,133 @@ import chatLoopExample from '../../../../../../examples/docs/running-agents/chat import conversationIdExample from '../../../../../../examples/docs/running-agents/conversationId.ts?raw'; import previousResponseIdExample from '../../../../../../examples/docs/running-agents/previousResponseId.ts?raw'; -エージェント は単体では何もしません。`Runner` クラスまたは `run()` ユーティリティで それらを **実行** します。 +エージェントは単体では何もしません。`Runner` クラスまたは `run()` ユーティリティで実行します。 - + -カスタム Runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスで動作する `run()` ユーティリティも使えます。 +カスタム runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスで実行する `run()` ユーティリティも使えます。 -あるいは独自の Runner インスタンスを作成できます: +あるいは、独自の runner インスタンスを作成できます。 - + -エージェント を実行すると、最終出力と実行全履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 +エージェントの実行後、最終出力と実行の全履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 ## エージェントループ -Runner の run メソッドを使うときは、開始する エージェント と入力を渡します。入力は文字列（ユーザー メッセージとして扱われます）か、OpenAI Responses API のアイテムである入力アイテムの一覧のいずれかです。 +Runner の run メソッドでは、開始するエージェントと入力を渡します。入力は文字列（ユーザーからのメッセージと見なされます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。 -Runner は次のループを実行します: +runner は次のループを実行します。 -1. 現在の入力で現在の エージェント のモデルを呼び出す -2. LLM の応答を確認する - - **最終出力** → 返す - - **ハンドオフ** → 新しい エージェント に切り替え、蓄積した会話履歴を保持し、1 に戻る - - **ツール呼び出し** → ツールを実行し、その結果を会話に追加して、1 に戻る -3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を送出する +1. 現在の入力で現在のエージェントのモデルを呼び出す +2. LLM 応答を検査する + - **Final output** → 返す + - **Handoff** → 新しいエージェントに切り替え、蓄積された会話履歴は保持し、1 に戻る + - **Tool calls** → ツールを実行し、その結果を会話に追加して、1 に戻る +3. `maxTurns` に到達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローする ### Runner のライフサイクル -アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシングオプションといったグローバル設定を保持します。まったく別の構成が必要な場合のみ別の `Runner` を作成してください。シンプルなスクリプトでは内部でデフォルト Runner を使う `run()` を呼ぶこともできます。 +アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシングなどのグローバル設定を保持します。完全に異なるセットアップが必要な場合のみ、別の `Runner` を作成してください。簡単なスクリプトなら、内部でデフォルト runner を使う `run()` を呼ぶこともできます。 ## 実行引数 -`run()` メソッドへの入力は、実行を開始する初期 エージェント、実行の入力、およびオプションのセットです。 +`run()` メソッドへの入力は、実行を開始する初期エージェント、実行の入力、および一連のオプションです。 -入力は、文字列（ユーザー メッセージとして扱われます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) の一覧、または [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` | +| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから届いたイベントを逐次発行します | +| `context` | – | すべての tool / ガードレール / handoff に転送されるコンテキストオブジェクト。詳しくは [コンテキスト管理](/openai-agents-js/ja/guides/context) | +| `maxTurns` | `10` | セーフティリミット。到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスロー | +| `signal` | – | キャンセル用の `AbortSignal` | ## ストリーミング -ストリーミング を使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリームが開始されると、`StreamedRunResult` は新しく生成されたすべての出力を含む、実行に関する完全な情報を保持します。`for await` ループでストリーミングイベントを反復処理できます。詳しくは[ストリーミング](/openai-agents-js/ja/guides/streaming)を参照してください。 +ストリーミングにより、LLM の実行中にストリーミングイベントを受け取れます。ストリーム開始後、`StreamedRunResult` には、生成された新しい出力を含む実行に関する完全な情報が含まれます。`for await` ループでストリーミングイベントを反復処理できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。 ## 実行設定 -独自の `Runner` インスタンスを作成する場合は、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` | すべてのスパンに添付する任意のメタデータ | +独自の `Runner` インスタンスを作成する場合、runner を構成するために `RunConfig` オブジェクトを渡せます。 + +| Field | Type | Purpose | +| --------------------------- | --------------------- | ---------------------------------------------------------------------------------------- | +| `model` | `string \| Model` | 実行中の **すべて** のエージェントで特定のモデルを強制する | +| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダー | +| `modelSettings` | `ModelSettings` | エージェント単位の設定を上書きするグローバルなチューニングパラメーター | +| `handoffInputFilter` | `HandoffInputFilter` | handoff を実行する際に入力アイテムを変換します（handoff 自体で既に定義されていない場合） | +| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | +| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | +| `tracingDisabled` | `boolean` | OpenAI のトレーシングを完全に無効化 | +| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、トレースから LLM/ツールの入出力を除外 | +| `workflowName` | `string` | Traces ダッシュボードに表示され、関連する実行をグルーピングするのに役立ちます | +| `traceId` / `groupId` | `string` | SDK に生成させず、トレースまたはグループ 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) を参照してください。 ### サーバー管理の会話 -OpenAI Responses API に会話履歴を保持させれば、毎ターンでローカルの全文書起こしを送信する必要がありません。長い会話や複数サービスの調整に便利です。詳細は[Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)を参照してください。 +OpenAI Responses API に会話履歴を保持させ、毎ターンでローカルの全文書きを送らないようにできます。長い会話や複数サービスの調整時に有用です。詳細は [会話状態ガイド](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 -OpenAI は、サーバーサイド状態を再利用する 2 つの方法を提供します: +OpenAI はサーバー側の状態を再利用する 2 つの方法を提供しています。 #### 1. 会話全体に対する `conversationId` -[Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) で一度会話を作成し、その ID を各ターンで再利用できます。SDK は新しく生成されたアイテムのみを自動的に含めます。 +[Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) で一度会話を作成し、その ID を毎ターン再利用できます。SDK は新しく生成されたアイテムのみを自動的に含めます。 #### 2. 直前のターンから続ける `previousResponseId` -最初から Responses API だけで始めたい場合は、前のレスポンスで返された ID を使って各リクエストを連結できます。これにより、会話リソースを作成せずにターン間でコンテキストを維持できます。 +いずれにせよ Responses API だけで始めたい場合、前回のレスポンスで返された ID を使って各リクエストを連結できます。これにより、会話リソースを作成せずにターン間のコンテキストを維持できます。 ## 例外 -SDK は捕捉可能な小さな集合のエラーを送出します: +SDK は、捕捉可能な少数のエラーをスローします。 - [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` に到達 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが不正な出力を生成（例: 形式不正な JSON、未知のツール） +- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが無効な出力を生成（例: 不正な JSON、未知のツール） - [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) – ガードレール違反 -- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールの実行失敗 -- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 関数ツール の呼び出しが失敗 -- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 構成または ユーザー 入力に基づいて送出されたエラー +- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールの実行が失敗 +- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 関数ツールの呼び出しのいずれかが失敗 +- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 構成やユーザー入力に基づくエラー -いずれも基底の `AgentsError` クラスを拡張しており、現在の実行状態にアクセスするための `state` プロパティを提供する場合があります。 +いずれもベースの `AgentsError` クラスを継承しており、現在の実行状態にアクセスするための `state` プロパティを提供することがあります。 -以下は `GuardrailExecutionError` を扱うコード例です: +以下は `GuardrailExecutionError` を処理するサンプルコードです。 -上の例を実行すると、次の出力が表示されます: +上記の例を実行すると、次の出力が表示されます。 ``` Guardrail execution failed: Error: Input guardrail failed to complete: Error: Something is wrong! @@ -152,6 +148,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 2e6ee5b5..747f20fd 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 は、実行および保留中のすべてのコールバックが完了すると解決されます。出力がもうないことを確実にするには、必ず待機してください。 ### すべてのイベントのリッスン -`for await` ループを使用して、到着した各イベントを検査できます。役立つ情報には、低レベルのモデルイベント、エージェントの切り替え、そして SDK 固有の実行情報が含まれます: +`for await` ループを使って、到着した各イベントを検査できます。役立つ情報には、低レベルなモデルイベント、エージェントの切り替え、SDK 固有の実行情報などがあります: -[the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照すると、プレーンテキストのストリームと元のイベントストリームの両方を出力する、完全なスクリプトが確認できます。 +両方、すなわちプレーンテキストストリームと元のイベントストリームを印字する完全なスクリプトは、[ストリーミングの code examples](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。 ## イベントタイプ -ストリームは 3 種類のイベントタイプを生成します: +ストリームは 3 種類のイベントタイプを返します: ### raw_model_stream_event @@ -118,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/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 df560062..e125f2b5 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,26 +10,26 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -ツールは、エージェント が **アクションを実行する** ことを可能にします。データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの使用までできます。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします: +ツールによって、エージェントは **アクションを実行する** ことができます。データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの操作まで可能です。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします。 -1. **組み込みツール（Hosted）** – OpenAI の サーバー 上でモデルと並行して実行 _(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_ -2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップして LLM が呼び出せるようにする -3. **ツールとしてのエージェント** – エージェント 全体を呼び出し可能なツールとして公開 -4. **ローカル MCP サーバー** – お使いのマシン上で動作する Model context protocol サーバーを接続 +1. **組み込みツール（Hosted）** – モデルと同じ OpenAI のサーバー上で動作します（Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成） +2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM から呼び出せるようにします +3. **エージェントをツールとして** – エージェント全体を呼び出し可能なツールとして公開します +4. **ローカル MCP サーバー** – 自身のマシンで動作する Model context protocol サーバーを接続します --- ## 1. 組み込みツール（Hosted） -`OpenAIResponsesModel` を使う場合、以下の組み込みツールを追加できます: +`OpenAIResponsesModel` を使用する場合、次の組み込みツールを追加できます。 -| ツール | 型文字列 | 目的 | -| ----------------------- | -------------------- | ----------------------------------------------- | -| Web search | `'web_search'` | インターネット検索 | -| File / retrieval search | `'file_search'` | OpenAI 上でホストされる ベクトルストア のクエリ | -| Computer use | `'computer'` | GUI 操作を自動化 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | -| Image generation | `'image_generation'` | テキストに基づいて画像を生成 | +| ツール | タイプ文字列 | 目的 | +| --------------------------- | -------------------- | ----------------------------------------- | +| Web 検索 | `'web_search'` | インターネット検索 | +| ファイル / リトリーバル検索 | `'file_search'` | OpenAI がホストするベクトルストアのクエリ | +| コンピュータ操作 | `'computer'` | GUI 操作の自動化 | +| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | +| 画像生成 | `'image_generation'` | テキストに基づく画像生成 | -正確なパラメーターセットは OpenAI Responses API に一致します。`rankingOptions` やセマンティックフィルターなどの高度なオプションは公式ドキュメントを参照してください。 +正確なパラメーターセットは OpenAI Responses API に一致します。`rankingOptions` やセマンティックフィルタなどの高度なオプションは公式ドキュメントを参照してください。 --- ## 2. 関数ツール -`tool()` ヘルパーを使うと、**任意** の関数をツールにできます。 +`tool()` ヘルパーを使うと、**あらゆる** 関数をツールにできます。 ### オプションリファレンス -| 項目 | 必須 | 説明 | -| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | いいえ | デフォルトは関数名（例: `get_weather`） | -| `description` | はい | LLM に表示される、明確で人間に読みやすい説明 | -| `parameters` | はい | Zod スキーマまたは 元 の JSON スキーマオブジェクトのいずれか。Zod パラメーターは自動的に **strict** モードを有効化 | -| `strict` | いいえ | `true`（デフォルト）の場合、引数が検証に通らなければ SDK はモデルエラーを返す。あいまいなマッチングにするには `false` に設定 | -| `execute` | はい | `(args, context) => string \| Promise`– ビジネスロジック本体。2 番目の引数は省略可能で、`RunContext` | -| `errorFunction` | いいえ | 内部エラーを ユーザー に見える文字列へ変換するためのカスタムハンドラー `(context, error) => string` | +| フィールド | 必須 | 説明 | +| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | いいえ | 省略時は関数名（例: `get_weather`）が使用されます | +| `description` | はい | LLM に提示される明確で人間が読める説明 | +| `parameters` | はい | Zod スキーマまたは元の JSON スキーマオブジェクトのいずれか。Zod の parameters を使用すると自動的に **strict** モードが有効になります | +| `strict` | いいえ | `true`（デフォルト）の場合、引数が検証に失敗すると SDK はモデルエラーを返します。あいまいなマッチングを許可するには `false` に設定します | +| `execute` | はい | `(args, context) => string \| Promise`– ビジネスロジック。2 番目の引数は省略可能で、`RunContext` です | +| `errorFunction` | いいえ | 内部エラーをユーザーに見える文字列へ変換するためのカスタムハンドラー `(context, error) => string` | -### 非 strict な JSON スキーマツール +### 非 strict JSON スキーマツール -無効または部分的な入力をモデルに*推測*させたい場合は、元 の JSON スキーマ使用時に strict モードを無効化できます: +無効または部分的な入力をモデルに推測させたい場合は、元の JSON スキーマ使用時に strict モードを無効化できます。 --- -## 3. ツールとしてのエージェント +## 3. エージェントをツールとして -会話全体を完全にハンドオフせずに、ある エージェント に別の エージェント を*支援*させたい場合は、`agent.asTool()` を使います: +会話全体を完全にハンドオフせず、別のエージェントを支援に使いたい場合があります。`agent.asTool()` を使用します。 -内部的に SDK は次を行います: +内部的に SDK は次を行います。 - 単一の `input` パラメーターを持つ関数ツールを作成 - ツール呼び出し時にその入力でサブエージェントを実行 -- 最後のメッセージ、または `customOutputExtractor` で抽出した出力を返す +- 最後のメッセージ、または `customOutputExtractor` で抽出された出力を返却 -エージェントをツールとして実行する場合、Agents SDK はデフォルト設定の runner を作成し、関数の実行内でそのエージェントを実行します。`runConfig` や `runOptions` のプロパティを指定したい場合は、`asTool()` メソッドに渡して runner の動作をカスタマイズできます。 +エージェントをツールとして実行すると、Agents SDK はデフォルト設定でランナーを作成し、関数実行内でそのランナーを使ってエージェントを実行します。`runConfig` や `runOptions` の任意のプロパティを指定したい場合は、`asTool()` メソッドに渡してランナーの動作をカスタマイズできます。 --- ## 4. MCP サーバー -[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) サーバー経由でツールを公開し、エージェント に接続できます。たとえば、`MCPServerStdio` を使って stdio MCP サーバーを起動・接続できます: +[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) を参照してください。MCP サーバーツール統合の包括的なガイドをお探しの場合は、[MCP 連携](/openai-agents-js/ja/guides/mcp) を参照してください。 +完全な例については [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) を参照してください。MCP サーバーツール連携の包括的なガイドをお探しの場合は、[MCP 連携](/openai-agents-js/ja/guides/mcp) を参照してください。 --- ## ツール使用時の挙動 -モデルがツールをいつどのように使用するべきか（`tool_choice`、`toolUseBehavior` など）の制御については、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください。 +モデルがいつどのようにツールを使用すべきかを制御する方法は、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください（`tool_choice`、`toolUseBehavior` など）。 --- ## ベストプラクティス -- **短く明確な説明** – ツールが*何をするか*、*いつ使うか*を記述 -- **入力を検証** – 可能な限り Zod スキーマで厳格な JSON 検証を実施 -- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返すべきで、throw しない -- **ツールは単一責務** – 小さく合成しやすいツールはモデルの推論を向上 +- **短く明示的な説明** – ツールが何をするのか、いつ使うのかを説明する +- **入力の検証** – 可能であれば Zod スキーマで厳密な JSON 検証を行う +- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返すだけにする（throw しない） +- **ツールごとに単一責務** – 小さく合成可能なツールはモデルの推論精度を高める --- ## 次のステップ - [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) について学ぶ -- ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 -- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツールタイプの TypeDoc リファレンスを読む +- ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加する +- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツールタイプの TypeDoc リファレンスを参照する diff --git a/docs/src/content/docs/ja/guides/tracing.mdx b/docs/src/content/docs/ja/guides/tracing.mdx index 97f8a358..9fbb3802 100644 --- a/docs/src/content/docs/ja/guides/tracing.mdx +++ b/docs/src/content/docs/ja/guides/tracing.mdx @@ -7,24 +7,24 @@ import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw'; -Agents SDK には組み込みのトレーシングがあり、エージェントの実行中に発生するイベントを包括的に記録します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントまでを収集します。[Traces ダッシュボード](https://platform.openai.com/traces)を使うと、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みのトレーシングが含まれており、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントも含まれます。[Traces ダッシュボード](https://platform.openai.com/traces) を使用して、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 ## エクスポートループのライフサイクル -多くの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。キューが溜まりすぎた場合はトレースはエクスポートされますが、定期的にはエクスポートされません。その代わり、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用して手動でトレースをエクスポートしてください。 +多くの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。トレースが大量にキューに溜まった場合はエクスポートされますが、定期的にはエクスポートされません。代わりに、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用してトレースを手動でエクスポートしてください。 -たとえば Cloudflare Worker では、コード全体を `try/catch/finally` ブロックでラップし、ワーカーが終了する前にトレースがエクスポートされるように `waitUntil` とともに force flush を使用します。 +たとえば Cloudflare Worker では、コード全体を `try/catch/finally` ブロックでラップし、`waitUntil` とあわせて強制フラッシュを使用して、ワーカーが終了する前にトレースがエクスポートされるようにします。 ` - - `group_id`: 同一会話の複数トレースを関連付けるための任意のグループ ID。例: チャットスレッドの ID + - `trace_id`: トレースの一意の ID。指定しない場合は自動生成。形式は `trace_<32_alphanumeric>` + - `group_id`: 任意のグループ ID。同じ会話からの複数のトレースを関連付けるために使用。例: チャットスレッド ID - `disabled`: True の場合、トレースは記録されない - - `metadata`: トレースの任意メタデータ -- **Spans** は開始時刻と終了時刻を持つ操作を表します。Spans には次があります: + - `metadata`: 任意のトレース用メタデータ +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります: - `started_at` と `ended_at` のタイムスタンプ - - 所属するトレースを表す `trace_id` - - この Span の親を指す `parent_id`（ある場合） - - `span_data`: Span に関する情報。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など + - 所属するトレースを示す `trace_id` + - 親スパンを指す `parent_id`（ある場合） + - スパンに関する情報である `span_data`。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成に関する情報など -## デフォルトのトレーシング +## 既定のトレーシング -デフォルトで SDK は次をトレースします: +デフォルトで、SDK は次をトレースします: -- `run()` または `Runner.run()` 全体を `Trace` でラップ -- エージェント実行ごとに `AgentSpan` でラップ -- LLM 生成は `GenerationSpan` でラップ -- 関数ツール呼び出しはそれぞれ `FunctionSpan` でラップ -- ガードレールは `GuardrailSpan` でラップ -- ハンドオフは `HandoffSpan` でラップ +- `run()` または `Runner.run()` 全体が `Trace` でラップされる +- エージェントが実行されるたびに `AgentSpan` でラップされる +- LLM の生成は `GenerationSpan` でラップされる +- 関数ツールの呼び出しはそれぞれ `FunctionSpan` でラップされる +- ガードレールは `GuardrailSpan` でラップされる +- ハンドオフは `HandoffSpan` でラップされる -デフォルトでは、トレース名は "Agent workflow" です。`withTrace` を使ってこの名前を設定するか、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを設定できます。 +デフォルトでは、トレース名は "Agent workflow" です。`withTrace` を使用してこの名前を設定できます。または、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを設定できます。 -加えて、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、他の宛先へトレースを送信できます（置き換え、または副次的な宛先）。 +さらに、[カスタムトレーシングプロセッサー](#custom-tracing-processors) を設定して、他の送信先へトレースを送ることもできます（置き換えまたは副次的送信先）。 ### 音声エージェントのトレーシング -`RealtimeAgent` と `RealtimeSession` をデフォルトの OpenAI Realtime API とともに使用している場合、`RealtimeSession` で `tracingDisabled: true` を設定するか、環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を使用して無効化しない限り、トレーシングは Realtime API 側で自動的に行われます。 +デフォルトの OpenAI Realtime API とともに `RealtimeAgent` と `RealtimeSession` を使用している場合、`RealtimeSession` で `tracingDisabled: true` を指定するか、環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を使用して無効化しない限り、トレーシングは Realtime API 側で自動的に行われます。 -詳細は[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents)を参照してください。 +詳しくは [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 -## 上位レベルのトレース +## 高レベルのトレース -複数の `run()` 呼び出しを単一のトレースにまとめたい場合があります。これはコード全体を `withTrace()` でラップすることで実現できます。 +`run()` への複数回の呼び出しを 1 つのトレースにまとめたい場合があります。その場合は、コード全体を `withTrace()` でラップします。 -1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります +1. `run` への 2 回の呼び出しが `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 -`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) によってそのデータの収集を無効化できます。 +`createGenerationSpan()` は LLM 生成の入出力を保存し、`createFunctionSpan()` は関数呼び出しの入出力を保存します。機微なデータを含む場合があるため、[`RunConfig.traceIncludeSensitiveData +`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) でその記録を無効化できます。 ## カスタムトレーシングプロセッサー トレーシングの高レベルなアーキテクチャは次のとおりです: -- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレースの作成を担い、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) からアクセスできます -- `TraceProvider` には [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) を設定し、トレース/スパンをバッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に送信します。エクスポーターはスパンとトレースをバッチで OpenAI のバックエンドにエクスポートします +- 初期化時に、グローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレースの作成を担当し、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) からアクセスできます +- `TraceProvider` は [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) で構成され、トレース/スパンをバッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に送信します。これがスパンとトレースを OpenAI のバックエンドへバッチエクスポートします -このデフォルト構成をカスタマイズして、別のバックエンドや追加のバックエンドへ送信したり、エクスポーターの動作を変更するには、次の 2 つの方法があります: +このデフォルト設定をカスタマイズして、別のバックエンドに送信したり、追加のバックエンドに送信したり、エクスポーターの動作を変更したりするには、次の 2 つの方法があります: -1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) は、トレースとスパンが準備でき次第受け取る**追加の**トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を行えます -2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) は、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換え**られます。これを行うと、OpenAI のバックエンドにトレースは送信されません。送信したい場合はその役割を持つ `TracingProcessor` を含める必要があります +1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) は、トレースやスパンが準備でき次第受け取る**追加の**トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理が可能になります +2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) は、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換え**られます。OpenAI のバックエンドにトレースを送信する `TracingProcessor` を含めない限り、トレースは OpenAI のバックエンドに送られません ## 外部トレーシングプロセッサー一覧 diff --git a/docs/src/content/docs/ja/guides/troubleshooting.mdx b/docs/src/content/docs/ja/guides/troubleshooting.mdx index f90a4b47..79fcacac 100644 --- a/docs/src/content/docs/ja/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ja/guides/troubleshooting.mdx @@ -3,39 +3,39 @@ title: トラブルシューティング description: Learn how to troubleshoot issues with the OpenAI Agents SDK. --- -## サポート環境 +## 対応環境 -OpenAI Agents SDK は次のサーバー環境でサポートされています。 +OpenAI Agents SDK は以下の サーバー 環境でサポートされています: - Node.js 22+ - Deno 2.35+ - Bun 1.2.5+ -### 限定サポート +### 制限付きサポート -- **Cloudflare Workers**: Agents SDK は Cloudflare Workers で使用できますが、現時点ではいくつかの制限があります。 - - 現在、SDK では `nodejs_compat` の有効化が必要です - - リクエストの終了時にトレースを手動でフラッシュする必要があります。詳細は [トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください。 - - Cloudflare Workers における `AsyncLocalStorage` のサポートが限定的なため、一部のトレースが正確でない場合があります - - 外向きの WebSocket 接続は fetch ベースのアップグレードを使用する必要があります（グローバルな `WebSocket` コンストラクタは使用不可）。Realtime では、`@openai/agents-extensions` の Cloudflare トランスポート（`CloudflareRealtimeTransportLayer`）を使用してください。 -- **Browsers**: - - ブラウザでは現在トレーシングはサポートされていません -- **v8 isolates**: - - 適切なブラウザ用ポリフィルを備えたバンドラを使えば v8 isolates 向けに SDK をバンドルできるはずですが、トレーシングは機能しません - - v8 isolates での動作は十分にテストされていません +- **Cloudflare Workers**: Agents SDK は Cloudflare Workers でも使用できますが、現時点では以下の制限があります: + - 現在 SDK は `nodejs_compat` を有効化する必要があります + - リクエストの最後でトレースを手動でフラッシュする必要があります。詳細は [トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください + - Cloudflare Workers の `AsyncLocalStorage` サポートが限定的なため、一部のトレースが正確でない可能性があります + - アウトバウンド WebSocket 接続は fetch ベースのアップグレードを使用する必要があります（グローバルの `WebSocket` コンストラクターは不可）。Realtime 用には `@openai/agents-extensions` の Cloudflare トランスポート（`CloudflareRealtimeTransportLayer`）を使用してください +- **ブラウザ**: + - ブラウザでは現在 トレーシング はサポートされていません +- **v8 アイソレート**: + - 適切なブラウザ向けポリフィルを備えたバンドラーを使用すれば v8 アイソレート向けに SDK をバンドルできるはずですが、トレーシングは機能しません + - v8 アイソレートでの広範な検証は行っていません -## デバッグログ +## デバッグ用ログ出力 -SDK で問題が発生している場合は、デバッグログを有効にすると詳細を確認できます。 +SDK で問題が発生している場合、デバッグ用ログ出力を有効にすると、内部で何が起きているかの詳細を確認できます。 -`DEBUG` 環境変数を `openai-agents:*` に設定してデバッグログを有効にします。 +`DEBUG` 環境変数を `openai-agents:*` に設定して、デバッグ用ログ出力を有効にします。 ```bash DEBUG=openai-agents:* ``` -また、SDK の特定部分にデバッグ範囲を絞れます。 +あるいは、SDK の特定部分にスコープを絞ってデバッグを有効化できます: -- `openai-agents:core` — SDK の主要な実行ロジック用 -- `openai-agents:openai` — OpenAI API 呼び出し用 -- `openai-agents:realtime` — Realtime Agents コンポーネント用 +- `openai-agents:core` — SDK のメイン実行ロジック向け +- `openai-agents:openai` — OpenAI API 呼び出し向け +- `openai-agents:realtime` — リアルタイムエージェント コンポーネント向け diff --git a/docs/src/content/docs/ja/guides/voice-agents.mdx b/docs/src/content/docs/ja/guides/voice-agents.mdx index f6ffdeab..29aa798b 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) -音声エージェントは OpenAI の speech-to-speech モデルを使用して、リアルタイムの音声チャットを提供します。これらのモデルは音声、テキスト、ツール呼び出しのストリーミングに対応しており、音声／電話でのカスタマーサポート、モバイルアプリの体験、音声チャットなどの用途に最適です。 +Voice Agents は OpenAI の speech-to-speech モデルを使って、リアルタイムの音声チャットを提供します。これらのモデルは音声、テキスト、ツール呼び出しのストリーミングに対応しており、音声/電話のカスタマーサポート、モバイルアプリの体験、音声チャットといった用途に最適です。 -Voice Agents SDK は [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) 用の TypeScript クライアントを提供します。 +Voice Agents SDK は [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) のための TypeScript クライアントを提供します。 ### 主な機能 -- WebSocket または WebRTC で接続 -- ブラウザでもバックエンド接続でも利用可能 -- 音声と割り込みのハンドリング +- WebSocket または WebRTC 経由で接続 +- ブラウザとバックエンド接続の両方で使用可能 +- 音声および割り込みのハンドリング - ハンドオフによるマルチエージェントのオーケストレーション -- ツール定義と呼び出し +- ツールの定義と呼び出し - モデル出力を監視するカスタムガードレール -- ストリーミングイベント用コールバック -- テキストと音声の両方のエージェントで同じコンポーネントを再利用 +- ストリーミングされたイベント用のコールバック +- テキストと音声のエージェントの両方で同じコンポーネントを再利用 -speech-to-speech モデルを使用することで、モデルが動作した後に文字起こしやテキストから音声への再変換を行う必要なく、モデルの音声処理能力をリアルタイムに活用できます。 +speech-to-speech モデルを使用することで、モデルが動作した後にテキストへ文字起こしして音声へ再変換する必要なく、モデルの音声処理能力をリアルタイムで活用できます。 -![Speech-to-speech モデル](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) +![音声対音声モデル](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) diff --git a/docs/src/content/docs/ja/guides/voice-agents/build.mdx b/docs/src/content/docs/ja/guides/voice-agents/build.mdx index 07a09508..6140d1d5 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,111 @@ import serverAgentExample from '../../../../../../../examples/docs/voice-agents/ import delegationAgentExample from '../../../../../../../examples/docs/voice-agents/delegationAgent.ts?raw'; import turnDetectionExample from '../../../../../../../examples/docs/voice-agents/turnDetection.ts?raw'; -## 音声の取り扱い +## 音声処理 -デフォルトの `OpenAIRealtimeWebRTC` のような一部のトランスポートレイヤーは、音声の入出力を自動で処理します。`OpenAIRealtimeWebSocket` のような別のトランスポートを使う場合は、セッションの音声を自分で処理する必要があります。 +デフォルトの `OpenAIRealtimeWebRTC` のようないくつかのトランスポート層は、音声の入出力を自動的に処理します。`OpenAIRealtimeWebSocket` のような他のトランスポートメカニズムでは、セッションの音声を自分で処理する必要があります。 ## セッション設定 -[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) のコンストラクターに追加オプションを渡すか、`connect(...)` を呼び出す際にオプションを渡すことで、セッションを設定できます。 +[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) の構築時、または `connect(...)` を呼び出す際に追加オプションを渡して、セッションを構成できます。 -これらのトランスポートレイヤーでは、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 +これらのトランスポート層では、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 -[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に存在しない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡した内容は `session` オブジェクトの一部としてそのまま渡されます。 +[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に対応するパラメーターがまだない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡したものは `session` オブジェクトの一部としてそのまま渡されます。 ## ハンドオフ -通常のエージェントと同様に、ハンドオフを使ってエージェントを複数のエージェントに分割し、それらをオーケストレーションすることで、エージェントのパフォーマンスを向上させ、問題の範囲を適切に絞り込めます。 +通常の エージェント と同様に、ハンドオフ を使って エージェント を複数に分割し、それらの間をオーケストレーションすることで エージェント のパフォーマンスを向上させ、問題の範囲を適切に絞り込むことができます。 -通常のエージェントと異なり、ハンドオフは Realtime Agents では少し異なる動作になります。ハンドオフが行われると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 +通常の エージェント と異なり、ハンドオフ は リアルタイムエージェント では少し動作が異なります。ハンドオフ が実行されると、進行中のセッションは新しい エージェント 構成で更新されます。このため、エージェント は進行中の会話履歴に自動的にアクセスでき、現在は入力フィルターが適用されません。 -さらに、これはハンドオフの一部として `voice` や `model` を変更できないことを意味します。接続できるのは他の Realtime Agents のみです。別のモデル、例えば `gpt-5-mini` のような推論モデルが必要な場合は、[ツールによる委譲](#delegation-through-tools) を使用できます。 +さらに、ハンドオフ の一部として `voice` や `model` を変更することはできません。また、接続できるのは他の リアルタイムエージェント のみです。別のモデル、たとえば `gpt-5-mini` のような推論モデルを使用する必要がある場合は、[ツールによる委譲](#delegation-through-tools) を利用できます。 ## ツール -通常のエージェントと同様に、Realtime Agents はツールを呼び出してアクションを実行できます。通常のエージェントで使用するのと同じ `tool()` 関数でツールを定義できます。 +通常の エージェント と同様に、リアルタイムエージェント はアクションを実行するためにツールを呼び出せます。通常の エージェント と同じ `tool()` 関数でツールを定義できます。 -Realtime Agents で使用できるのは関数ツールのみで、これらのツールは Realtime Session と同じ場所で実行されます。つまり、ブラウザで Realtime Session を実行している場合、ツールもブラウザで実行されます。より機密性の高いアクションを行う必要がある場合は、ツール内からバックエンド サーバーへ HTTP リクエストを送ることができます。 +リアルタイムエージェント で使用できるのは 関数ツール のみで、これらのツールは リアルタイムセッション と同じ場所で実行されます。つまり、ブラウザで リアルタイムセッション を実行している場合、ツールもブラウザで実行されます。より機微な操作を行う必要がある場合は、ツール内からバックエンド サーバー への HTTP リクエストを発行できます。 -ツールの実行中、エージェントはユーザーからの新しいリクエストを処理できません。体験を改善する方法の 1 つは、ツールを実行しようとしていることを事前にアナウンスするようにエージェントに指示したり、ツールの実行時間を稼ぐための特定のフレーズを話すようにすることです。 +ツールの実行中、エージェント は ユーザー からの新しいリクエストを処理できません。体験を改善する方法のひとつは、ツールを実行しようとしていることを エージェント にアナウンスさせるか、ツール実行のための時間を稼ぐ特定のフレーズを言わせることです。 ### 会話履歴へのアクセス -エージェントが特定のツールを呼び出した際の引数に加えて、Realtime Session が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[委譲のためのツール](#delegation-through-tools) を使う予定がある場合に便利です。 +エージェント が特定のツールを呼び出す際に渡した引数に加えて、リアルタイムセッション が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[委譲のためのツール](#delegation-through-tools) を使用する予定がある場合に有用です。 ### ツール実行前の承認 -`needsApproval: true` でツールを定義すると、エージェントはツールを実行する前に `tool_approval_requested` イベントを発行します。 +ツールを `needsApproval: true` で定義すると、エージェント はツールを実行する前に `tool_approval_requested` イベントを発行します。 -このイベントを監視して、ツール呼び出しを承認または拒否するための UI をユーザーに表示できます。 +このイベントをリッスンすることで、ツール呼び出しを承認または拒否するための UI を ユーザー に表示できます。 ## ガードレール -ガードレールは、エージェントの発話が一連のルールに違反していないか監視し、応答を即座に遮断する手段を提供します。これらのガードレールチェックはエージェントの応答の文字起こしに基づいて行われるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効）。 +ガードレール は、エージェント の発話が一連のルールに違反していないかを監視し、違反した場合に即座に応答を打ち切る方法を提供します。これらの ガードレール チェックは エージェント の応答の文字起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効）。 -提供されたガードレールは、モデル応答の返却と同時に非同期で実行されます。これにより、例えば「特定の禁止ワードへの言及」のような事前定義された分類トリガーに基づいて、応答を遮断できます。 +提供した ガードレール は、モデルの応答が返されるのと同時に非同期で実行され、たとえば「特定の禁止ワードに言及した」など、あらかじめ定義した分類トリガーに基づいて応答を打ち切ることができます。 -ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。イベントは、ガードレールをトリガーした `itemId` を含む `details` オブジェクトも提供します。 +ガードレール が作動すると、セッションは `guardrail_tripped` イベントを発行します。このイベントには、ガードレール をトリガーした `itemId` を含む `details` オブジェクトも含まれます。 -デフォルトでは、ガードレールは 100 文字ごと、または応答テキストの末尾で実行されます。音声で読み上げる方が通常は時間がかかるため、ほとんどの場合、ユーザーが聞く前にガードレールが違反を検知できます。 +デフォルトでは、ガードレール は 100 文字ごと、または応答テキストの末尾で実行されます。テキストを音声で話すには通常より時間がかかるため、ほとんどの場合、 ユーザー がそれを聞く前に ガードレール が違反を検出できます。 -この動作を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡してください。 +この動作を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡せます。 ## ターン検出 / 音声活動検出 -Realtime Session は、ユーザーが話しているタイミングを自動検出し、組み込みの [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使って新しいターンをトリガーします。 +リアルタイムセッション は、 ユーザー が発話しているタイミングを自動的に検出し、[Realtime 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 はエージェントの生成を割り込み、ユーザーに対して発話された内容の把握を適切に切り詰め、履歴を更新します。 +いずれの場合でも、リアルタイムセッション は、エージェント の生成の割り込み、 ユーザー に話した内容の切り詰め、履歴の更新の両方を処理します。 -エージェントへの接続に WebRTC を使用している場合、音声出力もクリアされます。WebSocket を使用している場合は、再生キューに入っている音声の再生を自分で停止する必要があります。 +エージェント への接続に WebRTC を使用している場合は、音声出力もクリアされます。WebSocket を使用している場合は、キューに入っている音声の再生を停止するなど、これを自分で処理する必要があります。 ## テキスト入力 -エージェントにテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用します。 +エージェント にテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用できます。 -エージェントとのやり取りに両方のモダリティをユーザーに有効化したい場合や、会話に追加のコンテキストを提供したい場合に便利です。 +これは、 ユーザー が エージェント と音声とテキストの両方のモダリティでやり取りできるようにしたい場合や、会話に追加のコンテキストを提供したい場合に有用です。 @@ -140,26 +140,26 @@ UI に「停止」ボタンを提供するなど、手動で割り込みを行 `RealtimeSession` は `history` プロパティで会話履歴を自動管理します。 -これを使って履歴をユーザーにレンダリングしたり、追加の処理を行えます。会話中は履歴が継続的に変化するため、`history_updated` イベントを監視できます。 +これを使って顧客向けに履歴をレンダリングしたり、追加の処理を行ったりできます。会話中はこの履歴が継続的に変化するため、`history_updated` イベントをリッスンできます。 -履歴を変更したい場合（メッセージを完全に削除する、文字起こしを更新するなど）は、`updateHistory` メソッドを使用します。 +履歴を変更したい場合（メッセージを完全に削除したり、文字起こしを更新したりなど）は、`updateHistory` メソッドを使用できます。 ### 制限事項 -1. 現在、関数ツールの呼び出しは後から更新/変更できません -2. 履歴のテキスト出力には、文字起こしとテキストモダリティが有効である必要があります -3. 割り込みによって切り詰められた応答には文字起こしがありません +1. 現時点では、関数ツール呼び出しを事後に更新/変更できません +2. 履歴でのテキスト出力には、文字起こしとテキスト モダリティの有効化が必要です +3. 割り込みにより切り詰められた応答には文字起こしがありません ## ツールによる委譲 ![ツールによる委譲](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) -会話履歴とツール呼び出しを組み合わせることで、より複雑なアクションの実行を別のバックエンド エージェントに委譲し、その結果をユーザーに返すことができます。 +会話履歴とツール呼び出しを組み合わせることで、会話を別のバックエンド エージェント に委譲して、より複雑なアクションを実行し、その結果を ユーザー に返すことができます。 -以下のコードは サーバー 上で実行されます。この例では Next.js の Server Actions を通じて実行します。 +以下のコードは サーバー 上で実行されます。この例では Next.js の server actions を通じて実行します。 diff --git a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx index 039ddc3a..9eac3336 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx @@ -28,7 +28,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 0. **プロジェクトの作成** - このクイックスタートでは、ブラウザで使える音声エージェントを作成します。新しいプロジェクトを試したい場合は、[`Next.js`](https://nextjs.org/docs/getting-started/installation) や [`Vite`](https://vite.dev/guide/installation.html) を試せます。 + このクイックスタートでは、ブラウザで使える音声エージェントを作成します。新規プロジェクトを試したい場合は、[`Next.js`](https://nextjs.org/docs/getting-started/installation) または [`Vite`](https://vite.dev/guide/installation.html) を利用できます。 ```bash npm create vite@latest my-project -- --template vanilla-ts @@ -40,11 +40,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t npm install @openai/agents zod@3 ``` - 代わりにスタンドアロンのブラウザ用パッケージである `@openai/agents-realtime` をインストールすることもできます。 + もしくはスタンドアロンのブラウザパッケージとして `@openai/agents-realtime` をインストールできます。 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 export OPENAI_API_KEY="sk-proj-...(your own key here)" @@ -59,9 +59,9 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - レスポンスにはトップレベルに "value" 文字列が含まれ、"ek\_" という接頭辞で始まります。このエフェメラルキーを使って後で WebRTC 接続を確立できます。このキーは短時間しか有効ではないため、再生成が必要になる点に注意してください。 + レスポンスにはトップレベルに "value" という文字列が含まれ、"ek\_" というプレフィックスで始まります。このエフェメラルキーを使用して、後で WebRTC 接続を確立できます。なお、このキーは短時間しか有効ではないため、再生成が必要になります。 -3. **はじめてのエージェントを作成** +3. **最初のエージェントの作成** 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`Agent`](/openai-agents-js/ja/guides/agents) の作成と非常によく似ています。 @@ -76,7 +76,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 4. **セッションの作成** - 通常のエージェントと異なり、音声エージェントは会話とモデルへの接続を継続的に扱う `RealtimeSession` の内部で常時実行・リスニングします。このセッションは、音声処理、中断、その他多くのライフサイクル機能も処理します。これらは後ほど説明します。 + 通常のエージェントと異なり、Voice Agent は会話とモデルへの継続的な接続を時間を通じて処理する `RealtimeSession` 内で常時稼働し、リスニングします。このセッションは音声処理や割り込み、その他多くのライフサイクル機能も扱います。これらについては後述します。 ```typescript import { RealtimeSession } from '@openai/agents/realtime'; @@ -86,7 +86,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` のコンストラクターは最初の引数として `agent` を受け取ります。このエージェントが、ユーザーが最初に対話できるエージェントになります。 + `RealtimeSession` のコンストラクターは最初の引数として `agent` を受け取ります。このエージェントが ユーザー が最初に対話できるエージェントになります。 5. **セッションへの接続** @@ -96,15 +96,15 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t await session.connect({ apiKey: 'ek_...(put your own key here)' }); ``` - これにより、ブラウザで 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 @@ -114,9 +114,9 @@ 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) 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 6eb866ff..01fcfa3a 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx @@ -28,46 +28,46 @@ import cloudflareTransportExample from '../../../../../../../examples/docs/exten ## デフォルトのトランスポート層 -### WebRTC 接続 +### WebRTC 経由での接続 -既定のトランスポート層は WebRTC を使用します。音声はマイクから録音され、自動的に再生されます。 +デフォルトのトランスポート層は WebRTC を使用します。音声はマイクから録音され、自動的に再生されます。 -独自のメディアストリームや audio 要素を使用するには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定します。 +独自のメディアストリームやオーディオ要素を使用するには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを渡します。 -### WebSocket 接続 +### WebSocket 経由での接続 -WebRTC の代わりに WebSocket 接続を使用するには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これはサーバーサイドのユースケース、たとえば Twilio で電話エージェントを構築する場合に有効です。 +WebRTC の代わりに WebSocket 接続を使用するには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これは サーバー サイドのユースケース、たとえば Twilio で電話エージェントを構築する場合に適しています。 -任意の録音/再生ライブラリを使用して、元 PCM16 音声バイトを処理します。 +録音/再生ライブラリを使用して、元の PCM16 オーディオバイトを処理してください。 #### Cloudflare Workers（workerd）に関する注意 -Cloudflare Workers やその他の workerd ランタイムでは、グローバルな `WebSocket` コンストラクターを使って外向きの WebSocket を開くことはできません。extensions パッケージの Cloudflare トランスポートを使用してください。これは内部で `fetch()` ベースのアップグレードを実行します。 +Cloudflare Workers およびその他の workerd ランタイムでは、グローバルな `WebSocket` コンストラクタを使用してアウトバウンド WebSocket を開くことはできません。extensions パッケージの Cloudflare トランスポートを使用してください。内部で `fetch()` ベースのアップグレードを実行します。 -### 独自トランスポート機構の構築 +### 独自のトランスポート機構の構築 -別の音声対音声 API を使いたい場合や、独自のカスタムトランスポート機構を持っている場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` イベントを発火することで独自に作成できます。 +別の音声対音声 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 — トランスポート層のみを使用 -自動ツール実行やガードレールなどが不要な場合は、接続と割り込みのみを管理する「薄い」クライアントとしてトランスポート層だけを使用できます。 +ツールの自動実行やガードレールなどが不要な場合は、接続と割り込みのみを管理する「薄いクライアント」として、トランスポート層だけを使用することもできます。 diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index c22604d0..6bc7aec1 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -19,32 +19,30 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概要 -[TypeScript 用 OpenAI Agents SDK](https://github.com/openai/openai-agents-js) は、 -抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できるようにします。これは以前のエージェント向け実験である -[Swarm](https://github.com/openai/swarm/tree/main) の本番運用向けアップグレードであり、[Python 版](https://github.com/openai/openai-agents-python) もあります。Agents SDK にはごく少数の基本コンポーネントがあります: +[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できるようにします。これは、エージェントに関する以前の実験である [Swarm](https://github.com/openai/swarm/tree/main) の本番対応版で、[available in Python](https://github.com/openai/openai-agents-python) でもあります。Agents SDK はごく少数の基本コンポーネントで構成されています: -- **エージェント**: instructions と tools を備えた LLMs -- **ハンドオフ**: 特定のタスクでエージェントが他のエージェントに委譲できる機能 -- **ガードレール**: エージェントへの入力を検証できる機能 +- **エージェント**: instructions と tools を備えた LLM +- **ハンドオフ**: 特定のタスクを他のエージェントに委譲する仕組み +- **ガードレール**: エージェントへの入力を検証できる仕組み -TypeScript と組み合わせることで、これらの基本コンポーネントだけでツールとエージェントの複雑な関係性を表現でき、学習コストをかけずに実アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグでき、評価やアプリ向けモデルのファインチューニングまで行えます。 +TypeScript と組み合わせることで、これらの基本コンポーネントは tools とエージェント間の複雑な関係を表現でき、急な学習曲線なしに実アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグできるだけでなく、評価やアプリケーション向けのモデルのファインチューニングも行えます。 ## Agents SDK を使う理由 -この SDK には 2 つの設計原則があります: +SDK の設計原則は次の 2 点です: -1. 使う価値のある十分な機能を備えつつ、学習が速いよう基本コンポーネントは少なく -2. すぐに使えて良好に動作しつつ、動作内容を細部までカスタマイズ可能に +1. 使う価値があるだけの機能を備えつつ、学習を素早くするために基本コンポーネントは少数にする +2. すぐに使えて優れた使い心地でありながら、挙動を細部までカスタマイズできる 主な機能は次のとおりです: -- **エージェントループ**: ツールの呼び出し、結果の LLM への送信、LLM の完了までのループを内蔵 -- **TypeScript ファースト**: 新しい抽象化を学ぶのではなく、言語機能でエージェントをオーケストレーションし連鎖可能 -- **ハンドオフ**: 複数エージェント間の調整と委譲を可能にする強力な機能 -- **ガードレール**: エージェントと並行して入力の検証やチェックを実行し、失敗時は早期に中断 -- **関数ツール**: 任意の TypeScript 関数をツール化し、自動スキーマ生成と Zod による検証を提供 +- **エージェントループ**: tools の呼び出し、結果の LLM への送信、LLM が完了するまでのループを処理 +- **TypeScript ファースト**: 新しい抽象化を学ぶ必要なく、言語機能でエージェントのオーケストレーションや連鎖を実現 +- **ハンドオフ**: 複数エージェント間の協調と委譲を可能にする強力な機能 +- **ガードレール**: エージェントと並行して入力のバリデーションやチェックを実行し、失敗時は早期終了 +- **関数ツール**: 任意の TypeScript 関数を tool に変換し、スキーマ生成と Zod によるバリデーションを自動化 - **トレーシング**: ワークフローの可視化・デバッグ・監視に加え、OpenAI の評価、ファインチューニング、蒸留ツールを活用可能 -- **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築可能 +- **リアルタイムエージェント**: 自動割り込み検出、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 ## インストール @@ -56,7 +54,7 @@ npm install @openai/agents zod@3 -(_実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) +(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/src/content/docs/ko/extensions/ai-sdk.mdx b/docs/src/content/docs/ko/extensions/ai-sdk.mdx index f85f822a..a18c2c2d 100644 --- a/docs/src/content/docs/ko/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ko/extensions/ai-sdk.mdx @@ -7,13 +7,13 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -기본적으로 Agents SDK는 Responses API 또는 Chat Completions API를 통해 OpenAI 모델과 함께 작동합니다. 그러나 다른 모델을 사용하려면, 이 어댑터를 통해 Agents SDK에 연결할 수 있는 다양한 지원 모델을 제공하는 [Vercel의 AI SDK](https://sdk.vercel.ai/)를 사용할 수 있습니다. +Agents SDK는 기본적으로 Responses API 또는 Chat Completions API를 통해 OpenAI 모델과 함께 작동합니다. 그러나 다른 모델을 사용하려면, 이 어댑터를 통해 [Vercel의 AI SDK](https://sdk.vercel.ai/)에서 지원하는 다양한 모델을 Agents SDK에 연결할 수 있습니다. ## 설정 @@ -25,13 +25,13 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk npm install @openai/agents-extensions ``` -2. [Vercel의 AI SDK](https://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'; @@ -47,19 +47,19 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk ## 예제 - + -## 제공자 메타데이터 전달 +## 프로바이더 메타데이터 전달 -메시지와 함께 제공자별 옵션을 보내야 한다면 `providerMetadata`를 통해 전달하세요. 값은 기본 AI SDK 모델로 그대로 전달됩니다. 예를 들어 Agents SDK에서 다음 `providerData`는 +메시지에 프로바이더별 옵션을 전달해야 하는 경우 `providerMetadata`를 통해 전달하세요. 값은 내부 AI SDK 모델로 그대로 전달됩니다. 예를 들어, Agents SDK에서 다음과 같은 `providerData`는 ```ts providerData: { @@ -71,7 +71,7 @@ providerData: { } ``` -AI SDK 통합을 사용할 때 다음과 같이 됩니다 +AI SDK 통합을 사용할 때 다음과 같이 변환됩니다 ```ts providerMetadata: { diff --git a/docs/src/content/docs/ko/extensions/cloudflare.mdx b/docs/src/content/docs/ko/extensions/cloudflare.mdx index a9cf202a..d3dfde38 100644 --- a/docs/src/content/docs/ko/extensions/cloudflare.mdx +++ b/docs/src/content/docs/ko/extensions/cloudflare.mdx @@ -6,31 +6,31 @@ description: Connect your Agents SDK agents from Cloudflare Workers/workerd usin import { Aside, Steps, Code } from '@astrojs/starlight/components'; import cloudflareBasicExample from '../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw'; -Cloudflare Workers 및 기타 workerd 런타임에서는 전역 `WebSocket` 생성자를 사용해 아웃바운드 WebSocket을 열 수 없습니다. 이러한 환경에서 실시간 에이전트를 간단히 연결할 수 있도록, extensions 패키지는 내부적으로 `fetch()` 기반 업그레이드를 수행하는 전용 전송 방식을 제공합니다. +Cloudflare Workers 및 기타 workerd 런타임은 전역 `WebSocket` 생성자를 사용해 아웃바운드 WebSocket을 열 수 없습니다. 이러한 환경에서 Realtime Agents 연결을 단순화하기 위해, 확장 패키지는 내부적으로 `fetch()` 기반 업그레이드를 수행하는 전용 전송 방식을 제공합니다. ## 설정 -1. **extensions 패키지를 설치하세요.** +1. **확장 패키지를 설치합니다.** ```bash npm install @openai/agents-extensions ``` -2. **전송 방식을 생성하고 세션에 연결하세요.** +2. **전송 방식을 생성하고 세션에 연결합니다.** -3. **`RealtimeSession`을(를) 연결하세요.** +3. **`RealtimeSession`을 연결합니다.** ```typescript await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' }); @@ -40,6 +40,6 @@ Cloudflare Workers 및 기타 workerd 런타임에서는 전역 `WebSocket` 생 ## 참고 사항 -- Cloudflare 전송 방식은 내부적으로 `Upgrade: websocket`과 함께 `fetch()`를 사용하며, 소켓의 `open` 이벤트를 기다리지 않아서 workerd API와 동작이 일치합니다 -- 이 전송 방식을 사용할 때도 모든 `RealtimeSession` 기능(도구, 가드레일 등)은 평소와 동일하게 작동합니다 +- Cloudflare 전송 방식은 내부적으로 `Upgrade: websocket`이 포함된 `fetch()`를 사용하며, 소켓 `open` 이벤트를 기다리지 않아 workerd API와 동작이 일치합니다 +- 이 전송 방식을 사용할 때도 모든 `RealtimeSession` 기능(tools, 가드레일 등)이 정상적으로 동작합니다 - 개발 중 상세 로그를 확인하려면 `DEBUG=openai-agents*`를 사용하세요 diff --git a/docs/src/content/docs/ko/extensions/twilio.mdx b/docs/src/content/docs/ko/extensions/twilio.mdx index 972d2f4f..08438619 100644 --- a/docs/src/content/docs/ko/extensions/twilio.mdx +++ b/docs/src/content/docs/ko/extensions/twilio.mdx @@ -7,14 +7,14 @@ 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/ko/guides/voice-agents)를 Twilio에 연결할 수 있습니다. 기본 Realtime Session 전송 방식을 `websocket` 모드로 사용하여 Twilio에서 오는 이벤트를 Realtime Session에 연결할 수 있습니다. 다만, 웹 기반 대화보다 통화는 자연스럽게 더 높은 지연을 유발하므로 올바른 오디오 포맷을 설정하고 인터럽션(중단 처리) 타이밍을 직접 조정해야 합니다. +Twilio는 전화 통화에서 생성되는 원시 오디오를 WebSocket 서버로 보내는 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)를 제공합니다. 이 설정을 사용하면 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 Twilio에 연결할 수 있습니다. 기본 Realtime Session 전송을 `websocket` 모드로 사용해 Twilio에서 오는 이벤트를 Realtime Session에 연결할 수 있습니다. 다만, 웹 기반 대화보다 전화 통화는 자연스럽게 지연이 더 크므로 올바른 오디오 포맷을 설정하고 인터럽션(중단 처리) 타이밍을 조정해야 합니다. -설정을 더 쉽게 하기 위해, 인터럽션 처리와 오디오 포워딩을 포함하여 Twilio와의 연결을 처리하는 전용 전송 레이어를 제공합니다. +설정 경험을 개선하기 위해, Twilio와의 연결을 처리하고 인터럽션 및 오디오 전달까지 처리하는 전용 전송 레이어를 제공합니다. @@ -22,21 +22,20 @@ Twilio는 전화 통화의 원시 오디오를 WebSocket 서버로 전송하는 -1. **Twilio 계정과 Twilio 전화번호를 준비합니다.** +1. **Twilio 계정과 Twilio 전화번호를 보유하고 있는지 확인하세요.** -2. **Twilio로부터 이벤트를 수신할 수 있는 WebSocket 서버를 설정합니다.** +2. **Twilio에서 오는 이벤트를 수신할 WebSocket 서버를 설정하세요.** - 로컬에서 개발 중이라면, [`ngrok`](https://ngrok.io/) 또는 - [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - 같은 로컬 터널을 구성하여 로컬 서버를 Twilio에서 접근 가능하게 해야 합니다. Twilio에 연결하기 위해 `TwilioRealtimeTransportLayer`를 사용할 수 있습니다. + 로컬에서 개발 중이라면, 이렇게 하려면 로컬 터널을 구성해야 합니다. 이렇게 하려면 로컬 터널을 구성해야 하며 [`ngrok`](https://ngrok.io/) 또는 + [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/)을 사용해 로컬 서버를 Twilio에서 접근 가능하게 만들어야 합니다. `TwilioRealtimeTransportLayer`를 사용해 Twilio에 연결할 수 있습니다. -3. **extensions 패키지를 설치하여 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' }); @@ -54,28 +53,28 @@ Twilio는 전화 통화의 원시 오디오를 WebSocket 서버로 전송하는 -`RealtimeSession`에서 기대되는 모든 이벤트와 동작은 도구 호출, 가드레일 등과 함께 정상적으로 작동합니다. 음성 에이전트와 `RealtimeSession`을 사용하는 방법에 대한 자세한 내용은 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 참고하세요. +`RealtimeSession`에서 기대하는 모든 이벤트와 동작(함수 호출, 가드레일 등)이 그대로 동작합니다. 음성 에이전트와 함께 `RealtimeSession`을 사용하는 방법에 대한 자세한 내용은 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 참조하세요. ## 팁 및 고려 사항 1. **속도가 핵심입니다.** - Twilio로부터 필요한 모든 이벤트와 오디오를 받으려면, WebSocket 연결에 대한 참조를 얻자마자 즉시 `TwilioRealtimeTransportLayer` 인스턴스를 생성하고 곧바로 `session.connect()`를 호출해야 합니다. + Twilio에서 필요한 모든 이벤트와 오디오를 수신하려면, WebSocket 연결에 대한 참조를 얻자마자 `TwilioRealtimeTransportLayer` 인스턴스를 생성하고 즉시 `session.connect()`를 호출해야 합니다. -2. **Twilio 원시 이벤트에 접근합니다.** +2. **Twilio 원문 이벤트에 접근하기.** - Twilio가 전송하는 원시 이벤트에 접근하려면, `RealtimeSession` 인스턴스에서 `transport_event` 이벤트를 리슨하면 됩니다. Twilio에서 오는 모든 이벤트는 타입이 `twilio_message`이며, 원시 이벤트 데이터가 담긴 `message` 속성을 포함합니다. + Twilio에서 전송되는 원문 이벤트에 접근하려면, `RealtimeSession` 인스턴스에서 `transport_event` 이벤트를 수신하면 됩니다. Twilio에서 오는 모든 이벤트의 타입은 `twilio_message`이며, 원문 이벤트 데이터가 담긴 `message` 프로퍼티를 포함합니다. -3. **디버그 로그를 확인합니다.** +3. **디버그 로그 확인하기.** - 내부 동작에 대한 더 많은 정보가 필요할 때가 있습니다. `DEBUG=openai-agents*` 환경 변수를 사용하면 Agents SDK의 모든 디버그 로그가 표시됩니다. 또는 `DEBUG=openai-agents:extensions:twilio*`로 Twilio 어댑터에 대한 디버그 로그만 활성화할 수 있습니다. + 문제 발생 시 동작을 더 자세히 파악하려면, 환경 변수 `DEBUG=openai-agents*`를 사용해 Agents SDK의 모든 디버그 로그를 확인할 수 있습니다. 또는 Twilio 어댑터에 대해서만 디버그 로그를 활성화하려면 `DEBUG=openai-agents:extensions:twilio*`를 사용하세요. ## 전체 예제 서버 -아래는 Twilio로부터 요청을 수신하고 이를 `RealtimeSession`으로 전달하는 WebSocket 서버의 엔드투엔드 예제입니다. +아래는 Twilio에서 요청을 수신하고 이를 `RealtimeSession`으로 전달하는 WebSocket 서버의 엔드 투 엔드 전체 예제입니다. diff --git a/docs/src/content/docs/ko/guides/agents.mdx b/docs/src/content/docs/ko/guides/agents.mdx index d077cc10..c7d1d554 100644 --- a/docs/src/content/docs/ko/guides/agents.mdx +++ b/docs/src/content/docs/ko/guides/agents.mdx @@ -15,132 +15,124 @@ 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의 주요 빌딩 블록입니다. **에이전트**는 다음으로 구성된 Large Language Model (LLM)입니다: +에이전트는 OpenAI Agents SDK의 주요 구성 요소입니다. **Agent** 는 다음으로 구성된 대규모 언어 모델(LLM)입니다: -- **Instructions** – 모델에게 _자신이 누구인지_ 와 *어떻게 응답해야 하는지*를 알려 주는 시스템 프롬프트 +- **Instructions** – 모델에게 _자기 정체_ 와 _응답 방식_ 을 알려주는 시스템 프롬프트 - **Model** – 호출할 OpenAI 모델과 선택적 모델 튜닝 매개변수 -- **Tools** – LLM이 작업을 수행하기 위해 호출할 수 있는 함수 또는 API 목록 +- **Tools** – 작업을 수행하기 위해 LLM이 호출할 수 있는 함수 또는 API 목록 - + -이 페이지의 나머지 부분에서는 모든 에이전트 기능을 자세히 살펴봅니다. +이 페이지의 나머지 부분에서는 모든 Agent 기능을 자세히 살펴봅니다. --- ## 기본 구성 -`Agent` 생성자는 단일 구성 객체를 받습니다. 가장 일반적으로 사용하는 속성은 다음과 같습니다. +`Agent` 생성자는 단일 구성 객체를 받습니다. 가장 자주 사용하는 속성은 아래와 같습니다. -| Property | Required | Description | -| --------------- | -------- | ------------------------------------------------------------------------------------------------------------ | -| `name` | yes | 짧고 사람이 읽을 수 있는 식별자 | -| `instructions` | yes | 시스템 프롬프트(문자열 **또는** 함수 – [동적 instructions](#dynamic-instructions) 참고) | -| `model` | no | 모델 이름 **또는** 사용자 정의 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 구현 | -| `modelSettings` | no | 튜닝 매개변수(temperature, top_p 등). 필요한 속성이 최상위에 없다면 `providerData` 아래에 포함할 수 있습니다 | -| `tools` | no | 모델이 호출할 수 있는 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 인스턴스 배열 | +| Property | Required | Description | +| --------------- | -------- | -------------------------------------------------------------------------------------------------------- | +| `name` | yes | 짧은 사람 친화적 식별자 | +| `instructions` | yes | 시스템 프롬프트(문자열 **또는** 함수 – [동적 instructions](#dynamic-instructions) 참고) | +| `model` | no | 모델 이름 **또는** 커스텀 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 구현 | +| `modelSettings` | no | 튜닝 매개변수(temperature, top_p 등). 필요한 속성이 최상위에 없다면 `providerData` 아래에 포함할 수 있음 | +| `tools` | no | 모델이 호출할 수 있는 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 인스턴스 배열 | - + --- ## 컨텍스트 -에이전트는 **컨텍스트 타입에 대해 제네릭**입니다 – 즉, `Agent`. _컨텍스트_ 는 `Runner.run()`에 전달하는 의존성 주입 객체입니다. 이는 모든 도구, 가드레일, 핸드오프 등으로 전달되며 상태를 저장하거나 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등)를 제공하는 데 유용합니다. +에이전트는 **컨텍스트 타입에 대해 제네릭** 입니다 – 예: `Agent`. _컨텍스트_ 는 여러분이 생성하여 `Runner.run()`에 전달하는 의존성 주입 객체입니다. 모든 도구, 가드레일, 핸드오프 등에 전달되며 상태 저장 또는 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등)를 제공하는 데 유용합니다. - + --- ## 출력 유형 -기본적으로 에이전트는 **plain text**(`string`)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 `outputType` 속성을 지정할 수 있습니다. SDK는 다음을 허용합니다: +기본적으로 에이전트는 **일반 텍스트**(`string`)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 `outputType` 속성을 지정하세요. SDK는 다음을 허용합니다: -1. [Zod](https://github.com/colinhacks/zod) 스키마 (`z.object({...})`) -2. JSON‑schema와 호환되는 객체 +1. [Zod](https://github.com/colinhacks/zod) 스키마(`z.object({...})`) +2. JSON‑schema 호환 객체 -`outputType`이 제공되면, SDK는 plain text 대신 자동으로 +`outputType`이 제공되면 SDK는 일반 텍스트 대신 자동으로 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용합니다. --- ## 멀티 에이전트 시스템 설계 패턴 -에이전트를 함께 구성하는 방법은 다양합니다. 실제 프로덕션 앱에서 자주 보는 두 가지 패턴은 다음과 같습니다: +에이전트를 함께 구성하는 방법은 여러 가지가 있습니다. 프로덕션 앱에서 자주 보는 두 가지 패턴은 다음과 같습니다: 1. **매니저(도구로서의 에이전트)** – 중앙 에이전트가 대화를 소유하고 도구로 노출된 특화 에이전트를 호출 -2. **핸드오프** – 초기 에이전트가 사용자의 요청을 파악한 후 전체 대화를 전문가에게 위임 +2. **핸드오프** – 초기 에이전트가 사용자의 요청을 식별하면 전체 대화를 전문가에게 위임 -이 접근 방식들은 상호 보완적입니다. 매니저는 가드레일이나 속도 제한을 한곳에서 강제할 수 있게 해주고, 핸드오프는 각 에이전트가 대화의 제어를 유지하지 않고 단일 작업에 집중할 수 있게 합니다. +이 접근 방식은 상호 보완적입니다. 매니저는 가드레일이나 레이트 리밋을 한 곳에서 적용할 수 있게 해주고, 핸드오프는 각 에이전트가 대화의 제어를 유지하지 않고 단일 작업에 집중할 수 있게 해줍니다. ### 매니저(도구로서의 에이전트) -이 패턴에서 매니저는 통제권을 넘기지 않으며—LLM이 도구를 사용하고 매니저가 최종 답을 요약합니다. 자세한 내용은 [도구](/openai-agents-js/ko/guides/tools#agents-as-tools)를 참고하세요. +이 패턴에서 매니저는 결코 제어권을 넘기지 않습니다 — LLM이 도구를 사용하고 매니저가 최종 답변을 요약합니다. 자세한 내용은 [도구 가이드](/openai-agents-js/ko/guides/tools#agents-as-tools)를 참조하세요. ### 핸드오프 -핸드오프에서는 분류 에이전트가 요청을 라우팅하지만, 일단 핸드오프가 발생하면 전문 에이전트가 최종 출력을 생성할 때까지 대화를 소유합니다. 이는 프롬프트를 짧게 유지하고 각 에이전트를 독립적으로 사고할 수 있게 해줍니다. 자세한 내용은 [핸드오프](/openai-agents-js/ko/guides/handoffs)를 참고하세요. +핸드오프에서는 분류 에이전트가 요청을 라우팅하지만, 한 번 핸드오프가 발생하면 전문가 에이전트가 최종 출력을 생성할 때까지 대화를 소유합니다. 이는 프롬프트를 짧게 유지하고 각 에이전트를 독립적으로 추론할 수 있게 해줍니다. 자세한 내용은 [핸드오프 가이드](/openai-agents-js/ko/guides/handoffs)에서 확인하세요. --- ## 동적 instructions -`instructions`는 문자열 대신 **함수**가 될 수 있습니다. 이 함수는 현재 `RunContext`와 에이전트 인스턴스를 받아 문자열 _또는_ `Promise`을 반환할 수 있습니다. +`instructions`는 문자열 대신 **함수**가 될 수 있습니다. 이 함수는 현재 `RunContext`와 Agent 인스턴스를 받고 문자열 _또는_ `Promise`을 반환할 수 있습니다. 동기 및 `async` 함수 모두 지원됩니다. --- -## 수명 주기 훅 +## 라이프사이클 훅 -고급 사용 사례에서는 이벤트를 구독하여 에이전트의 수명 주기를 관찰할 수 있습니다. 사용 가능한 항목은 [여기](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts)에 나열된 에이전트 훅 이벤트 이름을 참조하세요. +고급 사용 사례에서는 이벤트를 수신하여 Agent 라이프사이클을 관찰할 수 있습니다. 사용 가능한 항목은 [여기](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts)에 나열된 에이전트 훅 이벤트 이름을 참조하세요. --- ## 가드레일 -가드레일을 사용하면 사용자 입력과 에이전트 출력을 검증하거나 변환할 수 있습니다. `inputGuardrails` 및 `outputGuardrails` 배열을 통해 구성합니다. 자세한 내용은 [가드레일](/openai-agents-js/ko/guides/guardrails)을 참조하세요. +가드레일을 사용하면 사용자 입력과 에이전트 출력을 검증하거나 변환할 수 있습니다. `inputGuardrails` 및 `outputGuardrails` 배열을 통해 구성합니다. 자세한 내용은 [가드레일](/openai-agents-js/ko/guides/guardrails) 가이드를 참조하세요. --- -## 에이전트 복제/복사 +## 에이전트 클론/복사 -기존 에이전트를 약간만 수정한 버전이 필요하신가요? 완전히 새로운 `Agent` 인스턴스를 반환하는 `clone()` 메서드를 사용하세요. +기존 에이전트를 약간 수정한 버전이 필요하신가요? 완전히 새로운 `Agent` 인스턴스를 반환하는 `clone()` 메서드를 사용하세요. - + --- @@ -149,20 +141,20 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor 도구를 제공해도 LLM이 반드시 호출하는 것은 아닙니다. `modelSettings.tool_choice`로 도구 사용을 **강제**할 수 있습니다: 1. `'auto'`(기본값) – LLM이 도구 사용 여부를 결정 -2. `'required'` – 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을 다시 실행 -- `'stop_on_first_tool'` – 첫 번째 도구 결과를 최종 답으로 처리 +- `'run_llm_again'`(기본값) – 도구 결과로 LLM을 다시 실행 +- `'stop_on_first_tool'` – 첫 번째 도구 결과를 최종 답변으로 간주 - `{ stopAtToolNames: ['my_tool'] }` – 나열된 도구 중 하나가 호출되면 중지 -- `(context, toolResults) => ...` – 실행 종료 여부를 반환하는 사용자 정의 함수 +- `(context, toolResults) => ...` – 실행을 종료할지 여부를 반환하는 커스텀 함수 ```typescript const agent = new Agent({ @@ -175,6 +167,6 @@ const agent = new Agent({ ## 다음 단계 -- [에이전트 실행](/openai-agents-js/ko/guides/running-agents)을 학습하세요 -- [도구](/openai-agents-js/ko/guides/tools), [가드레일](/openai-agents-js/ko/guides/guardrails), [모델](/openai-agents-js/ko/guides/models)을 살펴보세요 -- 사이드바의 **@openai/agents** 아래 전체 TypeDoc 레퍼런스를 확인하세요 +- [에이전트 실행](/openai-agents-js/ko/guides/running-agents) 방법 알아보기 +- [도구](/openai-agents-js/ko/guides/tools), [가드레일](/openai-agents-js/ko/guides/guardrails), [모델](/openai-agents-js/ko/guides/models) 자세히 살펴보기 +- 사이드바의 **@openai/agents** 아래 전체 TypeDoc 레퍼런스 탐색 diff --git a/docs/src/content/docs/ko/guides/config.mdx b/docs/src/content/docs/ko/guides/config.mdx index 4c0e1e05..ee15b301 100644 --- a/docs/src/content/docs/ko/guides/config.mdx +++ b/docs/src/content/docs/ko/guides/config.mdx @@ -11,46 +11,46 @@ import setTracingExportApiKeyExample from '../../../../../../examples/docs/confi import setTracingDisabledExample from '../../../../../../examples/docs/config/setTracingDisabled.ts?raw'; import getLoggerExample from '../../../../../../examples/docs/config/getLogger.ts?raw'; -## API 키 및 클라이언트 +## 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()`로 설정할 수 있습니다. +별도의 키는 `setTracingExportApiKey()`로 설정할 수 있습니다: -트레이싱을 완전히 비활성화할 수도 있습니다. +트레이싱을 완전히 비활성화할 수도 있습니다: 트레이싱 기능에 대해 더 알아보려면 [트레이싱](/openai-agents-js/ko/guides/tracing)을 확인하세요. @@ -63,21 +63,21 @@ SDK는 디버그 로깅을 위해 [`debug`](https://www.npmjs.com/package/debug) 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/ko/guides/context.mdx b/docs/src/content/docs/ko/guides/context.mdx index 283f8b68..963feab4 100644 --- a/docs/src/content/docs/ko/guides/context.mdx +++ b/docs/src/content/docs/ko/guides/context.mdx @@ -6,18 +6,18 @@ 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'; -컨텍스트는 문맥에 따라 여러 의미로 쓰입니다. 다음 두 가지 주요 컨텍스트 범주가 있습니다: +컨텍스트는 과부하된 용어입니다. 신경 써야 할 컨텍스트에는 두 가지 주요 클래스가 있습니다: -1. 실행 중 코드가 접근할 수 있는 **로컬 컨텍스트**: 도구에 필요한 의존성이나 데이터, `onHandoff` 같은 콜백, 라이프사이클 훅 +1. 실행 중에 코드가 액세스할 수 있는 **로컬 컨텍스트**: 도구에 필요한 의존성과 데이터, `onHandoff` 같은 콜백, 라이프사이클 훅 2. 응답을 생성할 때 언어 모델이 볼 수 있는 **에이전트/LLM 컨텍스트** ## 로컬 컨텍스트 -로컬 컨텍스트는 `RunContext` 타입으로 표현됩니다. 상태나 의존성을 담을 임의의 객체를 만들고 이를 `Runner.run()`에 전달합니다. 모든 도구 호출과 훅은 `RunContext` 래퍼를 받아 해당 객체를 읽거나 수정할 수 있습니다. +로컬 컨텍스트는 `RunContext` 타입으로 표현됩니다. 상태나 의존성을 보관할 임의의 객체를 만들고 `Runner.run()`에 전달합니다. 모든 도구 호출과 훅은 해당 객체를 읽거나 수정할 수 있도록 `RunContext` 래퍼를 받습니다. -단일 실행에 참여하는 모든 에이전트, 도구, 훅은 동일한 컨텍스트의 **type**을 사용해야 합니다. +단일 실행에 참여하는 모든 에이전트, 도구, 훅은 동일한 **타입**의 컨텍스트를 사용해야 합니다. 로컬 컨텍스트는 다음과 같은 용도로 사용하세요: @@ -26,15 +26,15 @@ import localContextExample from '../../../../../../examples/docs/context/localCo - 헬퍼 함수 ## 에이전트/LLM 컨텍스트 -LLM이 호출될 때 볼 수 있는 데이터는 대화 히스토리에서만 옵니다. 추가 정보를 제공하려면 다음 옵션을 사용할 수 있습니다: +LLM이 호출될 때 볼 수 있는 데이터는 대화 기록에서만 옵니다. 추가 정보를 제공하려면 다음 옵션이 있습니다: -1. 에이전트 `instructions`에 추가합니다. 시스템 또는 개발자 메시지로도 알려져 있습니다. 이는 정적인 문자열이거나 컨텍스트를 받아 문자열을 반환하는 함수일 수 있습니다. -2. `Runner.run()` 호출 시 `input`에 포함합니다. 이는 instructions 기법과 유사하지만, 메시지를 [명령 체계](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)에서 더 낮은 위치에 둘 수 있습니다. +1. Agent `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. 리트리벌(retrieval) 또는 웹 검색 도구를 사용하여 파일, 데이터베이스, 웹의 관련 데이터에 근거해 응답을 생성합니다. +4. 리트리벌 또는 웹 검색 도구를 사용하여 파일, 데이터베이스, 웹의 관련 데이터에 기반해 응답을 보강합니다. diff --git a/docs/src/content/docs/ko/guides/guardrails.mdx b/docs/src/content/docs/ko/guides/guardrails.mdx index 39bf1fb7..3cad22b7 100644 --- a/docs/src/content/docs/ko/guides/guardrails.mdx +++ b/docs/src/content/docs/ko/guides/guardrails.mdx @@ -7,7 +7,7 @@ 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'; -가드레일은 에이전트와 함께 병렬로 실행되어, 사용자 입력 또는 에이전트 출력에 대한 검사와 검증을 수행할 수 있게 합니다. 예를 들어, 비용이 큰 모델을 호출하기 전에 경량 모델을 가드레일로 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 오류를 발생시켜 비용이 큰 모델의 실행을 중단할 수 있습니다. +가드레일은 에이전트와 병렬로 실행되어 사용자 입력 또는 에이전트 출력에 대한 점검과 유효성 검사를 수행할 수 있습니다. 예를 들어, 비용이 큰 모델을 호출하기 전에 경량 모델을 가드레일로 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 오류를 발생시켜 비용이 큰 모델의 실행을 중단할 수 있습니다. 가드레일에는 두 가지 종류가 있습니다: @@ -19,43 +19,43 @@ import outputGuardrailExample from '../../../../../../examples/docs/guardrails/g 입력 가드레일은 세 단계로 실행됩니다: 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) 오류가 발생합니다. > **참고** -> 입력 가드레일은 사용자 입력을 위한 것이므로, 워크플로에서 에이전트가 첫 번째 에이전트일 때만 실행됩니다. 가드레일은 에이전트 자체에 구성됩니다. 에이전트마다 요구되는 가드레일이 다른 경우가 많기 때문입니다. +> 입력 가드레일은 사용자 입력용이므로 워크플로에서 에이전트가 첫 번째일 때만 실행됩니다. 가드레일은 에이전트 자체에 구성합니다. 에이전트마다 필요한 가드레일이 다른 경우가 많기 때문입니다. ## 출력 가드레일 -출력 가드레일은 3단계로 실행됩니다: +출력 가드레일은 다음 3단계로 실행됩니다: 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) 오류가 발생합니다. > **참고** -> 출력 가드레일은 워크플로에서 에이전트가 마지막 에이전트일 때만 실행됩니다. 실시간 음성 상호작용은 [음성 에이전트 구축](/openai-agents-js/ko/guides/voice-agents/build#guardrails)을 참고하세요. +> 출력 가드레일은 워크플로에서 에이전트가 마지막일 때만 실행됩니다. 실시간 음성 상호작용의 경우 [음성 에이전트 구축](/openai-agents-js/ko/guides/voice-agents/build#guardrails)을 참고하세요. ## 트립와이어 -가드레일이 실패하면 트립와이어를 통해 이를 신호합니다. 트립와이어가 트리거되는 즉시 러너는 해당 오류를 던지고 실행을 중단합니다. +가드레일이 실패하면 트립와이어를 통해 이를 신호합니다. 트립와이어가 트리거되는 즉시 러너는 해당 오류를 던지고 실행을 중지합니다. ## 가드레일 구현 -가드레일은 `GuardrailFunctionOutput`을 반환하는 단순한 함수입니다. 아래는 내부적으로 다른 에이전트를 실행하여 사용자가 수학 숙제 도움을 요청하는지 확인하는 최소 예시입니다. +가드레일은 `GuardrailFunctionOutput`을 반환하는 간단한 함수입니다. 아래는 내부적으로 다른 에이전트를 실행하여 사용자가 수학 숙제 도움을 요청하는지 확인하는 최소 예시입니다. -출력 가드레일도 같은 방식으로 동작합니다. +출력 가드레일도 동일한 방식으로 동작합니다. 1. `guardrailAgent`는 가드레일 함수 내부에서 사용됩니다. diff --git a/docs/src/content/docs/ko/guides/handoffs.mdx b/docs/src/content/docs/ko/guides/handoffs.mdx index 53dfcb9d..d28ff4ff 100644 --- a/docs/src/content/docs/ko/guides/handoffs.mdx +++ b/docs/src/content/docs/ko/guides/handoffs.mdx @@ -10,23 +10,23 @@ import handoffInputExample from '../../../../../../examples/docs/handoffs/handof import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw'; import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw'; -핸드오프를 사용하면 한 에이전트가 대화의 일부를 다른 에이전트에 위임할 수 있습니다. 이는 서로 다른 에이전트가 특정 영역을 전문으로 할 때 유용합니다. 예를 들어 고객 지원 앱에서는 예약, 환불 또는 FAQ를 처리하는 에이전트를 둘 수 있습니다. +핸드오프는 한 에이전트가 대화의 일부를 다른 에이전트에 위임할 수 있게 합니다. 서로 다른 에이전트가 특정 영역에 특화되어 있을 때 유용합니다. 예를 들어 고객 지원 앱에서는 예약, 환불 또는 FAQ를 처리하는 에이전트를 둘 수 있습니다. -핸드오프는 LLM에게 도구로 표현됩니다. `Refund Agent`라는 에이전트로 핸드오프하는 경우, 도구 이름은 `transfer_to_refund_agent`가 됩니다. +핸드오프는 LLM에게 도구로 표현됩니다. `Refund Agent`라는 에이전트로 핸드오프할 경우 도구 이름은 `transfer_to_refund_agent`가 됩니다. ## 핸드오프 생성 -모든 에이전트는 `handoffs` 옵션을 허용합니다. 여기에는 다른 `Agent` 인스턴스나 `handoff()` 헬퍼가 반환하는 `Handoff` 객체를 포함할 수 있습니다. +모든 에이전트는 `handoffs` 옵션을 받습니다. 여기에는 다른 `Agent` 인스턴스나 `handoff()` 헬퍼가 반환하는 `Handoff` 객체를 담을 수 있습니다. ### 기본 사용 - + ### `handoff()`를 통한 핸드오프 커스터마이징 -`handoff()` 함수는 생성되는 도구를 조정할 수 있게 해줍니다. +`handoff()` 함수는 생성되는 도구를 세부 조정할 수 있게 합니다. -- `agent` – 핸드오프할 대상 에이전트 +- `agent` – 핸드오프 대상 에이전트 - `toolNameOverride` – 기본 `transfer_to_` 도구 이름 재정의 - `toolDescriptionOverride` – 기본 도구 설명 재정의 - `onHandoff` – 핸드오프 발생 시 콜백. `RunContext`와 선택적으로 파싱된 입력을 받음 @@ -36,28 +36,24 @@ 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`를 통해 권장 접두어를 제공합니다. - + diff --git a/docs/src/content/docs/ko/guides/human-in-the-loop.mdx b/docs/src/content/docs/ko/guides/human-in-the-loop.mdx index e58a9a32..2dd57b10 100644 --- a/docs/src/content/docs/ko/guides/human-in-the-loop.mdx +++ b/docs/src/content/docs/ko/guides/human-in-the-loop.mdx @@ -7,7 +7,7 @@ import { Aside, Code } from '@astrojs/starlight/components'; import humanInTheLoopExample from '../../../../../../examples/docs/human-in-the-loop/index.ts?raw'; import toolApprovalDefinition from '../../../../../../examples/docs/human-in-the-loop/toolApprovalDefinition.ts?raw'; -이 가이드는 SDK에 내장된 휴먼인더루프 (HITL) 지원을 사용하여 인간 개입에 따라 에이전트 실행을 일시 중지하고 재개하는 방법을 보여줍니다. +이 가이드는 SDK에 내장된 휴먼인더루프 (HITL) 지원을 사용하여 사람의 개입에 따라 에이전트 실행을 일시 중지하고 재개하는 방법을 보여줍니다. 현재 주요 사용 사례는 민감한 도구 실행에 대한 승인을 요청하는 것입니다. @@ -24,19 +24,19 @@ import toolApprovalDefinition from '../../../../../../examples/docs/human-in-the ### 흐름 -1. 에이전트가 도구(또는 여러 개)를 호출하기로 결정하면 `needsApproval` 을 평가하여 이 도구가 승인이 필요한지 확인합니다. -2. 승인이 필요한 경우, 에이전트는 승인이 이미 승인되었거나 거부되었는지 확인합니다. - - 승인이 승인되거나 거부되지 않은 경우, 도구는 도구 호출을 실행할 수 없다는 정적 메시지를 에이전트에 반환합니다. - - 승인/거부가 없는 경우 도구 승인 요청이 트리거됩니다. -3. 에이전트는 모든 도구 승인 요청을 수집하고 실행을 인터럽트합니다. -4. 인터럽션이 있는 경우, [실행 결과](/openai-agents-js/ko/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/ko/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단계부터 다시 시작됩니다 -## 예제 +## 예시 -아래는 터미널에서 승인을 요청하고 상태를 파일에 임시 저장하는 휴먼인더루프 (HITL) 흐름의 보다 완전한 예제입니다. +아래는 터미널에서 승인을 요청하고 상태를 파일에 임시로 저장하는 휴먼인더루프 (HITL) 흐름의 보다 완전한 예시입니다. -엔드 투 엔드로 동작하는 버전은 [전체 예제 스크립트](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)를 참고하세요. -## 장시간 승인 처리 +## 더 긴 승인 소요 시간 처리 -휴먼인더루프 흐름은 서버를 계속 실행하지 않고도 오랜 시간 동안 인터럽트 가능하도록 설계되었습니다. 요청을 종료하고 나중에 계속해야 하는 경우 상태를 직렬화하여 나중에 재개할 수 있습니다. +휴먼인더루프 (HITL) 흐름은 서버를 계속 실행하지 않고도 오랜 시간 동안 인터럽션될 수 있도록 설계되었습니다. 요청을 종료하고 나중에 계속해야 한다면 상태를 직렬화하여 이후에 재개할 수 있습니다. -상태는 `JSON.stringify(result.state)` 를 사용해 직렬화하고, 직렬화된 상태를 `RunState.fromString(agent, serializedState)` 에 전달하여 나중에 재개할 수 있습니다. 여기서 `agent` 는 전체 실행을 트리거한 에이전트 인스턴스입니다. +`JSON.stringify(result.state)` 를 사용해 상태를 직렬화하고, 직렬화된 상태를 `RunState.fromString(agent, serializedState)` 에 전달하여 나중에 재개할 수 있습니다. 여기서 `agent` 는 전체 실행을 트리거한 에이전트 인스턴스입니다. -이렇게 하면 직렬화된 상태를 데이터베이스나 요청과 함께 저장할 수 있습니다. +이 방식으로 직렬화된 상태를 데이터베이스 또는 요청과 함께 저장할 수 있습니다. -### 보류 중인 작업 버저닝 +### 보류 작업의 버전 관리 -승인 요청에 시간이 오래 걸리고 에이전트 정의를 의미 있게 버저닝하거나 Agents SDK 버전을 올릴 계획이라면, 패키지 별칭을 사용해 두 가지 버전의 Agents SDK 를 병행 설치하여 자체 분기 로직을 구현하는 것을 권장합니다. +승인 요청에 시간이 더 오래 걸리고 에이전트 정의를 의미 있게 버전 관리하거나 Agents SDK 버전을 올릴 계획이라면, 패키지 별칭을 사용하여 두 버전의 Agents SDK 를 병렬로 설치해 자체 분기 로직을 구현하는 것을 권장합니다. -실제로는 자체 코드에 버전 번호를 부여하고 이를 직렬화된 상태와 함께 저장하며, 역직렬화를 코드의 올바른 버전으로 안내하는 것을 의미합니다. +실제로는 코드에 자체 버전 번호를 부여하고 이를 직렬화된 상태와 함께 저장한 다음, 역직렬화를 코드의 올바른 버전으로 유도하는 것을 의미합니다. diff --git a/docs/src/content/docs/ko/guides/mcp.mdx b/docs/src/content/docs/ko/guides/mcp.mdx index b181b30b..c3dafc80 100644 --- a/docs/src/content/docs/ko/guides/mcp.mdx +++ b/docs/src/content/docs/ko/guides/mcp.mdx @@ -13,31 +13,31 @@ import streamableHttpExample from '../../../../../../examples/docs/mcp/streamabl import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; -[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io)은 애플리케이션이 LLM에 도구와 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP 문서에서 인용: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io)은 애플리케이션이 LLM에 도구와 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP 문서에서: > MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. 이 SDK가 지원하는 MCP 서버 유형은 세 가지입니다: -1. **호스티드 MCP 서버 도구** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp)가 도구로 사용하는 원격 MCP 서버 -2. **Streamable HTTP MCP 서버** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http)를 구현하는 로컬 또는 원격 서버 -3. **Stdio MCP 서버** – 표준 입력/출력을 통해 접근하는 서버(가장 간단한 옵션) +1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp)가 도구로 사용하는 원격 MCP 서버 +2. **Streamable HTTP MCP servers** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http)를 구현한 로컬 또는 원격 서버 +3. **Stdio MCP servers** – 표준 입출력을 통해 접근하는 서버(가장 간단한 옵션) 사용 사례에 따라 서버 유형을 선택하세요: -| 필요한 작업 | 추천 옵션 | -| -------------------------------------------------------------------- | ------------------------ | -| 공용으로 접근 가능한 원격 서버를 기본 OpenAI Responses 모델로 호출 | **1. 호스티드 MCP 도구** | -| 공용 원격 서버를 사용하되 도구 호출은 로컬에서 트리거 | **2. Streamable HTTP** | -| 로컬에서 실행 중인 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | -| OpenAI-Responses가 아닌 모델과 함께 어떤 Streamable HTTP 서버든 사용 | **2. Streamable HTTP** | -| 표준 I/O 프로토콜만 지원하는 로컬 MCP 서버와 작업 | **3. Stdio** | +| 필요한 사항 | 권장 옵션 | +| ------------------------------------------------------------------- | ----------------------- | +| 기본 OpenAI Responses 모델로 공개 접근 가능한 원격 서버 호출 | **1. Hosted MCP tools** | +| 공개 접근 가능한 원격 서버를 사용하지만 로컬에서 도구 호출을 트리거 | **2. Streamable HTTP** | +| 로컬에서 실행 중인 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | +| OpenAI Responses 이외의 모델과 함께 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | +| 표준 입출력 프로토콜만 지원하는 로컬 MCP 서버 사용 | **3. Stdio** | -## 1. 호스티드 MCP 서버 도구 +## 1. Hosted MCP 서버 도구 -호스티드 도구는 전체 라운드 트립을 모델 내부로 넣습니다. 코드가 MCP 서버를 호출하는 대신 OpenAI Responses API가 원격 도구 엔드포인트를 호출하고 결과를 모델로 스트리밍합니다. +호스티드 툴은 전체 라운드트립을 모델 내부로 밀어 넣습니다. 코드가 MCP 서버를 호출하는 대신 OpenAI Responses API가 원격 도구 엔드포인트를 호출하고 결과를 모델로 스트리밍합니다. -다음은 호스티드 MCP 도구를 사용하는 가장 간단한 예시입니다. 원격 MCP 서버의 라벨과 URL을 `hostedMcpTool` 유틸리티 함수에 전달하여 호스티드 MCP 서버 도구를 만들 수 있습니다. +다음은 호스티드 MCP 툴을 사용하는 가장 간단한 예시입니다. 원격 MCP 서버의 레이블과 URL을 `hostedMcpTool` 유틸리티 함수에 전달할 수 있으며, 이는 호스티드 MCP 서버 도구를 만들 때 유용합니다. @@ -45,7 +45,7 @@ import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.t -점진적인 MCP 결과를 스트리밍하려면 `Agent`를 실행할 때 `stream: true`를 전달하세요: +증분 MCP 결과를 스트리밍하려면 `Agent`를 실행할 때 `stream: true`를 전달하세요: -#### 승인 흐름(옵션) +#### 선택적 승인 흐름 민감한 작업의 경우 개별 도구 호출에 대해 사람의 승인을 요구할 수 있습니다. `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/ko/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/ko/guides/human-in-the-loop/) 접근 방식을 사용할 수 있습니다. ### 커넥터 기반 호스티드 서버 -호스티드 MCP는 OpenAI 커넥터도 지원합니다. `serverUrl` 대신 커넥터의 `connectorId`와 `authorization` 토큰을 전달하세요. 그러면 Responses API가 인증을 처리하고 커넥터의 도구를 호스티드 MCP 인터페이스를 통해 노출합니다. +호스티드 MCP는 OpenAI 커넥터도 지원합니다. `serverUrl` 대신 커넥터의 `connectorId`와 `authorization` 토큰을 전달하세요. 그러면 Responses API가 인증을 처리하고 호스티드 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)를 참고하세요. -완전히 동작하는 샘플(호스티드 도구/Streamable HTTP/stdio + 스트리밍, HITL, onApproval)은 GitHub 저장소의 [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp)에 있습니다. +완전히 동작하는 샘플(Hosted tools/Streamable HTTP/stdio + Streaming, HITL, onApproval)은 GitHub 리포지토리의 [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp)에 있습니다. ## 2. Streamable HTTP MCP 서버 -에이전트가 로컬 또는 원격의 Streamable HTTP MCP 서버와 직접 통신하는 경우 서버의 `url`, `name` 및 선택 설정과 함께 `MCPServerStreamableHttp`를 인스턴스화하세요: +에이전트가 로컬 또는 원격 Streamable HTTP MCP 서버와 직접 통신할 때는 서버의 `url`, `name` 및 선택적 설정으로 `MCPServerStreamableHttp`를 인스턴스화하세요: -생성자는 또한 `authProvider`, `requestInit`, `fetch`, `reconnectionOptions`, `sessionId` 같은 MCP TypeScript‑SDK 추가 옵션을 받습니다. 자세한 내용은 [MCP TypeScript SDK 저장소](https://github.com/modelcontextprotocol/typescript-sdk)와 문서를 참고하세요. +생성자는 `authProvider`, `requestInit`, `fetch`, `reconnectionOptions`, `sessionId`와 같은 추가 MCP TypeScript‑SDK 옵션도 받습니다. 자세한 내용은 [MCP TypeScript SDK 리포지토리](https://github.com/modelcontextprotocol/typescript-sdk)와 문서를 참조하세요. ## 3. Stdio MCP 서버 -표준 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/ko/guides/models.mdx b/docs/src/content/docs/ko/guides/models.mdx index a068fa8f..fe909b09 100644 --- a/docs/src/content/docs/ko/guides/models.mdx +++ b/docs/src/content/docs/ko/guides/models.mdx @@ -15,10 +15,10 @@ import setTracingExportApiKeyExample from '../../../../../../examples/docs/confi 모든 에이전트는 궁극적으로 LLM을 호출합니다. SDK는 두 가지 경량 인터페이스 뒤에 모델을 추상화합니다: -- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 특정 API에 대해 _한_ 번의 요청을 수행하는 방법을 알고 있음 +- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 특정 API에 대해 _하나의_ 요청을 수행하는 방법을 알고 있음 - [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 사람이 읽을 수 있는 모델 **이름**(예: `'gpt‑4o'`)을 `Model` 인스턴스로 해석 -일상적으로는 모델 **이름**과 때때로 `ModelSettings`만 사용합니다. +일상적인 작업에서는 일반적으로 모델 **이름**과 때때로 `ModelSettings`만 사용합니다. -더 낮은 지연 시간을 원한다면 [`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-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`로 되돌아갑니다. --- -## OpenAI 프로바이더 +## OpenAI 제공자 -기본 `ModelProvider`는 OpenAI API를 사용하여 이름을 해석합니다. 두 가지 구분된 엔드포인트를 지원합니다: +기본 `ModelProvider`는 OpenAI API를 사용해 이름을 해석합니다. 두 가지 구분되는 엔드포인트를 지원합니다: -| API | 사용처 | `setOpenAIAPI()` 호출 | -| ---------------- | ----------------------------------------------------- | --------------------------------------- | -| Chat Completions | 표준 채팅 및 함수 호출 | `setOpenAIAPI('chat_completions')` | -| Responses | 스트리밍 우선의 새로운 생성 API(툴 호출, 유연한 출력) | `setOpenAIAPI('responses')` _(default)_ | +| API | 사용법 | `setOpenAIAPI()` 호출 | +| ---------------- | ----------------------------------------------------- | -------------------------------------- | +| Chat Completions | 표준 채팅 및 함수 호출 | `setOpenAIAPI('chat_completions')` | +| Responses | 스트리밍 우선의 새로운 생성 API(툴 호출, 유연한 출력) | `setOpenAIAPI('responses')` _(기본값)_ | ### 인증 @@ -82,33 +82,33 @@ node my-awesome-agent.js title="기본 OpenAI 키 설정" /> -네트워킹 설정을 커스터마이즈해야 하는 경우 `setDefaultOpenAIClient(client)`를 통해 직접 `OpenAI` 클라이언트를 연결할 수도 있습니다. +맞춤 네트워킹 설정이 필요하다면 `setDefaultOpenAIClient(client)`를 통해 직접 `OpenAI` 클라이언트를 주입할 수도 있습니다. --- ## ModelSettings -`ModelSettings`는 OpenAI 매개변수를 반영하지만 공급자에 구애받지 않습니다. +`ModelSettings`는 OpenAI 매개변수를 반영하지만 제공자에 중립적입니다. | 필드 | 타입 | 비고 | | ------------------- | ------------------------------------------ | -------------------------------------------------------------------------- | -| `temperature` | `number` | 창의성 대 결정론 | +| `temperature` | `number` | 창의성 대 결정성 | | `topP` | `number` | 누클리어스 샘플링 | -| `frequencyPenalty` | `number` | 반복 토큰에 패널티 부여 | +| `frequencyPenalty` | `number` | 반복 토큰에 대한 패널티 | | `presencePenalty` | `number` | 새로운 토큰 장려 | -| `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [강제 도구 사용](/openai-agents-js/ko/guides/agents#forcing-tool-use) 참고 | +| `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [도구 사용 강제](/openai-agents-js/ko/guides/agents#forcing-tool-use) 참고 | | `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 등에서의 텍스트 상세 수준 | +| `store` | `boolean` | 검색/RAG 워크플로를 위해 응답을 지속 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 등에서의 리즈닝 강도 | +| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 등에서의 텍스트 장황도 | -설정은 어느 레벨이든 부착할 수 있습니다: +설정은 어느 레벨에서든 부착할 수 있습니다: -`Runner` 수준의 설정은 에이전트별 설정과 충돌 시 우선합니다. +`Runner` 레벨의 설정은 충돌하는 에이전트별 설정을 모두 재정의합니다. --- @@ -116,42 +116,42 @@ node my-awesome-agent.js 에이전트는 `prompt` 매개변수로 구성할 수 있으며, 이는 에이전트의 동작을 제어하기 위해 서버에 저장된 프롬프트 구성을 사용해야 함을 나타냅니다. 현재 이 옵션은 OpenAI [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용할 때만 지원됩니다. -| 필드 | 타입 | 비고 | -| ----------- | -------- | -------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | 프롬프트의 고유 식별자 | -| `version` | `string` | 사용하려는 프롬프트의 버전 | -| `variables` | `object` | 프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열 또는 텍스트, 이미지, 파일 등의 콘텐츠 입력 타입일 수 있음 | +| 필드 | 타입 | 비고 | +| ----------- | -------- | ----------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | 프롬프트의 고유 식별자 | +| `version` | `string` | 사용하려는 프롬프트의 버전 | +| `variables` | `object` | 프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열 또는 텍스트, 이미지, 파일 같은 콘텐츠 입력 타입이 될 수 있음 | -tools 또는 instructions와 같은 추가 에이전트 구성은 저장된 프롬프트에 구성했을 수 있는 값을 재정의합니다. +도구나 instructions 같은 추가 에이전트 구성은 저장된 프롬프트에서 구성한 값을 재정의합니다. --- -## 사용자 정의 모델 프로바이더 +## 커스텀 모델 제공자 -직접 프로바이더를 구현하는 것은 간단합니다 – `ModelProvider`와 `Model`을 구현하고 프로바이더를 `Runner` 생성자에 전달하세요: +직접 제공자를 구현하는 것은 간단합니다 – `ModelProvider`와 `Model`을 구현하고 제공자를 `Runner` 생성자에 전달하세요: --- -## 트레이싱 익스포터 +## 트레이싱 내보내기 -OpenAI 프로바이더를 사용할 때 API 키를 제공하여 자동 트레이스 내보내기를 옵트인할 수 있습니다: +OpenAI 제공자를 사용할 때 API 키를 제공하면 자동 트레이스 내보내기를 옵트인할 수 있습니다: 이는 [OpenAI 대시보드](https://platform.openai.com/traces)로 트레이스를 전송하며, 워크플로의 전체 실행 그래프를 확인할 수 있습니다. @@ -161,5 +161,5 @@ OpenAI 프로바이더를 사용할 때 API 키를 제공하여 자동 트레이 ## 다음 단계 - [에이전트 실행](/openai-agents-js/ko/guides/running-agents)을 살펴보세요 -- [도구](/openai-agents-js/ko/guides/tools)로 모델에 강력한 기능을 제공하세요 +- [도구](/openai-agents-js/ko/guides/tools)로 모델에 강력한 기능을 부여하세요 - 필요에 따라 [가드레일](/openai-agents-js/ko/guides/guardrails) 또는 [트레이싱](/openai-agents-js/ko/guides/tracing)을 추가하세요 diff --git a/docs/src/content/docs/ko/guides/multi-agent.md b/docs/src/content/docs/ko/guides/multi-agent.md index 2898d4ee..8d17279f 100644 --- a/docs/src/content/docs/ko/guides/multi-agent.md +++ b/docs/src/content/docs/ko/guides/multi-agent.md @@ -3,38 +3,38 @@ title: 멀티 에이전트 오케스트레이션 description: Coordinate the flow between several agents --- -오케스트레이션은 앱에서 에이전트의 흐름을 의미합니다. 어떤 에이전트를 어떤 순서로 실행하고, 다음에 무엇을 할지 어떻게 결정하는가를 말합니다. 에이전트를 오케스트레이션하는 주요 방식은 두 가지입니다: +오케스트레이션은 앱에서 에이전트의 흐름을 의미합니다. 어떤 에이전트가 어떤 순서로 실행되며, 다음에 무엇을 할지 어떻게 결정할까요? 에이전트를 오케스트레이션하는 두 가지 주요 방법이 있습니다: -1. LLM이 의사결정하도록 허용: LLM의 지능을 활용해 계획하고 추론하며 그에 따라 다음 단계를 결정 -2. 코드 기반 오케스트레이션: 코드로 에이전트의 흐름을 결정 +1. LLM 에게 의사결정을 맡기기: LLM 의 지능을 활용해 계획하고 추론하며 그에 따라 수행할 단계를 결정 +2. 코드로 오케스트레이션하기: 코드로 에이전트의 흐름을 결정 -이 패턴들은 혼합하여 사용할 수 있습니다. 각각의 트레이드오프는 아래에 설명합니다. +이 패턴들은 섞어서 사용할 수 있습니다. 각각의 트레이드오프는 아래에 설명합니다. -## LLM을 통한 오케스트레이션 +## LLM 기반 오케스트레이션 -에이전트는 instructions, tools, handoffs를 갖춘 LLM입니다. 이는 개방형 작업이 주어졌을 때, LLM이 도구를 사용해 행동하고 데이터를 수집하며, 핸드오프를 통해 하위 에이전트에게 작업을 위임하는 방식으로 스스로 작업 계획을 수립할 수 있음을 의미합니다. 예를 들어, 리서치 에이전트는 다음과 같은 도구를 갖출 수 있습니다: +에이전트는 instructions, tools, handoffs 를 갖춘 LLM 입니다. 이는 개방형 과제가 주어졌을 때, LLM 이 도구를 사용해 행동하고 데이터를 수집하며, 핸드오프를 통해 하위 에이전트에 작업을 위임하는 방식으로 과제를 해결할 계획을 자율적으로 세울 수 있음을 의미합니다. 예를 들어, 리서치 에이전트는 다음과 같은 도구를 갖출 수 있습니다: -- 웹 검색을 통한 온라인 정보 수집 -- 파일 검색 및 검색 기능을 통한 사내 데이터와 연결 탐색 -- 컴퓨터 사용을 통한 컴퓨터 상의 작업 수행 -- 코드 실행을 통한 데이터 분석 -- 계획 수립, 보고서 작성 등에 특화된 에이전트로의 핸드오프 +- 온라인에서 정보를 찾기 위한 웹 검색 +- 독점 데이터와 연결을 검색하기 위한 파일 검색 및 검색 +- 컴퓨터에서 작업을 수행하기 위한 컴퓨터 사용 +- 데이터 분석을 위한 코드 실행 +- 기획, 보고서 작성 등에 특화된 에이전트로의 핸드오프 -이 패턴은 작업이 개방형이고 LLM의 지능에 의존하고자 할 때 적합합니다. 여기서 가장 중요한 전술은 다음과 같습니다: +이 패턴은 과제가 개방형이고 LLM 의 지능에 의존하고 싶을 때 유용합니다. 여기서 중요한 전술은 다음과 같습니다: -1. 좋은 프롬프트에 투자하세요. 사용 가능한 도구, 사용 방법, 반드시 지켜야 할 매개변수를 명확히 하세요. -2. 앱을 모니터링하고 반복 개선하세요. 어디서 문제가 생기는지 확인하고 프롬프트를 개선하세요. -3. 에이전트가 자기 성찰하고 개선하도록 하세요. 예를 들어 루프로 실행해 스스로 비평하게 하거나, 오류 메시지를 제공해 개선하도록 하세요. -4. 모든 일을 잘하는 범용 에이전트 대신 하나의 작업에 특화된 에이전트를 두세요. -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` 루프로 함께 실행하고, 평가자가 출력이 특정 기준을 통과한다고 말할 때까지 반복 -- `Promise.all` 같은 JavaScript 기본 구성 요소를 통해 여러 에이전트를 병렬로 실행. 서로 의존하지 않는 여러 작업이 있을 때 속도 향상에 유용합니다. +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 점검 가능한 적절한 형식의 데이터를 생성. 예를 들어, 에이전트에게 작업을 몇 가지 카테고리로 분류하도록 요청한 다음, 해당 카테고리에 따라 다음 에이전트를 선택할 수 있습니다. +- 하나의 출력물을 다음 에이전트의 입력으로 변환하여 여러 에이전트를 체이닝. 블로그 포스트 작성 같은 작업을 일련의 단계로 분해할 수 있습니다 — 리서치, 개요 작성, 본문 작성, 비평, 그리고 개선 +- 평가와 피드백을 제공하는 에이전트와 실제 작업을 수행하는 에이전트를 `while` 루프로 함께 실행하여, 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복 +- JavaScript 의 `Promise.all` 같은 기본 구성요소를 통해 여러 에이전트를 병렬로 실행. 서로 의존하지 않는 여러 작업이 있을 때 속도 향상에 유용 -[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns)에 여러 code examples가 있습니다. +[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns)에 여러 예제가 있습니다. diff --git a/docs/src/content/docs/ko/guides/quickstart.mdx b/docs/src/content/docs/ko/guides/quickstart.mdx index 33a641f0..09340cdc 100644 --- a/docs/src/content/docs/ko/guides/quickstart.mdx +++ b/docs/src/content/docs/ko/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. 프로젝트를 생성하고 npm을 초기화하세요. 이 작업은 한 번만 수행하면 됩니다. +1. 프로젝트를 생성하고 npm 을 초기화합니다. 한 번만 수행하면 됩니다. ```bash mkdir my_project @@ -19,27 +19,27 @@ 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 키를 설정하세요. 키가 없다면 [이 안내](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따라 OpenAI API 키를 생성하세요. +3. OpenAI API 키를 설정합니다. 키가 없다면 OpenAI API 키를 생성하려면 [these instructions](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따르세요. ```bash export OPENAI_API_KEY=sk-... ``` - 또는 `setDefaultOpenAIKey('')`를 호출하여 프로그램적으로 키를 설정하고, - 트레이싱을 위해 `setTracingExportApiKey('')`를 사용할 수 있습니다. + 또는 `setDefaultOpenAIKey('')` 를 호출해 프로그램적으로 키를 설정하고, + 트레이싱에는 `setTracingExportApiKey('')` 를 사용할 수 있습니다. 자세한 내용은 [SDK 설정](/openai-agents-js/ko/guides/config)을 참고하세요. ## 첫 에이전트 생성 -에이전트는 instructions와 이름으로 정의됩니다. +에이전트는 instructions 와 이름으로 정의합니다. ```typescript import { Agent } from '@openai/agents'; @@ -55,7 +55,7 @@ const agent = new Agent({ `run` 메서드를 사용해 에이전트를 실행할 수 있습니다. 시작할 에이전트와 전달할 입력을 함께 넘기면 실행이 트리거됩니다. -이 호출은 해당 실행 동안 수행된 최종 출력과 모든 동작을 포함하는 결과를 반환합니다. +이 메서드는 해당 실행 동안 수행된 모든 액션과 최종 출력을 포함한 결과를 반환합니다. ```typescript import { Agent, run } from '@openai/agents'; @@ -73,7 +73,7 @@ console.log(result.finalOutput); ## 에이전트에 도구 제공 -에이전트가 정보를 조회하거나 작업을 수행할 수 있도록 도구를 제공할 수 있습니다. +정보를 조회하거나 액션을 수행할 수 있도록 에이전트에 도구를 제공할 수 있습니다. ```typescript import { Agent, tool } from '@openai/agents'; @@ -100,9 +100,9 @@ const agent = new Agent({ }); ``` -## 에이전트 추가 +## 에이전트 몇 개 더 추가 -추가 에이전트를 유사하게 정의하여 문제를 더 작은 부분으로 분해하고, 현재 작업에 더 집중하도록 만들 수 있습니다. 또한 에이전트에 모델을 정의하여 문제 유형별로 다른 모델을 사용할 수 있습니다. +추가 에이전트를 유사하게 정의해 문제를 더 작은 부분으로 나누고, 에이전트가 현재 작업에 더 집중하도록 할 수 있습니다. 또한 에이전트에 모델을 정의하여 문제별로 다른 모델을 사용할 수 있습니다. ```typescript const historyTutorAgent = new Agent({ @@ -120,7 +120,7 @@ const mathTutorAgent = new Agent({ ## 핸드오프 정의 -여러 에이전트를 오케스트레이션하기 위해 에이전트에 `handoffs`를 정의할 수 있습니다. 이렇게 하면 에이전트가 다음 에이전트로 대화를 넘길 수 있습니다. 이는 실행 과정에서 자동으로 발생합니다. +여러 에이전트를 오케스트레이션하기 위해 에이전트에 `handoffs` 를 정의할 수 있습니다. 이렇게 하면 에이전트가 다음 에이전트로 대화를 넘길 수 있습니다. 이는 실행 중에 자동으로 발생합니다. ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -132,11 +132,11 @@ const triageAgent = Agent.create({ }); ``` -실행 후 결과의 `finalAgent` 속성을 확인하여 최종 응답을 생성한 에이전트를 확인할 수 있습니다. +실행 후 결과의 `finalAgent` 속성을 보면 어떤 에이전트가 최종 응답을 생성했는지 확인할 수 있습니다. ## 에이전트 오케스트레이션 실행 -Runner는 개별 에이전트의 실행, 잠재적인 핸드오프, 도구 실행을 처리합니다. +Runner 는 개별 에이전트의 실행, 잠재적 핸드오프 및 도구 실행을 처리합니다. ```typescript import { run } from '@openai/agents'; @@ -151,21 +151,21 @@ main().catch((err) => console.error(err)); ## 전체 통합 -이제 모두 하나의 전체 예제로 합쳐 보겠습니다. 이를 `index.js` 파일에 넣고 실행하세요. +이제 모든 것을 하나의 전체 예제로 합쳐 보겠습니다. 이를 `index.js` 파일에 넣고 실행하세요. - + -## 트레이스 확인 +## 트레이스 보기 -Agents SDK는 자동으로 트레이스를 생성합니다. 이를 통해 에이전트가 어떻게 동작했는지, 어떤 도구를 호출했는지, 어떤 에이전트로 핸드오프했는지를 검토할 수 있습니다. +Agents SDK 는 자동으로 트레이스를 생성합니다. 이를 통해 에이전트가 어떻게 동작했는지, 어떤 도구를 호출했는지, 어떤 에이전트로 핸드오프했는지 검토할 수 있습니다. -에이전트 실행 중에 어떤 일이 있었는지 확인하려면 +에이전트 실행 중 무슨 일이 있었는지 확인하려면 [OpenAI 대시보드의 Trace viewer](https://platform.openai.com/traces)로 이동하세요. ## 다음 단계 -더 복잡한 에이전트 흐름을 만드는 방법을 알아보세요. +더 복잡한 에이전트 플로를 구축하는 방법을 알아보세요: -- [에이전트](/openai-agents-js/ko/guides/agents) 구성에 대해 알아보기. -- [에이전트 실행](/openai-agents-js/ko/guides/running-agents)에 대해 알아보기. -- [도구](/openai-agents-js/ko/guides/tools), [가드레일](/openai-agents-js/ko/guides/guardrails), [모델](/openai-agents-js/ko/guides/models)에 대해 알아보기. +- [에이전트](/openai-agents-js/ko/guides/agents) 구성 방법 알아보기 +- [에이전트 실행](/openai-agents-js/ko/guides/running-agents) 알아보기 +- [도구](/openai-agents-js/ko/guides/tools), [가드레일](/openai-agents-js/ko/guides/guardrails), [모델](/openai-agents-js/ko/guides/models) 알아보기 diff --git a/docs/src/content/docs/ko/guides/release.mdx b/docs/src/content/docs/ko/guides/release.mdx index bcbb226f..e0573a1c 100644 --- a/docs/src/content/docs/ko/guides/release.mdx +++ b/docs/src/content/docs/ko/guides/release.mdx @@ -5,30 +5,30 @@ description: Learn how we version and release the SDK and recent changes. ## 버전 관리 -이 프로젝트는 `0.Y.Z` 형식의 의미적 버전 관리(semantic versioning)를 약간 수정해 따릅니다. 앞의 `0`은 SDK가 여전히 빠르게 발전 중임을 의미합니다. 각 구성 요소는 다음과 같이 증가합니다. +이 프로젝트는 `0.Y.Z` 형태의 다소 수정된 시맨틱 버전 관리를 따릅니다. 앞의 `0`은 SDK가 아직 빠르게 발전 중임을 나타냅니다. 각 구성 요소는 다음과 같이 증가합니다: -## 마이너 (`Y`) 버전 +## 마이너(`Y`) 버전 -베타로 표시되지 않은 퍼블릭 인터페이스에 **호환성 파괴 변경**이 있을 때 마이너 버전 `Y`를 올립니다. 예를 들어 `0.0.x`에서 `0.1.x`로 올라갈 때 호환성 파괴 변경이 포함될 수 있습니다. +베타로 표시되지 않은 공개 인터페이스에 **breaking changes**가 있을 경우 마이너 버전 `Y`를 올립니다. 예를 들어 `0.0.x`에서 `0.1.x`로 올라갈 때는 호환성이 깨지는 변경이 포함될 수 있습니다. -호환성 파괴 변경을 원하지 않는 경우, 프로젝트에서 `0.0.x` 버전으로 고정할 것을 권장합니다. +호환성 파괴 변경을 원하지 않는 경우, 프로젝트에서 `0.0.x` 버전에 고정할 것을 권장합니다. -## 패치 (`Z`) 버전 +## 패치(`Z`) 버전 -호환성을 깨지 않는 변경에 대해 `Z`를 증가시킵니다: +하위 호환이 깨지지 않는 변경에 대해 `Z`를 증가시킵니다: - 버그 수정 -- 새로운 기능 -- 프라이빗 인터페이스 변경 +- 신규 기능 +- 비공개 인터페이스 변경 - 베타 기능 업데이트 -## 서브 패키지 버전 관리 +## 서브 패키지의 버전 관리 메인 `@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/ko/guides/results.mdx b/docs/src/content/docs/ko/guides/results.mdx index 96c60885..fedf8e6e 100644 --- a/docs/src/content/docs/ko/guides/results.mdx +++ b/docs/src/content/docs/ko/guides/results.mdx @@ -9,54 +9,54 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? [에이전트 실행](/openai-agents-js/ko/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/ko/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/ko/guides/streaming)을 확인하세요. ## 최종 출력 -`finalOutput` 속성에는 마지막으로 실행된 에이전트의 최종 출력이 포함됩니다. 결과는 다음 중 하나입니다: +`finalOutput` 속성에는 마지막으로 실행된 에이전트의 최종 출력이 포함됩니다. 이 결과는 다음 중 하나입니다: - `string` — `outputType`이 정의되지 않은 모든 에이전트의 기본값 -- `unknown` — 에이전트가 출력 타입으로 JSON 스키마를 정의한 경우. 이 경우 JSON은 파싱되지만 타입은 직접 검증해야 합니다. -- `z.infer` — 에이전트가 출력 타입으로 Zod 스키마를 정의한 경우. 출력은 자동으로 해당 스키마에 맞게 파싱됩니다. -- `undefined` — 에이전트가 출력을 생성하지 않은 경우(예: 출력을 생성하기 전에 중지된 경우) +- `unknown` — 에이전트가 출력 타입으로 JSON schema를 정의한 경우. 이 경우 JSON은 파싱되었지만 타입은 직접 검증해야 합니다. +- `z.infer` — 에이전트가 출력 타입으로 Zod schema를 정의한 경우. 출력은 자동으로 해당 스키마에 맞게 파싱됩니다. +- `undefined` — 에이전트가 출력을 생성하지 않은 경우(예: 출력을 생성하기 전에 중단된 경우) -서로 다른 출력 타입을 갖는 핸드오프를 사용하는 경우, 에이전트를 생성할 때 `new Agent()` 생성자 대신 `Agent.create()` 메서드를 사용해야 합니다. +서로 다른 출력 타입과 함께 핸드오프를 사용하는 경우, 에이전트를 생성할 때 `new Agent()` 생성자 대신 `Agent.create()` 메서드를 사용해야 합니다. -이렇게 하면 SDK가 가능한 모든 핸드오프 전반에서 출력 타입을 추론하고 `finalOutput` 속성에 대한 유니온 타입을 제공합니다. +이렇게 하면 SDK가 가능한 모든 핸드오프 전반의 출력 타입을 추론하고 `finalOutput` 속성에 대한 유니온 타입을 제공합니다. 예: ## 다음 턴을 위한 입력 다음 턴의 입력에 접근하는 방법은 두 가지가 있습니다: -- `result.history` — 입력과 에이전트 출력의 사본이 포함됨 -- `result.output` — 전체 에이전트 실행의 출력이 포함됨 +- `result.history` — 입력과 에이전트들의 출력을 모두 복사해 포함합니다 +- `result.output` — 전체 에이전트 실행의 출력을 포함합니다 -`history`는 채팅과 같은 사용 사례에서 전체 히스토리를 유지하기에 편리한 방법입니다: +`history`는 채팅과 같은 사용 사례에서 전체 히스토리를 유지하기 위한 편리한 방법입니다: - + ## 마지막 에이전트 -`lastAgent` 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라, 이는 다음 번에 사용자가 무언가를 입력할 때 유용한 경우가 많습니다. 예를 들어, 프런트라인 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우, 마지막 에이전트를 저장해 두었다가 사용자가 다음에 에이전트에게 메시지를 보낼 때 재사용할 수 있습니다. +`lastAgent` 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라, 이는 다음에 사용자가 입력할 때 유용한 경우가 많습니다. 예를 들어, 프런트라인 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우, 마지막 에이전트를 저장해 두었다가 사용자가 다음에 메시지를 보낼 때 재사용할 수 있습니다. 스트리밍 모드에서는 현재 실행 중인 에이전트에 매핑되는 `currentAgent` 속성에 접근하는 것도 유용할 수 있습니다. ## 새 항목 -`newItems` 속성에는 실행 중에 생성된 새 항목이 포함됩니다. 항목은 [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem)s입니다. 실행 항목은 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)은 핸드오프가 발생했음을 나타냅니다. 원문 항목은 핸드오프 도구 호출에 대한 도구 응답입니다. 항목에서 소스/타깃 에이전트에도 접근할 수 있습니다. +- [`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의 추론 항목을 나타냅니다. 원문 항목은 생성된 추론입니다. @@ -64,11 +64,11 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? ## 상태 -`state` 속성에는 실행의 상태가 포함됩니다. `result`에 첨부된 대부분은 `state`에서 파생되지만, `state`는 직렬화/역직렬화 가능하며 [오류에서 복구](/openai-agents-js/ko/guides/running-agents#exceptions)가 필요하거나 [`interruption`](#interruptions)을 처리해야 하는 경우 이후의 `run` 호출에 대한 입력으로도 사용할 수 있습니다. +`state` 속성에는 실행의 상태가 포함됩니다. `result`에 첨부된 대부분은 `state`에서 파생되지만, `state`는 직렬화/역직렬화가 가능하며, [오류에서 복구](/openai-agents-js/ko/guides/running-agents#exceptions)가 필요하거나 [`인터럽션(중단 처리)`](#interruptions)을 처리해야 하는 경우 이후의 `run` 호출에 대한 입력으로도 사용할 수 있습니다. ## 인터럽션(중단 처리) -에이전트에서 `needsApproval`을 사용하는 경우, 계속 진행하기 전에 처리해야 하는 `interruptions`가 트리거될 수 있습니다. 이 경우 `interruptions`는 인터럽션을 유발한 `ToolApprovalItem`s의 배열이 됩니다. 인터럽션을 처리하는 방법에 대한 자세한 내용은 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop) 가이드를 확인하세요. +에이전트에서 `needsApproval`을 사용하는 경우, 계속 진행하기 전에 처리해야 하는 `interruptions`가 트리거될 수 있습니다. 이 경우 `interruptions`는 인터럽션을 야기한 `ToolApprovalItem`의 배열이 됩니다. 인터럽션을 처리하는 방법에 대한 자세한 내용은 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop)을 확인하세요. ## 기타 정보 @@ -82,8 +82,8 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? ### 가드레일 결과 -`inputGuardrailResults`와 `outputGuardrailResults` 속성에는(있는 경우) 가드레일 결과가 포함됩니다. 가드레일 결과에는 로깅하거나 저장하고 싶은 유용한 정보가 들어 있는 경우가 있어, 이를 제공해 드립니다. +`inputGuardrailResults` 및 `outputGuardrailResults` 속성에는(있는 경우) 가드레일의 결과가 포함됩니다. 가드레일 결과에는 로깅하거나 저장하고 싶은 유용한 정보가 포함될 수 있으므로 이를 제공해 드립니다. ### 원본 입력 -`input` 속성에는 run 메서드에 제공한 원본 입력이 포함됩니다. 대부분의 경우 필요하지 않지만, 필요한 경우를 대비해 제공됩니다. +`input` 속성에는 run 메서드에 제공한 원본 입력이 포함됩니다. 대부분의 경우 필요하지 않지만 필요할 때를 대비해 제공됩니다. diff --git a/docs/src/content/docs/ko/guides/running-agents.mdx b/docs/src/content/docs/ko/guides/running-agents.mdx index e4113f03..02f284dd 100644 --- a/docs/src/content/docs/ko/guides/running-agents.mdx +++ b/docs/src/content/docs/ko/guides/running-agents.mdx @@ -11,29 +11,29 @@ import chatLoopExample from '../../../../../../examples/docs/running-agents/chat import conversationIdExample from '../../../../../../examples/docs/running-agents/conversationId.ts?raw'; import previousResponseIdExample from '../../../../../../examples/docs/running-agents/previousResponseId.ts?raw'; -에이전트는 스스로는 아무것도 하지 않습니다. `Runner` 클래스 또는 `run()` 유틸리티로 이를 실행합니다. +에이전트는 스스로 아무것도 하지 않습니다 – `Runner` 클래스 또는 `run()` 유틸리티로 이를 **실행**합니다. -커스텀 runner가 필요 없다면 싱글톤 기본 `Runner` 인스턴스를 실행하는 `run()` 유틸리티를 사용할 수 있습니다. +사용자 정의 러너가 필요 없다면, 싱글톤 기본 `Runner` 인스턴스를 실행하는 `run()` 유틸리티를 사용할 수 있습니다. -또는 직접 runner 인스턴스를 생성할 수 있습니다: +또는 자체 러너 인스턴스를 만들 수 있습니다: -에이전트를 실행하면 최종 출력과 실행의 전체 기록을 담은 [실행 결과](/openai-agents-js/ko/guides/results) 객체를 받게 됩니다. +에이전트를 실행한 후에는 최종 출력과 실행 전체 이력을 포함한 [실행 결과](/openai-agents-js/ko/guides/results) 객체를 받게 됩니다. ## 에이전트 루프 -Runner의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주)일 수도 있고, OpenAI Responses API의 항목인 입력 항목 리스트일 수도 있습니다. +Runner의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주) 또는 OpenAI Responses API의 항목인 입력 항목 목록일 수 있습니다. -runner는 다음 루프를 실행합니다: +러너는 다음과 같은 루프를 실행합니다: 1. 현재 입력으로 현재 에이전트의 모델을 호출 -2. LLM 응답을 검사 +2. LLM 응답 검사 - **최종 출력** → 반환 - - **핸드오프** → 새 에이전트로 전환하고 누적된 대화 기록을 유지한 채 1로 이동 - - **도구 호출** → 도구를 실행하고 결과를 대화에 추가한 후 1로 이동 + - **핸드오프** → 새 에이전트로 전환, 누적된 대화 이력 유지, 1로 이동 + - **도구 호출** → 도구 실행, 결과를 대화에 추가, 1로 이동 3. `maxTurns`에 도달하면 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) 발생