diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index afecc415..8db9415b 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -7,12 +7,12 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -Agents SDK は標準で OpenAI のモデルに対して Responses API または Chat Completions API を通じて動作します。ただし、別のモデルを使用したい場合は、このアダプターを通じて [Vercel の 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/) が提供しています。 ## セットアップ @@ -24,20 +24,20 @@ Agents SDK は標準で OpenAI のモデルに対して Responses API または npm install @openai/agents-extensions ``` -2. [Vercel の AI SDK](https://ai-sdk.dev/docs/foundations/providers-and-models) から使用したいモデルパッケージを選び、インストールします: +2. [Vercel の AI SDK](https://ai-sdk.dev/docs/foundations/providers-and-models) から利用したいモデル用パッケージを選び、インストールします: ```bash npm install @ai-sdk/openai ``` -3. アダプターとモデルをインポートしてエージェントに接続します: +3. アダプターとモデルをインポートして、エージェントに接続します: ```typescript import { openai } from '@ai-sdk/openai'; import { aisdk } from '@openai/agents-extensions'; ``` -4. エージェントが使用するモデルのインスタンスを初期化します: +4. エージェントで使用するモデルのインスタンスを初期化します: ```typescript const model = aisdk(openai('gpt-5-mini')); @@ -46,10 +46,10 @@ Agents SDK は標準で OpenAI のモデルに対して Responses API または ## 例 @@ -62,7 +62,7 @@ Agents SDK は標準で OpenAI のモデルに対して Responses API または ## プロバイダーのメタデータの受け渡し -メッセージにプロバイダー固有のオプションを付与する必要がある場合は、`providerMetadata` を通して渡します。値は基盤となる AI SDK のモデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` +メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` を通して渡します。値は基盤となる AI SDK モデルにそのまま転送されます。例えば、Agents SDK で次の `providerData` ```ts providerData: { diff --git a/docs/src/content/docs/ja/extensions/cloudflare.mdx b/docs/src/content/docs/ja/extensions/cloudflare.mdx index d9baa5d8..99910c7a 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 接続を開けません。これらの環境から Realtime Agents への接続を簡単にするため、extensions パッケージは `fetch()` ベースのアップグレードを内部で行う専用のトランスポートを提供します。 +Cloudflare Workers とその他の workerd ランタイムでは、グローバルな `WebSocket` コンストラクタを使ってアウトバウンド WebSockets を開くことはできません。これらの環境から Realtime Agents に接続しやすくするために、extensions パッケージは `fetch()` ベースのアップグレードを内部で実行する専用の transport を提供します。 ## セットアップ @@ -26,7 +25,7 @@ Cloudflare Workers とその他の workerd ランタイムでは、グローバ npm install @openai/agents-extensions ``` -2. **トランスポートを作成し、セッションにアタッチします。** +2. **transport を作成し、セッションにアタッチします。** @@ -40,6 +39,6 @@ Cloudflare Workers とその他の workerd ランタイムでは、グローバ ## 注意事項 -- Cloudflare トランスポートは内部で `Upgrade: websocket` 付きの `fetch()` を使用し、ソケットの `open` イベントを待たずに進むため、workerd の API に合わせています -- このトランスポートを使用しても、すべての `RealtimeSession` 機能（tools、ガードレール など）は通常どおり動作します -- 開発中の詳細ログの確認には `DEBUG=openai-agents*` を使用します +- Cloudflare の transport は内部で `Upgrade: websocket` 付きの `fetch()` を使用し、ソケットの `open` イベントを待たずに進行します。workerd の API に合わせた動作です +- この transport 使用時も、すべての `RealtimeSession` 機能（ツール、ガードレールなど）は通常どおり動作します +- 開発中の詳細ログ確認には `DEBUG=openai-agents*` を使用してください diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index 0862ffd8..5c4f6c43 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,13 +7,13 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio は、電話からの元音声を WebSocket サーバーに送信する [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しています。このセットアップを使って、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続できます。Twilio からのイベントを Realtime Session に接続するには、`websocket` モードのデフォルトの Realtime Session トランスポートを使用できます。ただし、電話は Web ベースの会話よりも遅延が大きくなるため、適切な音声フォーマットの設定や、割り込みタイミングの調整が必要になります。 +Twilio は、電話の通話音声の元オーディオを WebSocket サーバーに送信する [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しています。このセットアップは、あなたの [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続するために使用できます。Twilio から来るイベントを Realtime Session に接続するには、`websocket` モードのデフォルトの Realtime Session トランスポートを使用できます。ただし、Web ベースの会話より通話の方が自然にレイテンシが大きくなるため、適切なオーディオ形式を設定し、自分で割り込みタイミングを調整する必要があります。 -セットアップ体験を改善するために、Twilio への接続、割り込み処理、音声転送を扱う専用のトランスポートレイヤーを用意しました。 +セットアップ体験を改善するために、Twilio への接続、割り込み処理、オーディオ転送などを代わりに処理する専用のトランスポート層を作成しました。 @@ -22,22 +22,22 @@ Twilio は、電話からの元音声を WebSocket サーバーに送信する [ -1. **Twilio アカウントと Twilio の電話番号を用意します。** +1. **Twilio アカウントと Twilio の電話番号を用意すること** -2. **Twilio からのイベントを受信できる WebSocket サーバーをセットアップします。** +2. **Twilio からのイベントを受け取れる WebSocket サーバーをセットアップすること** ローカルで開発している場合は、[`ngrok`](https://ngrok.io/) や [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) - などのローカルトンネルを設定して、ローカルサーバーを Twilio からアクセス可能にする必要があります。`TwilioRealtimeTransportLayer` - を使って Twilio に接続できます。 + のようなローカルトンネルを構成して、ローカルサーバーを Twilio からアクセス可能にする必要があります。`TwilioRealtimeTransportLayer` + を使用して Twilio に接続できます。 -3. **拡張パッケージをインストールして Twilio アダプターを導入します:** +3. **extensions パッケージをインストールして Twilio アダプターを導入すること** ```bash npm install @openai/agents-extensions ``` -4. **アダプターとモデルをインポートして `RealtimeSession` に接続します:** +4. **アダプターとモデルをインポートして `RealtimeSession` に接続すること** -5. **`RealtimeSession` を Twilio に接続します:** +5. **`RealtimeSession` を Twilio に接続すること** ```typescript session.connect({ apiKey: 'your-openai-api-key' }); @@ -55,32 +55,28 @@ Twilio は、電話からの元音声を WebSocket サーバーに送信する [ -`RealtimeSession` から期待されるイベントや動作は、ツール呼び出しやガードレールなどを含めてそのまま機能します。`RealtimeSession` を音声エージェントと併用する方法の詳細は、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 +`RealtimeSession` から期待される任意のイベントや挙動は、ツール呼び出し、ガードレールなどを含め、期待どおりに機能します。`RealtimeSession` を音声エージェントで使用する方法の詳細は、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 ## ヒントと考慮事項 -1. **スピードが最優先です。** +1. **スピードが最重要です。** - Twilio から必要なイベントと音声をすべて受け取るには、WebSocket 接続の参照を取得したらすぐに - `TwilioRealtimeTransportLayer` インスタンスを作成し、その直後に `session.connect()` を呼び出してください。 + Twilio から必要なイベントとオーディオをすべて受け取るために、WebSocket 接続への参照を取得したらすぐに `TwilioRealtimeTransportLayer` インスタンスを作成し、その直後に `session.connect()` を呼び出してください。 -2. **Twilio の元イベントにアクセスします。** +2. **Twilio の元イベントにアクセスする。** - Twilio が送信する元イベントにアクセスしたい場合は、`RealtimeSession` インスタンスの - `transport_event` イベントをリッスンします。Twilio からのすべてのイベントは `twilio_message` の type を持ち、 - 元イベントデータが入った `message` プロパティを含みます。 + Twilio が送信している元イベントにアクセスしたい場合は、`RealtimeSession` インスタンス上の `transport_event` をリッスンできます。Twilio からのすべてのイベントは `twilio_message` の type を持ち、元のイベントデータを含む `message` プロパティを持ちます。 -3. **デバッグログを確認します。** +3. **デバッグログを確認する。** - 状況の詳細が必要になることがあります。環境変数 `DEBUG=openai-agents*` を使うと Agents SDK のすべてのデバッグログが表示されます。 - あるいは、`DEBUG=openai-agents:extensions:twilio*` を使用して Twilio アダプターのデバッグログのみに絞ることもできます。 + 何が起きているかの詳細が必要になることがあります。`DEBUG=openai-agents*` 環境変数を使用すると、Agents SDK からのすべてのデバッグログが表示されます。あるいは、`DEBUG=openai-agents:extensions:twilio*` を使って Twilio アダプターのデバッグログだけを有効にできます。 -## 完全なサーバーの例 +## サーバーの完全な例 -以下は、Twilio からのリクエストを受け取り、それらを `RealtimeSession` に転送する WebSocket サーバーのエンドツーエンドの例です。 +以下は、Twilio からのリクエストを受け取り、それを `RealtimeSession` に転送する、エンドツーエンドの WebSocket サーバーの例です。 diff --git a/docs/src/content/docs/ja/guides/agents.mdx b/docs/src/content/docs/ja/guides/agents.mdx index 0b4bca78..73607103 100644 --- a/docs/src/content/docs/ja/guides/agents.mdx +++ b/docs/src/content/docs/ja/guides/agents.mdx @@ -15,76 +15,76 @@ import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agen import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw'; import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw'; -エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** は、次の設定を備えた Large Language Model (LLM) です。 +エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** は、次の設定が行われた Large Language Model (LLM) です。 -- **Instructions** – モデルに「自分は誰で」「どのように応答すべきか」を伝える system prompt -- **Model** – 呼び出す OpenAI モデルと、任意のモデル調整パラメーター +- **Instructions** – モデルに _自分が何者か_、_どのように応答すべきか_ を伝えるシステムプロンプト +- **Model** – 使用する OpenAI モデル名と、任意のモデル調整パラメーター - **Tools** – タスク達成のために LLM が呼び出せる関数や API の一覧 - + -このページの残りの部分では、あらゆるエージェント機能を詳しく解説します。 +このページの残りでは、すべての Agent 機能を詳しく説明します。 --- ## 基本設定 -`Agent` コンストラクターは単一の設定オブジェクトを受け取ります。よく使われるプロパティは以下のとおりです。 +`Agent` コンストラクターは単一の設定オブジェクトを受け取ります。よく使われるプロパティは次のとおりです。 | Property | Required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | -| `name` | yes | 短い人間が読める識別子 | -| `instructions` | yes | System prompt（文字列 **または** 関数 – [Dynamic instructions](#dynamic-instructions) を参照） | -| `model` | no | モデル名 **または** カスタムの [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | -| `modelSettings` | no | 調整パラメーター（temperature、top_p など）。トップレベルにないプロパティが必要な場合は、`providerData` 配下に含められます | +| `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()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザー メタデータ、機能フラグなど）を提供するのに便利です。 --- ## 出力タイプ -デフォルトでは、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は次を受け付けます。 +既定では、Agent は **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は次を受け付けます。 1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`） -2. JSON‑schema 互換の任意のオブジェクト +2. JSON スキーマ互換の任意のオブジェクト -`outputType` が指定されると、SDK はプレーンテキストの代わりに自動的に +`outputType` が指定されると、SDK はプレーンテキストではなく自動的に [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。 --- -## マルチエージェントのシステム設計パターン +## マルチエージェントの設計パターン -エージェントを組み合わせる方法は多数あります。プロダクションアプリでよく見られるパターンは次の 2 つです。 +エージェントを組み合わせる方法は多数あります。本番アプリでよく見られるパターンは次の 2 つです。 -1. **マネージャー（エージェントをツールとして）** – 中央のエージェントが会話を所有し、ツールとして公開された専門エージェントを呼び出す -2. **ハンドオフ** – 最初のエージェントがユーザーのリクエストを特定したら、以降の会話全体を専門家に委譲する +1. **マネージャー（エージェントをツールとして）** – 中央のエージェントが会話を所有し、ツールとして公開された専門エージェントを呼び出します +2. **ハンドオフ** – 最初のエージェントがユーザーのリクエストを特定したら、会話全体を専門家に委譲します -これらのアプローチは相補的です。マネージャー方式はガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を保持せず単一タスクに集中できます。 +これらのアプローチは補完的です。マネージャーはガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を保持せずに単一タスクに集中できます。 ### マネージャー（エージェントをツールとして） -このパターンではマネージャーは制御を渡しません。LLM がツールを使い、マネージャーが最終回答を要約します。詳しくは [ツール](/openai-agents-js/ja/guides/tools#agents-as-tools) ガイドを参照してください。 +このパターンではマネージャーは決して制御を手放しません。LLM がツールを使い、マネージャーが最終回答を要約します。詳細は [ツール](/openai-agents-js/ja/guides/tools#agents-as-tools) を参照してください。 + --- @@ -111,7 +107,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor 同期関数と `async` 関数の両方がサポートされています。 @@ -120,50 +116,51 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## ライフサイクルフック -高度なユースケースでは、イベントをリッスンしてエージェントのライフサイクルを観測できます。利用可能なものについては、[こちら](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 はツールを _必ず_ 呼び出す（どれを使うかは選べる） +1. `'auto'`（デフォルト）– ツールを使うかどうかは LLM が判断 +2. `'required'` – LLM はツールを _必ず_ 呼び出す（どれを使うかは選択可） 3. `'none'` – LLM はツールを呼び出しては **ならない** -4. 特定のツール名（例: `'calculator'`）– そのツールを必ず呼び出す +4. 特定のツール名（例: `'calculator'`）– LLM はその特定のツールを呼び出す必要がある - + ### 無限ループの防止 -ツール呼び出しの後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループへの突入を防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 +ツール呼び出し後、SDK は `tool_choice` を自動的に `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループに入るのを防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 -- `'run_llm_again'`（デフォルト）– ツール結果を使って LLM を再度実行 +- `'run_llm_again'`（デフォルト）– ツール結果を使ってもう一度 LLM を実行 - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う - `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼ばれた時点で停止 - `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数 @@ -179,6 +176,6 @@ const agent = new Agent({ ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) 方法を学ぶ -- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) を深掘りする -- サイドバーの **@openai/agents** 配下で TypeDoc の完全なリファレンスを参照する +- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を学ぶ +- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) を詳しく見る +- サイドバーの **@openai/agents** 配下にある TypeDoc リファレンス全体を参照する diff --git a/docs/src/content/docs/ja/guides/config.mdx b/docs/src/content/docs/ja/guides/config.mdx index e33fd615..49011ed3 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,31 +13,31 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## 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 キーを使用します。 +トレーシングは既定で有効で、上記の OpenAI キーを使用します。 -別のキーは `setTracingExportApiKey()` で設定できます。 +別のキーは `setTracingExportApiKey()` で設定できます: -トレーシングは完全に無効化することもできます。 +トレーシングを完全に無効化することもできます: -トレーシング機能の詳細は、[トレーシング](/openai-agents-js/ja/guides/tracing)をご覧ください。 +トレーシング機能の詳細は、[トレーシング](/openai-agents-js/ja/guides/tracing) をご覧ください。 -## デバッグロギング +## デバッグログ -SDK はデバッグロギングに [`debug`](https://www.npmjs.com/package/debug) パッケージを使用します。詳細ログを表示するには、`DEBUG` 環境変数を `openai-agents*` に設定します。 +SDK はデバッグロギングに [`debug`](https://www.npmjs.com/package/debug) パッケージを使用します。詳細なログを表示するには、環境変数 `DEBUG` を `openai-agents*` に設定します。 ```bash export DEBUG=openai-agents* ``` -`@openai/agents` の `getLogger(namespace)` を使って、独自モジュール用の名前空間付きロガーを取得できます。 +`@openai/agents` の `getLogger(namespace)` を使うと、独自モジュール用の名前空間付きロガーを取得できます。 -### ログ内の機密データ +### ログ内の機微データ -一部のログには ユーザー データが含まれる場合があります。以下の環境変数を設定して無効化できます。 +一部のログには ユーザー データが含まれる場合があります。以下の環境変数を設定して無効化してください。 LLM の入力と出力のロギングを無効化するには: diff --git a/docs/src/content/docs/ja/guides/context.mdx b/docs/src/content/docs/ja/guides/context.mdx index d033cae1..ba92e589 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 など） - ロガーやデータフェッチャーなどの依存関係 @@ -36,9 +36,9 @@ import localContextExample from '../../../../../../examples/docs/context/localCo ## エージェント/LLM コンテキスト -LLM が呼び出されると、参照できるデータは会話履歴のみです。追加情報を利用可能にするには次のオプションがあります。 +LLM が呼び出されると、参照できるのは会話履歴からのデータだけです。追加情報を利用可能にするには、いくつかの方法があります: -1. エージェントの `instructions` に追加する（システムまたはデベロッパーメッセージとも呼ばれます）。これは静的な文字列でも、コンテキストを受け取って文字列を返す関数でも構いません -2. `Runner.run()` を呼び出す際の `input` に含める。instructions と同様の手法ですが、メッセージを [指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます -3. 関数ツールを通じて公開し、LLM がオンデマンドでデータを取得できるようにする -4. リトリーバルや Web 検索ツールを使って、ファイル、データベース、Web の関連データに基づいて応答をグラウンディングする +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) の下位に配置できます +3. 関数ツール経由で公開し、LLM がオンデマンドでデータを取得できるようにする +4. リトリーバルや Web 検索ツールを使い、ファイル、データベース、または Web の関連データに基づいて応答をグラウンディングする diff --git a/docs/src/content/docs/ja/guides/guardrails.mdx b/docs/src/content/docs/ja/guides/guardrails.mdx index 6c61595b..a091e08b 100644 --- a/docs/src/content/docs/ja/guides/guardrails.mdx +++ b/docs/src/content/docs/ja/guides/guardrails.mdx @@ -7,42 +7,47 @@ import { Code } from '@astrojs/starlight/components'; import inputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-input.ts?raw'; import outputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-output.ts?raw'; -ガードレールはエージェントと _並行して_ 実行され、ユーザー入力やエージェント出力に対してチェックやバリデーションを行えます。たとえば、高コストなモデルを呼び出す前に軽量モデルをガードレールとして実行できます。悪意ある利用を検知した場合、エラーを発生させて高コストなモデルの実行を停止できます。 +ガードレールはエージェントと並行して実行することも、完了まで実行をブロックすることもでき、ユーザー入力やエージェント出力に対するチェックやバリデーションを行えます。たとえば高コストのモデルを呼び出す前に、軽量モデルをガードレールとして実行できます。ガードレールが悪意ある利用を検知した場合は、エラーを発生させて高コストなモデルの実行を停止できます。 -ガードレールには 2 種類あります。 +ガードレールには 2 種類あります: -1. **Input guardrails** は初回のユーザー入力で実行されます -2. **Output guardrails** はエージェントの最終出力で実行されます +1. **入力ガードレール** は初回のユーザー入力に対して実行されます +2. **出力ガードレール** は最終的なエージェント出力に対して実行されます ## 入力ガードレール -入力ガードレールは 3 つの手順で実行されます。 +入力ガードレールは 3 段階で実行されます: -1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) でラップしたものを返します +1. ガードレールはエージェントに渡されたのと同じ入力を受け取ります +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) にラップして返します 3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます -> **Note** -> 入力ガードレールはユーザー入力を対象としているため、ワークフロー内でエージェントが _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。これは、エージェントごとに必要なガードレールが異なることが多いためです。 +> **注意** +> 入力ガードレールはユーザー入力を想定しているため、ワークフローでエージェントが最初のエージェントの場合にのみ実行されます。ガードレールはエージェントごとに設定します。異なるエージェントでは異なるガードレールが必要になることが多いためです。 + +### 実行モード + +- `runInParallel: true`（既定）は、ガードレールを LLM/ ツール呼び出しと並行して開始します。レイテンシーを最小化できますが、ガードレールが後からトリガーされた場合でも、モデルがすでにトークンを消費したりツールを実行している可能性があります +- `runInParallel: false` は、モデルを呼び出す前にガードレールを実行し、ガードレールがリクエストをブロックする際にトークン消費やツール実行を防ぎます。レイテンシーより安全性とコストを優先したい場合に使用します ## 出力ガードレール -出力ガードレールは 3 つの手順で実行されます。 +出力ガードレールは 3 段階で実行されます: 1. ガードレールはエージェントが生成した出力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) でラップしたものを返します +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) にラップして返します 3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーがスローされます -> **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. 追加情報をガードレール結果に含めることができます -4. `agent` はガードレールが適用される実際のワークフローを定義します +4. `agent` はガードレールを適用する実際のワークフローを定義します diff --git a/docs/src/content/docs/ja/guides/handoffs.mdx b/docs/src/content/docs/ja/guides/handoffs.mdx index 605ae90d..bc1e8818 100644 --- a/docs/src/content/docs/ja/guides/handoffs.mdx +++ b/docs/src/content/docs/ja/guides/handoffs.mdx @@ -10,13 +10,13 @@ import handoffInputExample from '../../../../../../examples/docs/handoffs/handof import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw'; import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw'; -ハンドオフを使うと、あるエージェントが会話の一部を別のエージェントに委譲できます。これは、異なるエージェントが特定の分野を専門としている場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、FAQ を担当するエージェントを用意できます。 +ハンドオフは、ある エージェント が会話の一部を別の エージェント に委譲できるようにします。これは、異なる エージェント が特定分野に特化している場合に有用です。たとえばカスタマーサポートアプリでは、予約、返金、FAQ を担当する エージェント を用意できます。 -ハンドオフは LLM に対してはツールとして表現されます。`Refund Agent` というエージェントにハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM に対してツールとして表現されます。`Refund Agent` にハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントは `handoffs` オプションを受け取ります。そこには他の `Agent` インスタンスや、`handoff()` ヘルパーが返す `Handoff` オブジェクトを含められます。 +すべての エージェント は `handoffs` オプションを受け付けます。ここには、他の `Agent` インスタンスや `handoff()` ヘルパーが返す `Handoff` オブジェクトを含めることができます。 ### 基本的な使い方 @@ -26,12 +26,12 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r `handoff()` 関数を使うと、生成されるツールを調整できます。 -- `agent` – ハンドオフ先のエージェント +- `agent` – ハンドオフ先の エージェント - `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き - `toolDescriptionOverride` – 既定のツール説明を上書き -- `onHandoff` – ハンドオフ時のコールバック。`RunContext` と、必要に応じて解析済みの入力を受け取ります +- `onHandoff` – ハンドオフが発生したときのコールバック。`RunContext` と、必要に応じてパース済みの入力を受け取ります - `inputType` – ハンドオフに期待する入力スキーマ -- `inputFilter` – 次のエージェントに渡す履歴のフィルター +- `inputFilter` – 次の エージェント に渡す履歴のフィルター -## ハンドオフ入力 +## ハンドオフの入力 -ハンドオフを呼び出す際に LLM にデータを提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 +ハンドオフの呼び出し時に LLM にデータを提供してほしい場合があります。入力スキーマを定義し、`handoff()` で使用します。 - + ## 入力フィルター -デフォルトでは、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。 +既定では、ハンドオフは会話履歴全体を受け取ります。次の エージェント に渡す内容を変更するには、`inputFilter` を指定します。 一般的なヘルパーは `@openai/agents-core/extensions` にあります。 ## 推奨プロンプト -プロンプトでハンドオフに言及すると、LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` を通じて推奨のプレフィックスを提供します。 +プロンプトでハンドオフに言及すると、LLM はより確実に応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` を通じて推奨の接頭辞を提供します。 -エンドツーエンドで動作する版は、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts)をご覧ください。 +エンドツーエンドで動作する版は [the full example script](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 0dd59e9e..e0b1480c 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -13,79 +13,75 @@ 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) は、アプリケーションが LLMs にツールとコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP のドキュメントより: -> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。USB‑C がさまざまな周辺機器やアクセサリーにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションにとっての USB‑C ポートのようなものだと考えてください。USB‑C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するように、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。 この SDK がサポートする MCP サーバーは 3 種類あります: 1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) によってツールとして使用されるリモート MCP サーバー -2. **Streamable HTTP MCP servers** – [Streamable HTTP トランスポート](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートサーバー -3. **Stdio MCP servers** – 標準入出力経由でアクセスするサーバー（最も簡単な選択肢） +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** | -| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーを使う | **3. Stdio** | +| 必要なこと | 推奨オプション | +| ------------------------------------------------------------------------------------------ | ----------------------- | +| パブリックにアクセス可能なリモートサーバーをデフォルトの OpenAI responses モデルで呼び出す | **1. Hosted MCP tools** | +| パブリックにアクセス可能なリモートサーバーを使うが、ツール呼び出しはローカルでトリガーする | **2. Streamable HTTP** | +| ローカルで動作する Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| OpenAI Responses 以外のモデルであらゆる Streamable HTTP サーバーを使う | **2. Streamable HTTP** | +| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーを使う | **3. Stdio** | -## 1. リモート MCP サーバーツール +## 1. Hosted MCP server tools -組み込みツール（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` メソッド）でエージェントを実行できます: - + -増分の 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 サーバー +### コネクタ対応の hosted サーバー -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) を参照してください。 -完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + Streaming、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + ストリーミング、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 -## 2. Streamable HTTP MCP サーバー +## 2. Streamable HTTP MCP servers -Agent がローカル・リモートの Streamable HTTP MCP サーバーと直接通信する場合は、サーバーの `url`、`name`、任意の設定で `MCPServerStreamableHttp` をインスタンス化します: +エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーと直接通信する場合は、サーバーの `url`、`name`、必要に応じた設定で `MCPServerStreamableHttp` を初期化します: -コンストラクターは `authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの MCP TypeScript‑SDK の追加オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 +このコンストラクタは、`authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの MCP TypeScript SDK の追加オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 -## 3. Stdio MCP サーバー +## 3. Stdio MCP servers -標準 I/O のみを公開するサーバーの場合は、`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` による静的フィルター、またはカスタム関数を渡すことで、各サーバーから公開されるツールを制限できます。以下は両方のアプローチを示す統合例です: -## 既定モデル +## 既定のモデル -`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"` の推論負荷をサポートしていないため、この Agents SDK では既定を `"low"` にしています。 +低レイテンシを求める場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) を `reasoning.effort="minimal"` とともに使用すると、既定設定より高速に応答を返すことが多いです。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の reasoning 努力度をサポートしていないため、この Agents SDK の既定は `"low"` になっています。 ### 非 GPT-5 モデル -カスタムの `modelSettings` なしで非 GPT-5 のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用の `modelSettings` にフォールバックします。 +カスタムの `modelSettings` なしで非 GPT-5 のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用的な `modelSettings` にフォールバックします。 --- ## OpenAI プロバイダー -既定の `ModelProvider` は OpenAI の API を使って名称を解決します。2 つの異なるエンドポイントをサポートしています。 +既定の `ModelProvider` は OpenAI APIs を使用して名前を解決します。2 つの明確なエンドポイントをサポートします: -| API | 用途 | `setOpenAIAPI()` の呼び出し | -| ---------------- | -------------------------------------------------------------------- | --------------------------------------- | -| Chat Completions | 標準的なチャットと Function Calling | `setOpenAIAPI('chat_completions')` | -| Responses | ツール呼び出しや柔軟な出力を備えた新しいストリーミング優先の生成 API | `setOpenAIAPI('responses')` _(default)_ | +| API | 用途 | `setOpenAIAPI()` の呼び出し | +| ---------------- | ---------------------------------------------------------------------------- | --------------------------------------- | +| Chat Completions | 標準的なチャット & 関数呼び出し | `setOpenAIAPI('chat_completions')` | +| Responses | ツールコールや柔軟な出力に対応した新しい ストリーミング ファーストの生成 API | `setOpenAIAPI('responses')` _(default)_ | ### 認証 @@ -82,29 +82,29 @@ node my-awesome-agent.js title="既定の OpenAI キーを設定" /> -ネットワーク設定をカスタマイズする必要がある場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 +カスタムのネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` 経由で独自の `OpenAI` クライアントを差し込むこともできます。 --- ## ModelSettings -`ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダーに依存しません。 +`ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダー非依存です。 -| フィールド | 型 | 注記 | +| Field | Type | Notes | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ | -| `temperature` | `number` | クリエイティビティ vs. 決定性 | -| `topP` | `number` | Nucleus サンプリング | -| `frequencyPenalty` | `number` | 繰り返し出現するトークンを抑制 | -| `presencePenalty` | `number` | 新しいトークンの出現を促進 | +| `temperature` | `number` | 創造性と決定性のバランス | +| `topP` | `number` | Nucleus sampling | +| `frequencyPenalty` | `number` | 繰り返し出現するトークンへのペナルティ | +| `presencePenalty` | `number` | 新しいトークンの促進 | | `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 | -| `parallelToolCalls` | `boolean` | サポートされている場合に関数呼び出しの並列実行を許可 | -| `truncation` | `'auto' \| 'disabled'` | トークンの切り詰め戦略 | +| `parallelToolCalls` | `boolean` | サポートされている場合に並列の関数呼び出しを許可 | +| `truncation` | `'auto' \| 'disabled'` | トークンの切り捨て戦略 | | `maxTokens` | `number` | 応答内の最大トークン数 | -| `store` | `boolean` | 取得や RAG ワークフローのために応答を永続化 | -| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 など向けの推論負荷 | -| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 など向けのテキスト冗長度 | +| `store` | `boolean` | 応答を永続化して取得や RAG ワークフローに利用 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 などのための reasoning 努力度 | +| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 などのためのテキスト冗長性 | -設定はどちらのレベルにも付与できます。 +設定は次のいずれかのレベルに付与できます: @@ -114,40 +114,40 @@ node my-awesome-agent.js ## プロンプト -エージェントは `prompt` パラメーターで設定できます。これは、エージェントの動作を制御するために使用するサーバー保存のプロンプト構成を示します。現在、このオプションは OpenAI の -[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみサポートされています。 +エージェントは `prompt` パラメーターで構成でき、エージェントの動作を制御するために使用する サーバー保管 のプロンプト設定を指定します。現在、このオプションがサポートされるのは OpenAI の +[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合のみです。 -| フィールド | 型 | 注記 | -| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | プロンプトの一意の識別子 | -| `version` | `string` | 使用したいプロンプトのバージョン | -| `variables` | `object` | プロンプトに代入する変数のキー/バリューのペア。値は文字列、またはテキスト・画像・ファイルのようなコンテンツ入力タイプを指定可能 | +| Field | Type | Notes | +| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | プロンプトの一意の識別子 | +| `version` | `string` | 使用したいプロンプトのバージョン | +| `variables` | `object` | プロンプトに代入する変数のキー/値ペア。値は文字列またはテキスト・画像・ファイルなどのコンテンツ入力タイプにできます | -ツールや 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/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 2a8d3a14..29c3f380 100644 --- a/docs/src/content/docs/ja/guides/multi-agent.md +++ b/docs/src/content/docs/ja/guides/multi-agent.md @@ -3,38 +3,38 @@ title: マルチエージェント description: Coordinate the flow between several agents --- -オーケストレーションとは、アプリ内でのエージェントの流れのことです。どのエージェントがどの順序で実行され、次に何をするかをどのように判断するのか。エージェントをオーケストレーションする主な方法は 2 つあります。 +オーケストレーションとは、アプリ内のエージェントの流れのことです。どのエージェントを、どの順序で実行し、次に何が起こるかをどう決めるのかには、主に 2 つの方法があります。 -1. LLM に意思決定させる方法：LLM の知性を使って計画・推論し、それに基づいて実行手順を決める方法 -2. コードでオーケストレーションする方法：コードでエージェントの流れを決める方法 +1. LLM に意思決定を任せる方法: LLM の知性を使って計画・推論し、それに基づいて実行手順を決めます +2. コードでオーケストレーションする方法: コードでエージェントの流れを決定します -これらのパターンは組み合わせて使えます。それぞれのトレードオフについては以下で説明します。 +これらのパターンは組み合わせて使えます。それぞれにトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントは、instructions、tools、ハンドオフを備えた LLM です。これは、オープンエンドなタスクが与えられたとき、LLM がツールを使ってアクションやデータ取得を行い、ハンドオフでサブエージェントに委譲しながら、自律的にタスクへの取り組み方を計画できることを意味します。たとえば、リサーチエージェントには次のようなツールを備えられます。 +エージェントは、instructions、tools、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM は自律的に計画を立て、ツールを使って行動やデータ取得を行い、ハンドオフでサブエージェントに委譲できます。例えば、リサーチ用のエージェントには次のようなツールを備えられます。 -- Web 検索でオンライン情報を探す -- ファイル検索と取得でプロプライエタリデータや接続を横断検索する -- コンピュータ操作でコンピュータ上のアクションを実行する -- コード実行でデータ分析を行う -- 計画やレポート作成などに長けた専門エージェントへのハンドオフ +- オンライン情報を見つけるための Web 検索 +- 独自データや接続先を横断して探すための ファイル検索 と取得 +- コンピュータ上でアクションを実行するための コンピュータ操作 +- データ分析を行うための コード実行 +- 計画立案、レポート執筆などに長けた特化エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、LLM の知性に依存したい場合に有効です。重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで LLM の知性に依拠したい場合に適しています。重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーターを明確にする -2. アプリを監視して反復する。問題が起きる箇所を見つけ、プロンプトを改善する -3. エージェントに内省と改善を許可する。たとえばループで実行し自己批評させる、あるいはエラーメッセージを提供して改善させる -4. 何でもできる汎用エージェントではなく、1 つのタスクに特化して優れた専門エージェントを用意する -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練してタスクの熟達度を高められます +1. 良いプロンプトに投資してください。利用可能なツール、その使い方、遵守すべきパラメーターを明確にします。 +2. アプリを監視して反復改善してください。問題が起きる箇所を特定し、プロンプトを改善します。 +3. エージェントに内省と改善を許可してください。例えばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させます。 +4. 何でもこなす汎用エージェントではなく、単一のタスクに優れた特化エージェントを用意してください。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資してください。これによりエージェントを訓練して性能を向上できます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・パフォーマンスの面でより決定論的で予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションはスピード、コスト、パフォーマンスの観点で、より決定的かつ予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用して、コードで検査できる適切な形式のデータを生成する。たとえば、タスクをいくつかのカテゴリーに分類するようエージェントに依頼し、そのカテゴリーに基づいて次のエージェントを選ぶ -- あるエージェントの出力を次のエージェントの入力に変換して複数のエージェントを連結する。ブログ記事の作成を、リサーチ、アウトライン作成、本文執筆、批評、その後の改善という一連のステップに分解する -- 実行エージェントを `while` ループで走らせ、評価とフィードバックを行うエージェントと組み合わせて、評価者が所定の基準を満たしたと判断するまで繰り返す -- 複数のエージェントを並列で実行する（例：`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/ja/guides/quickstart.mdx b/docs/src/content/docs/ja/guides/quickstart.mdx index 22205efc..5433496a 100644 --- a/docs/src/content/docs/ja/guides/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. プロジェクトを作成して npm を初期化します。これは一度だけで大丈夫です。 +1. プロジェクトを作成して npm を初期化します。一度だけ行えば大丈夫です ```bash mkdir my_project @@ -19,26 +19,26 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm init -y ``` -2. Agents SDK をインストールします。 +2. Agents SDK をインストールします ```bash npm install @openai/agents zod@3 ``` -3. OpenAI API キーを設定します。お持ちでない場合は、OpenAI API キーを作成するために [these instructions](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('')` を呼び出してプログラムから key を設定し、トレーシングには `setTracingExportApiKey('')` を使用できます。 + 詳細は[SDK の設定](/openai-agents-js/ja/guides/config)を参照してください ## はじめてのエージェントの作成 -エージェントは instructions と name で定義します。 +エージェントは instructions と name で定義されます。 ```typescript import { Agent } from '@openai/agents'; @@ -52,9 +52,9 @@ const agent = new Agent({ ## はじめてのエージェントの実行 -`run` メソッドでエージェントを実行できます。開始したいエージェントと、渡したい input の両方を指定して実行します。 +`run` メソッドでエージェントを実行できます。開始したいエージェントと渡したい入力の両方を指定して実行します。 -これは、その実行中に行われた最終出力とあらゆるアクションを含む result を返します。 +これにより、最終出力と実行中に行われたすべてのアクションを含む実行結果が返されます。 ```typescript import { Agent, run } from '@openai/agents'; @@ -70,9 +70,9 @@ const result = await run(agent, 'When did sharks first appear?'); console.log(result.finalOutput); ``` -## エージェントへのツール付与 +## エージェントへのツールの付与 -情報の参照やアクションの実行のために、エージェントにツールを与えることができます。 +情報の参照やアクションの実行に使えるツールをエージェントに与えられます。 ```typescript import { Agent, tool } from '@openai/agents'; @@ -101,7 +101,7 @@ const agent = new Agent({ ## さらにいくつかのエージェントの追加 -追加のエージェントを同様に定義して、問題を小さな部分に分割し、エージェントが現在のタスクにより集中できるようにします。エージェントごとに model を定義することで、問題に応じて異なるモデルを使い分けることもできます。 +追加のエージェントを同様に定義して、課題を小さな部分に分解し、エージェントが目の前のタスクにより集中できるようにします。エージェントで model を定義することで、課題ごとに異なるモデルを使うこともできます。 ```typescript const historyTutorAgent = new Agent({ @@ -119,7 +119,7 @@ const mathTutorAgent = new Agent({ ## ハンドオフの定義 -複数のエージェント間をオーケストレーションするために、エージェントの `handoffs` を定義できます。これにより、エージェントは会話を次のエージェントへ引き継げます。これは実行の過程で自動的に行われます。 +複数のエージェントをオーケストレーションするために、エージェントに `handoffs` を定義できます。これによりエージェントは会話を次のエージェントへ引き継げます。これは実行の過程で自動的に行われます。 ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -131,11 +131,11 @@ const triageAgent = Agent.create({ }); ``` -実行後、result の `finalAgent` プロパティを見ると、どのエージェントが最終応答を生成したかがわかります。 +実行後、結果の `finalAgent` プロパティを見ると、どのエージェントが最終応答を生成したかがわかります。 ## エージェントオーケストレーションの実行 -Runner は個々のエージェントの実行、必要に応じたハンドオフやツール実行の処理を担当します。 +Runner は個々のエージェントの実行、必要に応じたハンドオフ、ツール実行を処理します。 ```typescript import { run } from '@openai/agents'; @@ -148,23 +148,23 @@ async function main() { 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-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 84248f6c..80b20ef4 100644 --- a/docs/src/content/docs/ja/guides/release.mdx +++ b/docs/src/content/docs/ja/guides/release.mdx @@ -5,17 +5,17 @@ description: Learn how we version and release the SDK and recent changes. ## バージョニング -このプロジェクトは、`0.Y.Z` 形式を用いたやや改変したセマンティック バージョニングに従います。先頭の `0` は SDK が依然として急速に進化していることを示します。各コンポーネントは次のように増分します。 +本プロジェクトは `0.Y.Z` 形式の、やや修正した semantic versioning に従います。先頭の `0` は SDK がまだ急速に進化していることを示します。各コンポーネントは次のように増分します。 ## マイナー（`Y`）バージョン -ベータではない公開インターフェースへの**破壊的変更**に対して、マイナー バージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 +ベータでない公開インターフェースに対する **破壊的変更** がある場合、マイナー版 `Y` を増やします。たとえば `0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンにピン留めすることをおすすめします。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` に固定することをおすすめします。 ## パッチ（`Z`）バージョン -後方互換のある変更に対して `Z` を増やします。 +破壊的でない変更では `Z` を増やします。 - バグ修正 - 新機能 @@ -24,11 +24,11 @@ description: Learn how we version and release the SDK and recent changes. ## サブパッケージのバージョニング -メインの `@openai/agents` パッケージは、個別に使用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、いずれかのパッケージでバージョンが上がると他のパッケージも上がります。`1.0.0` に移行する際に、この方針を変更する可能性があります。 +メインの `@openai/agents` パッケージは、個別に利用できる複数のサブパッケージで構成されています。現時点では各パッケージのバージョンは連動しており、どれか 1 つのパッケージのバージョンが上がると他も上がります。`1.0.0` に移行する際にこの方針を変更する可能性があります。 ## 変更履歴 -何が変わったかを把握しやすくするため、各サブパッケージごとに変更履歴を生成しています。変更がサブパッケージ内で行われた可能性があるため、詳細は該当する変更履歴を参照してください。 +変更点を把握しやすくするため、各サブパッケージの変更履歴を生成しています。変更はサブパッケージ内で発生している場合があるため、詳細は該当する変更履歴をご確認ください。 - [`@openai/agents`](https://github.com/openai/openai-agents-js/blob/main/packages/agents/CHANGELOG.md) - [`@openai/agents-core`](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/CHANGELOG.md) diff --git a/docs/src/content/docs/ja/guides/results.mdx b/docs/src/content/docs/ja/guides/results.mdx index b7daf816..889dc3f0 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/guides/results.mdx @@ -7,23 +7,23 @@ import { Code } from '@astrojs/starlight/components'; import handoffFinalOutputTypes from '../../../../../../examples/docs/results/handoffFinalOutputTypes.ts?raw'; import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts?raw'; -[エージェントの実行](/openai-agents-js/ja/guides/running-agents)を行うと、次のいずれかを受け取ります。 +[エージェントの実行](/openai-agents-js/ja/guides/running-agents)時、以下のいずれかを受け取ります: -- `stream: true` を付けずに `run` を呼び出した場合は [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) -- `stream: true` を付けて `run` を呼び出した場合は [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。ストリーミングの詳細は[ストリーミング](/openai-agents-js/ja/guides/streaming)も参照してください +- `stream: true` を指定せずに `run` を呼び出した場合は [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) +- `stream: true` を指定して `run` を呼び出した場合は [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)。ストリーミングの詳細は[ストリーミング](/openai-agents-js/ja/guides/streaming)も参照してください ## 最終出力 -`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が入ります。結果は次のいずれかです。 +`finalOutput` プロパティには、最後に実行されたエージェントの最終出力が含まれます。結果は次のいずれかです: - `string` — `outputType` が定義されていないエージェントのデフォルト -- `unknown` — 出力タイプとして JSON スキーマが定義されている場合。この場合、JSON はパース済みですが型は手動で検証する必要があります -- `z.infer` — 出力タイプとして Zod スキーマが定義されている場合。出力は自動的にこのスキーマでパースされます -- `undefined` — エージェントが出力を生成しなかった場合（たとえば出力を生成する前に停止した場合） +- `unknown` — エージェントが出力タイプとして JSON スキーマを定義している場合。この場合 JSON はパース済みですが、型の検証は手動で行う必要があります +- `z.infer` — エージェントが出力タイプとして Zod スキーマを定義している場合。出力は自動的にこのスキーマに対してパースされます +- `undefined` — エージェントが出力を生成しなかった場合（例: 出力を生成する前に停止した場合） -異なる出力タイプのハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクタではなく `Agent.create()` メソッドを使用してください。 +異なる出力タイプのハンドオフを使用する場合は、エージェントの作成に `new Agent()` コンストラクタではなく `Agent.create()` メソッドを使用してください。 -これにより、SDK がすべての可能なハンドオフにわたる出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 +これにより、SDK がすべての可能なハンドオフにわたって出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 例: @@ -35,44 +35,44 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? ## 次のターンの入力 -次のターンの入力へアクセスする方法は 2 つあります。 +次のターンの入力にアクセスする方法は 2 つあります: - `result.history` — あなたの入力とエージェントの出力の両方のコピーを含みます -- `result.output` — エージェント全体の実行の出力を含みます +- `result.output` — エージェントのフル実行の出力を含みます -`history` は、チャットのようなユースケースで完全な履歴を保持するのに便利です。 +`history` はチャットのようなユースケースで完全な履歴を維持するのに便利です: ## 最後のエージェント -`lastAgent` プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、次回のユーザー入力時に有用です。たとえば、フロントラインのトリアージ エージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存しておき、ユーザーが次にエージェントにメッセージを送る際に再利用できます。 +`lastAgent` プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回 ユーザー が何かを入力する際に便利です。たとえば、フロントラインのトリアージ エージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存して、次回 ユーザー がエージェントにメッセージを送るときに再利用できます。 -ストリーミングモードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスすることも有用です。 +ストリーミング モードでは、実行中の現在のエージェントを指す `currentAgent` プロパティにアクセスするのも有用です。 ## 新規アイテム -`newItems` プロパティには、実行中に生成された新規アイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。ランアイテムは LLM が生成した元アイテムをラップします。これにより、LLM の出力に加えて、どのエージェントに関連付けられたイベントかを参照できます。 +`newItems` プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。実行アイテムは、LLM が生成した元のアイテムをラップします。これにより、LLM の出力に加えて、どのエージェントに関連付けられたイベントかにアクセスできます。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元アイテムは生成されたメッセージです -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフ ツールを呼び出したことを示します。元アイテムは LLM からのツール呼び出しアイテムです -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。元アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます -- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを起動したことを示します -- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。元アイテムはツールの応答です。アイテムからツール出力にもアクセスできます -- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM からの reasoning アイテムを示します。元アイテムは生成された reasoning です -- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。元アイテムは LLM からのツール呼び出しアイテムです +- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元のアイテムは生成されたメッセージです +- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフ ツールを呼び出したことを示します。元のアイテムは LLM からのツール呼び出しアイテムです +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。元のアイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます +- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを呼び出したことを示します +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。元のアイテムはツールの応答です。アイテムからツール出力にもアクセスできます +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM からの推論アイテムを示します。元のアイテムは生成された推論です +- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。元のアイテムは LLM からのツール呼び出しアイテムです ## 状態 -`state` プロパティには実行の状態が含まれます。`result` に付随する多くの情報は `state` から導出されますが、`state` はシリアライズ/デシリアライズ可能で、[エラーからの復旧](/openai-agents-js/ja/guides/running-agents#exceptions)や[`interruption`](#interruptions)への対応が必要な場合に、後続の `run` 呼び出しの入力としても使用できます。 +`state` プロパティには、実行の状態が含まれます。`result` に付随する多くの情報は `state` から派生しますが、`state` はシリアライズ/デシリアライズ可能で、[エラーからの復旧](/openai-agents-js/ja/guides/running-agents#exceptions)や[`interruption`](#interruptions) に対処するために、後続の `run` 呼び出しの入力としても使用できます。 ## 割り込み -エージェントで `needsApproval` を使用している場合、続行前に対処すべき `interruptions` が発生することがあります。その場合、`interruptions` は割り込みの原因となった `ToolApprovalItem` の配列になります。割り込みへの対応方法の詳細は、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)を参照してください。 +エージェントで `needsApproval` を使用している場合、続行前に処理が必要な `interruptions` が発生することがあります。その場合、`interruptions` は割り込みの原因となった `ToolApprovalItem` の配列になります。割り込みの扱い方については、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)を参照してください。 ## その他の情報 -### 元レスポンス +### 元のレスポンス `rawResponses` プロパティには、エージェント実行中にモデルが生成した元の LLM レスポンスが含まれます。 @@ -80,10 +80,10 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? `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 2c5df354..ae652053 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -11,94 +11,94 @@ 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()` ユーティリティで **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** → return - - **Handoff** → 新しいエージェントに切り替え、蓄積済みの会話履歴を保持し、1 に戻る - - **Tool calls** → ツールを実行し、その結果を会話に追加して、1 に戻る +2. LLM のレスポンスを検査する + - **Final output** → 返す + - **Handoff** → 新しいエージェントに切り替え、蓄積された会話履歴を保持し、1 に戻る + - **Tool calls** → ツールを実行し、その結果を会話に追加して 1 に戻る 3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローする ### Runner のライフサイクル -アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシング オプションなどのグローバル設定を保持します。まったく異なるセットアップが必要な場合のみ、別の `Runner` を作成してください。シンプルなスクリプトでは、内部でデフォルトの runner を使う `run()` を呼び出すこともできます。 +アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシング設定などのグローバル設定を保持します。完全に異なるセットアップが必要な場合のみ別の `Runner` を作成してください。簡単なスクリプトでは内部でデフォルト Runner を使う `run()` を呼ぶこともできます。 ## 実行引数 -`run()` メソッドへの入力は、実行を開始する初期エージェント、実行用の入力、およびオプションのセットです。 +`run()` メソッドへの入力は、実行を開始する初期エージェント、実行の入力、そして一連のオプションです。 -入力は、文字列（ユーザー メッセージと見なされます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) の一覧、または [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 +入力は、文字列（ユーザーのメッセージとみなされます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 追加のオプションは次のとおりです。 -| Option | Default | Description | -| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着したイベントを随時発行します | -| `context` | – | すべての 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` インスタンスを作成する場合は、runner を構成するために `RunConfig` オブジェクトを渡せます。 - -| Field | Type | Purpose | -| --------------------------- | --------------------- | ---------------------------------------------------------------------------------------- | -| `model` | `string \| Model` | 実行内の **すべての** エージェントに特定のモデルを強制します | -| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダーです | -| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニング パラメーター | -| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフの実行時に入力アイテムを変更します（ハンドオフ自体で既に定義されていない場合） | -| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | -| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | -| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します | -| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、トレースから LLM/ツールの入力・出力を除外します | -| `workflowName` | `string` | Traces ダッシュボードに表示されます。関連する実行をグループ化するのに役立ちます | -| `traceId` / `groupId` | `string` | SDK に生成させる代わりに、トレース ID またはグループ ID を手動で指定します | -| `traceMetadata` | `Record` | すべてのスパンに付与する任意のメタデータ | +独自の `Runner` インスタンスを作成する場合、Runner を構成するために `RunConfig` オブジェクトを渡せます。 + +| Field | Type | Purpose | +| --------------------------- | --------------------- | ------------------------------------------------------------------------------------ | +| `model` | `string \| Model` | 実行中の **すべて** のエージェントに特定のモデルを強制します | +| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダーです | +| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニングパラメーター | +| `handoffInputFilter` | `HandoffInputFilter` | handoff を行う際に入力アイテムを変更します（handoff 自体がすでに定義していない場合） | +| `inputGuardrails` | `InputGuardrail[]` | 初期のユーザー入力に適用されるガードレール | +| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | +| `tracingDisabled` | `boolean` | OpenAI のトレーシングを完全に無効化します | +| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、トレースから LLM/ツールの入力と出力を除外します | +| `workflowName` | `string` | Traces ダッシュボードに表示され、関連する実行をグルーピングするのに役立ちます | +| `traceId` / `groupId` | `string` | SDK に生成させる代わりに、トレースまたはグループ ID を手動で指定します | +| `traceMetadata` | `Record` | すべてのスパンに付与する任意のメタデータ | ## 会話 / チャットスレッド -`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーション レベルの会話における 1 回の **ターン** を表します。エンドユーザーにどの程度の `RunResult` を見せるかは自由です。`finalOutput` のみのときもあれば、生成されたすべてのアイテムのときもあります。 +`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における 1 回の **turn** を表します。エンドユーザーにどの程度の `RunResult` を表示するかは任意です。`finalOutput` のみの場合もあれば、生成されたすべてのアイテムを表示する場合もあります。 -インタラクティブ版は [the chat example](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 +インタラクティブ版は [チャットの code examples](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 ### サーバー管理の会話 -毎ターンでローカルの全文書を送らずに、OpenAI Responses API に会話履歴を永続化させることができます。長い会話や複数のサービスを調整する際に有用です。詳細は [Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 +毎回ローカルの全文書を送らずに、OpenAI Responses API に会話履歴を保持させることができます。長い会話や複数サービスの調整に便利です。詳細は [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 を各 turn で再利用できます。SDK は新たに生成されたアイテムのみを自動的に含めます。 -#### 2. 直前のターンから継続するための `previousResponseId` +#### 2. 直前の turn から継続するための `previousResponseId` -いずれにせよ最初から Responses API のみで始めたい場合は、前のレスポンスから返された ID を使って各リクエストをチェーンできます。これにより、完全な会話リソースを作らずにターン間でコンテキストを維持できます。 +最初から Responses API のみで始めたい場合、各リクエストを前回のレスポンスから返された ID で連結できます。これにより、完全な会話リソースを作成せずに turn をまたいでコンテキストを維持できます。 ## 例外 @@ -121,13 +121,13 @@ OpenAI はサーバーサイド状態を再利用する 2 つの方法を提供 SDK は捕捉可能な少数のエラーをスローします。 - [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` に到達 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが不正な出力を生成（例: 不正な形式の JSON、未知のツール） +- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが無効な出力を生成（例: 不正な JSON、未知のツール） - [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) – ガードレール違反 -- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールの実行に失敗 +- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールが完了に失敗 - [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 関数ツール呼び出しのいずれかが失敗 - [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 設定またはユーザー入力に基づいてスローされたエラー -これらはすべて基底の `AgentsError` クラスを拡張しており、現在の実行状態にアクセスするための `state` プロパティを提供する場合があります。 +すべて基底の `AgentsError` クラスを継承しており、現在の実行状態にアクセスするための `state` プロパティを提供することがあります。 以下は `GuardrailExecutionError` を処理するサンプルコードです。 @@ -148,6 +148,6 @@ Math homework guardrail tripped ## 次のステップ -- [モデル](/openai-agents-js/ja/guides/models) の構成方法を学ぶ +- [モデル](/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/sessions.mdx b/docs/src/content/docs/ja/guides/sessions.mdx index 35697bfa..276eed17 100644 --- a/docs/src/content/docs/ja/guides/sessions.mdx +++ b/docs/src/content/docs/ja/guides/sessions.mdx @@ -9,13 +9,13 @@ import manageHistory from '../../../../../../examples/docs/sessions/manageHistor import customSession from '../../../../../../examples/docs/sessions/customSession.ts?raw'; import sessionInputCallback from '../../../../../../examples/docs/sessions/sessionInputCallback.ts?raw'; -セッションは Agents SDK に**永続的なメモリレイヤー**を与えます。`Session` インターフェースを実装する任意のオブジェクトを `Runner.run` に渡すだけで、残りは SDK が処理します。セッションがある場合、runner は自動的に次を行います。 +セッションは Agents SDK による**永続メモリ層**です。`Session` インターフェースを実装した任意のオブジェクトを `Runner.run` に渡すだけで、残りは SDK が処理します。セッションがある場合、ランナーは自動的に次を行います。 -1. 以前に保存された会話アイテムを取得し、次のターンの先頭に追加する -2. 各実行完了後に新しい user 入力と assistant 出力を永続化する -3. 新しい user テキストで runner を呼び出す場合も、中断された `RunState` から再開する場合も、将来のターンのためにセッションを利用可能な状態に保つ +1. 以前に保存された会話アイテムを取得し、次のターンの先頭に付与 +2. 各実行完了後に新しい ユーザー入力とアシスタント出力を永続化 +3. 新しい ユーザー テキストでランナーを呼び出す場合も、中断された `RunState` から再開する場合も、将来のターンのためにセッションを維持 -これにより、手動で `toInputList()` を呼び出したり、ターン間で履歴をつなぎ合わせたりする必要がなくなります。TypeScript SDK には 2 つの実装が同梱されています。Conversations API 用の `OpenAIConversationsSession` と、ローカル開発向けの `MemorySession` です。これらは `Session` インターフェースを共有しているため、独自のストレージバックエンドを差し替えることができます。Conversations API 以外の参考としては、`examples/memory/` 配下のサンプルセッションバックエンド（Prisma、ファイルバックエンドなど）をご覧ください。 +これにより、手動で `toInputList()` を呼び出したり、ターン間で履歴をつなぎ合わせる必要がなくなります。TypeScript SDK には 2 つの実装が付属します。Conversations API 用の `OpenAIConversationsSession` と、ローカル開発向けの `MemorySession` です。両者は `Session` インターフェースを共有しているため、独自のストレージ バックエンドを差し替えられます。Conversations API 以外の発想が必要な場合は、`examples/memory/` 配下のサンプル セッション バックエンド（Prisma、ファイル バックエンドなど）を参照してください。 > ヒント: このページの `OpenAIConversationsSession` の例を実行するには、`OPENAI_API_KEY` 環境変数を設定する（またはセッション構築時に `apiKey` を指定する）ことで、SDK が Conversations API を呼び出せるようにしてください。 @@ -23,30 +23,30 @@ import sessionInputCallback from '../../../../../../examples/docs/sessions/sessi ## クイックスタート -`OpenAIConversationsSession` を使用して [Conversations API](https://platform.openai.com/docs/api-reference/conversations) とメモリを同期するか、別の `Session` 実装に差し替えてください。 +`OpenAIConversationsSession` を使って [Conversations API](https://platform.openai.com/docs/api-reference/conversations) とメモリを同期するか、他の任意の `Session` 実装に差し替えます。 -同じセッションインスタンスを再利用すると、各ターンの前にエージェントが会話履歴全体を受け取り、新しいアイテムが自動的に永続化されます。別の `Session` 実装への切り替えでも、他のコード変更は不要です。 +同じセッション インスタンスを再利用すると、毎ターンの前にエージェントが会話履歴全体を受け取り、新しいアイテムが自動で永続化されます。別の `Session` 実装への切り替えでも、その他のコード変更は不要です。 --- -## runner がセッションを使用する方法 +## ランナーによるセッションの使用 -- **各実行前** にセッションの履歴を取得し、新しいターンの入力とマージして、結合されたリストをエージェントに渡します -- **非ストリーミング実行後** は `session.addItems()` の 1 回の呼び出しで、元の user 入力と直近のターンのモデル出力の両方を永続化します -- **ストリーミング実行では** まず user 入力を書き込み、ターン完了時にストリームされた出力を追記します -- **`RunResult.state` からの再開時**（承認などの中断）には、同じ `session` を渡し続けてください。再開したターンは入力の再準備なしでメモリに追加されます +- **各実行前** にセッションの履歴を取得し、新しいターンの入力とマージして、結合したリストをエージェントに渡します +- **非ストリーミング実行後** は、1 回の `session.addItems()` 呼び出しで、直近のターンにおける元の ユーザー入力とモデル出力の両方を永続化します +- **ストリーミング実行の場合** は、まず ユーザー入力を書き込み、ターン完了時にストリーミング出力を追記します +- **`RunResult.state` からの再開時**（承認やその他の中断）も、同じ `session` を渡し続けます。再開したターンは入力の再準備なくメモリに追加されます --- ## 履歴の確認と編集 -セッションはシンプルな CRUD ヘルパーを公開しており、「取り消し」「チャット消去」や監査機能を実装できます。 +セッションはシンプルな CRUD ヘルパーを公開しており、「取り消し」「チャットをクリア」や監査機能を構築できます。 -`session.getItems()` は保存済みの `AgentInputItem[]` を返します。`popItem()` を呼び出すと最後のエントリを削除できます。エージェントを再実行する前の user の修正に便利です。 +`session.getItems()` は保存された `AgentInputItem[]` を返します。`popItem()` を呼ぶと最後のエントリを削除できます。エージェントを再実行する前の ユーザー修正に便利です。 --- -## 任意のストレージを使用 +## 独自ストレージの持ち込み -`Session` インターフェースを実装して、Redis、DynamoDB、SQLite、その他のデータストアでメモリを支えることができます。必要なのは 5 つの非同期メソッドだけです。 +`Session` インターフェースを実装して、メモリを Redis、DynamoDB、SQLite、または他のデータストアで支えることができます。必要なのは 5 つの非同期メソッドだけです。 -カスタムセッションにより、保持ポリシーの適用、暗号化の追加、永続化前に各会話ターンへメタデータを付与することができます。 +カスタム セッションでは、保持ポリシーの適用、暗号化の追加、各会話ターンへのメタデータ付与などを永続化前に行えます。 --- ## 履歴と新規アイテムのマージ方法の制御 -実行入力として `AgentInputItem` の配列を渡す場合、`sessionInputCallback` を指定して保存済み履歴とのマージを決定的に行えます。runner は既存の履歴を読み込み、**モデル呼び出しの前に** コールバックを呼び出し、返された配列をそのターンの完全な入力としてモデルに渡します。このフックは、古いアイテムのトリミング、ツール結果の重複排除、モデルに見せたいコンテキストのみを強調するのに最適です。 +実行入力として `AgentInputItem` の配列を渡す場合、`sessionInputCallback` を指定して保存済み履歴とのマージを決定的に制御します。ランナーは既存履歴を読み込み、**モデル呼び出し前に** コールバックを呼び、返された配列をそのターンの完全な入力としてモデルに渡します。このフックは、古いアイテムのトリミング、ツール結果の重複排除、モデルに見せたいコンテキストのみを強調するのに最適です。 -文字列入力の場合、runner は履歴を自動でマージするため、コールバックは任意です。 +文字列入力の場合はランナーが自動で履歴をマージするため、コールバックは任意です。 --- ## 承認と再開可能な実行の取り扱い -Human in the loop（人間の介入）フローでは、承認待ちで実行を一時停止することがよくあります。 +Human in the loop (人間の介入) のフローでは、承認待ちのために実行が一時停止することがあります。 ```typescript const result = await runner.run(agent, 'Search the itinerary', { @@ -103,4 +103,4 @@ if (result.requiresApproval) { } ``` -以前の `RunState` から再開すると、新しいターンは同じメモリレコードに追加され、単一の会話履歴が保持されます。Human-in-the-loop (HITL) フローは完全に互換性を維持します。承認チェックポイントは引き続き `RunState` を往復し、セッションは全文書記録を完全に保ちます。 +以前の `RunState` から再開すると、新しいターンは同じメモリ レコードに追加され、単一の会話履歴が維持されます。Human in the loop (人間の介入)（HITL）のフローは完全に互換性を保ちます。承認チェックポイントは引き続き `RunState` を往復しつつ、セッションが書き起こし全体を保持します。 diff --git a/docs/src/content/docs/ja/guides/streaming.mdx b/docs/src/content/docs/ja/guides/streaming.mdx index b577b170..7c66a6d2 100644 --- a/docs/src/content/docs/ja/guides/streaming.mdx +++ b/docs/src/content/docs/ja/guides/streaming.mdx @@ -9,48 +9,48 @@ import nodeTextStreamExample from '../../../../../../examples/docs/streaming/nod import handleAllEventsExample from '../../../../../../examples/docs/streaming/handleAllEvents.ts?raw'; import streamedHITLExample from '../../../../../../examples/docs/streaming/streamedHITL.ts?raw'; -Agents SDK は、モデルやその他の実行ステップからの出力を段階的に配信できます。ストリーミングにより UI が応答性を保ち、エンドユーザーの更新前に最終結果全体を待たずに済みます。 +Agents SDK は、モデルやその他の実行ステップからの出力を段階的に配信できます。ストリーミングにより UI を応答性よく保ち、エージェントの最終的な実行結果全体を待たずに ユーザー を更新できます。 ## ストリーミングの有効化 -`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な実行結果ではなくストリーミングオブジェクトを取得します: +`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な結果ではなくストリーミングオブジェクトを取得します: -ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、その実行内で何が起きたかを記述するオブジェクトです。ストリームはエージェントの実行の異なる部分を表す 3 種類のイベントのいずれかを送出します。多くのアプリケーションはモデルのテキストだけが必要なので、ストリームはそのためのヘルパーも提供します。 +ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、その実行内で何が起こったかを表すオブジェクトです。ストリームは 3 種類のイベントを出力し、それぞれがエージェントの実行の異なる部分を表します。多くのアプリケーションはモデルのテキストだけが必要なので、ストリームはそのためのヘルパーを提供します。 ### テキスト出力の取得 -送出されたテキストのストリームを取得するには `stream.toTextStream()` を呼びます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js `Readable` です。`process.stdout` や他の出力先に直接パイプできます。 +`stream.toTextStream()` を呼び出すと、生成されたテキストのストリームを取得できます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js の `Readable` です。`process.stdout` や別の出力先にそのままパイプできます。 -`stream.completed` の Promise は、実行とすべての保留中のコールバックが完了すると解決されます。出力がもうないことを確実にするには必ず待機してください。 +`stream.completed` の Promise は、実行と保留中のすべてのコールバックが完了すると解決されます。出力がもうないことを確実にするには、必ず待機してください。 -### すべてのイベントのリッスン +### すべてのイベントを監視 -`for await` ループを使って、到着した各イベントを確認できます。低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などが含まれます: +`for await` ループを使って、到着した各イベントを検査できます。有用な情報には、低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などがあります: -完全なスクリプトは [the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。プレーンテキストのストリームと raw イベントストリームの両方を表示します。 +完全なプレーンテキストストリームと 元 のイベントストリームをどちらも出力するスクリプトは、[the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。 ## イベントタイプ -ストリームは次の 3 種類のイベントを送出します: +ストリームは 3 種類のイベントを出力します: ### raw_model_stream_event @@ -120,21 +120,21 @@ type RunAgentUpdatedStreamEvent = { ## ストリーミング中の 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) です。 ## ヒント -- すべての出力がフラッシュされるよう、終了前に `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 a3c4cbd2..cc52eede 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,119 +10,111 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -ツールはエージェントに **アクションの実行** を可能にします。データ取得、外部 API 呼び出し、コード実行、さらにはコンピュータの使用まで行えます。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします。 +ツールはエージェントに **行動を取らせる** 手段です。データの取得、外部 API 呼び出し、コード実行、さらにはコンピュータの使用まで可能にします。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートしています: -1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと並行して実行されます（Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成） -2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップして LLM に呼び出させます +1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと並行して実行されます。_(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_ +2. **関数ツール** – 任意のローカル関数を JSON schema でラップし、LLM が呼び出せるようにします 3. **エージェントをツールとして** – エージェント全体を呼び出し可能なツールとして公開します -4. **ローカル MCP サーバー** – あなたのマシンで動作する Model context protocol サーバーを接続します +4. **ローカル MCP サーバー** – お使いのマシン上で動作する Model context protocol のサーバーを接続します --- ## 1. 組み込みツール（Hosted） -`OpenAIResponsesModel` を使うと、以下の組み込みツールを追加できます。 +`OpenAIResponsesModel` を使用する場合、次の組み込みツールを追加できます: -| Tool | Type string | Purpose | +| ツール | Type string | 目的 | | ----------------------- | -------------------- | ------------------------------------------- | | Web search | `'web_search'` | インターネット検索 | | File / retrieval search | `'file_search'` | OpenAI 上でホストされるベクトルストアの検索 | | Computer use | `'computer'` | GUI 操作の自動化 | -| Shell | `'shell'` | ホスト上でシェルコマンドを実行 | -| Apply patch | `'apply_patch'` | ローカルファイルへ V4A 差分を適用 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | +| Shell | `'shell'` | ホスト上でのシェルコマンド実行 | +| Apply patch | `'apply_patch'` | V4A の diff をローカルファイルに適用 | +| Code Interpreter | `'code_interpreter'` | サンドボックス環境でのコード実行 | | Image generation | `'image_generation'` | テキストに基づく画像生成 | - + -厳密なパラメーターは OpenAI Responses API と一致します。`rankingOptions` やセマンティックフィルタなどの高度なオプションは公式ドキュメントを参照してください。 +詳細な `rankingOptions` やセマンティックフィルターなど上級オプションは OpenAI Responses API と完全に一致します。公式ドキュメントを参照してください。 --- ## 2. 関数ツール -`tool()` ヘルパーで **任意** の関数をツールにできます。 +`tool()` ヘルパーで **任意の** 関数をツールにできます。 ### オプションリファレンス -| Field | Required | Description | -| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | No | 関数名（例: `get_weather`）がデフォルト | -| `description` | Yes | LLM に表示される明確で人間が読める説明 | -| `parameters` | Yes | Zod スキーマまたは raw の JSON スキーマオブジェクトのいずれか。Zod のパラメーターは自動的に **strict** モードを有効化 | -| `strict` | No | `true`（デフォルト）の場合、引数が検証に失敗すると SDK はモデルエラーを返します。曖昧一致にするには `false` に設定 | -| `execute` | Yes | `(args, context) => string \| Promise` – ビジネスロジック。本項目の 2 番目のオプション引数は `RunContext` | -| `errorFunction` | No | 内部エラーをユーザーに見える文字列へ変換するためのカスタムハンドラー `(context, error) => string` | +| フィールド | 必須 | 説明 | +| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | いいえ | 省略時は関数名（例: `get_weather`）が使用されます | +| `description` | はい | LLM に表示される明確で人間が読める説明 | +| `parameters` | はい | Zod schema か 元 JSON schema オブジェクトのいずれか。Zod の parameters を使うと自動的に **strict** モードが有効になります | +| `strict` | いいえ | `true`（デフォルト）の場合、引数が検証に失敗すると SDK は model error を返します。あいまいなマッチングを許すには `false` に設定します | +| `execute` | はい | `(args, context) => string \| Promise`– ビジネスロジック。2 つ目の引数は任意で、`RunContext` です | +| `errorFunction` | いいえ | 内部エラーをユーザーに見える文字列へ変換するカスタムハンドラー `(context, error) => string` | -### 非 strict な JSON スキーマツール +### 非 strict の JSON‑schema ツール -無効または部分的な入力をモデルに推測させる必要がある場合は、raw の JSON スキーマを使う際に strict モードを無効化できます。 +不正または部分的な入力をモデルに推測させる必要がある場合、元 JSON schema を使用するときに strict モードを無効化できます: --- ## 3. エージェントをツールとして -会話を完全にハンドオフせずに、別のエージェントを _支援_ させたい場合は `agent.asTool()` を使用します。 +会話全体を完全にハンドオフせずに、別のエージェントを _支援_ させたい場合があります。`agent.asTool()` を使用します: - + -内部的に SDK は次を行います。 +内部的に SDK は次を行います: - 単一の `input` パラメーターを持つ関数ツールを作成 -- ツールが呼び出されたときに、その入力でサブエージェントを実行 -- 最後のメッセージ、または `customOutputExtractor` で抽出された出力を返却 +- ツールが呼び出されたとき、その入力でサブエージェントを実行 +- 最後のメッセージ、または `customOutputExtractor` で抽出された出力を返す -エージェントをツールとして実行すると、Agents SDK はデフォルト設定でランナーを作成し、関数実行内でそのランナーを用いてエージェントを実行します。`runConfig` や `runOptions` のプロパティを指定したい場合は、`asTool()` メソッドに渡してランナーの動作をカスタマイズできます。 +エージェントをツールとして実行すると、Agents SDK はデフォルト設定で runner を作成し、関数実行内でその 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) を参照してください。 +完全な example は [`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 schema で厳密な JSON 検証を行う +- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返し、throw しない +- **ツールごとに 1 つの責務** – 小さく合成可能なツールはモデルの推論を向上させる --- ## 次のステップ -- [ツールの使用を強制する](/openai-agents-js/ja/guides/agents#forcing-tool-use) 方法を学ぶ +- [エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) で強制的なツール使用について学ぶ - ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 -- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツールタイプの TypeDoc リファレンスを確認 +- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種 Hosted ツールタイプの TypeDoc リファレンスを参照 diff --git a/docs/src/content/docs/ja/guides/tracing.mdx b/docs/src/content/docs/ja/guides/tracing.mdx index 96ae9da8..ad2f3a59 100644 --- a/docs/src/content/docs/ja/guides/tracing.mdx +++ b/docs/src/content/docs/ja/guides/tracing.mdx @@ -7,24 +7,24 @@ import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw'; -Agents SDK には組み込みのトレーシングがあり、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまでを含みます。[Traces ダッシュボード](https://platform.openai.com/traces)を使って、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みのトレーシングがあり、エージェント実行中に発生するイベントの包括的な記録を収集します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらに発生するカスタムイベントまで含みます。[Traces dashboard](https://platform.openai.com/traces) を使って、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 ## エクスポートループのライフサイクル -ほとんどの環境では、トレースは定期的に自動エクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。キューに溜まりすぎた場合はトレースがエクスポートされますが、定期的にはエクスポートされません。代わりに、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用して手動でトレースをエクスポートしてください。 +ほとんどの環境では、トレースは定期的な間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。キューに溜まりすぎた場合はエクスポートされますが、定期的にはエクスポートされません。代わりに、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用して手動でトレースをエクスポートしてください。 -たとえば Cloudflare Worker では、コード全体を `try/catch/finally` ブロックでラップし、`waitUntil` と併用して強制フラッシュを行い、ワーカーが終了する前にトレースがエクスポートされるようにします。 +たとえば Cloudflare Worker では、コードを `try/catch/finally` ブロックでラップし、`waitUntil` とあわせて強制フラッシュを使用することで、ワーカーが終了する前にトレースがエクスポートされるようにします。 ` - - `group_id`: 同じ会話からの複数トレースを関連付けるための任意のグループ ID。例えばチャットスレッド ID など + - `trace_id`: トレースの一意の ID。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります + - `group_id`: 同一会話からの複数のトレースをリンクするための任意のグループ ID。たとえばチャットスレッド ID を使用できます - `disabled`: True の場合、トレースは記録されません - - `metadata`: トレースの任意メタデータ -- **Spans** は開始時刻と終了時刻を持つ操作を表します。スパンには次が含まれます: - - `started_at` と `ended_at` タイムスタンプ - - 所属するトレースを示す `trace_id` - - 親スパンを指す `parent_id`（ある場合） - - スパンに関する情報である `span_data`。例えば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報など + - `metadata`: トレースの任意のメタデータ +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次が含まれます。 + - `started_at` と `ended_at` のタイムスタンプ + - 所属するトレースを表す `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/ja/guides/voice-agents)を参照してください。 +詳しくは [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 ## 高レベルのトレース -複数の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合は、コード全体を `withTrace()` でラップします。 +`run()` への複数回の呼び出しを 1 つのトレースの一部にしたい場合があります。これは、コード全体を `withTrace()` でラップすることで実現できます。 -1. `withTrace()` で 2 回の `run` 呼び出しをラップしているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります +1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 ## トレースの作成 -[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数を使用してトレースを作成できます。あるいは、`getGlobalTraceProvider().createTrace()` を使用して新しいトレースを手動で作成し、それを `withTrace()` に渡すこともできます。 +[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数を使用してトレースを作成できます。あるいは、`getGlobalTraceProvider().createTrace()` を使用して手動で新しいトレースを作成し、それを `withTrace()` に渡すこともできます。 -現在のトレースは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルで追跡されます。つまり、自動的に並行処理で機能します。 +現在のトレースは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルによって追跡されます。つまり、並行実行でも自動的に機能します。 ## スパンの作成 -さまざまな `create*Span()`（例: `createGenerationSpan()`、`createFunctionSpan()` など）メソッドを使用してスパンを作成できます。一般的にはスパンを手動で作成する必要はありません。カスタムスパン情報を追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数も利用できます。 +各種 `create*Span()`（例: `createGenerationSpan()`, `createFunctionSpan()` など）メソッドを使ってスパンを作成できます。一般的には、スパンを手動で作成する必要はありません。カスタムスパン情報を追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数が利用できます。 -スパンは自動的に現在のトレースの一部となり、[Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルで追跡される、最も近い現在のスパンの下にネストされます。 +スパンは自動的に現在のトレースの一部となり、[Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルで追跡される最も近い現在のスパンの下にネストされます。 -## 機微なデータ +## 機微データ -一部のスパンは、機微なデータを取得する可能性があります。 +一部のスパンは機微なデータを含む可能性があります。 -`createGenerationSpan()` は LLM 生成の入力/出力を保存し、`createFunctionSpan()` は関数呼び出しの入力/出力を保存します。これらには機微なデータが含まれる可能性があるため、[`RunConfig.traceIncludeSensitiveData +`createGenerationSpan()` は LLM 生成の入出力を保存し、`createFunctionSpan()` は関数呼び出しの入出力を保存します。これらは機微なデータを含む可能性があるため、[`RunConfig.traceIncludeSensitiveData `](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) によってそのデータの取得を無効化できます。 ## カスタムトレーシングプロセッサー @@ -99,12 +99,12 @@ Agents SDK には組み込みのトレーシングがあり、エージェント トレーシングの高レベルアーキテクチャは次のとおりです。 - 初期化時にグローバルな [`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` を [`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) は、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換え**ます。つまり、`TracingProcessor` を含めない限り、トレースは OpenAI バックエンドに送信されません ## 外部トレーシングプロセッサー一覧 diff --git a/docs/src/content/docs/ja/guides/troubleshooting.mdx b/docs/src/content/docs/ja/guides/troubleshooting.mdx index 93a9b996..59527c03 100644 --- a/docs/src/content/docs/ja/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ja/guides/troubleshooting.mdx @@ -3,39 +3,39 @@ title: トラブルシューティング description: Learn how to troubleshoot issues with the OpenAI Agents SDK. --- -## サポートされる環境 +## 対応環境 -OpenAI Agents SDK は次のサーバー環境でサポートされます: +OpenAI Agents SDK は次のサーバー環境でサポートされています: - Node.js 22+ - Deno 2.35+ - Bun 1.2.5+ -### 限定サポート +### 制限付きサポート -- **Cloudflare Workers**: Agents SDK は Cloudflare Workers で利用できますが、現時点ではいくつかの制限があります: - - SDK は現在 `nodejs_compat` の有効化が必要 - - リクエストの最後にトレースを手動でフラッシュする必要があります。[トレーシングガイドを参照](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) - - Cloudflare Workers での `AsyncLocalStorage` のサポートが限定的なため、一部のトレースが正確でない可能性があります - - アウトバウンド WebSocket 接続は fetch ベースのアップグレードを使用する必要があります（グローバルの `WebSocket` コンストラクタは不可）。Realtime では、`@openai/agents-extensions` の Cloudflare トランスポート（`CloudflareRealtimeTransportLayer`）を使用してください -- **ブラウザ**: +- **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:core` — SDK の主要な実行ロジック - `openai-agents:openai` — OpenAI API 呼び出し - `openai-agents:realtime` — リアルタイムエージェントのコンポーネント diff --git a/docs/src/content/docs/ja/guides/voice-agents.mdx b/docs/src/content/docs/ja/guides/voice-agents.mdx index 44c75d63..28dee3e8 100644 --- a/docs/src/content/docs/ja/guides/voice-agents.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents.mdx @@ -23,29 +23,29 @@ import websocketSessionExample from '../../../../../../examples/docs/voice-agent import transportEventsExample from '../../../../../../examples/docs/voice-agents/transportEvents.ts?raw'; import thinClientExample from '../../../../../../examples/docs/voice-agents/thinClient.ts?raw'; -![リアルタイムエージェント](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 の音声対音声モデルを使用して、リアルタイムのボイスチャットを提供します。これらのモデルは音声、テキスト、ツール呼び出しのストリーミングをサポートし、音声/電話のカスタマーサポート、モバイルアプリの体験、ボイスチャットといった用途に最適です。 +Voice Agents は OpenAI の speech-to-speech モデルを使用して、リアルタイムの音声チャットを提供します。これらのモデルは音声、テキスト、ツール呼び出しの ストリーミング をサポートし、音声/電話のカスタマーサポート、モバイルアプリ体験、音声チャットのような用途に最適です。 -Voice Agents SDK は [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) 用の TypeScript クライアントを提供します。 +Voice Agents SDK は [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) のための TypeScript クライアントを提供します。 ### 主な機能 - WebSocket または WebRTC で接続 - ブラウザとバックエンド接続の両方で利用可能 -- 音声および割り込みの処理 -- ハンドオフによるマルチエージェントのオーケストレーション -- ツールの定義と呼び出し -- モデル出力を監視するカスタムガードレール -- ストリーミングイベント向けのコールバック -- テキストと音声のエージェントの両方で同じコンポーネントを再利用 +- 音声と割り込みのハンドリング +- ハンドオフ によるマルチエージェントのオーケストレーション +- ツール定義と呼び出し +- モデル出力を監視するカスタム ガードレール +- ストリーミング されたイベントのコールバック +- テキストエージェントと音声エージェントの両方で同じコンポーネントを再利用 -音声対音声モデルを使用すると、モデルが動作した後にテキストへ文字起こしして再び音声に変換し直す必要がなく、モデルのリアルタイム音声処理能力を活用できます。 +speech-to-speech モデルを使用することで、モデルが動作した後にテキストを文字起こしして再度音声に変換する必要がなく、モデルのリアルタイム音声処理能力を活用できます。 -![音声対音声モデル](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) +![Speech-to-speech model](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) diff --git a/docs/src/content/docs/ja/guides/voice-agents/build.mdx b/docs/src/content/docs/ja/guides/voice-agents/build.mdx index d406b366..47e283b7 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/build.mdx @@ -28,51 +28,50 @@ import serverAgentExample from '../../../../../../../examples/docs/voice-agents/ import delegationAgentExample from '../../../../../../../examples/docs/voice-agents/delegationAgent.ts?raw'; import turnDetectionExample from '../../../../../../../examples/docs/voice-agents/turnDetection.ts?raw'; -## 音声の扱い +## 音声の処理 -既定の `OpenAIRealtimeWebRTC` のような一部のトランスポートレイヤーは、音声の入力と出力を自動的に処理します。`OpenAIRealtimeWebSocket` のような他のトランスポートでは、セッションの音声を自分で処理する必要があります: +デフォルトの `OpenAIRealtimeWebRTC` のような一部のトランスポート層は、音声の入力と出力を自動的に処理します。`OpenAIRealtimeWebSocket` のような他のトランスポート機構では、セッションの音声を自分で処理する必要があります。 ## セッションの設定 -[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) のコンストラクターに追加オプションを渡すか、`connect(...)` を呼び出す際にオプションを渡すことで、セッションを設定できます。 +[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) のコンストラクターに追加のオプションを渡すか、`connect(...)` を呼び出す際にオプションを渡すことで、セッションを設定できます。 -これらのトランスポートレイヤーでは、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 +これらのトランスポート層では、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 -[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に対応するパラメーターがまだない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡したものは `session` オブジェクトの一部としてそのまま渡されます。 +[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に存在しない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡したものは、`session` オブジェクトの一部としてそのまま渡されます。 ## ハンドオフ -通常のエージェントと同様に、ハンドオフを使ってエージェントを複数のエージェントに分割し、それらの間をオーケストレーションして、エージェントのパフォーマンスを高め、問題の範囲をより明確にできます。 +通常のエージェントと同様に、ハンドオフを使ってエージェントを複数に分割し、それらの間をオーケストレーションすることで、エージェントのパフォーマンスを向上させ、問題のスコープを適切に絞ることができます。 -通常のエージェントとは異なり、ハンドオフは リアルタイムエージェント では少し動作が異なります。ハンドオフが行われると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 +通常のエージェントと異なり、リアルタイムエージェントではハンドオフの挙動が少し異なります。ハンドオフが実行されると、進行中のセッションは新しいエージェント構成で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、現在は入力フィルターは適用されません。 -さらに、ハンドオフの一部として `voice` や `model` を変更することはできません。また、接続できるのは他の リアルタイムエージェント のみです。別のモデル、たとえば `gpt-5-mini` のような推論モデルを使用する必要がある場合は、[delegation through tools](#delegation-through-tools) を使用できます。 +さらに、これによりハンドオフの一部として `voice` や `model` を変更することはできません。また、接続できるのは他の リアルタイムエージェント のみです。別のモデル、たとえば `gpt-5-mini` のような推論モデルを使用する必要がある場合は、[ツールによる委譲](#delegation-through-tools) を使用できます。 ## ツール -通常のエージェントと同様に、リアルタイムエージェントはアクションを実行するためにツールを呼び出せます。通常のエージェントで使用するのと同じ `tool()` 関数でツールを定義できます。 +通常のエージェントと同様に、リアルタイムエージェント はアクションを実行するためにツールを呼び出せます。通常のエージェントで使用するのと同じ `tool()` 関数でツールを定義できます。 -リアルタイムエージェントで使用できるのは 関数ツール のみで、これらのツールはリアルタイムセッションと同じ場所で実行されます。つまり、ブラウザでリアルタイムセッションを実行している場合は、ツールもブラウザで実行されます。より機密性の高いアクションを実行する必要がある場合は、ツール内からバックエンド サーバー への HTTP リクエストを実行できます。 +リアルタイムエージェント で使用できるのは 関数ツール のみで、これらのツールはあなたの Realtime Session と同じ場所で実行されます。つまり、Realtime Session をブラウザで実行している場合、ツールもブラウザで実行されます。よりセンシティブな操作が必要な場合は、ツール内からバックエンド サーバー への HTTP リクエストを行ってください。 -ツールの実行中、エージェントは ユーザー からの新しいリクエストを処理できません。体験を向上させる 1 つの方法は、ツールの実行直前にアナウンスさせたり、ツール実行のための時間を稼ぐ決まり文句を話すようにエージェントに指示することです。 +ツールの実行中、エージェントは ユーザー からの新規リクエストを処理できません。体験を向上させる方法として、ツールを実行しようとしていることを事前にエージェントにアナウンスさせたり、ツール実行のための時間を稼ぐ特定のフレーズを話させたりできます。 ### 会話履歴へのアクセス -エージェントが特定のツールを呼び出した際の引数に加えて、リアルタイムセッションが追跡する現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[tools for delegation](#delegation-through-tools) を使用する予定がある場合に役立ちます。 +エージェントが特定のツールを呼び出した際の引数に加えて、Realtime Session によって追跡される現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[委譲のためのツール](#delegation-through-tools) を使用する予定がある場合に有用です。 ### ツール実行前の承認 @@ -84,82 +83,82 @@ import turnDetectionExample from '../../../../../../../examples/docs/voice-agent ## ガードレール -ガードレールは、エージェントの発言が一連のルールに違反したかどうかを監視し、違反した場合に即座にレスポンスを遮断する方法を提供します。これらのガードレールチェックはエージェントのレスポンスの書き起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効です）。 +ガードレール は、エージェントの発話が特定のルールに違反していないかを監視し、即座にレスポンスを打ち切る仕組みを提供します。これらの ガードレール チェックはエージェントの応答の書き起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効）。 -提供したガードレールは、モデルのレスポンスが返ってくるのと同時に非同期で実行され、あらかじめ定義された分類トリガー（例:「特定の禁止ワードに言及」）に基づいてレスポンスを遮断できます。 +提供した ガードレール は、モデルのレスポンスが返るのと同時に非同期に実行され、例えば「特定の禁止語を言及した」など、あらかじめ定義した分類トリガーに基づいてレスポンスを打ち切れます。 -ガードレールが作動すると、セッションは `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` オブジェクトを渡すことで変更できます。 +`turnDetection` オブジェクトをセッションに渡すことで、音声活動検出モードを変更できます。 -ターン検出の設定を調整すると、不要な割り込みのキャリブレーションや無音への対処に役立ちます。各種設定の詳細は [Realtime API ドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください +ターン検出の設定を調整することで、望ましくない割り込みや無音への対処をキャリブレーションできます。各種設定の詳細は [Realtime API ドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください ## 割り込み -組み込みの音声活動検出を使用している場合、エージェントの発話にかぶせて話すと、自動的に検出され、発話内容に基づいてコンテキストが更新されます。同時に `audio_interrupted` イベントも発行されます。これは、すべての音声再生を即座に停止するために使用できます（WebSocket 接続にのみ適用）。 +組み込みの音声活動検出を使用している場合、エージェントの発話に被せて話すと、自動的にエージェントが発話内容を検知し、コンテキストを更新します。また、`audio_interrupted` イベントを発行します。これはすべての音声再生を即座に停止するために使用できます（WebSocket 接続にのみ適用）。 -UI に「停止」ボタンを提供するなど、手動で割り込みを行いたい場合は、`interrupt()` を手動で呼び出せます: +UI に「停止」ボタンを用意するなど、手動で割り込みを行いたい場合は、`interrupt()` を手動で呼び出せます。 -いずれの場合も、リアルタイムセッションはエージェントの生成の中断、ユーザーに話した内容の切り捨て、および履歴の更新を処理します。 +いずれの場合も、Realtime Session はエージェントの生成を割り込み、ユーザーに話した内容の認識を切り詰め、履歴を更新します。 -エージェントへの接続に WebRTC を使用している場合は、音声出力もクリアされます。WebSocket を使用している場合は、キューに入っている音声の再生を停止するなど、これを自分で処理する必要があります。 +WebRTC を使用してエージェントに接続している場合は、音声出力もクリアされます。WebSocket を使用している場合は、再生キューに入っている音声の再生停止を自分で処理する必要があります。 ## テキスト入力 -エージェントにテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用できます。 +エージェントにテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用します。 -これは、エージェントとのインターフェースを両方のモダリティで有効にしたい場合や、会話に追加のコンテキストを提供したい場合に役立ちます。 +これは、エージェントとのやり取りを両方のモダリティで ユーザー に許可したい場合や、会話に追加のコンテキストを提供したい場合に有用です。 ## 会話履歴の管理 -`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) -会話履歴とツール呼び出しを組み合わせることで、会話を別のバックエンド エージェントに委任して、より複雑なアクションを実行し、その結果を ユーザー に返すことができます。 +会話履歴とツール呼び出しを組み合わせることで、より複雑なアクションを実行するために会話を別のバックエンド エージェント に委譲し、その結果を ユーザー に返すことができます。 -以下のコードは サーバー 上で実行されます。この例では 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 44c74735..b00a02fb 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. **クライアントの一時トークンを生成** +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. **はじめてのエージェントを作成** +3. **はじめてのエージェントの作成** - 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`Agent`](/openai-agents-js/ja/guides/agents) の作成と非常によく似ています。 + 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`エージェント`](/openai-agents-js/ja/guides/agents) の作成と非常によく似ています。 ```typescript import { RealtimeAgent } from '@openai/agents/realtime'; @@ -76,7 +76,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 4. **セッションの作成** - 通常のエージェントと異なり、Voice Agent は会話とモデルへの継続的な接続を処理する `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. **セッションに接続** +5. **セッションへの接続** - セッションに接続するには、先ほど生成したクライアントの一時トークンを渡します。 + セッションに接続するには、先ほど生成したクライアントのエフェメラルトークンを渡す必要があります。 ```typescript await session.connect({ apiKey: 'ek_...(put your own key here)' }); ``` - これにより、ブラウザで WebRTC を使って Realtime API に接続し、音声の入力と出力のためにマイクとスピーカーが自動的に設定されます。`RealtimeSession` をバックエンド サーバー（たとえば Node.js）で実行している場合、SDK は自動的に接続として WebSocket を使用します。さまざまなトランスポートレイヤーの詳細は、[リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドをご覧ください。 + これにより、ブラウザで WebRTC を使用して Realtime API に接続し、音声の入出力用にマイクとスピーカーが自動的に設定されます。`RealtimeSession` をバックエンド サーバー（例えば Node.js）で実行している場合、SDK は自動的に WebSocket を接続として使用します。異なるトランスポート層の詳細は、[リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドをご覧ください。 -6. **すべてをまとめる** +6. **すべてを組み合わせる** -7. **エンジンを始動して話し始める** +7. **エンジンを起動して話し始める** - Web サーバーを起動し、新しい Realtime Agent のコードを含むページに移動します。マイクへのアクセス許可のリクエストが表示されます。許可すると、エージェントと話し始めることができます。 + Web サーバー を起動し、新しい リアルタイムエージェント のコードを含むページにアクセスします。マイクへのアクセス許可のリクエストが表示されます。許可すると、エージェントと会話を始められます。 ```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) + - [音声の割り込みの処理](/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) 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 d7cd22b9..bb20f4b9 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/transport.mdx @@ -29,56 +29,56 @@ 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 オーディオバイトを処理できます。 -### SIP 接続 +### SIP 経由の接続 -`OpenAIRealtimeSIP` トランスポートを使用して、Twilio などのプロバイダからの SIP 通話をブリッジします。トランスポートは、あなたのテレフォニー プロバイダが発行する SIP イベントと Realtime セッションの同期を維持します。 +`OpenAIRealtimeSIP` トランスポートを使用して、Twilio などのプロバイダーからの SIP 通話をブリッジします。このトランスポートは、電話プロバイダーから送出される SIP イベントと リアルタイム セッションを同期させます。 -1. `OpenAIRealtimeSIP.buildInitialConfig()` で初期セッション設定を生成して着信を受け入れます。これにより、SIP 招待と Realtime セッションが同一のデフォルトを共有します -2. `OpenAIRealtimeSIP` トランスポートを使用する `RealtimeSession` をアタッチし、プロバイダの webhook によって発行された `callId` で接続します -3. セッションイベントをリッスンして、通話分析、トランスクリプト、またはエスカレーション ロジックを駆動します +1. `OpenAIRealtimeSIP.buildInitialConfig()` で初期セッション設定を生成し、着信を受け入れます。これにより、SIP 招待と リアルタイム セッションが同一のデフォルトを共有します +2. `OpenAIRealtimeSIP` トランスポートを使用する `RealtimeSession` をアタッチし、プロバイダーの Webhook により発行された `callId` で接続します +3. セッションイベントをリッスンして、通話分析、トランスクリプト、またはエスカレーションロジックを駆動します #### Cloudflare Workers (workerd) に関する注意 -Cloudflare Workers やその他の workerd ランタイムは、グローバルな `WebSocket` コンストラクタを使用してアウトバウンド WebSocket を開けません。拡張パッケージの Cloudflare 用トランスポートを使用してください。これは内部で `fetch()` ベースのアップグレードを実行します。 +Cloudflare Workers やその他の workerd ランタイムは、グローバルの `WebSocket` コンストラクターを使用してアウトバウンド WebSocket を開けません。拡張機能パッケージの 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 - トランスポート層へのアクセス -引き続き `RealtimeSession` のすべての機能を活用したい場合は、`session.transport` を通じてトランスポート層にアクセスできます。 +`RealtimeSession` のすべての機能を活用したい場合は、`session.transport` を通じてトランスポート層にアクセスできます。 -トランスポート層は受信したすべてのイベントを `*` イベントで発行し、`sendEvent()` メソッドを使って元のイベントを送信できます。 +トランスポート層は、受信したすべてのイベントを `*` イベントとして発行し、`sendEvent()` メソッドで元のイベントを送信できます。 -### オプション 2 — トランスポート層のみを使用 +### オプション 2 — トランスポート層のみの使用 -自動ツール実行やガードレールなどが不要な場合、接続と割り込みの管理だけを行う「"thin" クライアント」としてトランスポート層を使用できます。 +自動ツール実行や ガードレール などが不要な場合、接続と割り込みのみを管理する「thin」クライアントとしてトランスポート層を使用できます。 diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index 90a92756..64020437 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -19,33 +19,29 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概要 -[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) は、 -最小限の抽象化で軽量かつ使いやすいパッケージとして、エージェント型の AI アプリを構築できるようにします。これは、以前の -エージェント向け実験である -[Swarm](https://github.com/openai/swarm/tree/main) の本番運用向けアップグレード版で、[Python でも利用可能](https://github.com/openai/openai-agents-python) です。Agents SDK はごく少数の基本コンポーネントで構成されています: +[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できます。これは、以前のエージェント向け実験である [Swarm](https://github.com/openai/swarm/tree/main) の本番利用可能なアップグレードで、[Python 版](https://github.com/openai/openai-agents-python) もあります。Agents SDK の基本的な構成要素（basic components）は非常に少数です。 -- **エージェント**: instructions とツールを備えた LLM -- **ハンドオフ**: 特定のタスクを他のエージェントに委任できる仕組み -- **ガードレール**: エージェントへの入力を検証できる仕組み +- **エージェント**: instructions と tools を備えた LLM +- **ハンドオフ**: 特定のタスクを他のエージェントに委任するしくみ +- **ガードレール**: エージェントへの入力を検証するしくみ -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 の評価、ファインチューニング、蒸留ツールも活用可能 - **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 ## インストール @@ -54,7 +50,7 @@ TypeScript と組み合わせることで、これらの基本コンポーネン npm install @openai/agents zod@3 ``` -## Hello world のコード例 +## Hello World のコード例 diff --git a/docs/src/content/docs/ko/extensions/ai-sdk.mdx b/docs/src/content/docs/ko/extensions/ai-sdk.mdx index dd27c097..c44b9628 100644 --- a/docs/src/content/docs/ko/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ko/extensions/ai-sdk.mdx @@ -7,13 +7,13 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -기본적으로 Agents SDK는 Responses API 또는 Chat Completions API를 통해 OpenAI 모델과 함께 작동합니다. 그러나 다른 모델을 사용하려면, 이 어댑터를 통해 Agents SDK에 통합할 수 있는 다양한 지원 모델을 제공하는 [Vercel's AI SDK](https://sdk.vercel.ai/)를 사용할 수 있습니다. +기본적으로 Agents SDK는 Responses API 또는 Chat Completions API를 통해 OpenAI 모델과 함께 작동합니다. 그러나 다른 모델을 사용하려면, 이 어댑터를 통해 [Vercel의 AI SDK](https://sdk.vercel.ai/)가 지원하는 다양한 모델을 Agents SDK에 도입할 수 있습니다. ## 설정 @@ -25,7 +25,7 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk npm install @openai/agents-extensions ``` -2. [Vercel's AI SDK](https://ai-sdk.dev/docs/foundations/providers-and-models)에서 원하는 모델 패키지를 선택하여 설치합니다: +2. [Vercel의 AI SDK](https://ai-sdk.dev/docs/foundations/providers-and-models)에서 원하는 모델 패키지를 선택하고 설치합니다: ```bash npm install @ai-sdk/openai @@ -47,19 +47,19 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk ## 예제 - + ## 프로바이더 메타데이터 전달 -메시지와 함께 프로바이더별 옵션을 보내야 하는 경우 `providerMetadata`를 통해 전달하세요. 값은 하위 AI SDK 모델로 직접 전달됩니다. 예를 들어, Agents SDK에서 다음 `providerData` +메시지에 프로바이더별 옵션을 보내야 하는 경우 `providerMetadata`를 통해 전달하세요. 값은 기본 AI SDK 모델로 그대로 전달됩니다. 예를 들어, Agents SDK에서 다음 `providerData`는 ```ts providerData: { @@ -71,7 +71,7 @@ providerData: { } ``` -는 AI SDK 통합을 사용할 때 +AI SDK 통합을 사용할 때 다음과 같이 됩니다 ```ts providerMetadata: { @@ -82,5 +82,3 @@ providerMetadata: { } } ``` - -로 변환됩니다. diff --git a/docs/src/content/docs/ko/extensions/cloudflare.mdx b/docs/src/content/docs/ko/extensions/cloudflare.mdx index 41ba2b20..6933b59b 100644 --- a/docs/src/content/docs/ko/extensions/cloudflare.mdx +++ b/docs/src/content/docs/ko/extensions/cloudflare.mdx @@ -6,14 +6,14 @@ 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,7 +26,7 @@ Cloudflare Workers 및 기타 workerd 런타임에서는 전역 `WebSocket` 생 npm install @openai/agents-extensions ``` -2. **전송을 생성하여 세션에 연결합니다.** +2. **전송 방식을 생성하고 세션에 연결합니다.** @@ -40,6 +40,6 @@ Cloudflare Workers 및 기타 workerd 런타임에서는 전역 `WebSocket` 생 ## 참고 사항 -- Cloudflare 전송은 내부적으로 `Upgrade: websocket`과 함께 `fetch()`를 사용하며 소켓의 `open` 이벤트 대기를 건너뛰어, workerd API와 동일하게 동작합니다. -- 이 전송을 사용할 때에도 모든 `RealtimeSession` 기능(tools, guardrails 등)이 평소처럼 동작합니다. -- 개발 중 상세 로그를 확인하려면 `DEBUG=openai-agents*`를 사용하세요. +- 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 ee46ee8d..022e6460 100644 --- a/docs/src/content/docs/ko/extensions/twilio.mdx +++ b/docs/src/content/docs/ko/extensions/twilio.mdx @@ -7,29 +7,30 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio는 전화 통화의 원문 오디오를 WebSocket 서버로 전송하는 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)를 제공합니다. 이 설정을 사용하면 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 Twilio에 연결할 수 있습니다. 기본 Realtime Session 전송 방식을 `websocket` 모드로 사용하여 Twilio에서 오는 이벤트를 Realtime Session에 연결할 수 있습니다. 다만, 웹 기반 대화보다 통화에는 자연스럽게 더 많은 지연이 발생하므로 올바른 오디오 포맷을 설정하고 인터럽션(중단 처리) 타이밍을 조정해야 합니다. +Twilio는 전화 통화에서 나오는 원문 오디오를 WebSocket 서버로 전송하는 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)를 제공합니다. 이 설정을 사용하여 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 Twilio에 연결할 수 있습니다. 기본 Realtime Session 전송을 `websocket` 모드로 사용해 Twilio에서 오는 이벤트를 Realtime Session에 연결할 수 있습니다. 다만, 올바른 오디오 포맷을 설정하고, 웹 기반 대화보다 전화 통화가 자연스럽게 더 높은 지연을 유발하므로 인터럽션(중단 처리) 타이밍을 직접 조정해야 합니다. -설정 경험을 개선하기 위해, Twilio에 대한 연결을 처리하고 인터럽션 및 오디오 전달을 포함해 대신 처리해 주는 전용 전송 계층을 만들었습니다. +설정 경험을 개선하기 위해, 인터럽션(중단 처리)과 오디오 포워딩 등을 포함하여 Twilio와의 연결을 대신 처리하는 전용 전송 레이어를 만들었습니다. ## 설정 -1. **Twilio 계정과 Twilio 전화번호를 준비하세요.** +1. **Twilio 계정과 Twilio 전화번호를 보유하고 있는지 확인하세요.** -2. **Twilio에서 오는 이벤트를 수신할 수 있는 WebSocket 서버를 설정하세요.** +2. **Twilio에서 오는 이벤트를 받을 수 있는 WebSocket 서버를 설정하세요.** - 로컬에서 개발 중이라면, 로컬 서버를 Twilio가 접근할 수 있도록 + 로컬에서 개발하는 경우, Twilio가 로컬 서버에 접근할 수 있도록 [`ngrok`](https://ngrok.io/) 또는 - [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/)과 같은 - 로컬 터널을 구성해야 합니다. `TwilioRealtimeTransportLayer`를 사용해 Twilio에 연결할 수 있습니다. + [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) + 같은 로컬 터널을 구성해야 합니다. `TwilioRealtimeTransportLayer`를 사용해 Twilio에 + 연결할 수 있습니다. 3. **extensions 패키지를 설치하여 Twilio 어댑터를 설치하세요:** @@ -55,30 +56,30 @@ Twilio는 전화 통화의 원문 오디오를 WebSocket 서버로 전송하는 -`RealtimeSession`에서 기대하는 모든 이벤트와 동작은 예상대로 작동하며, 도구 호출, 가드레일 등도 포함됩니다. `RealtimeSession`을 음성 에이전트와 함께 사용하는 방법은 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 참고하세요. +`RealtimeSession`에서 기대되는 모든 이벤트와 동작은 도구 호출, 가드레일 등과 함께 정상적으로 작동합니다. `RealtimeSession`을 음성 에이전트와 함께 사용하는 방법에 대한 자세한 내용은 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 읽어 보세요. -## 팁 및 고려사항 +## 팁 및 고려 사항 1. **속도가 핵심입니다.** - Twilio에서 필요한 모든 이벤트와 오디오를 수신하려면 WebSocket 연결에 대한 참조를 얻는 즉시 - `TwilioRealtimeTransportLayer` 인스턴스를 생성하고 바로 `session.connect()`를 호출해야 합니다. + Twilio에서 필요한 모든 이벤트와 오디오를 받으려면, WebSocket 연결에 대한 참조를 얻는 즉시 + `TwilioRealtimeTransportLayer` 인스턴스를 생성하고 곧바로 `session.connect()`를 호출해야 합니다. -2. **Twilio 원문 이벤트 접근.** +2. **Twilio의 원문 이벤트에 접근하세요.** - Twilio에서 전송되는 원문 이벤트에 접근하려면 `RealtimeSession` 인스턴스에서 - `transport_event` 이벤트를 리슨하면 됩니다. Twilio의 모든 이벤트는 타입이 `twilio_message`이며 - 원문 이벤트 데이터를 포함하는 `message` 속성을 가집니다. + Twilio가 보내는 원문 이벤트에 접근하려면, `RealtimeSession` 인스턴스의 `transport_event` 이벤트를 + 수신하면 됩니다. Twilio에서 온 모든 이벤트는 타입이 `twilio_message`이며 원문 이벤트 데이터가 담긴 + `message` 속성을 가집니다. -3. **디버그 로그 확인.** +3. **디버그 로그를 확인하세요.** - 문제가 발생하여 더 많은 정보가 필요할 때가 있습니다. `DEBUG=openai-agents*` 환경 변수를 사용하면 - Agents SDK의 모든 디버그 로그를 볼 수 있습니다. 또는 Twilio 어댑터에 대해서만 디버그 로그를 - 활성화하려면 `DEBUG=openai-agents:extensions:twilio*`를 사용하세요. + 문제 상황에서 더 많은 정보를 원할 수 있습니다. `DEBUG=openai-agents*` 환경 변수를 사용하면 + Agents SDK의 모든 디버그 로그가 표시됩니다. 또는 Twilio 어댑터에 대한 디버그 로그만 활성화하려면 + `DEBUG=openai-agents:extensions:twilio*`를 사용하세요. -## 전체 예제 서버 +## 전체 예시 서버 -아래는 Twilio에서 요청을 수신하고 이를 `RealtimeSession`으로 전달하는 WebSocket 서버의 엔드투엔드 전체 예제입니다. +아래는 Twilio에서 요청을 수신하고 이를 `RealtimeSession`으로 전달하는 WebSocket 서버의 엔드 투 엔드 예시입니다. + -이 페이지의 나머지 부분에서는 모든 Agent 기능을 자세히 살펴봅니다. +이 페이지의 나머지 부분에서는 모든 Agent 기능을 자세히 설명합니다. --- @@ -31,130 +31,126 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor `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 | 시스템 프롬프트(문자열 **또는** 함수 – [Dynamic instructions](#dynamic-instructions) 참조) | +| `model` | no | 모델 이름 **또는** 사용자 정의 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 구현 | +| `modelSettings` | no | 튜닝 매개변수(temperature, top_p 등). 필요한 속성이 최상위에 없다면 `providerData` 아래에 포함할 수 있습니다 | +| `tools` | no | 모델이 호출할 수 있는 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 인스턴스 배열 | - + --- ## 컨텍스트 -에이전트는 **컨텍스트 타입에 제네릭** 입니다 – 즉, `Agent`. _컨텍스트_ 는 여러분이 생성하여 `Runner.run()` 에 전달하는 의존성 주입 객체입니다. 이는 모든 도구, 가드레일, 핸드오프 등으로 전달되며 상태를 저장하거나 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등)를 제공하는 데 유용합니다. +에이전트는 **컨텍스트 타입에 대해 제네릭** 입니다 – 예: `Agent`. _컨텍스트_ 는 여러분이 생성하여 `Runner.run()` 에 전달하는 의존성 주입 객체입니다. 이 객체는 모든 도구, 가드레일, 핸드오프 등으로 전달되며, 상태 저장 또는 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등)를 제공하는 데 유용합니다. - + --- -## 출력 유형 +## 출력 타입 -기본적으로 Agent는 **일반 텍스트**(`string`)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 `outputType` 속성을 지정할 수 있습니다. SDK는 다음을 허용합니다: +기본적으로 에이전트는 **일반 텍스트**(`string`)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 `outputType` 속성을 지정할 수 있습니다. SDK는 다음을 허용합니다: 1. [Zod](https://github.com/colinhacks/zod) 스키마(`z.object({...})`) -2. JSON 스키마와 호환되는 객체 +2. JSON‑schema 호환 객체 -`outputType` 이 제공되면 SDK는 일반 텍스트 대신 자동으로 -[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)을 사용합니다. +`outputType` 이 제공되면, SDK는 일반 텍스트 대신 +[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 자동으로 사용합니다. --- ## 멀티 에이전트 시스템 설계 패턴 -에이전트를 조합하는 방법은 다양합니다. 프로덕션 앱에서 자주 보이는 두 가지 패턴은 다음과 같습니다: +에이전트를 함께 구성하는 방법은 다양합니다. 프로덕션 앱에서 자주 보는 두 가지 패턴은 다음과 같습니다: -1. **매니저(에이전트를 도구로)** – 중앙 에이전트가 대화를 소유하고 도구로 노출된 전문 에이전트를 호출함 -2. **핸드오프** – 초기 에이전트가 사용자의 요청을 파악한 뒤 전체 대화를 전문가에게 위임함 +1. **Manager(에이전트를 도구로 사용)** – 중앙 에이전트가 대화를 소유하고 도구로 노출된 특화 에이전트를 호출 +2. **Handoffs** – 초기 에이전트가 사용자의 요청을 파악한 후 전체 대화를 전문가에게 위임 -이 접근 방식은 상호 보완적입니다. 매니저는 가드레일이나 속도 제한을 단일 위치에서 강제할 수 있게 하고, 핸드오프는 각 에이전트가 대화 제어를 유지하지 않고 단일 작업에 집중하도록 합니다. +이 접근 방식은 상호 보완적입니다. 매니저는 가드레일이나 레이트 리밋을 한 곳에서 적용할 수 있게 해주며, 핸드오프는 각 에이전트가 대화의 제어를 유지하지 않고 단일 작업에 집중할 수 있게 해줍니다. -### 매니저(에이전트를 도구로) +### Manager(에이전트를 도구로 사용) -이 패턴에서 매니저는 제어권을 넘기지 않습니다—LLM이 도구를 사용하고 매니저가 최종 답을 요약합니다. 자세한 내용은 [도구](/openai-agents-js/ko/guides/tools#agents-as-tools) 가이드를 참고하세요. +이 패턴에서는 매니저가 제어를 넘기지 않습니다—LLM이 도구를 사용하고 매니저가 최종 답을 요약합니다. 자세한 내용은 [도구](/openai-agents-js/ko/guides/tools#agents-as-tools) 가이드를 참조하세요. - + -### 핸드오프 +### Handoffs -핸드오프에서는 분류 에이전트가 요청을 라우팅하지만, 핸드오프가 일어나면 전문가 에이전트가 최종 출력을 낼 때까지 대화를 소유합니다. 이는 프롬프트를 짧게 유지하고 각 에이전트를 독립적으로 추론할 수 있게 합니다. 자세한 내용은 [핸드오프](/openai-agents-js/ko/guides/handoffs) 가이드를 참고하세요. +핸드오프에서는 분류 에이전트가 요청을 라우팅하지만, 일단 핸드오프가 발생하면 전문가 에이전트가 최종 출력을 생성할 때까지 대화를 소유합니다. 이는 프롬프트를 짧게 유지하고 각 에이전트를 독립적으로 이해할 수 있게 합니다. 자세한 내용은 [핸드오프](/openai-agents-js/ko/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/ko/guides/guardrails) 가이드를 참고하세요. +가드레일을 사용하면 사용자 입력과 에이전트 출력을 검증하거나 변환할 수 있습니다. `inputGuardrails` 및 `outputGuardrails` 배열을 통해 구성합니다. 자세한 내용은 [가드레일](/openai-agents-js/ko/guides/guardrails) 가이드를 참조하세요. --- ## 에이전트 복제/복사 -기존 에이전트를 약간만 수정한 버전이 필요하신가요? 완전히 새로운 `Agent` 인스턴스를 반환하는 `clone()` 메서드를 사용하세요. +기존 에이전트의 약간 수정된 버전이 필요하신가요? 완전히 새로운 `Agent` 인스턴스를 반환하는 `clone()` 메서드를 사용하세요. - + --- ## 도구 사용 강제 -도구를 제공해도 LLM이 반드시 호출하는 것은 아닙니다. `modelSettings.tool_choice` 로 도구 사용을 **강제**할 수 있습니다: +도구를 제공해도 LLM이 반드시 호출하는 것은 아닙니다. `modelSettings.tool_choice` 로 도구 사용을 **강제** 할 수 있습니다: 1. `'auto'`(기본값) – LLM이 도구 사용 여부를 결정 -2. `'required'` – LLM은 반드시 도구를 호출해야 함(어떤 도구를 사용할지는 선택 가능) -3. `'none'` – LLM은 도구를 호출하면 **안 됨** -4. 특정 도구 이름, 예: `'calculator'` – 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) => ...` – 실행을 종료할지 여부를 반환하는 커스텀 함수 +- `(context, toolResults) => ...` – 실행을 종료할지 여부를 반환하는 사용자 정의 함수 ```typescript const agent = new Agent({ @@ -167,6 +163,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 2a999c60..b177298f 100644 --- a/docs/src/content/docs/ko/guides/config.mdx +++ b/docs/src/content/docs/ko/guides/config.mdx @@ -13,7 +13,7 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## API 키와 클라이언트 -기본적으로 SDK 는 처음 임포트될 때 `OPENAI_API_KEY` 환경 변수를 읽습니다. 해당 변수를 설정할 수 없다면 `setDefaultOpenAIKey()` 를 수동으로 호출할 수 있습니다. +기본적으로 SDK는 처음 임포트될 때 `OPENAI_API_KEY` 환경 변수를 읽습니다. 해당 변수를 설정할 수 없는 경우 `setDefaultOpenAIKey()`를 직접 호출할 수 있습니다. -직접 만든 `OpenAI` 클라이언트 인스턴스를 전달할 수도 있습니다. 그렇지 않으면 SDK 가 기본 키를 사용해 자동으로 생성합니다. +직접 생성한 `OpenAI` 클라이언트 인스턴스를 전달할 수도 있습니다. 전달하지 않으면 SDK가 기본 키를 사용해 자동으로 생성합니다. -마지막으로 Responses API 와 Chat Completions API 간에 전환할 수 있습니다. +마지막으로 Responses API와 Chat Completions API 사이를 전환할 수 있습니다. @@ -37,7 +37,7 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t 트레이싱은 기본적으로 활성화되어 있으며 위 섹션의 OpenAI 키를 사용합니다. -별도의 키는 `setTracingExportApiKey()` 를 통해 설정할 수 있습니다: +별도의 키는 `setTracingExportApiKey()`를 통해 설정할 수 있습니다. -트레이싱을 완전히 비활성화할 수도 있습니다: +트레이싱을 완전히 비활성화할 수도 있습니다. @@ -71,13 +71,13 @@ export DEBUG=openai-agents* 일부 로그에는 사용자 데이터가 포함될 수 있습니다. 다음 환경 변수를 설정하여 비활성화하세요. -LLM 입력 및 출력을 비활성화하려면: +LLM 입력과 출력을 로깅하지 않으려면: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -도구 입력 및 출력을 비활성화하려면: +도구 입력과 출력을 로깅하지 않으려면: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/src/content/docs/ko/guides/context.mdx b/docs/src/content/docs/ko/guides/context.mdx index d3276cd5..79745b60 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` 같은 콜백, 그리고 라이프사이클 훅 +1. 실행 중 코드가 액세스할 수 있는 **로컬 컨텍스트**: 도구에 필요한 종속성이나 데이터, `onHandoff` 같은 콜백, 라이프사이클 훅 2. 응답을 생성할 때 언어 모델이 볼 수 있는 **에이전트/LLM 컨텍스트** ## 로컬 컨텍스트 -로컬 컨텍스트는 `RunContext` 타입으로 표현됩니다. 상태나 의존성을 담을 임의의 객체를 생성해 `Runner.run()`에 전달합니다. 모든 도구 호출과 훅은 `RunContext` 래퍼를 받아 그 객체를 읽거나 수정할 수 있습니다. +로컬 컨텍스트는 `RunContext` 타입으로 표현됩니다. 상태나 종속성을 담을 객체를 만들어 `Runner.run()`에 전달합니다. 모든 도구 호출과 훅은 `RunContext` 래퍼를 받아 해당 객체에서 읽거나 수정할 수 있습니다. -단일 실행에 참여하는 모든 에이전트, 도구, 훅은 동일한 **type**의 컨텍스트를 사용해야 합니다. +단일 실행에 참여하는 모든 에이전트, 도구, 훅은 동일한 **타입**의 컨텍스트를 사용해야 합니다. 로컬 컨텍스트는 다음과 같은 용도로 사용하세요: - 실행에 대한 데이터(사용자 이름, ID 등) -- 로거나 데이터 페처 같은 의존성 +- 로거 또는 데이터 페처 같은 종속성 - 헬퍼 함수 ## 에이전트/LLM 컨텍스트 LLM이 호출될 때 볼 수 있는 데이터는 대화 기록에서만 옵니다. 추가 정보를 제공하려면 다음 옵션이 있습니다: -1. 에이전트 `instructions`에 추가 – 시스템 또는 개발자 메시지라고도 합니다. 정적 문자열이거나 컨텍스트를 받아 문자열을 반환하는 함수가 될 수 있습니다 -2. `Runner.run()`을 호출할 때 `input`에 포함. instructions 기법과 유사하지만 메시지를 [명령 체계](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)에서 더 아래에 배치할 수 있습니다 -3. 함수 도구를 통해 노출하여 LLM이 온디맨드로 데이터를 가져올 수 있게 합니다 -4. 검색 또는 웹 검색 도구를 사용해 파일, 데이터베이스, 웹의 관련 데이터에 기반하여 응답을 보강합니다 +1. 에이전트 `instructions`에 추가 – 시스템 또는 개발자 메시지라고도 합니다. 고정 문자열이거나 컨텍스트를 받아 문자열을 반환하는 함수일 수 있습니다. +2. `Runner.run()` 호출 시 `input`에 포함합니다. instructions 기법과 유사하지만 메시지를 [명령 체계 (chain of command)](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)에서 더 아래에 배치할 수 있습니다. +3. 함수 도구를 통해 노출하여 LLM이 필요할 때 데이터를 가져올 수 있게 합니다. +4. 검색 또는 웹 검색 도구를 사용해 파일, 데이터베이스 또는 웹의 관련 데이터로 응답을 근거화합니다. diff --git a/docs/src/content/docs/ko/guides/guardrails.mdx b/docs/src/content/docs/ko/guides/guardrails.mdx index 9fe058d1..f5d08635 100644 --- a/docs/src/content/docs/ko/guides/guardrails.mdx +++ b/docs/src/content/docs/ko/guides/guardrails.mdx @@ -7,47 +7,52 @@ 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. 가드레일 함수가 실행되고 [`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** -> 입력 가드레일은 사용자 입력을 대상으로 하므로, 워크플로에서 에이전트가 _첫 번째_ 에이전트인 경우에만 실행됩니다. 가드레일은 에이전트 자체에 구성되며, 에이전트마다 필요한 가드레일이 다를 수 있습니다. +> 입력 가드레일은 사용자 입력을 위한 것이므로, 워크플로에서 해당 에이전트가 _첫 번째_ 에이전트일 때만 실행됩니다. 서로 다른 에이전트는 종종 다른 가드레일을 필요로 하므로 가드레일은 에이전트 자체에 구성됩니다. + +### 실행 모드 + +- `runInParallel: true`(기본값)는 가드레일을 LLM/도구 호출과 함께 시작합니다. 이는 지연 시간을 최소화하지만, 가드레일이 나중에 트리거되면 모델이 이미 토큰을 소비했거나 도구를 실행했을 수 있습니다. +- `runInParallel: false`는 모델을 호출하기 **전에** 가드레일을 실행하여, 가드레일이 요청을 차단할 때 토큰 사용과 도구 실행을 방지합니다. 지연 시간보다 안전성과 비용을 우선할 때 사용하세요. ## 출력 가드레일 출력 가드레일은 3단계로 실행됩니다: 1. 가드레일은 에이전트가 생성한 출력을 받습니다. -2. 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을 반환하며, 이는 [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult)로 래핑됩니다. +2. 가드레일 함수가 실행되고 [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) 내부에 래핑된 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을 반환합니다. 3. `tripwireTriggered`가 `true`이면 [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) 오류가 발생합니다. > **Note** -> 출력 가드레일은 워크플로에서 에이전트가 _마지막_ 에이전트인 경우에만 실행됩니다. 실시간 음성 상호작용은 [음성 에이전트 구축](/openai-agents-js/ko/guides/voice-agents/build#guardrails)을 참조하세요. +> 출력 가드레일은 워크플로에서 에이전트가 _마지막_ 에이전트일 때만 실행됩니다. 실시간 음성 상호작용은 [음성 에이전트 구축](/openai-agents-js/ko/guides/voice-agents/build#guardrails)을 참조하세요. ## 트립와이어 -가드레일이 실패하면 트립와이어를 통해 이를 신호합니다. 트립와이어가 트리거되는 즉시 러너는 해당 오류를 발생시키고 실행을 중단합니다. +가드레일이 실패하면 트립와이어를 통해 이를 신호합니다. 트립와이어가 트리거되는 즉시 러너가 해당 오류를 발생시키고 실행을 중단합니다. ## 가드레일 구현 -가드레일은 `GuardrailFunctionOutput`을 반환하는 간단한 함수입니다. 아래는 다른 에이전트를 내부적으로 실행하여 사용자가 수학 숙제 도움을 요청하는지 확인하는 최소 예시입니다. +가드레일은 `GuardrailFunctionOutput`을 반환하는 간단한 함수입니다. 아래는 내부적으로 다른 에이전트를 실행하여 사용자가 수학 숙제 도움을 요청하는지 확인하는 최소 예제입니다. 출력 가드레일도 동일한 방식으로 동작합니다. @@ -55,7 +60,7 @@ import outputGuardrailExample from '../../../../../../examples/docs/guardrails/g 1. `guardrailAgent`는 가드레일 함수 내부에서 사용됩니다. diff --git a/docs/src/content/docs/ko/guides/handoffs.mdx b/docs/src/content/docs/ko/guides/handoffs.mdx index dcd7b35b..6af6faeb 100644 --- a/docs/src/content/docs/ko/guides/handoffs.mdx +++ b/docs/src/content/docs/ko/guides/handoffs.mdx @@ -10,28 +10,28 @@ import handoffInputExample from '../../../../../../examples/docs/handoffs/handof import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw'; import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw'; -핸드오프는 한 에이전트가 대화의 일부를 다른 에이전트에 위임하도록 합니다. 이는 서로 다른 에이전트가 특정 영역에 특화되어 있을 때 유용합니다. 예를 들어 고객 지원 앱에서는 예약, 환불 또는 FAQ를 처리하는 에이전트가 있을 수 있습니다. +핸드오프는 에이전트가 대화의 일부를 다른 에이전트에 위임할 수 있게 합니다. 이는 서로 다른 에이전트가 특정 분야에 특화되어 있을 때 유용합니다. 예를 들어 고객 지원 앱에서는 예약, 환불 또는 FAQ를 처리하는 에이전트를 둘 수 있습니다. -핸드오프는 LLM에 도구로 표시됩니다. `Refund Agent`라는 에이전트로 핸드오프하면 도구 이름은 `transfer_to_refund_agent`가 됩니다. +핸드오프는 LLM에게 도구로 표현됩니다. `Refund Agent`라는 에이전트로 핸드오프하면 도구 이름은 `transfer_to_refund_agent`가 됩니다. ## 핸드오프 생성 -모든 에이전트는 `handoffs` 옵션을 허용합니다. 여기에는 다른 `Agent` 인스턴스나 `handoff()` 헬퍼가 반환하는 `Handoff` 객체를 포함할 수 있습니다. +모든 에이전트는 `handoffs` 옵션을 허용합니다. 여기에 다른 `Agent` 인스턴스나 `handoff()` 헬퍼가 반환하는 `Handoff` 객체를 포함할 수 있습니다. ### 기본 사용 -### `handoff()`를 통한 핸드오프 커스터마이징 +### `handoff()`를 통한 핸드오프 사용자 지정 -`handoff()` 함수로 생성되는 도구를 조정할 수 있습니다. +`handoff()` 함수는 생성되는 도구를 튜닝할 수 있게 해줍니다. -- `agent` – 핸드오프 대상 에이전트 +- `agent` – 핸드오프할 대상 에이전트 - `toolNameOverride` – 기본 `transfer_to_` 도구 이름 재정의 - `toolDescriptionOverride` – 기본 도구 설명 재정의 -- `onHandoff` – 핸드오프 발생 시 콜백. `RunContext`와 선택적으로 파싱된 입력을 받음 +- `onHandoff` – 핸드오프가 발생할 때 호출되는 콜백. `RunContext`와 선택적으로 파싱된 입력을 전달받음 - `inputType` – 핸드오프에 기대되는 입력 스키마 -- `inputFilter` – 다음 에이전트에 전달할 기록 필터 +- `inputFilter` – 다음 에이전트에 전달할 히스토리 필터 ## 입력 필터 -기본적으로 핸드오프는 전체 대화 기록을 받습니다. 다음 에이전트에 전달되는 내용을 변경하려면 `inputFilter`를 제공하세요. +기본적으로 핸드오프는 전체 대화 히스토리를 전달받습니다. 다음 에이전트에 무엇을 넘길지 변경하려면 `inputFilter`를 제공하세요. 공통 헬퍼는 `@openai/agents-core/extensions`에 있습니다. ## 권장 프롬프트 -프롬프트에 핸드오프를 언급하면 LLM이 더 안정적으로 응답합니다. SDK는 `RECOMMENDED_PROMPT_PREFIX`를 통해 권장 접두사를 제공합니다. +프롬프트에 핸드오프를 언급하면 LLM이 더 안정적으로 반응합니다. SDK는 `RECOMMENDED_PROMPT_PREFIX`를 통해 권장 접두어를 제공합니다. -작동하는 엔드 투 엔드 버전은 [전체 예제 스크립트](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts)를 참고하세요. +엔드 투 엔드로 동작하는 버전은 [전체 예제 스크립트](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts)를 참고하세요. -## 더 긴 승인 시간 처리 +## 긴 승인 소요 시간 처리 -휴먼인더루프 (HITL) 흐름은 서버를 계속 실행하지 않고도 오랜 기간 인터럽트될 수 있도록 설계되었습니다. 요청을 종료하고 나중에 계속해야 하는 경우 상태를 직렬화하여 나중에 재개할 수 있습니다. +휴먼인더루프 (HITL) 흐름은 서버를 계속 실행하지 않고도 오랜 시간 인터럽트될 수 있도록 설계되었습니다. 요청을 중지했다가 나중에 계속해야 한다면 상태를 직렬화하여 재개할 수 있습니다. `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 3244985b..efd61057 100644 --- a/docs/src/content/docs/ko/guides/mcp.mdx +++ b/docs/src/content/docs/ko/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)은 애플리케이션이 LLMs에 도구와 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP 문서에서 인용: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io)은 애플리케이션이 LLM에 도구와 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP 문서에서 인용: -> MCP는 애플리케이션이 LLMs에 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB-C 포트로 생각해 보세요. USB-C가 다양한 주변기기와 액세서리에 장치를 연결하는 표준화된 방식을 제공하듯이, MCP는 AI 모델을 다양한 데이터 소스와 도구에 연결하는 표준화된 방식을 제공합니다. +> MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP를 AI 애플리케이션용 USB‑C 포트라고 생각해 보세요. USB‑C가 다양한 주변기기와 액세서리에 기기를 연결하는 표준 방식을 제공하듯, MCP는 AI 모델을 서로 다른 데이터 소스와 도구에 연결하는 표준 방식을 제공합니다. 이 SDK가 지원하는 MCP 서버 유형은 세 가지입니다: -1. **호스티드 MCP 서버 도구** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp)가 도구로 사용하는 원격 MCP 서버 -2. **Streamable HTTP MCP 서버** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http)를 구현한 로컬 또는 원격 서버 -3. **Stdio MCP 서버** – 표준 입력/출력을 통해 접근하는 서버(가장 간단한 옵션) +1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp)가 도구로 사용하는 원격 MCP 서버 +2. **Streamable HTTP MCP servers** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http)를 구현한 로컬 또는 원격 서버 +3. **Stdio MCP servers** – 표준 입출력을 통해 접근하는 서버(가장 간단한 옵션) 사용 사례에 따라 서버 유형을 선택하세요: -| 필요한 것 | 권장 옵션 | -| ------------------------------------------------------------------- | ------------------------ | -| 기본 OpenAI Responses 모델로 공개 접근 가능한 원격 서버 호출 | **1. 호스티드 MCP 도구** | -| 공개 접근 가능한 원격 서버를 사용하지만 도구 호출은 로컬에서 트리거 | **2. Streamable HTTP** | -| 로컬에서 실행 중인 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | -| OpenAI-Responses 이외의 모델로 모든 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | -| 표준 I/O 프로토콜만 지원하는 로컬 MCP 서버 사용 | **3. Stdio** | +| 필요한 것 | 권장 옵션 | +| ------------------------------------------------------------------------- | ----------------------- | +| 공개적으로 접근 가능한 원격 서버를 기본 OpenAI Responses 모델과 함께 호출 | **1. Hosted MCP tools** | +| 공개적으로 접근 가능한 원격 서버를 사용하지만 도구 호출을 로컬에서 트리거 | **2. Streamable HTTP** | +| 로컬에서 실행 중인 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | +| OpenAI Responses가 아닌 모델로 모든 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | +| 표준 I/O 프로토콜만 지원하는 로컬 MCP 서버 사용 | **3. Stdio** | -## 1. 호스티드 MCP 서버 도구 +## 1. Hosted MCP server 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` 메서드)로 에이전트를 실행할 수 있습니다: -이 예시에서 `GOOGLE_CALENDAR_AUTHORIZATION` 환경 변수에는 Google OAuth Playground에서 얻은 OAuth 토큰이 들어 있으며, 커넥터 기반 서버가 Calendar API를 호출하도록 권한을 부여합니다. 스트리밍도 함께 시연하는 실행 가능한 샘플은 [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors)를 참고하세요. +이 예시에서 `GOOGLE_CALENDAR_AUTHORIZATION` 환경 변수에는 Google OAuth Playground에서 얻은 OAuth 토큰이 저장되어 있으며, 이는 커넥터 기반 서버가 Calendar API를 호출하도록 권한을 부여합니다. 스트리밍도 함께 보여주는 실행 가능한 샘플은 [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors)를 참조하세요. -완전한 동작 샘플(호스티드 도구/Streamable HTTP/stdio + 스트리밍, HITL, onApproval)은 GitHub 리포지토리의 [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp)에 있습니다. +완전한 동작 샘플(Hosted tools/Streamable HTTP/stdio + Streaming, HITL, onApproval)은 GitHub 리포지토리의 [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp)에 있습니다. -## 2. Streamable HTTP MCP 서버 +## 2. Streamable HTTP MCP servers -에이전트가 로컬 또는 원격의 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 서버 +## 3. Stdio MCP servers -표준 I/O만 노출하는 서버의 경우, `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/) – 공식 사양 +- [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 b2b35d47..f988d26a 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에 대해 _하나의_ 요청을 수행하는 방법을 알고 있습니다 -- [`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"` reasoning effort를 지원하지 않으므로, 이 Agents SDK는 기본값으로 `"low"`를 사용합니다. +더 낮은 지연 시간을 위해 [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 또는 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)를 `reasoning.effort="minimal"`로 사용하면 기본 설정보다 더 빠르게 응답하는 경우가 많습니다. 다만 Responses API의 일부 기본 제공 도구(예: 파일 검색 및 이미지 생성)는 `"minimal"` reasoning effort를 지원하지 않으므로, 이 Agents SDK의 기본값은 `"low"`입니다. ### 비 GPT-5 모델 -커스텀 `modelSettings` 없이 비 GPT-5 모델 이름을 전달하면, SDK는 모든 모델과 호환되는 일반적인 `modelSettings`로 되돌립니다. +사용자 지정 `modelSettings` 없이 비 GPT-5 모델 이름을 전달하면, SDK는 모든 모델과 호환되는 일반적인 `modelSettings`로 되돌립니다. --- ## OpenAI 프로바이더 -기본 `ModelProvider`는 OpenAI API를 사용하여 이름을 확인합니다. 두 가지 구분된 엔드포인트를 지원합니다: +기본 `ModelProvider`는 OpenAI API를 사용해 이름을 해석합니다. 두 가지 별도의 엔드포인트를 지원합니다: -| API | 사용 용도 | `setOpenAIAPI()` 호출 | -| ---------------- | ------------------------------------------------------- | --------------------------------------- | -| Chat Completions | 표준 채팅 및 함수 호출 | `setOpenAIAPI('chat_completions')` | -| Responses | 스트리밍 우선의 새로운 생성 API(도구 호출, 유연한 출력) | `setOpenAIAPI('responses')` _(default)_ | +| API | 사용법 | `setOpenAIAPI()` 호출 | +| ---------------- | ----------------------------------------------------- | -------------------------------------- | +| Chat Completions | 표준 채팅 및 함수 호출 | `setOpenAIAPI('chat_completions')` | +| Responses | 스트리밍 우선의 신규 생성 API(도구 호출, 유연한 출력) | `setOpenAIAPI('responses')` _(기본값)_ | ### 인증 @@ -82,45 +82,45 @@ node my-awesome-agent.js title="기본 OpenAI 키 설정" /> -맞춤형 네트워킹 설정이 필요하다면 `setDefaultOpenAIClient(client)`를 통해 직접 `OpenAI` 클라이언트를 연결할 수도 있습니다. +맞춤 네트워킹 설정이 필요하면 `setDefaultOpenAIClient(client)`를 통해 자체 `OpenAI` 클라이언트를 연결할 수 있습니다. --- ## ModelSettings -`ModelSettings`는 OpenAI 매개변수와 유사하지만 공급자에 구애받지 않습니다. +`ModelSettings`는 OpenAI 파라미터를 반영하지만 프로바이더에 종속되지 않습니다. -| 필드 | 타입 | 비고 | +| Field | Type | Notes | | ------------------- | ------------------------------------------ | -------------------------------------------------------------------------- | | `temperature` | `number` | 창의성 대 결정론 | | `topP` | `number` | 누클리어스 샘플링 | -| `frequencyPenalty` | `number` | 반복 토큰에 패널티 부여 | -| `presencePenalty` | `number` | 새로운 토큰을 장려 | -| `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [도구 사용 강제](/openai-agents-js/ko/guides/agents#forcing-tool-use) 참조 | +| `frequencyPenalty` | `number` | 반복 토큰에 대한 패널티 | +| `presencePenalty` | `number` | 새로운 토큰 장려 | +| `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [도구 사용 강제](/openai-agents-js/ko/guides/agents#forcing-tool-use) 참고 | | `parallelToolCalls` | `boolean` | 지원되는 경우 병렬 함수 호출 허용 | | `truncation` | `'auto' \| 'disabled'` | 토큰 절단 전략 | | `maxTokens` | `number` | 응답의 최대 토큰 수 | -| `store` | `boolean` | 응답을 보존하여 검색/RAG 워크플로에 사용 | +| `store` | `boolean` | 검색/RAG 워크플로를 위해 응답을 보존 | | `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 등에서의 reasoning effort | | `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` | 프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열이거나 텍스트, 이미지, 파일과 같은 콘텐츠 입력 타입일 수 있음 | +| Field | Type | Notes | +| ----------- | -------- | ---------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | 프롬프트의 고유 식별자 | +| `version` | `string` | 사용하려는 프롬프트 버전 | +| `variables` | `object` | 프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열 또는 텍스트, 이미지, 파일과 같은 콘텐츠 입력 타입일 수 있음 | -도구나 instructions 같은 추가 에이전트 구성은 저장된 프롬프트에서 구성했을 수 있는 값을 덮어씁니다. +도구나 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/guardrails) 또는 [트레이싱](/openai-agents-js/ko/guides/tracing)을 추가하세요. +- [에이전트 실행](/openai-agents-js/ko/guides/running-agents)을 살펴보세요 +- [도구](/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 8e164647..cbee8e40 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. 에이전트가 자기 성찰과 개선을 하도록 허용하세요. 예를 들어 루프에서 실행하여 스스로 비평하게 하거나, 에러 메시지를 제공하고 개선하도록 하세요. -4. 모든 일을 잘하는 범용 에이전트 대신 하나의 작업에 특화되어 뛰어난 에이전트를 두세요. -5. [evals](https://platform.openai.com/docs/guides/evals)에 투자하세요. 이를 통해 에이전트를 훈련해 개선하고 작업 수행 능력을 높일 수 있습니다. +1. 좋은 프롬프트에 투자하세요. 사용 가능한 도구, 사용 방법, 운영해야 하는 파라미터를 명확히 하세요 +2. 앱을 모니터링하고 반복 개선하세요. 문제가 발생하는 지점을 파악하고 프롬프트를 개선하세요 +3. 에이전트가 자기 성찰하고 개선하도록 하세요. 예를 들어 루프에서 실행해 스스로 비판하게 하거나, 에러 메시지를 제공해 개선하도록 하세요 +4. 모든 일을 잘하는 범용 에이전트 대신, 한 가지 작업에 특화된 에이전트를 두세요 +5. [evals](https://platform.openai.com/docs/guides/evals)에 투자하세요. 이를 통해 에이전트를 훈련해 성능을 향상할 수 있습니다 ## 코드 기반 오케스트레이션 -LLM을 통한 오케스트레이션은 강력하지만, 코드 기반 오케스트레이션은 속도, 비용, 성능 측면에서 더 결정적이고 예측 가능하게 만듭니다. 일반적인 패턴은 다음과 같습니다: +LLM 기반 오케스트레이션이 강력하긴 하지만, 코드 기반 오케스트레이션은 속도, 비용, 성능 면에서 작업을 더 결정적이고 예측 가능하게 만듭니다. 일반적인 패턴은 다음과 같습니다: -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성. 예를 들어, 에이전트에게 작업을 몇 개의 카테고리로 분류하게 한 뒤 해당 카테고리에 따라 다음 에이전트를 선택 -- 한 에이전트의 출력을 다음 에이전트의 입력으로 변환해 여러 에이전트를 체이닝. 블로그 글 작성을 조사하기, 개요 작성, 블로그 글 작성, 비평, 개선의 단계로 연속 구성할 수 있음 -- 작업을 수행하는 에이전트와 평가 및 피드백을 제공하는 에이전트를 함께 `while` 루프로 실행하고, 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복 -- `Promise.all` 같은 JavaScript 기본 컴포넌트를 통해 여러 에이전트를 병렬 실행. 서로 의존하지 않는 여러 작업이 있을 때 속도 면에서 유용 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성합니다. 예를 들어, 에이전트에게 태스크를 몇 가지 카테고리로 분류하게 한 뒤, 해당 카테고리에 따라 다음 에이전트를 선택할 수 있습니다 +- 한 에이전트의 출력을 다음 에이전트의 입력으로 변환하여 여러 에이전트를 체이닝합니다. 블로그 글 작성 같은 태스크를 연구, 개요 작성, 본문 작성, 비판, 개선의 일련의 단계로 분해할 수 있습니다 +- 평가와 피드백을 제공하는 에이전트와 실제 작업을 수행하는 에이전트를 `while` 루프로 함께 실행하고, 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복합니다 +- `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)에 여러 예제가 있습니다. diff --git a/docs/src/content/docs/ko/guides/quickstart.mdx b/docs/src/content/docs/ko/guides/quickstart.mdx index 872ad245..96256170 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 키를 설정합니다. 키가 없다면 OpenAI API 키를 생성하려면 [이 지침](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)을 따르세요. ```bash export OPENAI_API_KEY=sk-... ``` - 또는 `setDefaultOpenAIKey('')`를 호출하여 프로그램적으로 키를 설정하고, + 또는 `setDefaultOpenAIKey('')`를 호출해 프로그램적으로 키를 설정하고, 트레이싱에는 `setTracingExportApiKey('')`를 사용할 수 있습니다. - 자세한 내용은 [설정 가이드](/openai-agents-js/ko/guides/config)를 참고하세요. + 자세한 내용은 [SDK 설정](/openai-agents-js/ko/guides/config)을 참조하세요. ## 첫 에이전트 생성 -에이전트는 instructions와 이름으로 정의됩니다. +에이전트는 instructions와 이름으로 정의합니다. ```typescript import { Agent } from '@openai/agents'; @@ -53,10 +53,9 @@ const agent = new Agent({ ## 첫 에이전트 실행 -에이전트를 실행하려면 `run` 메서드를 사용할 수 있습니다. 시작할 에이전트와 -에이전트에 전달할 입력을 함께 전달하여 실행을 트리거합니다. +`run` 메서드를 사용해 에이전트를 실행할 수 있습니다. 시작할 에이전트와 전달할 입력을 함께 넘기면 실행이 트리거됩니다. -이렇게 하면 해당 실행 동안 수행된 모든 동작과 최종 출력을 포함하는 결과가 반환됩니다. +이렇게 하면 해당 실행 동안 수행된 최종 출력과 모든 작업이 포함된 결과가 반환됩니다. ```typescript import { Agent, run } from '@openai/agents'; @@ -74,7 +73,7 @@ console.log(result.finalOutput); ## 에이전트에 도구 제공 -에이전트가 정보를 조회하거나 작업을 수행할 수 있도록 도구를 제공할 수 있습니다. +에이전트에 정보를 조회하거나 작업을 수행하는 도구를 부여할 수 있습니다. ```typescript import { Agent, tool } from '@openai/agents'; @@ -101,11 +100,9 @@ const agent = new Agent({ }); ``` -## 에이전트 몇 개 더 추가 +## 에이전트 추가 -추가 에이전트를 비슷한 방식으로 정의하여 문제를 더 작은 부분으로 나누고, -에이전트가 현재 작업에 더욱 집중하도록 할 수 있습니다. 또한 에이전트에 모델을 정의하여 -문제 유형에 따라 서로 다른 모델을 사용할 수 있습니다. +추가 에이전트를 유사하게 정의해 문제를 더 작은 부분으로 분해하고, 에이전트가 현재 작업에 더 집중하도록 만들 수 있습니다. 또한 에이전트에 모델을 정의하여 문제마다 다른 모델을 사용할 수 있습니다. ```typescript const historyTutorAgent = new Agent({ @@ -123,9 +120,7 @@ const mathTutorAgent = new Agent({ ## 핸드오프 정의 -여러 에이전트를 오케스트레이션하기 위해 에이전트에 `handoffs`를 정의할 수 있습니다. -이렇게 하면 에이전트가 대화를 다음 에이전트로 넘길 수 있습니다. 이는 실행 과정에서 -자동으로 발생합니다. +여러 에이전트를 오케스트레이션하기 위해 에이전트에 `handoffs`를 정의할 수 있습니다. 이렇게 하면 에이전트가 다음 에이전트로 대화를 전달할 수 있으며, 이는 실행 과정에서 자동으로 이루어집니다. ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -137,11 +132,11 @@ const triageAgent = Agent.create({ }); ``` -실행이 끝난 후 결과의 `finalAgent` 속성을 확인하면 어떤 에이전트가 최종 응답을 생성했는지 알 수 있습니다. +실행이 끝난 후 결과의 `finalAgent` 속성을 보면 어느 에이전트가 최종 응답을 생성했는지 확인할 수 있습니다. ## 에이전트 오케스트레이션 실행 -Runner는 개별 에이전트의 실행, 잠재적 핸드오프, 도구 실행을 처리합니다. +Runner는 개별 에이전트의 실행, 가능한 핸드오프, 도구 실행을 처리합니다. ```typescript import { run } from '@openai/agents'; @@ -156,21 +151,20 @@ main().catch((err) => console.error(err)); ## 모두 합쳐 보기 -이제 모든 내용을 하나의 전체 예제로 합쳐 보겠습니다. 이를 `index.js` 파일에 넣고 실행하세요. +이제 모두 하나의 전체 예제로 합쳐 봅시다. 이를 `index.js` 파일에 넣고 실행하세요. - + -## 트레이스 확인 +## 트레이스 보기 -Agents SDK는 자동으로 트레이스를 생성합니다. 이를 통해 에이전트가 어떻게 동작했는지, -어떤 도구를 호출했는지, 어떤 에이전트로 핸드오프했는지를 확인할 수 있습니다. +Agents SDK는 자동으로 트레이스를 생성합니다. 이를 통해 에이전트가 어떻게 동작했는지, 어떤 도구를 호출했는지, 어느 에이전트로 핸드오프했는지 검토할 수 있습니다. -에이전트 실행 중에 어떤 일이 일어났는지 확인하려면 -[OpenAI Dashboard의 Trace viewer](https://platform.openai.com/traces)로 이동하세요. +에이전트 실행 중에 무엇이 일어났는지 검토하려면 +[OpenAI 대시보드의 Trace viewer](https://platform.openai.com/traces)로 이동하세요. ## 다음 단계 -더 복잡한 에이전트 플로우를 만드는 방법을 알아보세요: +더 복잡한 에이전트 플로우를 만드는 방법을 알아보세요. - [에이전트](/openai-agents-js/ko/guides/agents) 구성에 대해 알아보기 - [에이전트 실행](/openai-agents-js/ko/guides/running-agents)에 대해 알아보기 diff --git a/docs/src/content/docs/ko/guides/release.mdx b/docs/src/content/docs/ko/guides/release.mdx index fe7a3743..2358ecc3 100644 --- a/docs/src/content/docs/ko/guides/release.mdx +++ b/docs/src/content/docs/ko/guides/release.mdx @@ -5,30 +5,30 @@ description: Learn how we version and release the SDK and recent changes. ## 버전 관리 -이 프로젝트는 `0.Y.Z` 형태를 사용하는 의미론적 버전(semantic versioning)의 약간 수정된 방식을 따릅니다. 앞의 `0`은 SDK가 여전히 빠르게 발전 중임을 나타냅니다. 각 구성 요소 증분 규칙은 다음과 같습니다: +프로젝트는 `0.Y.Z` 형식의 약간 수정된 시맨틱 버전 관리를 따릅니다. 앞의 `0`은 SDK가 아직 빠르게 발전 중임을 나타냅니다. 각 구성 요소는 다음과 같이 증가시킵니다. ## 마이너(`Y`) 버전 -베타로 표시되지 않은 공개 인터페이스에 대한 **breaking changes**가 있을 때 마이너 버전 `Y`를 올립니다. 예를 들어, `0.0.x`에서 `0.1.x`로 변경될 때 호환성 파괴 변경이 포함될 수 있습니다. +베타로 표시되지 않은 공개 인터페이스에 **하위 호환이 깨지는 변경 사항**이 있을 경우 마이너 버전 `Y`를 증가시킵니다. 예를 들어, `0.0.x`에서 `0.1.x`로의 변경에는 하위 호환성 파괴 변경이 포함될 수 있습니다. -호환성 파괴 변경을 원하지 않는 경우 프로젝트에서 `0.0.x` 버전에 고정할 것을 권장합니다. +하위 호환성 파괴 변경을 원하지 않는 경우, 프로젝트에서 `0.0.x` 버전에 고정할 것을 권장합니다. ## 패치(`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 8354d616..bed207a5 100644 --- a/docs/src/content/docs/ko/guides/results.mdx +++ b/docs/src/content/docs/ko/guides/results.mdx @@ -7,25 +7,25 @@ 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)도 참고하세요 +- [`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/ko/guides/streaming)을 확인하세요 ## 최종 출력 `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` 속성에 대한 유니온 타입을 제공합니다. -예시: +예: -## 다음 턴의 입력 +## 다음 턴 입력 다음 턴의 입력에 접근하는 방법은 두 가지입니다: -- `result.history` — 입력과 에이전트 출력 모두의 사본을 포함 +- `result.history` — 입력과 에이전트 출력 모두의 복사본을 포함 - `result.output` — 전체 에이전트 실행의 출력을 포함 -`history`는 채팅과 같은 사용 사례에서 전체 이력을 유지하는 편리한 방법입니다: +`history`는 채팅과 유사한 사용 사례에서 전체 이력을 유지하기에 편리한 방법입니다: ## 마지막 에이전트 -`lastAgent` 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라 다음에 사용자가 무언가를 입력할 때 유용한 경우가 많습니다. 예를 들어, 1차 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우 마지막 에이전트를 저장해 두었다가 사용자가 다음에 메시지를 보낼 때 재사용할 수 있습니다. +`lastAgent` 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라, 이는 다음에 user가 무언가를 입력할 때 유용한 경우가 많습니다. 예를 들어, 프론트라인 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우, 마지막 에이전트를 저장해 두었다가 다음에 사용자가 에이전트에 메시지를 보낼 때 재사용할 수 있습니다. 스트리밍 모드에서는 현재 실행 중인 에이전트에 매핑되는 `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의 추론 항목을 나타냄. 원문 항목은 생성된 추론 +- [`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`s의 배열이 됩니다. 인터럽션을 다루는 방법에 대한 자세한 내용은 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop) 가이드를 확인하세요. +에이전트에서 `needsApproval`을 사용하는 경우, 계속하기 전에 처리해야 하는 `interruptions`가 트리거될 수 있습니다. 이 경우 `interruptions`는 인터럽션을 유발한 `ToolApprovalItem`의 배열이 됩니다. 인터럽션 처리 방법에 대한 자세한 내용은 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop) 가이드를 확인하세요. ## 기타 정보 ### 원문 응답 -`rawResponses` 속성에는 에이전트 실행 중 모델이 생성한 원문 LLM 응답이 포함됩니다. +`rawResponses` 속성에는 에이전트 실행 중 모델이 생성한 원문의 LLM 응답이 포함됩니다. ### 마지막 응답 ID @@ -82,8 +82,8 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? ### 가드레일 결과 -`inputGuardrailResults`와 `outputGuardrailResults` 속성에는 가드레일 결과(있는 경우)가 포함됩니다. 가드레일 결과에는 기록하거나 저장하고 싶은 유용한 정보가 포함될 수 있으므로 이를 제공해 드립니다. +`inputGuardrailResults`와 `outputGuardrailResults` 속성에는 가드레일 결과(있는 경우)가 포함됩니다. 가드레일 결과에는 로깅하거나 저장하고 싶은 유용한 정보가 포함될 수 있으므로 이를 제공합니다. -### 원래 입력 +### 원본 입력 -`input` 속성에는 run 메서드에 제공한 원래 입력이 포함됩니다. 대부분의 경우 필요하지 않지만, 필요한 경우를 대비해 제공됩니다. +`input` 속성에는 run 메서드에 제공한 원본 입력이 포함됩니다. 대부분의 경우 필요하지 않지만, 필요한 경우를 대비해 제공됩니다. diff --git a/docs/src/content/docs/ko/guides/running-agents.mdx b/docs/src/content/docs/ko/guides/running-agents.mdx index 32b6e131..47b658a5 100644 --- a/docs/src/content/docs/ko/guides/running-agents.mdx +++ b/docs/src/content/docs/ko/guides/running-agents.mdx @@ -11,28 +11,28 @@ 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` 인스턴스를 실행하는 `run()` 유틸리티를 사용할 수 있습니다. 또는 직접 러너 인스턴스를 만들 수도 있습니다: -에이전트를 실행한 후에는 최종 출력과 실행의 전체 내역을 담은 [실행 결과](/openai-agents-js/ko/guides/results) 객체를 받게 됩니다. +에이전트를 실행하면 최종 출력과 실행 전체 이력을 포함하는 [실행 결과](/openai-agents-js/ko/guides/results) 객체를 받게 됩니다. ## 에이전트 루프 -Runner에서 run 메서드를 사용할 때 시작할 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주됨) 또는 OpenAI Responses API의 항목인 입력 항목 리스트일 수 있습니다. +Runner에서 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주) 또는 OpenAI Responses API의 항목인 입력 항목 목록일 수 있습니다. -러너는 다음과 같은 루프를 수행합니다: +이후 러너는 다음 루프를 실행합니다: 1. 현재 입력으로 현재 에이전트의 모델을 호출 2. LLM 응답 검사 - **최종 출력** → 반환 - - **핸드오프** → 새 에이전트로 전환, 누적된 대화 기록 유지, 1로 이동 + - **핸드오프** → 새 에이전트로 전환, 누적 대화 기록 유지, 1로 이동 - **도구 호출** → 도구 실행, 결과를 대화에 추가, 1로 이동 3. `maxTurns`에 도달하면 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) 발생 @@ -43,48 +43,48 @@ Runner에서 run 메서드를 사용할 때 시작할 에이전트와 입력을 ### Runner 수명 주기 -앱 시작 시 `Runner`를 생성하고 요청 간에 재사용하세요. 이 인스턴스는 모델 제공자와 트레이싱 옵션 같은 전역 구성을 저장합니다. 완전히 다른 설정이 필요할 때만 다른 `Runner`를 만드세요. 간단한 스크립트의 경우 내부적으로 기본 러너를 사용하는 `run()`을 호출할 수도 있습니다. +앱이 시작될 때 `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` | – | 모든 도구 / 가드레일 / 핸드오프로 전달되는 컨텍스트 객체. [컨텍스트 가이드](/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` 객체를 전달할 수 있습니다. - -| 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` 인스턴스를 만드는 경우 러너를 구성하기 위해 `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` | 모든 스팬에 첨부할 임의의 메타데이터입니다. | ## 대화 / 채팅 스레드 -각 `runner.run()` 호출(또는 `run()` 유틸리티)은 애플리케이션 수준 대화의 한 번의 **턴**을 나타냅니다. 최종 사용자에게 `RunResult`의 어느 정도를 보여줄지 선택합니다. 때로는 `finalOutput`만, 때로는 생성된 모든 항목을 보여줍니다. +`runner.run()`(또는 `run()` 유틸리티)에 대한 각 호출은 애플리케이션 수준 대화에서 하나의 **턴**을 나타냅니다. 최종 사용자에게 `RunResult`의 어느 정도를 보여줄지 선택할 수 있습니다. 때로는 `finalOutput`만, 다른 때는 생성된 모든 항목을 보여줄 수 있습니다. -#### 2. 마지막 턴에서 이어가기 위한 `previousResponseId` +#### 2. 마지막 턴에서 계속하기 위한 `previousResponseId` -어차피 Responses API만으로 시작하려는 경우, 이전 응답에서 반환된 ID를 사용해 각 요청을 체이닝할 수 있습니다. 별도의 대화 리소스를 만들지 않고도 턴 간 컨텍스트를 유지합니다. +어차피 Responses API만으로 시작하려는 경우, 이전 응답에서 반환된 ID를 사용해 각 요청을 체이닝할 수 있습니다. 이렇게 하면 완전한 대화 리소스를 만들지 않고도 턴 간 컨텍스트가 유지됩니다. Tip: 이 페이지의 `OpenAIConversationsSession` 코드 예제를 실행하려면 `OPENAI_API_KEY` 환경 변수를 설정하세요(또는 세션 생성 시 `apiKey`를 제공). 그러면 SDK가 Conversations API를 호출할 수 있습니다. +> 팁: 이 페이지의 `OpenAIConversationsSession` 예제를 실행하려면 `OPENAI_API_KEY` 환경 변수를 설정하세요(또는 세션 생성 시 `apiKey`를 제공). 그러면 SDK가 Conversations API를 호출할 수 있습니다. --- ## 빠른 시작 -`OpenAIConversationsSession`을 사용하여 [Conversations API](https://platform.openai.com/docs/api-reference/conversations)와 메모리를 동기화하거나, 다른 어떤 `Session` 구현으로 교체하세요. +`OpenAIConversationsSession`을 사용해 [Conversations API](https://platform.openai.com/docs/api-reference/conversations)와 메모리를 동기화하거나, 다른 어떤 `Session` 구현으로 교체하세요. -같은 세션 인스턴스를 재사용하면 매 턴마다 에이전트가 전체 대화 기록을 수신하고 새 항목이 자동으로 영구 저장됩니다. 다른 `Session` 구현으로 전환해도 추가 코드 변경은 필요 없습니다. +동일한 세션 인스턴스를 재사용하면 에이전트가 매 턴 전에 전체 대화 히스토리를 받으며 새로운 항목도 자동으로 지속 저장됩니다. 다른 `Session` 구현으로 전환하더라도 코드 변경은 필요 없습니다. --- ## 러너의 세션 사용 방식 -- **각 실행 전** 세션 히스토리를 가져오고 새 턴 입력과 병합한 뒤, 결합된 목록을 에이전트에 전달합니다. -- **비 스트리밍 실행 후** `session.addItems()` 한 번으로 최신 턴의 원본 사용자 입력과 모델 출력을 모두 영구 저장합니다. -- **스트리밍 실행의 경우** 사용자 입력을 먼저 기록하고, 턴이 완료되면 스트리밍된 출력을 추가합니다. -- **`RunResult.state`에서 재개할 때**(승인 또는 기타 인터럽션(중단 처리)) 동일한 `session`을 계속 전달하세요. 재개된 턴은 입력을 다시 준비하지 않고 메모리에 추가됩니다. +- **각 실행 전** 세션 히스토리를 가져와 새 턴의 입력과 병합하고, 결합된 리스트를 에이전트에 전달합니다. +- **스트리밍이 아닌 실행 후** 한 번의 `session.addItems()` 호출로 최신 턴의 원본 사용자 입력과 모델 출력을 모두 저장합니다. +- **스트리밍 실행의 경우** 사용자 입력을 먼저 기록하고, 턴이 완료되면 스트리밍된 출력을 추가로 기록합니다. +- **`RunResult.state`에서 재개할 때**(승인 또는 기타 인터럽션) 동일한 `session`을 계속 전달하세요. 재개된 턴은 입력을 다시 준비하지 않고 메모리에 추가됩니다. --- ## 히스토리 검사 및 편집 -세션은 간단한 CRUD 헬퍼를 제공하므로 "실행 취소", "채팅 지우기", 감사를 위한 기능을 구축할 수 있습니다. +세션은 간단한 CRUD 도우미를 제공하므로 "실행 취소", "채팅 지우기" 또는 감사 기능을 구축할 수 있습니다. - + -`session.getItems()`는 저장된 `AgentInputItem[]`을 반환합니다. `popItem()`을 호출하여 마지막 항목을 제거할 수 있습니다. 이는 에이전트를 다시 실행하기 전에 사용자가 수정할 때 유용합니다. +`session.getItems()`는 저장된 `AgentInputItem[]`을 반환합니다. `popItem()`을 호출해 마지막 항목을 제거하세요—에이전트를 다시 실행하기 전에 사용자가 수정할 때 유용합니다. --- -## 스토리지 직접 제공 +## 사용자 스토리지 사용 -`Session` 인터페이스를 구현하여 Redis, DynamoDB, SQLite 또는 다른 데이터스토어로 메모리를 지원하세요. 필요한 비동기 메서드는 5개뿐입니다. +`Session` 인터페이스를 구현하여 Redis, DynamoDB, SQLite 또는 다른 데이터스토어로 메모리를 지원하세요. 필요한 것은 비동기 메서드 다섯 개뿐입니다. -커스텀 세션을 사용하면 보존 정책을 강제하거나, 암호화를 추가하거나, 영구 저장 전에 각 대화 턴에 메타데이터를 첨부할 수 있습니다. +커스텀 세션을 사용하면 보존 정책을 강제하고, 암호화를 추가하거나, 지속 저장 전에 각 대화 턴에 메타데이터를 첨부할 수 있습니다. --- -## 히스토리와 신규 항목의 병합 제어 +## 히스토리와 신규 항목 병합 제어 -실행 입력으로 `AgentInputItem` 배열을 전달하는 경우, `sessionInputCallback`을 제공하여 저장된 히스토리와 결정론적으로 병합하세요. 러너는 기존 히스토리를 로드하고, **모델 호출 전에** 콜백을 호출하며, 반환된 배열을 해당 턴의 완전한 입력으로 모델에 전달합니다. 이 훅은 오래된 항목을 잘라내거나, 도구 결과의 중복을 제거하거나, 모델이 보길 원하는 컨텍스트만 강조하는 데 이상적입니다. +실행 입력으로 `AgentInputItem` 배열을 전달할 때, 저장된 히스토리와 결정적으로 병합하려면 `sessionInputCallback`을 제공하세요. 러너는 기존 히스토리를 로드하고, **모델 호출 전에** 콜백을 호출한 뒤, 반환된 배열을 해당 턴의 완전한 입력으로 모델에 전달합니다. 이 훅은 오래된 항목을 잘라내거나, 도구 결과의 중복을 제거하거나, 모델이 보길 원하는 컨텍스트만 강조하는 데 적합합니다. -문자열 입력의 경우 러너가 히스토리를 자동으로 병합하므로 콜백은 선택 사항입니다. +문자열 입력의 경우 러너가 히스토리를 자동 병합하므로 콜백은 선택 사항입니다. --- @@ -103,4 +99,4 @@ if (result.requiresApproval) { } ``` -이전 `RunState`에서 재개하면, 단일 대화 히스토리를 보존하기 위해 새로운 턴이 같은 메모리 레코드에 추가됩니다. 휴먼인더루프 (HITL) 플로우는 완전히 호환되며, 승인 체크포인트는 계속 `RunState`를 통해 왕복되는 동안 세션은 전체 대화 기록을 유지합니다. +이전 `RunState`에서 재개할 때, 단일 대화 히스토리를 보존하기 위해 새 턴이 동일한 메모리 레코드에 추가됩니다. 휴먼인더루프 (HITL) 플로우는 완전히 호환되며—승인 체크포인트는 계속 `RunState`를 통해 왕복되고, 세션은 전체 대화 기록을 유지합니다. diff --git a/docs/src/content/docs/ko/guides/streaming.mdx b/docs/src/content/docs/ko/guides/streaming.mdx index 438af5c9..a9b98f73 100644 --- a/docs/src/content/docs/ko/guides/streaming.mdx +++ b/docs/src/content/docs/ko/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` 인터페이스를 구현합니다. 각 방출된 이벤트는 실행 내에서 발생한 일을 설명하는 객체입니다. 스트림은 에이전트 실행의 서로 다른 부분을 설명하는 세 가지 이벤트 유형 중 하나를 제공합니다. 대부분의 애플리케이션은 모델의 텍스트만 원하므로 스트림은 이를 위한 헬퍼를 제공합니다. +스트리밍이 활성화되면 반환된 `stream`은 `AsyncIterable` 인터페이스를 구현합니다. 각 전달된 이벤트는 실행 중에 일어난 일을 설명하는 객체입니다. 스트림은 에이전트 실행의 서로 다른 부분을 설명하는 세 가지 이벤트 유형 중 하나를 방출합니다. 대부분의 애플리케이션은 모델의 텍스트만 필요하므로, 스트림은 이를 위한 헬퍼를 제공합니다. -### 텍스트 출력 +### 텍스트 출력 가져오기 -`stream.toTextStream()`을 호출해 방출된 텍스트의 스트림을 얻습니다. `compatibleWithNodeStreams`가 `true`인 경우 반환값은 표준 Node.js `Readable`입니다. `process.stdout` 또는 다른 대상에 직접 파이프할 수 있습니다. +`stream.toTextStream()`을 호출하여 방출된 텍스트의 스트림을 얻습니다. `compatibleWithNodeStreams`가 `true`이면 반환값은 일반 Node.js `Readable`입니다. 이를 `process.stdout` 또는 다른 대상으로 바로 파이프할 수 있습니다. -프로미스 `stream.completed`는 실행과 모든 보류 중인 콜백이 완료되면 resolve됩니다. 더 이상 출력이 없음을 보장하려면 항상 이를 기다리세요. +프로미스 `stream.completed`는 실행과 보류 중인 모든 콜백이 완료되면 resolve됩니다. 더 이상 출력이 없음을 보장하려면 항상 이를 await 하세요. ### 모든 이벤트 수신 -`for await` 루프를 사용해 이벤트가 도착할 때마다 검사할 수 있습니다. 유용한 정보에는 로우 레벨 모델 이벤트, 에이전트 전환, 그리고 SDK 고유의 실행 정보가 포함됩니다: +`for await` 루프를 사용하여 도착하는 각 이벤트를 검사할 수 있습니다. 유용한 정보에는 저수준 모델 이벤트, 에이전트 전환, 그리고 SDK 특정 실행 정보가 포함됩니다: -[스트리밍 code examples](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)를 참조하면 순수 텍스트 스트림과 원문 이벤트 스트림을 모두 출력하는 완전한 스크립트를 볼 수 있습니다. ## 이벤트 유형 @@ -120,7 +120,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)입니다. ## 팁 -- 모든 출력이 플러시되었는지 보장하려면 종료 전에 `stream.completed`를 반드시 기다리세요 -- 초기 `{ stream: true }` 옵션은 제공된 그 호출에만 적용됩니다. `RunState`로 재실행하는 경우 옵션을 다시 지정해야 합니다 -- 애플리케이션이 텍스트 결과에만 관심이 있다면 개별 이벤트 객체를 다루지 않도록 `toTextStream()`을 사용하세요 +- 모든 출력이 플러시되었음을 보장하려면 종료 전에 `stream.completed`를 기다리세요 +- 초기 `{ 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 8a3f7e5e..95941050 100644 --- a/docs/src/content/docs/ko/guides/tools.mdx +++ b/docs/src/content/docs/ko/guides/tools.mdx @@ -10,81 +10,85 @@ 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. **함수 도구** – 로컬 함수를 JSON 스키마로 감싸 LLM이 호출할 수 있게 합니다. -3. **에이전트를 도구로** – 전체 에이전트를 호출 가능한 도구로 노출합니다. -4. **로컬 MCP 서버** – 로컬에서 실행되는 Model context protocol 서버를 연결합니다. +1. **호스티드 툴** – OpenAI 서버에서 모델과 함께 실행됨 _(웹 검색, 파일 검색, 컴퓨터 사용, Code Interpreter, 이미지 생성)_ +2. **함수 도구** – 모든 로컬 함수를 JSON 스키마로 감싸 LLM이 호출할 수 있게 함 +3. **도구로서의 에이전트** – 전체 에이전트를 호출 가능한 도구로 노출 +4. **로컬 MCP 서버** – 로컬에서 실행되는 Model Context Protocol 서버를 연결 --- ## 1. 호스티드 툴 -`OpenAIResponsesModel`을 사용할 때 다음 기본 제공 도구를 추가할 수 있습니다: +`OpenAIResponsesModel`을 사용할 때 다음과 같은 내장 도구를 추가할 수 있습니다: -| Tool | Type string | Purpose | -| ----------------------- | -------------------- | -------------------------------------- | -| Web search | `'web_search'` | 인터넷 검색 | -| File / retrieval search | `'file_search'` | OpenAI에서 호스팅되는 벡터 스토어 쿼리 | -| Computer use | `'computer'` | GUI 상호작용 자동화 | -| Shell | `'shell'` | 호스트에서 셸 명령 실행 | -| Apply patch | `'apply_patch'` | 로컬 파일에 V4A diff 적용 | -| Code Interpreter | `'code_interpreter'` | 샌드박스 환경에서 코드 실행 | -| Image generation | `'image_generation'` | 텍스트 기반 이미지 생성 | +| Tool | Type string | Purpose | +| ----------------------- | -------------------- | ------------------------------------ | +| Web search | `'web_search'` | Internet search | +| File / retrieval search | `'file_search'` | Query vector stores hosted on OpenAI | +| Computer use | `'computer'` | Automate GUI interactions | +| Shell | `'shell'` | Run shell commands on the host | +| Apply patch | `'apply_patch'` | Apply V4A diffs to local files | +| Code Interpreter | `'code_interpreter'` | Run code in a sandboxed environment | +| Image generation | `'image_generation'` | Generate images based on text | - + -정확한 매개변수 세트는 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 parameters를 사용하면 자동으로 **strict** 모드가 활성화됩니다 | -| `strict` | No | `true`(기본값)일 때, 인수가 검증에 실패하면 SDK가 모델 오류를 반환합니다. 퍼지 매칭이 필요하면 `false`로 설정하세요 | -| `execute` | Yes | `(args, context) => string \| Promise`– 비즈니스 로직. 두 번째 선택적 매개변수는 `RunContext`입니다 | -| `errorFunction` | No | 내부 오류를 사용자에게 보이는 문자열로 변환하는 커스텀 핸들러 `(context, error) => string` | +| 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` | -### 비‑strict JSON‑스키마 도구 +### 비‑strict JSON 스키마 도구 -유효하지 않거나 일부만 제공된 입력을 모델이 추론하도록 하려면 원문 JSON 스키마를 사용할 때 strict 모드를 비활성화할 수 있습니다: +모델이 유효하지 않거나 부분적인 입력을 추정하도록 하려면 원문 JSON 스키마를 사용할 때 strict 모드를 비활성화할 수 있습니다: --- -## 3. 에이전트를 도구로 +## 3. 도구로서의 에이전트 -대화를 완전히 핸드오프하지 않고 한 에이전트가 다른 에이전트를 *보조*하도록 하고 싶을 때 `agent.asTool()`을 사용하세요: +대화를 완전히 핸드오프하지 않고 한 에이전트가 다른 에이전트를 보조하도록 하고 싶을 때가 있습니다. `agent.asTool()`을 사용하세요: - + 내부적으로 SDK는 다음을 수행합니다: -- 단일 `input` 매개변수를 갖는 함수 도구를 생성 -- 도구가 호출되면 해당 입력으로 서브 에이전트를 실행 -- 마지막 메시지 또는 `customOutputExtractor`가 추출한 결과를 반환 +- 단일 `input` 매개변수를 가진 함수 도구를 생성 +- 도구가 호출되면 해당 입력으로 하위 에이전트를 실행 +- 마지막 메시지 또는 `customOutputExtractor`가 추출한 출력을 반환 -에이전트를 도구로 실행하면, Agents SDK는 기본 설정으로 runner를 생성하고 함수 실행 컨텍스트 내에서 해당 runner로 에이전트를 실행합니다. `runConfig` 또는 `runOptions`의 속성을 제공하려면 `asTool()` 메서드에 전달하여 runner 동작을 커스터마이즈할 수 있습니다. +에이전트를 도구로 실행하면, Agents SDK는 기본 설정으로 러너를 생성하고 함수 실행 내에서 해당 러너로 에이전트를 실행합니다. `runConfig`나 `runOptions`의 속성을 제공하려면 `asTool()` 메서드에 전달하여 러너 동작을 사용자 지정할 수 있습니다. --- @@ -93,29 +97,29 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer [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)를 참조하세요. --- ## 도구 사용 동작 -모델이 도구를 언제, 어떻게 사용해야 하는지(`tool_choice`, `toolUseBehavior` 등) 제어하려면 [에이전트](/openai-agents-js/ko/guides/agents#forcing-tool-use)를 참고하세요. +모델이 도구를 언제 어떻게 사용해야 하는지(`tool_choice`, `toolUseBehavior` 등)를 제어하려면 [에이전트](/openai-agents-js/ko/guides/agents#forcing-tool-use)를 참조하세요. --- ## 모범 사례 -- **짧고 명확한 설명** – 도구가 _무엇을 하는지_ 그리고 *언제 사용하는지*를 설명하세요. -- **입력 검증** – 가능하면 Zod 스키마로 엄격한 JSON 검증을 수행하세요. -- **에러 핸들러에서 부작용 회피** – `errorFunction`은 유용한 문자열을 반환해야 하며, 예외를 던지지 마세요. -- **도구당 하나의 책임** – 작고 컴포저블한 도구가 더 나은 모델 추론으로 이어집니다. +- **짧고 명확한 설명** – 도구가 _무엇을_ 하는지와 *언제 사용하는지*를 설명 +- **입력 검증** – 가능한 경우 엄격한 JSON 검증을 위해 Zod 스키마 사용 +- **에러 핸들러에서 부작용 회피** – `errorFunction`은 예외를 던지지 말고 유용한 문자열을 반환 +- **도구당 하나의 책임** – 작고 조합 가능한 도구가 더 나은 모델 추론으로 이어짐 --- ## 다음 단계 -- [도구 사용 강제](/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 82421e86..15330db4 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)를 사용해 개발 및 프로덕션에서 워크플로를 디버그, 시각화, 모니터링할 수 있습니다. ## 내보내기 루프 라이프사이클 -대부분의 환경에서는 트레이스가 정기적으로 자동 내보내기됩니다. 브라우저 또는 Cloudflare Workers에서는 이 기능이 기본적으로 비활성화되어 있습니다. 너무 많은 트레이스가 대기열에 쌓이면 여전히 내보내기되지만, 정기적으로 내보내기되지는 않습니다. 대신 코드의 라이프사이클 내에서 `getGlobalTraceProvider().forceFlush()`를 사용해 트레이스를 수동으로 내보내야 합니다. +대부분의 환경에서는 트레이스가 정기적으로 자동 내보내기됩니다. 브라우저 또는 Cloudflare Workers에서는 이 기능이 기본적으로 비활성화됩니다. 대기열에 너무 많은 트레이스가 쌓이면 내보내기되지만, 정기적으로 내보내기되지는 않습니다. 대신 코드 라이프사이클의 일부로 `getGlobalTraceProvider().forceFlush()` 를 사용해 수동으로 트레이스를 내보내야 합니다. -예를 들어 Cloudflare Worker에서는 코드를 `try/catch/finally` 블록으로 감싸고 `waitUntil`과 함께 강제 플러시를 사용하여 워커가 종료되기 전에 트레이스가 내보내지도록 해야 합니다. +예를 들어, Cloudflare Worker에서는 코드를 `try/catch/finally` 블록으로 감싸고, 종료 전에 트레이스가 내보내지도록 `waitUntil` 과 함께 강제 플러시를 사용해야 합니다. `이어야 합니다 - - `group_id`: 동일한 대화에서 여러 트레이스를 연결하기 위한 선택적 그룹 ID입니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다 - - `disabled`: True인 경우 트레이스가 기록되지 않습니다 - - `metadata`: 트레이스에 대한 선택적 메타데이터입니다 -- **스팬(Spans)** 은 시작 및 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다: +- **트레이스(Traces)** 는 하나의 "워크플로"에 대한 단일 엔드 투 엔드 작업을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: + - `workflow_name`: 논리적 워크플로 또는 앱 이름입니다. 예: "Code generation", "Customer service" + - `trace_id`: 트레이스의 고유 ID. 전달하지 않으면 자동 생성됨. 형식은 `trace_<32_alphanumeric>` 이어야 함 + - `group_id`: 선택적 그룹 ID로, 동일한 대화의 여러 트레이스를 연결할 수 있음. 예: 채팅 스레드 ID + - `disabled`: True이면 트레이스가 기록되지 않음 + - `metadata`: 트레이스에 대한 선택적 메타데이터 +- **스팬(Spans)** 은 시작과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다: - `started_at` 및 `ended_at` 타임스탬프 - 속한 트레이스를 나타내는 `trace_id` - - 이 스팬의 상위 스팬(있는 경우)을 가리키는 `parent_id` - - 스팬에 대한 정보인 `span_data`. 예를 들어 `AgentSpanData`에는 에이전트에 대한 정보가, `GenerationSpanData`에는 LLM 생성에 대한 정보가 포함됩니다 + - 이 스팬의 부모 스팬을 가리키는 `parent_id`(있을 경우) + - 스팬에 대한 정보인 `span_data`. 예를 들어, `AgentSpanData` 는 에이전트에 관한 정보를, `GenerationSpanData` 는 LLM 생성에 관한 정보를 포함 ## 기본 트레이싱 기본적으로 SDK는 다음을 트레이싱합니다: -- 전체 `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)으로 이름과 기타 속성을 구성할 수 있습니다. +기본적으로 트레이스 이름은 "에이전트 워크플로"입니다. `withTrace` 를 사용해서 이 이름을 설정할 수 있으며, [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) 으로 이름 및 기타 속성을 구성할 수도 있습니다. -또한 [사용자 지정 트레이스 프로세서](#custom-tracing-processors)를 설정하여 트레이스를 다른 대상으로 전송할 수 있습니다(대체 또는 보조 대상으로). +또한 [사용자 지정 트레이싱 프로세서](#custom-tracing-processors)를 설정해 다른 대상으로 트레이스를 전송할 수 있습니다(대체 또는 보조 대상으로). ### 음성 에이전트 트레이싱 -기본 OpenAI Realtime API와 함께 `RealtimeAgent` 및 `RealtimeSession`을 사용하는 경우, `RealtimeSession`에서 `tracingDisabled: true`로 비활성화하거나 `OPENAI_AGENTS_DISABLE_TRACING` 환경 변수를 사용하지 않는 한, 트레이싱은 Realtime API 측에서 자동으로 수행됩니다. +기본 OpenAI Realtime API와 함께 `RealtimeAgent` 및 `RealtimeSession` 을 사용하는 경우, `RealtimeSession` 에서 `tracingDisabled: true` 로 비활성화하거나 `OPENAI_AGENTS_DISABLE_TRACING` 환경 변수를 사용하지 않는 한 트레이싱은 Realtime API 측에서 자동으로 수행됩니다. 자세한 내용은 [음성 에이전트 개요](/openai-agents-js/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) 또는 해당 환경의 폴리필을 통해 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다. ## 민감한 데이터 -특정 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다. +일부 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다. -`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/)에 전송합니다. 이 Exporter는 스팬과 트레이스를 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 백엔드에 스팬과 트레이스를 내보냅니다. -기본 설정을 사용자 지정하여 대체 또는 추가 백엔드로 트레이스를 전송하거나 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 3a466b2d..768baefd 100644 --- a/docs/src/content/docs/ko/guides/troubleshooting.mdx +++ b/docs/src/content/docs/ko/guides/troubleshooting.mdx @@ -5,7 +5,7 @@ description: Learn how to troubleshoot issues with the OpenAI Agents SDK. ## 지원 환경 -OpenAI Agents SDK는 다음 서버 환경을 지원합니다: +OpenAI Agents SDK는 다음 서버 환경에서 지원됩니다: - Node.js 22+ - Deno 2.35+ @@ -15,26 +15,26 @@ OpenAI Agents SDK는 다음 서버 환경을 지원합니다: - **Cloudflare Workers**: Agents SDK는 Cloudflare Workers에서 사용할 수 있지만, 현재 다음과 같은 제한이 있습니다: - SDK는 현재 `nodejs_compat` 활성화가 필요함 - - 요청 종료 시 트레이스를 수동으로 플러시해야 합니다. 자세한 내용은 [트레이싱 가이드](/openai-agents-js/ko/guides/tracing#export-loop-lifecycle)를 참조하세요. + - 요청 종료 시 트레이스를 수동으로 플러시해야 함. 자세한 내용은 [트레이싱](/openai-agents-js/ko/guides/tracing#export-loop-lifecycle)을 참고하세요 - Cloudflare Workers의 `AsyncLocalStorage` 제한적 지원으로 인해 일부 트레이스가 정확하지 않을 수 있음 - - 아웃바운드 WebSocket 연결은 전역 `WebSocket` 생성자가 아닌 fetch 기반 업그레이드를 사용해야 합니다. Realtime의 경우 `@openai/agents-extensions`의 Cloudflare 전송(`CloudflareRealtimeTransportLayer`)을 사용하세요. + - 아웃바운드 WebSocket 연결은 fetch 기반 업그레이드를 사용해야 함(전역 `WebSocket` 생성자 사용 불가). Realtime의 경우 `@openai/agents-extensions`의 Cloudflare 전송(`CloudflareRealtimeTransportLayer`)을 사용하세요 - **브라우저**: - - 브라우저에서는 현재 트레이싱이 지원되지 않음 + - 브라우저에서는 현재 트레이싱을 지원하지 않음 - **v8 isolates**: - - 적절한 브라우저 폴리필을 포함한 번들러를 사용하면 v8 isolates용으로 SDK를 번들링할 수 있지만, 트레이싱은 작동하지 않음 + - 적절한 브라우저 폴리필을 포함한 번들러를 사용하면 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 호출 diff --git a/docs/src/content/docs/ko/guides/voice-agents.mdx b/docs/src/content/docs/ko/guides/voice-agents.mdx index e05f6b69..8158db6d 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'; -![Realtime Agents](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) +![실시간 에이전트](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) -Voice Agents 는 OpenAI 음성-음성 모델을 사용해 실시간 음성 채팅을 제공합니다. 이들 모델은 오디오, 텍스트, 도구 호출의 스트리밍을 지원하며 음성/전화 고객 지원, 모바일 앱 경험, 음성 채팅과 같은 애플리케이션에 적합합니다. +음성 에이전트는 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 로 연결 +- WebSocket 또는 WebRTC 연결 - 브라우저와 백엔드 연결 모두에서 사용 가능 - 오디오 및 인터럽션(중단 처리) 처리 - 핸드오프를 통한 멀티 에이전트 오케스트레이션 - 도구 정의 및 호출 -- 모델 출력을 모니터링하는 커스텀 가드레일 -- 스트리밍 이벤트에 대한 콜백 -- 텍스트 및 음성 에이전트 모두에서 동일한 구성 요소 재사용 +- 모델 출력 모니터링을 위한 사용자 정의 가드레일 +- 스트리밍 이벤트용 콜백 +- 텍스트 및 음성 에이전트 모두에서 동일한 컴포넌트 재사용 -음성-음성 모델을 사용하면, 모델이 동작한 후 텍스트로 전사하고 다시 오디오로 변환하는 과정 없이 모델의 실시간 오디오 처리 능력을 활용할 수 있습니다. +음성-음성 모델을 사용하면, 모델이 동작한 후에 음성을 텍스트로 변환하고 다시 음성으로 변환할 필요 없이 오디오를 실시간으로 처리하는 모델의 능력을 활용할 수 있습니다. ![음성-음성 모델](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 36bde36d..00cf1ca2 100644 --- a/docs/src/content/docs/ko/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ko/guides/voice-agents/build.mdx @@ -30,75 +30,75 @@ 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)을 사용할 수 있습니다. +또한, 이는 핸드오프의 일부로 `voice` 또는 `model`을 변경할 수 없음을 의미합니다. 다른 Realtime Agents에만 연결할 수 있습니다. 다른 모델, 예를 들어 `gpt-5-mini`와 같은 추론 모델이 필요하다면 [도구를 통한 위임](#delegation-through-tools)을 사용할 수 있습니다. ## 도구 -일반 에이전트와 마찬가지로 실시간 에이전트는 작업을 수행하기 위해 도구를 호출할 수 있습니다. 일반 에이전트에서 사용하던 것과 동일한 `tool()` 함수를 사용하여 도구를 정의할 수 있습니다. +일반 에이전트와 마찬가지로 Realtime Agents는 동작을 수행하기 위해 도구를 호출할 수 있습니다. 일반 에이전트에서 사용하는 것과 동일한 `tool()` 함수를 사용하여 도구를 정의할 수 있습니다. -실시간 에이전트에서는 함수 도구만 사용할 수 있으며, 이 도구들은 실시간 세션과 동일한 위치에서 실행됩니다. 즉, 실시간 세션을 브라우저에서 실행 중이라면 도구도 브라우저에서 실행됩니다. 더 민감한 작업을 수행해야 한다면 도구 내부에서 백엔드 서버로 HTTP 요청을 보낼 수 있습니다. +Realtime Agents에서는 함수 도구만 사용할 수 있으며, 이 도구들은 Realtime Session이 실행되는 동일한 위치에서 실행됩니다. 즉, Realtime Session을 브라우저에서 실행 중이라면 도구도 브라우저에서 실행됩니다. 더 민감한 작업을 수행해야 한다면 도구 내부에서 백엔드 서버로 HTTP 요청을 보낼 수 있습니다. -도구가 실행되는 동안 에이전트는 사용자로부터 새로운 요청을 처리할 수 없습니다. 경험을 개선하는 한 가지 방법은 에이전트에게 도구를 실행하려고 할 때 이를 알리도록 하거나, 도구를 실행하는 시간을 벌기 위한 특정 문구를 말하도록 지시하는 것입니다. +도구가 실행되는 동안 에이전트는 사용자로부터 새로운 요청을 처리할 수 없습니다. 경험을 개선하는 한 가지 방법은 도구를 실행하려 할 때 이를 알리거나, 도구 실행 시간을 벌기 위해 특정 구절을 말하도록 에이전트에게 지시하는 것입니다. ### 대화 기록 접근 -에이전트가 특정 도구를 호출할 때 전달된 인자 외에도, 실시간 세션이 추적하는 현재 대화 기록의 스냅샷에 접근할 수 있습니다. 이는 현재 대화 상태를 기반으로 더 복잡한 작업을 수행해야 하거나 [도구를 통한 위임](#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` 객체를 전달할 수 있습니다. @@ -106,17 +106,17 @@ import turnDetectionExample from '../../../../../../../examples/docs/voice-agent ## 턴 감지 / 음성 활동 감지 -실시간 세션은 사용자가 말할 때를 자동으로 감지하고 [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 문서](https://platform.openai.com/docs/guides/realtime-vad)를 참고하세요. +턴 감지 설정을 수정하면 원치 않는 인터럽션(중단 처리)과 침묵 처리 보정에 도움이 됩니다. 다양한 설정에 대한 자세한 내용은 [Realtime API 문서](https://platform.openai.com/docs/guides/realtime-vad)를 확인하세요 ## 인터럽션(중단 처리) -내장 음성 활동 감지를 사용할 때, 사용자가 에이전트의 발화 중에 말하면 에이전트는 자동으로 이를 감지하고 말한 내용에 따라 컨텍스트를 업데이트합니다. 또한 `audio_interrupted` 이벤트를 발생시킵니다. 이는 모든 오디오 재생을 즉시 중지하는 데 사용할 수 있습니다(WebSocket 연결에만 적용). +내장 음성 활동 감지를 사용할 때, 사용자가 에이전트의 말 위로 말하면 자동으로 에이전트가 이를 감지하고 말한 내용에 따라 컨텍스트를 업데이트합니다. 또한 `audio_interrupted` 이벤트를 발생시킵니다. 이는 모든 오디오 재생을 즉시 중지하는 데 사용할 수 있습니다(웹소켓 연결에만 적용). @@ -124,15 +124,15 @@ import turnDetectionExample from '../../../../../../../examples/docs/voice-agent -어느 경우든, 실시간 세션은 에이전트의 생성 중단, 사용자에게 말한 내용에 대한 지식 절단, 기록 업데이트를 모두 처리합니다. +어느 쪽이든, Realtime Session은 에이전트의 생성 중단, 사용자에게 말한 내용의 지식 단절, 기록 업데이트를 모두 처리합니다. -WebRTC로 에이전트에 연결하는 경우 오디오 출력도 지워집니다. WebSocket을 사용하는 경우에는 재생 대기 중인 오디오의 재생을 중지하는 처리를 직접 구현해야 합니다. +WebRTC로 에이전트에 연결하는 경우 오디오 출력도 지워집니다. WebSocket을 사용하는 경우, 재생 대기열에 있는 오디오의 재생을 중지하는 처리는 직접 해야 합니다. ## 텍스트 입력 에이전트에 텍스트 입력을 보내려면 `RealtimeSession`의 `sendMessage` 메서드를 사용할 수 있습니다. -이는 사용자가 에이전트와 두 가지 모달리티로 상호작용하도록 하거나, 대화에 추가 컨텍스트를 제공하려는 경우 유용합니다. +이는 사용자가 에이전트와 두 가지 모달리티로 상호작용하도록 하거나 대화에 추가 컨텍스트를 제공하려는 경우에 유용합니다. @@ -140,7 +140,7 @@ WebRTC로 에이전트에 연결하는 경우 오디오 출력도 지워집니 `RealtimeSession`은 `history` 속성에서 대화 기록을 자동으로 관리합니다: -이를 사용해 고객에게 기록을 렌더링하거나 추가 작업을 수행할 수 있습니다. 대화가 진행되는 동안 이 기록은 지속적으로 변경되므로 `history_updated` 이벤트를 수신할 수 있습니다. +이를 사용하여 고객에게 기록을 렌더링하거나 추가 작업을 수행할 수 있습니다. 대화 중에는 이 기록이 지속적으로 변경되므로 `history_updated` 이벤트를 수신할 수 있습니다. 기록을 수정하고 싶다면, 예를 들어 메시지를 완전히 제거하거나 전사를 업데이트하려면 `updateHistory` 메서드를 사용할 수 있습니다. @@ -156,10 +156,10 @@ WebRTC로 에이전트에 연결하는 경우 오디오 출력도 지워집니 ![도구를 통한 위임](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/ko/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/ko/guides/voice-agents/quickstart.mdx index 34ee6a48..2cb6d4fc 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. **클라이언트 임시 토큰 생성** - 이 애플리케이션은 사용자의 브라우저에서 실행되므로 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. **첫 에이전트 만들기** +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'; @@ -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/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#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) + - [전송 메커니즘 직접 구축](/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 65caad61..52a5ab52 100644 --- a/docs/src/content/docs/ko/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/ko/guides/voice-agents/transport.mdx @@ -27,58 +27,58 @@ 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를 사용합니다. 마이크에서 오디오를 녹음하고 자동으로 재생합니다. -자체 미디어 스트림이나 오디오 요소를 사용하려면 세션을 생성할 때 `OpenAIRealtimeWebRTC` 인스턴스를 제공하세요. +자체 미디어 스트림 또는 오디오 요소를 사용하려면 세션을 생성할 때 `OpenAIRealtimeWebRTC` 인스턴스를 제공하세요. -### WebSocket을 통한 연결 +### WebSocket 연결 WebRTC 대신 WebSocket 연결을 사용하려면 세션을 생성할 때 `transport: 'websocket'` 또는 `OpenAIRealtimeWebSocket` 인스턴스를 전달하세요. 이는 예를 들어 Twilio로 전화 에이전트를 구축하는 등 서버 측 사용 사례에 적합합니다. -원문 PCM16 오디오 바이트를 처리하려면 임의의 녹음/재생 라이브러리를 사용하세요. +원시 PCM16 오디오 바이트 처리를 위해 임의의 녹음/재생 라이브러리를 사용하세요. -### SIP를 통한 연결 +### SIP 연결 -`OpenAIRealtimeSIP` 전송을 사용하여 Twilio와 같은 공급자의 SIP 전화를 브리지하세요. 이 전송은 통신 공급자가 내보내는 SIP 이벤트와 Realtime 세션의 동기화를 유지합니다. +`OpenAIRealtimeSIP` 전송을 사용하여 Twilio와 같은 제공업체의 SIP 통화를 브리지하세요. 이 전송은 통신사에서 발생하는 SIP 이벤트와 Realtime 세션을 동기화합니다. -1. `OpenAIRealtimeSIP.buildInitialConfig()`로 초기 세션 구성을 생성하여 걸려오는 전화를 수락합니다. 이를 통해 SIP 초대와 Realtime 세션이 동일한 기본값을 공유하도록 보장합니다 -2. `OpenAIRealtimeSIP` 전송을 사용하는 `RealtimeSession`을 연결하고, 공급자 웹훅에서 발급한 `callId`로 접속합니다 -3. 세션 이벤트를 수신하여 통화 분석, 전사, 에스컬레이션 로직을 구동합니다 +1. `OpenAIRealtimeSIP.buildInitialConfig()`로 초기 세션 구성을 생성해 수신 전화를 수락합니다. 이렇게 하면 SIP 초대와 Realtime 세션이 동일한 기본값을 공유합니다. +2. `OpenAIRealtimeSIP` 전송을 사용하는 `RealtimeSession`을 연결하고, 제공업체 웹훅에서 발급된 `callId`로 접속합니다. +3. 세션 이벤트를 수신해 콜 분석, 전사, 에스컬레이션 로직을 구동합니다. -#### Cloudflare Workers (workerd) 참고 사항 +#### 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에 더 직접적으로 접근하려면 두 가지 옵션이 있습니다. -### 옵션 1 - 전송 레이어 액세스 +### 옵션 1 - 전송 계층 접근 -`RealtimeSession`의 모든 기능을 그대로 활용하고 싶다면 `session.transport`를 통해 전송 레이어에 접근할 수 있습니다. +`RealtimeSession`의 모든 기능을 활용하면서도 전송 계층에 접근하려면 `session.transport`를 사용하세요. -전송 레이어는 수신하는 모든 이벤트를 `*` 이벤트로 내보내며, `sendEvent()` 메서드를 사용해 원문 이벤트를 전송할 수 있습니다. +전송 계층은 수신한 모든 이벤트를 `*` 이벤트로 내보내며, `sendEvent()` 메서드로 원시 이벤트를 전송할 수 있습니다. -### 옵션 2 — 전송 레이어만 사용 +### 옵션 2 — 전송 계층만 사용 -자동 도구 실행, 가드레일 등은 필요 없고 연결과 인터럽션(중단 처리)만 관리하는 "얇은" 클라이언트가 필요하다면 전송 레이어만 사용할 수도 있습니다. +자동 도구 실행, 가드레일 등이 필요 없다면, 연결 및 인터럽션(중단 처리)만 관리하는 "얇은" 클라이언트로 전송 계층을 사용할 수 있습니다. diff --git a/docs/src/content/docs/ko/index.mdx b/docs/src/content/docs/ko/index.mdx index a902f392..7f80a797 100644 --- a/docs/src/content/docs/ko/index.mdx +++ b/docs/src/content/docs/ko/index.mdx @@ -19,42 +19,37 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 개요 -[TypeScript용 OpenAI Agents SDK](https://github.com/openai/openai-agents-js)는 -아주 적은 추상화로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 -구축할 수 있게 해줍니다. 이는 이전 에이전트 실험인 -[Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션급 업그레이드이며, -[Python 버전](https://github.com/openai/openai-agents-python)도 제공됩니다. Agents SDK는 매우 -작은 기본 구성 요소 집합을 제공합니다: +[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js)는 +아주 적은 추상화로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있게 합니다. 이는 이전 +에이전트 실험작인 +[Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션급 업그레이드이며, [Python 버전](https://github.com/openai/openai-agents-python)도 제공합니다. Agents SDK는 아주 +작은 개수의 기본 구성 요소를 제공합니다: -- **Agents**: instructions와 tools를 갖춘 LLM -- **Handoffs**: 에이전트가 특정 작업을 다른 에이전트에 위임하도록 허용 -- **Guardrails**: 에이전트 입력을 검증할 수 있도록 지원 +- **에이전트**: instructions와 tools가 장착된 LLM +- **핸드오프**: 특정 작업에 대해 다른 에이전트에 위임할 수 있게 함 +- **가드레일**: 에이전트 입력을 검증할 수 있게 함 -TypeScript와 결합하면, 이 기본 구성 요소만으로도 tools와 에이전트 간의 -복잡한 관계를 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 -구축할 수 있습니다. 또한 SDK에는 에이전트의 흐름을 시각화하고 디버그할 수 -있도록 하는 기본 제공 **트레이싱**이 포함되어 있으며, 이를 평가하고 -애플리케이션에 맞게 모델을 파인튜닝할 수도 있습니다. +TypeScript와 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현하고, +가파른 학습 곡선 없이 실사용 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 +에이전트 플로우를 시각화하고 디버그할 수 있는 **트레이싱**이 내장되어 있으며, +이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝하는 데에도 활용할 수 있습니다. -## Agents SDK를 사용하는 이유 +## Agents SDK 사용 이유 -SDK의 핵심 설계 원칙은 두 가지입니다: +SDK는 두 가지 설계 원칙을 따릅니다: -1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 학습할 수 있도록 기본 구성 요소는 최소화 -2. 기본 설정만으로도 충분히 잘 동작하되, 내부 동작을 정확히 원하는 대로 커스터마이즈 가능 +1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 익힐 수 있도록 기본 구성 요소는 최소화 +2. 기본값만으로도 잘 작동하지만, 동작을 세밀하게 커스터마이즈 가능 SDK의 주요 기능은 다음과 같습니다: -- **Agent loop**: tools 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 루프를 - 처리하는 기본 제공 에이전트 루프 -- **TypeScript 우선**: 새로운 추상화 학습 없이, 내장 언어 기능으로 에이전트를 - 오케스트레이션하고 체이닝 -- **Handoffs**: 여러 에이전트 간의 조정과 위임을 위한 강력한 기능 -- **Guardrails**: 에이전트와 병렬로 입력 검증과 체크를 실행하고, 실패 시 조기 중단 -- **함수 도구**: 어떤 TypeScript 함수든 자동 스키마 생성과 Zod 기반 검증으로 tool로 전환 -- **트레이싱**: 워크플로를 시각화, 디버그, 모니터링하고 OpenAI의 평가, 파인튜닝, - 증류 도구를 사용할 수 있게 하는 기본 제공 트레이싱 -- **실시간 에이전트**: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등을 포함한 강력한 음성 에이전트 구축 +- **에이전트 루프**: 도구 호출, 결과를 LLM으로 전송, LLM이 종료될 때까지 루프를 처리하는 내장 루프 +- **TypeScript 우선**: 새로운 추상화를 배울 필요 없이 언어 기능만으로 에이전트를 오케스트레이션하고 체이닝 +- **핸드오프**: 여러 에이전트 간의 조정과 위임을 위한 강력한 기능 +- **가드레일**: 에이전트와 병렬로 입력 검증과 점검을 수행하고, 실패 시 조기 중단 +- **함수 도구**: 어떤 TypeScript 함수든 자동 스키마 생성과 Zod 기반 검증으로 도구로 변환 +- **트레이싱**: 워크플로를 시각화, 디버그, 모니터링하고 OpenAI의 평가, 파인튜닝, 디스틸레이션 도구를 활용 +- **실시간 에이전트**: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등 강력한 음성 에이전트 구축 ## 설치 @@ -66,7 +61,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 a5fab867..135433ef 100644 --- a/docs/src/content/docs/zh/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/zh/extensions/ai-sdk.mdx @@ -7,30 +7,29 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -开箱即用时，Agents SDK 通过 Responses API 或 Chat Completions API 与 OpenAI 模型配合工作。不过，如果您想使用其他模型，[Vercel 的 AI SDK](https://sdk.vercel.ai/) 提供了多种受支持的模型，可通过此适配器引入到 Agents SDK 中。 +Agents SDK 开箱即用地通过 Responses API 或 Chat Completions API 支持 OpenAI 模型。不过，如果你想使用其他模型，[Vercel 的 AI SDK](https://sdk.vercel.ai/) 提供了多种受支持的模型，可通过此适配器集成到 Agents SDK 中。 ## 设置 -1. 通过安装扩展包来安装 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,18 +46,18 @@ 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 3e7d0977..4327be10 100644 --- a/docs/src/content/docs/zh/extensions/cloudflare.mdx +++ b/docs/src/content/docs/zh/extensions/cloudflare.mdx @@ -6,12 +6,12 @@ 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 连接。为便于在这些环境中连接 实时智能体，扩展包提供了一个专用的传输适配器，在内部使用基于 `fetch()` 的升级方式。 +Cloudflare Workers 和其他 workerd 运行时无法使用全局的 `WebSocket` 构造函数发起出站 WebSocket 连接。为便于在这些环境中连接实时智能体（Realtime Agents），extensions 包提供了一个专用传输，在内部使用基于 `fetch()` 的升级。 @@ -19,17 +19,17 @@ Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构 -1. **安装扩展包。** +1. **安装 extensions 包。** ```bash npm install @openai/agents-extensions ``` -2. **创建传输适配器并将其附加到您的会话。** +2. **创建一个传输并将其附加到会话。** -3. **连接您的 `RealtimeSession`。** +3. **连接你的 `RealtimeSession`。** ```typescript await session.connect({ apiKey: 'your-openai-ephemeral-or-server-key' }); @@ -37,8 +37,8 @@ Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构 -## 注意事项 +## 说明 -- Cloudflare 传输适配器在底层使用带有 `Upgrade: websocket` 的 `fetch()`，并且跳过等待套接字的 `open` 事件，以匹配 workerd API。 -- 使用该传输适配器时，所有 `RealtimeSession` 功能（工具、护栏等）均可照常使用。 -- 在开发过程中使用 `DEBUG=openai-agents*` 查看详细日志。 +- Cloudflare 传输在底层使用带有 `Upgrade: websocket` 的 `fetch()`，并跳过等待套接字的 `open` 事件，这与 workerd API 保持一致。 +- 使用该传输时，所有 `RealtimeSession` 功能（工具、护栏等）均可照常工作。 +- 使用 `DEBUG=openai-agents*` 在开发期间查看详细日志。 diff --git a/docs/src/content/docs/zh/extensions/twilio.mdx b/docs/src/content/docs/zh/extensions/twilio.mdx index 8767212e..abeaeea3 100644 --- a/docs/src/content/docs/zh/extensions/twilio.mdx +++ b/docs/src/content/docs/zh/extensions/twilio.mdx @@ -7,19 +7,14 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio 提供了一个 [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。您可以使用 `websocket` 模式下的默认 Realtime Session 传输机制，将来自 Twilio 的事件连接到您的 Realtime Session。不过，这需要您设置正确的音频格式，并调整自己的打断时机，因为电话通话相比基于 Web 的对话会自然引入更多延迟。 -为提升设置体验，我们创建了一个专用传输层，为您处理与 Twilio 的连接， -包括中断处理和音频转发。 +为改进搭建体验，我们创建了一个专用的传输层，为您处理与 Twilio 的连接，包括中断处理和音频转发。 ## 设置 @@ -28,12 +23,11 @@ Twilio 提供了一个 [Media Streams API](https://www.twilio.com/docs/voice/med 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 适配器：** @@ -42,7 +36,7 @@ Twilio 提供了一个 [Media Streams API](https://www.twilio.com/docs/voice/med npm install @openai/agents-extensions ``` -4. **导入适配器和模型以连接到您的 `RealtimeSession`：** +4. **导入适配器和模型以连接您的 `RealtimeSession`：** -`RealtimeSession` 中您期望的任何事件和行为都将按预期工作， -包括工具调用、护栏等。阅读[语音智能体概述](/openai-agents-js/zh/guides/voice-agents) -以了解更多如何在语音智能体中使用 `RealtimeSession` 的信息。 +任何您期望从 `RealtimeSession` 获得的事件与行为（包括工具调用、护栏等）都将如预期工作。阅读[语音智能体概述](/openai-agents-js/zh/guides/voice-agents)了解如何将 `RealtimeSession` 与语音智能体搭配使用的更多信息。 ## 提示与注意事项 1. **速度至关重要。** - 为了接收来自 Twilio 的所有必要事件和音频，您应在拿到 WebSocket - 连接的引用后尽快创建 `TwilioRealtimeTransportLayer` 实例，并立即调用 `session.connect()`。 + 为了接收来自 Twilio 的所有必要事件与音频，您应在获得 WebSocket 连接引用后立刻创建 + `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 的所有调试日志。 - 或者，您也可以仅为 Twilio 适配器启用调试日志： - `DEBUG=openai-agents:extensions:twilio*`。 + 有时您可能会遇到需要更多信息来排查的问题。使用环境变量 `DEBUG=openai-agents*` 将显示来自 Agents SDK 的所有调试日志。或者，您也可以仅启用 Twilio 适配器的调试日志：`DEBUG=openai-agents:extensions:twilio*`。 ## 完整示例服务器 -下面是一个端到端的 WebSocket 服务器示例，用于接收来自 -Twilio 的请求并将其转发到 `RealtimeSession`。 +下面是一个端到端的 WebSocket 服务器示例，用于接收来自 Twilio 的请求并将其转发到 `RealtimeSession`。 + -本页其余部分将更详细地介绍每个 Agent 功能。 +本页余下内容将更详细地介绍每个智能体特性。 --- ## 基础配置 -`Agent` 构造函数接收一个配置对象。最常用的属性如下所示。 +`Agent` 构造函数只接收一个配置对象。最常用的属性如下所示。 -| 属性 | 必需 | 描述 | -| --------------- | ---- | ------------------------------------------------------------------------------------------ | -| `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 | 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`。上下文（_context_）是一个依赖注入对象，由你创建并传入 `Runner.run()`。它会被转发到每个工具、护栏、交接等，适合用于存储状态或提供共享服务（数据库连接、用户元数据、功能开关等）。 - + --- ## 输出类型 -默认情况下，Agent 返回**纯文本**（`string`）。如果希望模型返回结构化对象，可以指定 `outputType` 属性。SDK 接受： +默认情况下，智能体返回**纯文本**（`string`）。如果希望模型返回结构化对象，可以指定 `outputType` 属性。SDK 接受： -1. [Zod](https://github.com/colinhacks/zod) 模式（`z.object({...})`）。 -2. 任何兼容 JSON Schema 的对象。 +1. 一个 [Zod](https://github.com/colinhacks/zod) schema（`z.object({...})`）。 +2. 任意兼容 JSON Schema 的对象。 当提供了 `outputType` 时，SDK 会自动使用 @@ -71,24 +71,24 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## 多智能体系统设计模式 -组合智能体有多种方式。我们在生产应用中经常看到的两种模式是： +将多个智能体组合的方式很多。我们在生产应用中经常看到的两种模式是： -1. **管理者（智能体作为工具）**——一个中心智能体掌控对话，并调用作为工具暴露的专业智能体。 -2. **交接**——初始智能体在识别出用户请求后，将整个对话委派给某个专家智能体。 +1. **管理器（智能体即工具）**——一个中心智能体拥有会话并调用作为工具暴露的专业智能体。 +2. **交接**——初始智能体在识别出用户请求后，将整个会话交给某个专家智能体处理。 -这些方法是互补的。管理者让你可以在单处实施护栏或速率限制，而交接则让每个智能体专注于单一任务而无需保留对话控制权。 +这两种方法是互补的。管理器让你可以在单一位置实施护栏或速率限制，而交接则使每个智能体专注于单一任务而无需保留对会话的控制权。 -### 管理者（智能体作为工具） +### 管理器（智能体即工具） -在该模式下，管理者从不移交控制权——LLM 使用工具，管理者汇总最终答案。详情参见[工具](/openai-agents-js/zh/guides/tools#agents-as-tools)指南。 +在该模式中，管理器不会移交控制权——LLM 使用工具，而管理器汇总最终答案。详见[工具](/openai-agents-js/zh/guides/tools#agents-as-tools)。 - + ### 交接 -采用交接时，分诊智能体负责路由请求，但一旦发生交接，专家智能体就拥有对话控制权直到产生最终输出。这能保持提示简短，并让你独立地推理每个智能体。了解更多参见[交接](/openai-agents-js/zh/guides/handoffs)指南。 +通过交接，分诊智能体负责路由请求，但一旦发生交接，专家智能体将拥有会话的控制权，直到它产生最终输出。这能保持提示简短，并让你可以独立地推理每个智能体。了解更多请参见[交接](/openai-agents-js/zh/guides/handoffs)。 - + --- @@ -99,58 +99,58 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor -同步和 `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/zh/guides/guardrails)指南。 +护栏允许你验证或转换用户输入和智能体输出。通过 `inputGuardrails` 与 `outputGuardrails` 数组进行配置。详见[护栏](/openai-agents-js/zh/guides/guardrails)。 --- -## 智能体克隆/复制 +## 克隆/复制智能体 -需要现有智能体的稍作修改版本？使用 `clone()` 方法，它会返回一个全新的 `Agent` 实例。 +需要现有智能体的轻微变体？使用 `clone()` 方法，它会返回一个全新的 `Agent` 实例。 - + --- -## 强制工具使用 +## 强制使用工具 提供工具并不保证 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) => ...` —— 返回是否应结束运行的自定义函数。 +- `'stop_on_first_tool'`——将第一个工具结果视为最终答案。 +- `{ stopAtToolNames: ['my_tool'] }`——当调用到任一列出的工具时停止。 +- `(context, toolResults) => ...`——返回是否应结束运行的自定义函数。 ```typescript const agent = new Agent({ @@ -161,8 +161,8 @@ 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** 下浏览完整的 TypeDoc 参考。 diff --git a/docs/src/content/docs/zh/guides/config.mdx b/docs/src/content/docs/zh/guides/config.mdx index 4520917e..41fa4845 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 之间切换。 @@ -49,31 +49,31 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t -如果想进一步了解追踪功能，请查看[追踪](/openai-agents-js/zh/guides/tracing)。 +如需了解更多追踪功能，请查看[追踪](/openai-agents-js/zh/guides/tracing)。 ## 调试日志 -SDK 使用 [`debug`](https://www.npmjs.com/package/debug) 包进行调试日志记录。将环境变量 `DEBUG` 设置为 `openai-agents*` 以查看详细日志。 +SDK 使用 [`debug`](https://www.npmjs.com/package/debug) 包进行调试日志记录。将环境变量 `DEBUG` 设置为 `openai-agents*` 可查看详细日志。 ```bash export DEBUG=openai-agents* ``` -您可以使用来自 `@openai/agents` 的 `getLogger(namespace)` 为自己的模块获取带命名空间的记录器。 +您可以使用来自 `@openai/agents` 的 `getLogger(namespace)` 为自己的模块获取命名空间日志记录器。 - + ### 日志中的敏感数据 某些日志可能包含用户数据。可通过设置以下环境变量禁用。 -要禁用记录 LLM 的输入与输出： +要禁用记录 LLM 的输入和输出： ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -要禁用记录工具的输入与输出： +要禁用记录工具的输入和输出： ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/src/content/docs/zh/guides/context.mdx b/docs/src/content/docs/zh/guides/context.mdx index 1853585d..fd416fd3 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'; -“Context”一词含义较多。通常有两大类你需要关注的上下文： +“Context” 是一个含义很广的术语。你可能关心的上下文主要有两类： -1. 代码在一次运行期间可访问的**本地上下文**：工具所需的依赖或数据、如 `onHandoff` 的回调，以及生命周期钩子。 +1. 你的代码在一次运行期间可以访问的**本地上下文**：工具所需的依赖或数据、如 `onHandoff` 的回调，以及生命周期钩子。 2. 语言模型在生成响应时可见的**智能体/LLM 上下文**。 ## 本地上下文 -本地上下文由 `RunContext` 类型表示。你可以创建任意对象来保存状态或依赖，并将其传给 `Runner.run()`。所有工具调用和钩子都会收到一个 `RunContext` 包装，以便它们读取或修改该对象。 +本地上下文由 `RunContext` 类型表示。你可以创建任意对象来保存状态或依赖，并将它传递给 `Runner.run()`。所有工具调用和钩子都会接收一个 `RunContext` 包装器，以便读取或修改该对象。 -参与同一次运行的每个智能体、工具和钩子必须使用相同**类型**的上下文。 +参与同一次运行的每个智能体、工具和钩子都必须使用相同**类型**的上下文。 -本地上下文适用于： +将本地上下文用于以下场景： -- 有关运行的数据（用户名、ID 等） -- 依赖，如日志记录器或数据获取器 +- 有关本次运行的数据（用户名、ID 等） +- 依赖项，例如日志记录器或数据获取器 - 帮助函数 ## 智能体/LLM 上下文 -当调用 LLM 时，它只能看到会话历史。要让更多信息可见，你可以： +当调用 LLM 时，它唯一可见的数据来自对话历史。要提供额外信息，你可以： -1. 将其添加到智能体的 `instructions`（也称系统或开发者消息）。它可以是静态字符串，或一个接收上下文并返回字符串的函数。 -2. 在调用 `Runner.run()` 时将其包含在 `input` 中。此方式类似于 instructions，但允许你将消息放在[指挥链](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)的更低位置。 -3. 通过函数工具暴露，让 LLM 按需获取数据。 -4. 使用检索或 Web 搜索工具，将响应基于来自文件、数据库或网页的相关数据。 +1. 将信息添加到智能体的 `instructions`——也称为系统或开发者消息。它可以是静态字符串，或接收上下文并返回字符串的函数。 +2. 在调用 `Runner.run()` 时，将其包含在 `input` 中。这与 instructions 的方式类似，但允许你将消息放在[指令链](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)中更靠后的位置。 +3. 通过函数工具暴露信息，让 LLM 按需获取数据。 +4. 使用检索或 Web 搜索工具，使响应以来自文件、数据库或 Web 的相关数据为依据。 diff --git a/docs/src/content/docs/zh/guides/guardrails.mdx b/docs/src/content/docs/zh/guides/guardrails.mdx index 63d37213..7e0f3002 100644 --- a/docs/src/content/docs/zh/guides/guardrails.mdx +++ b/docs/src/content/docs/zh/guides/guardrails.mdx @@ -7,42 +7,47 @@ import { Code } from '@astrojs/starlight/components'; import inputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-input.ts?raw'; import outputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-output.ts?raw'; -护栏与您的智能体*并行*运行，允许您对用户输入或智能体输出进行检查和验证。比如，您可以在调用昂贵模型之前运行一个轻量模型作为护栏。如果护栏检测到恶意使用，它可以触发错误并阻止高成本模型运行。 +护栏可以与您的智能体并行运行，或在其完成前阻塞执行，从而对用户输入或智能体输出进行检查与校验。例如，您可以在调用昂贵模型前先运行一个轻量模型作为护栏。如果护栏检测到恶意使用，它可以触发错误并阻止昂贵模型运行。 -护栏分为两种： +护栏分为两类： 1. **输入护栏** 运行在初始用户输入上。 2. **输出护栏** 运行在最终智能体输出上。 ## 输入护栏 -输入护栏分三步执行： +输入护栏分三步运行： 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) 错误。 +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** +> 输入护栏面向用户输入，因此仅当该智能体是工作流中的第一个智能体时才会运行。护栏在智能体上进行配置，因为不同智能体通常需要不同的护栏。 + +### 执行模式 + +- `runInParallel: true`（默认）会在 LLM/工具调用的同时启动护栏。这样可最小化延迟，但如果护栏之后触发，模型可能已经消耗了 tokens 或运行了工具。 +- `runInParallel: false` 会在调用模型之前运行护栏，当护栏阻止请求时可避免 token 消耗与工具执行。当您更看重安全与成本而非延迟时使用此模式。 ## 输出护栏 -输出护栏分三步执行： +输出护栏分三步运行： 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) 错误。 +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) 错误。 -> **注意** -> 仅当该智能体是工作流中的*最后一个*智能体时才会运行输出护栏。关于实时语音交互，请参见[构建语音智能体](/openai-agents-js/zh/guides/voice-agents/build#guardrails)。 +> **Note** +> 仅当该智能体是工作流中的最后一个智能体时，输出护栏才会运行。有关实时语音交互，请参阅[构建语音智能体](/openai-agents-js/zh/guides/voice-agents/build#guardrails)。 -## 绊线 +## 触发线 -当护栏失败时，会通过绊线发出信号。一旦绊线被触发，runner 会抛出相应错误并停止执行。 +当护栏失败时，它会通过触发线发出信号。一旦触发线被触发，runner 会抛出相应错误并停止执行。 ## 护栏实现 -护栏就是一个返回 `GuardrailFunctionOutput` 的函数。下面是一个最小示例：它通过在后台运行另一个智能体来检查用户是否在请求数学作业帮助。 +护栏就是一个返回 `GuardrailFunctionOutput` 的函数。下面是一个最小示例：通过在幕后运行另一个智能体来检查用户是否在请求数学作业帮助。 @@ -50,7 +55,7 @@ import outputGuardrailExample from '../../../../../../examples/docs/guardrails/g -1. `guardrailAgent` 在护栏函数中使用。 -2. 护栏函数接收智能体的输入或输出并返回结果。 -3. 可在护栏结果中包含额外信息。 +1. `guardrailAgent` 在护栏函数内部使用。 +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 1ca7ec82..aed7932a 100644 --- a/docs/src/content/docs/zh/guides/handoffs.mdx +++ b/docs/src/content/docs/zh/guides/handoffs.mdx @@ -10,9 +10,9 @@ 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`。 ## 创建交接 @@ -20,44 +20,36 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r ### 基本用法 - + ### 通过 `handoff()` 自定义交接 -`handoff()` 函数允许你微调生成的工具。 +`handoff()` 函数允许您微调生成的工具。 - `agent` – 要交接到的智能体。 - `toolNameOverride` – 覆盖默认的 `transfer_to_` 工具名。 -- `toolDescriptionOverride` – 覆盖默认工具描述。 -- `onHandoff` – 发生交接时的回调。接收一个 `RunContext` 和可选的已解析输入。 -- `inputType` – 交接所期望的输入模式。 +- `toolDescriptionOverride` – 覆盖默认的工具描述。 +- `onHandoff` – 交接发生时的回调。接收一个 `RunContext`，以及可选的已解析输入。 +- `inputType` – 交接的期望输入模式。 - `inputFilter` – 过滤传递给下一个智能体的历史记录。 - + ## 交接输入 -有时你希望 LLM 在调用交接时提供数据。定义一个输入模式并在 `handoff()` 中使用它。 +有时您希望 LLM 在调用交接时提供数据。定义一个输入模式，并在 `handoff()` 中使用它。 - + ## 输入过滤器 默认情况下，交接会接收整个对话历史。要修改传递给下一个智能体的内容，请提供一个 `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 0a89d633..fb22dda6 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 内置的 Human in the loop 支持，在有人为干预时暂停并恢复智能体运行。 -目前的主要用例是在执行敏感工具调用前请求批准。 +当前的主要用例是对敏感工具执行请求审批。 ## 审批请求 -可以通过将 `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)以获得可运行的端到端版本。 ## 处理较长审批时间 -人工干预流程被设计为可中断较长时间，而无需保持你的服务器运行。如果你需要先终止请求并稍后继续，可以序列化状态，之后再恢复。 +Human in the loop 流程被设计为可在较长时间内中断，而无需持续运行你的服务器。如果你需要先结束请求并在之后继续，可以序列化 state 并稍后恢复。 -可以使用 `JSON.stringify(result.state)` 序列化状态，并在稍后通过将序列化后的状态传入 `RunState.fromString(agent, serializedState)` 来恢复，其中 `agent` 是触发整个运行的智能体实例。 +你可以使用 `JSON.stringify(result.state)` 序列化 state，并在之后通过将序列化的 state 传入 `RunState.fromString(agent, serializedState)` 来恢复，其中 `agent` 是触发整个运行的智能体实例。 -这样，你就可以将序列化状态存储到数据库中，或与请求一起存储。 +这样你就可以将序列化后的 state 存储到数据库，或与请求一同存储。 ### 挂起任务的版本管理 -如果你的审批请求需要较长时间，并且你打算以有意义的方式对智能体定义进行版本化或升级你的 Agents SDK 版本，目前我们建议你通过使用包别名并行安装两个版本的 Agents SDK，来实现你自己的分支逻辑。 +如果你的审批请求需要较长时间且你打算以有意义的方式对智能体定义进行版本化，或升级你的 Agents SDK 版本，我们目前建议你通过使用包别名并行安装两个版本的 Agents SDK，自行实现分支逻辑。 -实际做法是给你的代码分配一个版本号，将其与序列化状态一同存储，并在反序列化时引导到你代码的正确版本。 +实际做法是为你的代码分配一个版本号，并将其与序列化的 state 一起存储，同时在反序列化时引导到你代码的正确版本。 diff --git a/docs/src/content/docs/zh/guides/mcp.mdx b/docs/src/content/docs/zh/guides/mcp.mdx index a1e38b10..a90071bd 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) 是一种开放协议，用于标准化应用如何向 LLMs 提供工具和上下文。来自 MCP 文档： +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) 是一种开放协议，用于标准化应用如何向 LLM 提供工具与上下文。来自 MCP 文档： -> MCP 是一种开放协议，用于标准化应用如何向 LLMs 提供上下文。可以把 MCP 想象成面向 AI 应用的 USB‑C 接口。就像 USB‑C 为设备连接各种外设和配件提供了标准化方式一样，MCP 为 AI 模型连接不同数据源和工具提供了标准化方式。 +> MCP 是一种开放协议，用于标准化应用如何向 LLM 提供上下文。可以把 MCP 想象成 AI 应用的 USB‑C 接口。正如 USB‑C 为设备连接各种外设与配件提供了标准化方式，MCP 为将 AI 模型连接到不同数据源和工具提供了标准化方式。 本 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 服务器** – 通过标准输入/输出访问的服务器（最简单的选项） +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. 托管 MCP 工具** | -| 使用可公开访问的远程服务器，但在本地触发工具调用 | **2. Streamable HTTP** | -| 使用本地运行的 Streamable HTTP 服务器 | **2. Streamable HTTP** | -| 使用非 OpenAI‑Responses 模型调用任意 Streamable HTTP 服务器 | **2. Streamable HTTP** | -| 使用仅支持标准 I/O 协议的本地 MCP 服务器 | **3. Stdio** | +| 您的需求 | 推荐选项 | +| ----------------------------------------------------------- | ----------------------- | +| 使用默认的 OpenAI responses 模型调用可公开访问的远程服务器 | **1. Hosted MCP tools** | +| 使用可公开访问的远程服务器，但在本地触发工具调用 | **2. Streamable HTTP** | +| 使用本地运行的 Streamable HTTP 服务器 | **2. Streamable HTTP** | +| 在非 OpenAI‑Responses 模型中使用任意 Streamable HTTP 服务器 | **2. Streamable HTTP** | +| 使用仅支持标准 I/O 协议的本地 MCP 服务器 | **3. Stdio** | -## 1. 托管 MCP 服务器工具 +## 1. Hosted MCP server tools -托管工具将整个往返流程置于模型内部。不是由您的代码调用 MCP 服务器，而是由 OpenAI Responses API 调用远程工具端点，并将结果流式传回模型。 +托管工具将整个往返交互推送进模型中。不是由您的代码调用 MCP 服务器，而是由 OpenAI Responses API 调用远程工具端点并将结果流式返回给模型。 -以下是使用托管 MCP 工具的最简单示例。您可以将远程 MCP 服务器的标签和 URL 传递给 `hostedMcpTool` 实用函数，便于创建托管 MCP 服务器工具。 +下面是使用托管 MCP 工具的最简例子。您可以将远程 MCP 服务器的标签与 URL 传递给 `hostedMcpTool` 工具函数，用于创建托管 MCP 服务器工具。 -然后，您可以使用 `run` 函数（或您自定义的 `Runner` 实例的 `run` 方法）运行该 Agent： +然后，使用 `run` 函数（或您自定义的 `Runner` 实例的 `run` 方法）运行该 Agent： -若要流式传输增量 MCP 结果，在运行 `Agent` 时传入 `stream: true`： +如需流式接收增量 MCP 结果，运行 `Agent` 时传入 `stream: true`： -在此示例中，`GOOGLE_CALENDAR_AUTHORIZATION` 环境变量保存了从 Google OAuth Playground 获取的 OAuth 令牌，它授权由 connector 支持的服务器调用 Calendar API。有关还演示流式传输的可运行示例，请参见 [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors)。 +在此示例中，环境变量 `GOOGLE_CALENDAR_AUTHORIZATION` 保存了从 Google OAuth Playground 获取的 OAuth 令牌，用于授权由 connector 支持的服务器调用 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 服务器 +## 2. Streamable HTTP MCP servers -当您的 Agent 直接与本地或远程的 Streamable HTTP MCP 服务器通信时，请使用服务器的 `url`、`name` 以及可选设置实例化 `MCPServerStreamableHttp`： +当您的 Agent 直接与 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 服务器 +## 3. Stdio MCP servers -对于仅通过标准 I/O 暴露的服务器，请使用 `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) – 上文提到的可运行演示。 +- [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 ca6ce8e3..e8a392ee 100644 --- a/docs/src/content/docs/zh/guides/models.mdx +++ b/docs/src/content/docs/zh/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'; -每个 Agent 最终都会调用一个 LLM。SDK 通过两个轻量接口抽象了模型： +每个智能体最终都会调用一个 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 提供方 -默认的 `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')`（默认） | ### 身份验证 @@ -88,62 +88,62 @@ node my-awesome-agent.js ## ModelSettings -`ModelSettings` 与 OpenAI 的参数相对应，但与提供方无关。 +`ModelSettings` 与 OpenAI 的参数相对应，但与具体提供方无关。 | 字段 | 类型 | 说明 | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------- | | `temperature` | `number` | 创造性与确定性的权衡。 | | `topP` | `number` | 核采样。 | -| `frequencyPenalty` | `number` | 惩罚重复的 token。 | -| `presencePenalty` | `number` | 鼓励引入新 token。 | +| `frequencyPenalty` | `number` | 惩罚重复 token。 | +| `presencePenalty` | `number` | 鼓励生成新的 token。 | | `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 工作流。 | -| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | 适用于 gpt-5 等的推理强度。 | -| `text.verbosity` | `'low' \| 'medium' \| 'high'` | 适用于 gpt-5 等的文本详尽程度。 | +| `store` | `boolean` | 持久化响应以便检索 / RAG 工作流。 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 等模型的推理强度。 | +| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 等模型的文本详尽度。 | -在任一层级附加设置： +可在任一层级附加设置： -`Runner` 级别的设置会覆盖任何冲突的每个智能体级别设置。 +`Runner` 级别的设置会覆盖任何与其冲突的按智能体设置。 --- -## Prompt +## 提示 -可以通过 `prompt` 参数为智能体进行配置，指向一个存储在服务器上的 prompt 配置，用于控制智能体行为。目前，此选项仅在你使用 OpenAI 的 +可以通过 `prompt` 参数为智能体进行配置，指明应使用的服务器存储提示配置来控制智能体行为。目前，此选项仅在你使用 OpenAI 的 [Responses API](https://platform.openai.com/docs/api-reference/responses) 时受支持。 -| 字段 | 类型 | 说明 | -| ----------- | -------- | ------------------------------------------------------------------------------------- | -| `promptId` | `string` | prompt 的唯一标识符。 | -| `version` | `string` | 你希望使用的 prompt 版本。 | -| `variables` | `object` | 传入到 prompt 中的键/值变量对。值可以是字符串，或诸如文本、图像、文件等内容输入类型。 | +| 字段 | 类型 | 说明 | +| ----------- | -------- | --------------------------------------------------------------------------- | +| `promptId` | `string` | 提示的唯一标识符。 | +| `version` | `string` | 你希望使用的提示版本。 | +| `variables` | `object` | 代入提示中的键/值变量对。取值可以是字符串或文本、图像、文件等内容输入类型。 | - + -任何额外的智能体配置（如 tools 或 instructions）都会覆盖你在存储的 prompt 中配置的值。 +任何其他智能体配置（如 tools 或 instructions）都会覆盖你在存储提示中可能配置的值。 --- ## 自定义模型提供方 -实现你自己的提供方非常简单——实现 `ModelProvider` 和 `Model`，然后将该提供方传给 `Runner` 构造函数： +实现你自己的提供方很简单——实现 `ModelProvider` 和 `Model`，并将该提供方传给 `Runner` 构造函数： --- ## 追踪导出器 -当使用 OpenAI 提供方时，你可以通过提供 API 密钥选择加入自动追踪导出： +当使用 OpenAI 提供方时，你可以通过提供 API 密钥来选择启用自动追踪导出： -这会将追踪发送到 [OpenAI dashboard](https://platform.openai.com/traces)，你可以在其中检查工作流的完整执行图。 +这会将追踪发送到 [OpenAI 仪表盘](https://platform.openai.com/traces)，你可以在其中检查工作流的完整执行图。 --- ## 后续步骤 - 探索[运行智能体](/openai-agents-js/zh/guides/running-agents)。 -- 借助[工具](/openai-agents-js/zh/guides/tools)为你的模型赋能。 +- 使用[工具](/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 6161b0f9..013cb146 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 的编排 -一个智能体是配备了 instructions、工具和交接 的 LLM。这意味着面对开放式任务时，LLM 可以自主规划如何完成任务，使用工具执行操作和获取数据，并通过交接把子任务委派给子智能体。例如，一个研究智能体可以配备以下工具： +一个智能体是一个配备了指令、工具和交接的 LLM。这意味着在面对开放式任务时，LLM 能自主规划如何处理任务，使用工具来执行动作和获取数据，并使用交接将任务委派给子智能体。比如，一个研究智能体可以配备如下工具： -- Web 搜索，用于在线查找信息 -- 文件搜索与检索，用于检索专有数据和连接 -- 计算机操作，用于在计算机上执行操作 -- 代码执行，用于进行数据分析 -- 交接，指向擅长规划、写报告等的专业智能体 +- Web 搜索以在线查找信息 +- 文件搜索与检索以查询专有数据和连接 +- 计算机操作以在电脑上执行动作 +- 代码执行以进行数据分析 +- 交接至擅长规划、写报告等工作的专门智能体 -当任务是开放式且你希望依赖 LLM 的智能时，这种模式非常适合。关键策略包括： +当任务是开放式且你希望依赖 LLM 的智能时，这种模式非常合适。这里最重要的做法是： -1. 投入精力打磨提示词。明确可用的工具、如何使用它们，以及必须遵守的参数。 -2. 监控你的应用并持续迭代。观察问题发生在哪里，并迭代优化提示词。 -3. 允许智能体自省并改进。例如，将其置于循环中，让它自我批评；或提供错误信息并让其改进。 -4. 使用专注于单一任务的专业智能体，而不是期待一个通用智能体对所有事情都很擅长。 -5. 投入于[evals](https://platform.openai.com/docs/guides/evals)。这能帮助你让智能体不断改进并提升任务表现。 +1. 打造优质提示词。明确可用的工具、如何使用它们，以及必须遵循的参数边界。 +2. 监控应用并迭代优化。找出问题发生的地方，并迭代你的提示词。 +3. 允许智能体自省与改进。例如在循环中运行，让其自我批评；或提供错误信息并让其改进。 +4. 使用在单一任务上表现卓越的专门智能体，而不是期望一个通用智能体样样精通。 +5. 投入于[评测（evals）](https://platform.openai.com/docs/guides/evals)。这能帮助你训练智能体以改进并更擅长完成任务。 ## 通过代码的编排 -虽然通过 LLM 编排很强大，但通过代码编排在速度、成本和性能方面更具确定性和可预测性。常见模式包括： +虽然通过 LLM 的编排很强大，但通过代码进行编排能在速度、成本和性能方面使任务更具确定性和可预测性。常见模式包括： -- 使用[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)生成可由代码检查的格式良好的数据。例如，你可以让一个智能体将任务归类到若干类别中，然后基于该类别选择下一个智能体。 -- 将多个智能体串联起来，把一个的输出转换为下一个的输入。你可以把写博客这种任务分解为一系列步骤——做研究、写大纲、撰写正文、批评审阅、再改进。 -- 让执行任务的智能体与负责评估和反馈的智能体在`while`循环中运行，直到评估者认为输出满足特定标准为止。 -- 并行运行多个智能体，例如通过 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)中提供了若干代码示例。 diff --git a/docs/src/content/docs/zh/guides/quickstart.mdx b/docs/src/content/docs/zh/guides/quickstart.mdx index f68ebca9..b0428c1a 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 密钥。若尚未拥有，请按照[这些说明](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/zh/guides/config)以了解更多详情。 + 或者，您可以调用 `setDefaultOpenAIKey('')` 以编程方式设置密钥，并使用 `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,11 +131,11 @@ const triageAgent = Agent.create({ }); ``` -在运行结束后，您可以通过查看结果上的 `finalAgent` 属性来了解是哪一个智能体生成了最终响应。 +运行结束后，您可以通过查看运行结果上的 `finalAgent` 属性来了解哪个智能体生成了最终响应。 ## 运行智能体编排 -Runner 负责处理各个智能体的执行、可能的交接以及工具执行。 +Runner 负责处理各个智能体的执行、潜在的交接以及工具调用。 ```typescript import { run } from '@openai/agents'; @@ -148,18 +148,18 @@ async function main() { main().catch((err) => console.error(err)); ``` -## 集成 +## 整合到一起 -让我们把以上内容整合成一个完整示例。将其放入您的 `index.js` 文件并运行。 +让我们将以上内容整合为一个完整示例。将其放入 `index.js` 文件并运行。 - + ## 查看追踪 -Agents SDK 会自动为您生成追踪。这使您可以审查智能体的运行情况、调用了哪些工具或交接给了哪个智能体。 +Agents SDK 将自动为您生成追踪。这使您能够审查智能体的运行方式、调用了哪些工具，或交接给了哪个智能体。 -要查看智能体运行期间发生的情况，请前往 -[OpenAI 仪表板中的 Trace 查看器](https://platform.openai.com/traces)。 +要查看一次智能体运行期间发生的情况，请前往 +[OpenAI Dashboard 中的 Trace 查看器](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 368b3b5a..673cfd07 100644 --- a/docs/src/content/docs/zh/guides/release.mdx +++ b/docs/src/content/docs/zh/guides/release.mdx @@ -5,30 +5,30 @@ description: Learn how we version and release the SDK and recent changes. ## 版本管理 -本项目遵循一种略微修改的语义化版本规则，形式为 `0.Y.Z`。前导的 `0` 表示 SDK 仍在快速演进中。各组件的递增规则如下： +本项目遵循稍作修改的语义化版本管理，形式为 `0.Y.Z`。前导的 `0` 表示 SDK 仍在快速演进。各组成部分的递增规则如下： -## 次版本（`Y`） +## 次版本号（`Y`） -对于未标注为 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 功能的更新 +- 私有接口的变更 +- 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 6227762e..57a534cb 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`，则为 [`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)。 ## 最终输出 `finalOutput` 属性包含最后一个运行的智能体的最终输出。该结果可能是： -- `string` — 默认用于未定义 `outputType` 的任何智能体 -- `unknown` — 如果智能体将 JSON schema 定义为输出类型。在这种情况下，JSON 已解析，但你仍需手动验证其类型。 -- `z.infer` — 如果智能体将 Zod schema 定义为输出类型。输出会自动按该 schema 进行解析。 -- `undefined` — 如果智能体未产生输出（例如在产生输出前就停止） +- `string` — 对于未定义 `outputType` 的任意智能体的默认类型 +- `unknown` — 如果智能体将 JSON 模式定义为输出类型。在这种情况下 JSON 已解析，但仍需您手动验证其类型。 +- `z.infer` — 如果智能体将 Zod 模式定义为输出类型。输出将自动按此模式进行解析。 +- `undefined` — 如果智能体未产生输出（例如在产生输出之前被停止） -如果你在使用具有不同输出类型的交接，应该使用 `Agent.create()` 方法而不是 `new Agent()` 构造函数来创建智能体。 +如果您使用具有不同输出类型的交接，建议使用 `Agent.create()` 方法而不是 `new Agent()` 构造函数来创建智能体。 这将使 SDK 能够在所有可能的交接中推断输出类型，并为 `finalOutput` 属性提供联合类型。 @@ -30,60 +30,60 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? -## 下一轮的输入 +## 下一轮输入 -你可以通过两种方式获取下一轮的输入： +有两种方式获取下一轮所需的输入： -- `result.history` — 包含你的输入以及智能体输出的副本。 +- `result.history` — 包含您输入和智能体输出的副本。 - `result.output` — 包含整个智能体运行的输出。 在类似聊天的用例中，`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) 表示发生了交接。原始条目是对交接工具调用的工具响应。你还可以从条目中访问源/目标智能体。 +- [`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 的推理条目。原始条目是生成的推理内容。 +- [`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)或处理[`interruption`](#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 -`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 520ff988..0b02db8d 100644 --- a/docs/src/content/docs/zh/guides/running-agents.mdx +++ b/docs/src/content/docs/zh/guides/running-agents.mdx @@ -11,129 +11,137 @@ 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 响应。 - **最终输出** → 返回。 - - **交接** → 切换到新智能体，保留累积的对话历史，回到步骤 1。 - - **工具调用** → 执行工具，将其结果追加到对话中，回到步骤 1。 + - **交接** → 切换到新智能体，保留累积的对话历史，转到 1。 + - **工具调用** → 执行工具，将其结果追加到对话中，转到 1。 3. 一旦达到 `maxTurns`，抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 ### Runner 生命周期 -在应用启动时创建一个 `Runner` 并在请求间复用。该实例存储全局配置，如模型提供方和追踪选项。只有在需要完全不同的设置时才创建另一个 `Runner`。对于简单脚本，您也可以直接调用 `run()`，它会在内部使用默认 runner。 +在应用启动时创建一个 `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) 对象。 其他选项包括： -| 选项 | 默认值 | 说明 | +| 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)。 | +| `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`。 | ## 流式传输 -流式传输允许您在 LLM 运行时接收额外的流式事件。一旦流开始，`StreamedRunResult` 将包含关于本次运行的完整信息，包括所有新产生的输出。您可以使用 `for await` 循环迭代这些流式事件。参阅[流式传输指南](/openai-agents-js/zh/guides/streaming)。 +流式传输允许你在 LLM 运行期间额外接收流式事件。流启动后，`StreamedRunResult` 将包含关于此次运行的完整信息，包括所有新产生的输出。你可以使用 `for await` 循环遍历流式事件。详见[流式传输](/openai-agents-js/zh/guides/streaming)。 ## 运行配置 -如果您要创建自己的 `Runner` 实例，可以传入一个 `RunConfig` 对象来配置 runner。 - -| 字段 | 类型 | 目的 | -| --------------------------- | --------------------- | ------------------------------------------------------------- | -| `model` | `string \| Model` | 为运行中的**所有**智能体强制指定特定模型。 | -| `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 自动生成。 | -| `traceMetadata` | `Record` | 要附加到每个 span 的任意元数据。 | +如果你在创建自己的 `Runner` 实例时，可以传入 `RunConfig` 对象来配置 runner。 + +| Field | Type | Purpose | +| --------------------------- | --------------------- | --------------------------------------------------------------- | +| `model` | `string \| Model` | 为运行中的**所有**智能体强制指定特定模型。 | +| `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 自动生成。 | +| `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 串联每个请求。这样无需创建完整的会话资源，也能在各轮次间保持上下文。 ## 异常 -SDK 会抛出一小组可捕获的错误： +SDK 会抛出一小组可供捕获的错误： -- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – 达到 `maxTurns`。 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – 模型生成了无效输出（例如格式错误的 JSON、未知工具）。 -- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) – 违反护栏。 -- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – 护栏执行失败。 -- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 任一函数工具调用失败。 -- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 基于配置或用户输入抛出的错误。 +- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) —— 达到 `maxTurns`。 +- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) —— 模型产生无效输出（如 JSON 格式错误、未知工具）。 +- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) —— 违反护栏。 +- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) —— 护栏执行失败。 +- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) —— 任一函数工具调用失败。 +- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) —— 基于配置或用户输入抛出的任何错误。 -这些错误均继承自基础类 `AgentsError`，该类可能提供 `state` 属性以访问当前运行状态。 +它们都继承自基础 `AgentsError` 类，该类可能提供 `state` 属性以访问当前运行状态。 -以下是一个处理 `GuardrailExecutionError` 的示例代码： +以下是处理 `GuardrailExecutionError` 的示例代码： -运行上述示例时，您将看到如下输出： +运行上述示例时，你将看到如下输出： ``` Guardrail execution failed: Error: Input guardrail failed to complete: Error: Something is wrong! @@ -145,5 +153,5 @@ Math homework guardrail tripped ## 后续步骤 - 了解如何[配置模型](/openai-agents-js/zh/guides/models)。 -- 为您的智能体提供[工具](/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/sessions.mdx b/docs/src/content/docs/zh/guides/sessions.mdx index b12d60a4..54c52731 100644 --- a/docs/src/content/docs/zh/guides/sessions.mdx +++ b/docs/src/content/docs/zh/guides/sessions.mdx @@ -9,64 +9,68 @@ import manageHistory from '../../../../../../examples/docs/sessions/manageHistor import customSession from '../../../../../../examples/docs/sessions/customSession.ts?raw'; import sessionInputCallback from '../../../../../../examples/docs/sessions/sessionInputCallback.ts?raw'; -会话为 Agents SDK 提供了一个**持久化内存层**。将任何实现了 `Session` 接口的对象传给 `Runner.run`，其余工作由 SDK 处理。当会话存在时，runner 会自动： +Sessions 为 Agents SDK 提供了一个**持久化内存层**。向 `Runner.run` 提供任何实现了 `Session` 接口的对象，其余由 SDK 处理。当存在 session 时，runner 会自动： -1. 获取先前存储的对话项并在下一轮对话前置。 -2. 在每次运行完成后持久化新的用户输入和助手输出。 -3. 保持会话可用于后续轮次，无论是用新的用户文本调用 runner，还是从中断的 `RunState` 恢复。 +1. 获取先前存储的对话项，并在下一轮对话前将其预置。 +2. 在每次运行完成后，持久化新的用户输入和助手输出。 +3. 保持该 session 可用于后续轮次，无论是用新的用户文本调用 runner，还是从中断的 `RunState` 恢复。 -这免去了手动调用 `toInputList()` 或在轮次间拼接历史的需要。TypeScript SDK 自带两个实现：用于 Conversations API 的 `OpenAIConversationsSession`，以及面向本地开发的 `MemorySession`。由于它们共享 `Session` 接口，您可以插入自定义存储后端。除了 Conversations API 之外的灵感，可参阅 `examples/memory/` 下的示例会话后端（Prisma、文件存储等）。 +这免除了手动调用 `toInputList()` 或在轮次之间拼接历史的需要。TypeScript SDK 自带两个实现：用于 Conversations API 的 `OpenAIConversationsSession`，以及用于本地开发的 `MemorySession`。由于它们共享 `Session` 接口，您可以插入自己的存储后端。除 Conversations API 外的更多灵感，可查看 `examples/memory/` 下的示例 session 后端（Prisma、文件存储等）。 -> 提示：要运行本页中的 `OpenAIConversationsSession` 示例，请设置 `OPENAI_API_KEY` 环境变量（或在构造会话时提供 `apiKey`），以便 SDK 能调用 Conversations API。 +> 提示：要运行本页中的 `OpenAIConversationsSession` 示例，请设置 `OPENAI_API_KEY` 环境变量（或在构造 session 时提供 `apiKey`），以便 SDK 可以调用 Conversations API。 --- ## 快速上手 -使用 `OpenAIConversationsSession` 将内存与 [Conversations API](https://platform.openai.com/docs/api-reference/conversations) 同步，或替换为任意其他 `Session` 实现。 +使用 `OpenAIConversationsSession` 与 [Conversations API](https://platform.openai.com/docs/api-reference/conversations) 同步内存，或替换为任何其他 `Session` 实现。 -复用同一个会话实例可确保智能体在每一轮前都能获得完整的对话历史，并自动持久化新条目。切换到不同的 `Session` 实现无需更改其他代码。 +复用同一个 session 实例可确保每一轮开始前，智能体都能收到完整对话历史，并自动持久化新增条目。切换到不同的 `Session` 实现无需其他代码改动。 --- -## runner 如何使用会话 +## Runner 如何使用 sessions -- 在每次运行之前，它会检索会话历史，将其与新一轮的输入合并，并将合并后的列表传给您的智能体。 -- 对于非流式运行，一次 `session.addItems()` 调用即可持久化最新一轮中的原始用户输入和模型输出。 -- 对于流式运行，它会先写入用户输入，并在该轮完成后追加流式输出。 -- 当从 `RunResult.state` 恢复（用于审批或其他中断）时，请继续传入相同的 `session`。恢复的该轮会被添加到内存中，而无需重新准备输入。 +- 在每次运行之前：检索 session 历史，将其与新一轮输入合并，并将合并后的列表传给智能体。 +- 对于非流式运行：一次调用 `session.addItems()` 即可持久化该轮的原始用户输入和模型输出。 +- 对于流式传输运行：先写入用户输入，并在该轮完成后追加流式输出。 +- 当从 `RunResult.state` 恢复时（用于审批或其他中断），继续传递同一个 `session`。恢复的该轮会被添加到内存中，而无需重新准备输入。 --- ## 历史的查看与编辑 -会话提供简洁的 CRUD 助手，便于构建“撤销”“清空对话”或审计等功能。 +Sessions 暴露了简单的 CRUD 助手，便于构建“撤销”“清空聊天”或审计等功能。 -`session.getItems()` 会返回已存储的 `AgentInputItem[]`。调用 `popItem()` 可移除最后一条记录——在您重新运行智能体前用于用户更正非常有用。 +`session.getItems()` 返回已存储的 `AgentInputItem[]`。调用 `popItem()` 可移除最后一条——在重新运行智能体前，适用于用户更正。 --- ## 自带存储 -实现 `Session` 接口即可使用 Redis、DynamoDB、SQLite 或其他数据存储来支撑内存。只需实现五个异步方法。 +实现 `Session` 接口，用 Redis、DynamoDB、SQLite 或其他数据存储来支撑内存。只需五个异步方法。 - + -自定义会话可用于实施保留策略、添加加密，或在持久化前为每次对话轮次附加元数据。 +自定义 session 可用于强制执行保留策略、添加加密，或在持久化前为每次对话轮次附加元数据。 --- ## 控制历史与新条目的合并方式 -当您将 `AgentInputItem` 数组作为运行输入时，可提供 `sessionInputCallback` 来以确定性方式与存储的历史合并。runner 会加载现有历史，在模型调用之前调用该回调，并将返回的数组作为该轮的完整输入交给模型。此钩子非常适合裁剪旧条目、去重工具结果，或仅突出您希望模型看到的上下文。 +当以 `AgentInputItem` 数组作为运行输入时，提供 `sessionInputCallback` 以确定性地将其与存储的历史合并。runner 会加载现有历史，在**模型调用之前**调用您的回调，并将返回的数组作为该轮的完整输入交给模型。此钩子非常适合裁剪旧条目、去重工具结果，或仅突出您希望模型看到的上下文。 -当启用流式传输时，返回的 `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 会被 resolve。如果你想确保没有更多输出，请务必等待它。 ### 监听所有事件 -你可以使用 `for await` 循环在每个事件到达时进行检查。可用信息包括底层模型事件、任何智能体切换以及 SDK 特定的运行信息： +你可以使用 `for await` 循环在事件到达时逐个检查。可用信息包括底层模型事件、任何智能体切换以及 SDK 特定的运行信息： -参见[流式传输示例](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)，该示例脚本完整演示了同时打印纯文本流和原始事件流。 ## 事件类型 @@ -75,7 +75,7 @@ type RunItemStreamEvent = { }; ``` -示例交接负载： +交接负载示例： ```json { @@ -112,12 +112,12 @@ type RunAgentUpdatedStreamEvent = { ## 流式传输中的人工干预 -流式传输与会暂停执行的交接兼容（例如当某个工具需要审批）。流对象上的 `interruption` 字段会暴露中断，你可以对每个中断调用 `state.approve()` 或 `state.reject()` 以继续执行。再次以 `{ stream: true }` 执行将恢复流式输出。 +流式传输与会暂停执行的交接兼容（例如当某个工具需要批准时）。流对象上的 `interruption` 字段会暴露中断，你可以为每个中断调用 `state.approve()` 或 `state.reject()` 以继续执行。再次以 `{ stream: true }` 执行即可恢复流式输出。 一个与用户交互的更完整示例见 @@ -126,7 +126,7 @@ type RunAgentUpdatedStreamEvent = { ## 提示 - 退出前请记得等待 `stream.completed`，以确保所有输出都已刷新。 -- 初始的 `{ stream: true }` 选项只适用于提供它的那次调用。若你使用 `RunState` 重新运行，必须再次指定该选项。 -- 若你的应用只关心文本结果，优先使用 `toTextStream()`，以免处理单个事件对象。 +- 初始的 `{ 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 eaab088c..4a4bc537 100644 --- a/docs/src/content/docs/zh/guides/tools.mdx +++ b/docs/src/content/docs/zh/guides/tools.mdx @@ -12,10 +12,10 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer 工具让智能体能够**执行操作**——获取数据、调用外部 API、执行代码，甚至使用计算机。JavaScript/TypeScript SDK 支持四种类别： -1. **托管工具**——与模型一起在 OpenAI 服务器上运行。（Web 搜索、文件搜索、计算机操作、Code Interpreter、图像生成） -2. **函数工具**——使用 JSON schema 包装任意本地函数，让 LLM 可调用。 -3. **智能体作为工具**——将整个智能体暴露为可调用的工具。 -4. **本地 MCP 服务器**——挂载在你机器上运行的 Model Context Protocol 服务器。 +1. **托管工具**——与模型在 OpenAI 服务器上并行运行。（Web 搜索、文件搜索、计算机操作、Code Interpreter、图像生成） +2. **函数工具**——使用 JSON schema 封装任意本地函数，以便 LLM 调用。 +3. **将智能体作为工具**——将整个智能体暴露为可调用的工具。 +4. **本地 MCP 服务器**——连接运行在本机上的 Model Context Protocol 服务器。 --- @@ -23,19 +23,19 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer 当你使用 `OpenAIResponsesModel` 时，可以添加以下内置工具： -| 工具 | 类型字符串 | 目的 | -| ----------------------- | -------------------- | -------------------------------- | -| Web search | `'web_search'` | 互联网搜索。 | -| File / retrieval search | `'file_search'` | 查询托管在 OpenAI 上的向量存储。 | -| Computer use | `'computer'` | 自动化 GUI 交互。 | -| Shell | `'shell'` | 在主机上运行 shell 命令。 | -| Apply patch | `'apply_patch'` | 将 V4A diffs 应用于本地文件。 | -| Code Interpreter | `'code_interpreter'` | 在沙盒环境中运行代码。 | -| Image generation | `'image_generation'` | 基于文本生成图像。 | +| 工具 | 类型字符串 | 目的 | +| ---------------- | -------------------- | -------------------------------- | +| Web 搜索 | `'web_search'` | 互联网搜索。 | +| 文件/检索搜索 | `'file_search'` | 查询托管在 OpenAI 上的向量存储。 | +| 计算机操作 | `'computer'` | 自动化 GUI 交互。 | +| Shell | `'shell'` | 在主机上运行 shell 命令。 | +| 应用补丁 | `'apply_patch'` | 将 V4A diff 应用于本地文件。 | +| Code Interpreter | `'code_interpreter'` | 在沙盒环境中运行代码。 | +| 图像生成 | `'image_generation'` | 基于文本生成图像。 | -具体的参数集合与 OpenAI Responses API 保持一致——高级选项（如 `rankingOptions` 或语义过滤器）请参考官方文档。 +具体参数集合与 OpenAI Responses API 完全一致——高级选项（如 `rankingOptions` 或语义过滤器）请参考官方文档。 --- @@ -51,18 +51,18 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer ### 选项参考 -| 字段 | 必填 | 描述 | +| 字段 | 必填 | 说明 | | --------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | 否 | 默认为函数名（例如 `get_weather`）。 | -| `description` | 是 | 清晰、可读的描述，展示给 LLM。 | -| `parameters` | 是 | 可以是 Zod schema 或原始 JSON schema 对象。使用 Zod 参数会自动启用**严格**模式。 | -| `strict` | 否 | 当为 `true`（默认）时，如果参数验证失败，SDK 会返回模型错误。设置为 `false` 以进行模糊匹配。 | +| `description` | 是 | 提供给 LLM 的清晰、可读的人类描述。 | +| `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 时禁用严格模式： +如果你需要模型在输入无效或不完整时进行“猜测”，可以在使用原始 JSON schema 时禁用严格模式： + -在幕后，SDK 会： +在内部，SDK 会： -- 创建一个仅包含 `input` 参数的函数工具。 -- 当该工具被调用时，使用该输入运行子智能体。 +- 创建一个只有 `input` 参数的函数工具。 +- 当工具被调用时，使用该输入运行子智能体。 - 返回最后一条消息，或由 `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/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) 了解详情。 --- ## 工具使用行为 -关于如何控制模型何时以及如何必须使用工具（`tool_choice`、`toolUseBehavior` 等），请参考[智能体](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 +关于控制模型何时以及如何必须使用工具（`tool_choice`、`toolUseBehavior` 等），请参阅[智能体](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 --- ## 最佳实践 -- **简短且明确的描述**——描述工具做什么，以及*何时使用*它。 -- **验证输入**——尽可能使用 Zod schema 实现严格的 JSON 验证。 -- **避免在错误处理器中产生副作用**——`errorFunction` 应返回有用的字符串，而不是抛出异常。 -- **每个工具只做一件事**——小而可组合的工具有助于提升模型推理效果。 +- **简短、明确的描述**——说明工具做什么、以及何时使用它。 +- **校验输入**——尽可能使用 Zod schema 进行严格的 JSON 校验。 +- **避免在错误处理器中产生副作用**——`errorFunction` 应返回有帮助的字符串，而不是抛出异常。 +- **单一职责**——小而可组合的工具有助于更好的模型推理。 --- ## 后续步骤 -- 了解[强制使用工具](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 -- 添加[护栏](/openai-agents-js/zh/guides/guardrails)以验证工具输入或输出。 -- 查阅 TypeDoc 中 [`tool()`](/openai-agents-js/openai/agents/functions/tool) 以及多种托管工具类型的参考文档。 +- 了解如何[强制使用工具](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 +- 添加[护栏](/openai-agents-js/zh/guides/guardrails)来验证工具输入或输出。 +- 查看 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 f915521c..7bdab57a 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 dashboard](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 退出前导出追踪。 `。 - - `group_id`：可选的分组 ID，用于将同一会话的多个 Trace 关联起来。例如，你可以使用聊天线程 ID。 - - `disabled`：若为 True，则不会记录该 Trace。 +- **Traces** 表示一次“工作流”的端到端操作。它们由 Spans 组成。Trace 具有以下属性： + - `workflow_name`：逻辑上的工作流或应用。例如“代码生成”或“客户服务”。 + - `trace_id`：Trace 的唯一 ID。如果未传入则自动生成。必须满足格式 `trace_<32_alphanumeric>`。 + - `group_id`：可选的分组 ID，用于关联同一会话的多条 Trace。例如可以使用聊天线程 ID。 + - `disabled`：若为 True，将不记录该 Trace。 - `metadata`：Trace 的可选元数据。 -- **Spans** 表示具有开始和结束时间的操作。Span 包含： +- **Spans** 表示有开始与结束时间的操作。Span 具有： - `started_at` 和 `ended_at` 时间戳。 - `trace_id`，表示其所属的 Trace - `parent_id`，指向该 Span 的父 Span（如果有） - - `span_data`，关于该 Span 的信息。例如，`AgentSpanData` 包含有关智能体的信息，`GenerationSpanData` 包含有关 LLM 生成的信息等。 + - `span_data`，即关于该 Span 的信息。例如，`AgentSpanData` 包含关于智能体的信息，`GenerationSpanData` 包含关于 LLM 生成的信息等。 ## 默认追踪 默认情况下，SDK 会追踪以下内容： -- 整个 `run()` 或 `Runner.run()` 会被一个 `Trace` 包裹。 -- 每次智能体运行都会被 `AgentSpan` 包裹 -- LLM 生成会被 `GenerationSpan` 包裹 +- 整个 `run()` 或 `Runner.run()` 被 `Trace` 包裹 +- 每次智能体运行，被 `AgentSpan` 包裹 +- LLM 生成被 `GenerationSpan` 包裹 - 函数工具调用各自被 `FunctionSpan` 包裹 -- 护栏会被 `GuardrailSpan` 包裹 -- 交接会被 `HandoffSpan` 包裹 +- 护栏被 `GuardrailSpan` 包裹 +- 交接被 `HandoffSpan` 包裹 -默认的 Trace 名称为 “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 trace processors](#custom-tracing-processors)，将追踪推送到其他目的地（作为替代或附加目的地）。 +此外，你可以设置[自定义追踪处理器](#custom-tracing-processors)，将追踪推送到其他目的地（作为替代或附加目的地）。 ### 语音智能体追踪 -如果你使用 `RealtimeAgent` 和 `RealtimeSession` 且采用默认的 OpenAI Realtime API，追踪会自动在 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)了解更多详情。 -## 更高层级的 Trace +## 更高层级的追踪 -有时，你可能希望多次调用 `run()` 归属于同一个 Trace。你可以将整段代码包裹在 `withTrace()` 中来实现。 +有时，你可能希望多次调用 `run()` 属于同一个 Trace。可以将整段代码包裹在 `withTrace()` 中实现。 -1. 因为两次对 `run` 的调用都包裹在 `withTrace()` 中，单次运行将作为整体 Trace 的一部分，而不是创建两个独立的 Trace。 +1. 因为两次 `run` 调用被 `withTrace()` 包裹，单次运行将作为整体 Trace 的一部分，而不是创建两个 Trace。 -## 创建 Trace +## 创建追踪 -你可以使用 [`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 函数创建一个 Trace。或者，你也可以使用 `getGlobalTraceProvider().createTrace()` 手动创建新 Trace，并将其传入 `withTrace()`。 +你可以使用 [`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 函数创建一个 Trace。或者，使用 `getGlobalTraceProvider().createTrace()` 手动创建新 Trace，并将其传入 `withTrace()`。 -当前 Trace 通过 [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 会自动归属于当前 Trace，并嵌套在最近的当前 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) 禁用对这些数据的捕获。 +`createGenerationSpan()` 会存储 LLM 生成的输入/输出，而 `createFunctionSpan()` 会存储函数调用的输入/输出。这些可能包含敏感数据，你可以通过 [`RunConfig.traceIncludeSensitiveData +`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) 来禁用捕获这些数据。 ## 自定义追踪处理器 追踪的高层架构如下： -- 初始化时，我们创建了一个全局的 [`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/)，它会将 Trace/Span 批量发送给 [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/)，由后者将 Span 和 Trace 批量导出到 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/)，该处理器会将 Trace/Span 批量发送到 [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/)，该导出器会将 Span 与 Trace 批量导出到 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) 允许添加一个“额外的”追踪处理器，它会在 Trace 与 Span 就绪时收到它们。这样你可以在将追踪发送到 OpenAI 后端之外，执行自定义处理。 +2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) 允许用你自己的追踪处理器“替换”默认处理器。这意味着除非你包含将数据发送到 OpenAI 后端的 `TracingProcessor`，否则追踪将不会发送到 OpenAI 后端。 ## 外部追踪处理器列表 diff --git a/docs/src/content/docs/zh/guides/troubleshooting.mdx b/docs/src/content/docs/zh/guides/troubleshooting.mdx index eda7c4dc..705dd185 100644 --- a/docs/src/content/docs/zh/guides/troubleshooting.mdx +++ b/docs/src/content/docs/zh/guides/troubleshooting.mdx @@ -3,7 +3,7 @@ title: 故障排除 description: Learn how to troubleshoot issues with the OpenAI Agents SDK. --- -## 支持的运行环境 +## 支持的环境 OpenAI Agents SDK 支持以下服务器环境： @@ -11,31 +11,31 @@ OpenAI Agents SDK 支持以下服务器环境： - Deno 2.35+ - Bun 1.2.5+ -### 限制性支持 +### 有限支持 -- **Cloudflare Workers**：Agents SDK 可在 Cloudflare Workers 中使用，但目前存在一些限制： - - 当前需要启用 `nodejs_compat` - - 需要在请求结束时手动刷新追踪数据。有关详细信息，[参见追踪指南](/openai-agents-js/zh/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/zh/guides/tracing#export-loop-lifecycle)了解详情。 + - 由于 Cloudflare Workers 对 `AsyncLocalStorage` 的支持有限，某些追踪可能不够准确 + - 出站 WebSocket 连接必须使用基于 fetch 的升级方式（不能使用全局 `WebSocket` 构造函数）。对于实时功能，请在 `@openai/agents-extensions` 中使用 Cloudflare 传输（`CloudflareRealtimeTransportLayer`）。 - **浏览器**： - - 目前在浏览器中不支持追踪 + - 浏览器当前不支持追踪 - **v8 isolates**： - - 如果使用带有合适浏览器 polyfill 的打包工具，理论上可以为 v8 isolates 打包 SDK，但追踪将无法工作 + - 如果使用带有合适浏览器 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` — Realtime Agents 组件 +- `openai-agents:realtime` — 实时智能体组件 diff --git a/docs/src/content/docs/zh/guides/voice-agents.mdx b/docs/src/content/docs/zh/guides/voice-agents.mdx index 52433e43..af46740a 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 客户端。 -### 关键功能 +### 关键特性 - 通过 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 187e0eca..f9c62713 100644 --- a/docs/src/content/docs/zh/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/zh/guides/voice-agents/build.mdx @@ -30,29 +30,29 @@ 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)。 ## 工具 @@ -60,104 +60,104 @@ import turnDetectionExample from '../../../../../../../examples/docs/voice-agent -你只能在实时智能体中使用函数工具，并且这些工具会在与你的 Realtime Session 相同的位置执行。这意味着如果你在浏览器中运行 Realtime Session，你的工具也会在浏览器中执行。如果需要执行更敏感的操作，你可以在工具内向你的后端服务器发起 HTTP 请求。 +实时智能体只能使用函数工具，并且这些工具会在与你的 Realtime Session 相同的位置执行。这意味着如果你在浏览器中运行 Realtime Session，你的工具也会在浏览器中执行。如果需要执行更敏感的操作，你可以在工具内部向后端服务器发起 HTTP 请求。 -在工具执行期间，智能体将无法处理来自用户的新请求。改进体验的一种方式是让你的智能体在即将执行工具时进行提示，或使用特定短语来为工具执行争取时间。 +在工具执行期间，智能体将无法处理来自用户的新请求。改进体验的一种方式是告知智能体在即将执行工具时进行提示，或说出特定短语以为工具执行争取时间。 -### 访问会话历史 +### 访问对话历史 -除了智能体调用特定工具时传入的参数外，你还可以访问由 Realtime Session 跟踪的当前会话历史快照。如果需要基于对话的当前状态执行更复杂的操作，或计划[通过工具进行委派](#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 Session 会自动检测用户何时开始说话，并使用 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 文档，了解不同设置的更多细节](https://platform.openai.com/docs/guides/realtime-vad) +修改轮次检测设置有助于校准意外的打断以及处理静音。查看[Realtime API 文档以了解不同设置的更多细节](https://platform.openai.com/docs/guides/realtime-vad) ## 打断 -使用内置的语音活动检测时，打断智能体说话会自动触发智能体根据所说内容检测并更新上下文。同时会发出 `audio_interrupted` 事件。此事件可用于立即停止所有音频回放（仅适用于 WebSocket 连接）。 +使用内置的语音活动检测时，用户打断智能体说话会自动触发智能体根据用户所说内容检测并更新上下文。同时会发出 `audio_interrupted` 事件。对于 WebSocket 连接，这可用于立刻停止所有音频播放。 -如果你想手动打断，例如在 UI 中提供“停止”按钮，你可以手动调用 `interrupt()`： +如果你想执行手动打断，例如在 UI 中提供“停止”按钮，你可以手动调用 `interrupt()`： -无论哪种方式，Realtime Session 都会处理智能体生成的中断，截断其对用户所说内容的认知，并更新历史。 +无论哪种方式，Realtime Session 都会处理对智能体生成的打断、截断其对已对用户所述内容的认知，并更新历史。 -如果你使用 WebRTC 连接智能体，它还会清除音频输出。若使用 WebSocket，你需要自行停止已排队的音频播放。 +如果你使用 WebRTC 连接到智能体，它还会清除音频输出。如果你使用 WebSocket，你需要自行停止已排队待播放内容的音频播放。 ## 文本输入 如果你想向智能体发送文本输入，可以使用 `RealtimeSession` 上的 `sendMessage` 方法。 -这在你希望让用户以两种模态与智能体交互，或为对话提供额外上下文时很有用。 +这在你希望让用户以双模态与智能体交互，或为对话提供额外上下文时很有用。 -## 会话历史管理 +## 对话历史管理 -`RealtimeSession` 会在 `history` 属性中自动管理会话历史： +`RealtimeSession` 会在 `history` 属性中自动管理对话历史： -你可以用它向客户渲染历史或对其执行其他操作。由于该历史会在对话过程中不断变化，你可以监听 `history_updated` 事件。 +你可以使用它向客户渲染历史或对其执行额外操作。由于在对话过程中此历史会不断变化，你可以监听 `history_updated` 事件。 -如果你想修改历史，例如完全移除一条消息或更新其转写，可以使用 `updateHistory` 方法。 +如果你想修改历史，例如完全移除一条消息或更新其转录，你可以使用 `updateHistory` 方法。 ### 限制 1. 目前无法在事后更新/更改函数工具调用 -2. 历史中的文本输出需要启用转写和文本模态 -3. 因打断而被截断的响应没有转写 +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 edfb0160..b5c45c99 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 key 来生成密钥。 ```bash export OPENAI_API_KEY="sk-proj-...(your own key here)" @@ -59,11 +59,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - 响应在顶层会包含一个以 "ek\_" 为前缀的 "value" 字符串。您可以使用此临时密钥稍后建立 WebRTC 连接。请注意，该密钥只在短时间内有效，需要重新生成。 + 响应的顶层会包含一个以 "ek\_" 前缀开头的 "value" 字符串。稍后您可以使用此临时密钥建立 WebRTC 连接。请注意，该密钥仅在短时间内有效，需要定期重新生成。 -3. **创建您的第一个智能体** +3. **创建第一个智能体** - 创建一个新的 [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) 与创建常规的 [`Agent`](/openai-agents-js/guides/agents) 非常相似。 + 创建新的 [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) 与创建常规的[`智能体`](/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,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，并自动配置麦克风与扬声器进行音频输入和输出。如果您在后端服务器（如 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,7 +114,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t ## 后续步骤 -从这里开始，您可以设计并构建自己的语音智能体。语音智能体包含大量与常规智能体相同的功能，同时也有其独特特性。 +从这里开始，您可以设计并构建自己的语音智能体。语音智能体包含与常规智能体相同的许多功能，同时也有其独特之处。 - 了解如何为语音智能体添加： - [工具](/openai-agents-js/zh/guides/voice-agents/build#tools) @@ -123,7 +123,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t - [处理音频打断](/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 6c315901..2c513a4a 100644 --- a/docs/src/content/docs/zh/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/zh/guides/voice-agents/transport.mdx @@ -31,54 +31,54 @@ import cloudflareTransportExample from '../../../../../../../examples/docs/exten ### WebRTC 连接 -默认传输层使用 WebRTC。音频将从麦克风录制并自动播放。 +默认传输层使用 WebRTC。音频会从麦克风录制并自动回放。 -如需使用您自己的媒体流或音频元素，在创建会话时提供一个 `OpenAIRealtimeWebRTC` 实例。 +如需使用自定义的媒体流或音频元素，请在创建会话时提供一个 `OpenAIRealtimeWebRTC` 实例。 ### WebSocket 连接 -在创建会话时传入 `transport: 'websocket'` 或 `OpenAIRealtimeWebSocket` 的实例，以使用 WebSocket 连接替代 WebRTC。这非常适合服务器端用例，例如构建使用 Twilio 的电话智能体。 +在创建会话时传入 `transport: 'websocket'` 或一个 `OpenAIRealtimeWebSocket` 实例，以使用 WebSocket 连接而非 WebRTC。该方式适合服务端场景，例如使用 Twilio 构建电话智能体。 -使用任意录制/播放库来处理原始 PCM16 音频字节。 +使用任意录制/回放库来处理原始 PCM16 音频字节。 ### SIP 连接 -通过使用 `OpenAIRealtimeSIP` 传输，将来自 Twilio 等提供商的 SIP 呼叫进行桥接。该传输会让 Realtime 会话与您的电话服务提供商发出的 SIP 事件保持同步。 +通过使用 `OpenAIRealtimeSIP` 传输层桥接来自 Twilio 等提供商的 SIP 呼叫。该传输层使 Realtime 会话与您的电信提供商发出的 SIP 事件保持同步。 -1. 通过 `OpenAIRealtimeSIP.buildInitialConfig()` 生成初始会话配置以接受来电。这可确保 SIP 邀请与 Realtime 会话共享一致的默认值。 -2. 附加一个使用 `OpenAIRealtimeSIP` 传输的 `RealtimeSession`，并使用提供商 webhook 发放的 `callId` 进行连接。 -3. 监听会话事件，用于驱动通话分析、转录或升级逻辑。 +1. 通过 `OpenAIRealtimeSIP.buildInitialConfig()` 生成初始会话配置以接受来电。这可确保 SIP 邀请与 Realtime 会话共享相同的默认值。 +2. 附加一个使用 `OpenAIRealtimeSIP` 传输层的 `RealtimeSession`，并使用提供商 webhook 发放的 `callId` 进行连接。 +3. 监听会话事件以驱动通话分析、转录或升级逻辑。 -#### Cloudflare Workers（workerd）注意事项 +#### 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 1cc56731..3194e2a3 100644 --- a/docs/src/content/docs/zh/index.mdx +++ b/docs/src/content/docs/zh/index.mdx @@ -17,32 +17,33 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概述 -[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) -使您可以用极少的抽象，在轻量、易用的包中构建具备智能体能力的 AI 应用。它是我们此前针对智能体的实验项目 +[适用于 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 仅包含一小组基础组件： -- **智能体**：配备指令和工具的 LLM -- **交接**：允许智能体将特定任务委派给其他智能体 -- **护栏**：对传入智能体的输入进行校验 +- **智能体（Agents）**：配备 instructions 和 tools 的 LLM +- **交接（Handoffs）**：允许智能体将特定任务委派给其他智能体 +- **护栏（Guardrails）**：用于对传入智能体的输入进行校验 -配合 TypeScript，这些基础组件足以表达工具与智能体之间的复杂关系，让您以较低的学习成本构建真实世界的应用。此外，SDK 内置 **追踪**，可帮助您可视化并调试智能体流程，进行评估，甚至为您的应用微调模型。 +结合 TypeScript，这些基础组件足以表达工具与智能体之间的复杂关系，帮助你在没有陡峭学习曲线的情况下构建真实世界的应用。此外，SDK 内置 **追踪（tracing）**，便于可视化与调试你的智能体流程，还可以对其进行评估，甚至为你的应用微调模型。 ## 为何使用 Agents SDK 该 SDK 的两大设计原则： -1. 功能足够丰富值得使用，但基础组件足够少，便于快速上手。 -2. 开箱即用体验优秀，同时允许您精确自定义行为。 +1. 功能足够丰富，值得使用；但基础组件足够精简，便于快速上手。 +2. 开箱即用体验优秀，同时又可精确自定义具体行为。 -主要特性包括： +SDK 的主要特性包括： -- **智能体循环**：内置循环，负责调用工具、将结果发送给 LLM，并循环直至 LLM 完成。 -- **TypeScript 优先**：使用内置语言特性来编排与串联智能体，无需学习新的抽象。 -- **交接**：在多个智能体之间进行协调与委派的强大能力。 -- **护栏**：与智能体并行运行输入校验与检查，若失败会尽早中断。 -- **函数工具**：将任意 TypeScript 函数变为工具，自动生成模式并使用 Zod 进行校验。 -- **追踪**：内置追踪，可视化、调试与监控工作流，并可使用 OpenAI 的评估、微调与蒸馏工具。 -- **实时智能体**：构建强大的语音智能体，包括自动打断检测、上下文管理、护栏等。 +- **Agent loop**：内置智能体循环，负责调用工具、将结果返回给 LLM，并循环直至 LLM 完成。 +- **TypeScript 优先**：使用内建语言特性来编排与串联智能体，而无需学习新的抽象。 +- **交接（Handoffs）**：在多个智能体之间进行协调与委派的强大能力。 +- **护栏（Guardrails）**：与智能体并行运行输入校验与检查，如检查失败可提前中止。 +- **函数工具（Function tools）**：将任意 TypeScript 函数变为工具，自动生成模式（schema）并提供基于 Zod 的校验。 +- **追踪（Tracing）**：内置追踪，用于可视化、调试和监控你的工作流，并可使用 OpenAI 的评估、微调与蒸馏工具。 +- **实时智能体（Realtime Agents）**：构建强大的语音智能体，包含自动打断检测、上下文管理、护栏等。 ## 安装 @@ -54,7 +55,7 @@ npm install @openai/agents zod@3 -(_如果要运行此示例，请确保设置 `OPENAI_API_KEY` 环境变量_) +（运行本示例时，请确保已设置 `OPENAI_API_KEY` 环境变量） ```bash export OPENAI_API_KEY=sk-...