diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index 1a17313e..4ba98023 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -9,28 +9,28 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk -Agents SDK は標準で Responses API または Chat Completions API を通じて OpenAI モデルと連携します。別のモデルを使用したい場合は、[Vercel の AI SDK](https://sdk.vercel.ai/) がサポートする幅広いモデルをこのアダプター経由で Agents SDK に取り込めます。 +Agents SDK は標準で Responses API または Chat Completions API を通じて OpenAI モデルと連携します。ですが、別のモデルを使いたい場合は、[Vercel の AI SDK](https://sdk.vercel.ai/) がサポートする幅広いモデルを、このアダプターを介して Agents SDK で利用できます。 ## セットアップ -1. 拡張パッケージをインストールして AI SDK アダプターを導入します: +1. extensions パッケージをインストールして 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,23 +46,19 @@ Agents SDK は標準で Responses API または Chat Completions API を通じ ## 例 - + ## プロバイダー メタデータの受け渡し -メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` を通して渡してください。値は基盤となる AI SDK のモデルにそのまま転送されます。たとえば、Agents SDK における次の `providerData` +メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` を通して渡します。値は基盤となる AI SDK モデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` ```ts providerData: { @@ -74,7 +70,7 @@ providerData: { } ``` -は、AI SDK 連携を使用する場合には +は、AI SDK 連携を使用すると ```ts providerMetadata: { @@ -86,4 +82,4 @@ providerMetadata: { } ``` -のようになります。 +になります。 diff --git a/docs/src/content/docs/ja/extensions/cloudflare.mdx b/docs/src/content/docs/ja/extensions/cloudflare.mdx index 39e33403..40d261a2 100644 --- a/docs/src/content/docs/ja/extensions/cloudflare.mdx +++ b/docs/src/content/docs/ja/extensions/cloudflare.mdx @@ -6,14 +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()` ベースのアップグレードを内部で実行する専用のトランスポートを提供します。 ## セットアップ @@ -26,11 +25,11 @@ Cloudflare Workers とその他の workerd ランタイムでは、グローバ npm install @openai/agents-extensions ``` -2. **トランスポートを作成し、セッションにアタッチします。** +2. **トランスポートを作成してセッションにアタッチします。** -3. **`RealtimeSession` に接続します。** +3. **`RealtimeSession` を接続します。** ```typescript await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' }); @@ -38,8 +37,8 @@ Cloudflare Workers とその他の workerd ランタイムでは、グローバ -## 注意点 +## 注意事項 -- Cloudflare トランスポートは内部的に `Upgrade: websocket` を伴う `fetch()` を使用し、ソケットの `open` イベントを待たずに処理を進めます。workerd の API に合わせた挙動です -- このトランスポート使用時も、`RealtimeSession` のすべての機能（ツール、ガードレール など）は通常どおり動作します -- 開発中の詳細ログ確認には `DEBUG=openai-agents*` を使用します +- Cloudflare トランスポートは内部的に `fetch()` と `Upgrade: websocket` を使用し、ソケットの `open` イベント待ちをスキップして workerd API に合わせます +- このトランスポート使用時も、`RealtimeSession` のすべての機能（tools、ガードレール など）は通常どおり動作します +- 開発時の詳細ログ確認には `DEBUG=openai-agents*` を使用します diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index 63bf3e2e..0eed17cf 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,36 +7,36 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio は、電話の通話音声の元オーディオを 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 に接続できます。デフォルトの Realtime Session トランスポートを `websocket` モードで使い、Twilio から来るイベントを Realtime Session に接続することも可能です。ただし、その場合は適切なオーディオ形式の設定や、Web ベースの会話よりも通話では遅延が大きくなるため、割り込みタイミングの調整が必要になります。 -セットアップ体験を改善するため、割り込み処理や音声の転送も含め、Twilio への接続を代わりに処理する専用のトランスポート層を用意しました。 +セットアップ体験を改善するために、Twilio への接続、割り込み処理、オーディオ転送を代わりに扱う専用のトランスポート層を用意しました。 ## セットアップ -1. **Twilio アカウントと Twilio の電話番号を用意します。** +1. **Twilio アカウントと Twilio の電話番号を用意する** -2. **Twilio からのイベントを受け取れる WebSocket サーバーを用意します。** +2. **Twilio からのイベントを受け取れる WebSocket サーバーを用意する** - ローカル開発の場合、[`ngrok`](https://ngrok.io/) や + ローカル開発の場合は、[`ngrok`](https://ngrok.io/) や [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - のようなローカルトンネルの設定が必要になり、ローカルサーバーを Twilio からアクセス可能にします。`TwilioRealtimeTransportLayer` + などのローカルトンネルを設定して、ローカル サーバーを Twilio からアクセス可能にする必要があります。`TwilioRealtimeTransportLayer` を使って Twilio に接続できます。 -3. **拡張パッケージをインストールして Twilio アダプターを導入します:** +3. **拡張パッケージをインストールして 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 +54,25 @@ 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` という type と、元のイベントデータを含む `message` プロパティを持ちます。 + Twilio から送られてくる 元 イベントにアクセスしたい場合は、`RealtimeSession` インスタンスの `transport_event` を購読します。Twilio の各イベントは `twilio_message` タイプで、 元 イベントデータを含む `message` プロパティを持ちます。 -3. **デバッグログを確認します。** +3. **デバッグログを確認する** - 状況を詳しく知りたい問題に遭遇することがあります。環境変数 `DEBUG=openai-agents*` を使うと Agents SDK のすべてのデバッグログが表示されます。Twilio アダプターのログだけを有効化する場合は - `DEBUG=openai-agents:extensions:twilio*` を使用します。 + 何が起きているかを詳しく知りたい場合があります。環境変数 `DEBUG=openai-agents*` を使うと Agents SDK からのすべてのデバッグログが表示されます。あるいは、`DEBUG=openai-agents:extensions:twilio*` を使って Twilio アダプターのデバッグログだけを有効にできます。 -## サーバーのフル例 +## フルサーバー例 -以下は、Twilio からリクエストを受け取り、それを `RealtimeSession` に転送する、エンドツーエンドの WebSocket サーバーの例です。 +以下は、Twilio からのリクエストを受け取り、それを `RealtimeSession` に転送する WebSocket サーバーのエンドツーエンドの例です。 + このページの残りでは、すべての Agent 機能を詳しく説明します。 @@ -29,39 +29,43 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## 基本設定 -`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。最も一般的に使用されるプロパティは次のとおりです。 +`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。よく使用されるプロパティは以下のとおりです。 -| Property | Required | Description | -| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | -| `name` | yes | 短い人間可読の識別子 | -| `instructions` | yes | システムプロンプト（文字列 **または** 関数 – [Dynamic instructions](#dynamic-instructions) を参照） | -| `model` | no | モデル名 **または** カスタム [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | -| `modelSettings` | no | 調整用パラメーター（temperature、top_p など）。必要なプロパティがトップレベルにない場合は `providerData` 配下に含められます | -| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | +| 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/) インスタンスの配列 | - + --- ## コンテキスト -エージェント は **コンテキスト型に対してジェネリック** です（例: `Agent`）。コンテキストは、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフ などに転送され、状態の保存や共有サービス（データベース接続、ユーザー メタデータ、フィーチャーフラグ など）の提供に役立ちます。 +エージェントはそのコンテキスト型に対して**ジェネリック**です（例: `Agent`）。コンテキストは、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザー メタデータ、機能フラグ、…）の提供に便利です。 - + --- ## 出力タイプ -デフォルトでは、Agent は **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は次を受け付けます: +デフォルトでは、Agent は **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定できます。SDK は以下を受け付けます。 1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`） -2. JSON スキーマ互換の任意のオブジェクト +2. JSON Schema 互換の任意のオブジェクト `outputType` が指定されると、SDK はプレーンテキストの代わりに自動的に @@ -71,85 +75,89 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## マルチエージェントの設計パターン -エージェント を組み合わせる方法は多数あります。プロダクションのアプリでよく見られるパターンは次の 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 -`instructions` は文字列の代わりに **関数** にできます。関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返せます。 +`instructions` は文字列ではなく**関数**にすることもできます。関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列または `Promise` を返せます。 -同期関数と `async` 関数の両方に対応しています。 +同期関数と `async` 関数の両方がサポートされています。 --- ## ライフサイクルフック -高度なユースケースでは、イベントをリッスンして Agent のライフサイクルを監視できます。利用可能な項目については、エージェントのフックイベント名を掲載している [こちら](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts) を参照してください。 +高度なユースケースでは、イベントをリッスンして 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'`）– その特定のツールを呼び出さなければならない +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 @@ -165,4 +173,4 @@ 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** 配下で完全な TypeDoc リファレンスを参照する diff --git a/docs/src/content/docs/ja/guides/config.mdx b/docs/src/content/docs/ja/guides/config.mdx index a0f107ef..ca1ed24c 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,39 +13,39 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## API キーとクライアント -デフォルトでは、SDK は最初にインポートされた際に環境変数 `OPENAI_API_KEY` を読み取ります。変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出せます。 +デフォルトでは SDK は初回のインポート時に環境変数 `OPENAI_API_KEY` を読み込みます。環境変数を設定できない場合は `setDefaultOpenAIKey()` を手動で呼び出せます。 -独自の `OpenAI` クライアントインスタンスを渡すこともできます。指定しない場合、SDK はデフォルトのキーを使って自動的に作成します。 +独自の `OpenAI` クライアント インスタンスを渡すこともできます。指定しない場合、SDK は既定のキーを使って自動的に作成します。 -最後に、Responses API と Chat Completions API を切り替えられます。 +最後に、Responses API と Chat Completions API を切り替えることができます。 ## トレーシング -トレーシングはデフォルトで有効で、上記セクションの OpenAI キーを使用します。 +トレーシングは既定で有効で、上記の OpenAI キーを使用します。 別のキーは `setTracingExportApiKey()` で設定できます。 -トレーシングは完全に無効化することも可能です。 +トレーシングは完全に無効化することもできます。 -トレーシング機能の詳細は、[トレーシング](/openai-agents-js/ja/guides/tracing)をご覧ください。 +トレーシング機能の詳細は [トレーシング](/openai-agents-js/ja/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)` を使って、独自モジュール用の名前空間付きロガーを取得できます。 -### ログ内の機密データ +### ログ内の機微データ -一部のログにはユーザーデータが含まれる場合があります。以下の環境変数を設定して無効化できます。 +一部のログには 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 12887dd0..c0677a75 100644 --- a/docs/src/content/docs/ja/guides/context.mdx +++ b/docs/src/content/docs/ja/guides/context.mdx @@ -6,14 +6,14 @@ description: Learn how to provide local data via RunContext and expose context t import { Aside, Code } from '@astrojs/starlight/components'; import localContextExample from '../../../../../../examples/docs/context/localContext.ts?raw'; -コンテキストは多義的な用語です。主に次の 2 つのコンテキストがあります。 +コンテキストは多義的な用語です。ここでは主に次の 2 つのコンテキストがあります: -1. 実行中にコードがアクセスできる **ローカルコンテキスト**: ツールに必要な依存関係やデータ、`onHandoff` のようなコールバック、ライフサイクルフック -2. 応答生成時に言語モデルが参照できる **エージェント/LLM コンテキスト** +1. 実行中にコードからアクセスできる **ローカルコンテキスト**: ツールに必要な依存関係やデータ、`onHandoff` のようなコールバック、ライフサイクルフック +2. 応答生成時に言語モデルが参照できる **エージェント/LLM のコンテキスト** ## ローカルコンテキスト -ローカルコンテキストは `RunContext` 型で表されます。状態や依存関係を保持する任意のオブジェクトを作成し、それを `Runner.run()` に渡します。すべてのツール呼び出しとフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み書きできます。 +ローカルコンテキストは `RunContext` 型で表現します。状態や依存関係を保持する任意のオブジェクトを作成し、`Runner.run()` に渡します。すべてのツール呼び出しとフックは `RunContext` ラッパーを受け取り、そのオブジェクトを読み書きできます。 -単一の実行に参加するすべてのエージェント、ツール、フックは同じ **型** のコンテキストを使用する必要があります。 +単一の実行に参加するすべてのエージェント、ツール、フックは、同じ **タイプ** のコンテキストを使用する必要があります。 -ローカルコンテキストの用途例: +ローカルコンテキストの用途: - 実行に関するデータ（ユーザー名、ID など） - ロガーやデータフェッチャーなどの依存関係 - ヘルパー関数 -## エージェント/LLM コンテキスト +## エージェント/LLM のコンテキスト -LLM が呼び出されると、参照できるのは会話履歴から来るデータだけです。追加情報を利用可能にするには、いくつかの方法があります。 +LLM が呼び出されると、参照できるデータは会話履歴のみです。追加情報を利用可能にするには、次のいずれかの方法があります: -1. エージェントの `instructions` に追加する – system または developer メッセージとしても知られます。これは静的な文字列、またはコンテキストを受け取って文字列を返す関数にできます。 -2. `Runner.run()` を呼び出す際の `input` に含める。この方法は instructions に似ていますが、メッセージを [指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます。 +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 の関連データに基づいて応答をグラウンディングする +4. リトリーバルや Web 検索ツールを使い、ファイル、データベース、または Web の関連データに基づいて応答を裏付ける diff --git a/docs/src/content/docs/ja/guides/guardrails.mdx b/docs/src/content/docs/ja/guides/guardrails.mdx index e318c067..af9906e4 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. **入力ガードレール** は最初のユーザー入力に対して実行されます +1. **入力ガードレール** は初回のユーザー入力に対して実行されます 2. **出力ガードレール** は最終的なエージェント出力に対して実行されます ## 入力ガードレール -入力ガードレールは次の 3 ステップで実行されます: +入力ガードレールは次の 3 段階で動作します: -1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) に包んで返します +1. ガードレールはエージェントに渡されるのと同じ入力を受け取ります +2. ガードレール関数が実行され、[`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します 3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます > **Note** -> 入力ガードレールはユーザー入力向けであり、ワークフローでエージェントが*最初*の場合にのみ実行されます。ガードレールはエージェント自体に設定します。エージェントごとに必要なガードレールが異なることが多いためです。 +> 入力ガードレールはユーザー入力を対象としているため、エージェントがワークフローの _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。これは、エージェントによって必要なガードレールが異なることが多いためです。 ## 出力ガードレール -出力ガードレールも同様のパターンに従います: +出力ガードレールは次の 3 段階で動作します: -1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) に包んで返します +1. ガードレールはエージェントが生成した出力を受け取ります +2. ガードレール関数が実行され、[`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップされた [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を返します 3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます > **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 991a3fcc..f572483e 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` になります。 ## ハンドオフの作成 -すべてのエージェントは `handoffs` オプションを受け付けます。ここには他の `Agent` インスタンス、または `handoff()` ヘルパーが返す `Handoff` オブジェクトを含めることができます。 +すべてのエージェントは `handoffs` オプションを受け付けます。ここには他の `Agent` インスタンスや、`handoff()` ヘルパーが返す `Handoff` オブジェクトを含められます。 ### 基本的な使い方 @@ -27,11 +27,11 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r `handoff()` 関数を使うと、生成されるツールを調整できます。 - `agent` – ハンドオフ先のエージェント -- `toolNameOverride` – 既定の `transfer_to_` ツール名の上書き -- `toolDescriptionOverride` – 既定のツール説明の上書き -- `onHandoff` – ハンドオフ時のコールバック。`RunContext` と、必要に応じてパース済みの入力を受け取ります -- `inputType` – ハンドオフに期待される入力スキーマ -- `inputFilter` – 次のエージェントに渡す履歴のフィルター +- `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き +- `toolDescriptionOverride` – 既定のツール説明を上書き +- `onHandoff` – ハンドオフ時のコールバック。`RunContext` と、必要に応じてパース済み入力を受け取ります +- `inputType` – ハンドオフに期待する入力スキーマ +- `inputFilter` – 次のエージェントへ渡す履歴のフィルター ## 入力フィルター -既定では、ハンドオフは会話の履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。 -一般的なヘルパーは `@openai/agents-core/extensions` にあります。 +既定では、ハンドオフは会話の全履歴を受け取ります。次のエージェントへ渡す内容を変更するには、`inputFilter` を指定します。 +共通ヘルパーは `@openai/agents-core/extensions` にあります。 ## 推奨プロンプト -プロンプトでハンドオフに言及すると、LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` を通じて推奨のプレフィックスを提供します。 +プロンプトでハンドオフに言及すると、LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` 経由で推奨のプレフィックスを提供しています。 ### フロー -1. エージェントがツール（複数可）の呼び出しを決定した場合、`needsApproval` の評価によりそのツールに承認が必要か確認します。 -2. 承認が必要な場合、既に承認済みか却下済みかを確認します。 - - 承認も却下もされていない場合、ツールはツール呼び出しを実行できないという静的メッセージをエージェントに返します。 - - 承認 / 却下が未処理の場合、ツール承認リクエストがトリガーされます。 -3. エージェントはすべてのツール承認リクエストを集約し、実行を中断します。 -4. 中断がある場合、[エージェントの実行結果](/openai-agents-js/ja/guides/results) に、保留中ステップを記述する `interruptions` 配列が含まれます。ツール呼び出しに確認が必要なときは、`type: "tool_approval_item"` の `ToolApprovalItem` が表示されます。 -5. ツール呼び出しを承認または却下するには、`result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出します。 -6. すべての中断に対処したら、`result.state` を `runner.run(agent, state)` に渡すことで実行を再開できます。ここで `agent` は全体の実行を開始した元のエージェントです。 -7. フローは手順 1 から再開します。 +1. エージェントがツール（複数も可）を呼び出すと判断した場合、`needsApproval` を評価してそのツールに承認が必要か確認します +2. 承認が必要な場合、エージェントは承認がすでに許可または拒否されているかを確認します + - 承認が許可または拒否されていない場合、ツールは「このツール呼び出しは実行できない」という固定メッセージをエージェントに返します + - 承認 / 拒否が未処理の場合、ツール承認リクエストをトリガーします +3. エージェントはすべてのツール承認リクエストを収集し、実行を中断します +4. 中断がある場合、[エージェントの実行結果](/openai-agents-js/ja/guides/results) に、保留中のステップを記述する `interruptions` 配列が含まれます。ツール呼び出しに確認が必要な場合、`type: "tool_approval_item"` を持つ `ToolApprovalItem` が表示されます +5. ツール呼び出しを承認または拒否するには、`result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出します +6. すべての中断を処理したら、`result.state` を `runner.run(agent, state)` に渡して実行を再開できます。ここで `agent` は全体の実行をトリガーした元のエージェントです +7. フローは手順 1 から再開します ## 例 -以下は、ターミナルで承認を促し、状態を一時的にファイルに保存する Human in the loop (人間の介入) フローの、より完全な例です。 +以下は、ターミナルで承認を促し、状態を一時的にファイルへ保存する Human in the loop (人間の介入) フローの、より完全な例です。 -動作するエンドツーエンドのバージョンは、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 +エンドツーエンドで動作する完全版は、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 -## より長い承認時間への対応 +## 長時間の承認対応 -Human in the loop (人間の介入) フローは、サーバーを稼働し続けることなく長時間中断可能なように設計されています。リクエストを一旦終了して後で続行する必要がある場合、状態をシリアライズして後で再開できます。 +Human in the loop (人間の介入) フローは、サーバーを起動し続けることなく、長時間の中断が可能なように設計されています。リクエストを一旦終了して後で続行する必要がある場合、状態をシリアライズして後から再開できます。 -`JSON.stringify(result.state)` を使用して状態をシリアライズし、後で `RunState.fromString(agent, serializedState)` にシリアライズ済み状態を渡すことで再開できます。ここで `agent` は全体の実行を開始したエージェントのインスタンスです。 +`JSON.stringify(result.state)` を使って状態をシリアライズし、後から `RunState.fromString(agent, serializedState)` にシリアライズ済み状態を渡して再開できます。ここで `agent` は全体の実行をトリガーしたエージェントのインスタンスです。 -この方法により、シリアライズ済み状態をデータベースやリクエストと共に保存できます。 +この方法により、シリアライズした状態をデータベースやリクエストと一緒に保存できます。 -### 保留タスクのバージョン管理 +### 保留タスクのバージョニング -承認リクエストに長時間かかり、エージェント定義を意味のある形でバージョン管理したい、または Agents SDK のバージョンを上げたい場合は、パッケージエイリアスを使用して 2 つの Agents SDK バージョンを並行してインストールし、独自の分岐ロジックを実装することを現時点では推奨します。 +承認リクエストに長い時間がかかり、エージェント定義の有意義なバージョニングや Agents SDK のバージョン更新を行いたい場合は、パッケージエイリアスを用いて 2 つの Agents SDK バージョンを並行インストールし、独自の分岐ロジックを実装することを現時点では推奨します。 -実務上は、自分のコードにバージョン番号を割り当ててシリアライズ済み状態と一緒に保存し、デシリアライズを自分のコードの正しいバージョンに誘導することを意味します。 +実務上は、独自のコードにバージョン番号を割り当て、それをシリアライズした状態と一緒に保存し、デシリアライズをコードの正しいバージョンへ誘導することを意味します。 diff --git a/docs/src/content/docs/ja/guides/mcp.mdx b/docs/src/content/docs/ja/guides/mcp.mdx index f9fd5e77..74b72afd 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -13,111 +13,107 @@ import streamableHttpExample from '../../../../../../examples/docs/mcp/streamabl import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; -[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP ドキュメントより: +The [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLMs にツールとコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより: -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。USB‑C がさまざまな周辺機器やアクセサリにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。 +> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンなプロトコルです。AI アプリケーションにとっての USB‑C ポートのようなものだと考えてください。USB‑C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するように、MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。 -この SDK がサポートする MCP サーバーには 3 つの種類があります: +この SDK がサポートする MCP サーバーには 3 種類あります: -1. **リモート MCP サーバーツール** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) によってツールとして利用されるリモート MCP サーバー -2. **Streamable HTTP MCP サーバー** – [Streamable HTTP 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** | -| 標準入出力プロトコルのみをサポートするローカル MCP サーバーを使う | **3. Stdio** | +| 必要なこと | 推奨オプション | +| ------------------------------------------------------------------------ | ---------------------------------- | +| 公開アクセス可能なリモートサーバーを既定の OpenAI Responses モデルで呼ぶ | **1. リモート MCP サーバーツール** | +| 公開アクセス可能なリモートサーバーを使いつつツール呼び出しはローカルで | **2. Streamable HTTP** | +| ローカルで動作する Streamable HTTP サーバーを利用 | **2. Streamable HTTP** | +| OpenAI Responses 以外のモデルで任意の Streamable HTTP サーバーを利用 | **2. Streamable HTTP** | +| 標準入出力プロトコルのみをサポートするローカル MCP サーバーと連携 | **3. Stdio** | ## 1. リモート MCP サーバーツール -組み込みツール（Hosted）は、往復処理全体をモデル内に押し込みます。あなたのコードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルへストリーミングします。 +組み込みツール（Hosted）は、往復の処理全体をモデル側に寄せます。コードが MCP サーバーを呼ぶ代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルにストリーミングします。 -リモート MCP ツールを使う最もシンプルな例を示します。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡すことで、リモート MCP サーバーツールを簡単に作成できます。 +以下は Hosted MCP ツールを使う最も簡単な例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡すことで、Hosted MCP サーバーツールを簡単に作成できます。 -その後、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）で Agent を実行できます: +次に、`run` 関数（または独自にカスタマイズした `Runner` インスタンスの `run` メソッド）で Agent を実行できます: - + -段階的な MCP の結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します: +増分的な MCP の結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します: -#### オプションの承認フロー +#### 任意の承認フロー -機微な操作に対しては、個々のツール呼び出しに人による承認を必須にできます。`requireApproval: 'always'` か、ツール名から `'never'`/`'always'` への詳細なマッピングオブジェクトを渡します。 +機微な操作では、個々のツール呼び出しに対する人間による承認を必須にできます。`requireApproval: 'always'` または、ツール名から `'never'`/`'always'` への詳細なマッピングオブジェクトを渡します。 -ツール呼び出しが安全かどうかをプログラムで判定できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または拒否できます。人による承認が必要な場合は、ローカルの 関数ツール と同様に `interruptions` を使った同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) アプローチを利用できます。 +プログラムによってツール呼び出しの安全性を判定できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または拒否できます。人間の承認が必要な場合は、ローカルの関数ツールと同様に `interruptions` を使う [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) のアプローチを利用できます。 -### コネクタ対応のホスト型サーバー +### コネクタ対応の Hosted サーバー -リモート MCP では OpenAI コネクタにも対応しています。`serverUrl` を提供する代わりに、コネクタの `connectorId` と `authorization` トークンを渡します。Responses API が認証を処理し、コネクタのツールをホスト型 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) を参照してください。 -完全に動作するサンプル（リモートツール/Streamable HTTP/stdio + ストリーミング、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全に動作するサンプル（Hosted ツール / Streamable HTTP / stdio + ストリーミング、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 ## 2. Streamable HTTP MCP サーバー -Agent がローカル/リモートの Streamable HTTP MCP サーバーと直接対話する場合は、サーバーの `url`、`name`、および任意の設定を指定して `MCPServerStreamableHttp` をインスタンス化します: +Agent がローカルまたはリモートの Streamable HTTP MCP サーバーと直接対話する場合は、サーバーの `url`、`name`、および任意の設定で `MCPServerStreamableHttp` を初期化します: -コンストラクタは `authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの追加の MCP TypeScript SDK オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 +コンストラクタは、`authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの追加の MCP TypeScript SDK オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 ## 3. Stdio MCP サーバー -標準入出力のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します: +標準入出力のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` を初期化します: - + -## その他の注意点 +## 知っておくと良いこと -**Streamable HTTP** および **Stdio** サーバーでは、`Agent` を実行するたびに使用可能なツールを検出するために `list_tools()` を呼び出す場合があります。この往復処理は特にリモートサーバーでレイテンシーを増やす可能性があるため、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡してメモリ内で結果をキャッシュできます。 +**Streamable HTTP** と **Stdio** サーバーでは、`Agent` の各実行時に利用可能なツールを検出するために `list_tools()` を呼び出す場合があります。この往復はレイテンシーを増やす可能性があり（特にリモートサーバー）、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡すことで結果をメモリにキャッシュできます。 -ツールリストが変わらないと確信できる場合にのみ有効化してください。後でキャッシュを無効化するには、サーバーインスタンスの `invalidateToolsCache()` を呼び出します。 +ツール一覧が変わらないと確信できる場合のみ有効化してください。後でキャッシュを無効化するには、サーバーインスタンスで `invalidateToolsCache()` を呼び出します。 ### ツールのフィルタリング -`createMCPToolStaticFilter` による静的フィルタ、またはカスタム関数を渡して、各サーバーから公開されるツールを制限できます。以下は両方のアプローチを示す複合的な例です: +`createMCPToolStaticFilter` による静的フィルター、またはカスタム関数を渡して、各サーバーから公開するツールを制限できます。以下は両方のアプローチを組み合わせた例です: - + -## 参考情報 +## 参考資料 - [Model Context Protocol](https://modelcontextprotocol.io/) – 公式仕様 -- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上記で参照した実行可能なデモ +- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上記で参照した実行可能デモ diff --git a/docs/src/content/docs/ja/guides/models.mdx b/docs/src/content/docs/ja/guides/models.mdx index 159c0ac2..d61d5704 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 回_ のリクエストを行う方法を知っています -- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読めるモデルの **名前**（例: `'gpt‑4o'`）を `Model` インスタンスへ解決します +- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して*1 回*のリクエストを行う方法を知っています +- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読めるモデルの**名前**（例: `'gpt‑4o'`）を `Model` インスタンスに解決します -日々の作業では通常、モデルの **名前** と、必要に応じて `ModelSettings` にのみ触れます。 +日々の作業では通常、モデルの**名前**と、場合によっては `ModelSettings` のみを扱います。 -## 既定モデル +## 既定のモデル -`Agent` を初期化するときにモデルを指定しない場合は、既定モデルが使用されます。現在の既定は [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント的なワークフローにおける予測可能性と低レイテンシのバランスに優れています。 +`Agent` を初期化するときにモデルを指定しない場合、既定のモデルが使用されます。現在の既定は [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェントワークフローにおける予測可能性と低レイテンシのバランスに優れています。 -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) など他のモデルに切り替えたい場合、エージェントを設定する方法は 2 つあります。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) など他のモデルに切り替えたい場合、エージェントを構成する方法は 2 つあります。 -まず、カスタムモデルを設定していないすべてのエージェントで一貫して特定のモデルを使用したい場合は、エージェントを実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定します。 +まず、カスタムモデルを設定していないすべてのエージェントで特定のモデルを一貫して使用したい場合は、エージェントを実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定します。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 node my-awesome-agent.js ``` -次に、`Runner` インスタンスに既定モデルを設定できます。エージェント側でモデルを設定しない場合、この `Runner` の既定モデルが使用されます。 +次に、`Runner` インスタンスに既定のモデルを設定できます。エージェントにモデルを設定しない場合は、この `Runner` の既定モデルが使用されます。 -より低レイテンシを求める場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を組み合わせると、既定設定より高速に応答が返ることが多いです。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の reasoning effort をサポートしないため、この Agents SDK の既定は `"low"` になっています。 +より低レイテンシにするには、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) を `reasoning.effort="minimal"` とともに使用することで、既定設定より高速に応答が返ることが多いです。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の推論負荷をサポートしていないため、この Agents SDK では既定値を `"low"` にしています。 ### 非 GPT-5 モデル -カスタムの `modelSettings` なしで非 GPT-5 のモデル名を渡すと、SDK はあらゆるモデルと互換性のある汎用的な `modelSettings` にフォールバックします。 +カスタム `modelSettings` なしで GPT-5 以外のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用的な `modelSettings` にフォールバックします。 --- ## OpenAI プロバイダー -既定の `ModelProvider` は OpenAI の API を使って名前を解決します。2 つの異なるエンドポイントをサポートします: +既定の `ModelProvider` は OpenAI API を使って名前を解決します。次の 2 つの明確に異なるエンドポイントをサポートします。 -| API | 用途 | `setOpenAIAPI()` の呼び出し | -| ---------------- | -------------------------------------------------------------------------- | --------------------------------------- | -| Chat Completions | 標準的なチャットと関数呼び出し | `setOpenAIAPI('chat_completions')` | -| Responses | ツール呼び出しや柔軟な出力を備えた新しい ストリーミング ファースト生成 API | `setOpenAIAPI('responses')` _(default)_ | +| API | 用途 | `setOpenAIAPI()` の呼び出し | +| ---------------- | ---------------------------------------------------------------------- | ------------------------------------ | +| Chat Completions | 標準的なチャット & 関数呼び出し | `setOpenAIAPI('chat_completions')` | +| Responses | ツール呼び出しや柔軟な出力に対応した新しいストリーミング優先の生成 API | `setOpenAIAPI('responses')` _(既定)_ | ### 認証 @@ -82,7 +82,7 @@ node my-awesome-agent.js title="既定の OpenAI キーを設定" /> -ネットワーク設定をカスタマイズする必要がある場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 +ネットワーク設定をカスタムにする必要がある場合は、`setDefaultOpenAIClient(client)` で独自の `OpenAI` クライアントを差し込むこともできます。 --- @@ -90,52 +90,52 @@ node my-awesome-agent.js `ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダーに依存しません。 -| 項目 | 型 | 注記 | +| フィールド | 型 | 注記 | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ | -| `temperature` | `number` | 創造性と決定論のバランス | -| `topP` | `number` | ニュークリアスサンプリング | -| `frequencyPenalty` | `number` | 繰り返し出現するトークンへのペナルティ | +| `temperature` | `number` | クリエイティビティと決定性のバランス | +| `topP` | `number` | nucleus サンプリング | +| `frequencyPenalty` | `number` | 繰り返し出現するトークンにペナルティを課す | | `presencePenalty` | `number` | 新しいトークンの出現を促す | | `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 | -| `parallelToolCalls` | `boolean` | サポートされている場合に関数呼び出しの並列実行を許可 | -| `truncation` | `'auto' \| 'disabled'` | トークンの切り詰め戦略 | +| `parallelToolCalls` | `boolean` | 対応している場合に関数呼び出しの並列実行を許可 | +| `truncation` | `'auto' \| 'disabled'` | トークン切り詰め戦略 | | `maxTokens` | `number` | 応答内の最大トークン数 | -| `store` | `boolean` | 応答を保持して取得や RAG ワークフローに利用 | -| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 などのための reasoning effort | -| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 などのためのテキスト冗長性 | +| `store` | `boolean` | 応答を永続化して取得や RAG ワークフローに利用 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 などの推論負荷 | +| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 などのテキスト冗長度 | -設定はどちらのレベルにも付与できます: +設定はどちらのレベルにも付与できます。 -`Runner` レベルの設定は、競合するエージェントごとの設定を上書きします。 +`Runner` レベルの設定は、競合するエージェント単位の設定を上書きします。 --- ## プロンプト -エージェントは `prompt` パラメーターで構成できます。これは エージェント の挙動を制御するために使用すべき、サーバーに保存されたプロンプト設定を示します。現在、このオプションは OpenAI の -[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合のみサポートされています。 +エージェントは `prompt` パラメーターで構成できます。これは、エージェントの挙動を制御するために使用すべき サーバー保存のプロンプト構成を示します。現在、このオプションは OpenAI の +[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみサポートされています。 -| 項目 | 型 | 注記 | -| ----------- | -------- | ----------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | プロンプトの一意な識別子 | -| `version` | `string` | 使用したいプロンプトのバージョン | -| `variables` | `object` | プロンプトに代入する変数のキー/値ペア。値は文字列またはテキスト、画像、ファイルなどのコンテンツ入力型が可能 | +| フィールド | 型 | 注記 | +| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | プロンプトの一意識別子 | +| `version` | `string` | 使用したいプロンプトのバージョン | +| `variables` | `object` | プロンプトに代入する変数のキー/値ペア。値は文字列またはテキスト、画像、ファイルなどのコンテンツ入力タイプが使用可能 | -tools や instructions など、追加のエージェント設定は、保存済みプロンプトで構成した値を上書きします。 +tools や instructions などの追加のエージェント設定は、保存済みプロンプトで構成した値を上書きします。 --- ## カスタムモデルプロバイダー -独自のプロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、プロバイダーを `Runner` コンストラクターに渡します: +独自のプロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、プロバイダーを `Runner` のコンストラクターに渡します。 -これにより、[OpenAI ダッシュボード](https://platform.openai.com/traces) にトレースが送信され、ワークフローの完全な実行グラフを確認できます。 +これによりトレースが [OpenAI ダッシュボード](https://platform.openai.com/traces) に送信され、ワークフローの完全な実行グラフを確認できます。 --- ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を探る -- [ツール](/openai-agents-js/ja/guides/tools) でモデルを強化する -- 必要に応じて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加する +- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を探索 +- [ツール](/openai-agents-js/ja/guides/tools) でモデルに強力な機能を付与 +- 必要に応じて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加 diff --git a/docs/src/content/docs/ja/guides/multi-agent.md b/docs/src/content/docs/ja/guides/multi-agent.md index 39a6749f..25c58f9a 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 によるオーケストレーション -エージェントは、指示、ツール、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM はツールを使って行動やデータ取得を行い、ハンドオフでサブエージェントに委譲しながら、そのタスクにどう取り組むかを自律的に計画できます。たとえば、リサーチエージェントには次のようなツールを備えられます。 +エージェントは、instructions、tools、handoffs を備えた LLM です。つまり、オープンエンドなタスクに対して、LLM は自律的に計画し、ツールで行動してデータを取得し、ハンドオフでサブエージェントに委譲できます。たとえば、リサーチ用のエージェントには次のようなツールを備えられます。 - Web 検索でオンライン情報を見つける -- ファイル検索と取得で社内データや接続先を横断して検索する -- コンピュータ操作 でコンピュータ上のアクションを実行する -- コード実行 でデータ分析を行う -- 計画やレポート作成などに長けた特化エージェントへのハンドオフ +- ファイル検索と取得で独自データや接続を横断して検索する +- コンピュータ操作で PC 上のアクションを取る +- コード実行でデータ分析を行う +- 計画、レポート執筆などに長けた専門エージェントへのハンドオフ -このパターンはタスクがオープンエンドで、LLM の知性に依拠したい場合に有効です。重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで LLM の知性に任せたいときに有効です。重要な戦術は次のとおりです。 1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーターを明確にする -2. アプリを監視して反復改善する。問題が起きる箇所を観察し、プロンプトを改善する -3. エージェントに内省と改善を許可する。例: ループで実行して自己批評させる、エラーメッセージを与えて改善させる -4. 何でもそつなくこなす汎用エージェントではなく、単一タスクに特化して卓越したエージェントを用意する -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` ループで動かし、評価とフィードバックを行うエージェントと組み合わせ、評価者が一定の基準を満たしたと判断するまで繰り返す +- 複数のエージェントを並列実行する（例: `Promise.all` のような JavaScript の基本コンポーネントを利用）。相互依存のない複数タスクを高速化できる -多数のコード例は [`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) にあります。 +[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns) に多数の code examples があります。 diff --git a/docs/src/content/docs/ja/guides/quickstart.mdx b/docs/src/content/docs/ja/guides/quickstart.mdx index 832045ec..c10b821c 100644 --- a/docs/src/content/docs/ja/guides/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. プロジェクトを作成して npm を初期化します。これは一度だけ行えば大丈夫です。 +1. プロジェクトを作成して npm を初期化します。一度だけ実行すれば大丈夫です ```bash mkdir my_project @@ -19,20 +19,20 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm init -y ``` -2. Agents SDK をインストールします。 +2. Agents SDK をインストールします ```bash npm install @openai/agents zod@3 ``` -3. OpenAI API キーを設定します。まだ持っていない場合は、OpenAI API キーの作成手順については[こちらの手順](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)をご覧ください @@ -52,9 +52,9 @@ const agent = new Agent({ ## はじめてのエージェントの実行 -`run` メソッドでエージェントを実行できます。開始したいエージェントと、渡したい入力を渡して実行します。 +`run` メソッドでエージェントを実行できます。開始したいエージェントと、それに渡したい入力の両方を渡して実行します。 -これにより、その実行中に行われた最終出力と任意のアクションを含む実行結果が返されます。 +これにより、最終的な出力と、その実行中に実行されたアクションを含む実行結果が返されます。 ```typescript import { Agent, run } from '@openai/agents'; @@ -70,9 +70,9 @@ const result = await run(agent, 'When did sharks first appear?'); console.log(result.finalOutput); ``` -## エージェントへのツール付与 +## エージェントにツールを付与 -情報の検索やアクションの実行に使えるツールをエージェントに与えることができます。 +情報の参照やアクションの実行に使えるツールをエージェントに与えられます。 ```typescript import { Agent, tool } from '@openai/agents'; @@ -99,9 +99,9 @@ const agent = new Agent({ }); ``` -## エージェントの追加 +## いくつかのエージェントの追加 -追加のエージェントを同様に定義して、問題を小さな部分に分解し、エージェントを目の前のタスクにより集中させることができます。エージェント上でモデルを定義することで、問題ごとに異なるモデルを使うこともできます。 +追加のエージェントを同様に定義して、問題を小さな部分に分解し、エージェントが現在のタスクにより集中できるようにします。また、エージェントごとにモデルを定義することで、問題に応じて異なるモデルを使用できます。 ```typescript const historyTutorAgent = new Agent({ @@ -131,11 +131,11 @@ const triageAgent = Agent.create({ }); ``` -実行後、結果の `finalAgent` プロパティを見ると、どのエージェントが最終レスポンスを生成したかが分かります。 +実行後、結果の `finalAgent` プロパティを見ると、どのエージェントが最終応答を生成したかがわかります。 -## エージェントオーケストレーションの実行 +## エージェントのオーケストレーションの実行 -Runner は、個々のエージェントの実行、ハンドオフ、およびツール実行の処理を行います。 +Runner は、個々のエージェントの実行、必要に応じたハンドオフ、ツールの実行を処理します。 ```typescript import { run } from '@openai/agents'; @@ -150,21 +150,20 @@ 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 a6667017..8da18818 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`）バージョン -beta とマークされていない公開インターフェースに **破壊的変更** がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への移行に破壊的変更が含まれることがあります。 +ベータと明示されていない公開インターフェースへの**破壊的変更**がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。 ## パッチ（`Z`）バージョン -互換性を壊さない変更については `Z` を上げます。 +以下のような破壊的でない変更の場合は `Z` を増やします。 - バグ修正 - 新機能 - 非公開インターフェースの変更 -- beta 機能の更新 +- ベータ機能の更新 -## サブパッケージのバージョニング +## サブパッケージのバージョン管理 -メインの `@openai/agents` パッケージは、個別に利用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、いずれかのパッケージのバージョンが上がると、他も同様に上がります。`1.0.0` への移行に伴い、この方針を変更する可能性があります。 +メインの `@openai/agents` パッケージは、個別に利用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、いずれかのパッケージでバージョンが上がると他も同様に上がります。`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 92b8321e..13540593 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -9,81 +9,81 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? [エージェントの実行](/openai-agents-js/ja/guides/running-agents)を行うと、次のいずれかを受け取ります: -- [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) — `stream: true` を指定せずに `run` を呼び出した場合 -- [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult) — `stream: true` を指定して `run` を呼び出した場合。ストリーミングの詳細は[ストリーミング](/openai-agents-js/ja/guides/streaming)も参照してください +- `stream: true` を指定せずに `run` を呼び出した場合は [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) +- `stream: true` を指定して `run` を呼び出した場合は [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。ストリーミングの詳細は[ストリーミング](/openai-agents-js/ja/guides/streaming)も参照してください。 ## 最終出力 -`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が含まれます。結果は次のいずれかです: +`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が含まれます。この結果は次のいずれかです: - `string` — `outputType` が定義されていないエージェントのデフォルト -- `unknown` — エージェントが出力タイプとして JSON スキーマを定義している場合。この場合、JSON はパースされていますが、型は手動で検証する必要があります -- `z.infer` — エージェントが出力タイプとして Zod スキーマを定義している場合。このスキーマに対して自動的にパースされます +- `unknown` — エージェントが出力タイプとして JSON スキーマを定義している場合。この場合、JSON はパースされていますが、型の検証は手動で行う必要があります +- `z.infer` — エージェントが出力タイプとして Zod スキーマを定義している場合。出力は自動的にこのスキーマに対してパースされます - `undefined` — エージェントが出力を生成しなかった場合（たとえば、出力を生成する前に停止した場合） -異なる出力タイプを持つハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 +異なる出力タイプのハンドオフを使用している場合は、エージェントを作成する際に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 -これにより、SDK がすべての可能なハンドオフにわたって出力タイプを推論し、`finalOutput` プロパティに対して union type を提供できるようになります。 +これにより、SDK が考え得るすべてのハンドオフにわたって出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 例: -## 次ターンの入力 +## 次ターンへの入力 次ターン用の入力にアクセスする方法は 2 つあります: -- `result.history` — 入力とエージェントの出力の両方のコピーを含みます -- `result.output` — エージェント全体の実行出力を含みます +- `result.history` — あなたの入力とエージェントの出力の両方のコピーを含みます +- `result.output` — エージェント実行全体の出力を含みます -`history` は、チャットのようなユースケースで完全な履歴を維持するのに便利です: +`history` は、チャット風のユースケースで完全な履歴を維持するのに便利です: - + ## 最後のエージェント -`lastAgent` プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回 ユーザー が何かを入力する際に役立つことがよくあります。たとえば、フロントラインのトリアージ エージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存して、次に ユーザー がエージェントにメッセージを送るときに再利用できます。 +`lastAgent` プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回ユーザーが入力する際に役立つことがよくあります。たとえば、フロントラインのトリアージ用エージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存して、次回ユーザーがメッセージを送るときに再利用できます。 -ストリーミング モードでは、現在実行中のエージェントに対応する `currentAgent` プロパティにアクセスするのも有用です。 +ストリーミングモードでは、現在実行中のエージェントに対応する `currentAgent` プロパティにアクセスするのも有用です。 ## 新規アイテム -`newItems` プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。実行アイテムは、LLM が生成した 元 アイテムをラップします。これにより、LLM の出力に加えて、どのエージェントに関連するイベントだったかにもアクセスできます。 +`newItems` プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。実行アイテムは、LLM が生成した元のアイテムをラップします。これにより、LLM の出力に加えて、どのエージェントに関連付けられたイベントかにもアクセスできます。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。 元 アイテムは生成されたメッセージです -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフ ツールを呼び出したことを示します。 元 アイテムは LLM からのツール呼び出しアイテムです -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。 元 アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲット エージェントにもアクセスできます -- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを呼び出したことを示します -- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。 元 アイテムはツール応答です。アイテムからツール出力にもアクセスできます -- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM からの推論アイテムを示します。 元 アイテムは生成された推論です -- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。 元 アイテムは LLM からのツール呼び出しアイテムです +- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元アイテムは生成されたメッセージです +- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフツールを呼び出したことを示します。元アイテムは LLM からのツール呼び出しアイテムです +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。元アイテムはハンドオフツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます +- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを起動したことを示します +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。元アイテムはツールの応答です。アイテムからツールの出力にもアクセスできます +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM からの reasoning アイテムを示します。元アイテムは生成された reasoning です +- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。元アイテムは LLM からのツール呼び出しアイテムです ## 状態 -`state` プロパティには実行の状態が含まれます。`result` に付随する情報の大部分は `state` から導出されていますが、`state` はシリアライズ/デシリアライズ可能で、[エラーからの復旧](/openai-agents-js/ja/guides/running-agents#exceptions)が必要な場合や、[`interruption`](#interruptions) に対処する場合に、後続の `run` 呼び出しの入力としても使用できます。 +`state` プロパティには、実行の状態が含まれます。`result` に付随する情報の多くは `state` から導出されていますが、`state` はシリアライズ/デシリアライズ可能で、[エラーからのリカバリー](/openai-agents-js/ja/guides/running-agents#exceptions)が必要な場合や、[`interruption`](#interruptions) を処理する場合に、後続の `run` 呼び出しの入力としても使用できます。 ## 中断 -エージェントで `needsApproval` を使用している場合、続行する前に処理が必要な `interruptions` が発生することがあります。その場合、`interruptions` は中断を引き起こした `ToolApprovalItem` の配列になります。中断への対処方法の詳細は、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)を参照してください。 +エージェントで `needsApproval` を使用している場合、続行する前に処理が必要な `interruptions` がトリガーされることがあります。その場合、`interruptions` は中断を引き起こした `ToolApprovalItem`s の配列になります。中断の扱い方については、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)を確認してください。 ## その他の情報 ### 元レスポンス -`rawResponses` プロパティには、エージェント実行中にモデルが生成した LLM の 元 レスポンスが含まれます。 +`rawResponses` プロパティには、エージェント実行中にモデルが生成した元の LLM レスポンスが含まれます。 -### 最後のレスポンス ID +### 最終レスポンス ID `lastResponseId` プロパティには、エージェント実行中にモデルが最後に生成したレスポンスの ID が含まれます。 -### ガードレールの結果 +### ガードレール結果 -`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 b17cac80..aed85d20 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -11,134 +11,134 @@ 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()` ユーティリティでそれらを **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 の応答を検査する - - **Final output** → 返す - - **Handoff** → 新しいエージェントに切り替え、蓄積された会話履歴を保持して 1 に戻る - - **Tool calls** → ツールを実行し、その結果を会話に追加して 1 に戻る -3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローする +1. 現在の入力で現在の エージェント のモデルを呼び出す +2. LLM の応答を確認する + - **最終出力** → 返す + - **ハンドオフ** → 新しい エージェント に切り替え、蓄積した会話履歴を保持し、1 に戻る + - **ツール呼び出し** → ツールを実行し、その結果を会話に追加して、1 に戻る +3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を送出する ### Runner のライフサイクル -アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデル プロバイダーやトレーシング オプションなどのグローバル設定を保持します。まったく異なるセットアップが必要な場合のみ別の `Runner` を作成してください。簡単なスクリプトでは、内部でデフォルト runner を使う `run()` を呼び出すこともできます。 +アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシングオプションといったグローバル設定を保持します。まったく別の構成が必要な場合のみ別の `Runner` を作成してください。シンプルなスクリプトでは内部でデフォルト Runner を使う `run()` を呼ぶこともできます。 ## 実行引数 -`run()` メソッドへの入力は、実行を開始する初期エージェント、実行の入力、およびオプションのセットです。 +`run()` メソッドへの入力は、実行を開始する初期 エージェント、実行の入力、およびオプションのセットです。 -入力は、文字列（ユーザー メッセージとして扱われます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 +入力は、文字列（ユーザー メッセージとして扱われます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) の一覧、または [Human in the loop (人間の介入)](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 -追加のオプションは次のとおりです: +追加オプションは次のとおりです: -| Option | Default | Description | -| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着するイベントを逐次発行します | -| `context` | – | すべての tool / guardrail / handoff に転送されるコンテキスト オブジェクト。詳しくは[コンテキスト管理](/openai-agents-js/ja/guides/context)を参照 | -| `maxTurns` | `10` | セーフティ制限。到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローします | -| `signal` | – | キャンセル用の `AbortSignal` | +| Option | Default | Description | +| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着したイベントを逐次送出します | +| `context` | – | すべての tool / guardrail / handoff に転送されるコンテキストオブジェクト。詳細は[コンテキスト管理](/openai-agents-js/ja/guides/context)を参照 | +| `maxTurns` | `10` | セーフティリミット。到達時に [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を送出します | +| `signal` | – | 取り消し用の `AbortSignal` | ## ストリーミング -ストリーミングにより、LLM の実行中にストリーミング イベントを受け取ることができます。ストリームが開始されると、`StreamedRunResult` は、生成されたすべての新しい出力を含む実行に関する完全な情報を保持します。`for await` ループを使ってストリーミング イベントを反復処理できます。詳しくは[ストリーミング](/openai-agents-js/ja/guides/streaming)を参照してください。 +ストリーミング を使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリームが開始されると、`StreamedRunResult` は新しく生成されたすべての出力を含む、実行に関する完全な情報を保持します。`for await` ループでストリーミングイベントを反復処理できます。詳しくは[ストリーミング](/openai-agents-js/ja/guides/streaming)を参照してください。 ## 実行設定 -独自の `Runner` インスタンスを作成する場合は、`RunConfig` オブジェクトを渡して runner を構成できます。 - -| Field | Type | Purpose | -| --------------------------- | --------------------- | ------------------------------------------------------------------------------------ | -| `model` | `string \| Model` | 実行中の **すべて** のエージェントに特定のモデルを強制します | -| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダーです | -| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニング パラメーター | -| `handoffInputFilter` | `HandoffInputFilter` | handoff を実行する際に入力アイテムを変更します（handoff 自体で定義されていない場合） | -| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | -| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | -| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します | -| `traceIncludeSensitiveData` | `boolean` | スパンは発行したまま、トレースから LLM/ツールの入出力を除外します | -| `workflowName` | `string` | Traces ダッシュボードに表示され、関連する実行のグルーピングに役立ちます | -| `traceId` / `groupId` | `string` | SDK に生成させず、トレースまたはグループ ID を手動で指定します | -| `traceMetadata` | `Record` | すべてのスパンに付与する任意のメタデータ | +独自の `Runner` インスタンスを作成する場合は、Runner を構成するために `RunConfig` オブジェクトを渡せます。 + +| Field | Type | Purpose | +| --------------------------- | --------------------- | ----------------------------------------------------------------------------- | +| `model` | `string \| Model` | 実行中の **すべて** の エージェント に対して特定のモデルを強制します | +| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダーです | +| `modelSettings` | `ModelSettings` | エージェント個別の設定を上書きするグローバルなチューニング パラメーター | +| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ時に入力アイテムを変換します（ハンドオフ自体で未定義の場合） | +| `inputGuardrails` | `InputGuardrail[]` | 最初の ユーザー 入力に適用されるガードレール | +| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | +| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します | +| `traceIncludeSensitiveData` | `boolean` | スパンは送出しつつ、トレースから LLM/ツールの入力・出力を除外します | +| `workflowName` | `string` | Traces ダッシュボードに表示され、関連する実行をグルーピングするのに役立ちます | +| `traceId` / `groupId` | `string` | SDK に生成させず、トレース ID またはグループ ID を手動で指定します | +| `traceMetadata` | `Record` | すべてのスパンに添付する任意のメタデータ | ## 会話 / チャットスレッド -`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーション レベルの会話における 1 回の **ターン** を表します。エンドユーザーにどの程度の `RunResult` を見せるかは任意です。`finalOutput` のみの場合もあれば、生成されたすべてのアイテムを表示する場合もあります。 +`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における 1 つの **ターン** を表します。エンド ユーザー にどれだけの `RunResult` を見せるかは任意です。`finalOutput` のみの場合もあれば、生成されたすべてのアイテムを見せる場合もあります。 - + -インタラクティブ版は[チャットの sample code](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 ガイド](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)を参照してください。 +OpenAI Responses API に会話履歴を保持させれば、毎ターンでローカルの全文書起こしを送信する必要がありません。長い会話や複数サービスの調整に便利です。詳細は[Conversation state guide](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` +#### 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` プロパティを提供する場合があります。 -`GuardrailExecutionError` を処理するコード例です: +以下は `GuardrailExecutionError` を扱うコード例です: 上の例を実行すると、次の出力が表示されます: @@ -152,6 +152,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 4c48754a..2e6ee5b5 100644 --- a/docs/src/content/docs/ja/guides/streaming.mdx +++ b/docs/src/content/docs/ja/guides/streaming.mdx @@ -9,11 +9,11 @@ import nodeTextStreamExample from '../../../../../../examples/docs/streaming/nod import handleAllEventsExample from '../../../../../../examples/docs/streaming/handleAllEvents.ts?raw'; import streamedHITLExample from '../../../../../../examples/docs/streaming/streamedHITL.ts?raw'; -Agents SDK は、モデルおよびその他の実行ステップからの出力を段階的に配信できます。ストリーミングにより UI を応答性よく保ち、最終的な実行結果のすべてを待たずに ユーザー への更新ができます。 +Agents SDK は、モデルやその他の実行ステップからの出力を段階的に配信できます。ストリーミングにより UI が応答性を保ち、ユーザーの更新前に最終結果全体を待つ必要がなくなります。 ## ストリーミングの有効化 -`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミングオブジェクトが取得できます: +`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミング用のオブジェクトを取得できます: -ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、実行中に何が起きたかを説明するオブジェクトです。ストリームはエージェントの実行の異なる部分を説明する 3 種類のイベントのいずれかを返します。とはいえ、ほとんどのアプリケーションはモデルのテキストだけが必要なため、ストリームにはそれを支援するヘルパーが用意されています。 +ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、その実行中に起きたことを表すオブジェクトです。ストリームは 3 種類のイベントのいずれかを生成し、エージェントの実行の異なる部分を表します。ほとんどのアプリケーションはモデルのテキストだけを必要とするため、ストリームには補助機能が用意されています。 ### テキスト出力の取得 -`stream.toTextStream()` を呼び出すと、出力されたテキストのストリームが得られます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js の `Readable` です。`process.stdout` や他の出力先に直接パイプできます。 +`stream.toTextStream()` を呼び出すと、出力されたテキストのストリームが得られます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js の `Readable` です。`process.stdout` や他の出力先にそのままパイプできます。 -`stream.completed` の Promise は、実行と保留中のすべてのコールバックが完了すると解決されます。出力がこれ以上ないことを確実にする場合は、必ず待機してください。 +`stream.completed` の Promise は、実行と保留中のすべてのコールバックが完了すると解決されます。出力がもうないことを確実にするには必ず待機してください。 -### すべてのイベントをリッスン +### すべてのイベントのリッスン -`for await` ループを使って、到着した各イベントを確認できます。役立つ情報には、低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などがあります: +`for await` ループを使用して、到着した各イベントを検査できます。役立つ情報には、低レベルのモデルイベント、エージェントの切り替え、そして SDK 固有の実行情報が含まれます: -[the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照すると、プレーンテキストのストリームと元のイベントストリームの両方を出力する完全なスクリプトが確認できます。 +[the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照すると、プレーンテキストのストリームと元のイベントストリームの両方を出力する、完全なスクリプトが確認できます。 ## イベントタイプ -ストリームは 3 種類の異なるイベントタイプを返します: +ストリームは 3 種類のイベントタイプを生成します: ### raw_model_stream_event @@ -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 2662abf3..df560062 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,104 +10,112 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -ツールはエージェントが **アクションを実行** する手段です。データ取得、外部 API 呼び出し、コード実行、さらにはコンピュータ操作まで可能です。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします: +ツールは、エージェント が **アクションを実行する** ことを可能にします。データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの使用までできます。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします: -1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと並行して実行されます（Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成） -2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM が呼び出せるようにします -3. **エージェントをツールとして使用** – エージェント全体を呼び出し可能なツールとして公開します -4. **ローカル MCP サーバー** – 手元で動作する Model Context Protocol サーバーを接続します +1. **組み込みツール（Hosted）** – OpenAI の サーバー 上でモデルと並行して実行 _(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_ +2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップして LLM が呼び出せるようにする +3. **ツールとしてのエージェント** – エージェント 全体を呼び出し可能なツールとして公開 +4. **ローカル MCP サーバー** – お使いのマシン上で動作する Model context protocol サーバーを接続 --- ## 1. 組み込みツール（Hosted） -`OpenAIResponsesModel` を使用する場合、次の組み込みツールを追加できます: +`OpenAIResponsesModel` を使う場合、以下の組み込みツールを追加できます: -| ツール | Type 文字列 | 目的 | -| ----------------------- | -------------------- | --------------------------------------------- | -| Web search | `'web_search'` | インターネット検索 | -| File / retrieval search | `'file_search'` | OpenAI 上でホストされるベクトルストアのクエリ | -| Computer use | `'computer'` | GUI 操作を自動化 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | -| Image generation | `'image_generation'` | テキストに基づく画像生成 | +| ツール | 型文字列 | 目的 | +| ----------------------- | -------------------- | ----------------------------------------------- | +| Web search | `'web_search'` | インターネット検索 | +| File / retrieval search | `'file_search'` | OpenAI 上でホストされる ベクトルストア のクエリ | +| Computer use | `'computer'` | GUI 操作を自動化 | +| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | +| Image generation | `'image_generation'` | テキストに基づいて画像を生成 | - + -正確なパラメーターは OpenAI Responses API と一致します。`rankingOptions` やセマンティックフィルターなどの高度なオプションについては公式ドキュメントを参照してください。 +正確なパラメーターセットは OpenAI Responses API に一致します。`rankingOptions` やセマンティックフィルターなどの高度なオプションは公式ドキュメントを参照してください。 --- ## 2. 関数ツール -`tool()` ヘルパーを使って、**任意** の関数をツールにできます。 +`tool()` ヘルパーを使うと、**任意** の関数をツールにできます。 ### オプションリファレンス -| フィールド | 必須 | 説明 | -| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | いいえ | デフォルトは関数名（例: `get_weather`） | -| `description` | はい | LLM に表示される明確で人間が読める説明 | -| `parameters` | はい | Zod スキーマまたは元の JSON スキーマオブジェクトのいずれか。Zod パラメーターは自動的に **strict** モードを有効化 | -| `strict` | いいえ | `true`（デフォルト）の場合、引数が検証に合格しないと SDK はモデルエラーを返します。あいまい一致にするには `false` に設定 | -| `execute` | はい | `(args, context) => string \| Promise`– ビジネスロジック。第 2 引数は省略可能で、`RunContext` | -| `errorFunction` | いいえ | 内部エラーをユーザーに表示する文字列へ変換するためのカスタムハンドラー `(context, error) => string` | +| 項目 | 必須 | 説明 | +| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | いいえ | デフォルトは関数名（例: `get_weather`） | +| `description` | はい | LLM に表示される、明確で人間に読みやすい説明 | +| `parameters` | はい | Zod スキーマまたは 元 の JSON スキーマオブジェクトのいずれか。Zod パラメーターは自動的に **strict** モードを有効化 | +| `strict` | いいえ | `true`（デフォルト）の場合、引数が検証に通らなければ SDK はモデルエラーを返す。あいまいなマッチングにするには `false` に設定 | +| `execute` | はい | `(args, context) => string \| Promise`– ビジネスロジック本体。2 番目の引数は省略可能で、`RunContext` | +| `errorFunction` | いいえ | 内部エラーを ユーザー に見える文字列へ変換するためのカスタムハンドラー `(context, error) => string` | ### 非 strict な JSON スキーマツール -無効または部分的な入力をモデルに推測させたい場合は、元の JSON スキーマ使用時に strict モードを無効化できます: +無効または部分的な入力をモデルに*推測*させたい場合は、元 の JSON スキーマ使用時に strict モードを無効化できます: --- -## 3. エージェントをツールとして使用 +## 3. ツールとしてのエージェント -会話全体を引き渡さずに、別のエージェントを補助として使いたい場合は `agent.asTool()` を使用します: +会話全体を完全にハンドオフせずに、ある エージェント に別の エージェント を*支援*させたい場合は、`agent.asTool()` を使います: - + -SDK は内部的に次を実行します: +内部的に SDK は次を行います: - 単一の `input` パラメーターを持つ関数ツールを作成 - ツール呼び出し時にその入力でサブエージェントを実行 -- 最後のメッセージ、または `customOutputExtractor` で抽出された出力を返却 +- 最後のメッセージ、または `customOutputExtractor` で抽出した出力を返す -エージェントをツールとして実行すると、Agents SDK はデフォルト設定でランナーを作成し、関数実行内でそのランナーを使ってエージェントを実行します。`runConfig` や `runOptions` のプロパティを指定したい場合は、`asTool()` メソッドに渡してランナーの動作をカスタマイズできます。 +エージェントをツールとして実行する場合、Agents SDK はデフォルト設定の runner を作成し、関数の実行内でそのエージェントを実行します。`runConfig` や `runOptions` のプロパティを指定したい場合は、`asTool()` メソッドに渡して runner の動作をカスタマイズできます。 --- ## 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) を参照してください。 +モデルがツールをいつどのように使用するべきか（`tool_choice`、`toolUseBehavior` など）の制御については、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください。 --- ## ベストプラクティス -- **短く明確な説明** – ツールが何をするか、いつ使うかを記述 -- **入力を検証** – 可能であれば Zod スキーマで厳密な JSON 検証を実施 -- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返すべきで、例外は投げない -- **ツールごとに単一責務** – 小さく合成可能なツールはモデルの推論性能を高める +- **短く明確な説明** – ツールが*何をするか*、*いつ使うか*を記述 +- **入力を検証** – 可能な限り Zod スキーマで厳格な JSON 検証を実施 +- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返すべきで、throw しない +- **ツールは単一責務** – 小さく合成しやすいツールはモデルの推論を向上 --- @@ -115,4 +123,4 @@ SDK は内部的に次を実行します: - [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) について学ぶ - ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 -- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種 Hosted ツールタイプの TypeDoc リファレンスを参照 +- [`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 dcabdfe7..97f8a358 100644 --- a/docs/src/content/docs/ja/guides/tracing.mdx +++ b/docs/src/content/docs/ja/guides/tracing.mdx @@ -7,24 +7,24 @@ import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw'; -Agents SDK には組み込みのトレーシングがあり、エージェント実行中の包括的なイベント記録を収集します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらには発生するカスタムイベントまで対象です。[Traces ダッシュボード](https://platform.openai.com/traces)を使用すると、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みのトレーシングがあり、エージェントの実行中に発生するイベントを包括的に記録します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントまでを収集します。[Traces ダッシュボード](https://platform.openai.com/traces)を使うと、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 ## エクスポートループのライフサイクル -多くの環境では、トレースは定期的に自動エクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。キューに溜まりすぎた場合はトレースがエクスポートされますが、定期的にはエクスポートされません。代わりに、コードのライフサイクル内で手動エクスポートするために `getGlobalTraceProvider().forceFlush()` を使用してください。 +多くの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。キューが溜まりすぎた場合はトレースはエクスポートされますが、定期的にはエクスポートされません。その代わり、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用して手動でトレースをエクスポートしてください。 -例として、Cloudflare Worker では、コードを `try/catch/finally` ブロックでラップし、`waitUntil` と合わせて強制フラッシュを使うことで、ワーカー終了前にトレースがエクスポートされるようにします。 +たとえば Cloudflare Worker では、コード全体を `try/catch/finally` ブロックでラップし、ワーカーが終了する前にトレースがエクスポートされるように `waitUntil` とともに force flush を使用します。 ` である必要があります - - `group_id`: 任意のグループ ID。同じ会話からの複数トレースを紐づけるために使用。例えばチャットスレッド ID など - - `disabled`: True の場合、このトレースは記録されません +- **Traces** は「ワークフロー」の単一のエンドツーエンドな操作を表します。Spans で構成されます。Traces には次のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリ。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意 ID。未指定の場合は自動生成。形式は `trace_<32_alphanumeric>` + - `group_id`: 同一会話の複数トレースを関連付けるための任意のグループ ID。例: チャットスレッドの ID + - `disabled`: True の場合、トレースは記録されない - `metadata`: トレースの任意メタデータ -- **スパン** は開始時刻と終了時刻を持つ処理を表します。スパンには次があります: +- **Spans** は開始時刻と終了時刻を持つ操作を表します。Spans には次があります: - `started_at` と `ended_at` のタイムスタンプ - 所属するトレースを表す `trace_id` - - 親スパンを指す `parent_id`（ある場合） - - スパンに関する情報である `span_data`。例えば、`AgentSpanData` はエージェントの情報、`GenerationSpanData` は LLM 生成の情報など + - この Span の親を指す `parent_id`（ある場合） + - `span_data`: Span に関する情報。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など ## デフォルトのトレーシング -デフォルトでは、SDK は次をトレースします: +デフォルトで SDK は次をトレースします: -- `run()` または `Runner.run()` 全体が `Trace` にラップされる -- エージェントが実行されるたびに `AgentSpan` にラップされる -- LLM の生成は `GenerationSpan` にラップされる -- 関数ツールの呼び出しはそれぞれ `FunctionSpan` にラップされる -- ガードレールは `GuardrailSpan` にラップされる -- ハンドオフは `HandoffSpan` にラップされる +- `run()` または `Runner.run()` 全体を `Trace` でラップ +- エージェント実行ごとに `AgentSpan` でラップ +- LLM 生成は `GenerationSpan` でラップ +- 関数ツール呼び出しはそれぞれ `FunctionSpan` でラップ +- ガードレールは `GuardrailSpan` でラップ +- ハンドオフは `HandoffSpan` でラップ -デフォルトでは、トレース名は "Agent workflow" です。`withTrace` を使用してこの名前を設定できます。または [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを設定できます。 +デフォルトでは、トレース名は "Agent workflow" です。`withTrace` を使ってこの名前を設定するか、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを設定できます。 -さらに、[カスタム トレース プロセッサー](#custom-tracing-processors) を設定して、トレースを別の宛先へ送信できます（置き換えとして、または副次的な宛先として）。 +加えて、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、他の宛先へトレースを送信できます（置き換え、または副次的な宛先）。 ### 音声エージェントのトレーシング -デフォルトの OpenAI Realtime API で `RealtimeAgent` と `RealtimeSession` を使用している場合、`RealtimeSession` で `tracingDisabled: true` を設定するか、環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を使用して無効化しない限り、トレーシングは Realtime API 側で自動的に行われます。 +`RealtimeAgent` と `RealtimeSession` をデフォルトの OpenAI Realtime API とともに使用している場合、`RealtimeSession` で `tracingDisabled: true` を設定するか、環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を使用して無効化しない限り、トレーシングは Realtime API 側で自動的に行われます。 -詳しくは[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents)を参照してください。 +詳細は[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents)を参照してください。 ## 上位レベルのトレース -複数の `run()` 呼び出しを 1 つのトレースにまとめたい場合は、コード全体を `withTrace()` でラップします。 +複数の `run()` 呼び出しを単一のトレースにまとめたい場合があります。これはコード全体を `withTrace()` でラップすることで実現できます。 -1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 +1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります ## トレースの作成 [`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` を含める必要があります -## 外部トレーシング プロセッサー一覧 +## 外部トレーシングプロセッサー一覧 - [AgentOps](https://docs.agentops.ai/v2/usage/typescript-sdk#openai-agents-integration) - [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agents-sdk-js) diff --git a/docs/src/content/docs/ja/guides/troubleshooting.mdx b/docs/src/content/docs/ja/guides/troubleshooting.mdx index 6e797cc9..f90a4b47 100644 --- a/docs/src/content/docs/ja/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ja/guides/troubleshooting.mdx @@ -3,7 +3,7 @@ title: トラブルシューティング description: Learn how to troubleshoot issues with the OpenAI Agents SDK. --- -## サポートされている環境 +## サポート環境 OpenAI Agents SDK は次のサーバー環境でサポートされています。 @@ -13,29 +13,29 @@ OpenAI Agents SDK は次のサーバー環境でサポートされています ### 限定サポート -- **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`）を使用してください +- **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 は広範にはテストされていません + - 適切なブラウザ用ポリフィルを備えたバンドラを使えば v8 isolates 向けに SDK をバンドルできるはずですが、トレーシングは機能しません + - v8 isolates での動作は十分にテストされていません -## デバッグロギング +## デバッグログ -SDK で問題が発生している場合、デバッグロギングを有効にして、実行状況に関する詳細情報を取得できます。 +SDK で問題が発生している場合は、デバッグログを有効にすると詳細を確認できます。 -`DEBUG` 環境変数を `openai-agents:*` に設定してデバッグロギングを有効化します。 +`DEBUG` 環境変数を `openai-agents:*` に設定してデバッグログを有効にします。 ```bash DEBUG=openai-agents:* ``` -または、SDK の特定部分にデバッグ対象を絞ることもできます。 +また、SDK の特定部分にデバッグ範囲を絞れます。 -- `openai-agents:core` — SDK の主要な実行ロジック向け -- `openai-agents:openai` — OpenAI API 呼び出し向け -- `openai-agents:realtime` — リアルタイムエージェントのコンポーネント向け +- `openai-agents:core` — SDK の主要な実行ロジック用 +- `openai-agents:openai` — OpenAI API 呼び出し用 +- `openai-agents:realtime` — Realtime Agents コンポーネント用 diff --git a/docs/src/content/docs/ja/guides/voice-agents.mdx b/docs/src/content/docs/ja/guides/voice-agents.mdx index acc42ecd..f6ffdeab 100644 --- a/docs/src/content/docs/ja/guides/voice-agents.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents.mdx @@ -23,11 +23,11 @@ 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'; -![リアルタイムエージェント](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) +![Realtime Agents](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) -Voice Agents は OpenAI の 音声対音声モデル を使って、リアルタイムの音声チャットを提供します。これらのモデルは 音声のストリーミング、テキスト、ツール呼び出し をサポートし、音声／電話でのカスタマーサポート、モバイルアプリでの体験、音声チャットなどの用途に最適です。 +音声エージェントは 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 クライアントを提供します。 ## セッション設定 -[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) のコンストラクターや、`connect(...)` を呼び出すときにオプションを追加で渡して、セッションを設定できます。 +[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) のコンストラクターに追加オプションを渡すか、`connect(...)` を呼び出す際にオプションを渡すことで、セッションを設定できます。 これらのトランスポートレイヤーでは、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 -[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に存在しない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡された内容は `session` オブジェクトの一部として直接渡されます。 +[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に存在しない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡した内容は `session` オブジェクトの一部としてそのまま渡されます。 ## ハンドオフ -通常の エージェント と同様に、ハンドオフ を使用して エージェント を複数の エージェント に分割し、それらの間をオーケストレーションすることで、エージェント のパフォーマンスを向上させ、問題の範囲を適切に絞り込めます。 +通常のエージェントと同様に、ハンドオフを使ってエージェントを複数のエージェントに分割し、それらをオーケストレーションすることで、エージェントのパフォーマンスを向上させ、問題の範囲を適切に絞り込めます。 -通常の エージェント と異なり、ハンドオフ は リアルタイムエージェント では少し挙動が異なります。ハンドオフ が実行されると、進行中のセッションは新しい エージェント 構成で更新されます。このため、エージェント は進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 +通常のエージェントと異なり、ハンドオフは Realtime Agents では少し異なる動作になります。ハンドオフが行われると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 -さらに、これにより、`voice` や `model` は ハンドオフ の一部として変更できません。また、接続できるのは他の リアルタイムエージェント のみです。異なるモデル、たとえば `gpt-5-mini` のような推論モデルを使う必要がある場合は、[delegation through tools](#delegation-through-tools) を使用できます。 +さらに、これはハンドオフの一部として `voice` や `model` を変更できないことを意味します。接続できるのは他の Realtime Agents のみです。別のモデル、例えば `gpt-5-mini` のような推論モデルが必要な場合は、[ツールによる委譲](#delegation-through-tools) を使用できます。 ## ツール -通常の エージェント と同様に、リアルタイムエージェント は ツール を呼び出してアクションを実行できます。通常の エージェント で使用するのと同じ `tool()` 関数を使って ツール を定義できます。 +通常のエージェントと同様に、Realtime Agents はツールを呼び出してアクションを実行できます。通常のエージェントで使用するのと同じ `tool()` 関数でツールを定義できます。 -リアルタイムエージェント では使用できるのは 関数ツール のみで、これらのツールは リアルタイムセッション と同じ場所で実行されます。つまり、ブラウザで リアルタイムセッション を実行している場合は、ツールもブラウザで実行されます。より機微なアクションを実行する必要がある場合は、ツール内からバックエンド サーバー への HTTP リクエストを行えます。 +Realtime Agents で使用できるのは関数ツールのみで、これらのツールは Realtime Session と同じ場所で実行されます。つまり、ブラウザで Realtime Session を実行している場合、ツールもブラウザで実行されます。より機密性の高いアクションを行う必要がある場合は、ツール内からバックエンド サーバーへ HTTP リクエストを送ることができます。 -ツールの実行中、エージェント は ユーザー からの新しいリクエストを処理できません。体験を改善する 1 つの方法は、エージェント にツールを実行しようとしていることをアナウンスさせたり、ツールを実行する時間を稼ぐために特定のフレーズを話すよう指示したりすることです。 +ツールの実行中、エージェントはユーザーからの新しいリクエストを処理できません。体験を改善する方法の 1 つは、ツールを実行しようとしていることを事前にアナウンスするようにエージェントに指示したり、ツールの実行時間を稼ぐための特定のフレーズを話すようにすることです。 ### 会話履歴へのアクセス -エージェント が特定の ツール を呼び出したときの引数に加えて、リアルタイムセッション によって追跡されている現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[tools for delegation](#delegation-through-tools) を使用する予定がある場合に便利です。 +エージェントが特定のツールを呼び出した際の引数に加えて、Realtime Session が追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[委譲のためのツール](#delegation-through-tools) を使う予定がある場合に便利です。 ### ツール実行前の承認 -`needsApproval: true` でツールを定義すると、エージェント はツールを実行する前に `tool_approval_requested` イベントを発行します。 +`needsApproval: true` でツールを定義すると、エージェントはツールを実行する前に `tool_approval_requested` イベントを発行します。 -このイベントを監視することで、ツール呼び出しを承認または拒否するための UI を ユーザー に表示できます。 +このイベントを監視して、ツール呼び出しを承認または拒否するための UI をユーザーに表示できます。 ## ガードレール -ガードレール は、エージェント の発話が一連のルールに違反していないかを監視し、即座にレスポンスを遮断する手段を提供します。これらの ガードレール チェックは、エージェント のレスポンスの書き起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効です）。 +ガードレールは、エージェントの発話が一連のルールに違反していないか監視し、応答を即座に遮断する手段を提供します。これらのガードレールチェックはエージェントの応答の文字起こしに基づいて行われるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効）。 -提供した ガードレール は、モデル レスポンスの返却と同時に非同期で実行され、あらかじめ定義した分類トリガー（例: 「特定の禁止ワードに言及した」）に基づいてレスポンスを遮断できます。 +提供されたガードレールは、モデル応答の返却と同時に非同期で実行されます。これにより、例えば「特定の禁止ワードへの言及」のような事前定義された分類トリガーに基づいて、応答を遮断できます。 -ガードレール が作動すると、セッションは `guardrail_tripped` イベントを発行します。イベントには、ガードレール をトリガーした `itemId` を含む `details` オブジェクトも含まれます。 +ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。イベントは、ガードレールをトリガーした `itemId` を含む `details` オブジェクトも提供します。 -デフォルトでは、ガードレール は 100 文字ごと、またはレスポンステキストの末尾で実行されます。テキストの発話は通常それより長くかかるため、ほとんどの場合、 ユーザー が聞く前に ガードレール が違反を検知できます。 +デフォルトでは、ガードレールは 100 文字ごと、または応答テキストの末尾で実行されます。音声で読み上げる方が通常は時間がかかるため、ほとんどの場合、ユーザーが聞く前にガードレールが違反を検知できます。 -この動作を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡せます。 +この動作を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡してください。 ## ターン検出 / 音声活動検出 -リアルタイムセッション は ユーザー が話しているとき自動的に検出し、組み込みの [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使って新しいターンをトリガーします。 +Realtime Session は、ユーザーが話しているタイミングを自動検出し、組み込みの [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使って新しいターンをトリガーします。 `turnDetection` オブジェクトをセッションに渡すことで、音声活動検出モードを変更できます。 -ターン検出設定を調整することで、望ましくない割り込みの調整や無音への対応が改善できます。さまざまな設定の詳細については、[Realtime API documentation for more details on the different settings](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` メソッドを使用します。 -これは、エージェント との対話を両方のモダリティで ユーザー に提供したい場合や、会話に追加のコンテキストを提供したい場合に役立ちます。 +エージェントとのやり取りに両方のモダリティをユーザーに有効化したい場合や、会話に追加のコンテキストを提供したい場合に便利です。 ## 会話履歴の管理 -`RealtimeSession` は `history` プロパティで会話履歴を自動的に管理します: +`RealtimeSession` は `history` プロパティで会話履歴を自動管理します。 -これを使用して、顧客に履歴を表示したり、追加の処理を実行したりできます。この履歴は会話の進行中に継続的に変化するため、`history_updated` イベントをリッスンできます。 +これを使って履歴をユーザーにレンダリングしたり、追加の処理を行えます。会話中は履歴が継続的に変化するため、`history_updated` イベントを監視できます。 -履歴を変更したい場合（たとえばメッセージを完全に削除したり、その書き起こしを更新したりする場合）は、`updateHistory` メソッドを使用できます。 +履歴を変更したい場合（メッセージを完全に削除する、文字起こしを更新するなど）は、`updateHistory` メソッドを使用します。 ### 制限事項 -1. 現時点では 関数ツール 呼び出しを事後に更新/変更できません -2. 履歴内のテキスト出力には、書き起こしとテキストモダリティが有効である必要があります -3. 割り込みにより切り詰められたレスポンスには書き起こしがありません +1. 現在、関数ツールの呼び出しは後から更新/変更できません +2. 履歴のテキスト出力には、文字起こしとテキストモダリティが有効である必要があります +3. 割り込みによって切り詰められた応答には文字起こしがありません -## delegation through tools +## ツールによる委譲 -![Delegation through tools](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) +![ツールによる委譲](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) -会話履歴と ツール呼び出しを組み合わせることで、会話を別のバックエンド エージェント に委譲して、より複雑なアクションを実行し、その結果を ユーザー に返せます。 +会話履歴とツール呼び出しを組み合わせることで、より複雑なアクションの実行を別のバックエンド エージェントに委譲し、その結果をユーザーに返すことができます。 -以下のコードは サーバー 上で実行されます。この例では Next.js の 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 c6af16d0..039ddc3a 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. **はじめての Agent の作成** +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` の内部で継続的に稼働し、リッスンします。このセッションは音声処理、中断、その他多くのライフサイクル機能も処理します。これらは後ほど説明します。 + 通常のエージェントと異なり、音声エージェントは会話とモデルへの接続を継続的に扱う `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 サーバー を起動し、新しい リアルタイムエージェント のコードを含むページに移動します。マイクへのアクセス許可を求めるリクエストが表示されるはずです。許可すると、エージェントに話しかけられるようになります。 + Web サーバーを起動し、新しい Realtime Agent のコードを含むページに移動します。マイクアクセスの許可を求めるリクエストが表示されるはずです。アクセスを許可すると、エージェントに話しかけられるようになります。 ```bash npm run dev @@ -114,16 +114,16 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t ## 次のステップ -ここからは、独自の音声エージェントの設計と構築を開始できます。音声エージェントには通常のエージェントと同じ機能が多数含まれますが、独自の機能もいくつか備えています。 +ここからは、独自の音声エージェントの設計と構築を始められます。音声エージェントは通常のエージェントと多くの共通機能を持ちながら、独自の機能も備えています。 -- 音声エージェントに次の機能を付与する方法を学ぶ +- 音声エージェントに次の機能を追加する方法を学ぶ - [ツール](/openai-agents-js/ja/guides/voice-agents/build#tools) - [ハンドオフ](/openai-agents-js/ja/guides/voice-agents/build#handoffs) - [ガードレール](/openai-agents-js/ja/guides/voice-agents/build#guardrails) - [音声の割り込みへの対応](/openai-agents-js/ja/guides/voice-agents/build#audio-interruptions) - [セッション履歴の管理](/openai-agents-js/ja/guides/voice-agents/build#session-history) -- さまざまなトランスポート層についてさらに学ぶ +- 異なるトランスポート層についてさらに学ぶ - [WebRTC](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-webrtc) - [WebSocket](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-websocket) - - [独自のトランスポート機構の構築](/openai-agents-js/ja/guides/voice-agents/transport#building-your-own-transport-mechanism) + - [独自のトランスポートメカニズムの構築](/openai-agents-js/ja/guides/voice-agents/transport#building-your-own-transport-mechanism) diff --git a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx index c2141868..6eb866ff 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx @@ -26,48 +26,48 @@ import transportEventsExample from '../../../../../../../examples/docs/voice-age import thinClientExample from '../../../../../../../examples/docs/voice-agents/thinClient.ts?raw'; import cloudflareTransportExample from '../../../../../../../examples/docs/extensions/cloudflare-basic.ts?raw'; -## 既定のトランスポートレイヤー +## デフォルトのトランスポート層 -### WebRTC 経由での接続 +### WebRTC 接続 -既定のトランスポートレイヤーは WebRTC を使用します。音声はマイクから録音され、自動的に再生されます。 +既定のトランスポート層は WebRTC を使用します。音声はマイクから録音され、自動的に再生されます。 -独自のメディアストリームや audio 要素を使うには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定します。 +独自のメディアストリームや audio 要素を使用するには、セッション作成時に `OpenAIRealtimeWebRTC` インスタンスを指定します。 -### WebSocket 経由での接続 +### WebSocket 接続 -WebRTC の代わりに WebSocket 接続を使用するには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これはサーバーサイドのユースケース、たとえば Twilio で電話エージェントを構築する場合によく適しています。 +WebRTC の代わりに WebSocket 接続を使用するには、セッション作成時に `transport: 'websocket'` または `OpenAIRealtimeWebSocket` のインスタンスを渡します。これはサーバーサイドのユースケース、たとえば Twilio で電話エージェントを構築する場合に有効です。 -任意の録音/再生ライブラリを使用して、元の PCM16 音声バイトを扱ってください。 +任意の録音/再生ライブラリを使用して、元 PCM16 音声バイトを処理します。 -#### Cloudflare Workers (workerd) に関する注意 +#### Cloudflare Workers（workerd）に関する注意 -Cloudflare Workers や他の workerd ランタイムは、グローバルな `WebSocket` コンストラクタを使って外向きの WebSocket を開くことができません。拡張機能パッケージの Cloudflare トランスポートを使用してください。これは内部で `fetch()` ベースのアップグレードを実行します。 +Cloudflare Workers やその他の workerd ランタイムでは、グローバルな `WebSocket` コンストラクターを使って外向きの WebSocket を開くことはできません。extensions パッケージの Cloudflare トランスポートを使用してください。これは内部で `fetch()` ベースのアップグレードを実行します。 -### 独自のトランスポート機構の構築 +### 独自トランスポート機構の構築 -別の speech-to-speech API を使用する場合や独自のカスタムトランスポート機構がある場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` イベントを発火して独自に作成できます。 +別の音声対音声 API を使いたい場合や、独自のカスタムトランスポート機構を持っている場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` イベントを発火することで独自に作成できます。 -## Realtime API をより直接的に操作 +## Realtime API とのより直接的なやり取り -OpenAI Realtime API を使用しつつ、Realtime API により直接アクセスしたい場合は次の 2 つの方法があります。 +OpenAI Realtime API を使用しつつ、Realtime API へより直接的にアクセスしたい場合は、次の 2 つの選択肢があります。 -### オプション 1 - トランスポートレイヤーへのアクセス +### オプション 1 - トランスポート層へのアクセス -`RealtimeSession` のすべての機能の恩恵を受けたい場合は、`session.transport` を通じてトランスポートレイヤーにアクセスできます。 +`RealtimeSession` のあらゆる機能を活用したい場合は、`session.transport` からトランスポート層にアクセスできます。 -トランスポートレイヤーは、受け取ったすべてのイベントを `*` イベントとして発火し、`sendEvent()` メソッドを使用して元のイベントを送信できます。 +トランスポート層は受信したすべてのイベントを `*` イベントで発火し、`sendEvent()` メソッドを使って元のイベントを送信できます。 -### オプション 2 — トランスポートレイヤーのみを使用 +### オプション 2 — トランスポート層のみの利用 -自動ツール実行やガードレールなどが不要な場合、接続と割り込みのみを管理する「薄い」クライアントとしてトランスポートレイヤーを使用することもできます。 +自動ツール実行やガードレールなどが不要な場合は、接続と割り込みのみを管理する「薄い」クライアントとしてトランスポート層だけを使用できます。 diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index e28d57d4..c22604d0 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -19,30 +19,32 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概要 -[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できるようにします。これは、以前のエージェント向け実験である [Swarm](https://github.com/openai/swarm/tree/main) の本番運用向けアップグレードで、[Python 版](https://github.com/openai/openai-agents-python) もあります。Agents SDK にはごく少数の基本コンポーネントがあります。 +[TypeScript 用 OpenAI Agents SDK](https://github.com/openai/openai-agents-js) は、 +抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できるようにします。これは以前のエージェント向け実験である +[Swarm](https://github.com/openai/swarm/tree/main) の本番運用向けアップグレードであり、[Python 版](https://github.com/openai/openai-agents-python) もあります。Agents SDK にはごく少数の基本コンポーネントがあります: -- **エージェント**: instructions と tools を備えた LLM -- **ハンドオフ**: 特定のタスクを他のエージェントに委譲する仕組み -- **ガードレール**: エージェントへの入力を検証できる仕組み +- **エージェント**: instructions と tools を備えた LLMs +- **ハンドオフ**: 特定のタスクでエージェントが他のエージェントに委譲できる機能 +- **ガードレール**: エージェントへの入力を検証できる機能 -TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストなしに実運用アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントフローの可視化とデバッグ、評価、さらにはアプリケーション向けモデルのファインチューニングまで行えます。 +TypeScript と組み合わせることで、これらの基本コンポーネントだけでツールとエージェントの複雑な関係性を表現でき、学習コストをかけずに実アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグでき、評価やアプリ向けモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 -SDK には 2 つの設計原則があります。 +この SDK には 2 つの設計原則があります: -1. 使う価値があるだけの十分な機能を備えつつ、学習を素早くするために基本コンポーネントは少なく -2. すぐに使える一方で、挙動を細かくカスタマイズ可能 +1. 使う価値のある十分な機能を備えつつ、学習が速いよう基本コンポーネントは少なく +2. すぐに使えて良好に動作しつつ、動作内容を細部までカスタマイズ可能に -主な機能は次のとおりです。 +主な機能は次のとおりです: -- **エージェントループ**: ツールの呼び出し、結果の LLM への送信、LLM が完了するまでのループを内蔵 -- **TypeScript ファースト**: 新しい抽象を学ぶのではなく、言語の組み込み機能でエージェントをオーケストレーションし連結 -- **ハンドオフ**: 複数のエージェント間での調整と委譲を可能にする強力な機能 -- **ガードレール**: エージェントと並行して入力のバリデーションやチェックを実行し、失敗した場合は早期に中断 -- **関数ツール**: 任意の TypeScript 関数をツール化し、スキーマ自動生成と Zod によるバリデーションを提供 -- **トレーシング**: ワークフローの可視化、デバッグ、モニタリングに加え、OpenAI の評価、ファインチューニング、蒸留ツールを活用可能 -- **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 +- **エージェントループ**: ツールの呼び出し、結果の LLM への送信、LLM の完了までのループを内蔵 +- **TypeScript ファースト**: 新しい抽象化を学ぶのではなく、言語機能でエージェントをオーケストレーションし連鎖可能 +- **ハンドオフ**: 複数エージェント間の調整と委譲を可能にする強力な機能 +- **ガードレール**: エージェントと並行して入力の検証やチェックを実行し、失敗時は早期に中断 +- **関数ツール**: 任意の TypeScript 関数をツール化し、自動スキーマ生成と Zod による検証を提供 +- **トレーシング**: ワークフローの可視化・デバッグ・監視に加え、OpenAI の評価、ファインチューニング、蒸留ツールを活用可能 +- **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築可能 ## インストール @@ -50,11 +52,11 @@ SDK には 2 つの設計原則があります。 npm install @openai/agents zod@3 ``` -## Hello World のコード例 +## Hello World の例 -(_これを実行する場合は、`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 bbfa1564..f85f822a 100644 --- a/docs/src/content/docs/ko/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ko/extensions/ai-sdk.mdx @@ -7,31 +7,31 @@ 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 모델과 함께 작동합니다. 그러나 다른 모델을 사용하려면, 이 어댑터를 통해 Agents SDK에 연결할 수 있는 다양한 지원 모델을 제공하는 [Vercel의 AI SDK](https://sdk.vercel.ai/)를 사용할 수 있습니다. ## 설정 -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'; @@ -47,8 +47,8 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk @@ -57,9 +57,9 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk -## 프로바이더 메타데이터 전달 +## 제공자 메타데이터 전달 -메시지에 프로바이더별 옵션을 전송해야 한다면 `providerMetadata`를 통해 전달하세요. 값은 하위 AI SDK 모델에 직접 전달됩니다. 예를 들어, Agents SDK에서 다음과 같은 `providerData`는 +메시지와 함께 제공자별 옵션을 보내야 한다면 `providerMetadata`를 통해 전달하세요. 값은 기본 AI SDK 모델로 그대로 전달됩니다. 예를 들어 Agents SDK에서 다음 `providerData`는 ```ts providerData: { diff --git a/docs/src/content/docs/ko/extensions/cloudflare.mdx b/docs/src/content/docs/ko/extensions/cloudflare.mdx index d41fb5c9..a9cf202a 100644 --- a/docs/src/content/docs/ko/extensions/cloudflare.mdx +++ b/docs/src/content/docs/ko/extensions/cloudflare.mdx @@ -6,13 +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()` 기반 업그레이드를 수행하는 전용 전송(transport)을 제공합니다. +Cloudflare Workers 및 기타 workerd 런타임에서는 전역 `WebSocket` 생성자를 사용해 아웃바운드 WebSocket을 열 수 없습니다. 이러한 환경에서 실시간 에이전트를 간단히 연결할 수 있도록, extensions 패키지는 내부적으로 `fetch()` 기반 업그레이드를 수행하는 전용 전송 방식을 제공합니다. @@ -20,17 +20,17 @@ Cloudflare Workers 및 기타 workerd 런타임은 전역 `WebSocket` 생성자 -1. **extensions 패키지를 설치합니다.** +1. **extensions 패키지를 설치하세요.** ```bash npm install @openai/agents-extensions ``` -2. **전송(transport)을 생성하고 세션에 연결합니다.** +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 전송(transport)은 내부적으로 `Upgrade: websocket` 헤더와 함께 `fetch()`를 사용하며, workerd API와 동일하게 소켓 `open` 이벤트를 대기하지 않습니다 -- 이 전송을 사용할 때도 모든 `RealtimeSession` 기능(도구, 가드레일 등)이 정상 동작합니다 +- Cloudflare 전송 방식은 내부적으로 `Upgrade: websocket`과 함께 `fetch()`를 사용하며, 소켓의 `open` 이벤트를 기다리지 않아서 workerd API와 동작이 일치합니다 +- 이 전송 방식을 사용할 때도 모든 `RealtimeSession` 기능(도구, 가드레일 등)은 평소와 동일하게 작동합니다 - 개발 중 상세 로그를 확인하려면 `DEBUG=openai-agents*`를 사용하세요 diff --git a/docs/src/content/docs/ko/extensions/twilio.mdx b/docs/src/content/docs/ko/extensions/twilio.mdx index 3359f436..972d2f4f 100644 --- a/docs/src/content/docs/ko/extensions/twilio.mdx +++ b/docs/src/content/docs/ko/extensions/twilio.mdx @@ -7,36 +7,36 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio는 전화 통화의 원시 오디오를 WebSocket 서버로 보내는 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)를 제공합니다. 이 설정은 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 Twilio에 연결하는 데 사용할 수 있습니다. `websocket` 모드의 기본 Realtime Session 전송 방식을 사용하여 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와의 연결을 처리하는 전용 전송 레이어를 제공합니다. ## 설정 -1. **Twilio 계정과 Twilio 전화번호를 준비하세요.** +1. **Twilio 계정과 Twilio 전화번호를 준비합니다.** -2. **Twilio로부터 이벤트를 수신할 수 있는 WebSocket 서버를 설정하세요.** +2. **Twilio로부터 이벤트를 수신할 수 있는 WebSocket 서버를 설정합니다.** - 로컬에서 개발 중이라면 로컬 서버를 Twilio가 접근할 수 있도록 - [`ngrok`](https://ngrok.io/) 또는 + 로컬에서 개발 중이라면, [`ngrok`](https://ngrok.io/) 또는 [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - 같은 로컬 터널을 구성해야 합니다. Twilio에 연결하는 데 `TwilioRealtimeTransportLayer`를 사용할 수 있습니다. + 같은 로컬 터널을 구성하여 로컬 서버를 Twilio에서 접근 가능하게 해야 합니다. Twilio에 연결하기 위해 `TwilioRealtimeTransportLayer`를 사용할 수 있습니다. -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,34 +54,28 @@ Twilio는 전화 통화의 원시 오디오를 WebSocket 서버로 보내는 [Me -`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의 모든 디버그 로그가 표시됩니다. 또는 `DEBUG=openai-agents:extensions:twilio*`로 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 de0fdeb0..d077cc10 100644 --- a/docs/src/content/docs/ko/guides/agents.mdx +++ b/docs/src/content/docs/ko/guides/agents.mdx @@ -15,37 +15,41 @@ import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agen import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw'; import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw'; -에이전트는 OpenAI Agents SDK의 주요 기본 구성요소입니다. **Agent** 는 다음과 같이 구성된 대형 언어 모델(LLM)입니다. +에이전트는 OpenAI Agents SDK의 주요 빌딩 블록입니다. **에이전트**는 다음으로 구성된 Large Language Model (LLM)입니다: -- **Instructions** – 모델에게 _자신이 누구인지_ 와 _어떻게 응답해야 하는지_ 알려주는 시스템 프롬프트 +- **Instructions** – 모델에게 _자신이 누구인지_ 와 *어떻게 응답해야 하는지*를 알려 주는 시스템 프롬프트 - **Model** – 호출할 OpenAI 모델과 선택적 모델 튜닝 매개변수 - **Tools** – LLM이 작업을 수행하기 위해 호출할 수 있는 함수 또는 API 목록 -이 페이지의 나머지 부분에서는 모든 에이전트 기능을 자세히 설명합니다. +이 페이지의 나머지 부분에서는 모든 에이전트 기능을 자세히 살펴봅니다. --- ## 기본 구성 -`Agent` 생성자는 단일 구성 객체를 받습니다. 가장 자주 사용하는 속성은 아래와 같습니다. +`Agent` 생성자는 단일 구성 객체를 받습니다. 가장 일반적으로 사용하는 속성은 다음과 같습니다. | Property | Required | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `name` | yes | 짧고 사람이 읽을 수 있는 식별자 | | `instructions` | yes | 시스템 프롬프트(문자열 **또는** 함수 – [동적 instructions](#dynamic-instructions) 참고) | -| `model` | no | 모델 이름 **또는** 커스텀 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 구현 | +| `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()`에 전달하는 의존성 주입 객체입니다. 이는 모든 도구, 가드레일, 핸드오프 등으로 전달되며 상태를 저장하거나 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등)를 제공하는 데 유용합니다. -`outputType` 이 제공되면, SDK는 일반 텍스트 대신 자동으로 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)을 사용합니다. +`outputType`이 제공되면, SDK는 plain text 대신 자동으로 +[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용합니다. --- ## 멀티 에이전트 시스템 설계 패턴 -에이전트를 함께 구성하는 방법은 다양합니다. 프로덕션 앱에서 자주 보는 두 가지 패턴은 다음과 같습니다. +에이전트를 함께 구성하는 방법은 다양합니다. 실제 프로덕션 앱에서 자주 보는 두 가지 패턴은 다음과 같습니다: -1. **매니저(agents as tools)** – 중앙 에이전트가 대화를 소유하고 도구로 노출된 특화 에이전트를 호출 -2. **핸드오프** – 초기 에이전트가 사용자의 요청을 파악하면 전체 대화를 전문 에이전트에게 위임 +1. **매니저(도구로서의 에이전트)** – 중앙 에이전트가 대화를 소유하고 도구로 노출된 특화 에이전트를 호출 +2. **핸드오프** – 초기 에이전트가 사용자의 요청을 파악한 후 전체 대화를 전문가에게 위임 -이 접근법들은 상호 보완적입니다. 매니저는 가드레일이나 레이트 리밋을 한 곳에서 적용할 수 있게 해주며, 핸드오프는 각 에이전트가 대화의 제어를 유지하지 않고 단일 작업에 집중할 수 있게 해줍니다. +이 접근 방식들은 상호 보완적입니다. 매니저는 가드레일이나 속도 제한을 한곳에서 강제할 수 있게 해주고, 핸드오프는 각 에이전트가 대화의 제어를 유지하지 않고 단일 작업에 집중할 수 있게 합니다. -### 매니저 (agents as tools) +### 매니저(도구로서의 에이전트) -이 패턴에서 매니저는 제어권을 넘기지 않습니다—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`는 문자열 대신 **함수**가 될 수 있습니다. 이 함수는 현재 `RunContext`와 에이전트 인스턴스를 받아 문자열 _또는_ `Promise`을 반환할 수 있습니다. --- ## 가드레일 -가드레일을 사용하면 사용자 입력과 에이전트 출력을 검증하거나 변환할 수 있습니다. `inputGuardrails` 및 `outputGuardrails` 배열로 구성합니다. 자세한 내용은 [가드레일](/openai-agents-js/ko/guides/guardrails)을 참고하세요. +가드레일을 사용하면 사용자 입력과 에이전트 출력을 검증하거나 변환할 수 있습니다. `inputGuardrails` 및 `outputGuardrails` 배열을 통해 구성합니다. 자세한 내용은 [가드레일](/openai-agents-js/ko/guides/guardrails)을 참조하세요. --- ## 에이전트 복제/복사 -기존 에이전트의 약간 수정된 버전이 필요하신가요? `clone()` 메서드를 사용하세요. 완전히 새로운 `Agent` 인스턴스를 반환합니다. +기존 에이전트를 약간만 수정한 버전이 필요하신가요? 완전히 새로운 `Agent` 인스턴스를 반환하는 `clone()` 메서드를 사용하세요. @@ -145,23 +146,23 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## 도구 사용 강제 -도구를 제공하더라도 LLM이 반드시 호출하는 것은 아닙니다. `modelSettings.tool_choice` 로 도구 사용을 **강제** 할 수 있습니다. +도구를 제공해도 LLM이 반드시 호출하는 것은 아닙니다. `modelSettings.tool_choice`로 도구 사용을 **강제**할 수 있습니다: -1. `'auto'` (기본값) – 도구 사용 여부는 LLM이 결정 -2. `'required'` – LLM은 반드시 도구를 호출해야 함(어떤 도구인지는 선택 가능) -3. `'none'` – LLM은 도구를 호출하지 **말아야 함** -4. 특정 도구 이름, 예: `'calculator'` – 해당 도구를 반드시 호출해야 함 +1. `'auto'`(기본값) – LLM이 도구 사용 여부를 결정 +2. `'required'` – LLM은 _반드시_ 도구를 호출해야 함(어느 도구를 사용할지는 선택 가능) +3. `'none'` – LLM은 도구를 호출하면 **안 됨** +4. 특정 도구 이름(예: `'calculator'`) – 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({ @@ -174,6 +175,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 294ea103..4c0e1e05 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는 최초 import 시 `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 ``` -tool 입력 및 출력을 로깅하지 않으려면: +도구 입력 및 출력 로깅을 비활성화하려면: ```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 41554668..283f8b68 100644 --- a/docs/src/content/docs/ko/guides/context.mdx +++ b/docs/src/content/docs/ko/guides/context.mdx @@ -6,35 +6,35 @@ 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` 같은 콜백, 라이프사이클 훅 등이 포함됩니다 -2. **에이전트/LLM 컨텍스트**: LLM이 응답을 생성할 때 볼 수 있는 정보 +1. 실행 중 코드가 접근할 수 있는 **로컬 컨텍스트**: 도구에 필요한 의존성이나 데이터, `onHandoff` 같은 콜백, 라이프사이클 훅 +2. 응답을 생성할 때 언어 모델이 볼 수 있는 **에이전트/LLM 컨텍스트** ## 로컬 컨텍스트 -로컬 컨텍스트는 `RunContext` 타입으로 표현됩니다. 상태나 의존성을 담을 객체를 만들고 `Runner.run()`에 전달합니다. 모든 도구 호출과 훅은 `RunContext` 래퍼를 받아 해당 객체를 읽거나 수정할 수 있습니다. +로컬 컨텍스트는 `RunContext` 타입으로 표현됩니다. 상태나 의존성을 담을 임의의 객체를 만들고 이를 `Runner.run()`에 전달합니다. 모든 도구 호출과 훅은 `RunContext` 래퍼를 받아 해당 객체를 읽거나 수정할 수 있습니다. -단일 실행에 참여하는 모든 에이전트, 도구, 훅은 동일한 **type**의 컨텍스트를 사용해야 합니다. +단일 실행에 참여하는 모든 에이전트, 도구, 훅은 동일한 컨텍스트의 **type**을 사용해야 합니다. 로컬 컨텍스트는 다음과 같은 용도로 사용하세요: - 실행에 대한 데이터(사용자 이름, ID 등) -- 로거 또는 데이터 페처와 같은 의존성 +- 로거나 데이터 패처 같은 의존성 - 헬퍼 함수 ## 에이전트/LLM 컨텍스트 -LLM이 호출될 때 볼 수 있는 데이터는 대화 기록에서만 옵니다. 추가 정보를 제공하려면 다음 옵션을 사용할 수 있습니다: +LLM이 호출될 때 볼 수 있는 데이터는 대화 히스토리에서만 옵니다. 추가 정보를 제공하려면 다음 옵션을 사용할 수 있습니다: -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. 파일, 데이터베이스 또는 웹의 관련 데이터에 근거해 응답하도록 검색 도구나 웹 검색 도구를 사용합니다 +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. 리트리벌(retrieval) 또는 웹 검색 도구를 사용하여 파일, 데이터베이스, 웹의 관련 데이터에 근거해 응답을 생성합니다. diff --git a/docs/src/content/docs/ko/guides/guardrails.mdx b/docs/src/content/docs/ko/guides/guardrails.mdx index a59c06ab..39bf1fb7 100644 --- a/docs/src/content/docs/ko/guides/guardrails.mdx +++ b/docs/src/content/docs/ko/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'; -가드레일은 에이전트와 _병렬로_ 실행되어 사용자 입력이나 에이전트 출력에 대해 점검과 검증을 수행할 수 있습니다. 예를 들어, 비용이 큰 모델을 호출하기 전에 경량 모델을 가드레일로 실행할 수 있습니다. 가드레일이 악의적인 사용을 감지하면 오류를 발생시켜 비용이 큰 모델의 실행을 중단할 수 있습니다. +가드레일은 에이전트와 함께 병렬로 실행되어, 사용자 입력 또는 에이전트 출력에 대한 검사와 검증을 수행할 수 있게 합니다. 예를 들어, 비용이 큰 모델을 호출하기 전에 경량 모델을 가드레일로 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 오류를 발생시켜 비용이 큰 모델의 실행을 중단할 수 있습니다. 가드레일에는 두 가지 종류가 있습니다: -1. **입력 가드레일**은 초기 사용자 입력에 대해 실행됩니다. -2. **출력 가드레일**은 최종 에이전트 출력에 대해 실행됩니다. +1. **입력 가드레일**은 초기 사용자 입력에서 실행됩니다. +2. **출력 가드레일**은 최종 에이전트 출력에서 실행됩니다. ## 입력 가드레일 입력 가드레일은 세 단계로 실행됩니다: 1. 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다. -2. 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을(를) [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) 안에 감싼 형태로 반환합니다. +2. 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을(를) [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) 안에 감싸 반환합니다. 3. `tripwireTriggered`가 `true`이면 [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) 오류가 발생합니다. -> **Note** -> 입력 가드레일은 사용자 입력을 위한 것이므로, 워크플로에서 에이전트가 _첫 번째_ 에이전트일 때만 실행됩니다. 가드레일은 종종 에이전트마다 다르게 필요하므로 에이전트 자체에 구성합니다. +> **참고** +> 입력 가드레일은 사용자 입력을 위한 것이므로, 워크플로에서 에이전트가 첫 번째 에이전트일 때만 실행됩니다. 가드레일은 에이전트 자체에 구성됩니다. 에이전트마다 요구되는 가드레일이 다른 경우가 많기 때문입니다. ## 출력 가드레일 -출력 가드레일은 동일한 패턴을 따릅니다: +출력 가드레일은 3단계로 실행됩니다: -1. 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다. -2. 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을(를) [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) 안에 감싼 형태로 반환합니다. +1. 가드레일은 에이전트가 생성한 출력을 받습니다. +2. 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을(를) [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) 안에 감싸 반환합니다. 3. `tripwireTriggered`가 `true`이면 [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) 오류가 발생합니다. -> **Note** -> 출력 가드레일은 워크플로에서 에이전트가 _마지막_ 에이전트일 때만 실행됩니다. 실시간 음성 상호작용의 경우 [음성 에이전트 구축](/openai-agents-js/ko/guides/voice-agents/build#guardrails)을 참고하세요. +> **참고** +> 출력 가드레일은 워크플로에서 에이전트가 마지막 에이전트일 때만 실행됩니다. 실시간 음성 상호작용은 [음성 에이전트 구축](/openai-agents-js/ko/guides/voice-agents/build#guardrails)을 참고하세요. ## 트립와이어 -가드레일이 실패하면 트립와이어를 통해 이를 신호합니다. 트립와이어가 트리거되는 즉시 러너는 해당 오류를 발생시키고 실행을 중단합니다. +가드레일이 실패하면 트립와이어를 통해 이를 신호합니다. 트립와이어가 트리거되는 즉시 러너는 해당 오류를 던지고 실행을 중단합니다. ## 가드레일 구현 -가드레일은 `GuardrailFunctionOutput`을 반환하는 단순한 함수입니다. 아래는 내부적으로 또 다른 에이전트를 실행해 사용자가 수학 숙제 도움을 요청하는지 확인하는 최소 예시입니다. +가드레일은 `GuardrailFunctionOutput`을 반환하는 단순한 함수입니다. 아래는 내부적으로 다른 에이전트를 실행하여 사용자가 수학 숙제 도움을 요청하는지 확인하는 최소 예시입니다. -출력 가드레일도 동일한 방식으로 동작합니다. +출력 가드레일도 같은 방식으로 동작합니다. 1. `guardrailAgent`는 가드레일 함수 내부에서 사용됩니다. -2. 가드레일 함수는 에이전트 입력 또는 출력을 받고 결과를 반환합니다. -3. 추가 정보를 가드레일 결과에 포함할 수 있습니다. +2. 가드레일 함수는 에이전트 입력 또는 출력을 받아 결과를 반환합니다. +3. 가드레일 결과에 추가 정보를 포함할 수 있습니다. 4. `agent`는 가드레일이 적용되는 실제 워크플로를 정의합니다. diff --git a/docs/src/content/docs/ko/guides/handoffs.mdx b/docs/src/content/docs/ko/guides/handoffs.mdx index edc123c3..53dfcb9d 100644 --- a/docs/src/content/docs/ko/guides/handoffs.mdx +++ b/docs/src/content/docs/ko/guides/handoffs.mdx @@ -10,50 +10,54 @@ import handoffInputExample from '../../../../../../examples/docs/handoffs/handof import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw'; import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw'; -핸드오프는 에이전트가 대화의 일부를 다른 에이전트에 위임할 수 있게 해 줍니다. 이는 서로 다른 에이전트가 특정 분야를 전문적으로 담당할 때 유용합니다. 예를 들어 고객 지원 앱에서는 예약, 환불 또는 FAQ를 처리하는 에이전트를 둘 수 있습니다. +핸드오프를 사용하면 한 에이전트가 대화의 일부를 다른 에이전트에 위임할 수 있습니다. 이는 서로 다른 에이전트가 특정 영역을 전문으로 할 때 유용합니다. 예를 들어 고객 지원 앱에서는 예약, 환불 또는 FAQ를 처리하는 에이전트를 둘 수 있습니다. -핸드오프는 LLM에 도구로 표현됩니다. `Refund Agent`로 핸드오프하면 도구 이름은 `transfer_to_refund_agent`가 됩니다. +핸드오프는 LLM에게 도구로 표현됩니다. `Refund Agent`라는 에이전트로 핸드오프하는 경우, 도구 이름은 `transfer_to_refund_agent`가 됩니다. ## 핸드오프 생성 -모든 에이전트는 `handoffs` 옵션을 받습니다. 여기에는 다른 `Agent` 인스턴스나 `handoff()` 헬퍼가 반환하는 `Handoff` 객체를 포함할 수 있습니다. +모든 에이전트는 `handoffs` 옵션을 허용합니다. 여기에는 다른 `Agent` 인스턴스나 `handoff()` 헬퍼가 반환하는 `Handoff` 객체를 포함할 수 있습니다. ### 기본 사용 - + ### `handoff()`를 통한 핸드오프 커스터마이징 -`handoff()` 함수로 생성되는 도구를 조정할 수 있습니다. +`handoff()` 함수는 생성되는 도구를 조정할 수 있게 해줍니다. -- `agent` – 핸드오프할 에이전트 +- `agent` – 핸드오프할 대상 에이전트 - `toolNameOverride` – 기본 `transfer_to_` 도구 이름 재정의 - `toolDescriptionOverride` – 기본 도구 설명 재정의 -- `onHandoff` – 핸드오프가 발생할 때 콜백. `RunContext`와 선택적으로 파싱된 입력을 받음 -- `inputType` – 핸드오프에 기대하는 입력 스키마 +- `onHandoff` – 핸드오프 발생 시 콜백. `RunContext`와 선택적으로 파싱된 입력을 받음 +- `inputType` – 핸드오프에 기대되는 입력 스키마 - `inputFilter` – 다음 에이전트에 전달할 히스토리 필터 ## 핸드오프 입력 -때로는 핸드오프를 호출할 때 LLM이 데이터를 제공하도록 하고 싶을 수 있습니다. 입력 스키마를 정의하고 `handoff()`에 사용하세요. +때로는 핸드오프를 호출할 때 LLM이 데이터를 제공하도록 하고 싶을 수 있습니다. 입력 스키마를 정의하고 `handoff()`에서 사용하세요. - + ## 입력 필터 -기본적으로 핸드오프는 전체 대화 히스토리를 받습니다. 다음 에이전트에 전달되는 내용을 수정하려면 `inputFilter`를 제공하세요. -공용 헬퍼는 `@openai/agents-core/extensions`에 있습니다. +기본적으로 핸드오프는 전체 대화 히스토리를 받습니다. 다음 에이전트에 무엇을 전달할지 수정하려면 `inputFilter`를 제공하세요. +공통 헬퍼는 `@openai/agents-core/extensions`에 있습니다. - + ## 권장 프롬프트 -프롬프트에 핸드오프를 언급하면 LLM이 더 안정적으로 응답합니다. SDK는 `RECOMMENDED_PROMPT_PREFIX`를 통해 권장 접두사를 제공합니다. +프롬프트에 핸드오프를 언급하면 LLM이 더 안정적으로 반응합니다. SDK는 `RECOMMENDED_PROMPT_PREFIX`를 통해 권장 접두사를 제공합니다. - + 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 42fff1bb..e58a9a32 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) 지원을 사용하여 인간 개입에 따라 에이전트 실행을 일시 중지하고 재개하는 방법을 보여줍니다. 현재 주요 사용 사례는 민감한 도구 실행에 대한 승인을 요청하는 것입니다. @@ -18,49 +18,49 @@ 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` 는 전체 실행을 트리거한 원래 에이전트입니다. +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)를 참고하세요. -## 더 긴 승인 시간 처리 +## 장시간 승인 처리 -휴먼인더루프 흐름은 서버를 계속 실행하지 않고도 오랜 시간 인터럽트될 수 있도록 설계되었습니다. 요청을 종료하고 나중에 계속해야 하는 경우 상태를 직렬화하여 이후에 재개할 수 있습니다. +휴먼인더루프 흐름은 서버를 계속 실행하지 않고도 오랜 시간 동안 인터럽트 가능하도록 설계되었습니다. 요청을 종료하고 나중에 계속해야 하는 경우 상태를 직렬화하여 나중에 재개할 수 있습니다. -`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 bf52eae7..b181b30b 100644 --- a/docs/src/content/docs/ko/guides/mcp.mdx +++ b/docs/src/content/docs/ko/guides/mcp.mdx @@ -13,111 +13,103 @@ 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는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화한 개방형 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB‑C 포트라고 생각해 보세요. USB‑C가 다양한 주변기기와 액세서리에 기기를 표준 방식으로 연결하듯이, MCP는 AI 모델을 서로 다른 데이터 소스와 도구에 표준 방식으로 연결합니다. +> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. 이 SDK가 지원하는 MCP 서버 유형은 세 가지입니다: 1. **호스티드 MCP 서버 도구** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp)가 도구로 사용하는 원격 MCP 서버 -2. **Streamable HTTP MCP 서버** – [Streamable HTTP 전송](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http)을 구현한 로컬 또는 원격 서버 -3. **Stdio MCP 서버** – 표준 입출력을 통해 접근하는 서버(가장 간단한 옵션) +2. **Streamable HTTP MCP 서버** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http)를 구현하는 로컬 또는 원격 서버 +3. **Stdio MCP 서버** – 표준 입력/출력을 통해 접근하는 서버(가장 간단한 옵션) 사용 사례에 따라 서버 유형을 선택하세요: -| 필요한 것 | 권장 옵션 | -| ----------------------------------------------------------------- | ------------------------ | -| 공개 접근 가능한 원격 서버를 기본 OpenAI Responses 모델로 호출 | **1. 호스티드 MCP 도구** | -| 공개 접근 가능한 원격 서버를 사용하되 도구 호출은 로컬에서 트리거 | **2. Streamable HTTP** | -| 로컬에서 실행 중인 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | -| OpenAI Responses 이외의 모델과 함께 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | -| 표준 입출력 프로토콜만 지원하는 로컬 MCP 서버 사용 | **3. Stdio** | +| 필요한 작업 | 추천 옵션 | +| -------------------------------------------------------------------- | ------------------------ | +| 공용으로 접근 가능한 원격 서버를 기본 OpenAI Responses 모델로 호출 | **1. 호스티드 MCP 도구** | +| 공용 원격 서버를 사용하되 도구 호출은 로컬에서 트리거 | **2. Streamable HTTP** | +| 로컬에서 실행 중인 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | +| OpenAI-Responses가 아닌 모델과 함께 어떤 Streamable HTTP 서버든 사용 | **2. Streamable HTTP** | +| 표준 I/O 프로토콜만 지원하는 로컬 MCP 서버와 작업 | **3. Stdio** | ## 1. 호스티드 MCP 서버 도구 -호스티드 툴은 전체 왕복 과정을 모델 내부로 밀어 넣습니다. 코드가 MCP 서버를 직접 호출하는 대신, OpenAI Responses API가 원격 도구 엔드포인트를 호출하고 결과를 모델로 스트리밍합니다. +호스티드 도구는 전체 라운드 트립을 모델 내부로 넣습니다. 코드가 MCP 서버를 호출하는 대신 OpenAI Responses API가 원격 도구 엔드포인트를 호출하고 결과를 모델로 스트리밍합니다. -다음은 호스티드 MCP 도구를 사용하는 가장 간단한 예시입니다. 원격 MCP 서버의 레이블과 URL을 `hostedMcpTool` 유틸리티 함수에 전달할 수 있으며, 호스티드 MCP 서버 도구를 만들 때 유용합니다. +다음은 호스티드 MCP 도구를 사용하는 가장 간단한 예시입니다. 원격 MCP 서버의 라벨과 URL을 `hostedMcpTool` 유틸리티 함수에 전달하여 호스티드 MCP 서버 도구를 만들 수 있습니다. 그런 다음 `run` 함수(또는 커스터마이즈한 `Runner` 인스턴스의 `run` 메서드)로 에이전트를 실행할 수 있습니다: - + -증분 MCP 결과를 스트리밍하려면 `Agent`를 실행할 때 `stream: true`를 전달하세요: +점진적인 MCP 결과를 스트리밍하려면 `Agent`를 실행할 때 `stream: true`를 전달하세요: -#### 선택적 승인 플로우 +#### 승인 흐름(옵션) -민감한 작업의 경우 개별 도구 호출에 대한 사람의 승인을 요구할 수 있습니다. `requireApproval: 'always'` 또는 도구 이름을 `'never'`/`'always'`에 매핑하는 세밀한 객체를 전달하세요. +민감한 작업의 경우 개별 도구 호출에 대해 사람의 승인을 요구할 수 있습니다. `requireApproval: 'always'` 또는 도구 이름을 `'never'`/`'always'`에 매핑하는 세분화된 객체를 전달하세요. -도구 호출의 안전성을 프로그램적으로 판단할 수 있다면 [`onApproval` 콜백](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts)을 사용해 승인 또는 거부할 수 있습니다. 사람의 승인이 필요하다면 로컬 함수 도구와 동일하게 `interruptions`를 사용하는 [휴먼 인 더 루프 (HITL) 접근 방식](/openai-agents-js/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)에 있습니다. +완전히 동작하는 샘플(호스티드 도구/Streamable HTTP/stdio + 스트리밍, 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 서버 -표준 입출력만 노출하는 서버의 경우 `fullCommand`로 `MCPServerStdio`를 인스턴스화하세요: +표준 I/O만 노출하는 서버의 경우 `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) – 위에서 언급한 실행 가능한 diff --git a/docs/src/content/docs/ko/guides/models.mdx b/docs/src/content/docs/ko/guides/models.mdx index 1a4a9980..a068fa8f 100644 --- a/docs/src/content/docs/ko/guides/models.mdx +++ b/docs/src/content/docs/ko/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는 모델을 두 가지 가벼운 인터페이스 뒤로 추상화합니다: +모든 에이전트는 궁극적으로 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 모델 -이 방법으로 GPT-5의 어떤 reasoning 모델([`gpt-5`](https://platform.openai.com/docs/models/gpt-5), [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini), [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano))을 사용하면, SDK가 기본적으로 합리적인 `modelSettings`를 적용합니다. 구체적으로 `reasoning.effort`와 `verbosity`를 모두 `"low"`로 설정합니다. 기본 모델에 대한 reasoning effort를 조정하려면 사용자 정의 `modelSettings`를 전달하세요: +이 방식으로 GPT-5의 추론 모델([`gpt-5`](https://platform.openai.com/docs/models/gpt-5), [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini), [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano))을 사용할 때, SDK는 합리적인 기본 `modelSettings`를 적용합니다. 구체적으로 `reasoning.effort`와 `verbosity`를 모두 `"low"`로 설정합니다. 기본 모델의 추론 강도를 조정하려면 직접 `modelSettings`를 전달하세요: -더 낮은 지연 시간을 원한다면, [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 또는 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)에 `reasoning.effort="minimal"`을 사용하면 기본 설정보다 더 빠르게 응답하는 경우가 많습니다. 다만 Responses API의 일부 내장 도구(예: 파일 검색과 이미지 생성)는 `"minimal"` reasoning effort를 지원하지 않으므로, 이 Agents SDK의 기본값은 `"low"`입니다. +더 낮은 지연 시간을 원한다면 [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 또는 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)를 `reasoning.effort="minimal"`과 함께 사용하면 기본 설정보다 더 빠르게 응답을 반환하는 경우가 많습니다. 다만 Responses API의 일부 내장 도구(예: 파일 검색과 이미지 생성)는 `"minimal"` 추론 강도를 지원하지 않으므로, 이 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')` _(기본값)_ | +| API | 사용처 | `setOpenAIAPI()` 호출 | +| ---------------- | ----------------------------------------------------- | --------------------------------------- | +| Chat Completions | 표준 채팅 및 함수 호출 | `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,25 +90,25 @@ node my-awesome-agent.js `ModelSettings`는 OpenAI 매개변수를 반영하지만 공급자에 구애받지 않습니다. -| Field | Type | Notes | +| 필드 | 타입 | 비고 | | ------------------- | ------------------------------------------ | -------------------------------------------------------------------------- | -| `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 등에서의 reasoning effort | -| `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,11 +116,11 @@ node my-awesome-agent.js 에이전트는 `prompt` 매개변수로 구성할 수 있으며, 이는 에이전트의 동작을 제어하기 위해 서버에 저장된 프롬프트 구성을 사용해야 함을 나타냅니다. 현재 이 옵션은 OpenAI [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용할 때만 지원됩니다. -| Field | Type | Notes | -| ----------- | -------- | ---------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | 프롬프트의 고유 식별자 | -| `version` | `string` | 사용하려는 프롬프트의 버전 | -| `variables` | `object` | 프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열 또는 텍스트, 이미지, 파일과 같은 콘텐츠 입력 타입일 수 있음 | +| 필드 | 타입 | 비고 | +| ----------- | -------- | -------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | 프롬프트의 고유 식별자 | +| `version` | `string` | 사용하려는 프롬프트의 버전 | +| `variables` | `object` | 프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열 또는 텍스트, 이미지, 파일 등의 콘텐츠 입력 타입일 수 있음 | -tools나 instructions 같은 추가 에이전트 구성은 저장된 프롬프트에 구성해 둔 값을 오버라이드합니다. +tools 또는 instructions와 같은 추가 에이전트 구성은 저장된 프롬프트에 구성했을 수 있는 값을 재정의합니다. --- -## 사용자 정의 모델 공급자 +## 사용자 정의 모델 프로바이더 -자체 공급자를 구현하는 것은 간단합니다 – `ModelProvider`와 `Model`을 구현하고 공급자를 `Runner` 생성자에 전달하세요: +직접 프로바이더를 구현하는 것은 간단합니다 – `ModelProvider`와 `Model`을 구현하고 프로바이더를 `Runner` 생성자에 전달하세요: --- -## 트레이싱 내보내기 +## 트레이싱 익스포터 -OpenAI 공급자를 사용할 때 API 키를 제공하면 자동 추적 내보내기를 옵트인할 수 있습니다: +OpenAI 프로바이더를 사용할 때 API 키를 제공하여 자동 트레이스 내보내기를 옵트인할 수 있습니다: -이는 [OpenAI 대시보드](https://platform.openai.com/traces)로 트레이스를 전송하며, 거기에서 워크플로의 전체 실행 그래프를 확인할 수 있습니다. +이는 [OpenAI 대시보드](https://platform.openai.com/traces)로 트레이스를 전송하며, 워크플로의 전체 실행 그래프를 확인할 수 있습니다. --- ## 다음 단계 - [에이전트 실행](/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 49b2fd9a..2898d4ee 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 및 핸드오프로 장비된 LLM입니다. 이는 개방형 과제가 주어졌을 때, LLM이 도구를 사용해 행동하고 데이터를 획득하며, 핸드오프를 통해 하위 에이전트에 작업을 위임하는 방식으로 과제를 처리할 계획을 자율적으로 수립할 수 있음을 의미합니다. 예를 들어, 리서치 에이전트는 다음과 같은 도구를 갖출 수 있습니다: +에이전트는 instructions, tools, handoffs를 갖춘 LLM입니다. 이는 개방형 작업이 주어졌을 때, LLM이 도구를 사용해 행동하고 데이터를 수집하며, 핸드오프를 통해 하위 에이전트에게 작업을 위임하는 방식으로 스스로 작업 계획을 수립할 수 있음을 의미합니다. 예를 들어, 리서치 에이전트는 다음과 같은 도구를 갖출 수 있습니다: -- 웹 검색을 통한 온라인 정보 탐색 -- 파일 검색 및 검색 기능을 통한 사내 데이터와 연결 검색 +- 웹 검색을 통한 온라인 정보 수집 +- 파일 검색 및 검색 기능을 통한 사내 데이터와 연결 탐색 - 컴퓨터 사용을 통한 컴퓨터 상의 작업 수행 - 코드 실행을 통한 데이터 분석 - 계획 수립, 보고서 작성 등에 특화된 에이전트로의 핸드오프 -이 패턴은 과제가 개방형이고 LLM의 지능에 의존하고자 할 때 유용합니다. 여기서 중요한 전술은 다음과 같습니다: +이 패턴은 작업이 개방형이고 LLM의 지능에 의존하고자 할 때 적합합니다. 여기서 가장 중요한 전술은 다음과 같습니다: -1. 좋은 프롬프트에 투자하세요. 사용 가능한 도구, 사용 방법, 그리고 준수해야 할 매개변수를 명확히 하세요. -2. 앱을 모니터링하고 반복 개선하세요. 어디서 문제가 발생하는지 확인하고 프롬프트를 개선하세요. -3. 에이전트가 자기 성찰하고 개선할 수 있게 하세요. 예를 들어 루프로 실행하여 스스로를 비평하게 하거나, 오류 메시지를 제공해 개선하게 하세요. +1. 좋은 프롬프트에 투자하세요. 사용 가능한 도구, 사용 방법, 반드시 지켜야 할 매개변수를 명확히 하세요. +2. 앱을 모니터링하고 반복 개선하세요. 어디서 문제가 생기는지 확인하고 프롬프트를 개선하세요. +3. 에이전트가 자기 성찰하고 개선하도록 하세요. 예를 들어 루프로 실행해 스스로 비평하게 하거나, 오류 메시지를 제공해 개선하도록 하세요. 4. 모든 일을 잘하는 범용 에이전트 대신 하나의 작업에 특화된 에이전트를 두세요. -5. [evals](https://platform.openai.com/docs/guides/evals)에 투자하세요. 이를 통해 에이전트를 학습시키고 과제 수행 능력을 향상할 수 있습니다. +5. [evals](https://platform.openai.com/docs/guides/evals)에 투자하세요. 이를 통해 에이전트를 학습시켜 작업 수행 능력을 개선할 수 있습니다. ## 코드 기반 오케스트레이션 -LLM 기반 오케스트레이션이 강력하지만, 코드 기반 오케스트레이션은 속도, 비용, 성능 측면에서 작업을 더 결정론적이고 예측 가능하게 만듭니다. 일반적인 패턴은 다음과 같습니다: +LLM을 통한 오케스트레이션이 강력하긴 하지만, 코드 기반 오케스트레이션은 속도, 비용, 성능 면에서 작업을 더 결정론적이고 예측 가능하게 만듭니다. 일반적인 패턴은 다음과 같습니다: -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성. 예를 들어, 에이전트에게 작업을 몇 가지 카테고리로 분류하도록 요청한 다음, 카테고리에 따라 다음 에이전트를 선택할 수 있음 -- 한 에이전트의 출력을 다음 에이전트의 입력으로 변환해 여러 에이전트를 체이닝. 블로그 글쓰기를 리서치, 개요 작성, 본문 작성, 비평, 개선의 일련의 단계로 분해할 수 있음 -- 작업을 수행하는 에이전트를 `while` 루프로 실행하고, 평가 및 피드백을 제공하는 에이전트와 함께 evaluator가 출력이 특정 기준을 통과했다고 말할 때까지 반복 -- `Promise.all` 같은 JavaScript 기본 컴포넌트를 통해 여러 에이전트를 병렬로 실행. 서로 의존하지 않는 여러 작업이 있을 때 속도 면에서 유용 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사 가능한 적절한 형식의 데이터를 생성. 예를 들어, 에이전트에게 작업을 몇 가지 카테고리로 분류하게 한 뒤 해당 카테고리에 따라 다음 에이전트를 선택할 수 있습니다. +- 한 에이전트의 출력을 다음 에이전트의 입력으로 변환해 여러 에이전트를 체이닝. 블로그 글쓰기를 연구, 개요 작성, 본문 작성, 비평, 개선의 일련의 단계로 분해할 수 있습니다. +- 수행 에이전트와 이를 평가하고 피드백을 제공하는 에이전트를 `while` 루프로 함께 실행하고, 평가자가 출력이 특정 기준을 통과한다고 말할 때까지 반복 +- `Promise.all` 같은 JavaScript 기본 구성 요소를 통해 여러 에이전트를 병렬로 실행. 서로 의존하지 않는 여러 작업이 있을 때 속도 향상에 유용합니다. -[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns)에 다양한 code examples가 있습니다. +[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns)에 여러 code examples가 있습니다. diff --git a/docs/src/content/docs/ko/guides/quickstart.mdx b/docs/src/content/docs/ko/guides/quickstart.mdx index 9a9cea67..33a641f0 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 @@ -25,21 +25,21 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm install @openai/agents zod@3 ``` -3. OpenAI API 키를 설정하세요. 없다면 OpenAI API 키를 생성하려면 [이 가이드](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따라주세요. +3. OpenAI API 키를 설정하세요. 키가 없다면 [이 안내](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따라 OpenAI API 키를 생성하세요. ```bash export OPENAI_API_KEY=sk-... ``` - 또는 `setDefaultOpenAIKey('')`를 호출하여 프로그래밍 방식으로 키를 설정하고, - 트레이싱에는 `setTracingExportApiKey('')`를 사용할 수 있습니다. - 자세한 내용은 [SDK 설정](/openai-agents-js/ko/guides/config)을 참조하세요. + 또는 `setDefaultOpenAIKey('')`를 호출하여 프로그램적으로 키를 설정하고, + 트레이싱을 위해 `setTracingExportApiKey('')`를 사용할 수 있습니다. + 자세한 내용은 [SDK 설정](/openai-agents-js/ko/guides/config)을 참고하세요. ## 첫 에이전트 생성 -에이전트는 instructions와 이름으로 정의합니다. +에이전트는 instructions와 이름으로 정의됩니다. ```typescript import { Agent } from '@openai/agents'; @@ -53,9 +53,9 @@ const agent = new Agent({ ## 첫 에이전트 실행 -`run` 메서드를 사용해 에이전트를 실행할 수 있습니다. 시작할 에이전트와 전달할 입력을 함께 넘기면 실행됩니다. +`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'; @@ -149,23 +149,23 @@ async function main() { 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 a1bafaa8..bcbb226f 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` 형식의 다소 수정된 의미적 버전 관리를 따릅니다. 앞의 `0`은 SDK가 여전히 빠르게 발전 중임을 나타냅니다. 각 구성 요소는 다음과 같이 증가합니다: +이 프로젝트는 `0.Y.Z` 형식의 의미적 버전 관리(semantic versioning)를 약간 수정해 따릅니다. 앞의 `0`은 SDK가 여전히 빠르게 발전 중임을 의미합니다. 각 구성 요소는 다음과 같이 증가합니다. -## 마이너(`Y`) 버전 +## 마이너 (`Y`) 버전 -베타로 표시되지 않은 공개 인터페이스에 대한 **호환성 파괴 변경**이 있을 때 마이너 버전 `Y`를 증가시킵니다. 예를 들어 `0.0.x`에서 `0.1.x`로의 변경에는 호환성 파괴 변경이 포함될 수 있습니다. +베타로 표시되지 않은 퍼블릭 인터페이스에 **호환성 파괴 변경**이 있을 때 마이너 버전 `Y`를 올립니다. 예를 들어 `0.0.x`에서 `0.1.x`로 올라갈 때 호환성 파괴 변경이 포함될 수 있습니다. -호환성 파괴 변경을 원치 않으면, 프로젝트에서 `0.0.x` 버전에 고정할 것을 권장합니다. +호환성 파괴 변경을 원하지 않는 경우, 프로젝트에서 `0.0.x` 버전으로 고정할 것을 권장합니다. -## 패치(`Z`) 버전 +## 패치 (`Z`) 버전 -호환성 파괴가 없는 변경에 대해 `Z`를 증가시킵니다: +호환성을 깨지 않는 변경에 대해 `Z`를 증가시킵니다: - 버그 수정 -- 신규 기능 -- 비공개 인터페이스 변경 +- 새로운 기능 +- 프라이빗 인터페이스 변경 - 베타 기능 업데이트 ## 서브 패키지 버전 관리 -메인 `@openai/agents` 패키지는 독립적으로 사용할 수 있는 여러 서브 패키지로 구성됩니다. 현재는 패키지들의 버전이 연결되어 있어, 하나의 패키지 버전이 증가하면 다른 패키지도 함께 증가합니다. `1.0.0`으로 이동하면서 이 전략을 변경할 수 있습니다. +메인 `@openai/agents` 패키지는 독립적으로 사용할 수 있는 여러 서브 패키지로 구성됩니다. 현재는 패키지들의 버전이 연결되어 있어, 하나의 패키지 버전이 올라가면 다른 패키지도 함께 올라갑니다. `1.0.0`으로 이동하면서 이 전략을 변경할 수 있습니다. ## 변경 로그 -무엇이 변경되었는지 이해를 돕기 위해 각 서브 패키지에 대한 변경 로그를 생성합니다. 변경이 특정 서브 패키지에서 발생했을 수 있으므로, 해당 변경에 대한 세부 정보는 그 패키지의 변경 로그를 확인해야 할 수 있습니다. +무엇이 변경되었는지 이해할 수 있도록 각 서브 패키지별로 변경 로그를 생성합니다. 변경이 특정 서브 패키지에서 발생했을 수 있으므로, 해당 변경에 대한 자세한 내용은 해당 변경 로그를 확인해야 할 수 있습니다. - [`@openai/agents`](https://github.com/openai/openai-agents-js/blob/main/packages/agents/CHANGELOG.md) - [`@openai/agents-core`](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/CHANGELOG.md) diff --git a/docs/src/content/docs/ko/guides/results.mdx b/docs/src/content/docs/ko/guides/results.mdx index 9a637f78..96c60885 100644 --- a/docs/src/content/docs/ko/guides/results.mdx +++ b/docs/src/content/docs/ko/guides/results.mdx @@ -7,23 +7,23 @@ import { Code } from '@astrojs/starlight/components'; import handoffFinalOutputTypes from '../../../../../../examples/docs/results/handoffFinalOutputTypes.ts?raw'; import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts?raw'; -[에이전트 실행](/openai-agents-js/ko/guides/running-agents)을 하면 다음 중 하나를 받게 됩니다: +[에이전트 실행](/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`을 호출한 경우 [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult). 스트리밍에 대한 자세한 내용은 [스트리밍](/openai-agents-js/ko/guides/streaming)도 확인하세요. ## 최종 출력 -`finalOutput` 속성은 마지막으로 실행된 에이전트의 최종 출력을 포함합니다. 이 결과는 다음 중 하나입니다: +`finalOutput` 속성에는 마지막으로 실행된 에이전트의 최종 출력이 포함됩니다. 결과는 다음 중 하나입니다: - `string` — `outputType`이 정의되지 않은 모든 에이전트의 기본값 -- `unknown` — 에이전트가 출력 타입으로 JSON 스키마를 정의한 경우. 이 경우 JSON 은 파싱되었지만 타입을 수동으로 검증해야 합니다 -- `z.infer` — 에이전트가 출력 타입으로 Zod 스키마를 정의한 경우. 출력은 자동으로 해당 스키마에 대해 파싱됩니다 +- `unknown` — 에이전트가 출력 타입으로 JSON 스키마를 정의한 경우. 이 경우 JSON은 파싱되지만 타입은 직접 검증해야 합니다. +- `z.infer` — 에이전트가 출력 타입으로 Zod 스키마를 정의한 경우. 출력은 자동으로 해당 스키마에 맞게 파싱됩니다. - `undefined` — 에이전트가 출력을 생성하지 않은 경우(예: 출력을 생성하기 전에 중지된 경우) -서로 다른 출력 타입을 가진 핸드오프를 사용하는 경우, 에이전트를 만들 때 `new Agent()` 생성자 대신 `Agent.create()` 메서드를 사용해야 합니다. +서로 다른 출력 타입을 갖는 핸드오프를 사용하는 경우, 에이전트를 생성할 때 `new Agent()` 생성자 대신 `Agent.create()` 메서드를 사용해야 합니다. -이렇게 하면 SDK 가 가능한 모든 핸드오프 전반에 걸쳐 출력 타입을 추론하고 `finalOutput` 속성에 대해 유니온 타입을 제공할 수 있습니다. +이렇게 하면 SDK가 가능한 모든 핸드오프 전반에서 출력 타입을 추론하고 `finalOutput` 속성에 대한 유니온 타입을 제공합니다. 예: @@ -33,56 +33,56 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? title="핸드오프 최종 출력 타입" /> -## 다음 턴 입력 +## 다음 턴을 위한 입력 다음 턴의 입력에 접근하는 방법은 두 가지가 있습니다: -- `result.history` — 입력과 에이전트의 출력이 모두 복사본으로 포함됨 +- `result.history` — 입력과 에이전트 출력의 사본이 포함됨 - `result.output` — 전체 에이전트 실행의 출력이 포함됨 -`history`는 채팅과 유사한 사용 사례에서 전체 히스토리를 유지하기에 편리합니다: +`history`는 채팅과 같은 사용 사례에서 전체 히스토리를 유지하기에 편리한 방법입니다: ## 마지막 에이전트 -`lastAgent` 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라, 이는 다음에 사용자가 무언가를 입력할 때 유용한 경우가 많습니다. 예를 들어, 1차 분류를 담당하는 에이전트가 언어별 에이전트로 핸드오프하는 경우, 마지막 에이전트를 저장해 두고 사용자가 다음에 메시지를 보낼 때 재사용할 수 있습니다. +`lastAgent` 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라, 이는 다음 번에 사용자가 무언가를 입력할 때 유용한 경우가 많습니다. 예를 들어, 프런트라인 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우, 마지막 에이전트를 저장해 두었다가 사용자가 다음에 에이전트에게 메시지를 보낼 때 재사용할 수 있습니다. 스트리밍 모드에서는 현재 실행 중인 에이전트에 매핑되는 `currentAgent` 속성에 접근하는 것도 유용할 수 있습니다. ## 새 항목 -`newItems` 속성에는 실행 중에 생성된 새 항목이 포함됩니다. 항목은 [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem)입니다. 실행 항목은 LLM 이 생성한 원문 항목을 래핑합니다. 이를 통해 LLM 의 출력 외에도 어떤 에이전트와 연관된 이벤트인지 접근할 수 있습니다. +`newItems` 속성에는 실행 중에 생성된 새 항목이 포함됩니다. 항목은 [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem)s입니다. 실행 항목은 LLM이 생성한 원문 항목을 감쌉니다. 이를 사용해 LLM의 출력 외에도 이러한 이벤트가 어떤 에이전트와 연관되어 있는지 접근할 수 있습니다. -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem)은 LLM 의 메시지를 나타냅니다. 원문 항목은 생성된 메시지입니다 -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem)은 LLM 이 핸드오프 도구를 호출했음을 나타냅니다. 원문 항목은 LLM 의 도구 호출 항목입니다 -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem)은 핸드오프가 발생했음을 나타냅니다. 원문 항목은 핸드오프 도구 호출에 대한 도구 응답입니다. 또한 항목에서 소스/타깃 에이전트에 접근할 수 있습니다 -- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem)은 LLM 이 도구를 호출했음을 나타냅니다 -- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem)은 도구가 호출되었음을 나타냅니다. 원문 항목은 도구 응답입니다. 또한 항목에서 도구 출력을 확인할 수 있습니다 -- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem)은 LLM 의 추론 항목을 나타냅니다. 원문 항목은 생성된 추론입니다 -- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem)은 LLM 이 도구 호출에 대한 승인을 요청했음을 나타냅니다. 원문 항목은 LLM 의 도구 호출 항목입니다 +- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem)은 LLM의 메시지를 나타냅니다. 원문 항목은 생성된 메시지입니다. +- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem)은 LLM이 핸드오프 도구를 호출했음을 나타냅니다. 원문 항목은 LLM의 도구 호출 항목입니다. +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem)은 핸드오프가 발생했음을 나타냅니다. 원문 항목은 핸드오프 도구 호출에 대한 도구 응답입니다. 항목에서 소스/타깃 에이전트에도 접근할 수 있습니다. +- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem)은 LLM이 도구를 호출했음을 나타냅니다. +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem)은 도구가 호출되었음을 나타냅니다. 원문 항목은 도구 응답입니다. 항목에서 도구 출력에도 접근할 수 있습니다. +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem)은 LLM의 추론 항목을 나타냅니다. 원문 항목은 생성된 추론입니다. +- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem)은 LLM이 도구 호출에 대한 승인을 요청했음을 나타냅니다. 원문 항목은 LLM의 도구 호출 항목입니다. ## 상태 -`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)가 필요하거나 [`interruption`](#interruptions)을 처리해야 하는 경우 이후의 `run` 호출에 대한 입력으로도 사용할 수 있습니다. -## 인터럽션 +## 인터럽션(중단 처리) -에이전트에서 `needsApproval`을 사용하는 경우, 계속하기 전에 처리해야 하는 일부 `interruptions`가 트리거될 수 있습니다. 이 경우 `interruptions`는 인터럽션을 유발한 `ToolApprovalItem`의 배열이 됩니다. 인터럽션을 처리하는 방법에 대한 자세한 내용은 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop) 가이드를 확인하세요. +에이전트에서 `needsApproval`을 사용하는 경우, 계속 진행하기 전에 처리해야 하는 `interruptions`가 트리거될 수 있습니다. 이 경우 `interruptions`는 인터럽션을 유발한 `ToolApprovalItem`s의 배열이 됩니다. 인터럽션을 처리하는 방법에 대한 자세한 내용은 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop) 가이드를 확인하세요. ## 기타 정보 ### 원문 응답 -`rawResponses` 속성에는 에이전트 실행 동안 모델이 생성한 원문 LLM 응답이 포함됩니다. +`rawResponses` 속성에는 에이전트 실행 중 모델이 생성한 원문 LLM 응답이 포함됩니다. ### 마지막 응답 ID -`lastResponseId` 속성에는 에이전트 실행 동안 모델이 생성한 마지막 응답의 ID 가 포함됩니다. +`lastResponseId` 속성에는 에이전트 실행 중 모델이 생성한 마지막 응답의 ID가 포함됩니다. ### 가드레일 결과 -`inputGuardrailResults`와 `outputGuardrailResults` 속성에는 가드레일 결과(있는 경우)가 포함됩니다. 가드레일 결과에는 로그를 남기거나 저장하고 싶은 유용한 정보가 포함되는 경우가 있으므로, 이를 확인할 수 있도록 제공합니다. +`inputGuardrailResults`와 `outputGuardrailResults` 속성에는(있는 경우) 가드레일 결과가 포함됩니다. 가드레일 결과에는 로깅하거나 저장하고 싶은 유용한 정보가 들어 있는 경우가 있어, 이를 제공해 드립니다. ### 원본 입력 diff --git a/docs/src/content/docs/ko/guides/running-agents.mdx b/docs/src/content/docs/ko/guides/running-agents.mdx index 619741e7..e4113f03 100644 --- a/docs/src/content/docs/ko/guides/running-agents.mdx +++ b/docs/src/content/docs/ko/guides/running-agents.mdx @@ -11,125 +11,125 @@ 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` 인스턴스를 실행하는 `run()` 유틸리티를 사용할 수 있습니다. +커스텀 runner가 필요 없다면 싱글톤 기본 `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) 발생 ### Runner 수명 주기 -앱이 시작될 때 `Runner`를 만들고 요청 간에 재사용하세요. 인스턴스는 모델 제공자와 트레이싱 옵션 같은 전역 구성을 저장합니다. 완전히 다른 설정이 필요할 때만 다른 `Runner`를 생성하세요. 간단한 스크립트에서는 내부적으로 기본 러너를 사용하는 `run()`을 호출할 수도 있습니다. +앱 시작 시 `Runner`를 생성하고 요청 간 재사용하세요. 인스턴스는 모델 제공자 및 트레이싱 옵션 같은 전역 구성을 저장합니다. 완전히 다른 설정이 필요할 때만 다른 `Runner`를 생성하세요. 간단한 스크립트의 경우 내부적으로 기본 runner를 사용하는 `run()`을 호출할 수도 있습니다. ## 실행 인수 -`run()` 메서드의 입력은 실행을 시작할 초기 에이전트, 실행 입력, 옵션 집합입니다. +`run()` 메서드의 입력은 실행을 시작할 초기 에이전트, 실행 입력, 그리고 옵션 세트입니다. -입력은 문자열(사용자 메시지로 간주), [입력 항목](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) 목록, 또는 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop) 에이전트를 구축하는 경우 [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) 객체일 수 있습니다. +입력은 문자열(사용자 메시지로 간주)일 수도 있고, [입력 항목](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) 리스트일 수도 있으며, [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/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/ko/guides/context) 가이드를 참고하세요. | -| `maxTurns` | `10` | 안전 한도 – 도달 시 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) 발생 | -| `signal` | – | 취소를 위한 `AbortSignal` | +| Option | Default | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `stream` | `false` | `true`이면 호출이 `StreamedRunResult`를 반환하고 모델에서 도착하는 이벤트를 즉시 방출합니다. | +| `context` | – | 모든 tool / guardrail / handoff에 전달되는 컨텍스트 객체입니다. [컨텍스트 관리](/openai-agents-js/ko/guides/context)에서 자세히 보기 | +| `maxTurns` | `10` | 안전 한도 – 도달 시 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)를 던집니다. | +| `signal` | – | 취소를 위한 `AbortSignal` | ## 스트리밍 -스트리밍을 사용하면 LLM 실행 중 스트리밍 이벤트를 추가로 받을 수 있습니다. 스트림이 시작되면 `StreamedRunResult`에는 새로 생성된 모든 출력 등을 포함해 실행에 대한 완전한 정보가 담깁니다. `for await` 루프를 사용해 스트리밍 이벤트를 반복 처리할 수 있습니다. 자세한 내용은 [스트리밍](/openai-agents-js/ko/guides/streaming) 가이드를 참조하세요. +스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트를 추가로 받을 수 있습니다. 스트림이 시작되면 `StreamedRunResult`에는 실행에 대한 전체 정보와 새로 생성된 모든 출력이 포함됩니다. `for await` 루프를 사용해 스트리밍 이벤트를 순회할 수 있습니다. 자세한 내용은 [스트리밍](/openai-agents-js/ko/guides/streaming) 가이드를 참고하세요. ## 실행 구성 -자체 `Runner` 인스턴스를 만드는 경우 러너를 구성하기 위해 `RunConfig` 객체를 전달할 수 있습니다. +자체 `Runner` 인스턴스를 생성하는 경우, runner를 구성하기 위해 `RunConfig` 객체를 전달할 수 있습니다. -| Field | Type | Purpose | -| --------------------------- | --------------------- | ------------------------------------------------------------------------ | -| `model` | `string \| Model` | 실행의 **모든** 에이전트에 대해 특정 모델 강제 지정 | -| `modelProvider` | `ModelProvider` | 모델 이름 확인 – 기본값은 OpenAI 제공자 | -| `modelSettings` | `ModelSettings` | 에이전트별 설정을 재정의하는 전역 튜닝 매개변수 | -| `handoffInputFilter` | `HandoffInputFilter` | 핸드오프 수행 시 입력 항목 변환(핸드오프 자체에 정의되어 있지 않은 경우) | -| `inputGuardrails` | `InputGuardrail[]` | 초기 사용자 입력에 적용되는 가드레일 | -| `outputGuardrails` | `OutputGuardrail[]` | 최종 출력에 적용되는 가드레일 | -| `tracingDisabled` | `boolean` | OpenAI 트레이싱 완전 비활성화 | -| `traceIncludeSensitiveData` | `boolean` | 스팬은 내보내되 트레이스에서 LLM/도구 입력 및 출력을 제외 | -| `workflowName` | `string` | Traces 대시보드에 표시 – 관련 실행을 그룹화하는 데 도움 | -| `traceId` / `groupId` | `string` | SDK가 생성하지 않고 트레이스 또는 그룹 ID를 수동 지정 | -| `traceMetadata` | `Record` | 모든 스팬에 첨부할 임의의 메타데이터 | +| Field | Type | Purpose | +| --------------------------- | --------------------- | --------------------------------------------------------------------------------- | +| `model` | `string \| Model` | 실행의 **모든** 에이전트에 대해 특정 모델을 강제합니다. | +| `modelProvider` | `ModelProvider` | 모델 이름을 확인합니다. 기본값은 OpenAI 제공자입니다. | +| `modelSettings` | `ModelSettings` | 에이전트별 설정을 재정의하는 전역 튜닝 매개변수입니다. | +| `handoffInputFilter` | `HandoffInputFilter` | 핸드오프 수행 시 입력 항목을 변형합니다(핸드오프 자체가 이미 정의하지 않은 경우). | +| `inputGuardrails` | `InputGuardrail[]` | 초기 사용자 입력에 적용되는 가드레일입니다. | +| `outputGuardrails` | `OutputGuardrail[]` | 최종 출력에 적용되는 가드레일입니다. | +| `tracingDisabled` | `boolean` | OpenAI 트레이싱을 완전히 비활성화합니다. | +| `traceIncludeSensitiveData` | `boolean` | 스팬은 계속 방출하면서도 트레이스에서 LLM/도구 입력 및 출력을 제외합니다. | +| `workflowName` | `string` | Traces 대시에 표시되며 관련 실행을 그룹화하는 데 도움이 됩니다. | +| `traceId` / `groupId` | `string` | SDK가 생성하도록 두는 대신 트레이스 또는 그룹 ID를 수동으로 지정합니다. | +| `traceMetadata` | `Record` | 모든 스팬에 첨부할 임의의 메타데이터입니다. | -## 대화 / 채팅 스레드 +## 대화/채팅 스레드 -각 `runner.run()`(또는 `run()` 유틸리티) 호출은 애플리케이션 수준 대화의 한 번의 **턴**을 나타냅니다. 최종 사용자에게 `RunResult` 중 얼마나 보여줄지는 선택 사항입니다. 때로는 `finalOutput`만, 때로는 생성된 모든 항목을 보여줍니다. +각 `runner.run()` 호출(또는 `run()` 유틸리티)은 애플리케이션 수준 대화에서 하나의 **턴**을 나타냅니다. 최종 사용자에게 `RunResult` 중 얼마나 보여줄지는 선택하면 됩니다. 때로는 `finalOutput`만, 다른 때는 생성된 모든 항목을 보여줄 수 있습니다. 대화형 버전은 [채팅 예제](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts)를 참고하세요. -### 서버 관리 대화 +### 서버 관리형 대화 -매 턴마다 전체 로컬 대화 기록을 보내는 대신 OpenAI Responses API가 대화 이력을 유지하도록 할 수 있습니다. 이는 긴 대화나 여러 서비스를 조율할 때 유용합니다. 자세한 내용은 [대화 상태 가이드](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는 서버 측 상태를 재사용하는 두 가지 방법을 제공합니다: -#### 1. 전체 대화를 위한 `conversationId` +#### 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) – 모델이 잘못된 출력 생성(예: malformed 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) – 구성 또는 사용자 입력을 기반으로 발생한 오류 +- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 함수 도구 호출 중 하나 실패 +- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 구성 또는 사용자 입력에 기반해 발생한 오류 -모두 기본 `AgentsError` 클래스를 확장하며, 현재 실행 상태에 접근하기 위한 `state` 속성을 제공할 수 있습니다. +모두 기본 `AgentsError` 클래스를 확장하며, 현재 실행 상태에 접근할 수 있는 `state` 속성을 제공할 수 있습니다. -다음은 `GuardrailExecutionError`를 처리하는 예제 코드입니다: +다음은 `GuardrailExecutionError`를 처리하는 예시 코드입니다: -스트리밍이 활성화되면 반환된 `stream`은 `AsyncIterable` 인터페이스를 구현합니다. 각 생성된 이벤트는 실행 중에 발생한 일을 설명하는 객체입니다. 스트림은 에이전트 실행의 서로 다른 부분을 설명하는 세 가지 이벤트 유형 중 하나를 생성합니다. 대부분의 애플리케이션은 모델의 텍스트만 원하므로, 스트림은 이를 위한 헬퍼를 제공합니다. +스트리밍이 활성화되면 반환된 `stream`은 `AsyncIterable` 인터페이스를 구현합니다. 각 전달된 이벤트는 실행 내에서 발생한 일을 설명하는 객체입니다. 스트림은 에이전트 실행의 서로 다른 부분을 설명하는 세 가지 이벤트 타입 중 하나를 전달합니다. +대부분의 애플리케이션은 모델의 텍스트만 원하므로, 스트림은 이를 위한 도우미를 제공합니다. -### 텍스트 출력 가져오기 +### 텍스트 출력 받기 -`stream.toTextStream()`을 호출하여 방출된 텍스트의 스트림을 얻을 수 있습니다. `compatibleWithNodeStreams`가 `true`이면 반환값은 일반 Node.js `Readable`입니다. 이를 `process.stdout` 또는 다른 목적지로 직접 파이프할 수 있습니다. +발생한 텍스트의 스트림을 얻으려면 `stream.toTextStream()`을 호출하세요. `compatibleWithNodeStreams`가 `true`이면 반환값은 일반 Node.js `Readable`입니다. `process.stdout` 또는 다른 대상을 향해 직접 파이프할 수 있습니다. -프로미스 `stream.completed`는 실행과 모든 보류 중인 콜백이 완료되면 resolve됩니다. 더 이상 출력이 없음을 보장하려면 항상 이를 await 하세요. +`stream.completed` 프라미스는 실행과 보류 중인 모든 콜백이 완료되면 resolve됩니다. 더 이상 출력이 없음을 보장하려면 항상 이를 기다리세요. ### 모든 이벤트 수신 -`for await` 루프를 사용하여 이벤트가 도착할 때마다 검사할 수 있습니다. 유용한 정보에는 저수준 모델 이벤트, 에이전트 전환, 그리고 SDK 고유의 실행 정보가 포함됩니다: +`for await` 루프를 사용해 도착하는 각 이벤트를 검사할 수 있습니다. 유용한 정보에는 로우 레벨 모델 이벤트, 에이전트 전환, 그리고 SDK 고유의 실행 정보가 포함됩니다: -전체 텍스트 스트림과 원문 이벤트 스트림을 모두 출력하는 완전한 스크립트는 [스트리밍 예제](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts)를 참고하세요. +[스트리밍 예제](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts)를 참고하면 일반 텍스트 스트림과 원문 이벤트 스트림을 모두 출력하는 완성된 스크립트를 볼 수 있습니다. ## 이벤트 타입 -스트림은 세 가지 다른 이벤트 타입을 생성합니다: +스트림은 세 가지 서로 다른 이벤트 타입을 전달합니다: ### raw_model_stream_event @@ -120,7 +121,7 @@ type RunAgentUpdatedStreamEvent = { ## 스트리밍 중 휴먼인더루프 (HITL) -스트리밍은 실행을 일시 중지하는 핸드오프(예: 도구가 승인 필요)를 지원합니다. 스트림 객체의 `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: true }` 옵션은 제공된 호출에만 적용됩니다. `RunState`로 다시 실행하는 경우 옵션을 다시 지정해야 합니다 +- 애플리케이션이 텍스트 결과만 필요하다면 개별 이벤트 객체를 다루지 않도록 `toTextStream()`을 사용하는 것이 좋습니다 -스트리밍과 이벤트 시스템을 통해 에이전트를 채팅 인터페이스, 터미널 애플리케이션, 또는 사용자에게 점진적 업데이트가 유용한 어떤 곳에든 통합할 수 있습니다. +스트리밍과 이벤트 시스템을 통해 에이전트를 채팅 인터페이스, 터미널 애플리케이션, 또는 점진적 업데이트가 유용한 모든 곳에 통합할 수 있습니다. diff --git a/docs/src/content/docs/ko/guides/tools.mdx b/docs/src/content/docs/ko/guides/tools.mdx index 5232a574..226c2f04 100644 --- a/docs/src/content/docs/ko/guides/tools.mdx +++ b/docs/src/content/docs/ko/guides/tools.mdx @@ -10,12 +10,12 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -도구는 에이전트가 **행동을 수행**하도록 합니다. 데이터 가져오기, 외부 API 호출, 코드 실행, 심지어 컴퓨터 사용까지 할 수 있습니다. JavaScript/TypeScript SDK는 네 가지 카테고리를 지원합니다: +도구는 에이전트가 **행동을 수행**하도록 합니다 – 데이터 가져오기, 외부 API 호출, 코드 실행, 심지어 컴퓨터 사용까지. JavaScript/TypeScript SDK는 네 가지 카테고리를 지원합니다: 1. **호스티드 툴** – OpenAI 서버에서 모델과 함께 실행됩니다. _(웹 검색, 파일 검색, 컴퓨터 사용, Code Interpreter, 이미지 생성)_ -2. **함수 도구** – LLM이 호출할 수 있도록 로컬 함수를 JSON 스키마로 래핑합니다. -3. **에이전트를 도구로 사용** – 전체 에이전트를 호출 가능한 도구로 노출합니다. -4. **로컬 MCP 서버** – 로컬에서 실행 중인 Model context protocol 서버를 연결합니다. +2. **함수 도구** – 로컬 함수를 JSON 스키마로 래핑하여 LLM이 호출할 수 있게 합니다. +3. **도구로서의 에이전트** – 전체 에이전트를 호출 가능한 도구로 노출합니다. +4. **로컬 MCP 서버** – 내 머신에서 실행되는 Model Context Protocol 서버를 연결합니다. --- @@ -23,68 +23,64 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer `OpenAIResponsesModel`을 사용할 때 다음 내장 도구를 추가할 수 있습니다: -| Tool | Type string | Purpose | -| ----------------------- | -------------------- | -------------------------------------- | -| Web search | `'web_search'` | 인터넷 검색 | -| File / retrieval search | `'file_search'` | OpenAI에서 호스팅하는 벡터 스토어 질의 | -| Computer use | `'computer'` | GUI 상호작용 자동화 | -| Code Interpreter | `'code_interpreter'` | 샌드박스 환경에서 코드 실행 | -| Image generation | `'image_generation'` | 텍스트 기반 이미지 생성 | +| 도구 | Type 문자열 | 목적 | +| ---------------- | -------------------- | ------------------------------------ | +| 웹 검색 | `'web_search'` | 인터넷 검색 | +| 파일 / 검색 | `'file_search'` | OpenAI가 호스팅하는 벡터 스토어 조회 | +| 컴퓨터 사용 | `'computer'` | GUI 상호작용 자동화 | +| Code Interpreter | `'code_interpreter'` | 샌드박스 환경에서 코드 실행 | +| 이미지 생성 | `'image_generation'` | 텍스트 기반 이미지 생성 | - + -정확한 매개변수 세트는 OpenAI Responses API와 동일합니다. `rankingOptions`나 시맨틱 필터 같은 고급 옵션은 공식 문서를 참고하세요. +정확한 매개변수 세트는 OpenAI Responses API와 동일합니다 – `rankingOptions`나 시맨틱 필터 같은 고급 옵션은 공식 문서를 참고하세요. --- ## 2. 함수 도구 -`tool()` 헬퍼로 **어떤** 함수든 도구로 만들 수 있습니다. +`tool()` 헬퍼로 **어떤** 함수든 도구로 바꿀 수 있습니다. ### 옵션 레퍼런스 -| Field | Required | Description | -| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `name` | No | 기본값은 함수 이름입니다 (예: `get_weather`) | -| `description` | Yes | LLM에 표시되는 명확하고 사람이 읽을 수 있는 설명 | -| `parameters` | Yes | Zod 스키마 또는 원문 JSON 스키마 객체. Zod 매개변수를 사용하면 자동으로 **strict** 모드가 활성화됩니다 | -| `strict` | No | `true`(기본값)일 때, 인수가 유효성 검사를 통과하지 못하면 SDK가 모델 오류를 반환합니다. 퍼지 매칭이 필요하면 `false`로 설정하세요 | -| `execute` | Yes | `(args, context) => string \| Promise`– 비즈니스 로직. 두 번째 인자는 선택 사항이며 `RunContext`입니다 | -| `errorFunction` | No | 내부 오류를 사용자에게 보이는 문자열로 변환하는 커스텀 핸들러 `(context, error) => string` | +| 필드 | 필수 | 설명 | +| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | 아니오 | 함수 이름을 기본값으로 사용합니다 (예: `get_weather`) | +| `description` | 예 | LLM에 표시되는 명확하고 사람이 읽기 쉬운 설명 | +| `parameters` | 예 | Zod 스키마 또는 원문 JSON 스키마 객체. Zod parameters를 사용하면 자동으로 **strict** 모드가 활성화됩니다 | +| `strict` | 아니오 | `true`(기본값)일 때 인수가 검증에 실패하면 SDK가 모델 오류를 반환합니다. 흐릿한 매칭이 필요하면 `false`로 설정하세요 | +| `execute` | 예 | `(args, context) => string \| Promise`– 비즈니스 로직. 두 번째 매개변수는 선택 사항이며 `RunContext`입니다 | +| `errorFunction` | 아니오 | 내부 오류를 사용자에게 보이는 문자열로 변환하는 커스텀 핸들러 `(context, error) => string` | -### 비엄격 JSON 스키마 도구 +### 비‑strict JSON‑schema 도구 -유효하지 않거나 부분적인 입력을 모델이 추측하도록 하려면 원문 JSON 스키마 사용 시 strict 모드를 비활성화할 수 있습니다: +모델이 잘못되었거나 불완전한 입력을 _추정_ 하도록 하려면 원문 JSON 스키마를 사용할 때 strict 모드를 비활성화하세요: --- -## 3. 에이전트를 도구로 사용 +## 3. 도구로서의 에이전트 -대화를 완전히 핸드오프하지 않고 한 에이전트가 다른 에이전트를 *보조*하도록 하고 싶을 때 `agent.asTool()`을 사용하세요: +대화를 완전히 핸드오프하지 않고 한 에이전트가 다른 에이전트를 _보조_ 하게 하고 싶을 때가 있습니다. `agent.asTool()`을 사용하세요: - + 내부적으로 SDK는 다음을 수행합니다: -- 단일 `input` 매개변수를 가진 함수 도구를 생성 -- 도구가 호출되면 해당 입력으로 서브 에이전트를 실행 -- 마지막 메시지 또는 `customOutputExtractor`가 추출한 출력을 반환 +- 단일 `input` 매개변수를 가진 함수 도구를 만듭니다 +- 도구가 호출되면 해당 입력으로 하위 에이전트를 실행합니다 +- 마지막 메시지 또는 `customOutputExtractor`로 추출된 출력을 반환합니다 에이전트를 도구로 실행할 때, Agents SDK는 기본 설정으로 러너를 생성하고 함수 실행 내에서 해당 에이전트를 실행합니다. `runConfig` 또는 `runOptions`의 속성을 제공하려면 `asTool()` 메서드에 전달하여 러너 동작을 커스터마이즈할 수 있습니다. @@ -92,32 +88,32 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer ## 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 guide](/openai-agents-js/ko/guides/mcp)를 참조하세요. +완전한 예시는 [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts)를 참조하세요. 또한 MCP 서버 도구 통합에 대한 종합적인 가이드를 찾고 있다면, 자세한 내용은 [모델 컨텍스트 프로토콜 (MCP)](/openai-agents-js/ko/guides/mcp) 가이드를 참고하세요. --- ## 도구 사용 동작 -모델이 도구를 언제, 어떻게 사용해야 하는지 제어하려면 [Agents guide](/openai-agents-js/ko/guides/agents#forcing-tool-use)를 참고하세요 (`tool_choice`, `toolUseBehavior` 등). +모델이 도구를 언제 어떻게 사용해야 하는지(`tool_choice`, `toolUseBehavior` 등)를 제어하려면 [에이전트](/openai-agents-js/ko/guides/agents#forcing-tool-use)를 참고하세요. --- ## 모범 사례 -- **짧고 명확한 설명** – 도구가 _무엇을_ 하는지와 *언제 사용하는지*를 설명하세요 -- **입력 검증** – 가능한 경우 Zod 스키마로 엄격한 JSON 검증을 수행하세요 +- **짧고 명확한 설명** – 도구가 _무엇을_ 하는지와 _언제 사용하는지_ 설명하세요 +- **입력 검증** – 가능하면 Zod 스키마로 엄격한 JSON 검증을 사용하세요 - **에러 핸들러에서 부작용 회피** – `errorFunction`은 예외를 던지지 말고 유용한 문자열을 반환해야 합니다 -- **도구당 하나의 책임** – 작고 조합 가능한 도구가 더 나은 모델 추론을 이끕니다 +- **도구당 하나의 책임** – 작고 조합 가능한 도구가 더 나은 모델 추론으로 이어집니다 --- ## 다음 단계 -- [forcing tool use](/openai-agents-js/ko/guides/agents#forcing-tool-use)에 대해 알아보기 -- 도구 입력 또는 출력을 검증하기 위해 [가드레일](/openai-agents-js/ko/guides/guardrails) 추가 -- [`tool()`](/openai-agents-js/openai/agents/functions/tool) 및 다양한 호스티드 툴 타입에 대한 TypeDoc 레퍼런스 살펴보기 +- [도구 사용 강제](/openai-agents-js/ko/guides/agents#forcing-tool-use)에 대해 알아보세요 +- 도구 입력 또는 출력을 검증하기 위해 [가드레일](/openai-agents-js/ko/guides/guardrails)을 추가하세요 +- [`tool()`](/openai-agents-js/openai/agents/functions/tool) 및 다양한 호스티드 툴 타입에 대한 TypeDoc 레퍼런스를 살펴보세요 diff --git a/docs/src/content/docs/ko/guides/tracing.mdx b/docs/src/content/docs/ko/guides/tracing.mdx index 41a8e979..3df55893 100644 --- a/docs/src/content/docs/ko/guides/tracing.mdx +++ b/docs/src/content/docs/ko/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)를 사용해 개발 중과 프로덕션에서 워크플로를 디버그, 시각화, 모니터링할 수 있습니다. -## 내보내기 루프 수명 주기 +## Export loop 라이프사이클 -대부분의 환경에서는 트레이스가 정기적으로 자동 내보내기됩니다. 브라우저나 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 를 사용할 수 있습니다 - - `disabled`: True 인 경우 트레이스가 기록되지 않습니다 +- **Traces** 는 "워크플로"의 단일 엔드 투 엔드 작업을 나타냅니다. Span으로 구성됩니다. 트레이스는 다음 속성을 가집니다: + - `workflow_name`: 논리적 워크플로 또는 앱 이름. 예: "Code generation" 또는 "Customer service" + - `trace_id`: 트레이스의 고유 ID. 전달하지 않으면 자동 생성. 형식은 `trace_<32_alphanumeric>` 여야 함 + - `group_id`: 선택적 그룹 ID로, 동일한 대화의 여러 트레이스를 연결. 예: 채팅 스레드 ID 사용 가능 + - `disabled`: True인 경우 트레이스가 기록되지 않음 - `metadata`: 트레이스에 대한 선택적 메타데이터 -- **스팬(Spans)** 은 시작 및 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다: +- **Spans** 는 시작 및 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 포함됩니다: - `started_at` 및 `ended_at` 타임스탬프 - - 속한 트레이스를 나타내는 `trace_id` - - 이 스팬의 상위 스팬을 가리키는 `parent_id` (있는 경우) - - 스팬에 대한 정보인 `span_data`. 예를 들어 `AgentSpanData` 는 에이전트에 대한 정보를, `GenerationSpanData` 는 LLM 생성에 대한 정보를 포함합니다 + - 소속 트레이스를 나타내는 `trace_id` + - 이 스팬의 부모 스팬을 가리키는 `parent_id` (있는 경우) + - 스팬에 대한 정보인 `span_data`. 예: `AgentSpanData` 는 에이전트 정보, `GenerationSpanData` 는 LLM 생성 관련 정보 등을 포함 ## 기본 트레이싱 -기본적으로 SDK 는 다음을 트레이싱합니다: +기본적으로 SDK는 다음을 트레이싱합니다: -- 전체 `run()` 또는 `Runner.run()` 이 `Trace` 로 감싸집니다 -- 에이전트가 실행될 때마다 `AgentSpan` 으로 감쌉니다 -- LLM 생성은 `GenerationSpan` 으로 감쌉니다 -- 함수 도구 호출은 각각 `FunctionSpan` 으로 감쌉니다 -- 가드레일은 `GuardrailSpan` 으로 감쌉니다 -- 핸드오프는 `HandoffSpan` 으로 감쌉니다 +- 전체 `run()` 또는 `Runner.run()` 이 `Trace` 로 감싸짐 +- 에이전트가 실행될 때마다 `AgentSpan` 으로 감싸짐 +- LLM 생성은 `GenerationSpan` 으로 감싸짐 +- 함수 도구 호출은 각각 `FunctionSpan` 으로 감싸짐 +- 가드레일은 `GuardrailSpan` 으로 감싸짐 +- 핸드오프는 `HandoffSpan` 으로 감싸짐 -기본적으로 트레이스 이름은 "Agent workflow" 입니다. `withTrace` 를 사용해 이 이름을 설정할 수 있으며, [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) 으로 이름과 기타 속성을 구성할 수 있습니다. +기본적으로 트레이스 이름은 "Agent workflow" 입니다. `withTrace` 를 사용해 이 이름을 설정할 수 있으며, [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) 으로 이름 및 기타 속성을 구성할 수도 있습니다. -또한 [사용자 정의 트레이스 프로세서](#custom-tracing-processors)를 설정해 트레이스를 다른 대상에 전송할 수 있습니다(대체 또는 보조 대상). +또한 [custom trace processors](#custom-tracing-processors) 를 설정하여 트레이스를 다른 대상으로 전송할 수 있습니다(대체 또는 보조 대상으로). ### 음성 에이전트 트레이싱 -기본 OpenAI Realtime API 와 함께 `RealtimeAgent` 및 `RealtimeSession` 을 사용하는 경우, `RealtimeSession` 에서 `tracingDisabled: true` 를 사용하거나 `OPENAI_AGENTS_DISABLE_TRACING` 환경 변수를 사용해 비활성화하지 않는 한 트레이싱은 Realtime API 쪽에서 자동으로 수행됩니다. +기본 OpenAI Realtime API 와 함께 `RealtimeAgent` 및 `RealtimeSession` 을 사용하는 경우, `RealtimeSession` 에서 `tracingDisabled: true` 를 사용하거나 `OPENAI_AGENTS_DISABLE_TRACING` 환경 변수를 사용하지 않는 한 트레이싱은 Realtime API 측에서 자동으로 수행됩니다. 자세한 내용은 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 확인하세요. -## 상위 레벨 트레이스 +## 상위 수준 트레이스 -때로는 여러 번의 `run()` 호출을 단일 트레이스의 일부로 만들고 싶을 수 있습니다. 이 경우 전체 코드를 `withTrace()` 로 감싸면 됩니다. +때때로 여러 번의 `run()` 호출을 단일 트레이스의 일부로 묶고 싶을 수 있습니다. 이때 전체 코드를 `withTrace()` 로 감싸면 됩니다. -1. `withTrace()` 로 `run` 에 대한 두 호출을 감쌌기 때문에, 개별 실행이 두 개의 트레이스를 만드는 대신 전체 트레이스의 일부가 됩니다. +1. 두 번의 `run` 호출이 `withTrace()` 로 감싸져 있으므로, 개별 실행이 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다. ## 트레이스 생성 -[`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) 를 통해 해당 데이터 캡처를 비활성화할 수 있습니다. -## 사용자 정의 트레이싱 프로세서 +## 커스텀 트레이싱 프로세서 트레이싱의 상위 수준 아키텍처는 다음과 같습니다: -- 초기화 시, 트레이스를 생성하고 [`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) 를 통해 접근할 수 있는 전역 [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) 를 생성합니다 -- `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/) 에 전송하고, Exporter 는 OpenAI 백엔드로 배치 전송합니다 -이 기본 설정을 사용자 정의하여 대체 또는 추가 백엔드로 트레이스를 전송하거나 내보내기 동작을 수정하려면 두 가지 옵션이 있습니다: +이 기본 구성을 맞춤화하여 다른 백엔드로 전송하거나 추가 백엔드로 동시에 전송하거나 Exporter 동작을 수정하려면 두 가지 옵션이 있습니다: -1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) 는 트레이스와 스팬이 준비되는 대로 수신할 수 있는 **추가** 트레이스 프로세서를 추가할 수 있게 해줍니다. 이를 통해 OpenAI 백엔드로 트레이스를 보내는 것 외에 자체 처리를 수행할 수 있습니다 -2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) 는 기본 프로세서를 사용자 정의 트레이스 프로세서로 **교체** 할 수 있게 해줍니다. 이는 OpenAI 백엔드로 트레이스가 전송되지 않으며, 그렇게 하도록 하는 `TracingProcessor` 를 포함해야 함을 의미합니다 +1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) 는 트레이스와 스팬이 준비될 때 이를 수신하는 **추가** 트레이스 프로세서를 추가할 수 있게 해줍니다. 이를 통해 OpenAI 백엔드로 전송하는 것과 더불어 자체 처리를 수행할 수 있습니다 +2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) 는 기본 프로세서를 사용자 정의 트레이스 프로세서로 **교체** 할 수 있게 해줍니다. 이 경우 OpenAI 백엔드로 트레이스가 전송되지 않으며, 이를 수행하는 `TracingProcessor` 를 포함해야 합니다 ## 외부 트레이싱 프로세서 목록 diff --git a/docs/src/content/docs/ko/guides/troubleshooting.mdx b/docs/src/content/docs/ko/guides/troubleshooting.mdx index 6973765d..9e97ca8b 100644 --- a/docs/src/content/docs/ko/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ko/guides/troubleshooting.mdx @@ -3,7 +3,7 @@ title: 문제 해결 description: Learn how to troubleshoot issues with the OpenAI Agents SDK. --- -## 지원 환경 +## 지원되는 환경 OpenAI Agents SDK는 다음 서버 환경에서 지원됩니다: @@ -13,20 +13,20 @@ OpenAI Agents SDK는 다음 서버 환경에서 지원됩니다: ### 제한적 지원 -- **Cloudflare Workers**: Agents SDK는 Cloudflare Workers에서 사용할 수 있지만 현재 몇 가지 제한 사항이 있습니다: - - SDK는 현재 `nodejs_compat` 활성화가 필요합니다 - - 요청 종료 시 트레이스를 수동으로 플러시해야 합니다. 자세한 내용은 [트레이싱](/openai-agents-js/ko/guides/tracing#export-loop-lifecycle)을 참조하세요 - - Cloudflare Workers의 `AsyncLocalStorage` 제한적 지원으로 인해 일부 트레이스가 정확하지 않을 수 있습니다 - - 아웃바운드 WebSocket 연결은 fetch 기반 업그레이드를 사용해야 합니다(전역 `WebSocket` 생성자 사용 불가). Realtime의 경우 `@openai/agents-extensions`의 Cloudflare 전송(`CloudflareRealtimeTransportLayer`)을 사용하세요 -- **Browsers**: - - 브라우저에서는 트레이싱이 현재 지원되지 않습니다 +- **Cloudflare Workers**: Agents SDK는 Cloudflare Workers에서 사용할 수 있지만, 현재 다음과 같은 제한이 있습니다: + - SDK는 현재 `nodejs_compat` 활성화가 필요함 + - 트레이스는 요청 종료 시 수동으로 플러시해야 합니다. 자세한 내용은 [트레이싱](/openai-agents-js/ko/guides/tracing#export-loop-lifecycle)을 참조하세요. + - Cloudflare Workers의 `AsyncLocalStorage` 제한적 지원으로 인해 일부 트레이스가 정확하지 않을 수 있음 + - 아웃바운드 WebSocket 연결은 전역 `WebSocket` 생성자가 아닌 fetch 기반 업그레이드를 사용해야 합니다. Realtime의 경우 `@openai/agents-extensions`의 Cloudflare transport(`CloudflareRealtimeTransportLayer`)를 사용하세요. +- **브라우저**: + - 브라우저에서는 현재 트레이싱이 지원되지 않음 - **v8 isolates**: - - 적절한 브라우저 폴리필이 있는 번들러를 사용하면 v8 isolates용으로 SDK를 번들링할 수 있지만, 트레이싱은 작동하지 않습니다 - - v8 isolates는 광범위하게 테스트되지 않았습니다 + - 적절한 브라우저 폴리필을 갖춘 번들러를 사용하면 v8 isolates용으로 SDK를 번들할 수 있지만, 트레이싱은 동작하지 않음 + - v8 isolates는 광범위하게 테스트되지 않음 ## 디버그 로깅 -SDK 사용 중 문제가 발생하면 디버그 로깅을 활성화하여 동작에 대한 추가 정보를 확인할 수 있습니다. +SDK에서 문제가 발생하면 디버그 로깅을 활성화하여 동작에 대한 추가 정보를 확인할 수 있습니다. `DEBUG` 환경 변수를 `openai-agents:*`로 설정하여 디버그 로깅을 활성화하세요. @@ -34,7 +34,7 @@ SDK 사용 중 문제가 발생하면 디버그 로깅을 활성화하여 동작 DEBUG=openai-agents:* ``` -또는 SDK의 특정 부분에 대해서만 디버깅 범위를 지정할 수 있습니다: +또는 SDK의 특정 부분만 대상으로 디버깅할 수 있습니다: - `openai-agents:core` — SDK의 주요 실행 로직 - `openai-agents:openai` — OpenAI API 호출 diff --git a/docs/src/content/docs/ko/guides/voice-agents.mdx b/docs/src/content/docs/ko/guides/voice-agents.mdx index d7c46736..48fa64ea 100644 --- a/docs/src/content/docs/ko/guides/voice-agents.mdx +++ b/docs/src/content/docs/ko/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'; -![실시간 에이전트](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) +![Realtime Agents](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) -음성 에이전트는 OpenAI speech-to-speech 모델을 사용하여 실시간 음성 채팅을 제공합니다. 이들 모델은 스트리밍 오디오, 텍스트, 도구 호출을 지원하며 음성/전화 고객 지원, 모바일 앱 경험, 음성 채팅 같은 애플리케이션에 적합합니다. +Voice Agents는 OpenAI 음성-음성 모델을 사용해 실시간 음성 채팅을 제공합니다. 이 모델들은 오디오, 텍스트, 도구 호출의 스트리밍을 지원하며, 음성/전화 고객 지원, 모바일 앱 경험, 음성 채팅 같은 애플리케이션에 적합합니다. Voice Agents SDK는 [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime)를 위한 TypeScript 클라이언트를 제공합니다. ### 주요 기능 -- WebSocket 또는 WebRTC로 연결 +- WebSocket 또는 WebRTC 연결 - 브라우저와 백엔드 연결 모두에서 사용 가능 - 오디오 및 인터럽션(중단 처리) 처리 - 핸드오프를 통한 멀티 에이전트 오케스트레이션 - 도구 정의 및 호출 -- 모델 출력 모니터링을 위한 커스텀 가드레일 -- 스트리밍 이벤트용 콜백 -- 텍스트와 음성 에이전트 모두에 동일한 컴포넌트 재사용 +- 모델 출력 모니터링을 위한 사용자 정의 가드레일 +- 스트리밍된 이벤트에 대한 콜백 +- 동일한 구성요소를 텍스트 및 음성 에이전트 모두에 재사용 -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/ko/guides/voice-agents/build.mdx b/docs/src/content/docs/ko/guides/voice-agents/build.mdx index 1e9776ce..3027d832 100644 --- a/docs/src/content/docs/ko/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ko/guides/voice-agents/build.mdx @@ -30,117 +30,119 @@ import turnDetectionExample from '../../../../../../../examples/docs/voice-agent ## 오디오 처리 -기본 `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`을 변경할 수 없음을 의미합니다. 다른 실시간 에이전트에만 연결할 수 있습니다. 다른 모델이 필요한 경우, 예를 들어 `gpt-5-mini` 같은 reasoning 모델이 필요한 경우 [delegation through tools](#delegation-through-tools)를 사용할 수 있습니다. +또한, 이 말은 핸드오프의 일부로 `voice` 또는 `model`을 변경할 수 없음을 의미합니다. 다른 Realtime Agents에만 연결할 수 있습니다. 만약 `gpt-5-mini` 같은 추론 모델 등 다른 모델을 사용해야 한다면 [도구를 통한 위임](#delegation-through-tools)을 사용할 수 있습니다. ## 도구 -일반 에이전트와 마찬가지로, 실시간 에이전트는 도구를 호출해 작업을 수행할 수 있습니다. 일반 에이전트에서 사용하는 것과 동일한 `tool()` 함수를 사용해 도구를 정의할 수 있습니다. +일반 에이전트와 마찬가지로 Realtime Agents도 도구를 호출해 작업을 수행할 수 있습니다. 일반 에이전트에서 사용하는 것과 동일한 `tool()` 함수를 사용해 도구를 정의할 수 있습니다. -실시간 에이전트에서는 함수 도구만 사용할 수 있으며, 이러한 도구는 Realtime Session과 동일한 위치에서 실행됩니다. 즉, Realtime Session을 브라우저에서 실행 중이라면 도구도 브라우저에서 실행됩니다. 더 민감한 작업을 수행해야 하는 경우, 도구 내부에서 백엔드 서버로 HTTP 요청을 보낼 수 있습니다. +Realtime Agents에서는 함수 도구만 사용할 수 있으며, 이 도구들은 Realtime 세션과 동일한 위치에서 실행됩니다. 즉, 브라우저에서 Realtime 세션을 실행 중이라면 도구도 브라우저에서 실행됩니다. 더 민감한 작업을 수행해야 하는 경우, 도구 내부에서 백엔드 서버로 HTTP 요청을 보낼 수 있습니다. -도구가 실행되는 동안 에이전트는 user의 새로운 요청을 처리할 수 없습니다. 경험을 개선하는 한 가지 방법은 에이전트가 도구를 실행하기 직전에 이를 알리거나, 도구 실행 시간을 벌기 위한 특정 문구를 말하도록 지시하는 것입니다. +도구가 실행되는 동안 에이전트는 사용자로부터의 새 요청을 처리할 수 없습니다. 경험을 개선하는 한 가지 방법은 에이전트에게 도구를 실행하기 직전임을 알리거나, 도구 실행 시간을 벌기 위해 특정 문구를 말하도록 지시하는 것입니다. -### 대화 기록 접근 +### 대화 내역 접근 -에이전트가 특정 도구를 호출할 때 전달된 인자 외에도, Realtime Session이 추적하는 현재 대화 히스토리의 스냅샷에 접근할 수 있습니다. 이는 현재 대화 상태에 기반해 더 복잡한 작업을 수행해야 하거나 [tools for delegation](#delegation-through-tools)을 사용할 계획일 때 유용합니다. +에이전트가 특정 도구를 호출할 때 전달한 인자 외에도, Realtime 세션이 추적하는 현재 대화 내역의 스냅샷에 접근할 수 있습니다. 이는 현재 대화 상태를 기반으로 더 복잡한 작업을 수행해야 하거나 [도구를 통한 위임](#delegation-through-tools)을 사용할 계획인 경우 유용합니다. ### 도구 실행 전 승인 도구를 `needsApproval: true`로 정의하면, 에이전트는 도구를 실행하기 전에 `tool_approval_requested` 이벤트를 발생시킵니다. -이 이벤트를 수신하여 user에게 도구 호출을 승인 또는 거부하는 UI를 표시할 수 있습니다. +이 이벤트를 수신하여 사용자에게 도구 호출을 승인 또는 거부하는 UI를 표시할 수 있습니다. ## 가드레일 -가드레일은 에이전트가 말한 내용이 규칙을 위반했는지 모니터링하고 즉시 응답을 차단하는 방법을 제공합니다. 이 가드레일 검사는 에이전트 응답의 전사에 기반해 수행되므로 모델의 텍스트 출력이 활성화되어 있어야 합니다(기본적으로 활성화). +가드레일은 에이전트의 발화가 규칙을 위반했는지 모니터링하고 응답을 즉시 차단하는 방법을 제공합니다. 이러한 가드레일 검사는 에이전트 응답의 전사에 기반해 수행되므로 모델의 텍스트 출력이 활성화되어 있어야 합니다(기본값으로 활성화됨). -제공한 가드레일은 모델 응답이 반환되는 동안 비동기적으로 실행되어, 예를 들어 "특정 금지어를 언급" 같은 사전 정의된 분류 트리거에 따라 응답을 차단할 수 있습니다. +제공한 가드레일은 모델 응답이 반환되는 동안 비동기적으로 실행되며, 예를 들어 "특정 금지어를 언급" 같은 사전 정의된 분류 트리거에 따라 응답을 차단할 수 있습니다. -가드레일이 트리거되면 세션은 `guardrail_tripped` 이벤트를 발생시킵니다. 이벤트는 가드레일을 트리거한 `itemId`를 포함하는 `details` 객체도 제공합니다. +가드레일이 작동하면 세션은 `guardrail_tripped` 이벤트를 발생시킵니다. 이벤트에는 가드레일을 트리거한 `itemId`를 포함하는 `details` 객체도 제공됩니다. -기본적으로 가드레일은 100자마다 또는 응답 텍스트가 끝날 때 실행됩니다. 일반적으로 텍스트를 말하는 데 더 오래 걸리므로, 대부분의 경우 user가 듣기 전에 가드레일이 위반을 잡아낼 수 있습니다. +기본적으로 가드레일은 100자마다 또는 응답 텍스트 생성이 끝날 때 실행됩니다. +텍스트를 말하는 데는 보통 더 오래 걸리므로, 대부분의 경우 사용자에게 들리기 전에 +가드레일이 위반을 감지합니다. -이 동작을 수정하려면 세션에 `outputGuardrailSettings` 객체를 전달하면 됩니다. +이 동작을 수정하려면 세션에 `outputGuardrailSettings` 객체를 전달할 수 있습니다. ## 턴 감지 / 음성 활동 감지 -Realtime Session은 사용자가 말할 때를 자동으로 감지하고, Realtime API의 내장 [voice activity detection 모드](https://platform.openai.com/docs/guides/realtime-vad)를 사용해 새로운 턴을 트리거합니다. +Realtime 세션은 사용자가 말할 때를 자동으로 감지하고 Realtime API의 내장된 [voice activity detection 모드](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` 이벤트를 발생시킵니다. 이는 모든 오디오 재생을 즉시 중지하는 데 사용할 수 있습니다(웹소켓 연결에만 해당). -UI에 "중지" 버튼을 제공하는 등 수동 인터럽션을 수행하려면, `interrupt()`를 수동으로 호출할 수 있습니다: +수동 인터럽션을 수행하려는 경우, 예를 들어 UI에 "중지" 버튼을 제공하려면 `interrupt()`를 수동으로 호출할 수 있습니다: -두 경우 모두 Realtime Session은 에이전트의 생성을 인터럽트하고, user에게 말하던 내용을 잘라 내며, 히스토리를 업데이트합니다. +어느 방식이든, Realtime 세션은 에이전트의 생성을 중단하고, 사용자에게 말한 내용에 대한 지식을 잘라내며, 히스토리를 업데이트합니다. -에이전트에 WebRTC로 연결 중인 경우 오디오 출력도 지워집니다. WebSocket을 사용하는 경우, 큐에 재생 대기 중인 오디오의 재생을 중지하는 처리를 직접 수행해야 합니다. +WebRTC로 에이전트에 연결하는 경우 오디오 출력도 지워집니다. WebSocket을 사용하는 경우, 대기열에 재생될 항목의 오디오 재생을 직접 중지하는 처리를 해야 합니다. ## 텍스트 입력 에이전트에 텍스트 입력을 보내려면 `RealtimeSession`의 `sendMessage` 메서드를 사용할 수 있습니다. -이는 user가 에이전트와 두 가지 모달리티 모두로 상호작용하도록 하거나, 대화에 추가 컨텍스트를 제공하려는 경우에 유용합니다. +이는 사용자에게 에이전트와의 양방향 모달리티 인터페이스를 제공하거나 대화에 추가 컨텍스트를 제공하려는 경우에 유용합니다. -## 대화 기록 관리 +## 대화 내역 관리 -`RealtimeSession`은 `history` 속성에서 대화 기록을 자동으로 관리합니다: +`RealtimeSession`은 `history` 속성에서 대화 내역을 자동으로 관리합니다: -이를 사용해 고객에게 히스토리를 렌더링하거나 추가 작업을 수행할 수 있습니다. 대화가 진행되는 동안 히스토리는 지속적으로 변경되므로 `history_updated` 이벤트를 수신할 수 있습니다. +이를 사용해 고객에게 내역을 렌더링하거나 추가 작업을 수행할 수 있습니다. 대화 진행 중에는 이 내역이 지속적으로 변경되므로 `history_updated` 이벤트를 수신할 수 있습니다. 메시지를 완전히 제거하거나 전사를 업데이트하는 등 히스토리를 수정하려면 `updateHistory` 메서드를 사용할 수 있습니다. @@ -148,18 +150,18 @@ UI에 "중지" 버튼을 제공하는 등 수동 인터럽션을 수행하려면 ### 제한 사항 -1. 현재로서는 사후에 함수 도구 호출을 업데이트/변경할 수 없음 -2. 히스토리의 텍스트 출력에는 전사와 텍스트 모달리티가 활성화되어 있어야 함 -3. 인터럽션으로 잘린 응답에는 전사가 없음 +1. 현재로서는 사후에 함수 도구 호출을 업데이트/변경할 수 없습니다 +2. 히스토리의 텍스트 출력은 전사와 텍스트 모달리티가 활성화되어 있어야 합니다 +3. 인터럽션으로 인해 잘린 응답은 전사가 없습니다 ## 도구를 통한 위임 ![도구를 통한 위임](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) -대화 기록과 도구 호출을 결합하여, 더 복잡한 작업을 수행하기 위해 대화를 다른 백엔드 에이전트에 위임하고 그 결과를 user에게 다시 전달할 수 있습니다. +대화 내역과 도구 호출을 결합하면, 대화를 다른 백엔드 에이전트에 위임하여 더 복잡한 작업을 수행하게 한 다음 그 결과를 사용자에게 다시 전달할 수 있습니다. -아래 코드는 서버에서 실행됩니다. 이 예에서는 Next.js의 server actions를 통해 실행됩니다. +아래 코드는 서버에서 실행됩니다. 이 예시는 Next.js의 server actions를 통해 실행됩니다. diff --git a/docs/src/content/docs/ko/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/ko/guides/voice-agents/quickstart.mdx index 2c6f650f..37c0fdf7 100644 --- a/docs/src/content/docs/ko/guides/voice-agents/quickstart.mdx +++ b/docs/src/content/docs/ko/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. **클라이언트 일시 토큰 생성** +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,11 +59,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - 응답에는 최상위에 "value" 문자열이 포함되며, "ek\_" 접두사로 시작합니다. 이 일시 키를 사용해 이후 WebRTC 연결을 설정할 수 있습니다. 이 키는 짧은 시간 동안만 유효하며 재생성이 필요합니다. + 응답에는 최상위에 "value" 문자열이 포함되며, "ek\_" 접두사로 시작합니다. 이 임시 키로 이후 WebRTC 연결을 설정할 수 있습니다. 이 키는 유효 기간이 짧으므로 재생성이 필요합니다. 3. **첫 번째 에이전트 생성** - 새 [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/)를 생성하는 것은 일반 [`Agent`](/openai-agents-js/ko/guides/agents)를 생성하는 것과 매우 유사합니다. + 새로운 [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) 생성은 일반 [`Agent`](/openai-agents-js/ko/guides/agents) 생성과 매우 유사합니다. ```typescript import { RealtimeAgent } from '@openai/agents/realtime'; @@ -76,7 +76,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 4. **세션 생성** - 일반 에이전트와 달리, 음성 에이전트는 `RealtimeSession` 내에서 지속적으로 실행되며 대화와 모델과의 장기 연결을 처리합니다. 이 세션은 오디오 처리, 인터럽션(중단 처리), 그리고 이후에 다룰 다양한 라이프사이클 기능도 담당합니다. + 일반 에이전트와 달리, 음성 에이전트는 대화와 모델과의 장기 연결을 처리하는 `RealtimeSession` 내부에서 지속적으로 실행되고 청취합니다. 이 세션은 오디오 처리, 인터럽션(중단 처리), 그 외 이후에 다룰 많은 라이프사이클 기능도 처리합니다. ```typescript import { RealtimeSession } from '@openai/agents/realtime'; @@ -86,25 +86,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` 생성자는 첫 번째 인수로 `agent`를 받습니다. 이 에이전트가 사용자가 처음 상호작용할 수 있는 에이전트가 됩니다. + `RealtimeSession` 생성자는 첫 번째 인자로 `agent`를 받습니다. 이 에이전트가 사용자가 처음 상호작용할 수 있는 에이전트가 됩니다. 5. **세션에 연결** - 세션에 연결하려면 앞에서 생성한 클라이언트 일시 토큰을 전달해야 합니다. + 세션에 연결하려면 앞에서 생성한 클라이언트 임시 토큰을 전달해야 합니다. ```typescript await session.connect({ apiKey: 'ek_...(put your own key here)' }); ``` - 이렇게 하면 브라우저에서 WebRTC 를 사용해 Realtime API 에 연결하고, 오디오 입력과 출력을 위해 마이크와 스피커를 자동으로 구성합니다. `RealtimeSession`을 백엔드 서버(예: Node.js)에서 실행하는 경우 SDK 는 자동으로 WebSocket 을 연결로 사용합니다. 다양한 전송 방식에 대해서는 [전송 방식](/openai-agents-js/ko/guides/voice-agents/transport) 가이드를 참고하세요. + 이는 브라우저에서 WebRTC를 사용해 Realtime API에 연결하고, 오디오 입력과 출력을 위해 마이크와 스피커를 자동으로 구성합니다. `RealtimeSession`을 백엔드 서버(Node.js 등)에서 실행하는 경우 SDK는 자동으로 연결 방식으로 WebSocket을 사용합니다. 다양한 전송 계층에 대한 자세한 내용은 [전송 방식](/openai-agents-js/ko/guides/voice-agents/transport) 가이드를 참고하세요. -6. **모두 합치기** +6. **모두 합쳐서 사용** -7. **엔진을 가동하고 대화 시작** +7. **엔진 시동 및 대화 시작** - 웹 서버를 시작하고 새 Realtime Agent 코드가 포함된 페이지로 이동하세요. 마이크 접근 권한 요청이 표시됩니다. 권한을 허용하면 에이전트와 대화를 시작할 수 있습니다. + 웹서버를 시작하고 새 Realtime Agent 코드가 포함된 페이지로 이동하세요. 마이크 접근 권한 요청이 표시됩니다. 권한을 허용하면 에이전트와 대화를 시작할 수 있습니다. ```bash npm run dev @@ -114,16 +114,16 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t ## 다음 단계 -이제 자신만의 음성 에이전트를 설계하고 구축할 수 있습니다. 음성 에이전트는 일반 에이전트와 많은 기능을 공유하지만, 고유한 기능도 일부 포함합니다. +이제부터 직접 음성 에이전트를 설계하고 구축할 수 있습니다. 음성 에이전트는 일반 에이전트와 많은 기능을 공유하지만, 고유한 기능도 일부 갖고 있습니다. -- 음성 에이전트에 다음을 추가하는 방법을 알아보세요: +- 음성 에이전트에 다음을 제공하는 방법 알아보기 - [도구](/openai-agents-js/ko/guides/voice-agents/build#tools) - [핸드오프](/openai-agents-js/ko/guides/voice-agents/build#handoffs) - [가드레일](/openai-agents-js/ko/guides/voice-agents/build#guardrails) - [오디오 인터럽션(중단 처리) 처리](/openai-agents-js/ko/guides/voice-agents/build#audio-interruptions) - [세션 기록 관리](/openai-agents-js/ko/guides/voice-agents/build#session-history) -- 다양한 전송 방식에 대해 더 알아보기 +- 다양한 전송 계층 더 알아보기 - [WebRTC](/openai-agents-js/ko/guides/voice-agents/transport#connecting-over-webrtc) - [WebSocket](/openai-agents-js/ko/guides/voice-agents/transport#connecting-over-websocket) - [나만의 전송 메커니즘 구축](/openai-agents-js/ko/guides/voice-agents/transport#building-your-own-transport-mechanism) diff --git a/docs/src/content/docs/ko/guides/voice-agents/transport.mdx b/docs/src/content/docs/ko/guides/voice-agents/transport.mdx index e23c7937..b90dcf90 100644 --- a/docs/src/content/docs/ko/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/ko/guides/voice-agents/transport.mdx @@ -28,46 +28,46 @@ import cloudflareTransportExample from '../../../../../../../examples/docs/exten ## 기본 전송 계층 -### WebRTC 연결 +### WebRTC를 통한 연결 기본 전송 계층은 WebRTC를 사용합니다. 마이크에서 오디오를 녹음하고 자동으로 재생합니다. -직접 준비한 미디어 스트림 또는 오디오 요소를 사용하려면 세션 생성 시 `OpenAIRealtimeWebRTC` 인스턴스를 전달하세요. +자신의 미디어 스트림이나 오디오 요소를 사용하려면 세션을 생성할 때 `OpenAIRealtimeWebRTC` 인스턴스를 제공하세요. -### WebSocket 연결 +### WebSocket을 통한 연결 -WebRTC 대신 WebSocket 연결을 사용하려면 세션 생성 시 `transport: 'websocket'` 또는 `OpenAIRealtimeWebSocket` 인스턴스를 전달하세요. 이는 예를 들어 Twilio로 전화 에이전트를 구축하는 등의 서버 사이드 사용 사례에 적합합니다. +WebRTC 대신 WebSocket 연결을 사용하려면 세션을 생성할 때 `transport: 'websocket'` 또는 `OpenAIRealtimeWebSocket` 인스턴스를 전달하세요. 이는 예를 들어 Twilio로 전화 에이전트를 구축하는 등 서버 측 사용 사례에 적합합니다. -원문 PCM16 오디오 바이트 처리를 위해 임의의 녹음/재생 라이브러리를 사용하세요. +원문 PCM16 오디오 바이트를 처리하기 위해 임의의 녹음/재생 라이브러리를 사용하세요. -#### Cloudflare Workers (workerd) 참고 +#### Cloudflare Workers (workerd) 참고 사항 Cloudflare Workers 및 기타 workerd 런타임은 전역 `WebSocket` 생성자를 사용해 아웃바운드 WebSocket을 열 수 없습니다. 확장 패키지의 Cloudflare 전송을 사용하세요. 내부적으로 `fetch()` 기반 업그레이드를 수행합니다. -### 자체 전송 메커니즘 구축 +### 사용자 지정 전송 메커니즘 구축 -다른 음성-대-음성 API를 사용하거나 커스텀 전송 메커니즘이 필요한 경우, `RealtimeTransportLayer` 인터페이스를 구현하고 `RealtimeTransportEventTypes` 이벤트를 발생시켜 직접 만들 수 있습니다. +다른 음성 간 API를 사용하거나 사용자 지정 전송 메커니즘이 필요한 경우 `RealtimeTransportLayer` 인터페이스를 구현하고 `RealtimeTransportEventTypes` 이벤트를 발생시켜 직접 만들 수 있습니다. -## Realtime API 직접 상호작용 +## Realtime API와의 보다 직접적인 상호작용 -OpenAI Realtime API를 사용하되 Realtime API에 더 직접적으로 접근하고 싶다면 다음 두 가지 옵션이 있습니다. +OpenAI Realtime API를 사용하면서 Realtime API에 더 직접 접근하려면 두 가지 옵션이 있습니다. -### 옵션 1 - 전송 계층 접근 +### 옵션 1 - 전송 계층 액세스 -`RealtimeSession`의 모든 기능을 계속 활용하려면 `session.transport`를 통해 전송 계층에 접근할 수 있습니다. +`RealtimeSession`의 모든 기능을 활용하면서 전송 계층에 접근하려면 `session.transport`를 통해 접근하세요. -전송 계층은 수신한 모든 이벤트를 `*` 이벤트로 내보내며, `sendEvent()` 메서드를 사용해 원문 이벤트를 전송할 수 있습니다. +전송 계층은 수신한 모든 이벤트를 `*` 이벤트로 내보내며, `sendEvent()` 메서드를 사용해 원시 이벤트를 전송할 수 있습니다. ### 옵션 2 — 전송 계층만 사용 -자동 도구 실행, 가드레일 등이 필요하지 않다면, 연결과 인터럽션(중단 처리)만 관리하는 “얇은(thin)” 클라이언트로 전송 계층만 사용할 수 있습니다. +자동 도구 실행, 가드레일 등이 필요 없다면 연결과 인터럽션(중단 처리)만 관리하는 "얇은(thin) 클라이언트"로 전송 계층만 사용할 수도 있습니다. diff --git a/docs/src/content/docs/ko/index.mdx b/docs/src/content/docs/ko/index.mdx index 1aa32158..becfcb6e 100644 --- a/docs/src/content/docs/ko/index.mdx +++ b/docs/src/content/docs/ko/index.mdx @@ -20,35 +20,30 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 개요 [OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js)는 -아주 적은 추상화로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있게 합니다. 이는 이전의 -에이전트를 위한 실험 프로젝트인 -[Swarm](https://github.com/openai/swarm/tree/main)을 프로덕션 수준으로 업그레이드한 것으로, [Python 에서도 사용 가능](https://github.com/openai/openai-agents-python)합니다. Agents SDK 는 아주 -작은 기본 구성요소 세트를 제공합니다: +아주 적은 추상화로 가벼우면서도 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있게 해줍니다. 이는 이전 에이전트 실험작인 +[Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션 준비 완료 업그레이드이며, [Python에서도 제공](https://github.com/openai/openai-agents-python)됩니다. Agents SDK는 매우 작은 기본 구성 요소 집합을 제공합니다: -- **에이전트**: instructions 와 tools 를 갖춘 LLM -- **핸드오프**: 특정 작업을 위해 다른 에이전트에 위임할 수 있게 함 -- **가드레일**: 에이전트에 대한 입력을 검증할 수 있게 함 +- **Agents**: instructions와 tools가 장착된 LLM +- **Handoffs**: 특정 작업에 대해 다른 에이전트에 위임하도록 하는 기능 +- **Guardrails**: 에이전트의 입력을 검증하는 기능 -TypeScript 와 결합하면, 이러한 기본 구성요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현하고 -가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK 는 -내장형 **트레이싱**을 제공하여 에이전트 플로우를 시각화하고 디버그하며, -평가하고 애플리케이션에 맞게 모델을 파인튜닝할 수도 있습니다. +TypeScript와 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트 흐름을 시각화하고 디버그하며, 평가하고 심지어 애플리케이션에 맞게 모델을 미세 조정할 수 있게 해주는 **트레이싱**이 기본 제공됩니다. -## Agents SDK 를 사용하는 이유 +## Agents SDK를 사용하는 이유 -SDK 의 두 가지 핵심 설계 원칙: +SDK는 두 가지 핵심 설계 원칙을 따릅니다: -1. 사용할 가치가 있을 만큼 충분한 기능, 하지만 빠르게 배울 수 있을 만큼 적은 기본 구성요소 -2. 기본 설정으로도 훌륭하게 동작하지만, 정확히 어떤 일이 일어나는지 맞춤화 가능 +1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 학습을 빠르게 하는 데 충분할 만큼 기본 구성 요소는 적게 유지 +2. 기본값으로도 훌륭하게 동작하지만, 발생하는 일을 정확히 커스터마이즈 가능 -SDK 의 주요 기능: +SDK의 주요 기능은 다음과 같습니다: -- **에이전트 루프**: 도구 호출, 결과를 LLM 에 전송, LLM 이 완료될 때까지 루프를 처리하는 내장 루프 -- **TypeScript 우선**: 새로운 추상화를 배울 필요 없이 언어 기능만으로 에이전트를 오케스트레이션하고 체이닝 -- **핸드오프**: 여러 에이전트 간 조정과 위임을 위한 강력한 기능 -- **가드레일**: 에이전트와 병렬로 입력 검증과 점검을 수행하고 실패 시 조기 중단 -- **함수 도구**: 어떤 TypeScript 함수든 자동 스키마 생성과 Zod 기반 검증으로 도구로 변환 -- **트레이싱**: 시각화, 디버깅, 모니터링을 지원하는 내장 트레이싱과 OpenAI 의 평가, 파인튜닝, 디스틸레이션 도구 활용 +- **에이전트 루프**: 도구 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 루프를 처리하는 기본 제공 루프 +- **TypeScript 우선**: 새로운 추상화를 배울 필요 없이 언어의 기본 기능으로 에이전트를 오케스트레이션하고 체이닝 +- **핸드오프**: 여러 에이전트 간 조율과 위임을 위한 강력한 기능 +- **가드레일**: 에이전트와 병렬로 입력 검증과 체크를 수행하고 실패 시 조기 중단 +- **함수 도구**: 어떤 TypeScript 함수든 자동 스키마 생성과 Zod 기반 검증으로 도구로 전환 +- **트레이싱**: 워크플로를 시각화, 디버그, 모니터링하고 OpenAI의 평가, 파인튜닝, 증류 도구를 활용할 수 있는 기본 제공 트레이싱 - **실시간 에이전트**: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등을 포함한 강력한 음성 에이전트 구축 ## 설치 @@ -61,7 +56,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/zh/extensions/ai-sdk.mdx b/docs/src/content/docs/zh/extensions/ai-sdk.mdx index f5cbd82a..38b5fceb 100644 --- a/docs/src/content/docs/zh/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/zh/extensions/ai-sdk.mdx @@ -7,12 +7,12 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -开箱即用，Agents SDK 可通过 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 中。 ## 设置 @@ -24,13 +24,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'; @@ -46,19 +46,19 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk ## 示例 - + -## 传递提供商元数据 +## 传递提供方元数据 -如果需要随消息发送提供商特定的选项，请通过 `providerMetadata` 传递。这些值会被直接转发到底层的 AI SDK 模型。例如，以下在 Agents SDK 中的 `providerData` +如果你需要在消息中发送特定于提供方的选项，请通过 `providerMetadata` 传递。其值会直接转发给底层的 AI SDK 模型。例如，以下在 Agents SDK 中的 `providerData` ```ts providerData: { diff --git a/docs/src/content/docs/zh/extensions/cloudflare.mdx b/docs/src/content/docs/zh/extensions/cloudflare.mdx index 9b618c64..469565ef 100644 --- a/docs/src/content/docs/zh/extensions/cloudflare.mdx +++ b/docs/src/content/docs/zh/extensions/cloudflare.mdx @@ -6,13 +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。为便于在这些环境中连接实时智能体（Realtime Agents），扩展包提供了一个专用传输，在内部通过基于 `fetch()` 的升级完成连接。 +Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构造函数发起出站 WebSocket 连接。为简化在这些环境中连接实时智能体（Realtime Agents），extensions 包提供了一个专用传输层，在内部执行基于 `fetch()` 的升级。 ## 设置 @@ -25,11 +25,11 @@ Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构 npm install @openai/agents-extensions ``` -2. **创建传输并将其附加到你的会话。** +2. **创建传输并将其附加到您的会话。** -3. **连接你的 `RealtimeSession`。** +3. **连接您的 `RealtimeSession`。** ```typescript await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' }); @@ -39,6 +39,6 @@ Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构 ## 注意事项 -- Cloudflare 传输在底层使用带有 `Upgrade: websocket` 的 `fetch()`，并跳过等待套接字 `open` 事件的步骤，以与 workerd API 保持一致。 -- 使用该传输时，所有 `RealtimeSession` 功能（tools、guardrails 等）均可照常使用。 +- Cloudflare 传输在底层使用带有 `Upgrade: websocket` 的 `fetch()`，并跳过等待套接字 `open` 事件，以匹配 workerd API。 +- 使用此传输时，所有 `RealtimeSession` 功能（tools、guardrails 等）均可照常工作。 - 在开发过程中使用 `DEBUG=openai-agents*` 查看详细日志。 diff --git a/docs/src/content/docs/zh/extensions/twilio.mdx b/docs/src/content/docs/zh/extensions/twilio.mdx index 74ce1a3c..3d39c221 100644 --- a/docs/src/content/docs/zh/extensions/twilio.mdx +++ b/docs/src/content/docs/zh/extensions/twilio.mdx @@ -7,12 +7,12 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio 提供了一个 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)，可将电话通话的原始音频发送到 WebSocket 服务器。此设置可用于将您的[语音智能体概述](/openai-agents-js/zh/guides/voice-agents)连接到 Twilio。您可以使用 `websocket` 模式下的默认 Realtime Session 传输，将来自 Twilio 的事件连接到您的 Realtime Session。不过，这需要您设置正确的音频格式并调整中断时机，因为电话通话相较于基于 Web 的对话自然会引入更多延迟。 +Twilio 提供了一个 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)，可以将电话通话中的原始音频发送到一个 WebSocket 服务器。该设置可用于将您的[语音智能体概述](/openai-agents-js/zh/guides/voice-agents)连接到 Twilio。您可以使用默认的 Realtime Session 传输在 `websocket` 模式下，将来自 Twilio 的事件连接到您的 Realtime Session。不过，这需要您设置正确的音频格式，并调整自己的中断时机，因为电话通话相比基于 Web 的对话会自然引入更多延迟。 -为了改进设置体验，我们创建了一个专用的传输层，为您处理与 Twilio 的连接，包括处理中断和音频转发。 +为改进设置体验，我们创建了一个专用传输层，替您处理与 Twilio 的连接，包括处理中断和音频转发。 @@ -21,15 +21,14 @@ Twilio 提供了一个 [Media Streams API](https://www.twilio.com/docs/voice/med -1. **确保您拥有 Twilio 账户和一个 Twilio 电话号码。** +1. **确保您拥有一个 Twilio 账户和一个 Twilio 电话号码。** -2. **设置一个能接收来自 Twilio 事件的 WebSocket 服务器。** +2. **设置一个可以接收来自 Twilio 事件的 WebSocket 服务器。** - 如果您在本地开发，这将需要您配置一个本地隧道，比如 - 这将需要您配置一个本地隧道，比如 [`ngrok`](https://ngrok.io/) 或 + 如果您在本地开发，这需要配置一个本地隧道，例如使用 [`ngrok`](https://ngrok.io/) 或 [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - 以便让本地服务器能被 Twilio 访问。您可以使用 `TwilioRealtimeTransportLayer` - 连接到 Twilio。 + 让您的本地服务器可被 Twilio 访问。您可以使用 `TwilioRealtimeTransportLayer` + 来连接 Twilio。 3. **通过安装扩展包来安装 Twilio 适配器：** @@ -55,28 +54,27 @@ Twilio 提供了一个 [Media Streams API](https://www.twilio.com/docs/voice/med -您对 `RealtimeSession` 的事件和行为预期都将正常工作，包括工具调用、护栏等。阅读[语音智能体概述](/openai-agents-js/zh/guides/voice-agents)，了解如何将 `RealtimeSession` 与语音智能体一起使用的更多信息。 +任何您期望从 `RealtimeSession` 获得的事件和行为都会按预期工作，包括工具调用、护栏等。阅读[语音智能体概述](/openai-agents-js/zh/guides/voice-agents)以了解如何将 `RealtimeSession` 与语音智能体一起使用的更多信息。 ## 提示与注意事项 1. **速度至关重要。** 为了接收来自 Twilio 的所有必要事件和音频，您应在拿到 WebSocket 连接引用后立即创建 - `TwilioRealtimeTransportLayer` 实例，并立刻调用 `session.connect()`。 + `TwilioRealtimeTransportLayer` 实例，并紧接着调用 `session.connect()`。 2. **访问原始 Twilio 事件。** - 如果您想访问 Twilio 发送的原始事件，可以在 `RealtimeSession` 实例上监听 - `transport_event` 事件。来自 Twilio 的每个事件其类型为 `twilio_message`，并带有包含原始事件数据的 `message` 属性。 + 如果您想访问 Twilio 发送的原始事件，您可以在 `RealtimeSession` 实例上监听 + `transport_event` 事件。来自 Twilio 的每个事件都会有一个类型 `twilio_message`，以及包含原始事件数据的 `message` 属性。 3. **查看调试日志。** - 有时您可能会遇到需要更多信息的问题。使用 `DEBUG=openai-agents*` 环境变量可以显示来自 Agents SDK 的所有调试日志。 - 或者，您也可以使用 `DEBUG=openai-agents:extensions:twilio*` 仅启用 Twilio 适配器的调试日志。 + 有时您可能会遇到需要更多信息的问题。使用环境变量 `DEBUG=openai-agents*` 将显示来自 Agents SDK 的所有调试日志。或者，您也可以仅启用 Twilio 适配器的调试日志：`DEBUG=openai-agents:extensions:twilio*`。 ## 完整示例服务器 -下面是一个端到端的 WebSocket 服务器示例，用于接收来自 Twilio 的请求并将其转发到 `RealtimeSession`。 +下面是一个端到端的 WebSocket 服务器示例，它接收来自 Twilio 的请求并将其转发到 `RealtimeSession`。 + -本页的其余部分将更详细地介绍每个 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()` 的依赖注入对象。它会被转发给每个工具、护栏、交接等，并可用于存储状态或提供共享服务（数据库连接、用户元数据、功能开关等）。 - + --- ## 输出类型 -默认情况下，Agent 返回**纯文本**（`string`）。如果你希望模型返回结构化对象，可以指定 `outputType` 属性。SDK 接受： +默认情况下，智能体返回**纯文本**（`string`）。如果你希望模型返回结构化对象，可以指定 `outputType` 属性。SDK 接受： 1. [Zod](https://github.com/colinhacks/zod) 模式（`z.object({...})`）。 2. 任何兼容 JSON Schema 的对象。 @@ -64,93 +64,93 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor title="使用 Zod 的结构化输出" /> -当提供了 `outputType` 时，SDK 会自动使用 +当提供 `outputType` 时，SDK 会自动使用 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) 而不是纯文本。 --- ## 多智能体系统设计模式 -将多个智能体组合在一起有多种方式。在生产应用中我们常见两种模式： +组合智能体的方式有很多。在生产应用中我们经常看到两种模式： -1. **管理器（智能体作为工具）**——一个中心智能体掌控对话，并调用作为工具暴露的专业化智能体。 -2. **交接**——一旦识别出用户请求，初始智能体将整个对话交给某个专家智能体处理。 +1. **Manager（agents as tools）** —— 一个中心智能体拥有对话控制，并调用作为工具暴露的专业化智能体。 +2. **交接（Handoffs）** —— 初始智能体在识别出用户请求后，将整个对话交给专家智能体。 -这两种方法是互补的。管理器让你可以在单一位置实施护栏或速率限制，而交接让每个智能体只专注于单一任务而无需保留对话控制权。 +这些方法是互补的。Manager 让你可以在单处实施护栏或速率限制，而交接让每个智能体专注于单一任务且不保留对对话的控制权。 -### 管理器（智能体作为工具） +### Manager（agents as tools） -在此模式中，管理器不会移交控制权——LLM 使用这些工具，而管理器总结最终答案。详情参见[工具](/openai-agents-js/zh/guides/tools#agents-as-tools)。 +在这种模式中，管理者不会移交控制权——LLM 使用工具，管理者总结最终答案。详见[工具](/openai-agents-js/zh/guides/tools#agents-as-tools)。 - + -### 交接 +### 交接（Handoffs） -通过交接，分诊智能体负责路由请求，但一旦交接发生，专家智能体将拥有对话控制权，直至产生最终输出。这样可保持提示简短，并可独立推理每个智能体。了解更多请参见[交接](/openai-agents-js/zh/guides/handoffs)。 +通过交接，分诊智能体负责路由请求，但一旦发生交接，专家智能体将拥有对话，直到产生最终输出。这能保持提示简短，并让你可以独立地推理每个智能体。了解更多，请参阅[交接](/openai-agents-js/zh/guides/handoffs)。 - + --- ## 动态 instructions -`instructions` 可以是**函数**而不是字符串。该函数接收当前的 `RunContext` 和 Agent 实例，并可返回字符串或 `Promise`。 +`instructions` 可以是**函数**而不是字符串。该函数会接收当前的 `RunContext` 和 Agent 实例，并可返回字符串或 `Promise`。 -同步与 `async` 函数均受支持。 +同时支持同步和 `async` 函数。 --- ## 生命周期钩子 -对于高级用例，你可以通过监听事件来观察 Agent 的生命周期。可用事件名称请参见[此处](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts)。 +对于高级用例，你可以通过监听事件来观察智能体的生命周期。要了解可用内容，请参阅[此处](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts)列出的智能体钩子事件名称。 --- ## 护栏 -护栏允许你验证或转换用户输入与智能体输出。通过 `inputGuardrails` 和 `outputGuardrails` 数组进行配置。详情参见[护栏](/openai-agents-js/zh/guides/guardrails)。 +护栏允许你验证或转换用户输入和智能体输出。它们通过 `inputGuardrails` 和 `outputGuardrails` 数组进行配置。详见[护栏](/openai-agents-js/zh/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。 -- `'stop_on_first_tool'`——将第一个工具结果视为最终答案。 -- `{ stopAtToolNames: ['my_tool'] }`——当调用到列表中的任一工具时停止。 -- `(context, toolResults) => ...`——返回运行是否应结束的自定义函数。 +- `'run_llm_again'`（默认）—— 使用工具结果再次运行 LLM。 +- `'stop_on_first_tool'` —— 将第一个工具结果视为最终答案。 +- `{ stopAtToolNames: ['my_tool'] }` —— 当调用列表中的任一工具时停止。 +- `(context, toolResults) => ...` —— 返回是否应结束运行的自定义函数。 ```typescript const agent = new Agent({ @@ -164,5 +164,5 @@ const agent = new Agent({ ## 后续步骤 - 了解如何[运行智能体](/openai-agents-js/zh/guides/running-agents)。 -- 深入学习[工具](/openai-agents-js/zh/guides/tools)、[护栏](/openai-agents-js/zh/guides/guardrails)和[模型](/openai-agents-js/zh/guides/models)。 -- 在侧边栏的 **@openai/agents** 下浏览完整的 TypeDoc 参考。 +- 深入了解[工具](/openai-agents-js/zh/guides/tools)、[护栏](/openai-agents-js/zh/guides/guardrails)和[模型](/openai-agents-js/zh/guides/models)。 +- 在侧边栏的 **@openai/agents** 下查看完整的 TypeDoc 参考。 diff --git a/docs/src/content/docs/zh/guides/config.mdx b/docs/src/content/docs/zh/guides/config.mdx index 73ebf9a4..a68daad5 100644 --- a/docs/src/content/docs/zh/guides/config.mdx +++ b/docs/src/content/docs/zh/guides/config.mdx @@ -21,7 +21,7 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t title="设置默认 OpenAI 密钥" /> -您也可以传入自定义的 `OpenAI` 客户端实例。否则 SDK 会使用默认密钥自动创建一个。 +您也可以传入自定义的 `OpenAI` 客户端实例。否则 SDK 会使用默认密钥自动创建一个实例。 -最后，您可以在 Responses API 与 Chat Completions API 之间切换。 +最后，您可以在 Responses API 和 Chat Completions API 之间切换。 ## 追踪 -追踪默认启用，并使用上文中的 OpenAI 密钥。 +追踪默认启用，并使用上述章节中的 OpenAI 密钥。 -您可以通过 `setTracingExportApiKey()` 设置单独的密钥： +可以通过 `setTracingExportApiKey()` 设置单独的密钥： -若想进一步了解追踪功能，请参阅[追踪](/openai-agents-js/zh/guides/tracing)。 +如果您想进一步了解追踪功能，请查看[追踪](/openai-agents-js/zh/guides/tracing)。 ## 调试日志 @@ -59,13 +59,13 @@ SDK 使用 [`debug`](https://www.npmjs.com/package/debug) 包进行调试日志 export DEBUG=openai-agents* ``` -您可以使用 `@openai/agents` 中的 `getLogger(namespace)` 为自己的模块获取带命名空间的日志记录器。 +您可以使用来自 `@openai/agents` 的 `getLogger(namespace)` 为自己的模块获取命名空间日志记录器。 ### 日志中的敏感数据 -某些日志可能包含用户数据。可通过设置以下环境变量禁用这些日志。 +某些日志可能包含用户数据。可通过设置以下环境变量禁用。 要禁用记录 LLM 的输入与输出： diff --git a/docs/src/content/docs/zh/guides/context.mdx b/docs/src/content/docs/zh/guides/context.mdx index 74d5934d..fea25d9b 100644 --- a/docs/src/content/docs/zh/guides/context.mdx +++ b/docs/src/content/docs/zh/guides/context.mdx @@ -6,34 +6,34 @@ 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` 的回调，以及生命周期钩子。 -2. 语言模型在生成回复时可见的**智能体/LLM 上下文**。 +1. **本地上下文**：你的代码在一次运行期间可以访问的内容，如工具所需的依赖或数据、`onHandoff` 等回调以及生命周期钩子。 +2. **智能体/LLM 上下文**：语言模型在生成响应时能够看到的内容。 ## 本地上下文 -本地上下文由 `RunContext` 类型表示。你可以创建任意对象来保存状态或依赖，并将其传给 `Runner.run()`。所有工具调用和钩子都会接收一个 `RunContext` 包装器，从而读取或修改该对象。 +本地上下文由 `RunContext` 类型表示。你可以创建任意对象来保存状态或依赖，并将其传给 `Runner.run()`。所有工具调用和钩子都会接收一个 `RunContext` 包装器，以便读取或修改该对象。 参与同一次运行的每个智能体、工具和钩子都必须使用相同**类型**的上下文。 -本地上下文适用于如下场景： +本地上下文适用于以下场景： - 关于本次运行的数据（用户名、ID 等） -- 依赖，如日志器或数据获取器 +- 依赖项，如日志器或数据获取器 - 帮助函数 ## 智能体/LLM 上下文 -当调用 LLM 时，它只能看到来自对话历史的数据。要提供额外信息，你可以： +当调用 LLM 时，它只能看到对话历史中的数据。若要提供额外信息，你有以下几种方式： -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. 使用检索或 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 搜索工具，将响应建立在来自文件、数据库或网络的相关数据之上。 diff --git a/docs/src/content/docs/zh/guides/guardrails.mdx b/docs/src/content/docs/zh/guides/guardrails.mdx index d3b639fb..6ff41086 100644 --- a/docs/src/content/docs/zh/guides/guardrails.mdx +++ b/docs/src/content/docs/zh/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'; -护栏与您的智能体*并行*运行，允许您对用户输入或智能体输出执行检查与校验。例如，您可以在调用昂贵模型之前运行一个轻量模型作为护栏。如果护栏检测到恶意使用，它可以触发错误并阻止高成本模型运行。 +护栏与您的智能体是并行运行的，允许您对用户输入或智能体输出进行检查与校验。例如，您可以在调用昂贵模型前，先运行一个轻量模型作为护栏。如果护栏检测到恶意使用，它可以触发错误并阻止高成本模型运行。 护栏有两种类型： -1. **输入护栏** 运行在初始用户输入上。 -2. **输出护栏** 运行在最终智能体输出上。 +1. **输入护栏** 对初始用户输入运行。 +2. **输出护栏** 对最终智能体输出运行。 ## 输入护栏 输入护栏分三步运行： 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) 错误。 +2. 护栏函数执行并返回一个 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)，该对象被包裹在 [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) 中。 +3. 如果 `tripwireTriggered` 为 `true`，则抛出 [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) 错误。 -> **注意** -> 输入护栏面向用户输入，因此仅当该智能体是工作流中的*第一个*智能体时才会运行。护栏在智能体上进行配置，因为不同智能体通常需要不同的护栏。 +> **Note** +> 输入护栏用于用户输入，因此仅当该智能体是工作流中的第一个智能体时才会运行。护栏在智能体本身上配置，因为不同的智能体往往需要不同的护栏。 ## 输出护栏 -输出护栏遵循相同模式： +输出护栏分三步运行： -1. 护栏接收与智能体相同的输入。 -2. 护栏函数执行并返回一个 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)，封装在 [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) 中。 -3. 如果 `tripwireTriggered` 为 `true`，将抛出 [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) 错误。 +1. 护栏接收由智能体产生的输出。 +2. 护栏函数执行并返回一个 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)，该对象被包裹在 [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) 中。 +3. 如果 `tripwireTriggered` 为 `true`，则抛出 [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) 错误。 -> **注意** -> 仅当该智能体是工作流中的*最后一个*智能体时，才会运行输出护栏。关于实时语音交互，请参阅[构建语音智能体](/openai-agents-js/zh/guides/voice-agents/build#guardrails)。 +> **Note** +> 仅当该智能体是工作流中的最后一个智能体时，输出护栏才会运行。关于实时语音交互，请参阅[构建语音智能体](/openai-agents-js/zh/guides/voice-agents/build#guardrails)。 ## 绊线 -当护栏失败时，会通过绊线发出信号。一旦绊线被触发，runner（运行器）会抛出相应错误并停止执行。 +当护栏失败时，会通过绊线进行信号通知。一旦绊线被触发，runner 会抛出相应错误并停止执行。 -## 护栏的实现 +## 护栏实现 -护栏本质上是一个返回 `GuardrailFunctionOutput` 的函数。下面是一个最小示例，通过在底层运行另一个智能体来检查用户是否在请求数学作业帮助。 +护栏本质上是一个返回 `GuardrailFunctionOutput` 的函数。下面是一个最小示例，它通过在内部运行另一个智能体来检查用户是否在寻求数学作业帮助。 @@ -51,6 +51,6 @@ import outputGuardrailExample from '../../../../../../examples/docs/guardrails/g 1. `guardrailAgent` 在护栏函数内部使用。 -2. 护栏函数接收智能体的输入或输出并返回结果。 -3. 可以在护栏结果中包含额外信息。 -4. `agent` 定义了应用护栏的实际工作流。 +2. 护栏函数接收智能体的输入或输出，并返回结果。 +3. 护栏结果中可包含额外信息。 +4. `agent` 定义应用护栏的实际工作流。 diff --git a/docs/src/content/docs/zh/guides/handoffs.mdx b/docs/src/content/docs/zh/guides/handoffs.mdx index 54098fcf..209af171 100644 --- a/docs/src/content/docs/zh/guides/handoffs.mdx +++ b/docs/src/content/docs/zh/guides/handoffs.mdx @@ -10,54 +10,46 @@ 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'; -交接使一个智能体可以将对话的一部分委托给另一个智能体。这在不同智能体专精不同领域时很有用。比如在客服应用中，您可能有负责预订、退款或常见问题的智能体。 +交接使一个智能体可以将对话的一部分委托给另一个智能体。当不同智能体在特定领域各有所长时，这非常有用。例如在客服应用中，您可能有负责预订、退款或常见问题的智能体。 -交接在 LLM 中被表示为工具。如果您将会话交接给名为 `Refund Agent` 的智能体，工具名将是 `transfer_to_refund_agent`。 +交接在 LLM 中以工具的形式呈现。如果你将会话交接给名为 `Refund Agent` 的智能体，工具名将是 `transfer_to_refund_agent`。 ## 创建交接 -每个智能体都接受一个 `handoffs` 选项。它可以包含其他 `Agent` 实例或由 `handoff()` helper 返回的 `Handoff` 对象。 +每个智能体都接受一个 `handoffs` 选项。它可以包含其他 `Agent` 实例，或由 `handoff()` 辅助函数返回的 `Handoff` 对象。 ### 基本用法 - + ### 通过 `handoff()` 自定义交接 -`handoff()` 函数允许您调整生成的工具。 +`handoff()` 函数允许你调整生成的工具。 - `agent` – 要交接到的智能体。 -- `toolNameOverride` – 覆盖默认的 `transfer_to_` 工具名称。 +- `toolNameOverride` – 覆盖默认的 `transfer_to_` 工具名。 - `toolDescriptionOverride` – 覆盖默认的工具描述。 -- `onHandoff` – 交接发生时的回调。接收 `RunContext` 和可选的已解析输入。 +- `onHandoff` – 交接发生时的回调。接收一个 `RunContext`，以及可选的已解析输入。 - `inputType` – 交接所需的输入模式。 - `inputFilter` – 过滤传递给下一个智能体的历史记录。 - + ## 交接输入 -有时您希望 LLM 在调用交接时提供数据。定义一个输入模式并在 `handoff()` 中使用它。 +有时你希望 LLM 在调用交接时提供数据。定义一个输入模式，并在 `handoff()` 中使用它。 - + ## 输入过滤器 -默认情况下，交接会接收整个对话历史。要修改传递给下一个智能体的内容，请提供一个 `inputFilter`。 -常用的 helper 位于 `@openai/agents-core/extensions`。 +默认情况下，交接会接收整个对话历史。若需修改传递给下一个智能体的内容，请提供一个 `inputFilter`。 +常用辅助函数位于 `@openai/agents-core/extensions`。 - + -## 推荐提示词 +## 推荐提示 -当提示中提及交接时，LLM 的响应更稳定。SDK 通过 `RECOMMENDED_PROMPT_PREFIX` 提供了一个推荐前缀。 +当你的提示中提到交接时，LLM 的响应会更稳定。SDK 通过 `RECOMMENDED_PROMPT_PREFIX` 提供了一个推荐前缀。 - + diff --git a/docs/src/content/docs/zh/guides/human-in-the-loop.mdx b/docs/src/content/docs/zh/guides/human-in-the-loop.mdx index 81a8e888..342a2658 100644 --- a/docs/src/content/docs/zh/guides/human-in-the-loop.mdx +++ b/docs/src/content/docs/zh/guides/human-in-the-loop.mdx @@ -7,13 +7,13 @@ 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 内置的 人工干预 支持，根据人工干预来暂停和恢复智能体运行。 +本指南演示如何使用 SDK 内置的人工干预支持，根据人工介入来暂停和恢复智能体运行。 -目前的主要用例是对敏感工具调用进行审批。 +当前的主要用例是对敏感的工具执行请求审批。 ## 审批请求 -你可以通过将 `needsApproval` 选项设置为 `true`，或设置为返回布尔值的异步函数，来定义需要审批的工具。 +您可以通过将 `needsApproval` 选项设置为 `true`，或设置为返回布尔值的异步函数，来定义需要审批的工具。 -参见[完整示例脚本](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)获取可端到端运行的版本。 -## 处理较长审批时间 +## 处理较长的审批时间 -人工干预 流程被设计为可在较长时间内中断，而无需保持你的服务器持续运行。如果你需要先结束请求并稍后继续，你可以序列化状态并在之后恢复。 +人工干预流程被设计为可在较长时间内中断，而无需持续运行您的服务器。如果您需要先结束请求并稍后继续，可以序列化状态并在之后恢复。 -你可以使用 `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/zh/guides/mcp.mdx b/docs/src/content/docs/zh/guides/mcp.mdx index c88de90d..d725cf0c 100644 --- a/docs/src/content/docs/zh/guides/mcp.mdx +++ b/docs/src/content/docs/zh/guides/mcp.mdx @@ -13,35 +13,35 @@ 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 是一种开放协议，用于标准化应用如何向 LLM 提供上下文。可以把 MCP 想象成 AI 应用的 USB‑C 接口。正如 USB‑C 为你的设备连接各种外设与配件提供了标准化方式，MCP 也为将 AI 模型连接到不同数据源与工具提供了标准化方式。 +> MCP 是一个开放协议，用于标准化应用如何向 LLM 提供上下文。把 MCP 想象成 AI 应用的 USB‑C 接口。正如 USB‑C 提供了将设备连接到各种外设和配件的标准化方式，MCP 也提供了将 AI 模型连接到不同数据源和工具的标准化方式。 本 SDK 支持三种 MCP 服务器类型： -1. **远程 MCP 服务器工具（Hosted MCP server tools）**——由 [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) 作为工具调用的远程 MCP 服务器 -2. **Streamable HTTP MCP 服务器**——实现了 [Streamable HTTP 传输](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) 的本地或远程服务器 -3. **Stdio MCP 服务器**——通过标准输入/输出访问的服务器（最简单的选项） +1. **Hosted MCP server tools** – 由 [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) 作为工具调用的远程 MCP 服务器 +2. **Streamable HTTP MCP servers** – 实现了 [Streamable HTTP 传输](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) 的本地或远程服务器 +3. **Stdio MCP servers** – 通过标准输入/输出访问的服务器（最简单的选项） -根据你的用例选择服务器类型： +请根据您的用例选择服务器类型： -| 你的需求 | 推荐选项 | +| 需求 | 推荐选项 | | ----------------------------------------------------------- | ----------------------- | | 使用默认的 OpenAI responses 模型调用可公开访问的远程服务器 | **1. Hosted MCP tools** | | 使用可公开访问的远程服务器，但在本地触发工具调用 | **2. Streamable HTTP** | | 使用本地运行的 Streamable HTTP 服务器 | **2. Streamable HTTP** | -| 在非 OpenAI-Responses 模型中使用任意 Streamable HTTP 服务器 | **2. Streamable HTTP** | +| 使用非 OpenAI‑Responses 模型调用任意 Streamable HTTP 服务器 | **2. Streamable HTTP** | | 使用仅支持标准 I/O 协议的本地 MCP 服务器 | **3. Stdio** | ## 1. 远程 MCP 服务器工具 -托管工具（Hosted tools）将整次往返交给模型处理。你的代码不直接调用 MCP 服务器，而是由 OpenAI Responses API 调用远程工具端点，并将结果流式回传给模型。 +托管工具将整个往返过程交由模型完成。不是由您的代码调用 MCP 服务器，而是由 OpenAI Responses API 调用远程工具端点并将结果流式传回模型。 -以下是使用远程 MCP 工具的最简单示例。你可以将远程 MCP 服务器的标签和 URL 传给 `hostedMcpTool` 工具函数，便于创建远程 MCP 服务器工具。 +下面是使用托管 MCP 工具的最简单示例。您可以将远程 MCP 服务器的标签和 URL 传给 `hostedMcpTool` 实用函数，用于创建托管 MCP 服务器工具。 -然后，你可以使用 `run` 函数（或你自定义的 `Runner` 实例的 `run` 方法）运行智能体： +然后，您可以使用 `run` 函数（或您自定义的 `Runner` 实例的 `run` 方法）运行智能体： -若要流式传输增量 MCP 结果，在运行 `Agent` 时传入 `stream: true`： +若要流式获取增量 MCP 结果，在运行 `Agent` 时传入 `stream: true`： -在此示例中，环境变量 `GOOGLE_CALENDAR_AUTHORIZATION` 存放了从 Google OAuth Playground 获取的 OAuth token，用于授权基于连接器的服务器调用 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)。 +功能完整的示例（托管工具/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`： -构造函数还接受其他 MCP TypeScript‑SDK 选项，例如 `authProvider`、`requestInit`、`fetch`、`reconnectionOptions` 和 `sessionId`。详见 [MCP TypeScript SDK 仓库](https://github.com/modelcontextprotocol/typescript-sdk)及其文档。 +构造函数也接受其他 MCP TypeScript‑SDK 选项，如 `authProvider`、`requestInit`、`fetch`、`reconnectionOptions` 和 `sessionId`。详见 [MCP TypeScript SDK 仓库](https://github.com/modelcontextprotocol/typescript-sdk)及其文档。 ## 3. Stdio MCP 服务器 @@ -105,20 +105,20 @@ import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.t title="Run with Stdio MCP servers" /> -## 其他注意事项 +## 其他须知 -对于 **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)——上文提到的可运行 +- [Model Context Protocol](https://modelcontextprotocol.io/) – 官方规范。 +- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上文提到的可运行 演示。 diff --git a/docs/src/content/docs/zh/guides/models.mdx b/docs/src/content/docs/zh/guides/models.mdx index 41f3b5e9..573230bc 100644 --- a/docs/src/content/docs/zh/guides/models.mdx +++ b/docs/src/content/docs/zh/guides/models.mdx @@ -15,10 +15,10 @@ import setTracingExportApiKeyExample from '../../../../../../examples/docs/confi 每个智能体最终都会调用一个 LLM。SDK 通过两个轻量接口对模型进行抽象： -- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 知道如何针对某个特定 API 发起*一次*请求。 -- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 将人类可读的模型**名称**（例如 `'gpt‑4o'`）解析为 `Model` 实例。 +- [`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 模型 -如果你传入非 GPT-5 的模型名称且未提供自定义 `modelSettings`，SDK 将回退到适用于任意模型的通用 `modelSettings`。 +如果您传入的是非 GPT-5 的模型名称且未设置自定义 `modelSettings`，SDK 将回退到与任意模型兼容的通用 `modelSettings`。 --- -## OpenAI 提供方 +## OpenAI 提供程序 -默认的 `ModelProvider` 使用 OpenAI API 来解析名称。它支持两个不同的端点： +默认的 `ModelProvider` 使用 OpenAI API 解析模型名称。它支持两个不同的端点： | API | 用途 | 调用 `setOpenAIAPI()` | | ---------------- | ------------------------------------------------ | ------------------------------------ | | Chat Completions | 标准聊天与函数调用 | `setOpenAIAPI('chat_completions')` | -| Responses | 新的以流式为先的生成式 API（工具调用、灵活输出） | `setOpenAIAPI('responses')` _(默认)_ | +| Responses | 新的以流式优先的生成式 API（工具调用、灵活输出） | `setOpenAIAPI('responses')` _(默认)_ | -### 认证 +### 身份验证 -如果你需要自定义网络设置，也可以通过 `setDefaultOpenAIClient(client)` 插入你自己的 `OpenAI` 客户端。 +如果您需要自定义网络设置，也可以通过 `setDefaultOpenAIClient(client)` 插入自有的 `OpenAI` 客户端。 --- ## ModelSettings -`ModelSettings` 与 OpenAI 的参数一一对应，但不依赖具体提供方。 +`ModelSettings` 与 OpenAI 的参数相对应，但与具体提供方无关。 | 字段 | 类型 | 说明 | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------- | -| `temperature` | `number` | 创造性 vs. 确定性。 | -| `topP` | `number` | 核采样。 | -| `frequencyPenalty` | `number` | 惩罚重复的 token。 | -| `presencePenalty` | `number` | 鼓励新 token。 | +| `temperature` | `number` | 创造性与确定性的权衡。 | +| `topP` | `number` | 核采样（Nucleus sampling）。 | +| `frequencyPenalty` | `number` | 惩罚重复的 tokens。 | +| `presencePenalty` | `number` | 鼓励新 tokens。 | | `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | 参见[强制使用工具](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 | | `parallelToolCalls` | `boolean` | 在支持的情况下允许并行函数调用。 | | `truncation` | `'auto' \| 'disabled'` | Token 截断策略。 | -| `maxTokens` | `number` | 响应中的最大 token 数。 | -| `store` | `boolean` | 持久化响应以用于检索/RAG 工作流。 | +| `maxTokens` | `number` | 响应中的最大 tokens 数。 | +| `store` | `boolean` | 持久化响应，便于检索 / RAG 工作流。 | | `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | 适用于 gpt-5 等的推理强度。 | -| `text.verbosity` | `'low' \| 'medium' \| 'high'` | 适用于 gpt-5 等的文本冗长度。 | +| `text.verbosity` | `'low' \| 'medium' \| 'high'` | 适用于 gpt-5 等的文本详尽程度。 | -可在任一层级附加设置： +可以在任一层级附加设置： -`Runner` 级别的设置会覆盖任何冲突的逐智能体设置。 +`Runner` 级的设置会覆盖任何与之冲突的按智能体级别设置。 --- ## 提示 -智能体可通过 `prompt` 参数进行配置，指向一个存储在服务器上的提示配置，用于控制智能体的行为。目前，此选项仅在你使用 OpenAI 的 +智能体可以通过 `prompt` 参数进行配置，指示应使用某个存储在服务器上的提示配置来控制智能体行为。目前，此选项仅在您使用 OpenAI 的 [Responses API](https://platform.openai.com/docs/api-reference/responses) 时受支持。 -| 字段 | 类型 | 说明 | -| ----------- | -------- | ------------------------------------------------------------------------------ | -| `promptId` | `string` | 提示的唯一标识符。 | -| `version` | `string` | 你希望使用的提示版本。 | -| `variables` | `object` | 要替换进提示中的变量键值对。值可以是字符串，或文本、图片、文件等内容输入类型。 | +| 字段 | 类型 | 说明 | +| ----------- | -------- | ----------------------------------------------------------------------------- | +| `promptId` | `string` | 提示的唯一标识符。 | +| `version` | `string` | 希望使用的提示版本。 | +| `variables` | `object` | 用于替换进提示中的键/值变量。值可以是字符串或文本、图像、文件等内容输入类型。 | -任何额外的智能体配置（如 tools 或 instructions）都会覆盖你在存储提示中配置的值。 +任何额外的智能体配置，如 tools 或 instructions，都会覆盖您在存储的提示中可能配置的值。 --- -## 自定义模型提供方 +## 自定义模型提供程序 -实现你自己的提供方很简单——实现 `ModelProvider` 与 `Model`，并将该提供方传入 `Runner` 构造函数： +实现您自己的提供程序很简单——实现 `ModelProvider` 和 `Model`，然后将该提供程序传递给 `Runner` 构造函数： --- ## 追踪导出器 -使用 OpenAI 提供方时，你可以通过提供 API 密钥来选择启用自动追踪导出： +当使用 OpenAI 提供程序时，您可以通过提供 API 密钥来选择启用自动追踪导出： -这会将追踪发送到 [OpenAI dashboard](https://platform.openai.com/traces)，你可以在其中检查工作流的完整执行图。 +这会将追踪发送到 [OpenAI dashboard](https://platform.openai.com/traces)，您可以在其中检查完整的工作流执行图。 --- ## 后续步骤 - 探索[运行智能体](/openai-agents-js/zh/guides/running-agents)。 -- 使用[工具](/openai-agents-js/zh/guides/tools)为你的模型赋能。 -- 按需添加[护栏](/openai-agents-js/zh/guides/guardrails)或[追踪](/openai-agents-js/zh/guides/tracing)。 +- 使用[工具](/openai-agents-js/zh/guides/tools)为模型赋能。 +- 视需要添加[护栏](/openai-agents-js/zh/guides/guardrails)或[追踪](/openai-agents-js/zh/guides/tracing)。 diff --git a/docs/src/content/docs/zh/guides/multi-agent.md b/docs/src/content/docs/zh/guides/multi-agent.md index 1ffcc9d8..2c6a07a7 100644 --- a/docs/src/content/docs/zh/guides/multi-agent.md +++ b/docs/src/content/docs/zh/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。这意味着在给定开放式任务时，LLM 可以自主规划如何处理任务，使用工具采取行动并获取数据，并通过交接将任务委派给子智能体。比如，一个研究智能体可以配备如下工具： +一个智能体是配备了 instructions、tools 和 handoffs 的 LLM。这意味着对于一个开放式任务，LLM 可以自主规划如何完成任务，使用工具采取行动并获取数据，并通过 handoffs 将任务委派给子智能体。例如，一个研究型智能体可以配备如下工具： -- Web 搜索以在网上查找信息 -- 文件搜索与检索以在专有数据和连接中搜索 -- 计算机操作以在计算机上执行动作 -- 代码执行以进行数据分析 -- 交接至擅长规划、撰写报告等的专业智能体 +- Web 搜索，用于在线查找信息 +- 文件搜索与检索，用于检索专有数据和连接 +- 计算机操作，用于在计算机上执行操作 +- 代码执行，用于进行数据分析 +- Handoffs 到擅长规划、报告撰写等的专业智能体 当任务是开放式且你希望依赖 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` 循环中运行，直到评估者认为输出满足某些标准。 -- 并行运行多个智能体，例如通过 JavaScript 基本组件如 `Promise.all`。当你有多个相互独立的任务时，这对速度很有帮助。 +- 使用[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/zh/guides/quickstart.mdx b/docs/src/content/docs/zh/guides/quickstart.mdx index fc964d78..7fe0cbf9 100644 --- a/docs/src/content/docs/zh/guides/quickstart.mdx +++ b/docs/src/content/docs/zh/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. 创建项目并初始化 npm。该步骤只需执行一次。 +1. 创建项目并初始化 npm。此步骤只需执行一次。 ```bash mkdir my_project @@ -25,20 +25,20 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm install @openai/agents zod@3 ``` -3. 设置 OpenAI API key。如果没有，请按照[这些说明](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)创建一个 OpenAI API key。 +3. 设置 OpenAI API key。如果还没有，请按照[这些说明](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)创建一个 OpenAI API key。 ```bash export OPENAI_API_KEY=sk-... ``` - 或者，您可以调用 `setDefaultOpenAIKey('')` 以编程方式设置密钥，并使用 `setTracingExportApiKey('')` 开启追踪。 - 详见[SDK 配置](/openai-agents-js/zh/guides/config)。 + 或者，您也可以调用 `setDefaultOpenAIKey('')` 在代码中设置 key，并使用 `setTracingExportApiKey('')` 进行追踪。 + 详情参见[SDK 配置](/openai-agents-js/zh/guides/config)。 ## 创建第一个智能体 -智能体通过 instructions 和名称来定义。 +智能体由 instructions 和名称定义。 ```typescript import { Agent } from '@openai/agents'; @@ -52,9 +52,9 @@ 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'; @@ -101,7 +101,7 @@ const agent = new Agent({ ## 添加更多智能体 -可以以类似方式定义其他智能体，将问题拆解为更小的部分，使智能体更专注于当前任务。还可以通过在智能体上定义模型，为不同问题使用不同的模型。 +可以以类似方式定义更多智能体，将问题拆分为更小的部分，使智能体更专注于当前任务。通过在智能体上定义模型，也可以针对不同问题使用不同的模型。 ```typescript const historyTutorAgent = new Agent({ @@ -119,7 +119,7 @@ const mathTutorAgent = new Agent({ ## 定义交接 -为了在多个智能体之间进行编排，您可以为某个智能体定义 `handoffs`。这将使该智能体能够把会话传递给下一个智能体。这会在运行过程中自动发生。 +为在多个智能体之间进行编排，您可以为某个智能体定义 `handoffs`。这将使其能够在对话过程中自动将会话交接给下一个智能体。 ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -131,7 +131,7 @@ const triageAgent = Agent.create({ }); ``` -在运行结束后，您可以通过查看执行结果上的 `finalAgent` 属性，了解最终由哪个智能体生成了响应。 +运行结束后，您可以通过查看运行结果中的 `finalAgent` 属性，了解是哪一个智能体生成了最终响应。 ## 运行智能体编排 @@ -148,17 +148,17 @@ async function main() { main().catch((err) => console.error(err)); ``` -## 整合示例 +## 综合示例 让我们把以上内容整合为一个完整示例。将其放入您的 `index.js` 文件并运行。 - + ## 查看追踪 -Agents SDK 会自动为您生成追踪。这使您可以审查智能体的运行方式、调用了哪些工具，或交接给了哪个智能体。 +Agents SDK 会为您自动生成追踪。这使您能够审查智能体的运行方式、调用了哪些工具，或交接给了哪个智能体。 -要查看智能体运行期间发生的情况，请前往 +要查看智能体运行期间发生的事件，请前往 [OpenAI Dashboard 中的 Trace viewer](https://platform.openai.com/traces)。 ## 后续步骤 diff --git a/docs/src/content/docs/zh/guides/release.mdx b/docs/src/content/docs/zh/guides/release.mdx index 1f66de5a..77755745 100644 --- a/docs/src/content/docs/zh/guides/release.mdx +++ b/docs/src/content/docs/zh/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`）版本 -对于未标记为 beta 的任何公共接口发生的**破坏性变更**，我们将提升次版本号 `Y`。例如，从 `0.0.x` 升到 `0.1.x` 可能包含破坏性变更。 +对于未标记为 beta 的任何公共接口发生的**破坏性变更**，我们会提升次版本号 `Y`。例如，从 `0.0.x` 升到 `0.1.x` 可能包含破坏性变更。 -如果您不希望引入破坏性变更，建议在项目中将版本固定到 `0.0.x`。 +如果你不希望引入破坏性变更，建议在项目中固定到 `0.0.x` 版本。 -## 修订版本（`Z`） +## 修订版（`Z`）版本 -对于非破坏性变更，我们将提升修订版本号 `Z`： +对于非破坏性变更，我们会提升 `Z`： - Bug 修复 - 新功能 - 对私有接口的更改 - 对 beta 功能的更新 -## 子包版本控制 +## 子包版本管理 -主包 `@openai/agents` 由多个可独立使用的子包组成。目前各包的版本是联动的，这意味着如果某个包版本提升，其他包也会随之提升。随着迈向 `1.0.0`，我们可能会改变这一策略。 +主包 `@openai/agents` 由多个可独立使用的子包组成。目前各包的版本是联动的，即任一包提升版本，其他包也会同步提升。随着我们迈向 `1.0.0`，这一策略可能会变化。 ## 更新日志 -我们为每个子包生成更新日志，以帮助了解发生了哪些变更。由于变更可能发生在某个子包中，您可能需要查看相应的更新日志以获取变更的详细信息。 +我们为每个子包生成更新日志，以帮助了解变更内容。由于更改可能发生在某个子包中，你可能需要查看相应的更新日志来获取变更详情。 - [`@openai/agents`](https://github.com/openai/openai-agents-js/blob/main/packages/agents/CHANGELOG.md) - [`@openai/agents-core`](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/CHANGELOG.md) diff --git a/docs/src/content/docs/zh/guides/results.mdx b/docs/src/content/docs/zh/guides/results.mdx index 6b30516c..828e186d 100644 --- a/docs/src/content/docs/zh/guides/results.mdx +++ b/docs/src/content/docs/zh/guides/results.mdx @@ -7,21 +7,21 @@ import { Code } from '@astrojs/starlight/components'; import handoffFinalOutputTypes from '../../../../../../examples/docs/results/handoffFinalOutputTypes.ts?raw'; import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts?raw'; -当你[运行你的智能体](/openai-agents-js/zh/guides/running-agents)时，你将会收到： +当你[运行智能体](/openai-agents-js/zh/guides/running-agents)时，你将会得到： - 如果调用 `run` 且未设置 `stream: true`，则返回 [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) -- 如果调用 `run` 且设置了 `stream: true`，则返回 [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。关于流式传输的详情，请参阅[流式传输](/openai-agents-js/zh/guides/streaming)。 +- 如果调用 `run` 且设置了 `stream: true`，则返回 [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。关于流式传输的细节，参见[流式传输](/openai-agents-js/zh/guides/streaming)。 ## 最终输出 `finalOutput` 属性包含最后一个运行的智能体的最终输出。该结果可能是： -- `string` — 任何未定义 `outputType` 的智能体的默认类型 -- `unknown` — 如果智能体将 JSON schema 定义为输出类型。在这种情况下 JSON 已被解析，但你仍需手动验证其类型。 -- `z.infer` — 如果智能体将 Zod schema 定义为输出类型。输出将自动按该 schema 解析。 -- `undefined` — 如果智能体未产生输出（例如在产生输出前被停止） +- `string`——默认值，适用于未定义 `outputType` 的任何智能体 +- `unknown`——当智能体的输出类型定义为 JSON schema 时。在这种情况下，JSON 已被解析，但你仍需手动验证其类型。 +- `z.infer`——当智能体的输出类型定义为 Zod schema 时。输出会自动按该 schema 进行解析。 +- `undefined`——当智能体未产生输出（例如在产生输出前已停止） -如果你使用了具有不同输出类型的交接，应使用 `Agent.create()` 方法而不是 `new Agent()` 构造函数来创建智能体。 +如果你使用了具有不同输出类型的交接，应使用 `Agent.create()` 方法而非 `new Agent()` 构造函数来创建智能体。 这将使 SDK 能够在所有可能的交接中推断输出类型，并为 `finalOutput` 属性提供联合类型。 @@ -35,55 +35,55 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? ## 下一轮输入 -有两种方式可以获取下一轮的输入： +有两种方式获取下一轮的输入： -- `result.history` — 包含你的输入和智能体输出的副本。 -- `result.output` — 包含整个智能体运行的输出。 +- `result.history`——包含你的输入和智能体输出的副本。 +- `result.output`——包含整个智能体运行的输出。 -在类似聊天的用例中，`history` 是维护完整历史的便捷方式： +在类聊天场景中，`history` 是维护完整历史的便捷方式： ## 最后一个智能体 -`lastAgent` 属性包含最后一个运行的智能体。根据你的应用，这通常对用户下次输入很有用。例如，如果你有一个前线分诊智能体会交接到特定语言的智能体，你可以存储最后一个智能体，并在用户下次给智能体发消息时复用它。 +`lastAgent` 属性包含最后一个运行的智能体。根据你的应用，这通常对用户下一次输入很有用。例如，如果你有一个前线分诊智能体会交接至特定语言的智能体，你可以存储最后一个智能体，并在用户下一次与智能体对话时复用它。 -在流式模式下，访问 `currentAgent` 属性也很有用，它映射到当前正在运行的智能体。 +在流式传输模式下，访问映射到当前正在运行的智能体的 `currentAgent` 属性也很有用。 -## 新增项 +## 新增条目 -`newItems` 属性包含在运行期间生成的新增项。这些项是 [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem)。运行项包装了由 LLM 生成的原始项。除了用于访问 LLM 的输出外，还可用于查看这些事件关联的是哪个智能体。 +`newItems` 属性包含在运行期间生成的新条目。条目是 [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem)。运行条目包装了 LLM 生成的原始条目。除了访问 LLM 的输出外，它们还能用于了解这些事件关联的是哪个智能体。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) 表示来自 LLM 的消息。原始项是生成的消息。 -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) 表示 LLM 调用了交接工具。原始项是来自 LLM 的工具调用项。 -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) 表示发生了交接。原始项是对交接工具调用的工具响应。你还可以从该项访问源/目标智能体。 +- [`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 的工具调用项。 +- [`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/zh/guides/running-agents#exceptions)或处理[`中断`](#interruptions)时，也可作为后续调用 `run` 的输入。 +`state` 属性包含此次运行的状态。附加到 `result` 上的大多数信息均源自 `state`，但 `state` 可序列化/反序列化，并且在你需要[从错误中恢复](/openai-agents-js/zh/guides/running-agents#exceptions)或处理[`interruption`](#interruptions)时，也可作为后续调用 `run` 的输入。 ## 中断 -如果你在智能体中使用了 `needsApproval`，你的 `run` 可能会触发一些你需要在继续前处理的 `interruptions`。此时 `interruptions` 将是导致中断的 `ToolApprovalItem` 数组。参阅[人机协作](/openai-agents-js/zh/guides/human-in-the-loop)以了解如何处理中断的更多信息。 +如果你在智能体中使用了 `needsApproval`，你的 `run` 可能会触发一些需要处理后才能继续的 `interruptions`。在这种情况下，`interruptions` 将是导致中断的 `ToolApprovalItem` 数组。有关如何处理中断的更多信息，请参阅[人机协作](/openai-agents-js/zh/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/zh/guides/running-agents.mdx b/docs/src/content/docs/zh/guides/running-agents.mdx index e866a36a..bfecba42 100644 --- a/docs/src/content/docs/zh/guides/running-agents.mdx +++ b/docs/src/content/docs/zh/guides/running-agents.mdx @@ -11,80 +11,80 @@ 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 时，也可以使用 `run()` 工具，它会运行一个单例的默认 `Runner` 实例。 +当你不需要自定义 runner 时，也可以使用 `run()` 实用函数，它会运行一个单例的默认 `Runner` 实例。 -或者，你也可以创建自己的 runner 实例： +或者，你可以创建自己的 runner 实例： -运行智能体后，你会收到一个[执行结果](/openai-agents-js/zh/guides/results)对象，其中包含最终输出以及本次运行的完整历史。 +运行智能体后，你将收到一个[执行结果](/openai-agents-js/zh/guides/results)对象，其中包含最终输出以及本次运行的完整历史记录。 ## 智能体循环 -当你在 Runner 中使用 run 方法时，你需要传入一个起始智能体和输入。输入可以是字符串（视为用户消息），也可以是输入项列表，即 OpenAI Responses API 中的各类项目。 +当你使用 Runner 的 run 方法时，你需要传入一个起始智能体和输入。输入可以是字符串（被视为一条用户消息），也可以是输入项列表，即 OpenAI Responses API 中的项目。 -随后 runner 会运行一个循环： +然后 runner 会运行一个循环： 1. 使用当前输入调用当前智能体的模型。 -2. 检查 LLM 响应。 +2. 检查 LLM 的响应。 - **最终输出** → 返回。 - - **交接** → 切换到新智能体，保留累积的对话历史，回到步骤 1。 - - **工具调用** → 执行工具，将其结果追加到对话中，回到步骤 1。 -3. 一旦达到 `maxTurns`，抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 + - **交接** → 切换到新的智能体，保留累积的会话历史，回到步骤 1。 + - **工具调用** → 执行工具，将其结果追加到会话中，回到步骤 1。 +3. 当达到 `maxTurns` 时抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 ### Runner 生命周期 -在应用启动时创建一个 `Runner` 并在各个请求间复用。该实例存储全局配置，如模型提供方与追踪选项。仅当需要完全不同的配置时才创建新的 `Runner`。对于简单脚本，你也可以调用内部使用默认 runner 的 `run()`。 +在应用启动时创建一个 `Runner` 并在各个请求之间复用。该实例存储全局配置，例如模型提供方和追踪选项。只有当你需要完全不同的配置时才创建另一个 `Runner`。对于简单脚本，你也可以调用 `run()`，它会在内部使用默认 runner。 ## 运行参数 -`run()` 方法的输入包括：用于开始运行的初始智能体、运行的输入以及一组选项。 +`run()` 方法的输入包括用于启动运行的初始智能体、运行的输入以及一组选项。 -输入可以是字符串（视为用户消息），或一组[输入项](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem)，也可以是在你构建[人机协作](/openai-agents-js/zh/guides/human-in-the-loop)智能体时使用的 [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) 对象。 +输入可以是字符串（被视为一条用户消息）、[输入项](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem)列表，或在构建[人机协作](/openai-agents-js/zh/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/zh/guides/context)。 | -| `maxTurns` | `10` | 安全上限——达到后抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 | -| `signal` | – | 用于取消的 `AbortSignal`。 | +| Option | Default | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | +| `stream` | `false` | 如果为 `true`，调用将返回一个 `StreamedRunResult`，并在事件从模型到达时逐步发出。 | +| `context` | – | 转发到每个工具 / 护栏 / 交接的上下文对象。详见[上下文管理](/openai-agents-js/zh/guides/context)。 | +| `maxTurns` | `10` | 安全限制——达到该值时抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 | +| `signal` | – | 用于取消的 `AbortSignal`。 | ## 流式传输 -流式传输允许你在 LLM 运行过程中额外接收流式事件。流启动后，`StreamedRunResult` 将包含关于本次运行的完整信息，包括所有新产生的输出。你可以使用 `for await` 循环迭代流式事件。详见[流式传输](/openai-agents-js/zh/guides/streaming)。 +流式传输允许你在 LLM 运行时接收额外的流式事件。流启动后，`StreamedRunResult` 将包含关于此次运行的完整信息，包括所有新生成的输出。你可以使用 `for await` 循环迭代这些流式事件。阅读[流式传输](/openai-agents-js/zh/guides/streaming)指南了解更多。 ## 运行配置 -如果你创建自己的 `Runner` 实例，可以传入 `RunConfig` 对象来配置 runner。 +如果你要创建自己的 `Runner` 实例，可以传入一个 `RunConfig` 对象来配置 runner。 | Field | Type | Purpose | | --------------------------- | --------------------- | ------------------------------------------------------------- | | `model` | `string \| Model` | 为运行中的**所有**智能体强制指定特定模型。 | -| `modelProvider` | `ModelProvider` | 解析模型名称——默认使用 OpenAI 提供方。 | -| `modelSettings` | `ModelSettings` | 覆盖按智能体设置的全局调优参数。 | -| `handoffInputFilter` | `HandoffInputFilter` | 执行交接时修改输入项（如果交接本身尚未定义该逻辑）。 | +| `modelProvider` | `ModelProvider` | 解析模型名称——默认为 OpenAI 提供方。 | +| `modelSettings` | `ModelSettings` | 覆盖每个智能体设置的全局调优参数。 | +| `handoffInputFilter` | `HandoffInputFilter` | 执行交接时用于变更输入项（如果交接本身未定义）的过滤器。 | | `inputGuardrails` | `InputGuardrail[]` | 应用于*初始*用户输入的护栏。 | | `outputGuardrails` | `OutputGuardrail[]` | 应用于*最终*输出的护栏。 | | `tracingDisabled` | `boolean` | 完全禁用 OpenAI 追踪。 | | `traceIncludeSensitiveData` | `boolean` | 在仍然发出 span 的同时，将 LLM/工具的输入与输出从追踪中排除。 | -| `workflowName` | `string` | 显示在 Traces 仪表板中——有助于对相关运行进行分组。 | -| `traceId` / `groupId` | `string` | 手动指定 trace 或 group ID，而非由 SDK 自动生成。 | +| `workflowName` | `string` | 显示在 Traces 仪表板中——有助于将相关运行分组。 | +| `traceId` / `groupId` | `string` | 手动指定 trace 或 group ID，而不是交由 SDK 自动生成。 | | `traceMetadata` | `Record` | 附加到每个 span 的任意元数据。 | ## 会话 / 聊天线程 -每次调用 `runner.run()`（或 `run()` 工具）代表你在应用层对话中的一个**轮次**。你可以自行决定向终端用户展示多少 `RunResult` 内容——有时仅展示 `finalOutput`，有时展示每个生成的项目。 +每次调用 `runner.run()`（或 `run()` 实用函数）都代表你的应用层会话中的一个**轮次**。你可以自行决定向终端用户展示多少 `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 为你持久化会话历史，而无需在每个轮次都发送完整的本地话术。这在协调长对话或多个服务时很有用。详见[会话状态指南](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 提供两种复用服务器端状态的方式： -#### 1. 使用 `conversationId` 覆盖整段会话 +#### 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` 从上个轮次继续 +#### 2. 使用 `previousResponseId` 从上一个轮次继续 -如果你无论如何都想仅从 Responses API 开始，你可以通过前一次响应返回的 ID 将每个请求串联起来。这样无需创建完整的会话资源也能在轮次间保持上下文。 +如果你只想从 Responses API 开始，可以使用上一个响应返回的 ID 串联每个请求。这样无需创建完整的会话资源也能在轮次之间保持上下文。 + -启用流式传输后，返回的 `stream` 实现了 `AsyncIterable` 接口。每个产出的事件都是一个对象，用来描述本次运行中发生了什么。该流会产出三种事件类型之一，分别对应智能体执行的不同部分。大多数应用只需要模型的文本，因此流也提供了便捷方法。 +启用流式传输后，返回的 `stream` 实现了 `AsyncIterable` 接口。每个产出的事件都是一个对象，描述运行期间发生的事。该流会产出三种事件类型之一，分别对应智能体执行的不同部分。大多数应用只关心模型的文本，因此流提供了辅助方法。 ### 获取文本输出 -调用 `stream.toTextStream()` 获取已发送文本的流。当 `compatibleWithNodeStreams` 为 `true` 时，返回值是一个常规的 Node.js `Readable`。我们可以直接将其管道传输到 `process.stdout` 或其他目标。 +调用 `stream.toTextStream()` 以获取已发出的文本流。当 `compatibleWithNodeStreams` 为 `true` 时，返回值是标准的 Node.js `Readable`。我们可以将其直接管道到 `process.stdout` 或其他目标。 -当运行及所有挂起的回调完成后，`stream.completed` 这个 promise 会被 resolve。若要确保没有更多输出，请务必等待它完成。 +当运行及所有挂起的回调完成后，`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) 获取一个完整脚本，同时打印纯文本流和原始事件流。 +请参阅[流式示例](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts)，其中包含一个完整脚本，同时打印纯文本流和原始事件流。 ## 事件类型 @@ -75,7 +83,7 @@ type RunItemStreamEvent = { }; ``` -交接负载示例： +示例交接负载： ```json { @@ -112,21 +120,21 @@ type RunAgentUpdatedStreamEvent = { ## 流式传输中的人工干预 -流式传输与会暂停执行的交接兼容（例如当某个工具需要审批时）。流对象上的 `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)。 ## 提示 -- 退出前请记得等待 `stream.completed`，以确保所有输出都已刷新。 -- 初始的 `{ stream: true }` 选项只对提供它的那次调用生效。如果你使用 `RunState` 重新运行，必须再次指定该选项。 -- 如果应用只关心文本结果，优先使用 `toTextStream()`，以避免逐个处理事件对象。 +- 退出前请记得等待 `stream.completed`，以确保所有输出已刷新。 +- 初始的 `{ stream: true }` 选项只适用于提供它的那次调用。如果你使用 `RunState` 重新运行，必须再次指定该选项。 +- 如果你的应用只关心文本结果，优先使用 `toTextStream()`，以避免处理单个事件对象。 -借助流式传输和事件系统，你可以将智能体集成到聊天界面、终端应用，或任何用户能从增量更新中受益的场景中。 +借助流式传输和事件系统，你可以将智能体集成到聊天界面、终端应用或任何用户受益于增量更新的场景中。 diff --git a/docs/src/content/docs/zh/guides/tools.mdx b/docs/src/content/docs/zh/guides/tools.mdx index 63ad377e..c648b983 100644 --- a/docs/src/content/docs/zh/guides/tools.mdx +++ b/docs/src/content/docs/zh/guides/tools.mdx @@ -10,12 +10,12 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -工具让智能体**执行操作**——获取数据、调用外部 API、执行代码，甚至进行计算机操作。JavaScript/TypeScript SDK 支持四种类别： +工具让智能体能够**执行操作**——获取数据、调用外部 API、执行代码，甚至进行计算机操作。JavaScript/TypeScript SDK 支持四种类别： 1. **托管工具**——与模型一起在 OpenAI 服务器上运行。（Web 搜索、文件搜索、计算机操作、Code Interpreter、图像生成） -2. **函数工具**——用 JSON schema 包装任意本地函数，使 LLM 可调用。 -3. **智能体作为工具**——将整个智能体暴露为可调用的工具。 -4. **本地 MCP 服务器**——挂载运行在你机器上的 Model context protocol 服务器。 +2. **函数工具**——用 JSON schema 包装任意本地函数，让 LLM 可以调用。 +3. **智能体作为工具**——将整个智能体暴露为可调用工具。 +4. **本地 MCP 服务器**——挂载运行在你机器上的 Model Context Protocol 服务器。 --- @@ -23,17 +23,17 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer 当你使用 `OpenAIResponsesModel` 时，可以添加以下内置工具： -| 工具 | 类型字符串 | 作用 | -| ----------------------- | -------------------- | -------------------------------- | -| Web search | `'web_search'` | 互联网搜索。 | -| File / retrieval search | `'file_search'` | 查询托管在 OpenAI 上的向量存储。 | -| 计算机操作 | `'computer'` | 自动化 GUI 交互。 | -| Code Interpreter | `'code_interpreter'` | 在沙盒环境中运行代码。 | -| 图像生成 | `'image_generation'` | 基于文本生成图像。 | +| 工具 | 类型字符串 | 目的 | +| ---------------- | -------------------- | ---------------------------- | +| Web 搜索 | `'web_search'` | 互联网搜索。 | +| 文件/检索搜索 | `'file_search'` | 查询 OpenAI 托管的向量存储。 | +| 计算机操作 | `'computer'` | 自动化 GUI 交互。 | +| Code Interpreter | `'code_interpreter'` | 在沙盒环境中运行代码。 | +| 图像生成 | `'image_generation'` | 基于文本生成图像。 | -具体参数集合与 OpenAI Responses API 保持一致——参见官方文档以获取 `rankingOptions` 或语义过滤等高级选项。 +具体参数与 OpenAI Responses API 完全一致——高级选项如 `rankingOptions` 或语义过滤请参考官方文档。 --- @@ -44,23 +44,23 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer ### 选项参考 -| 字段 | 必填 | 描述 | +| 字段 | 必填 | 说明 | | --------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | 否 | 默认为函数名（例如 `get_weather`）。 | | `description` | 是 | 清晰、可读的人类描述，展示给 LLM。 | -| `parameters` | 是 | 可以是 Zod schema 或原始 JSON schema 对象。使用 Zod 参数会自动启用 **strict** 模式。 | -| `strict` | 否 | 当为 `true`（默认）时，如果参数校验不通过，SDK 会返回模型错误。将其设为 `false` 可进行模糊匹配。 | -| `execute` | 是 | `(args, context) => string \| Promise`——你的业务逻辑。第二个参数可选，为 `RunContext`。 | +| `parameters` | 是 | Zod schema 或原始 JSON schema 对象。使用 Zod 参数会自动启用 **strict** 模式。 | +| `strict` | 否 | 当为 `true`（默认）时，如果参数校验失败，SDK 会返回模型错误。将其设为 `false` 以进行模糊匹配。 | +| `execute` | 是 | `(args, context) => string \| Promise`——你的业务逻辑。可选的第二个参数为 `RunContext`。 | | `errorFunction` | 否 | 自定义处理器 `(context, error) => string`，用于将内部错误转换为对用户可见的字符串。 | ### 非严格 JSON schema 工具 -如果你需要模型在输入无效或不完整时进行“猜测”，可以在使用原始 JSON schema 时关闭严格模式： +如果你需要模型在输入无效或不完整时进行“猜测”，可在使用原始 JSON schema 时禁用严格模式： -完整示例见 [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts)。此外，如果你在寻找关于 MCP 服务器工具集成的综合指南，请参阅 [MCP 集成](/openai-agents-js/zh/guides/mcp) 了解详情。 +完整示例见 [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts)。此外，如果你在寻找有关 MCP 服务器工具集成的全面指南，请参阅 [MCP 集成](/openai-agents-js/zh/guides/mcp) 获取详情。 --- ## 工具使用行为 -参见 [智能体](/openai-agents-js/zh/guides/agents#forcing-tool-use) 了解如何控制模型必须何时以及如何使用工具（`tool_choice`、`toolUseBehavior` 等）。 +关于控制模型何时以及如何必须使用工具（`tool_choice`、`toolUseBehavior` 等），请参考[智能体](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 --- ## 最佳实践 -- **简短且明确的描述**——说明工具做什么，以及何时使用它。 +- **简短且明确的描述**——说明工具做什么以及何时使用。 - **校验输入**——尽可能使用 Zod schema 进行严格的 JSON 校验。 - **避免在错误处理器中产生副作用**——`errorFunction` 应返回有用的字符串，而不是抛出异常。 - **单一职责**——小而可组合的工具有助于更好的模型推理。 @@ -114,6 +114,6 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer ## 后续步骤 -- 了解[强制使用工具](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 +- 了解[强制工具使用](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 - 添加[护栏](/openai-agents-js/zh/guides/guardrails)以校验工具输入或输出。 -- 查阅 TypeDoc 参考：[`tool()`](/openai-agents-js/openai/agents/functions/tool) 以及各种托管工具类型。 +- 查阅 TypeDoc 参考：[`tool()`](/openai-agents-js/openai/agents/functions/tool) 以及各类托管工具类型。 diff --git a/docs/src/content/docs/zh/guides/tracing.mdx b/docs/src/content/docs/zh/guides/tracing.mdx index 53f6c586..acfe3c8a 100644 --- a/docs/src/content/docs/zh/guides/tracing.mdx +++ b/docs/src/content/docs/zh/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 dashboard](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` 调用强制刷新，确保在 worker 退出前完成导出。 +例如，在 Cloudflare Worker 中，你应将代码包裹在 `try/catch/finally` 中，并结合 `waitUntil` 使用强制刷新，以确保在 worker 退出前导出追踪。 -## 跟踪与 Span +## 跟踪与跨度 -- **Traces（跟踪）** 表示一次“工作流”的端到端操作，由多个 Span 组成。Trace 具有以下属性： - - `workflow_name`：逻辑工作流或应用名称。例如 “Code generation” 或 “Customer service”。 - - `trace_id`：该跟踪的唯一 ID。如未传入会自动生成。格式必须为 `trace_<32_alphanumeric>`。 - - `group_id`：可选的分组 ID，用于关联同一会话中的多条跟踪。例如可使用聊天线程 ID。 - - `disabled`：若为 True，则不会记录该跟踪。 - - `metadata`：跟踪的可选元数据。 -- **Spans** 表示有起止时间的操作。Span 包含： +- **Traces（跟踪）** 表示一次“工作流”的端到端操作。它由多个 Spans 组成。Trace 具有以下属性： + - `workflow_name`：逻辑上的工作流或应用。例如 “Code generation” 或 “Customer service”。 + - `trace_id`：该 Trace 的唯一 ID。若不传则自动生成。格式必须为 `trace_<32_alphanumeric>`。 + - `group_id`：可选的分组 ID，用于关联同一会话中的多个 Trace。例如，你可以使用聊天线程 ID。 + - `disabled`：若为 True，则不会记录该 Trace。 + - `metadata`：Trace 的可选元数据。 +- **Spans（跨度）** 表示有开始与结束时间的操作。Span 包含： - `started_at` 与 `ended_at` 时间戳。 - - `trace_id`，标识其所属的跟踪 - - `parent_id`，指向该 Span 的父 Span（若有） - - `span_data`，Span 的信息。例如，`AgentSpanData` 包含智能体信息，`GenerationSpanData` 包含 LLM 生成信息等。 + - `trace_id`，表示其所属的 Trace + - `parent_id`，指向其父 Span（若有） + - `span_data`，关于该 Span 的信息。例如，`AgentSpanData` 包含关于智能体的信息，`GenerationSpanData` 包含关于 LLM 生成的信息，等等。 -## 默认追踪 +## 默认跟踪 默认情况下，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) 配置名称及其他属性。 +默认的 Trace 名称为 "Agent workflow"。你可以使用 `withTrace` 设置该名称，或者通过 [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) 配置名称及其他属性。 -此外，你可以设置[自定义追踪处理器](#custom-tracing-processors)，将跟踪发送到其他目标（替代或作为辅助目的地）。 +此外，你可以设置[自定义追踪处理器](#custom-tracing-processors)，将追踪推送到其他目的地（作为替代或次要目的地）。 -### 语音智能体追踪 +### 语音智能体跟踪 -如果你使用默认的 OpenAI Realtime API 下的 `RealtimeAgent` 和 `RealtimeSession`，追踪会自动在 Realtime API 侧进行，除非你在 `RealtimeSession` 上通过 `tracingDisabled: true` 或环境变量 `OPENAI_AGENTS_DISABLE_TRACING` 禁用了它。 +如果你在使用 `RealtimeAgent` 和 `RealtimeSession` 搭配默认的 OpenAI Realtime API，追踪将自动在 Realtime API 侧进行，除非你在 `RealtimeSession` 上通过 `tracingDisabled: true` 或设置环境变量 `OPENAI_AGENTS_DISABLE_TRACING` 来禁用它。 查看[语音智能体概述](/openai-agents-js/zh/guides/voice-agents)了解更多详情。 ## 更高层级的跟踪 -有时，你可能希望多次调用 `run()` 属于同一个跟踪。可以将整段代码包裹在 `withTrace()` 中实现。 +有时，你可能希望多次调用 `run()` 属于同一个 Trace。你可以将整段代码包裹在 `withTrace()` 中实现。 -1. 因为两次 `run` 调用被 `withTrace()` 包裹，单独的运行会归入同一总跟踪中，而不是创建两条跟踪。 +1. 由于两次对 `run` 的调用都被 `withTrace()` 包裹，这些单次运行将归入同一个整体 Trace，而不是创建两个 Trace。 ## 创建跟踪 -你可以使用 [`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 创建跟踪。或者，你也可以使用 `getGlobalTraceProvider().createTrace()` 手动创建一个新的跟踪并传入 `withTrace()`。 +你可以使用 [`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 函数来创建一个 Trace。或者，你也可以使用 `getGlobalTraceProvider().createTrace()` 手动创建一个新的 Trace，并将其传入 `withTrace()`。 -当前跟踪通过 [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 或相应环境的 polyfill 进行追踪。这意味着它可自动适配并发。 +当前 Trace 通过 [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 或相应环境的 polyfill 进行跟踪。这意味着它能自动与并发协同工作。 -## 创建 Span +## 创建跨度 -你可以使用各类 `create*Span()`（例如 `createGenerationSpan()`、`createFunctionSpan()` 等）方法创建 Span。通常无需手动创建 Span。也可使用 [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 函数来追踪自定义 Span 信息。 +你可以使用各类 `create*Span()`（如 `createGenerationSpan()`、`createFunctionSpan()` 等）方法来创建 Span。通常无需手动创建 Span。提供了一个 [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 函数用于跟踪自定义 Span 信息。 -Span 会自动归入当前跟踪，并嵌套在最近的当前 Span 之下；其通过 [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 或相应环境的 polyfill 进行追踪。 +Span 会自动归入当前 Trace，并嵌套在最近的当前 Span 下方，该 Span 通过 [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 或相应环境的 polyfill 进行跟踪。 ## 敏感数据 某些 Span 可能会捕获潜在的敏感数据。 `createGenerationSpan()` 会存储 LLM 生成的输入/输出，而 `createFunctionSpan()` 会存储函数调用的输入/输出。这些可能包含敏感数据，因此你可以通过 [`RunConfig.traceIncludeSensitiveData -`](/openai-agents-js/openai/agents-core/type-aliases/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/)，批量将跟踪/Span 发送给 [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/)，后者再将其批量导出到 OpenAI 后端。 +- 在初始化时，我们创建一个全局的 [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider)，负责创建 Trace，并可通过 [`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 后端。 -若要自定义上述默认设置，将跟踪发送到替代或额外的后端，或修改导出器行为，有两种选择： +若要自定义该默认设置，将追踪发送到替代或附加的后端，或修改导出器行为，你有两种选择： -1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) 允许你添加一个“额外的”追踪处理器，使其在跟踪和 Span 就绪时接收它们。这使你可以在将跟踪发送到 OpenAI 后端之外进行自定义处理。 -2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) 允许你“替换”默认处理器，使用你自己的处理器。除非包含会将数据发送到 OpenAI 后端的 `TracingProcessor`，否则跟踪将不会被发送到 OpenAI 后端。 +1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) 允许你添加一个**额外的**追踪处理器，它会在追踪和跨度就绪时接收它们。这样你可以在将追踪发送到 OpenAI 后端之外，进行你自己的处理。 +2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) 允许你**替换**默认处理器为你自己的追踪处理器。这意味着除非你包含一个将追踪发送到 OpenAI 后端的 `TracingProcessor`，否则追踪将不会发送到 OpenAI 后端。 -## 外部追踪处理器列表 +## 外部跟踪处理器列表 - [AgentOps](https://docs.agentops.ai/v2/usage/typescript-sdk#openai-agents-integration) - [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agents-sdk-js) diff --git a/docs/src/content/docs/zh/guides/troubleshooting.mdx b/docs/src/content/docs/zh/guides/troubleshooting.mdx index 6bb9196d..0ff97dfa 100644 --- a/docs/src/content/docs/zh/guides/troubleshooting.mdx +++ b/docs/src/content/docs/zh/guides/troubleshooting.mdx @@ -5,37 +5,37 @@ 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，但目前存在一些限制： +- **Cloudflare Workers**：Agents SDK 可在 Cloudflare Workers 中使用，但目前存在一些限制： - SDK 目前需要启用 `nodejs_compat` - - 需要在请求结束时手动刷新追踪数据。有关更多详情，[参阅追踪](/openai-agents-js/zh/guides/tracing#export-loop-lifecycle)。 + - 需要在请求结束时手动刷新追踪数据。参阅[追踪](/openai-agents-js/zh/guides/tracing#export-loop-lifecycle)获取更多详情。 - 由于 Cloudflare Workers 对 `AsyncLocalStorage` 的支持有限，部分追踪可能不准确 - - 出站 WebSocket 连接必须使用基于 fetch 的升级方式（不能使用全局 `WebSocket` 构造函数）。对于 Realtime，请使用 `@openai/agents-extensions` 中的 Cloudflare 传输（`CloudflareRealtimeTransportLayer`）。 -- **Browsers**： - - 浏览器中当前不支持追踪 + - 出站 WebSocket 连接必须使用基于 fetch 的升级方式（而非全局的 `WebSocket` 构造函数）。对于 Realtime，请使用 `@openai/agents-extensions` 中的 Cloudflare 传输（`CloudflareRealtimeTransportLayer`）。 +- **浏览器**： + - 浏览器中目前不支持追踪 - **v8 isolates**： - - 如果使用带有正确浏览器 polyfill 的打包器，您应该可以为 v8 isolates 打包该 SDK，但追踪将无法工作 - - v8 isolates 尚未经过广泛测试 + - 如果使用具备合适浏览器 polyfill 的打包工具，虽然可以为 v8 isolates 打包 SDK，但追踪功能将无法使用 + - v8 isolates 尚未经过充分测试 ## 调试日志 如果您在使用 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` — 实时智能体组件 +- `openai-agents:realtime` — Realtime Agents 组件 diff --git a/docs/src/content/docs/zh/guides/voice-agents.mdx b/docs/src/content/docs/zh/guides/voice-agents.mdx index 82050fc6..d4699cdc 100644 --- a/docs/src/content/docs/zh/guides/voice-agents.mdx +++ b/docs/src/content/docs/zh/guides/voice-agents.mdx @@ -25,27 +25,27 @@ import thinClientExample from '../../../../../../examples/docs/voice-agents/thin ![实时智能体](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) -语音智能体使用 OpenAI 语音到语音模型，提供实时语音聊天。这些模型支持音频、文本与工具调用的流式传输，非常适合语音/电话客服、移动应用体验和语音聊天等场景。 +语音智能体使用 OpenAI 语音到语音模型提供实时语音聊天。这些模型支持音频、文本和工具调用的流式传输，非常适合语音/电话客服、移动应用体验和语音聊天等场景。 -Voice Agents SDK 提供了 [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) 的 TypeScript 客户端。 +Voice Agents SDK 为 [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) 提供 TypeScript 客户端。 -### 关键功能 +### 关键特性 - 通过 WebSocket 或 WebRTC 连接 -- 既可用于浏览器也可用于后端连接 +- 可用于浏览器与后端连接 - 音频与打断处理 - 通过交接实现多智能体编排 - 工具定义与调用 - 自定义护栏以监控模型输出 -- 流式事件回调 -- 文本与语音智能体复用同一套组件 +- 针对流式事件的回调 +- 文本与语音智能体复用相同组件 -借助语音到语音模型，我们可以让模型实时处理音频，而无需在模型完成推理后先转写为文本再将文本转换回音频。 +通过使用语音到语音模型，我们可以利用模型对音频的实时处理能力，而无需在模型完成后先转写再将文本转换回音频。 ![语音到语音模型](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) diff --git a/docs/src/content/docs/zh/guides/voice-agents/build.mdx b/docs/src/content/docs/zh/guides/voice-agents/build.mdx index e52466fb..13cb7382 100644 --- a/docs/src/content/docs/zh/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/zh/guides/voice-agents/build.mdx @@ -30,134 +30,134 @@ import turnDetectionExample from '../../../../../../../examples/docs/voice-agent ## 音频处理 -某些传输层（如默认的 `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` 对象的一部分直接传递。 ## 交接 -与常规智能体类似，你可以使用交接将你的智能体拆分为多个智能体，在它们之间进行编排，以提升智能体的性能并更好地限定问题范围。 +与常规智能体类似，你可以使用交接将一个智能体拆分为多个智能体，并在它们之间进行编排，以提升智能体性能并更好地限定问题范围。 -与常规智能体不同，交接在实时智能体中行为略有不同。执行交接时，进行中的会话会更新为新的智能体配置。因此，智能体会自动访问进行中的对话历史，并且当前不会应用输入过滤器。 +与常规智能体不同，交接在实时智能体上的行为略有差异。执行交接时，进行中的会话会更新为新的智能体配置。由此，智能体会自动访问正在进行的对话历史，并且当前不会应用输入过滤器。 -此外，这意味着在交接过程中不能更改 `voice` 或 `model`。你也只能连接到其他实时智能体。如果你需要使用不同的模型，例如像 `gpt-5-mini` 这样的推理模型，你可以使用[通过工具进行委托](#delegation-through-tools)。 +此外，这意味着在交接过程中不能更改 `voice` 或 `model`。你也只能连接到其他实时智能体。如果你需要使用不同的模型，例如像 `gpt-5-mini` 这样的推理模型，可以使用[通过工具进行委派](#delegation-through-tools)。 ## 工具 -与常规智能体一样，实时智能体可以调用工具执行操作。你可以使用和常规智能体相同的 `tool()` 函数定义工具。 +与常规智能体一样，实时智能体可以调用工具执行操作。你可以使用与常规智能体相同的 `tool()` 函数定义工具。 -你只能在实时智能体中使用函数工具，并且这些工具会在与你的实时会话相同的位置执行。这意味着如果你在浏览器中运行实时会话，你的工具也会在浏览器中执行。如果需要执行更敏感的操作，你可以在工具内向你的后端服务器发起 HTTP 请求。 +你只能在实时智能体中使用函数工具，并且这些工具会在与你的实时会话相同的位置执行。这意味着如果你的实时会话在浏览器中运行，你的工具也将在浏览器中执行。如果需要执行更敏感的操作，你可以在工具内向后端服务器发起 HTTP 请求。 -工具执行期间，智能体无法处理来自用户的新请求。改进体验的一种方式是让智能体在即将执行工具时进行提示，或说出特定短语，为执行工具争取时间。 +工具执行期间，智能体无法处理来自用户的新请求。改进体验的一种方式是在你的智能体即将执行工具时进行提示，或让其说出特定短语以争取时间来执行工具。 -### 访问会话历史 +### 访问对话历史 -除了智能体调用特定工具时的参数外，你还可以访问由实时会话追踪的当前对话历史的快照。如果你需要基于当前对话状态执行更复杂的操作，或计划使用[用于委托的工具](#delegation-through-tools)，这会很有用。 +除了访问智能体调用某个工具时传递的参数外，你还可以访问由实时会话跟踪的当前对话历史快照。如果你需要基于对话的当前状态执行更复杂的操作，或计划[使用工具进行委派](#delegation-through-tools)，这将非常有用。 ### 工具执行前的审批 -如果你以 `needsApproval: true` 定义工具，智能体会在执行工具前发出 `tool_approval_requested` 事件。 +如果你使用 `needsApproval: true` 定义工具，智能体会在执行工具前触发 `tool_approval_requested` 事件。 通过监听该事件，你可以向用户展示 UI 以批准或拒绝该工具调用。 ## 护栏 -护栏提供了一种方式来监控智能体的发言是否违反了一组规则，并立即切断响应。这些护栏检查将基于智能体响应的转写执行，因此需要启用模型的文本输出（默认启用）。 +护栏提供了一种方式来监控智能体的输出是否违反一组规则，并立即切断响应。这些护栏检查基于智能体响应的转写进行，因此要求启用模型的文本输出（默认启用）。 -你提供的护栏会在模型响应返回时异步运行，允许你基于预定义的分类触发条件切断响应，例如“提到某个特定禁词”。 +你提供的护栏会在模型响应返回时异步运行，使你可以基于预定义的分类触发器切断响应，例如“提到特定禁用词”。 -当护栏被触发时，会话会发出 `guardrail_tripped` 事件。该事件还会提供一个包含触发护栏的 `itemId` 的 `details` 对象。 +当护栏被触发时，会话会发出 `guardrail_tripped` 事件。该事件还提供包含触发护栏的 `itemId` 的 `details` 对象。 -默认情况下，护栏每 100 个字符或在响应文本结束时运行一次。由于朗读文本通常更耗时，这意味着在大多数情况下，护栏应在用户听到之前捕获到违规。 +默认情况下，护栏每 100 个字符或在响应文本结束时运行一次。由于朗读文本通常更耗时，这意味着在大多数情况下，护栏应能在用户听到之前捕捉到违规内容。 -如果你想修改此行为，可以向会话传递一个 `outputGuardrailSettings` 对象。 +如果你想修改此行为，可以向会话传入 `outputGuardrailSettings` 对象。 -## 轮次检测 / 语音活动检测 +## 回合检测 / 语音活动检测 -实时会话会自动检测用户何时开始说话，并使用 Realtime API 内置的[语音活动检测模式](https://platform.openai.com/docs/guides/realtime-vad)触发新的轮次。 +实时会话会自动检测用户何时在说话，并使用 Realtime API 内置的[语音活动检测模式](https://platform.openai.com/docs/guides/realtime-vad)触发新的回合。 -你可以通过向会话传递一个 `turnDetection` 对象来更改语音活动检测模式。 +你可以通过向会话传入 `turnDetection` 对象来更改语音活动检测模式。 -修改轮次检测设置有助于校准不必要的打断以及处理静音。查看[Realtime API 文档，了解不同设置的更多细节](https://platform.openai.com/docs/guides/realtime-vad) +调整回合检测设置有助于校准不必要的打断和处理静默。查看[Realtime API 文档以了解不同设置的更多细节](https://platform.openai.com/docs/guides/realtime-vad) ## 打断 -使用内置语音活动检测时，打断智能体说话会自动触发智能体基于所说内容检测并更新其上下文。它还会发出一个 `audio_interrupted` 事件。这可用于立即停止所有音频播放（仅适用于 WebSocket 连接）。 +使用内置的语音活动检测时，打断智能体说话会自动触发智能体根据所说内容检测并更新其上下文。同时会发出 `audio_interrupted` 事件。这可用于立即停止所有音频播放（仅适用于 WebSocket 连接）。 -如果你想执行手动打断，例如为你的 UI 提供一个“停止”按钮，你可以手动调用 `interrupt()`： +如果你想进行手动打断，例如在 UI 中提供“停止”按钮，你可以手动调用 `interrupt()`： -无论哪种方式，实时会话都会处理对智能体生成的打断，截断其对已向用户说出内容的认知，并更新历史。 +无论采用哪种方式，实时会话都会处理对智能体生成的打断，截断其对向用户所述内容的认知，并更新历史记录。 -如果你使用 WebRTC 连接到智能体，音频输出也会被清除。如果你使用 WebSocket，则需要自行处理，停止已排队等待播放的音频的播放。 +如果你使用 WebRTC 连接到智能体，它还会清除音频输出。如果你使用 WebSocket，你需要自行停止已排队播放的音频。 ## 文本输入 -如果你想向智能体发送文本输入，你可以在 `RealtimeSession` 上使用 `sendMessage` 方法。 +如果你想向智能体发送文本输入，可以在 `RealtimeSession` 上使用 `sendMessage` 方法。 -这在你希望让用户以两种模态与智能体交互，或向对话提供额外上下文时很有用。 +当你希望用户同时以两种模态与智能体交互，或向对话提供额外上下文时，这会很有用。 -## 会话历史管理 +## 对话历史管理 `RealtimeSession` 会在 `history` 属性中自动管理对话历史： -你可以使用它向客户渲染历史或对其执行其他操作。由于这段历史会在对话过程中不断变化，你可以监听 `history_updated` 事件。 +你可以用它向用户渲染历史，或对其执行其他操作。由于对话过程中历史会不断变化，你可以监听 `history_updated` 事件。 -如果你想修改历史，例如完全移除一条消息或更新其转写，可以使用 `updateHistory` 方法。 +如果你想修改历史，比如完全移除一条消息或更新其转写，可以使用 `updateHistory` 方法。 ### 限制 -1. 目前无法事后更新/更改函数工具调用 -2. 历史中的文本输出需要启用转写和文本模态 +1. 目前无法在事后更新/更改函数工具调用 +2. 历史中的文本输出需要启用转写与文本模态 3. 因打断而被截断的响应没有转写 -## 通过工具进行委托 +## 通过工具进行委派 -![通过工具进行委托](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) +![通过工具进行委派](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/zh/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/zh/guides/voice-agents/quickstart.mdx index 01ddf1d5..143c49ac 100644 --- a/docs/src/content/docs/zh/guides/voice-agents/quickstart.mdx +++ b/docs/src/content/docs/zh/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 连接到模型。为此，我们可以使用一个应由你的后端服务器生成的[临时客户端密钥](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token)。在测试时，你也可以使用 `curl` 和你的常规 OpenAI API 密钥来生成一个密钥。 + 由于该应用将在用户的浏览器中运行，我们需要一种安全的方式通过 Realtime API 连接模型。为此，我们可以使用一种[短期客户端密钥](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token)，它应在您的后端服务器上生成。出于测试目的，您也可以使用 `curl` 和常规的 OpenAI API 密钥生成此密钥。 ```bash export OPENAI_API_KEY="sk-proj-...(your own key here)" @@ -59,11 +59,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - 响应会在顶层包含一个名为 "value" 的字符串，前缀为 "ek\_"。你可以使用该临时密钥稍后建立 WebRTC 连接。请注意，该密钥仅在短时间内有效，需要定期重新生成。 + 响应会在顶层包含一个以 "ek\_" 前缀开头的 "value" 字符串。稍后您可以使用这个临时密钥建立 WebRTC 连接。请注意，该密钥仅在短时间内有效，需要重新生成。 -3. **创建你的第一个智能体** +3. **创建您的第一个智能体** - 创建新的 [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) 与创建常规的 [`Agent`](/openai-agents-js/zh/guides/agents) 非常相似。 + 创建一个新的[`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) 与创建常规的[`Agent`](/openai-agents-js/zh/guides/agents)非常相似。 ```typescript import { RealtimeAgent } from '@openai/agents/realtime'; @@ -76,7 +76,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 4. **创建会话** - 与常规智能体不同，语音智能体会在 `RealtimeSession` 中持续运行与监听，它会随时间处理与模型的对话和连接。该会话还将处理音频处理、打断，以及我们稍后会介绍的许多其他生命周期功能。 + 与常规智能体不同，语音智能体会在一个持续运行并监听的 `RealtimeSession` 中工作，该会话会随时间处理与模型的对话与连接。此会话还将处理音频处理、打断，以及我们稍后将介绍的许多其他生命周期功能。 ```typescript import { RealtimeSession } from '@openai/agents/realtime'; @@ -86,25 +86,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` 构造函数将 `agent` 作为第一个参数。此智能体将是用户首先能够交互的对象。 + `RealtimeSession` 构造函数将 `agent` 作为第一个参数。此智能体将是用户最先能够交互的智能体。 5. **连接到会话** - 要连接到会话，你需要传入之前生成的客户端临时令牌。 + 要连接到会话，您需要传入之前生成的客户端临时令牌。 ```typescript await session.connect({ apiKey: 'ek_...(put your own key here)' }); ``` - 这将在浏览器中使用 WebRTC 连接到 Realtime API，并自动配置你的麦克风和扬声器用于音频输入与输出。如果你在后端服务器（如 Node.js）上运行 `RealtimeSession`，SDK 将自动使用 WebSocket 作为连接方式。你可以在[传输机制](/openai-agents-js/zh/guides/voice-agents/transport)指南中了解更多不同的传输层。 + 这将在浏览器中使用 WebRTC 连接到 Realtime API，并自动配置麦克风与扬声器用于音频输入与输出。如果您在后端服务器（如 Node.js）上运行 `RealtimeSession`，SDK 将自动使用 WebSocket 作为连接。您可以在[传输机制](/openai-agents-js/zh/guides/voice-agents/transport)指南中了解不同的传输层。 -6. **整合到一起** +6. **将以上内容整合在一起** 7. **启动并开始对话** - 启动你的 web 服务器，导航到包含新 Realtime Agent 代码的页面。你应会看到麦克风访问请求。授予访问权限后，你就可以开始与智能体对话了。 + 启动您的 web 服务器并导航到包含新 Realtime Agent 代码的页面。您应该会看到麦克风访问请求。授权后即可开始与智能体对话。 ```bash npm run dev @@ -114,16 +114,16 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t ## 后续步骤 -从这里开始，你可以设计并构建你自己的语音智能体。语音智能体包含许多与常规智能体相同的功能，同时也有自己独特的特性。 +从这里开始，您可以设计并构建自己的语音智能体。语音智能体包含与常规智能体相同的许多功能，但也有一些独特特性。 -- 了解如何为语音智能体添加： +- 了解如何为您的语音智能体添加： - [工具](/openai-agents-js/zh/guides/voice-agents/build#tools) - [交接](/openai-agents-js/zh/guides/voice-agents/build#handoffs) - [护栏](/openai-agents-js/zh/guides/voice-agents/build#guardrails) - [处理音频打断](/openai-agents-js/zh/guides/voice-agents/build#audio-interruptions) - [管理会话历史](/openai-agents-js/zh/guides/voice-agents/build#session-history) -- 进一步了解不同的传输层： +- 了解更多不同的传输层： - [WebRTC](/openai-agents-js/zh/guides/voice-agents/transport#connecting-over-webrtc) - [WebSocket](/openai-agents-js/zh/guides/voice-agents/transport#connecting-over-websocket) - - [构建你自己的传输机制](/openai-agents-js/zh/guides/voice-agents/transport#building-your-own-transport-mechanism) + - [自定义传输机制](/openai-agents-js/zh/guides/voice-agents/transport#building-your-own-transport-mechanism) diff --git a/docs/src/content/docs/zh/guides/voice-agents/transport.mdx b/docs/src/content/docs/zh/guides/voice-agents/transport.mdx index 04fe507e..7824ad86 100644 --- a/docs/src/content/docs/zh/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/zh/guides/voice-agents/transport.mdx @@ -30,15 +30,15 @@ import cloudflareTransportExample from '../../../../../../../examples/docs/exten ### 通过 WebRTC 连接 -默认传输层使用 WebRTC。音频会从麦克风录制并自动回放。 +默认传输层使用 WebRTC。音频将从麦克风录制并自动回放。 -如需使用自定义的媒体流或音频元素，在创建会话时提供一个 `OpenAIRealtimeWebRTC` 实例。 +若要使用您自己的媒体流或音频元素，请在创建会话时提供一个 `OpenAIRealtimeWebRTC` 实例。 ### 通过 WebSocket 连接 -在创建会话时传入 `transport: 'websocket'` 或 `OpenAIRealtimeWebSocket` 的实例，以使用 WebSocket 连接替代 WebRTC。该方式非常适合服务端场景，例如使用 Twilio 构建电话智能体。 +在创建会话时传入 `transport: 'websocket'` 或一个 `OpenAIRealtimeWebSocket` 实例，以使用 WebSocket 连接替代 WebRTC。此方式非常适合服务器端用例，例如使用 Twilio 构建电话智能体。 @@ -46,28 +46,28 @@ import cloudflareTransportExample from '../../../../../../../examples/docs/exten #### Cloudflare Workers（workerd）注意事项 -Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构造函数发起出站 WebSocket。请使用扩展包中的 Cloudflare 传输，它会在内部执行基于 `fetch()` 的升级。 +Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构造函数发起出站 WebSocket。请使用扩展包中的 Cloudflare 传输组件，它会在内部执行基于 `fetch()` 的升级。 ### 自定义传输机制 -如果你想使用不同的语音到语音 API，或拥有自定义传输机制，可以实现 `RealtimeTransportLayer` 接口并发出 `RealtimeTransportEventTypes` 事件，来自行创建。 +如果您想使用不同的语音到语音 API，或拥有自定义传输机制，您可以通过实现 `RealtimeTransportLayer` 接口并触发 `RealtimeTransportEventTypes` 事件来创建自己的传输层。 -## 更直接的 Realtime API 交互 +## 更直接地与 Realtime API 交互 -如果你想使用 OpenAI Realtime API，同时更直接地访问 Realtime API，有两种方式： +如果您想使用 OpenAI Realtime API，同时更直接地访问 Realtime API，有两种选项： ### 选项 1 - 访问传输层 -如果仍希望受益于 `RealtimeSession` 的全部能力，你可以通过 `session.transport` 访问你的传输层。 +如果您仍希望受益于 `RealtimeSession` 的全部能力，您可以通过 `session.transport` 访问传输层。 -传输层会在 `*` 事件下发出其接收的每个事件，你也可以使用 `sendEvent()` 方法发送原始事件。 +传输层会在 `*` 事件下触发其接收到的每个事件，您也可以使用 `sendEvent()` 方法发送原始事件。 ### 选项 2 — 仅使用传输层 -如果你不需要自动工具执行、护栏等功能，也可以将传输层作为一个仅管理连接与中断的“薄”客户端来使用。 +如果您不需要自动工具执行、护栏等功能，也可以将传输层作为一个只管理连接与中断的“轻薄”客户端来使用。 diff --git a/docs/src/content/docs/zh/index.mdx b/docs/src/content/docs/zh/index.mdx index fff95297..492cb335 100644 --- a/docs/src/content/docs/zh/index.mdx +++ b/docs/src/content/docs/zh/index.mdx @@ -17,32 +17,39 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概述 -[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) -让你以轻量、易用、极少抽象的方式构建智能体 AI 应用。它是我们此前针对智能体的 -实验项目 [Swarm](https://github.com/openai/swarm/tree/main) 的一版可用于生产的升级，也[提供 Python 版本](https://github.com/openai/openai-agents-python)。Agents SDK 仅包含一小组基础组件： +[适用于 TypeScript 的 OpenAI Agents SDK](https://github.com/openai/openai-agents-js) +让你以轻量、易用、几乎不引入抽象的方式构建智能体应用。它是我们先前 +针对智能体的试验项目 +[Swarm](https://github.com/openai/swarm/tree/main) 的生产级升级版本，并且[也可用于 Python](https://github.com/openai/openai-agents-python)。Agents SDK 只有一小组基本组件： -- **智能体（Agents）**：配备指令和工具的 LLM -- **交接（Handoffs）**：允许智能体将特定任务委派给其他智能体 +- **智能体（Agents）**：配备 instructions 和工具的 LLM +- **交接（Handoffs）**：允许智能体将特定任务委托给其他智能体 - **护栏（Guardrails）**：用于验证传入智能体的输入 -结合 TypeScript，这些基础组件足以表达工具与智能体之间的复杂关系，让你无需陡峭的学习曲线即可构建真实世界的应用。此外，SDK 内置 **追踪（tracing）**，可用于可视化和调试你的智能体流程，并支持评估，甚至为你的应用微调模型。 +结合 TypeScript，这些基本组件足以表达工具与智能体之间的复杂关系，让你无需陡峭学习曲线即可构建 +真实世界的应用。此外，SDK 内置了**追踪（tracing）**，可用于可视化与调试你的智能体流程，并进一步评估它们，甚至为你的应用微调模型。 -## 使用 Agents SDK 的原因 +## 使用 Agents SDK 的理由 该 SDK 遵循两条核心设计原则： -1. 功能足够有用，但基础组件足够精简，便于快速上手。 -2. 开箱即用效果出色，同时可精细定制具体行为。 +1. 功能足够多，值得使用；但原语足够少，便于快速学习。 +2. 开箱即用效果很好，同时你可以精确自定义具体行为。 -主要特性包括： +SDK 的主要特性如下： -- **智能体循环（Agent loop）**：内置循环处理调用工具、将结果返回给 LLM，并循环直至 LLM 完成。 -- **TypeScript 优先（TypeScript-first）**：利用语言内置能力来编排和串联智能体，无需学习新的抽象。 -- **交接（Handoffs）**：强大的机制，用于在多个智能体之间协调与委派。 -- **护栏（Guardrails）**：与智能体并行运行输入校验与检查，如检查失败则提前中止。 -- **函数工具（Function tools）**：将任意 TypeScript 函数变成工具，自动生成 schema，并使用 Zod 进行校验。 -- **追踪（Tracing）**：内置追踪用于可视化、调试与监控工作流，并可使用 OpenAI 的评估、微调与蒸馏工具。 -- **实时智能体（Realtime Agents）**：构建强大的语音智能体，包含自动打断检测、上下文管理、护栏等。 +- **智能体循环（Agent loop）**：内置循环，负责调用工具、将结果发送给 + LLM，并循环直至 LLM 完成。 +- **TypeScript 优先（TypeScript-first）**：利用语言内置特性来编排与串联 + 智能体，而无需学习新的抽象。 +- **交接（Handoffs）**：强大的能力，用于在多个智能体之间协调与委托。 +- **护栏（Guardrails）**：与智能体并行运行输入验证与检查，如检查失败可提前中断。 +- **函数工具（Function tools）**：将任意 TypeScript 函数变为工具，自动生成 + schema，并使用 Zod 进行验证。 +- **追踪（Tracing）**：内置追踪，便于可视化、调试和监控你的工作流，并可使用 OpenAI 的评估、微调与 + 蒸馏工具。 +- **实时智能体（Realtime Agents）**：构建强大的语音智能体，包括自动打断 + 检测、上下文管理、护栏等。 ## 安装 @@ -54,7 +61,7 @@ npm install @openai/agents zod@3 -(_如果要运行此示例，请确保已设置 `OPENAI_API_KEY` 环境变量_) +(_如果要运行，请确保已设置 `OPENAI_API_KEY` 环境变量_) ```bash export OPENAI_API_KEY=sk-...