From 5e21651e5625682a828b63eba15d3278a98ebcc1 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 13 Nov 2025 18:41:00 +0000 Subject: [PATCH] Update all translated document pages --- .../src/content/docs/ja/extensions/ai-sdk.mdx | 28 ++--- .../content/docs/ja/extensions/cloudflare.mdx | 15 +-- .../src/content/docs/ja/extensions/twilio.mdx | 42 +++---- docs/src/content/docs/ja/guides/agents.mdx | 108 ++++++++++-------- docs/src/content/docs/ja/guides/config.mdx | 24 ++-- docs/src/content/docs/ja/guides/context.mdx | 28 ++--- .../src/content/docs/ja/guides/guardrails.mdx | 32 +++--- docs/src/content/docs/ja/guides/handoffs.mdx | 24 ++-- .../docs/ja/guides/human-in-the-loop.mdx | 43 ++++--- docs/src/content/docs/ja/guides/mcp.mdx | 77 +++++++------ docs/src/content/docs/ja/guides/models.mdx | 80 ++++++------- .../src/content/docs/ja/guides/multi-agent.md | 44 +++---- .../src/content/docs/ja/guides/quickstart.mdx | 44 +++---- docs/src/content/docs/ja/guides/release.mdx | 12 +- docs/src/content/docs/ja/guides/results.mdx | 64 +++++------ .../content/docs/ja/guides/running-agents.mdx | 98 ++++++++-------- docs/src/content/docs/ja/guides/sessions.mdx | 46 ++++---- docs/src/content/docs/ja/guides/streaming.mdx | 42 +++---- docs/src/content/docs/ja/guides/tools.mdx | 98 ++++++++-------- docs/src/content/docs/ja/guides/tracing.mdx | 88 +++++++------- .../docs/ja/guides/troubleshooting.mdx | 30 ++--- .../content/docs/ja/guides/voice-agents.mdx | 18 +-- .../docs/ja/guides/voice-agents/build.mdx | 71 ++++++------ .../ja/guides/voice-agents/quickstart.mdx | 38 +++--- .../docs/ja/guides/voice-agents/transport.mdx | 38 +++--- docs/src/content/docs/ja/index.mdx | 38 +++--- .../src/content/docs/ko/extensions/ai-sdk.mdx | 26 ++--- .../content/docs/ko/extensions/cloudflare.mdx | 18 +-- .../src/content/docs/ko/extensions/twilio.mdx | 56 ++++----- docs/src/content/docs/ko/guides/agents.mdx | 99 ++++++++-------- docs/src/content/docs/ko/guides/config.mdx | 18 +-- docs/src/content/docs/ko/guides/context.mdx | 32 +++--- .../src/content/docs/ko/guides/guardrails.mdx | 28 ++--- docs/src/content/docs/ko/guides/handoffs.mdx | 20 ++-- .../docs/ko/guides/human-in-the-loop.mdx | 42 +++---- docs/src/content/docs/ko/guides/mcp.mdx | 75 ++++++------ docs/src/content/docs/ko/guides/models.mdx | 80 ++++++------- .../src/content/docs/ko/guides/multi-agent.md | 42 +++---- .../src/content/docs/ko/guides/quickstart.mdx | 44 ++++--- docs/src/content/docs/ko/guides/release.mdx | 14 +-- docs/src/content/docs/ko/guides/results.mdx | 52 ++++----- .../content/docs/ko/guides/running-agents.mdx | 106 ++++++++--------- docs/src/content/docs/ko/guides/sessions.mdx | 56 ++++----- docs/src/content/docs/ko/guides/streaming.mdx | 31 ++--- docs/src/content/docs/ko/guides/tools.mdx | 91 +++++++-------- docs/src/content/docs/ko/guides/tracing.mdx | 68 +++++------ .../docs/ko/guides/troubleshooting.mdx | 28 ++--- .../content/docs/ko/guides/voice-agents.mdx | 14 +-- .../docs/ko/guides/voice-agents/build.mdx | 68 ++++++----- .../ko/guides/voice-agents/quickstart.mdx | 36 +++--- .../docs/ko/guides/voice-agents/transport.mdx | 46 ++++---- docs/src/content/docs/ko/index.mdx | 49 ++++---- .../src/content/docs/zh/extensions/ai-sdk.mdx | 18 +-- .../content/docs/zh/extensions/cloudflare.mdx | 16 +-- .../src/content/docs/zh/extensions/twilio.mdx | 41 ++++--- docs/src/content/docs/zh/guides/agents.mdx | 100 ++++++++-------- docs/src/content/docs/zh/guides/config.mdx | 16 +-- docs/src/content/docs/zh/guides/context.mdx | 30 ++--- .../src/content/docs/zh/guides/guardrails.mdx | 40 +++---- docs/src/content/docs/zh/guides/handoffs.mdx | 44 ++++--- .../docs/zh/guides/human-in-the-loop.mdx | 40 +++---- docs/src/content/docs/zh/guides/mcp.mdx | 91 ++++++++------- docs/src/content/docs/zh/guides/models.mdx | 69 +++++------ .../src/content/docs/zh/guides/multi-agent.md | 42 +++---- .../src/content/docs/zh/guides/quickstart.mdx | 44 +++---- docs/src/content/docs/zh/guides/release.mdx | 14 +-- docs/src/content/docs/zh/guides/results.mdx | 58 +++++----- .../content/docs/zh/guides/running-agents.mdx | 104 ++++++++--------- docs/src/content/docs/zh/guides/sessions.mdx | 50 ++++---- docs/src/content/docs/zh/guides/streaming.mdx | 30 ++--- docs/src/content/docs/zh/guides/tools.mdx | 80 ++++++------- docs/src/content/docs/zh/guides/tracing.mdx | 76 ++++++------ .../docs/zh/guides/troubleshooting.mdx | 26 ++--- .../content/docs/zh/guides/voice-agents.mdx | 16 +-- .../docs/zh/guides/voice-agents/build.mdx | 68 +++++------ .../zh/guides/voice-agents/quickstart.mdx | 34 +++--- .../docs/zh/guides/voice-agents/transport.mdx | 32 +++--- docs/src/content/docs/zh/index.mdx | 37 +++--- 78 files changed, 1904 insertions(+), 1821 deletions(-) diff --git a/docs/src/content/docs/ja/extensions/ai-sdk.mdx b/docs/src/content/docs/ja/extensions/ai-sdk.mdx index 443cd950..afecc415 100644 --- a/docs/src/content/docs/ja/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/ja/extensions/ai-sdk.mdx @@ -7,37 +7,37 @@ 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 は標準で OpenAI のモデルに対して Responses API または Chat Completions API を通じて動作します。ただし、別のモデルを使用したい場合は、このアダプターを通じて [Vercel の AI SDK](https://sdk.vercel.ai/) がサポートする幅広いモデルを Agents SDK に取り込むことができます。 ## セットアップ -1. 拡張パッケージをインストールして AI SDK アダプターを導入します: +1. extensions パッケージをインストールして AI SDK アダプターを導入します: ```bash npm install @openai/agents-extensions ``` -2. [Vercel の AI SDK](https://ai-sdk.dev/docs/foundations/providers-and-models) から使用したいモデルのパッケージを選び、インストールします: +2. [Vercel の AI SDK](https://ai-sdk.dev/docs/foundations/providers-and-models) から使用したいモデルパッケージを選び、インストールします: ```bash npm install @ai-sdk/openai ``` -3. アダプターとモデルをインポートして、エージェントに接続します: +3. アダプターとモデルをインポートしてエージェントに接続します: ```typescript import { openai } from '@ai-sdk/openai'; import { aisdk } from '@openai/agents-extensions'; ``` -4. エージェントで使用するモデルのインスタンスを初期化します: +4. エージェントが使用するモデルのインスタンスを初期化します: ```typescript const model = aisdk(openai('gpt-5-mini')); @@ -46,19 +46,23 @@ Agents SDK は標準で OpenAI モデルに対して Responses API または Cha ## 例 - + -## プロバイダー メタデータの指定 +## プロバイダーのメタデータの受け渡し -メッセージにプロバイダー固有のオプションを送る必要がある場合は、`providerMetadata` に渡します。値は基盤となる AI SDK のモデルにそのままフォワードされます。たとえば、Agents SDK で次の `providerData` +メッセージにプロバイダー固有のオプションを付与する必要がある場合は、`providerMetadata` を通して渡します。値は基盤となる AI SDK のモデルにそのまま転送されます。たとえば、Agents SDK で次の `providerData` ```ts providerData: { @@ -81,5 +85,3 @@ providerMetadata: { } } ``` - -。 diff --git a/docs/src/content/docs/ja/extensions/cloudflare.mdx b/docs/src/content/docs/ja/extensions/cloudflare.mdx index 694b90e1..d9baa5d8 100644 --- a/docs/src/content/docs/ja/extensions/cloudflare.mdx +++ b/docs/src/content/docs/ja/extensions/cloudflare.mdx @@ -6,13 +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 接続を開けません。これらの環境から Realtime Agents への接続を簡単にするため、extensions パッケージは `fetch()` ベースのアップグレードを内部で行う専用のトランスポートを提供します。 ## セットアップ @@ -39,6 +40,6 @@ Cloudflare Workers とその他の workerd ランタイムでは、グローバ ## 注意事項 -- Cloudflare のトランスポートは内部で `Upgrade: websocket` 付きの `fetch()` を使用し、ソケットの `open` イベントを待たずに処理します。これは workerd の API に合わせた動作です +- Cloudflare トランスポートは内部で `Upgrade: websocket` 付きの `fetch()` を使用し、ソケットの `open` イベントを待たずに進むため、workerd の API に合わせています - このトランスポートを使用しても、すべての `RealtimeSession` 機能（tools、ガードレール など）は通常どおり動作します -- 開発中の詳細ログを確認するには `DEBUG=openai-agents*` を使用してください +- 開発中の詳細ログの確認には `DEBUG=openai-agents*` を使用します diff --git a/docs/src/content/docs/ja/extensions/twilio.mdx b/docs/src/content/docs/ja/extensions/twilio.mdx index f120b6c9..0862ffd8 100644 --- a/docs/src/content/docs/ja/extensions/twilio.mdx +++ b/docs/src/content/docs/ja/extensions/twilio.mdx @@ -7,14 +7,15 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio は、電話の通話音声の 元 audio を WebSocket サーバーへ送る [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しています。このセットアップを使うと、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続できます。既定の Realtime Session transport を `websocket` モードで使用して、Twilio から来るイベントを Realtime Session に接続できます。ただし、電話は Web ベースの会話よりも遅延が大きくなりがちなため、適切な音声フォーマットを設定し、割り込みタイミングを自前で調整する必要があります。 +Twilio は、電話からの元音声を WebSocket サーバーに送信する [Media Streams API](https://www.twilio.com/docs/voice/media-streams) を提供しています。このセットアップを使って、[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を Twilio に接続できます。Twilio からのイベントを Realtime Session に接続するには、`websocket` モードのデフォルトの Realtime Session トランスポートを使用できます。ただし、電話は Web ベースの会話よりも遅延が大きくなるため、適切な音声フォーマットの設定や、割り込みタイミングの調整が必要になります。 -セットアップの体験を向上させるため、Twilio への接続や割り込み処理、音声の転送までを代わりに処理する専用のトランスポート層を用意しました。 +セットアップ体験を改善するために、Twilio への接続、割り込み処理、音声転送を扱う専用のトランスポートレイヤーを用意しました。 ## セットアップ @@ -23,14 +24,14 @@ Twilio は、電話の通話音声の 元 audio を WebSocket サーバーへ送 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. **extensions パッケージをインストールして Twilio アダプターを導入します:** +3. **拡張パッケージをインストールして Twilio アダプターを導入します:** ```bash npm install @openai/agents-extensions @@ -54,31 +55,32 @@ Twilio は、電話の通話音声の 元 audio を 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. **デバッグログを確認します。** - 何が起きているかの詳細が必要になることがあります。環境変数 `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 a392eee8..0b4bca78 100644 --- a/docs/src/content/docs/ja/guides/agents.mdx +++ b/docs/src/content/docs/ja/guides/agents.mdx @@ -15,45 +15,49 @@ import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agen import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw'; import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw'; -エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** は、次のように設定された大規模言語モデル（LLM）です。 +エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** は、次の設定を備えた Large Language Model (LLM) です。 -- **Instructions** – モデルに _自分は誰か_、_どのように応答すべきか_ を伝える system prompt +- **Instructions** – モデルに「自分は誰で」「どのように応答すべきか」を伝える system prompt - **Model** – 呼び出す OpenAI モデルと、任意のモデル調整パラメーター -- **Tools** – LLM がタスクを達成するために呼び出せる関数や API の一覧 +- **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` の下に含めることができます | -| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | +| Property | Required | Description | +| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | +| `name` | yes | 短い人間が読める識別子 | +| `instructions` | yes | System prompt（文字列 **または** 関数 – [Dynamic instructions](#dynamic-instructions) を参照） | +| `model` | no | モデル名 **または** カスタムの [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | +| `modelSettings` | no | 調整パラメーター（temperature、top_p など）。トップレベルにないプロパティが必要な場合は、`providerData` 配下に含められます | +| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列 | - + --- ## コンテキスト -エージェントは **コンテキスト型に対してジェネリック** です（例: `Agent`）。_コンテキスト_ はあなたが作成し `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザー メタデータ、機能フラグなど）を提供するのに便利です。 +エージェントはそのコンテキスト型に対して **ジェネリック** です（例: `Agent`）。コンテキストは、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはあらゆるツール、ガードレール、ハンドオフなどに転送され、状態の保持や共有サービス（データベース接続、ユーザー メタデータ、フラグ管理など）を提供するのに便利です。 - + --- ## 出力タイプ -デフォルトでは、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定できます。SDK は次を受け付けます。 +デフォルトでは、エージェントは **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は次を受け付けます。 1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`） 2. JSON‑schema 互換の任意のオブジェクト @@ -61,7 +65,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor `outputType` が指定されると、SDK はプレーンテキストの代わりに自動的に @@ -69,88 +73,100 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor --- -## マルチエージェントの設計パターン +## マルチエージェントのシステム設計パターン -エージェントを組み合わせる方法は多数あります。プロダクションアプリでよく見られるパターンは次のとおりです。 +エージェントを組み合わせる方法は多数あります。プロダクションアプリでよく見られるパターンは次の 2 つです。 -1. **Manager（エージェントをツールとして）** – 中央のエージェントが会話を所有し、ツールとして公開された専門エージェントを呼び出す -2. **ハンドオフ** – 初期エージェントが、ユーザーのリクエストを特定したら会話全体を専門家に委譲する +1. **マネージャー（エージェントをツールとして）** – 中央のエージェントが会話を所有し、ツールとして公開された専門エージェントを呼び出す +2. **ハンドオフ** – 最初のエージェントがユーザーのリクエストを特定したら、以降の会話全体を専門家に委譲する -これらのアプローチは補完的です。マネージャーはガードレールやレート制限を 1 か所で適用でき、ハンドオフは各エージェントが会話の制御を保持せずに単一タスクに集中できるようにします。 +これらのアプローチは相補的です。マネージャー方式はガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を保持せず単一タスクに集中できます。 ### マネージャー（エージェントをツールとして） -このパターンでは、マネージャーは決して制御を手放しません。LLM がツールを使い、マネージャーが最終回答を要約します。詳しくは[ツール](/openai-agents-js/ja/guides/tools#agents-as-tools)をご覧ください。 +このパターンではマネージャーは制御を渡しません。LLM がツールを使い、マネージャーが最終回答を要約します。詳しくは [ツール](/openai-agents-js/ja/guides/tools#agents-as-tools) ガイドを参照してください。 - + ### ハンドオフ -ハンドオフでは、トリアージ エージェントがリクエストを振り分けますが、いったんハンドオフが発生すると、専門エージェントが最終出力を生成するまで会話を所有します。これによりプロンプトが短くなり、各エージェントを独立して考えることができます。詳しくは[ハンドオフ](/openai-agents-js/ja/guides/handoffs)をご覧ください。 +ハンドオフではトリアージ用エージェントがリクエストを振り分けますが、ハンドオフ後は専門エージェントが最終出力を生成するまで会話を所有します。これによりプロンプトを短く保ち、各エージェントを独立に考察できます。詳しくは [ハンドオフ](/openai-agents-js/ja/guides/handoffs) ガイドをご覧ください。 - + --- ## 動的 instructions -`instructions` は文字列ではなく **関数** にすることもできます。この関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返せます。 +`instructions` は文字列の代わりに **関数** にできます。この関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返せます。 -同期関数と `async` 関数の両方をサポートします。 +同期関数と `async` 関数の両方がサポートされています。 --- ## ライフサイクルフック -高度なユースケースでは、イベントをリッスンして Agent のライフサイクルを観測できます。利用可能な内容は、[こちら](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts)に記載のエージェントフックのイベント名を参照してください。 +高度なユースケースでは、イベントをリッスンしてエージェントのライフサイクルを観測できます。利用可能なものについては、[こちら](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 が決定 +1. `'auto'`（デフォルト）– ツールを使うかどうかを LLM が判断 2. `'required'` – LLM はツールを _必ず_ 呼び出す（どれを使うかは選べる） 3. `'none'` – LLM はツールを呼び出しては **ならない** 4. 特定のツール名（例: `'calculator'`）– そのツールを必ず呼び出す - + ### 無限ループの防止 -ツール呼び出し後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツールを繰り返し呼び出す無限ループに入ることを防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 +ツール呼び出しの後、SDK は自動的に `tool_choice` を `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループへの突入を防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。 -- `'run_llm_again'`（デフォルト）– ツール結果を使って LLM を再実行 +- `'run_llm_again'`（デフォルト）– ツール結果を使って LLM を再度実行 - `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う -- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼ばれたら停止 -- `(context, toolResults) => ...` – 実行終了可否を返すカスタム関数 +- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼ばれた時点で停止 +- `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数 ```typescript const agent = new Agent({ @@ -163,6 +179,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 2266464a..e33fd615 100644 --- a/docs/src/content/docs/ja/guides/config.mdx +++ b/docs/src/content/docs/ja/guides/config.mdx @@ -13,20 +13,20 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## API キーとクライアント -既定では、SDK は最初にインポートされたときに環境変数 `OPENAI_API_KEY` を読み取ります。変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出せます。 +デフォルトで SDK は最初の import 時に `OPENAI_API_KEY` 環境変数を読み込みます。変数を設定できない場合は、手動で `setDefaultOpenAIKey()` を呼び出せます。 -独自の `OpenAI` クライアント インスタンスを渡すこともできます。渡さない場合、SDK は既定のキーを使って自動的に作成します。 +独自の `OpenAI` クライアントインスタンスを渡すこともできます。指定がない場合、SDK はデフォルトのキーで自動的に作成します。 最後に、Responses API と Chat Completions API を切り替えられます。 @@ -35,17 +35,17 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t ## トレーシング -トレーシングは既定で有効で、上記の 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* @@ -67,9 +67,9 @@ export DEBUG=openai-agents* -### ログ内の機微データ +### ログ内の機密データ -特定のログにはユーザー データが含まれる場合があります。次の環境変数を設定して無効化できます。 +一部のログには ユーザー データが含まれる場合があります。以下の環境変数を設定して無効化できます。 LLM の入力と出力のロギングを無効化するには: diff --git a/docs/src/content/docs/ja/guides/context.mdx b/docs/src/content/docs/ja/guides/context.mdx index dd8e3eed..d033cae1 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` ラッパーを受け取り、そのオブジェクトを読み書きできます。 -1 回の実行に参加するすべてのエージェント、ツール、フックは同じ **型** のコンテキストを使う必要があります。 +単一の実行に参加するすべてのエージェント、ツール、フックは、同じコンテキストの**型**を使用する必要があります。 -ローカルコンテキストの用途例: +ローカルコンテキストは次のような用途に使います: - 実行に関するデータ（ユーザー名、ID など） - ロガーやデータフェッチャーなどの依存関係 - ヘルパー関数 -## エージェント / LLM コンテキスト +## エージェント/LLM コンテキスト -LLM が呼び出されると、参照できるのは会話履歴から来るデータのみです。追加情報を利用可能にするには次の選択肢があります。 +LLM が呼び出されると、参照できるデータは会話履歴のみです。追加情報を利用可能にするには次のオプションがあります。 -1. エージェントの `instructions` に追加する（system または developer メッセージとも呼ばれます）。静的な文字列でも、コンテキストを受け取って文字列を返す関数でも構いません -2. `Runner.run()` を呼び出すときに `input` に含める。これは instructions の手法に似ていますが、メッセージを [指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます -3. 関数ツール経由で公開し、LLM がオンデマンドでデータを取得できるようにする -4. リトリーバルや Web 検索ツールを使って、ファイル、データベース、または Web の関連データに基づいて応答を支える +1. エージェントの `instructions` に追加する（システムまたはデベロッパーメッセージとも呼ばれます）。これは静的な文字列でも、コンテキストを受け取って文字列を返す関数でも構いません +2. `Runner.run()` を呼び出す際の `input` に含める。instructions と同様の手法ですが、メッセージを [指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置できます +3. 関数ツールを通じて公開し、LLM がオンデマンドでデータを取得できるようにする +4. リトリーバルや Web 検索ツールを使って、ファイル、データベース、Web の関連データに基づいて応答をグラウンディングする diff --git a/docs/src/content/docs/ja/guides/guardrails.mdx b/docs/src/content/docs/ja/guides/guardrails.mdx index acc8b043..6c61595b 100644 --- a/docs/src/content/docs/ja/guides/guardrails.mdx +++ b/docs/src/content/docs/ja/guides/guardrails.mdx @@ -7,42 +7,42 @@ import { Code } from '@astrojs/starlight/components'; import inputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-input.ts?raw'; import outputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-output.ts?raw'; -ガードレールはエージェントと _並行して_ 実行され、ユーザー入力やエージェント出力に対してチェックや検証を行えます。たとえば、コストの高いモデルを呼び出す前に軽量なモデルをガードレールとして実行できます。悪意のある使用をガードレールが検知した場合、エラーを発生させて高コストなモデルの実行を停止できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力やエージェント出力に対してチェックやバリデーションを行えます。たとえば、高コストなモデルを呼び出す前に軽量モデルをガードレールとして実行できます。悪意ある利用を検知した場合、エラーを発生させて高コストなモデルの実行を停止できます。 -ガードレールには 2 種類あります: +ガードレールには 2 種類あります。 -1. **入力ガードレール** は初回のユーザー入力に対して実行されます -2. **出力ガードレール** は最終的なエージェントの出力に対して実行されます +1. **Input guardrails** は初回のユーザー入力で実行されます +2. **Output guardrails** はエージェントの最終出力で実行されます ## 入力ガードレール -入力ガードレールは次の 3 ステップで実行されます: +入力ガードレールは 3 つの手順で実行されます。 1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) に包んで返します -3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーが送出されます +2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult) でラップしたものを返します +3. `tripwireTriggered` が `true` の場合、[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) エラーがスローされます > **Note** -> 入力ガードレールはユーザー入力向けであり、ワークフローでそのエージェントが _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。異なるエージェントでは異なるガードレールが必要になることが多いためです。 +> 入力ガードレールはユーザー入力を対象としているため、ワークフロー内でエージェントが _最初_ のエージェントである場合にのみ実行されます。ガードレールはエージェントごとに設定します。これは、エージェントごとに必要なガードレールが異なることが多いためです。 ## 出力ガードレール -出力ガードレールは次の 3 ステップで実行されます: +出力ガードレールは 3 つの手順で実行されます。 1. ガードレールはエージェントが生成した出力を受け取ります -2. ガードレール関数が実行され、[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput) を [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult) に包んで返します -3. `tripwireTriggered` が `true` の場合、[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) エラーが送出されます +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` はガードレール関数内で使用されます -2. ガードレール関数はエージェントの入力または出力を受け取り、結果を返します -3. 追加情報をガードレールの結果に含めることができます +2. ガードレール関数はエージェントの入力または出力を受け取り、その結果を返します +3. 追加情報をガードレール結果に含めることができます 4. `agent` はガードレールが適用される実際のワークフローを定義します diff --git a/docs/src/content/docs/ja/guides/handoffs.mdx b/docs/src/content/docs/ja/guides/handoffs.mdx index 14fb88b7..605ae90d 100644 --- a/docs/src/content/docs/ja/guides/handoffs.mdx +++ b/docs/src/content/docs/ja/guides/handoffs.mdx @@ -10,17 +10,17 @@ 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()` によるハンドオフのカスタマイズ @@ -29,35 +29,35 @@ import recommendedPromptExample from '../../../../../../examples/docs/handoffs/r - `agent` – ハンドオフ先のエージェント - `toolNameOverride` – 既定の `transfer_to_` ツール名を上書き - `toolDescriptionOverride` – 既定のツール説明を上書き -- `onHandoff` – ハンドオフ発生時のコールバック。`RunContext` と、必要に応じて解析済み入力を受け取る +- `onHandoff` – ハンドオフ時のコールバック。`RunContext` と、必要に応じて解析済みの入力を受け取ります - `inputType` – ハンドオフに期待する入力スキーマ - `inputFilter` – 次のエージェントに渡す履歴のフィルター ## ハンドオフ入力 -ハンドオフの呼び出し時に LLM にデータを提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 +ハンドオフを呼び出す際に LLM にデータを提供させたい場合があります。入力スキーマを定義し、`handoff()` で使用します。 - + ## 入力フィルター -既定では、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。 +デフォルトでは、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、`inputFilter` を指定します。 一般的なヘルパーは `@openai/agents-core/extensions` にあります。 - + ## 推奨プロンプト -プロンプトでハンドオフに言及すると、LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` を通じて推奨プレフィックスを提供します。 +プロンプトでハンドオフに言及すると、LLM はより安定して応答します。SDK は `RECOMMENDED_PROMPT_PREFIX` を通じて推奨のプレフィックスを提供します。 diff --git a/docs/src/content/docs/ja/guides/human-in-the-loop.mdx b/docs/src/content/docs/ja/guides/human-in-the-loop.mdx index 3eae8fe9..c8d563f5 100644 --- a/docs/src/content/docs/ja/guides/human-in-the-loop.mdx +++ b/docs/src/content/docs/ja/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 に組み込まれた Human in the loop (人間の介入) サポートを使って、人の介入に基づきエージェントの実行を一時停止・再開する方法を説明します。 +このガイドでは、SDK に組み込まれた Human in the loop（人間の介入）サポートを使って、人的介入に基づきエージェントの実行を一時停止・再開する方法を説明します。 -現在の主なユースケースは、機微なツール実行の承認を求めることです。 +現時点での主なユースケースは、機微なツール実行に対する承認の取得です。 ## 承認リクエスト -`needsApproval` オプションを `true`、または真偽値を返す非同期関数に設定すると、承認が必要なツールを定義できます。 +`needsApproval` オプションを `true`、または boolean を返す非同期関数に設定することで、承認が必要なツールを定義できます。 -動作するエンドツーエンド版は、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。 +エンドツーエンドで動作する版は、[完全なサンプルスクリプト](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts)をご覧ください。 -## 承認に時間がかかる場合の対処 +## 長時間の承認への対処 -Human in the loop (人間の介入) フローは、サーバーを動かし続けることなく長時間中断できるよう設計されています。いったんリクエストを終了し、後で続ける必要がある場合は、状態をシリアライズして後から再開できます。 +Human in the loop のフローは、サーバーを稼働し続けなくても長時間の中断に対応できるよう設計されています。リクエストをいったん停止して後で続行したい場合は、状態をシリアライズして後から再開できます。 -`JSON.stringify(result.state)` で状態をシリアライズし、後で `RunState.fromString(agent, serializedState)` にシリアライズ済み状態を渡して再開できます。ここで `agent` は全体の実行を開始したエージェントのインスタンスです。 +状態は `JSON.stringify(result.state)` を使ってシリアライズでき、後から `RunState.fromString(agent, serializedState)` にシリアライズ済み状態を渡すことで再開できます。ここで `agent` は全体の実行をトリガーしたエージェントのインスタンスです。 -この方法なら、シリアライズした状態をデータベースやリクエストと一緒に保存できます。 +この方法により、シリアライズした状態をデータベースやリクエストと一緒に保存できます。 ### 保留タスクのバージョニング -承認リクエストに時間がかかり、エージェント定義を意味のある形でバージョン管理したい、または Agents SDK のバージョンを上げたい場合は、パッケージエイリアスを使って 2 つの Agents SDK を並行インストールし、独自の分岐ロジックを実装することを現在は推奨します。 +承認リクエストに時間がかかり、エージェント定義を意味のある形でバージョン管理したい、または Agents SDK のバージョンを更新したい場合は、パッケージエイリアスを用いて 2 つの Agents SDK バージョンを並行インストールし、独自の分岐ロジックを実装することを現時点では推奨します。 -実務上は、自分のコードにバージョン番号を付与してシリアライズした状態と一緒に保存し、デシリアライズ時に正しいコードのバージョンへ誘導することを意味します。 +実務上は、自分のコードにバージョン番号を付与し、それをシリアライズした状態とともに保存し、デシリアライズを自分のコードの正しいバージョンへ誘導することを意味します。 diff --git a/docs/src/content/docs/ja/guides/mcp.mdx b/docs/src/content/docs/ja/guides/mcp.mdx index 9b787e76..0dd59e9e 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -13,61 +13,65 @@ import streamableHttpExample from '../../../../../../examples/docs/mcp/streamabl import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; -The [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールやコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLMs にツールとコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP のドキュメントより: -> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. +> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。USB‑C がさまざまな周辺機器やアクセサリーにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 -この SDK がサポートする MCP サーバーの種類は 3 つあります: +この SDK がサポートする MCP サーバーは 3 種類あります: -1. **Hosted 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 トランスポート](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** | -| 標準入出力プロトコルのみをサポートするローカル 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. Hosted MCP サーバーツール +## 1. リモート MCP サーバーツール -組み込みツール（Hosted）は、往復の処理全体をモデルに任せます。あなたのコードが MCP サーバーを呼ぶ代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルにストリーミングします。 +組み込みツール（Hosted）は、往復の処理をすべてモデル側で行います。あなたのコードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルへストリーミングします。 -Hosted MCP ツールを使う最もシンプルな例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡すことで、Hosted MCP サーバーツールの作成に役立ちます。 +以下は組み込み MCP ツールを使う最も簡単な例です。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡すことで、組み込み MCP サーバーツールの作成に役立ちます。 -次に、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行できます: +その後、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）で Agent を実行できます: - + -増分の MCP 結果をストリーミングするには、`Agent` を実行する際に `stream: true` を渡します: +増分の MCP 結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します: -#### 任意の承認フロー +#### オプションの承認フロー -機微な操作では、個々のツール呼び出しに対して人間の承認を要求できます。`requireApproval: 'always'` または、ツール名を `'never'`/`'always'` にマッピングするきめ細かなオブジェクトを渡してください。 +機微な操作には、個々のツール呼び出しに対して人による承認を必須にできます。`requireApproval: 'always'` または、ツール名ごとに `'never'`/`'always'` を指定する詳細なオブジェクトを渡します。 -ツール呼び出しの安全性をプログラムで判断できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または却下できます。人間の承認が必要な場合は、ローカルの 関数ツール と同様に `interruptions` を用いた同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) アプローチが使えます。 +ツール呼び出しの安全性をプログラムで判定できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認・却下できます。人による承認が必要な場合は、ローカルの 関数ツール と同様に `interruptions` を使った同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) アプローチを使えます。 ### コネクタ対応の Hosted サーバー -Hosted MCP は OpenAI コネクタにも対応しています。`serverUrl` を渡す代わりに、コネクタの `connectorId` と `authorization` トークンを渡します。Responses API が認証を処理し、Hosted MCP インターフェースを通じてコネクタのツールを公開します。 +Hosted MCP は OpenAI コネクタにも対応しています。`serverUrl` を指定する代わりに、コネクタの `connectorId` と `authorization` トークンを渡します。Responses API が認証を処理し、組み込み MCP インターフェースを通じてコネクタのツールを公開します。 -この例では、環境変数 `GOOGLE_CALENDAR_AUTHORIZATION` に Google OAuth Playground から取得した OAuth トークンが保持されており、コネクタ対応サーバーが Calendar API を呼び出すことを許可します。ストリーミングもあわせて示す実行可能なサンプルは [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors) を参照してください。 +この例では、`GOOGLE_CALENDAR_AUTHORIZATION` 環境変数に Google OAuth Playground で取得した OAuth トークンを保持し、コネクタ対応サーバーが Calendar API を呼び出せるようにしています。ストリーミングもあわせて実演する実行可能なサンプルは [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors) を参照してください。 -完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + ストリーミング、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 +完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + Streaming、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 ## 2. Streamable HTTP MCP サーバー -エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーと直接やり取りする場合は、サーバーの `url`、`name`、および任意の設定で `MCPServerStreamableHttp` をインスタンス化します: +Agent がローカル・リモートの Streamable HTTP MCP サーバーと直接通信する場合は、サーバーの `url`、`name`、任意の設定で `MCPServerStreamableHttp` をインスタンス化します: -このコンストラクターは、`authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの追加の MCP TypeScript‑SDK オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 +コンストラクターは `authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの MCP TypeScript‑SDK の追加オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。 ## 3. Stdio MCP サーバー -標準入出力のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します: +標準 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` による静的フィルター、またはカスタム関数を渡すことで、各サーバーから公開するツールを制限できます。以下は両方のアプローチを示す複合例です: -レイテンシをさらに下げるには、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を指定すると、既定設定よりも高速に応答が返ることがよくあります。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の推論負荷をサポートしていないため、この Agents SDK の既定は `"low"` になっています。 +より低レイテンシにするには、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を指定すると、既定設定よりも高速に応答が返ることが多いです。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の推論負荷をサポートしていないため、この Agents SDK では既定を `"low"` にしています。 ### 非 GPT-5 モデル -カスタムの `modelSettings` なしで非 GPT-5 のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用的な `modelSettings` にフォールバックします。 +カスタムの `modelSettings` なしで非 GPT-5 のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用の `modelSettings` にフォールバックします。 --- ## OpenAI プロバイダー -既定の `ModelProvider` は OpenAI API を使って名前を解決します。2 つの異なるエンドポイントをサポートします: +既定の `ModelProvider` は OpenAI の API を使って名称を解決します。2 つの異なるエンドポイントをサポートしています。 -| API | 用途 | `setOpenAIAPI()` の呼び出し | -| ---------------- | ---------------------------------------------------------------------------- | --------------------------------------- | -| Chat Completions | 標準的なチャットと Function Calling | `setOpenAIAPI('chat_completions')` | -| Responses | ツール呼び出しや柔軟な出力に対応した新しいストリーミングファーストの生成 API | `setOpenAIAPI('responses')` _(default)_ | +| API | 用途 | `setOpenAIAPI()` の呼び出し | +| ---------------- | -------------------------------------------------------------------- | --------------------------------------- | +| Chat Completions | 標準的なチャットと Function Calling | `setOpenAIAPI('chat_completions')` | +| Responses | ツール呼び出しや柔軟な出力を備えた新しいストリーミング優先の生成 API | `setOpenAIAPI('responses')` _(default)_ | ### 認証 @@ -82,60 +82,60 @@ node my-awesome-agent.js title="既定の OpenAI キーを設定" /> -ネットワーク設定をカスタマイズする必要がある場合は、`setDefaultOpenAIClient(client)` で独自の `OpenAI` クライアントを差し込むこともできます。 +ネットワーク設定をカスタマイズする必要がある場合は、`setDefaultOpenAIClient(client)` を使って独自の `OpenAI` クライアントを差し込むこともできます。 --- ## ModelSettings -`ModelSettings` は OpenAI のパラメーターを反映しますが、プロバイダーに依存しません。 +`ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダーに依存しません。 -| フィールド | 型 | 備考 | +| フィールド | 型 | 注記 | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ | -| `temperature` | `number` | 創造性と決定性のバランス | +| `temperature` | `number` | クリエイティビティ vs. 決定性 | | `topP` | `number` | Nucleus サンプリング | -| `frequencyPenalty` | `number` | 繰り返しトークンの抑制 | -| `presencePenalty` | `number` | 新規トークンの促進 | +| `frequencyPenalty` | `number` | 繰り返し出現するトークンを抑制 | +| `presencePenalty` | `number` | 新しいトークンの出現を促進 | | `toolChoice` | `'auto' \| 'required' \| 'none' \| string` | [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 | -| `parallelToolCalls` | `boolean` | 対応している場合に関数呼び出しの並列実行を許可 | +| `parallelToolCalls` | `boolean` | サポートされている場合に関数呼び出しの並列実行を許可 | | `truncation` | `'auto' \| 'disabled'` | トークンの切り詰め戦略 | | `maxTokens` | `number` | 応答内の最大トークン数 | -| `store` | `boolean` | 応答を永続化して取得 / RAG ワークフローに利用 | -| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 などの推論負荷 | -| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 などのテキスト冗長性 | +| `store` | `boolean` | 取得や RAG ワークフローのために応答を永続化 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 など向けの推論負荷 | +| `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 など向けのテキスト冗長度 | -設定はどちらのレベルにも付与できます: +設定はどちらのレベルにも付与できます。 -`Runner` レベルの設定は、競合するエージェント個別設定を上書きします。 +`Runner` レベルの設定は、競合するエージェントごとの設定を上書きします。 --- ## プロンプト -エージェントには `prompt` パラメーターを設定でき、サーバーに保存されたプロンプト構成を用いてエージェントの動作を制御できます。現在、このオプションは OpenAI の -[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合のみサポートされています。 +エージェントは `prompt` パラメーターで設定できます。これは、エージェントの動作を制御するために使用するサーバー保存のプロンプト構成を示します。現在、このオプションは OpenAI の +[Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合にのみサポートされています。 -| フィールド | 型 | 備考 | -| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | プロンプトの一意な識別子 | -| `version` | `string` | 使用したいプロンプトのバージョン | -| `variables` | `object` | プロンプトに差し込む変数のキー/バリューの組。値は文字列またはテキスト・画像・ファイルなどのコンテンツ入力タイプを指定可能 | +| フィールド | 型 | 注記 | +| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | プロンプトの一意の識別子 | +| `version` | `string` | 使用したいプロンプトのバージョン | +| `variables` | `object` | プロンプトに代入する変数のキー/バリューのペア。値は文字列、またはテキスト・画像・ファイルのようなコンテンツ入力タイプを指定可能 | -tools や instructions など、追加のエージェント設定は、保存済みプロンプトで設定した値を上書きします。 +ツールや instructions などの追加のエージェント設定は、保存済みプロンプトで設定した値を上書きします。 --- ## カスタムモデルプロバイダー -独自のプロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、`Runner` のコンストラクターにプロバイダーを渡します: +独自のプロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、そのプロバイダーを `Runner` のコンストラクターに渡します。 -これによりトレースが [OpenAI ダッシュボード](https://platform.openai.com/traces) に送信され、ワークフローの完全な実行グラフを確認できます。 +これはトレースを [OpenAI dashboard](https://platform.openai.com/traces) に送信し、ワークフローの完全な実行グラフを確認できます。 --- ## 次のステップ -- [エージェントの実行](/openai-agents-js/ja/guides/running-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/tracing) を追加する diff --git a/docs/src/content/docs/ja/guides/multi-agent.md b/docs/src/content/docs/ja/guides/multi-agent.md index 4be518a6..2a8d3a14 100644 --- a/docs/src/content/docs/ja/guides/multi-agent.md +++ b/docs/src/content/docs/ja/guides/multi-agent.md @@ -3,38 +3,38 @@ title: マルチエージェント description: Coordinate the flow between several agents --- -オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが、どの順序で動き、次に何をするかをどのように決めるか、ということです。エージェントをオーケストレーションする方法は主に 2 つあります。 +オーケストレーションとは、アプリ内でのエージェントの流れのことです。どのエージェントがどの順序で実行され、次に何をするかをどのように判断するのか。エージェントをオーケストレーションする主な方法は 2 つあります。 -1. LLM に意思決定させる方法: これは LLM の知能を使って計画し、推論し、それに基づいて取るべき手順を決めます -2. コードによるオーケストレーション: コードでエージェントのフローを決定します +1. LLM に意思決定させる方法：LLM の知性を使って計画・推論し、それに基づいて実行手順を決める方法 +2. コードでオーケストレーションする方法：コードでエージェントの流れを決める方法 -これらのパターンは組み合わせて使えます。それぞれのトレードオフは以下のとおりです。 +これらのパターンは組み合わせて使えます。それぞれのトレードオフについては以下で説明します。 ## LLM によるオーケストレーション -エージェントは、instructions、ツール、ハンドオフを備えた LLM です。これは、オープンエンドなタスクが与えられたときに、LLM が自律的に計画し、ツールを使ってアクションやデータ取得を行い、ハンドオフを使ってサブエージェントにタスクを委譲できることを意味します。たとえば、リサーチ用エージェントには次のようなツールを備えられます。 +エージェントは、instructions、tools、ハンドオフを備えた LLM です。これは、オープンエンドなタスクが与えられたとき、LLM がツールを使ってアクションやデータ取得を行い、ハンドオフでサブエージェントに委譲しながら、自律的にタスクへの取り組み方を計画できることを意味します。たとえば、リサーチエージェントには次のようなツールを備えられます。 -- オンラインで情報を見つけるための Web 検索 -- プロプライエタリデータや接続を検索するためのファイル検索と取得 -- コンピュータ操作を行うための機能 -- データ分析のためのコード実行 -- 計画、レポート作成などに長けた専門エージェントへのハンドオフ +- Web 検索でオンライン情報を探す +- ファイル検索と取得でプロプライエタリデータや接続を横断検索する +- コンピュータ操作でコンピュータ上のアクションを実行する +- コード実行でデータ分析を行う +- 計画やレポート作成などに長けた専門エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、LLM の知能に依存したい場合に最適です。ここで重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、LLM の知性に依存したい場合に有効です。重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、順守すべきパラメーターを明確にする -2. アプリを監視して反復する。問題が起きる箇所を確認し、プロンプトを改善する -3. エージェントに内省と改善を許可する。例えばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させる -4. 何でもできる汎用エージェントではなく、特定タスクに特化して卓越するエージェントを用意する -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練してタスクの上達を図れる +1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーターを明確にする +2. アプリを監視して反復する。問題が起きる箇所を見つけ、プロンプトを改善する +3. エージェントに内省と改善を許可する。たとえばループで実行し自己批評させる、あるいはエラーメッセージを提供して改善させる +4. 何でもできる汎用エージェントではなく、1 つのタスクに特化して優れた専門エージェントを用意する +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練してタスクの熟達度を高められます ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度、コスト、パフォーマンスの観点でより決定論的かつ予測可能にできます。よくあるパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・パフォーマンスの面でより決定論的で予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる適切な形式のデータを生成する。例えば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選ぶ -- 複数のエージェントを、あるエージェントの出力を次のエージェントの入力に変換して連鎖させる。ブログ投稿の執筆のようなタスクを、調査、アウトライン作成、ブログ投稿の執筆、批評、その後の改善といった一連のステップに分解する -- タスクを実行するエージェントと、それを評価してフィードバックを与えるエージェントを `while` ループで回し、評価者が出力が一定の基準を満たしたと判断するまで繰り返す -- 複数のエージェントを並列に実行する。例えば `Promise.all` のような JavaScript の基本コンポーネントを使う。相互依存しない複数タスクがある場合に速度面で有用 +- [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 46e5b331..22205efc 100644 --- a/docs/src/content/docs/ja/guides/quickstart.mdx +++ b/docs/src/content/docs/ja/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. プロジェクトを作成して npm を初期化します。これは一度だけ行えば大丈夫です。 +1. プロジェクトを作成して npm を初期化します。これは一度だけで大丈夫です。 ```bash mkdir my_project @@ -25,20 +25,20 @@ 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 キーを作成するために [these instructions](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従ってください。 ```bash export OPENAI_API_KEY=sk-... ``` - 代わりに、`setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、トレーシングには `setTracingExportApiKey('')` を使用できます。 - 詳細は[SDK の設定](/openai-agents-js/ja/guides/config)をご覧ください。 + あるいは `setDefaultOpenAIKey('')` を呼び出してプログラムからキーを設定し、トレーシング用に `setTracingExportApiKey('')` を使用できます。 + 詳細は [SDK の設定](/openai-agents-js/ja/guides/config) を参照してください。 ## はじめてのエージェントの作成 -エージェントは instructions と名前で定義します。 +エージェントは instructions と name で定義します。 ```typescript import { Agent } from '@openai/agents'; @@ -52,9 +52,9 @@ const agent = new Agent({ ## はじめてのエージェントの実行 -`run` メソッドでエージェントを実行できます。開始するエージェントと渡したい入力の両方を渡して実行をトリガーします。 +`run` メソッドでエージェントを実行できます。開始したいエージェントと、渡したい input の両方を指定して実行します。 -これにより、その実行中に行われた最終出力とあらゆるアクションを含むエージェントの実行結果が返されます。 +これは、その実行中に行われた最終出力とあらゆるアクションを含む 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'; @@ -99,9 +99,9 @@ const agent = new Agent({ }); ``` -## いくつかのエージェントの追加 +## さらにいくつかのエージェントの追加 -追加のエージェントを同様に定義して、問題を小さな部分に分解し、エージェントが目の前の作業により集中できるようにします。これはまた、エージェントでモデルを定義することで、異なる問題に対して異なるモデルを使えるようにします。 +追加のエージェントを同様に定義して、問題を小さな部分に分割し、エージェントが現在のタスクにより集中できるようにします。エージェントごとに 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({ }); ``` -実行後、結果の `finalAgent` プロパティを確認すると、どのエージェントが最終応答を生成したかが分かります。 +実行後、result の `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 ダッシュボードの 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 ed6bec2c..84248f6c 100644 --- a/docs/src/content/docs/ja/guides/release.mdx +++ b/docs/src/content/docs/ja/guides/release.mdx @@ -5,17 +5,17 @@ description: Learn how we version and release the SDK and recent changes. ## バージョニング -本プロジェクトは、`0.Y.Z` 形式のやや修正したセマンティック バージョニングに従います。先頭の `0` は SDK が依然として急速に進化していることを示します。各コンポーネントは次のように増分します。 +このプロジェクトは、`0.Y.Z` 形式を用いたやや改変したセマンティック バージョニングに従います。先頭の `0` は SDK が依然として急速に進化していることを示します。各コンポーネントは次のように増分します。 ## マイナー（`Y`）バージョン -ベータと明示されていない公開インターフェースに対する **破壊的変更** がある場合、マイナー バージョン `Y` を増やします。たとえば、`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.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 0744d9c4..b7daf816 100644 --- a/docs/src/content/docs/ja/guides/results.mdx +++ b/docs/src/content/docs/ja/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/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 スキーマを定義している場合。出力はこのスキーマに自動的にパースされます +- `string` — `outputType` が定義されていないエージェントのデフォルト +- `unknown` — 出力タイプとして JSON スキーマが定義されている場合。この場合、JSON はパース済みですが型は手動で検証する必要があります +- `z.infer` — 出力タイプとして Zod スキーマが定義されている場合。出力は自動的にこのスキーマでパースされます - `undefined` — エージェントが出力を生成しなかった場合（たとえば出力を生成する前に停止した場合） -異なる出力タイプを伴うハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクターではなく `Agent.create()` メソッドを使用してください。 +異なる出力タイプのハンドオフを使用している場合は、エージェントの作成に `new Agent()` コンストラクタではなく `Agent.create()` メソッドを使用してください。 これにより、SDK がすべての可能なハンドオフにわたる出力タイプを推論し、`finalOutput` プロパティに対してユニオン型を提供できるようになります。 @@ -33,57 +33,57 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? title="Handoff final output types" /> -## 次ターンの入力 +## 次のターンの入力 -次ターンの入力にアクセスする方法は 2 つあります: +次のターンの入力へアクセスする方法は 2 つあります。 -- `result.history` — 入力とエージェントの出力の両方のコピーを保持 -- `result.output` — エージェント全体の実行結果の出力を保持 +- `result.history` — あなたの入力とエージェントの出力の両方のコピーを含みます +- `result.output` — エージェント全体の実行の出力を含みます -`history` は、チャットのようなユースケースで完全な履歴を維持するのに便利です: +`history` は、チャットのようなユースケースで完全な履歴を保持するのに便利です。 ## 最後のエージェント -`lastAgent` プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、これは次回 ユーザー が何かを入力する際に役立ちます。例えば、フロントラインのトリアージ エージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存し、次回 ユーザー がエージェントにメッセージを送るときに再利用できます。 +`lastAgent` プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、次回のユーザー入力時に有用です。たとえば、フロントラインのトリアージ エージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存しておき、ユーザーが次にエージェントにメッセージを送る際に再利用できます。 -ストリーミング モードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスするのも有用です。 +ストリーミングモードでは、現在実行中のエージェントに対応する `currentAgent` プロパティへアクセスすることも有用です。 ## 新規アイテム -`newItems` プロパティには、実行中に生成された新しいアイテムが入ります。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。実行アイテムは、LLM が生成した 元 アイテムをラップします。これにより、LLM の出力に加えて、どのエージェントに関連するイベントかにアクセスできます。 +`newItems` プロパティには、実行中に生成された新規アイテムが含まれます。アイテムは [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem) です。ランアイテムは LLM が生成した元アイテムをラップします。これにより、LLM の出力に加えて、どのエージェントに関連付けられたイベントかを参照できます。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は、LLM からのメッセージを示します。元アイテムは生成されたメッセージです -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は、LLM がハンドオフ ツールを呼び出したことを示します。元アイテムは LLM からのツール呼び出しアイテムです -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) は、ハンドオフが発生したことを示します。元アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます -- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は、LLM がツールを呼び出したことを示します -- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) は、ツールが呼び出されたことを示します。元アイテムはツール応答です。アイテムからツール出力にもアクセスできます -- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は、LLM からのリースニング項目を示します。元アイテムは生成されたリースニングです -- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は、LLM がツール呼び出しの承認を要求したことを示します。元アイテムは LLM からのツール呼び出しアイテムです +- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) は LLM からのメッセージを示します。元アイテムは生成されたメッセージです +- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) は LLM がハンドオフ ツールを呼び出したことを示します。元アイテムは LLM からのツール呼び出しアイテムです +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) はハンドオフが発生したことを示します。元アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます +- [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) は LLM がツールを起動したことを示します +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) はツールが呼び出されたことを示します。元アイテムはツールの応答です。アイテムからツール出力にもアクセスできます +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) は LLM からの reasoning アイテムを示します。元アイテムは生成された reasoning です +- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) は LLM がツール呼び出しの承認を要求したことを示します。元アイテムは LLM からのツール呼び出しアイテムです ## 状態 -`state` プロパティには、実行の状態が入ります。`result` に付随するほとんどの情報は `state` から導出されますが、`state` はシリアライズ/デシリアライズ可能で、エラーからの[復旧](/openai-agents-js/ja/guides/running-agents#exceptions)や[`interruption`](#interruptions) への対処が必要な場合に、後続の `run` 呼び出しの入力としても使用できます。 +`state` プロパティには実行の状態が含まれます。`result` に付随する多くの情報は `state` から導出されますが、`state` はシリアライズ/デシリアライズ可能で、[エラーからの復旧](/openai-agents-js/ja/guides/running-agents#exceptions)や[`interruption`](#interruptions)への対応が必要な場合に、後続の `run` 呼び出しの入力としても使用できます。 -## 中断 +## 割り込み -エージェントで `needsApproval` を使用している場合、続行前に処理が必要な `interruptions` が `run` によってトリガーされることがあります。その場合、`interruptions` は中断を引き起こした `ToolApprovalItem` の配列になります。中断への対処方法の詳細は、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) を参照してください。 +エージェントで `needsApproval` を使用している場合、続行前に対処すべき `interruptions` が発生することがあります。その場合、`interruptions` は割り込みの原因となった `ToolApprovalItem` の配列になります。割り込みへの対応方法の詳細は、[人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop)を参照してください。 ## その他の情報 ### 元レスポンス -`rawResponses` プロパティには、エージェントの実行中にモデルが生成した 元 の LLM レスポンスが入ります。 +`rawResponses` プロパティには、エージェント実行中にモデルが生成した元の LLM レスポンスが含まれます。 -### 最終レスポンス ID +### 最後のレスポンス ID -`lastResponseId` プロパティには、エージェントの実行中にモデルが生成した最後のレスポンスの ID が入ります。 +`lastResponseId` プロパティには、エージェント実行中にモデルが生成した最後のレスポンスの ID が含まれます。 -### ガードレールの結果 +### ガードレール結果 -`inputGuardrailResults` と `outputGuardrailResults` プロパティには、存在する場合にガードレールの結果が入ります。ガードレールの結果には、ログや保存を行いたい有用な情報が含まれることがあるため、これらを参照できるようにしています。 +`inputGuardrailResults` と `outputGuardrailResults` プロパティには、存在する場合はガードレールの結果が含まれます。ガードレール結果には、ログ記録や保存に有用な情報が含まれることがあるため、参照できるようにしています。 ### 元の入力 -`input` プロパティには、run メソッドに提供した元の入力が入ります。ほとんどの場合は不要ですが、必要に応じて利用できます。 +`input` プロパティには、run メソッドに提供した元の入力が含まれます。多くの場合は不要ですが、必要な場合に備えて利用できます。 diff --git a/docs/src/content/docs/ja/guides/running-agents.mdx b/docs/src/content/docs/ja/guides/running-agents.mdx index 36a2a189..2c5df354 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -11,109 +11,109 @@ import chatLoopExample from '../../../../../../examples/docs/running-agents/chat import conversationIdExample from '../../../../../../examples/docs/running-agents/conversationId.ts?raw'; import previousResponseIdExample from '../../../../../../examples/docs/running-agents/previousResponseId.ts?raw'; -エージェントはそれ自体では何もしません。`Runner` クラスまたは `run()` ユーティリティで実行します。 +エージェントはそれ自体では何もしません。`Runner` クラスまたは `run()` ユーティリティでエージェントを **実行** します。 カスタム runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスを実行する `run()` ユーティリティも使えます。 -あるいは、独自の runner インスタンスを作成できます。 +または、独自の runner インスタンスを作成できます。 -エージェントを実行すると、最終出力と実行の完全な履歴を含む[エージェントの実行結果](/openai-agents-js/ja/guides/results)オブジェクトを受け取ります。 +エージェントの実行後、最終出力と実行の完全な履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 ## エージェントループ -Runner の run メソッドを使うときは、開始するエージェントと入力を渡します。入力は文字列（ユーザー メッセージとして扱われます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。 +Runner の run メソッドを使うときは、開始するエージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）か、OpenAI Responses API のアイテムである入力アイテムの一覧のいずれかです。 runner は次のループを実行します。 1. 現在の入力で現在のエージェントのモデルを呼び出す 2. LLM の応答を検査する - - **最終出力** → 戻る - - **ハンドオフ** → 新しいエージェントに切り替え、累積した会話履歴を保持し、1 に戻る - - **ツール呼び出し** → ツールを実行し、その結果を会話に追加して、1 に戻る -3. `maxTurns` に到達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) を投げる + - **Final output** → return + - **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` | – | すべてのツール / ガードレール / ハンドオフに転送されるコンテキストオブジェクト。詳細は[コンテキスト管理](/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` | すべてのスパンに付与する任意のメタデータ | +| Field | Type | Purpose | +| --------------------------- | --------------------- | ---------------------------------------------------------------------------------------- | +| `model` | `string \| Model` | 実行内の **すべての** エージェントに特定のモデルを強制します | +| `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI プロバイダーです | +| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニング パラメーター | +| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフの実行時に入力アイテムを変更します（ハンドオフ自体で既に定義されていない場合） | +| `inputGuardrails` | `InputGuardrail[]` | 最初のユーザー入力に適用されるガードレール | +| `outputGuardrails` | `OutputGuardrail[]` | 最終出力に適用されるガードレール | +| `tracingDisabled` | `boolean` | OpenAI トレーシングを完全に無効化します | +| `traceIncludeSensitiveData` | `boolean` | スパンは発行しつつ、トレースから LLM/ツールの入力・出力を除外します | +| `workflowName` | `string` | Traces ダッシュボードに表示されます。関連する実行をグループ化するのに役立ちます | +| `traceId` / `groupId` | `string` | SDK に生成させる代わりに、トレース ID またはグループ ID を手動で指定します | +| `traceMetadata` | `Record` | すべてのスパンに付与する任意のメタデータ | ## 会話 / チャットスレッド -`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における 1 回の**ターン**を表します。エンドユーザーにどれだけの `RunResult` を見せるかは任意です。`finalOutput` のみの場合もあれば、生成されたすべてのアイテムを見せる場合もあります。 +`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーション レベルの会話における 1 回の **ターン** を表します。エンドユーザーにどの程度の `RunResult` を見せるかは自由です。`finalOutput` のみのときもあれば、生成されたすべてのアイテムのときもあります。 -インタラクティブ版は[the chat example](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts)を参照してください。 +インタラクティブ版は [the chat example](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 を毎ターンで再利用できます。SDK は新たに生成されたアイテムのみを自動的に含めます。 -#### 2. 直前のターンから続けるための `previousResponseId` +#### 2. 直前のターンから継続するための `previousResponseId` -とにかく Responses API だけで開始したい場合は、前のレスポンスから返された ID を使って各リクエストを連結できます。これにより、会話リソースを作成せずにターン間でコンテキストを保持できます。 +いずれにせよ最初から Responses API のみで始めたい場合は、前のレスポンスから返された ID を使って各リクエストをチェーンできます。これにより、完全な会話リソースを作らずにターン間でコンテキストを維持できます。 ## 例外 @@ -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) – 構成またはユーザー入力に基づいてスローされたエラー +- [`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/tools)を提供する -- 本番対応のために[ガードレール](/openai-agents-js/ja/guides/guardrails)や[トレーシング](/openai-agents-js/ja/guides/tracing)を追加する +- [モデル](/openai-agents-js/ja/guides/models) の構成方法を学ぶ +- エージェントに [ツール](/openai-agents-js/ja/guides/tools) を提供する +- 本番運用に向けて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加する diff --git a/docs/src/content/docs/ja/guides/sessions.mdx b/docs/src/content/docs/ja/guides/sessions.mdx index c79a10d2..35697bfa 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 が処理します。セッションがある場合、ランナーは自動的に次を行います。 +セッションは Agents SDK に**永続的なメモリレイヤー**を与えます。`Session` インターフェースを実装する任意のオブジェクトを `Runner.run` に渡すだけで、残りは SDK が処理します。セッションがある場合、runner は自動的に次を行います。 1. 以前に保存された会話アイテムを取得し、次のターンの先頭に追加する -2. 各実行完了後に新しいユーザー入力とアシスタント出力を永続化する -3. 新しいユーザー文でランナーを呼ぶ場合も、中断された `RunState` から再開する場合も、将来のターンのためにセッションを利用可能な状態に保つ +2. 各実行完了後に新しい user 入力と assistant 出力を永続化する +3. 新しい user テキストで runner を呼び出す場合も、中断された `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 がセッションを使用する方法 -- **各実行の前** にセッション履歴を取得し、新しいターンの入力とマージして、結合済みリストをエージェントへ渡す -- **非ストリーミング実行の後** は、1 回の `session.addItems()` 呼び出しで直近ターンの元のユーザー入力とモデル出力の両方を永続化する -- **ストリーミング実行では** まずユーザー入力を書き込み、ターン完了時にストリームされた出力を追記する -- **`RunResult.state` からの再開時**（承認やその他の中断）も同じ `session` を渡し続ける。再開したターンは入力の再準備なしにメモリへ追加される +- **各実行前** にセッションの履歴を取得し、新しいターンの入力とマージして、結合されたリストをエージェントに渡します +- **非ストリーミング実行後** は `session.addItems()` の 1 回の呼び出しで、元の user 入力と直近のターンのモデル出力の両方を永続化します +- **ストリーミング実行では** まず user 入力を書き込み、ターン完了時にストリームされた出力を追記します +- **`RunResult.state` からの再開時**（承認などの中断）には、同じ `session` を渡し続けてください。再開したターンは入力の再準備なしでメモリに追加されます --- ## 履歴の確認と編集 -セッションはシンプルな CRUD ヘルパーを公開しているため、「取り消し」や「チャットのクリア」、監査機能を構築できます。 +セッションはシンプルな CRUD ヘルパーを公開しており、「取り消し」「チャット消去」や監査機能を実装できます。 -`session.getItems()` は保存済みの `AgentInputItem[]` を返します。`popItem()` を呼ぶと最後のエントリを削除できます。エージェントを再実行する前のユーザーの修正に役立ちます。 +`session.getItems()` は保存済みの `AgentInputItem[]` を返します。`popItem()` を呼び出すと最後のエントリを削除できます。エージェントを再実行する前の user の修正に便利です。 --- -## 独自ストレージの利用 +## 任意のストレージを使用 -`Session` インターフェースを実装して、Redis、DynamoDB、SQLite、その他のデータストアでメモリを裏付けできます。必要なのは 5 つの非同期メソッドだけです。 +`Session` インターフェースを実装して、Redis、DynamoDB、SQLite、その他のデータストアでメモリを支えることができます。必要なのは 5 つの非同期メソッドだけです。 -カスタムセッションにより、保持ポリシーの適用、暗号化の追加、または永続化前に各会話ターンへメタデータを付与できます。 +カスタムセッションにより、保持ポリシーの適用、暗号化の追加、永続化前に各会話ターンへメタデータを付与することができます。 --- -## 履歴と新規アイテムのマージ制御 +## 履歴と新規アイテムのマージ方法の制御 -実行入力として `AgentInputItem` の配列を渡す場合、`sessionInputCallback` を提供して保存済み履歴とのマージを決定的に制御できます。ランナーは既存の履歴をロードし、**モデル呼び出しの前に** コールバックを呼び出し、返された配列をそのターンの完全な入力としてモデルへ渡します。このフックは古いアイテムのトリミング、ツール結果の重複排除、モデルに見せたいコンテキストだけを強調するのに最適です。 +実行入力として `AgentInputItem` の配列を渡す場合、`sessionInputCallback` を指定して保存済み履歴とのマージを決定的に行えます。runner は既存の履歴を読み込み、**モデル呼び出しの前に** コールバックを呼び出し、返された配列をそのターンの完全な入力としてモデルに渡します。このフックは、古いアイテムのトリミング、ツール結果の重複排除、モデルに見せたいコンテキストのみを強調するのに最適です。 -文字列入力の場合、ランナーは自動で履歴をマージするため、このコールバックは任意です。 +文字列入力の場合、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 bea5ec9f..b577b170 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) を参照してください。 +完全なスクリプトは [the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。プレーンテキストのストリームと raw イベントストリームの両方を表示します。 ## イベントタイプ -ストリームは 3 種類のイベントタイプを返します: +ストリームは次の 3 種類のイベントを送出します: ### raw_model_stream_event @@ -83,7 +83,7 @@ type RunItemStreamEvent = { }; ``` -ハンドオフの payload の例: +ハンドオフのペイロード例: ```json { @@ -118,23 +118,23 @@ type RunAgentUpdatedStreamEvent = { } ``` -## ストリーミング中の Human in the loop（人間の介入） +## ストリーミング中の Human in the loop (人間の介入) -ストリーミングは、実行を一時停止するハンドオフ（たとえばツールに承認が必要な場合）と両立します。ストリームオブジェクトの `interruption` フィールドで割り込みにアクセスでき、各割り込みに対して `state.approve()` または `state.reject()` を呼び出すことで実行を継続できます。`{ stream: true }` で再度実行するとストリーミング出力が再開します。 +ストリーミングは、実行を一時停止するハンドオフ（たとえば、ツールに承認が必要な場合）と両立します。ストリームオブジェクトの `interruption` フィールドで割り込みにアクセスでき、各割り込みに対して `state.approve()` または `state.reject()` を呼び出すことで実行を継続できます。再度 `{ stream: true }` で実行するとストリーミング出力が再開します。 -ユーザーと対話する、より完全な例は +ユーザーと対話する、より包括的な例は [`human-in-the-loop-stream.ts`](https://github.com/openai/openai-agents-js/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 c6686f97..a3c4cbd2 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -10,111 +10,119 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -ツールは エージェント が **行動を実行** できるようにします — データ取得、外部 API 呼び出し、コード実行、さらにはコンピュータも操作できます。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします: +ツールはエージェントに **アクションの実行** を可能にします。データ取得、外部 API 呼び出し、コード実行、さらにはコンピュータの使用まで行えます。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします。 -1. **組み込みツール（Hosted）** – モデルと同じ OpenAI のサーバー上で動作 _(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_ -2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップして LLM が呼び出せるようにする -3. **エージェントをツールとして** – エージェント全体を呼び出し可能なツールとして公開 -4. **ローカル MCP サーバー** – 手元で動く Model Context Protocol サーバーを接続 +1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと並行して実行されます（Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成） +2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップして LLM に呼び出させます +3. **エージェントをツールとして** – エージェント全体を呼び出し可能なツールとして公開します +4. **ローカル MCP サーバー** – あなたのマシンで動作する Model context protocol サーバーを接続します --- ## 1. 組み込みツール（Hosted） -`OpenAIResponsesModel` を使う場合、以下の組み込みツールを追加できます: +`OpenAIResponsesModel` を使うと、以下の組み込みツールを追加できます。 -| ツール | 型文字列 | 目的 | -| ----------------------- | -------------------- | ----------------------------------------------- | -| Web search | `'web_search'` | インターネット検索 | -| File / retrieval search | `'file_search'` | OpenAI 上でホストされる ベクトルストア のクエリ | -| Computer use | `'computer'` | GUI 操作を自動化 | -| Shell | `'shell'` | ホスト上でシェルコマンドを実行 | -| Apply patch | `'apply_patch'` | ホスト上のファイルに V4A 差分を適用 | -| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | -| Image generation | `'image_generation'` | テキストに基づいて画像を生成 | +| 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 差分を適用 | +| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 | +| Image generation | `'image_generation'` | テキストに基づく画像生成 | - + -正確なパラメーターセットは OpenAI Responses API と一致します。`rankingOptions` やセマンティックフィルタなどの高度なオプションについては公式ドキュメントを参照してください。 +厳密なパラメーターは OpenAI Responses API と一致します。`rankingOptions` やセマンティックフィルタなどの高度なオプションは公式ドキュメントを参照してください。 --- ## 2. 関数ツール -`tool()` ヘルパーを使えば **どんな** 関数でもツールにできます。 +`tool()` ヘルパーで **任意** の関数をツールにできます。 ### オプションリファレンス -| フィールド | 必須 | 説明 | -| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `name` | いいえ | 省略時は関数名を使用します（例: `get_weather`） | -| `description` | はい | LLM に提示される、明確で人間が読める説明 | -| `parameters` | はい | Zod スキーマ、または 元 の JSON スキーマオブジェクトのいずれか。Zod parameters を使うと自動的に **strict** モードが有効になります | -| `strict` | いいえ | `true`（デフォルト）の場合、引数が検証に通らなければ SDK はモデルエラーを返します。曖昧なマッチングを許すには `false` に設定します | -| `execute` | はい | `(args, context) => string \| Promise` – ビジネスロジック。2 つ目の引数は省略可能で、`RunContext` です | -| `errorFunction` | いいえ | 内部エラーを ユーザー 向けの文字列に変換するためのカスタムハンドラー `(context, error) => string` | +| Field | Required | Description | +| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | No | 関数名（例: `get_weather`）がデフォルト | +| `description` | Yes | LLM に表示される明確で人間が読める説明 | +| `parameters` | Yes | Zod スキーマまたは raw の JSON スキーマオブジェクトのいずれか。Zod のパラメーターは自動的に **strict** モードを有効化 | +| `strict` | No | `true`（デフォルト）の場合、引数が検証に失敗すると SDK はモデルエラーを返します。曖昧一致にするには `false` に設定 | +| `execute` | Yes | `(args, context) => string \| Promise` – ビジネスロジック。本項目の 2 番目のオプション引数は `RunContext` | +| `errorFunction` | No | 内部エラーをユーザーに見える文字列へ変換するためのカスタムハンドラー `(context, error) => string` | ### 非 strict な JSON スキーマツール -不正確または部分的な入力をモデルに推測させたい場合は、 元 の JSON スキーマを使う際に strict モードを無効化できます: +無効または部分的な入力をモデルに推測させる必要がある場合は、raw の JSON スキーマを使う際に strict モードを無効化できます。 --- ## 3. エージェントをツールとして -会話全体を完全にハンドオフせずに、あるエージェントが別のエージェントを支援してほしい場合があります。`agent.asTool()` を使います: +会話を完全にハンドオフせずに、別のエージェントを _支援_ させたい場合は `agent.asTool()` を使用します。 - + -内部的に SDK は次を行います: +内部的に SDK は次を行います。 - 単一の `input` パラメーターを持つ関数ツールを作成 -- ツールが呼ばれたらその入力でサブエージェントを実行 +- ツールが呼び出されたときに、その入力でサブエージェントを実行 - 最後のメッセージ、または `customOutputExtractor` で抽出された出力を返却 -エージェントをツールとして実行すると、Agents SDK はデフォルト設定でランナーを作成し、関数実行内でそのランナーを使ってエージェントを実行します。`runConfig` や `runOptions` の任意のプロパティを指定したい場合は、`asTool()` メソッドに渡してランナーの挙動をカスタマイズできます。 +エージェントをツールとして実行すると、Agents SDK はデフォルト設定でランナーを作成し、関数実行内でそのランナーを用いてエージェントを実行します。`runConfig` や `runOptions` のプロパティを指定したい場合は、`asTool()` メソッドに渡してランナーの動作をカスタマイズできます。 --- ## 4. MCP サーバー -[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) サーバー経由でツールを公開し、エージェントに接続できます。たとえば `MCPServerStdio` を使って、stdio MCP サーバーを起動・接続できます: +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) サーバーを通じてツールを公開し、エージェントに接続できます。たとえば、`MCPServerStdio` を使って stdio MCP サーバーを起動・接続できます。 - + -完全な例は [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) を参照してください。MCP サーバーツール統合の包括的なガイドをお探しの場合は、[MCP 連携](/openai-agents-js/ja/guides/mcp) を参照してください。 +完全な例は [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) を参照してください。MCP サーバーツール連携の包括的なガイドを探している場合は、[MCP 連携](/openai-agents-js/ja/guides/mcp) を参照してください。 --- -## ツール使用時の動作 +## ツール使用時の挙動 -モデルがツールをいつどのように使うべきか（`tool_choice`、`toolUseBehavior` など）の制御については、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください。 +モデルがいつどのようにツールを使用すべきか（`tool_choice`、`toolUseBehavior` など）の制御については、[エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください。 --- ## ベストプラクティス -- **短く明示的な説明** – ツールが何をするか、いつ使うかを記述 -- **入力の検証** – 可能なら Zod スキーマで厳格な JSON 検証を実施 -- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返し、例外は投げない -- **ツールは単一責務** – 小さく合成可能なツールはモデルの推論精度を高める +- **短く明確な説明** – ツールが _何をするか_ と _いつ使うか_ を記述 +- **入力の検証** – 可能な限り Zod スキーマで厳密な JSON 検証を実施 +- **エラーハンドラーで副作用を避ける** – `errorFunction` は役立つ文字列を返し、例外は投げない +- **ツールは単一責務** – 小さく合成しやすいツールはモデルの推論を改善 --- ## 次のステップ -- [エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) でツール使用の強制について学ぶ +- [ツールの使用を強制する](/openai-agents-js/ja/guides/agents#forcing-tool-use) 方法を学ぶ - ツールの入力や出力を検証するために [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加 -- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種 組み込みツール（Hosted） タイプの TypeDoc リファレンスを参照 +- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツールタイプの TypeDoc リファレンスを確認 diff --git a/docs/src/content/docs/ja/guides/tracing.mdx b/docs/src/content/docs/ja/guides/tracing.mdx index a56033a4..96ae9da8 100644 --- a/docs/src/content/docs/ja/guides/tracing.mdx +++ b/docs/src/content/docs/ja/guides/tracing.mdx @@ -7,24 +7,24 @@ import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw'; -Agents SDK には組み込みのトレーシングが含まれており、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまでを対象にします。[Traces ダッシュボード](https://platform.openai.com/traces) を使って、開発時や本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みのトレーシングがあり、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまでを含みます。[Traces ダッシュボード](https://platform.openai.com/traces)を使って、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 ## エクスポートループのライフサイクル -多くの環境では、トレースは定期的に自動エクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。大量にキューされた場合はトレースがエクスポートされますが、定期的にはエクスポートされません。代わりに、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用し、手動でトレースをエクスポートしてください。 +ほとんどの環境では、トレースは定期的に自動エクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。キューに溜まりすぎた場合はトレースがエクスポートされますが、定期的にはエクスポートされません。代わりに、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を使用して手動でトレースをエクスポートしてください。 -たとえば Cloudflare Worker では、コード全体を `try/catch/finally` ブロックでラップし、`waitUntil` と併用して強制フラッシュすることで、ワーカー終了前にトレースがエクスポートされるようにします。 +たとえば Cloudflare Worker では、コード全体を `try/catch/finally` ブロックでラップし、`waitUntil` と併用して強制フラッシュを行い、ワーカーが終了する前にトレースがエクスポートされるようにします。 ` である必要があります - - `group_id`: 任意のグループ ID。同一の会話からの複数トレースを関連付けるために使用。例えばチャットスレッド ID など +- **Traces** は「ワークフロー」の単一のエンドツーエンドの操作を表します。複数の Span で構成されます。トレースには次のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意の ID。渡さない場合は自動生成。形式は `trace_<32_alphanumeric>` + - `group_id`: 同じ会話からの複数トレースを関連付けるための任意のグループ ID。例えばチャットスレッド ID など - `disabled`: True の場合、トレースは記録されません - - `metadata`: トレースに関する任意のメタデータ -- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります - - `started_at` と `ended_at` のタイムスタンプ + - `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) で名前や他のプロパティを設定できます。 +デフォルトでは、トレース名は "Agent workflow" です。`withTrace` を使用するとこの名前を設定できます。または、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを設定できます。 -さらに、[custom trace processors](#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/ja/guides/voice-agents) を参照してください。 +詳しくは[音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents)を参照してください。 -## 上位レベルのトレース +## 高レベルのトレース -複数の `run()` 呼び出しを単一のトレースに含めたい場合があります。これは、コード全体を `withTrace()` でラップすることで実現できます。 +複数の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合は、コード全体を `withTrace()` でラップします。 -1. 2 回の `run` 呼び出しが `withTrace()` にラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります +1. `withTrace()` で 2 回の `run` 呼び出しをラップしているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります ## トレースの作成 -[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数を使用してトレースを作成できます。あるいは、`getGlobalTraceProvider().createTrace()` を使って手動で新しいトレースを作成し、それを `withTrace()` に渡すこともできます。 +[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数を使用してトレースを作成できます。あるいは、`getGlobalTraceProvider().createTrace()` を使用して新しいトレースを手動で作成し、それを `withTrace()` に渡すこともできます。 -現在のトレースは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルを通じて追跡されます。これにより、自動的に並行実行に対応します。 +現在のトレースは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルで追跡されます。つまり、自動的に並行処理で機能します。 ## スパンの作成 -各種 `create*Span()`（例: `createGenerationSpan()`, `createFunctionSpan()` など）メソッドを使用してスパンを作成できます。一般的には、手動でスパンを作成する必要はありません。カスタムスパン情報を追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数が利用できます。 +さまざまな `create*Span()`（例: `createGenerationSpan()`、`createFunctionSpan()` など）メソッドを使用してスパンを作成できます。一般的にはスパンを手動で作成する必要はありません。カスタムスパン情報を追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 関数も利用できます。 -スパンは自動的に現在のトレースの一部となり、[Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルを通じて追跡される、最も近い現在のスパンの下にネストされます。 +スパンは自動的に現在のトレースの一部となり、[Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または対応する環境のポリフィルで追跡される、最も近い現在のスパンの下にネストされます。 ## 機微なデータ -一部のスパンは、潜在的に機微なデータを取得する場合があります。 +一部のスパンは、機微なデータを取得する可能性があります。 -`createGenerationSpan()` は LLM 生成の入力/出力を、`createFunctionSpan()` は関数呼び出しの入力/出力を保存します。機微なデータが含まれる可能性があるため、[`RunConfig.traceIncludeSensitiveData -`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) を使用して、そのデータの取得を無効化できます。 +`createGenerationSpan()` は LLM 生成の入力/出力を保存し、`createFunctionSpan()` は関数呼び出しの入力/出力を保存します。これらには機微なデータが含まれる可能性があるため、[`RunConfig.traceIncludeSensitiveData +`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) によってそのデータの取得を無効化できます。 -## カスタム トレーシング プロセッサー +## カスタムトレーシングプロセッサー -トレーシングの高レベルなアーキテクチャは次のとおりです: +トレーシングの高レベルアーキテクチャは次のとおりです。 -- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレース作成を担当し、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) からアクセスできます -- `TraceProvider` に [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) を設定し、[`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に対してトレース/スパンをバッチ送信します。これにより、OpenAI のバックエンドへバッチでエクスポートされます +- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレースの作成を担当し、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) を通じてアクセスできます +- `TraceProvider` を [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) で構成し、トレース/スパンをバッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に送信します。これはスパンとトレースをバッチで OpenAI バックエンドにエクスポートします -デフォルト構成をカスタマイズして、別の（または追加の）バックエンドへトレースを送信したり、エクスポーターの動作を変更したい場合は、次の 2 つの方法があります: +このデフォルト構成をカスタマイズし、別のバックエンドへの送信や追加のバックエンドへの送信、エクスポーターの挙動変更を行うには、次の 2 つの方法があります。 -1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) は、トレースやスパンが準備でき次第受け取る、**追加の** トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへトレースを送信するのに加えて、独自の処理を実装できます -2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) は、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換え**られます。これを使用する場合、OpenAI のバックエンドには、送信する `TracingProcessor` を含めない限りトレースは送信されません +1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) は、トレースとスパンが準備でき次第受け取る、**追加の** トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理が可能です +2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) は、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換え**できます。これにより、OpenAI バックエンドにトレースは送信されなくなります（送信する `TracingProcessor` を含めない限り） -## 外部トレーシング プロセッサー一覧 +## 外部トレーシングプロセッサー一覧 - [AgentOps](https://docs.agentops.ai/v2/usage/typescript-sdk#openai-agents-integration) - [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agents-sdk-js) diff --git a/docs/src/content/docs/ja/guides/troubleshooting.mdx b/docs/src/content/docs/ja/guides/troubleshooting.mdx index 6eea399f..93a9b996 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` コンストラクタは不可） リアルタイム用途では `@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`）を使用してください - **ブラウザ**: - ブラウザでは現在トレーシングはサポートされていません - **v8 isolates**: - - 適切なブラウザ polyfill を備えたバンドラーを使えば 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 5cbd2ce1..44c75d63 100644 --- a/docs/src/content/docs/ja/guides/voice-agents.mdx +++ b/docs/src/content/docs/ja/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 の 音声対音声モデルを使用して、リアルタイムの音声チャットを提供します。これらのモデルは、音声・テキスト・ツール呼び出しのストリーミングをサポートし、音声/電話のカスタマーサポート、モバイルアプリ体験、ボイスチャットなどの用途に最適です。 +Voice Agents は OpenAI の音声対音声モデルを使用して、リアルタイムのボイスチャットを提供します。これらのモデルは音声、テキスト、ツール呼び出しのストリーミングをサポートし、音声/電話のカスタマーサポート、モバイルアプリの体験、ボイスチャットといった用途に最適です。 -Voice Agents SDK は、[OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) 向けの TypeScript クライアントを提供します。 +Voice Agents SDK は [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) 用の TypeScript クライアントを提供します。 ### 主な機能 - WebSocket または WebRTC で接続 - ブラウザとバックエンド接続の両方で利用可能 -- 音声と割り込みのハンドリング +- 音声および割り込みの処理 - ハンドオフによるマルチエージェントのオーケストレーション -- ツール定義と呼び出し -- モデル出力を監視するカスタム ガードレール -- ストリーミングイベント用コールバック -- テキストと音声のエージェントで同じコンポーネントを再利用 +- ツールの定義と呼び出し +- モデル出力を監視するカスタムガードレール +- ストリーミングイベント向けのコールバック +- テキストと音声のエージェントの両方で同じコンポーネントを再利用 -音声対音声モデルを使うことで、モデルが動作した後に音声を文字起こしして再度音声に変換し直す必要がなく、音声をリアルタイムに処理するモデルの能力を活用できます。 +音声対音声モデルを使用すると、モデルが動作した後にテキストへ文字起こしして再び音声に変換し直す必要がなく、モデルのリアルタイム音声処理能力を活用できます。 ![音声対音声モデル](https://cdn.openai.com/API/docs/images/diagram-chained-agent.png) diff --git a/docs/src/content/docs/ja/guides/voice-agents/build.mdx b/docs/src/content/docs/ja/guides/voice-agents/build.mdx index 6d85e593..d406b366 100644 --- a/docs/src/content/docs/ja/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ja/guides/voice-agents/build.mdx @@ -28,50 +28,51 @@ import serverAgentExample from '../../../../../../../examples/docs/voice-agents/ import delegationAgentExample from '../../../../../../../examples/docs/voice-agents/delegationAgent.ts?raw'; import turnDetectionExample from '../../../../../../../examples/docs/voice-agents/turnDetection.ts?raw'; -## 音声の取り扱い +## 音声の扱い -デフォルトの `OpenAIRealtimeWebRTC` のような一部のトランスポート層は、音声の入出力を自動で処理します。`OpenAIRealtimeWebSocket` のような他のトランスポートでは、セッションの音声を自分で処理する必要があります: +既定の `OpenAIRealtimeWebRTC` のような一部のトランスポートレイヤーは、音声の入力と出力を自動的に処理します。`OpenAIRealtimeWebSocket` のような他のトランスポートでは、セッションの音声を自分で処理する必要があります: ## セッションの設定 -[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) のコンストラクターに追加オプションを渡すか、`connect(...)` を呼び出すときに渡すことで、セッションを設定できます。 +[`RealtimeSession`](/openai-agents-js/openai/agents-realtime/classes/realtimesession/) のコンストラクターに追加オプションを渡すか、`connect(...)` を呼び出す際にオプションを渡すことで、セッションを設定できます。 -これらのトランスポート層では、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 +これらのトランスポートレイヤーでは、[session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update) に一致する任意のパラメーターを渡せます。 -[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) にまだ存在しない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡したものは `session` オブジェクトの一部としてそのまま渡されます。 +[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/) に対応するパラメーターがまだない新しいパラメーターについては、`providerData` を使用できます。`providerData` に渡したものは `session` オブジェクトの一部としてそのまま渡されます。 ## ハンドオフ -通常のエージェントと同様に、ハンドオフを使ってエージェントを複数のエージェントに分割し、それらをオーケストレーションしてエージェントのパフォーマンスを向上させ、問題のスコープを適切に絞り込めます。 +通常のエージェントと同様に、ハンドオフを使ってエージェントを複数のエージェントに分割し、それらの間をオーケストレーションして、エージェントのパフォーマンスを高め、問題の範囲をより明確にできます。 -通常のエージェントと異なり、Realtime Agents ではハンドオフの挙動が少し異なります。ハンドオフが行われると、進行中のセッションは新しいエージェント設定で更新されます。これにより、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現時点では適用されません。 +通常のエージェントとは異なり、ハンドオフは リアルタイムエージェント では少し動作が異なります。ハンドオフが行われると、進行中のセッションは新しいエージェント設定で更新されます。このため、エージェントは進行中の会話履歴に自動的にアクセスでき、入力フィルターは現在適用されません。 -さらに、ハンドオフの一部として `voice` や `model` を変更することはできません。また、接続できるのは他の Realtime Agents のみです。別のモデル、例えば `gpt-5-mini` のような推論モデルが必要な場合は、[ツールによる委任](#delegation-through-tools) を使用できます。 +さらに、ハンドオフの一部として `voice` や `model` を変更することはできません。また、接続できるのは他の リアルタイムエージェント のみです。別のモデル、たとえば `gpt-5-mini` のような推論モデルを使用する必要がある場合は、[delegation through tools](#delegation-through-tools) を使用できます。 ## ツール -通常のエージェントと同様に、Realtime Agents はアクションを実行するためにツールを呼び出せます。通常のエージェントで使用するのと同じ `tool()` 関数でツールを定義できます。 +通常のエージェントと同様に、リアルタイムエージェントはアクションを実行するためにツールを呼び出せます。通常のエージェントで使用するのと同じ `tool()` 関数でツールを定義できます。 -Realtime Agents で使用できるのは 関数ツール のみで、これらのツールは Realtime Session と同じ場所で実行されます。つまり、ブラウザで Realtime Session を実行している場合、ツールもブラウザで実行されます。より機密性の高い処理が必要な場合は、ツール内からバックエンド サーバー への HTTP リクエストを行ってください。 +リアルタイムエージェントで使用できるのは 関数ツール のみで、これらのツールはリアルタイムセッションと同じ場所で実行されます。つまり、ブラウザでリアルタイムセッションを実行している場合は、ツールもブラウザで実行されます。より機密性の高いアクションを実行する必要がある場合は、ツール内からバックエンド サーバー への HTTP リクエストを実行できます。 -ツールが実行されている間、エージェントは新しい ユーザー からのリクエストを処理できません。体験を改善する方法の 1 つは、ツールの実行直前にアナウンスするようにエージェントに伝えるか、ツールの実行時間を稼ぐための特定のフレーズを言わせることです。 +ツールの実行中、エージェントは ユーザー からの新しいリクエストを処理できません。体験を向上させる 1 つの方法は、ツールの実行直前にアナウンスさせたり、ツール実行のための時間を稼ぐ決まり文句を話すようにエージェントに指示することです。 ### 会話履歴へのアクセス -エージェントが特定のツールを呼び出したときの引数に加えて、Realtime Session が追跡する現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑な処理を行う必要がある場合や、[ツールによる委任](#delegation-through-tools) を使用する予定がある場合に役立ちます。 +エージェントが特定のツールを呼び出した際の引数に加えて、リアルタイムセッションが追跡する現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する必要がある場合や、[tools for delegation](#delegation-through-tools) を使用する予定がある場合に役立ちます。 ### ツール実行前の承認 @@ -89,33 +90,33 @@ Realtime Agents で使用できるのは 関数ツール のみで、これら ## ガードレール -ガードレール は、エージェントの発言が一連のルールに違反していないかを監視し、即座に応答を遮断する方法を提供します。これらのガードレール チェックは、エージェントの応答の文字起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効）。 +ガードレールは、エージェントの発言が一連のルールに違反したかどうかを監視し、違反した場合に即座にレスポンスを遮断する方法を提供します。これらのガードレールチェックはエージェントのレスポンスの書き起こしに基づいて実行されるため、モデルのテキスト出力が有効である必要があります（デフォルトで有効です）。 -提供したガードレールは、モデル応答の返却に合わせて非同期に実行され、あらかじめ定義した分類トリガー（例: 「特定の禁止ワードに言及」）に基づいて応答を遮断できます。 +提供したガードレールは、モデルのレスポンスが返ってくるのと同時に非同期で実行され、あらかじめ定義された分類トリガー（例:「特定の禁止ワードに言及」）に基づいてレスポンスを遮断できます。 ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。このイベントは、ガードレールをトリガーした `itemId` を含む `details` オブジェクトも提供します。 -デフォルトでは、ガードレールは 100 文字ごと、または応答テキストの生成が終了した時点で実行されます。テキストの読み上げには通常より時間がかかるため、ほとんどの場合、ユーザーが聞く前にガードレールが違反を検知できます。 +デフォルトでは、ガードレールは 100 文字ごと、またはレスポンステキストの生成が終了した時点で実行されます。テキストを話し終えるまでには通常それより時間がかかるため、ほとんどの場合、ユーザーが聞く前にガードレールが違反を検出できます。 -この挙動を変更したい場合は、`outputGuardrailSettings` オブジェクトをセッションに渡してください。 +この動作を変更したい場合は、セッションに `outputGuardrailSettings` オブジェクトを渡せます。 -## ターン検出／音声活動検出 +## ターン検出 / 音声活動検出 -Realtime Session は、ユーザーが話しているタイミングを自動検出し、組み込みの [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使って新しいターンをトリガーします。 +リアルタイムセッションは、ユーザーが話しているタイミングを自動的に検出し、組み込みの [Realtime API の音声活動検出モード](https://platform.openai.com/docs/guides/realtime-vad) を使用して新しいターンをトリガーします。 -`turnDetection` オブジェクトをセッションに渡すことで、音声活動検出モードを変更できます。 +音声活動検出モードは、セッションに `turnDetection` オブジェクトを渡すことで変更できます。 -ターン検出設定を調整することで、望ましくない割り込みや無音への対処を調整できます。さまざまな設定の詳細は [Realtime API のドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください。 +ターン検出の設定を調整すると、不要な割り込みのキャリブレーションや無音への対処に役立ちます。各種設定の詳細は [Realtime API ドキュメント](https://platform.openai.com/docs/guides/realtime-vad) を参照してください ## 割り込み -組み込みの音声活動検出を使うと、エージェントの発話にかぶせて話すことで、発話内容に基づいてエージェントが自動的にコンテキストを検出・更新します。また、`audio_interrupted` イベントも発行します。これはすべての音声再生を即座に停止するために使用できます（WebSocket 接続にのみ適用）。 +組み込みの音声活動検出を使用している場合、エージェントの発話にかぶせて話すと、自動的に検出され、発話内容に基づいてコンテキストが更新されます。同時に `audio_interrupted` イベントも発行されます。これは、すべての音声再生を即座に停止するために使用できます（WebSocket 接続にのみ適用）。 @@ -123,42 +124,42 @@ UI に「停止」ボタンを提供するなど、手動で割り込みを行 -いずれの場合も、Realtime Session はエージェントの生成の割り込み、ユーザーに話した内容の切り詰め、履歴の更新を処理します。 +いずれの場合も、リアルタイムセッションはエージェントの生成の中断、ユーザーに話した内容の切り捨て、および履歴の更新を処理します。 -エージェントへの接続に WebRTC を使用している場合は、音声出力もクリアされます。WebSocket を使用している場合は、再生キューに入っている音声の再生停止を自分で処理する必要があります。 +エージェントへの接続に WebRTC を使用している場合は、音声出力もクリアされます。WebSocket を使用している場合は、キューに入っている音声の再生を停止するなど、これを自分で処理する必要があります。 ## テキスト入力 エージェントにテキスト入力を送信したい場合は、`RealtimeSession` の `sendMessage` メソッドを使用できます。 -これは、エージェントとのインターフェースを両方のモダリティで ユーザー に提供したい場合や、会話に追加のコンテキストを提供したい場合に有用です。 +これは、エージェントとのインターフェースを両方のモダリティで有効にしたい場合や、会話に追加のコンテキストを提供したい場合に役立ちます。 ## 会話履歴の管理 -`RealtimeSession` は、`history` プロパティ内で会話履歴を自動的に管理します: +`RealtimeSession` は `history` プロパティで会話履歴を自動管理します: -これを使って、顧客に履歴を表示したり、追加のアクションを実行したりできます。会話の進行に伴い履歴は継続的に変化するため、`history_updated` イベントをリッスンできます。 +これを使用して、顧客に履歴を表示したり、追加の処理を実行したりできます。会話の過程でこの履歴は常に変化するため、`history_updated` イベントをリッスンできます。 -履歴を変更したい場合（メッセージを完全に削除する、または文字起こしを更新するなど）は、`updateHistory` メソッドを使用できます。 +履歴を変更したい場合（メッセージを完全に削除する、または書き起こしを更新するなど）は、`updateHistory` メソッドを使用できます。 ### 制限事項 -1. 現時点では、後から 関数ツール 呼び出しを更新／変更することはできません -2. 履歴内のテキスト出力には、文字起こしとテキスト モダリティの有効化が必要です -3. 割り込みによって切り詰められた応答には文字起こしがありません +1. 現時点では、後から 関数ツール の呼び出しを更新/変更できません +2. 履歴内のテキスト出力には、書き起こしとテキストモダリティが有効である必要があります +3. 割り込みにより切り捨てられたレスポンスには書き起こしが存在しません -## ツールによる委任 +## delegation through tools -![ツールによる委任](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) +![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 43fccdfa..44c74735 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,9 +59,9 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - レスポンスにはトップレベルに "value" 文字列が含まれ、"ek\_" プレフィックスで始まります。このエフェメラルキーを使って後で WebRTC 接続を確立できます。なお、このキーは有効期間が短いため、再生成が必要になります。 + レスポンスにはトップレベルに "value" 文字列が含まれ、"ek\_" プレフィックスで始まります。この一時キーを使って後で WebRTC 接続を確立できます。なお、このキーは短時間のみ有効で、再生成が必要です。 -3. **最初の Agent を作成** +3. **はじめてのエージェントを作成** 新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`Agent`](/openai-agents-js/ja/guides/agents) の作成と非常によく似ています。 @@ -76,7 +76,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 4. **セッションの作成** - 通常のエージェントと異なり、Voice Agent は会話とモデルへの継続的な接続を処理する `RealtimeSession` 内で継続的に実行・リッスンします。このセッションは音声処理、割り込み、その他多くのライフサイクル機能も扱います。これらについては後ほど説明します。 + 通常のエージェントと異なり、Voice Agent は会話とモデルへの継続的な接続を処理する `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 サーバーを起動し、新しい Realtime Agent のコードを含むページに移動します。マイクへのアクセス許可のリクエストが表示されます。許可すると、エージェントと話し始めることができます。 ```bash npm run dev @@ -114,16 +114,16 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t ## 次のステップ -ここからは、独自の音声エージェントの設計と構築を始められます。音声エージェントは通常のエージェントと多くの機能を共有しますが、固有の機能もあります。 +ここからは自分の音声エージェントの設計と構築を始められます。音声エージェントには通常のエージェントと同様の機能が多く含まれますが、独自の機能もあります。 -- 音声エージェントに次の機能を与える方法を学ぶ +- 音声エージェントに以下を追加する方法を学ぶ - [ツール](/openai-agents-js/ja/guides/voice-agents/build#tools) - [ハンドオフ](/openai-agents-js/ja/guides/voice-agents/build#handoffs) - [ガードレール](/openai-agents-js/ja/guides/voice-agents/build#guardrails) - - [音声の割り込み処理](/openai-agents-js/ja/guides/voice-agents/build#audio-interruptions) - - [セッション履歴の管理](/openai-agents-js/ja/guides/voice-agents/build#session-history) + - [音声の割り込みを処理](/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 01a805b9..d7cd22b9 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 イベントと Realtime セッションの同期を維持します。 -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` のイベントを発行することで独自実装を作成できます。 +別の speech-to-speech API を使用したい場合や独自のトランスポート機構がある場合は、`RealtimeTransportLayer` インターフェースを実装し、`RealtimeTransportEventTypes` イベントを発行して独自に作成できます。 -## Realtime API をより直接的に操作する +## Realtime API とのより直接的なやり取り -OpenAI の Realtime API を使用しつつ、より直接的にアクセスしたい場合は、次の 2 つの方法があります。 +OpenAI Realtime API を使いつつ、より直接的に Realtime API へアクセスしたい場合は、次の 2 つの方法があります。 ### オプション 1 - トランスポート層へのアクセス -`RealtimeSession` のすべての機能を活用したい場合は、`session.transport` を介してトランスポート層にアクセスできます。 +引き続き `RealtimeSession` のすべての機能を活用したい場合は、`session.transport` を通じてトランスポート層にアクセスできます。 -トランスポート層は、受信したすべてのイベントを `*` イベントとして発行し、`sendEvent()` メソッドを使用して元のイベントを送信できます。 +トランスポート層は受信したすべてのイベントを `*` イベントで発行し、`sendEvent()` メソッドを使って元のイベントを送信できます。 ### オプション 2 — トランスポート層のみを使用 -自動ツール実行やガードレールなどが不要な場合、接続と割り込みだけを管理する「薄い」クライアントとしてトランスポート層のみを使用できます。 +自動ツール実行やガードレールなどが不要な場合、接続と割り込みの管理だけを行う「"thin" クライアント」としてトランスポート層を使用できます。 diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index 9a4c69f2..90a92756 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -19,29 +19,33 @@ 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 はごく少数の基本コンポーネントで構成されています: -- **エージェント**: instructions と tools を備えた LLM -- **ハンドオフ**: 特定のタスクを他のエージェントに委譲 -- **ガードレール**: エージェントへの入力を検証 +- **エージェント**: instructions とツールを備えた LLM +- **ハンドオフ**: 特定のタスクを他のエージェントに委任できる仕組み +- **ガードレール**: エージェントへの入力を検証できる仕組み -TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグし、評価したり、アプリケーション向けにモデルをファインチューニングすることもできます。 +TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに +実運用アプリケーションを構築できます。さらに、この SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグし、評価やアプリ向けモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 -この SDK は次の 2 つの設計原則に基づいています: +この SDK は 2 つの設計原則に基づいています: -1. 使う価値がある十分な機能を備えつつ、学習を素早くするために基本コンポーネントは少数に保つ -2. すぐに高いパフォーマンスで使える一方で、動作を細部までカスタマイズできる +1. 使う価値があるだけの機能を備えつつ、すぐ学べるよう基本コンポーネントは少数に抑える +2. そのままでも十分に動作しつつ、挙動を正確にカスタマイズできる -SDK の主な機能は次のとおりです: +主な機能は次のとおりです: -- **エージェントループ**: ツール呼び出し、結果の LLM への送信、LLM の完了までのループを内蔵で処理 -- **TypeScript ファースト**: 新しい抽象を学ぶのではなく、言語機能でエージェントのオーケストレーションや連鎖を実現 -- **ハンドオフ**: 複数エージェント間の協調と委譲を可能にする強力な機能 -- **ガードレール**: エージェントと並行して入力検証とチェックを実行し、失敗時は早期に中断 -- **関数ツール**: 任意の TypeScript 関数をツール化し、スキーマ生成と Zod ベースの検証を自動化 -- **トレーシング**: フローの可視化、デバッグ、監視に加え、OpenAI の評価、ファインチューニング、蒸留ツール群を活用可能 +- **エージェントループ**: ツールの呼び出し、結果の LLM への送信、LLM が完了するまでのループを内蔵 +- **TypeScript ファースト**: 新しい抽象を学ぶ必要なく、言語機能でエージェントをオーケストレーション・連鎖 +- **ハンドオフ**: 複数のエージェント間での調整と委任を可能にする強力な機能 +- **ガードレール**: チェックが失敗したら早期に中断しつつ、エージェントと並行で入力検証を実行 +- **関数ツール**: 任意の TypeScript 関数をツール化し、スキーマ自動生成と Zod ベースの検証を提供 +- **トレーシング**: ワークフローの可視化・デバッグ・監視に加え、OpenAI の評価、ファインチューニング、蒸留ツール群を活用可能 - **リアルタイムエージェント**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築 ## インストール @@ -50,11 +54,11 @@ SDK の主な機能は次のとおりです: npm install @openai/agents zod@3 ``` -## Hello World の例 +## Hello world のコード例 -(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) +(_実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/src/content/docs/ko/extensions/ai-sdk.mdx b/docs/src/content/docs/ko/extensions/ai-sdk.mdx index 9b04509b..dd27c097 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 모델과 함께 작동합니다. 그러나 다른 모델을 사용하려는 경우, [Vercel's AI SDK](https://sdk.vercel.ai/)에서 제공하는 다양한 지원 모델을 이 어댑터를 통해 Agents SDK에 연결할 수 있습니다. +기본적으로 Agents SDK는 Responses API 또는 Chat Completions API를 통해 OpenAI 모델과 함께 작동합니다. 그러나 다른 모델을 사용하려면, 이 어댑터를 통해 Agents SDK에 통합할 수 있는 다양한 지원 모델을 제공하는 [Vercel's AI SDK](https://sdk.vercel.ai/)를 사용할 수 있습니다. ## 설정 @@ -31,7 +31,7 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk npm install @ai-sdk/openai ``` -3. 어댑터와 모델을 임포트하여 에이전트에 연결합니다: +3. 어댑터와 모델을 가져와 에이전트에 연결합니다: ```typescript import { openai } from '@ai-sdk/openai'; @@ -47,19 +47,19 @@ import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk ## 예제 - + -## 제공자 메타데이터 전달 +## 프로바이더 메타데이터 전달 -메시지와 함께 제공자별 옵션을 전송해야 하는 경우 `providerMetadata`로 전달하세요. 값은 하위 AI SDK 모델로 직접 전달됩니다. 예를 들어, Agents SDK에서 다음 `providerData` +메시지와 함께 프로바이더별 옵션을 보내야 하는 경우 `providerMetadata`를 통해 전달하세요. 값은 하위 AI SDK 모델로 직접 전달됩니다. 예를 들어, Agents SDK에서 다음 `providerData` ```ts providerData: { @@ -71,7 +71,7 @@ providerData: { } ``` -은(는) AI SDK 통합을 사용할 때 +는 AI SDK 통합을 사용할 때 ```ts providerMetadata: { diff --git a/docs/src/content/docs/ko/extensions/cloudflare.mdx b/docs/src/content/docs/ko/extensions/cloudflare.mdx index 1209ede4..41ba2b20 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을 열 수 없습니다. 이러한 환경에서 Realtime Agents 연결을 단순화하기 위해, 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` 기능(도구, 가드레일 등)은 그대로 동작합니다 -- 개발 중 상세 로그를 확인하려면 `DEBUG=openai-agents*`를 사용하세요 +- Cloudflare 전송은 내부적으로 `Upgrade: websocket`과 함께 `fetch()`를 사용하며 소켓의 `open` 이벤트 대기를 건너뛰어, workerd API와 동일하게 동작합니다. +- 이 전송을 사용할 때에도 모든 `RealtimeSession` 기능(tools, guardrails 등)이 평소처럼 동작합니다. +- 개발 중 상세 로그를 확인하려면 `DEBUG=openai-agents*`를 사용하세요. diff --git a/docs/src/content/docs/ko/extensions/twilio.mdx b/docs/src/content/docs/ko/extensions/twilio.mdx index 97c29f60..ee46ee8d 100644 --- a/docs/src/content/docs/ko/extensions/twilio.mdx +++ b/docs/src/content/docs/ko/extensions/twilio.mdx @@ -7,37 +7,37 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw'; import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw'; -Twilio는 전화 통화의 원문 오디오를 WebSocket 서버로 전송하는 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)를 제공합니다. 이 설정을 사용해 Twilio를 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)에 연결할 수 있습니다. 기본 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가 접근할 수 있도록 [`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 어댑터를 설치합니다:** +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,33 +55,33 @@ Twilio는 전화 통화의 원문 오디오를 WebSocket 서버로 전송하는 -`RealtimeSession`에서 기대되는 모든 이벤트와 동작은 도구 호출, 가드레일 등을 포함해 예상대로 작동합니다. 음성 에이전트와 함께 `RealtimeSession`을 사용하는 방법은 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 참고하세요. +`RealtimeSession`에서 기대하는 모든 이벤트와 동작은 예상대로 작동하며, 도구 호출, 가드레일 등도 포함됩니다. `RealtimeSession`을 음성 에이전트와 함께 사용하는 방법은 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 참고하세요. -## 팁과 고려사항 +## 팁 및 고려사항 -1. **속도가 가장 중요합니다.** +1. **속도가 핵심입니다.** - Twilio에서 필요한 모든 이벤트와 오디오를 받으려면, WebSocket 연결 참조를 얻자마자 - `TwilioRealtimeTransportLayer` 인스턴스를 생성하고 즉시 `session.connect()`를 호출해야 합니다. + Twilio에서 필요한 모든 이벤트와 오디오를 수신하려면 WebSocket 연결에 대한 참조를 얻는 즉시 + `TwilioRealtimeTransportLayer` 인스턴스를 생성하고 바로 `session.connect()`를 호출해야 합니다. -2. **Twilio 원문 이벤트에 접근합니다.** +2. **Twilio 원문 이벤트 접근.** - Twilio가 보내는 원문 이벤트에 접근하려면, `RealtimeSession` 인스턴스에서 - `transport_event` 이벤트를 리슨하면 됩니다. Twilio에서 오는 모든 이벤트는 - 타입이 `twilio_message`이며 원문 이벤트 데이터를 담은 `message` 속성을 가집니다. + Twilio에서 전송되는 원문 이벤트에 접근하려면 `RealtimeSession` 인스턴스에서 + `transport_event` 이벤트를 리슨하면 됩니다. Twilio의 모든 이벤트는 타입이 `twilio_message`이며 + 원문 이벤트 데이터를 포함하는 `message` 속성을 가집니다. -3. **디버그 로그를 확인합니다.** +3. **디버그 로그 확인.** - 문제를 겪을 때 추가 정보가 필요할 수 있습니다. `DEBUG=openai-agents*` 환경 변수를 사용하면 - Agents SDK의 모든 디버그 로그가 표시됩니다. 또는 `DEBUG=openai-agents:extensions:twilio*` - 로 Twilio 어댑터에 대한 디버그 로그만 활성화할 수 있습니다. + 문제가 발생하여 더 많은 정보가 필요할 때가 있습니다. `DEBUG=openai-agents*` 환경 변수를 사용하면 + Agents SDK의 모든 디버그 로그를 볼 수 있습니다. 또는 Twilio 어댑터에 대해서만 디버그 로그를 + 활성화하려면 `DEBUG=openai-agents:extensions:twilio*`를 사용하세요. ## 전체 예제 서버 -아래는 Twilio로부터 요청을 받아 `RealtimeSession`으로 전달하는 WebSocket 서버의 종단 간 전체 예제입니다. +아래는 Twilio에서 요청을 수신하고 이를 `RealtimeSession`으로 전달하는 WebSocket 서버의 엔드투엔드 전체 예제입니다. diff --git a/docs/src/content/docs/ko/guides/agents.mdx b/docs/src/content/docs/ko/guides/agents.mdx index fb5f527f..2cb283ae 100644 --- a/docs/src/content/docs/ko/guides/agents.mdx +++ b/docs/src/content/docs/ko/guides/agents.mdx @@ -15,90 +15,95 @@ 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의 주요 구성 요소입니다. **에이전트**는 다음으로 구성된 대규모 언어 모델(LLM)입니다: +에이전트는 OpenAI Agents SDK의 주요 기본 구성 요소입니다. **Agent** 는 다음으로 구성된 대규모 언어 모델(LLM)입니다: -- **Instructions** – 모델에게 _자기 정체_ 와 _응답 방식_ 을 알려주는 시스템 프롬프트 +- **Instructions** – 모델에게 _자신이 누구인지_ 와 _어떻게 응답해야 하는지_ 알려주는 시스템 프롬프트 - **Model** – 호출할 OpenAI 모델과 선택적 모델 튜닝 매개변수 - **Tools** – LLM이 작업을 수행하기 위해 호출할 수 있는 함수 또는 API 목록 - + -이 페이지의 나머지 부분에서는 모든 에이전트 기능을 자세히 설명합니다. +이 페이지의 나머지 부분에서는 모든 Agent 기능을 자세히 살펴봅니다. --- ## 기본 구성 -`Agent` 생성자는 단일 구성 객체를 받습니다. 가장 자주 사용하는 속성은 아래와 같습니다. +`Agent` 생성자는 단일 구성 객체를 받습니다. 가장 일반적으로 사용되는 속성은 아래와 같습니다. -| Property | Required | Description | -| --------------- | -------- | ----------------------------------------------------------------------------------------------------------- | -| `name` | yes | 사람이 읽을 수 있는 짧은 식별자 | -| `instructions` | yes | 시스템 프롬프트(문자열 **또는** 함수 – [Dynamic instructions](#dynamic-instructions) 참조) | -| `model` | no | 모델 이름 **또는** 커스텀 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 구현 | -| `modelSettings` | no | 튜닝 매개변수(temperature, top_p 등). 상위 수준에 없는 속성이 필요하면 `providerData` 아래에 포함할 수 있음 | -| `tools` | no | 모델이 호출할 수 있는 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 인스턴스 배열 | +| Property | Required | Description | +| --------------- | -------- | --------------------------------------------------------------------------------------------------------------- | +| `name` | yes | 사람이 읽을 수 있는 짧은 식별자 | +| `instructions` | yes | 시스템 프롬프트(문자열 **또는** 함수 – [동적 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 스키마 호환 객체 +2. JSON 스키마와 호환되는 객체 -`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. **매니저(에이전트를 도구로)** – 중앙 에이전트가 대화를 소유하고 도구로 노출된 전문 에이전트를 호출함 +2. **핸드오프** – 초기 에이전트가 사용자의 요청을 파악한 뒤 전체 대화를 전문가에게 위임함 -이러한 접근 방식은 상호 보완적입니다. 매니저는 한 곳에서 가드레일이나 속도 제한을 적용할 수 있게 해주며, 핸드오프는 각 에이전트가 대화의 통제권을 유지하지 않고 단일 작업에 집중할 수 있게 해줍니다. +이 접근 방식은 상호 보완적입니다. 매니저는 가드레일이나 속도 제한을 단일 위치에서 강제할 수 있게 하고, 핸드오프는 각 에이전트가 대화 제어를 유지하지 않고 단일 작업에 집중하도록 합니다. -### 매니저(도구로서의 에이전트) +### 매니저(에이전트를 도구로) -이 패턴에서 매니저는 결코 제어권을 넘기지 않습니다—LLM이 도구를 사용하고 매니저가 최종 답변을 요약합니다. 자세한 내용은 [도구](/openai-agents-js/ko/guides/tools#agents-as-tools)를 참고하세요. +이 패턴에서 매니저는 제어권을 넘기지 않습니다—LLM이 도구를 사용하고 매니저가 최종 답을 요약합니다. 자세한 내용은 [도구](/openai-agents-js/ko/guides/tools#agents-as-tools) 가이드를 참고하세요. - + ### 핸드오프 -핸드오프에서는 분류 에이전트가 요청을 라우팅하지만, 일단 핸드오프가 이루어지면 전문 에이전트가 최종 출력이 나올 때까지 대화를 소유합니다. 이는 프롬프트를 짧게 유지하고 각 에이전트를 독립적으로 추론할 수 있게 해줍니다. 자세한 내용은 [핸드오프](/openai-agents-js/ko/guides/handoffs)를 참고하세요. +핸드오프에서는 분류 에이전트가 요청을 라우팅하지만, 핸드오프가 일어나면 전문가 에이전트가 최종 출력을 낼 때까지 대화를 소유합니다. 이는 프롬프트를 짧게 유지하고 각 에이전트를 독립적으로 추론할 수 있게 합니다. 자세한 내용은 [핸드오프](/openai-agents-js/ko/guides/handoffs) 가이드를 참고하세요. - + --- ## 동적 instructions -`instructions`는 문자열 대신 **함수**가 될 수 있습니다. 이 함수는 현재 `RunContext`와 에이전트 인스턴스를 받아 문자열 _또는_ `Promise`을 반환할 수 있습니다. +`instructions` 는 문자열 대신 **함수**가 될 수 있습니다. 이 함수는 현재 `RunContext` 와 Agent 인스턴스를 받아 문자열 _또는_ `Promise` 을 반환할 수 있습니다. 동기 및 `async` 함수 모두 지원됩니다. @@ -107,49 +112,49 @@ 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/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'` – 첫 번째 도구 결과를 최종 답변으로 처리 +- `'stop_on_first_tool'` – 첫 번째 도구 결과를 최종 답으로 처리 - `{ stopAtToolNames: ['my_tool'] }` – 나열된 도구 중 하나가 호출되면 중지 -- `(context, toolResults) => ...` – 실행을 종료할지 여부를 반환하는 사용자 지정 함수 +- `(context, toolResults) => ...` – 실행을 종료할지 여부를 반환하는 커스텀 함수 ```typescript const agent = new Agent({ @@ -162,6 +167,6 @@ const agent = new Agent({ ## 다음 단계 -- [에이전트 실행](/openai-agents-js/ko/guides/running-agents) 방법 알아보기 -- [도구](/openai-agents-js/ko/guides/tools), [가드레일](/openai-agents-js/ko/guides/guardrails), [모델](/openai-agents-js/ko/guides/models) 자세히 살펴보기 -- 사이드바의 **@openai/agents** 아래에 있는 전체 TypeDoc 레퍼런스를 확인하세요 +- [에이전트 실행](/openai-agents-js/ko/guides/running-agents) 방법을 알아보세요 +- [도구](/openai-agents-js/ko/guides/tools), [가드레일](/openai-agents-js/ko/guides/guardrails), [모델](/openai-agents-js/ko/guides/models)을 살펴보세요 +- 사이드바의 **@openai/agents** 아래에서 전체 TypeDoc 레퍼런스를 탐색하세요 diff --git a/docs/src/content/docs/ko/guides/config.mdx b/docs/src/content/docs/ko/guides/config.mdx index 5a806f31..2a999c60 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()` 를 통해 설정할 수 있습니다: -트레이싱 기능에 대해 더 알아보려면 [트레이싱](/openai-agents-js/ko/guides/tracing)을 확인하세요. +트레이싱 기능에 대해 더 알아보려면 [트레이싱](/openai-agents-js/ko/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)` 를 사용해 모듈별 네임스페이스 로거를 얻을 수 있습니다. @@ -71,13 +71,13 @@ export DEBUG=openai-agents* 일부 로그에는 사용자 데이터가 포함될 수 있습니다. 다음 환경 변수를 설정하여 비활성화하세요. -LLM 입력 및 출력 로깅을 비활성화하려면: +LLM 입력 및 출력을 비활성화하려면: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -tool 입력 및 출력 로깅을 비활성화하려면: +도구 입력 및 출력을 비활성화하려면: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/src/content/docs/ko/guides/context.mdx b/docs/src/content/docs/ko/guides/context.mdx index 87a9ecbf..d3276cd5 100644 --- a/docs/src/content/docs/ko/guides/context.mdx +++ b/docs/src/content/docs/ko/guides/context.mdx @@ -6,39 +6,35 @@ description: Learn how to provide local data via RunContext and expose context t import { Aside, Code } from '@astrojs/starlight/components'; import localContextExample from '../../../../../../examples/docs/context/localContext.ts?raw'; -컨텍스트는 과부하되어 쓰이는 용어입니다. 고려해야 할 컨텍스트에는 두 가지 주요 분류가 있습니다: +컨텍스트는 여러 의미로 사용됩니다. 관심을 가질 수 있는 컨텍스트에는 두 가지 주요 범주가 있습니다: -1. 실행 중 코드가 접근할 수 있는 **로컬 컨텍스트**: 도구에 필요한 의존성이나 데이터, `onHandoff` 같은 콜백, 라이프사이클 훅 -2. 응답 생성 시 언어 모델이 볼 수 있는 **에이전트/LLM 컨텍스트** +1. 실행 중에 코드가 액세스할 수 있는 **로컬 컨텍스트**: 도구에 필요한 의존성 또는 데이터, `onHandoff` 같은 콜백, 그리고 라이프사이클 훅 +2. 응답을 생성할 때 언어 모델이 볼 수 있는 **에이전트/LLM 컨텍스트** ## 로컬 컨텍스트 -로컬 컨텍스트는 `RunContext` 타입으로 표현됩니다. 상태나 의존성을 보관할 임의의 객체를 만들고 이를 `Runner.run()`에 전달합니다. 모든 도구 호출과 훅은 해당 객체를 읽거나 수정할 수 있도록 `RunContext` 래퍼를 받습니다. +로컬 컨텍스트는 `RunContext` 타입으로 표현됩니다. 상태나 의존성을 담을 임의의 객체를 생성해 `Runner.run()`에 전달합니다. 모든 도구 호출과 훅은 `RunContext` 래퍼를 받아 그 객체를 읽거나 수정할 수 있습니다. - + -단일 실행에 참여하는 모든 에이전트, 도구, 훅은 동일한 **타입**의 컨텍스트를 사용해야 합니다. +단일 실행에 참여하는 모든 에이전트, 도구, 훅은 동일한 **type**의 컨텍스트를 사용해야 합니다. 로컬 컨텍스트는 다음과 같은 용도로 사용하세요: -- 실행 관련 데이터(사용자 이름, ID 등) -- 로거나 데이터 패처 같은 의존성 +- 실행에 대한 데이터(사용자 이름, 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 기법과 유사하지만 메시지를 [명령 체계](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 c18c92cc..9fe058d1 100644 --- a/docs/src/content/docs/ko/guides/guardrails.mdx +++ b/docs/src/content/docs/ko/guides/guardrails.mdx @@ -7,11 +7,11 @@ 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. **입력 가드레일**은 최초 사용자 입력에 대해 실행됩니다. +1. **입력 가드레일**은 초기 사용자 입력에 대해 실행됩니다. 2. **출력 가드레일**은 최종 에이전트 출력에 대해 실행됩니다. ## 입력 가드레일 @@ -19,35 +19,35 @@ import outputGuardrailExample from '../../../../../../examples/docs/guardrails/g 입력 가드레일은 세 단계로 실행됩니다: 1. 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다. -2. 가드레일 함수가 실행되고 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을(를) [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult)로 감싸서 반환합니다. +2. 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을 반환하며, 이는 [`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult)로 래핑됩니다. 3. `tripwireTriggered`가 `true`이면 [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered) 오류가 발생합니다. -> **참고** -> 입력 가드레일은 사용자 입력을 대상으로 하므로, 에이전트가 워크플로의 _첫 번째_ 에이전트일 때만 실행됩니다. 가드레일은 에이전트별로 구성합니다. 에이전트마다 필요한 가드레일이 다를 수 있기 때문입니다. +> **Note** +> 입력 가드레일은 사용자 입력을 대상으로 하므로, 워크플로에서 에이전트가 _첫 번째_ 에이전트인 경우에만 실행됩니다. 가드레일은 에이전트 자체에 구성되며, 에이전트마다 필요한 가드레일이 다를 수 있습니다. ## 출력 가드레일 -출력 가드레일은 세 단계로 실행됩니다: +출력 가드레일은 3단계로 실행됩니다: 1. 가드레일은 에이전트가 생성한 출력을 받습니다. -2. 가드레일 함수가 실행되고 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을(를) [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult)로 감싸서 반환합니다. +2. 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)을 반환하며, 이는 [`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult)로 래핑됩니다. 3. `tripwireTriggered`가 `true`이면 [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered) 오류가 발생합니다. -> **참고** -> 출력 가드레일은 에이전트가 워크플로의 _마지막_ 에이전트일 때만 실행됩니다. 실시간 음성 상호작용은 [음성 에이전트 구축](/openai-agents-js/ko/guides/voice-agents/build#guardrails)을 참고하세요. +> **Note** +> 출력 가드레일은 워크플로에서 에이전트가 _마지막_ 에이전트인 경우에만 실행됩니다. 실시간 음성 상호작용은 [음성 에이전트 구축](/openai-agents-js/ko/guides/voice-agents/build#guardrails)을 참조하세요. ## 트립와이어 -가드레일이 실패하면 트립와이어를 통해 이를 알립니다. 트립와이어가 트리거되는 즉시 러너는 해당 오류를 발생시키고 실행을 중단합니다. +가드레일이 실패하면 트립와이어를 통해 이를 신호합니다. 트립와이어가 트리거되는 즉시 러너는 해당 오류를 발생시키고 실행을 중단합니다. ## 가드레일 구현 -가드레일은 `GuardrailFunctionOutput`을 반환하는 단순한 함수입니다. 아래는 내부적으로 또 다른 에이전트를 실행하여 사용자가 수학 숙제 도움을 요청하는지 확인하는 최소 예제입니다. +가드레일은 `GuardrailFunctionOutput`을 반환하는 간단한 함수입니다. 아래는 다른 에이전트를 내부적으로 실행하여 사용자가 수학 숙제 도움을 요청하는지 확인하는 최소 예시입니다. 출력 가드레일도 동일한 방식으로 동작합니다. @@ -55,10 +55,10 @@ import outputGuardrailExample from '../../../../../../examples/docs/guardrails/g 1. `guardrailAgent`는 가드레일 함수 내부에서 사용됩니다. 2. 가드레일 함수는 에이전트 입력 또는 출력을 받아 결과를 반환합니다. -3. 추가 정보를 가드레일 결과에 포함할 수 있습니다. +3. 가드레일 결과에 추가 정보를 포함할 수 있습니다. 4. `agent`는 가드레일이 적용되는 실제 워크플로를 정의합니다. diff --git a/docs/src/content/docs/ko/guides/handoffs.mdx b/docs/src/content/docs/ko/guides/handoffs.mdx index 76490b30..dcd7b35b 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`와 선택적으로 파싱된 입력을 받음 - `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) 흐름은 서버를 계속 실행하지 않고도 오랜 기간 인터럽트될 수 있도록 설계되었습니다. 요청을 종료하고 나중에 계속해야 하는 경우 상태를 직렬화하여 나중에 재개할 수 있습니다. -`JSON.stringify(result.state)` 를 사용해 상태를 직렬화하고, 직렬화된 상태를 `RunState.fromString(agent, serializedState)` 에 전달하여 나중에 재개할 수 있습니다. 여기서 `agent` 는 전체 실행을 트리거한 에이전트 인스턴스입니다. +`JSON.stringify(result.state)`를 사용해 상태를 직렬화하고, 직렬화된 상태를 `RunState.fromString(agent, serializedState)`에 전달하여 나중에 재개할 수 있습니다. 여기서 `agent`는 전체 실행을 트리거한 에이전트 인스턴스입니다. 이렇게 하면 직렬화된 상태를 데이터베이스나 요청과 함께 저장할 수 있습니다. -### 보류 작업 버전 관리 +### 보류 중 작업의 버전 관리 -승인 요청에 시간이 오래 걸리고 에이전트 정의를 의미 있게 버전 관리하거나 Agents SDK 버전을 올릴 계획이라면, 패키지 별칭을 사용하여 두 버전의 Agents SDK 를 병행 설치하고 자체 분기 로직을 구현할 것을 권장합니다. +승인 요청에 시간이 오래 걸리고 에이전트 정의에 의미 있는 버전 관리를 하거나 Agents SDK 버전을 올릴 예정이라면, 패키지 별칭을 사용해 두 버전의 Agents SDK를 병렬로 설치하여 자체 분기 로직을 구현하는 것을 권장합니다. -실제로는 코드에 자체 버전 번호를 부여하고 이를 직렬화된 상태와 함께 저장한 다음, 역직렬화를 코드의 올바른 버전으로 안내하는 방식을 의미합니다. +실제로는 코드에 자체 버전 번호를 부여하고 이를 직렬화된 상태와 함께 저장한 후, 역직렬화를 코드의 올바른 버전으로 유도하는 것을 의미합니다. diff --git a/docs/src/content/docs/ko/guides/mcp.mdx b/docs/src/content/docs/ko/guides/mcp.mdx index 985ccf27..3244985b 100644 --- a/docs/src/content/docs/ko/guides/mcp.mdx +++ b/docs/src/content/docs/ko/guides/mcp.mdx @@ -13,56 +13,60 @@ import streamableHttpExample from '../../../../../../examples/docs/mcp/streamabl import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; -[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io)는 애플리케이션이 LLM에 도구와 컨텍스트를 제공하는 방식을 표준화한 오픈 프로토콜입니다. MCP 문서에서 인용: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io)은 애플리케이션이 LLMs에 도구와 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP 문서에서 인용: -> MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화한 오픈 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB‑C 포트라고 생각해 보세요. USB‑C가 다양한 주변기기와 액세서리에 기기를 표준 방식으로 연결하듯, MCP는 AI 모델을 다양한 데이터 소스와 도구에 표준 방식으로 연결합니다. +> MCP는 애플리케이션이 LLMs에 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. 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 서버** – 표준 입출력을 통해 액세스하는 서버(가장 간단한 옵션) +2. **Streamable HTTP MCP 서버** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http)를 구현한 로컬 또는 원격 서버 +3. **Stdio MCP 서버** – 표준 입력/출력을 통해 접근하는 서버(가장 간단한 옵션) 사용 사례에 따라 서버 유형을 선택하세요: -| 필요한 것 | 권장 옵션 | -| ----------------------------------------------------------------- | ----------------------- | -| 기본 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. 호스티드 MCP 도구** | +| 공개 접근 가능한 원격 서버를 사용하지만 도구 호출은 로컬에서 트리거 | **2. Streamable HTTP** | +| 로컬에서 실행 중인 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | +| OpenAI-Responses 이외의 모델로 모든 Streamable HTTP 서버 사용 | **2. Streamable HTTP** | +| 표준 I/O 프로토콜만 지원하는 로컬 MCP 서버 사용 | **3. Stdio** | ## 1. 호스티드 MCP 서버 도구 -호스티드 툴은 전체 라운드트립을 모델 내부로 이동합니다. 코드가 MCP 서버를 호출하는 대신, OpenAI Responses API가 원격 도구 엔드포인트를 호출하고 결과를 모델로 스트리밍합니다. +호스티드 툴은 전체 왕복 과정을 모델 내부에서 처리합니다. 코드가 MCP 서버를 호출하는 대신, OpenAI Responses API가 원격 도구 엔드포인트를 호출하고 결과를 모델로 스트리밍합니다. -다음은 호스티드 MCP 툴을 사용하는 가장 단순한 예시입니다. 원격 MCP 서버의 레이블과 URL을 `hostedMcpTool` 유틸리티 함수에 전달하면 호스티드 MCP 서버 도구를 쉽게 생성할 수 있습니다. +다음은 호스티드 MCP 도구를 사용하는 가장 간단한 예시입니다. 원격 MCP 서버의 레이블과 URL을 `hostedMcpTool` 유틸리티 함수에 전달할 수 있으며, 이는 호스티드 MCP 서버 도구를 만드는 데 유용합니다. -그다음 `run` 함수(또는 커스텀 `Runner` 인스턴스의 `run` 메서드)로 에이전트를 실행할 수 있습니다: +그런 다음 `run` 함수(또는 사용자 정의한 `Runner` 인스턴스의 `run` 메서드)로 에이전트를 실행할 수 있습니다: - + 증분 MCP 결과를 스트리밍하려면 `Agent`를 실행할 때 `stream: true`를 전달하세요: #### 선택적 승인 흐름 -민감한 작업의 경우 개별 도구 호출에 대한 사람의 승인을 요구할 수 있습니다. `requireApproval: 'always'` 또는 도구 이름을 `'never'`/`'always'`에 매핑하는 세밀한 객체를 전달하세요. +민감한 작업의 경우 개별 도구 호출에 대한 사람의 승인을 요구할 수 있습니다. `requireApproval: 'always'` 또는 도구 이름을 `'never'`/`'always'`에 매핑하는 세분화된 객체를 전달하세요. -도구 호출의 안전성을 프로그램적으로 판별할 수 있다면 [`onApproval` 콜백](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts)을 사용해 도구 호출을 승인 또는 거부할 수 있습니다. 사람의 승인이 필요한 경우 로컬 함수 도구에서와 동일하게 `interruptions`를 사용하는 [휴먼 인 더 루프 (HITL) 접근 방식](/openai-agents-js/ko/guides/human-in-the-loop/)을 사용할 수 있습니다. +도구 호출의 안전성을 프로그램적으로 판단할 수 있다면 [`onApproval` 콜백](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts)을 사용해 도구 호출을 승인하거나 거부할 수 있습니다. 사람의 승인이 필요한 경우, 로컬 함수 도구와 동일하게 `interruptions`를 사용하는 동일한 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop/) 접근 방식을 사용할 수 있습니다. ### 커넥터 기반 호스티드 서버 @@ -72,45 +76,48 @@ import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.t -이 예시에서 `GOOGLE_CALENDAR_AUTHORIZATION` 환경 변수에는 Google OAuth Playground에서 얻은 OAuth 토큰이 저장되며, 이는 커넥터 기반 서버가 Calendar API를 호출하도록 승인합니다. 스트리밍도 함께 보여주는 실행 가능한 샘플은 [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors)를 참조하세요. +이 예시에서 `GOOGLE_CALENDAR_AUTHORIZATION` 환경 변수에는 Google OAuth Playground에서 얻은 OAuth 토큰이 들어 있으며, 커넥터 기반 서버가 Calendar API를 호출하도록 권한을 부여합니다. 스트리밍도 함께 시연하는 실행 가능한 샘플은 [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors)를 참고하세요. -완전한 동작 샘플(호스티드 툴/Streamable HTTP/stdio + 스트리밍, HITL, onApproval)은 GitHub 리포지토리의 [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp)에 있습니다. +완전한 동작 샘플(호스티드 도구/Streamable HTTP/stdio + 스트리밍, HITL, onApproval)은 GitHub 리포지토리의 [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp)에 있습니다. ## 2. Streamable HTTP MCP 서버 -에이전트가 로컬 또는 원격의 Streamable HTTP MCP 서버와 직접 통신할 때는 서버의 `url`, `name` 및 선택적 설정과 함께 `MCPServerStreamableHttp`를 인스턴스화하세요: +에이전트가 로컬 또는 원격의 Streamable HTTP MCP 서버와 직접 통신하는 경우, 서버의 `url`, `name` 및 선택적 설정과 함께 `MCPServerStreamableHttp`를 인스턴스화하세요: -생성자는 `authProvider`, `requestInit`, `fetch`, `reconnectionOptions`, `sessionId` 등 MCP TypeScript‑SDK의 추가 옵션도 허용합니다. 자세한 내용은 [MCP TypeScript SDK 리포지토리](https://github.com/modelcontextprotocol/typescript-sdk)와 해당 문서를 참고하세요. +생성자는 `authProvider`, `requestInit`, `fetch`, `reconnectionOptions`, `sessionId`와 같은 추가 MCP TypeScript‑SDK 옵션도 허용합니다. 자세한 내용은 [MCP TypeScript SDK 리포지토리](https://github.com/modelcontextprotocol/typescript-sdk) 및 해당 문서를 참고하세요. ## 3. Stdio MCP 서버 -표준 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) – 위에서 참조한 실행 가능한 - 데모 +- [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 e2478ae9..b2b35d47 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"` 추론 강도를 지원하지 않으므로, 이 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')` _(기본값)_ | +| API | 사용 용도 | `setOpenAIAPI()` 호출 | +| ---------------- | ------------------------------------------------------- | --------------------------------------- | +| Chat Completions | 표준 채팅 및 함수 호출 | `setOpenAIAPI('chat_completions')` | +| Responses | 스트리밍 우선의 새로운 생성 API(도구 호출, 유연한 출력) | `setOpenAIAPI('responses')` _(default)_ | ### 인증 @@ -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` | 창의성 vs. 결정성 | +| `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 워크플로우를 위해 응답을 저장 | -| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 등에서의 추론 강도 | +| `store` | `boolean` | 응답을 보존하여 검색/RAG 워크플로에 사용 | +| `reasoning.effort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 등에서의 reasoning effort | | `text.verbosity` | `'low' \| 'medium' \| 'high'` | gpt-5 등에서의 텍스트 장황도 | -설정은 어느 수준에든 부착할 수 있습니다: +설정은 어느 수준에나 부착할 수 있습니다: -`Runner` 수준의 설정은 에이전트별 설정과 충돌 시 이를 우선합니다. +`Runner` 수준의 설정은 충돌하는 에이전트별 설정을 덮어씁니다. --- ## 프롬프트 -에이전트는 `prompt` 매개변수로 구성할 수 있으며, 이는 서버에 저장된 프롬프트 구성을 사용해 에이전트의 동작을 제어해야 함을 나타냅니다. 현재 이 옵션은 OpenAI [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용할 때만 지원됩니다. +에이전트는 `prompt` 매개변수로 구성할 수 있으며, 이는 에이전트의 동작을 제어하는 데 사용해야 하는 서버에 저장된 프롬프트 구성을 나타냅니다. 현재 이 옵션은 OpenAI [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용할 때만 지원됩니다. -| Field | Type | Notes | -| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------- | -| `promptId` | `string` | 프롬프트의 고유 식별자 | -| `version` | `string` | 사용하려는 프롬프트 버전 | -| `variables` | `object` | 프롬프트에 치환할 변수의 키/값 쌍입니다. 값은 문자열이거나 텍스트, 이미지, 파일 등의 콘텐츠 입력 타입일 수 있습니다. | +| 필드 | 타입 | 비고 | +| ----------- | -------- | ----------------------------------------------------------------------------------------------------------- | +| `promptId` | `string` | 프롬프트의 고유 식별자 | +| `version` | `string` | 사용하려는 프롬프트의 버전 | +| `variables` | `object` | 프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열이거나 텍스트, 이미지, 파일과 같은 콘텐츠 입력 타입일 수 있음 | -tools 또는 instructions 같은 추가 에이전트 구성은 저장된 프롬프트에서 구성한 값을 재정의합니다. +도구나 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 48329180..8e164647 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, 도구와 핸드오프를 갖춘 LLM입니다. 이는 개방형 작업이 주어졌을 때 LLM이 도구를 사용해 행동하고 데이터를 획득하며, 핸드오프를 통해 하위 에이전트에 작업을 위임하는 계획을 자율적으로 세울 수 있음을 의미합니다. 예를 들어, 리서치 에이전트는 다음과 같은 도구를 갖출 수 있습니다: +에이전트는 instructions, tools 및 핸드오프를 갖춘 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` 루프에서 평가 및 피드백을 제공하는 에이전트와 함께 실행하여, 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복하기 -- JavaScript 기본 구성요소인 `Promise.all` 등을 통해 여러 에이전트를 병렬로 실행하기. 서로 의존하지 않는 여러 작업이 있을 때 속도에 유용합니다. +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성. 예를 들어, 에이전트에게 작업을 몇 개의 카테고리로 분류하게 한 뒤 해당 카테고리에 따라 다음 에이전트를 선택 +- 한 에이전트의 출력을 다음 에이전트의 입력으로 변환해 여러 에이전트를 체이닝. 블로그 글 작성을 조사하기, 개요 작성, 블로그 글 작성, 비평, 개선의 단계로 연속 구성할 수 있음 +- 작업을 수행하는 에이전트와 평가 및 피드백을 제공하는 에이전트를 함께 `while` 루프로 실행하고, 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복 +- `Promise.all` 같은 JavaScript 기본 컴포넌트를 통해 여러 에이전트를 병렬 실행. 서로 의존하지 않는 여러 작업이 있을 때 속도 면에서 유용 -[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns)에 여러 예제가 있습니다. +[`examples/agent-patterns`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns)에 다양한 code examples가 있습니다. diff --git a/docs/src/content/docs/ko/guides/quickstart.mdx b/docs/src/content/docs/ko/guides/quickstart.mdx index cc867ba9..872ad245 100644 --- a/docs/src/content/docs/ko/guides/quickstart.mdx +++ b/docs/src/content/docs/ko/guides/quickstart.mdx @@ -11,7 +11,7 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. -1. 프로젝트를 생성하고 npm을 초기화하세요. 이 작업은 한 번만 수행하면 됩니다. +1. 프로젝트를 만들고 npm을 초기화합니다. 이 작업은 한 번만 수행하면 됩니다. ```bash mkdir my_project @@ -19,27 +19,27 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm init -y ``` -2. Agents SDK를 설치하세요. +2. Agents SDK를 설치합니다. ```bash npm install @openai/agents zod@3 ``` -3. OpenAI API 키를 설정하세요. 아직 없다면 [이 가이드](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따라 OpenAI API 키를 생성하세요. +3. OpenAI API 키를 설정합니다. 아직 없다면 OpenAI API 키를 생성하려면 [이 안내](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따르세요. ```bash export OPENAI_API_KEY=sk-... ``` - 또는 `setDefaultOpenAIKey('')`를 호출해 프로그램에서 키를 설정하고, + 또는 `setDefaultOpenAIKey('')`를 호출하여 프로그램적으로 키를 설정하고, 트레이싱에는 `setTracingExportApiKey('')`를 사용할 수 있습니다. - 자세한 내용은 [SDK 설정](/openai-agents-js/ko/guides/config)을 참고하세요. + 자세한 내용은 [설정 가이드](/openai-agents-js/ko/guides/config)를 참고하세요. ## 첫 에이전트 생성 -에이전트는 instructions와 name으로 정의합니다. +에이전트는 instructions와 이름으로 정의됩니다. ```typescript import { Agent } from '@openai/agents'; @@ -53,9 +53,10 @@ const agent = new Agent({ ## 첫 에이전트 실행 -`run` 메서드를 사용해 에이전트를 실행할 수 있습니다. 시작할 에이전트와 전달할 입력을 함께 넘기면 실행이 트리거됩니다. +에이전트를 실행하려면 `run` 메서드를 사용할 수 있습니다. 시작할 에이전트와 +에이전트에 전달할 입력을 함께 전달하여 실행을 트리거합니다. -이렇게 하면 해당 실행 동안 수행된 최종 출력과 모든 작업이 포함된 결과가 반환됩니다. +이렇게 하면 해당 실행 동안 수행된 모든 동작과 최종 출력을 포함하는 결과가 반환됩니다. ```typescript import { Agent, run } from '@openai/agents'; @@ -100,9 +101,11 @@ const agent = new Agent({ }); ``` -## 에이전트 추가 +## 에이전트 몇 개 더 추가 -추가 에이전트를 유사하게 정의해 문제를 더 작은 부분으로 분해하고 현재 작업에 더 집중하도록 만들 수 있습니다. 또한 에이전트에서 모델을 정의함으로써 서로 다른 문제에 서로 다른 모델을 사용할 수 있습니다. +추가 에이전트를 비슷한 방식으로 정의하여 문제를 더 작은 부분으로 나누고, +에이전트가 현재 작업에 더욱 집중하도록 할 수 있습니다. 또한 에이전트에 모델을 정의하여 +문제 유형에 따라 서로 다른 모델을 사용할 수 있습니다. ```typescript const historyTutorAgent = new Agent({ @@ -120,7 +123,9 @@ const mathTutorAgent = new Agent({ ## 핸드오프 정의 -여러 에이전트를 오케스트레이션하기 위해 에이전트에 `handoffs`를 정의할 수 있습니다. 이렇게 하면 에이전트가 다음 에이전트로 대화를 넘길 수 있습니다. 이는 실행 과정에서 자동으로 발생합니다. +여러 에이전트를 오케스트레이션하기 위해 에이전트에 `handoffs`를 정의할 수 있습니다. +이렇게 하면 에이전트가 대화를 다음 에이전트로 넘길 수 있습니다. 이는 실행 과정에서 +자동으로 발생합니다. ```typescript // Using the Agent.create method to ensures type safety for the final output @@ -136,7 +141,7 @@ const triageAgent = Agent.create({ ## 에이전트 오케스트레이션 실행 -Runner는 개별 에이전트의 실행, 잠재적인 핸드오프 및 도구 실행 처리를 담당합니다. +Runner는 개별 에이전트의 실행, 잠재적 핸드오프, 도구 실행을 처리합니다. ```typescript import { run } from '@openai/agents'; @@ -149,22 +154,23 @@ async function main() { main().catch((err) => console.error(err)); ``` -## 전체 통합 +## 모두 합쳐 보기 -이제 모든 것을 하나의 전체 예제로 통합해 봅시다. 이를 `index.js` 파일에 넣고 실행하세요. +이제 모든 내용을 하나의 전체 예제로 합쳐 보겠습니다. 이를 `index.js` 파일에 넣고 실행하세요. -## 트레이스 보기 +## 트레이스 확인 -Agents SDK는 자동으로 트레이스를 생성합니다. 이를 통해 에이전트가 어떻게 동작했는지, 어떤 도구를 호출했는지, 어떤 에이전트로 핸드오프했는지 검토할 수 있습니다. +Agents SDK는 자동으로 트레이스를 생성합니다. 이를 통해 에이전트가 어떻게 동작했는지, +어떤 도구를 호출했는지, 어떤 에이전트로 핸드오프했는지를 확인할 수 있습니다. -에이전트 실행 중에 어떤 일이 있었는지 검토하려면 -[OpenAI 대시보드의 Trace viewer](https://platform.openai.com/traces)로 이동하세요. +에이전트 실행 중에 어떤 일이 일어났는지 확인하려면 +[OpenAI Dashboard의 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 65f69313..fe7a3743 100644 --- a/docs/src/content/docs/ko/guides/release.mdx +++ b/docs/src/content/docs/ko/guides/release.mdx @@ -5,30 +5,30 @@ description: Learn how we version and release the SDK and recent changes. ## 버전 관리 -본 프로젝트는 `0.Y.Z` 형태를 사용하는 약간 수정된 시맨틱 버전 관리를 따릅니다. 선행하는 `0`은 SDK가 아직 빠르게 발전 중임을 나타냅니다. 구성 요소 증분 규칙은 다음과 같습니다: +이 프로젝트는 `0.Y.Z` 형태를 사용하는 의미론적 버전(semantic versioning)의 약간 수정된 방식을 따릅니다. 앞의 `0`은 SDK가 여전히 빠르게 발전 중임을 나타냅니다. 각 구성 요소 증분 규칙은 다음과 같습니다: ## 마이너(`Y`) 버전 -베타로 표시되지 않은 공개 인터페이스에 대한 **호환성 파괴 변경**이 있을 때 마이너 버전 `Y`를 올립니다. 예: `0.0.x`에서 `0.1.x`로 올라갈 때 호환성 파괴 변경이 포함될 수 있습니다. +베타로 표시되지 않은 공개 인터페이스에 대한 **breaking changes**가 있을 때 마이너 버전 `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 3d6ae92a..8354d616 100644 --- a/docs/src/content/docs/ko/guides/results.mdx +++ b/docs/src/content/docs/ko/guides/results.mdx @@ -7,23 +7,23 @@ import { Code } from '@astrojs/starlight/components'; import handoffFinalOutputTypes from '../../../../../../examples/docs/results/handoffFinalOutputTypes.ts?raw'; import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts?raw'; -[에이전트 실행](/openai-agents-js/ko/guides/running-agents)을 수행하면 다음 중 하나를 받습니다: +[에이전트 실행](/openai-agents-js/ko/guides/running-agents)을(를) 하면 다음 중 하나를 받게 됩니다: -- `stream: true` 없이 `run`을 호출한 경우 [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) -- `stream: true`와 함께 `run`을 호출한 경우 [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult). 스트리밍에 대한 자세한 내용은 [스트리밍](/openai-agents-js/ko/guides/streaming)도 확인하세요. +- `stream: true` 없이 `run`을 호출했다면 [`RunResult`](/openai-agents-js/openai/agents/classes/runresult) +- `stream: true`로 `run`을 호출했다면 [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult). 스트리밍의 자세한 내용은 [스트리밍](/openai-agents-js/ko/guides/streaming)도 참고하세요 ## 최종 출력 `finalOutput` 속성에는 마지막으로 실행된 에이전트의 최종 출력이 포함됩니다. 이 결과는 다음 중 하나입니다: - `string` — `outputType`이 정의되지 않은 모든 에이전트의 기본값 -- `unknown` — 에이전트가 출력 타입으로 JSON 스키마를 정의한 경우. 이 경우 JSON 이 파싱되지만 타입은 직접 검증해야 합니다. -- `z.infer` — 에이전트가 출력 타입으로 Zod 스키마를 정의한 경우. 출력은 이 스키마에 자동으로 파싱됩니다. +- `unknown` — 에이전트가 출력 타입으로 JSON 스키마를 정의한 경우. 이 경우 JSON은 파싱되지만 타입은 직접 검증해야 합니다 +- `z.infer` — 에이전트가 출력 타입으로 Zod 스키마를 정의한 경우. 출력은 이 스키마에 따라 자동으로 파싱됩니다 - `undefined` — 에이전트가 출력을 생성하지 않은 경우(예: 출력을 생성하기 전에 중단된 경우) -서로 다른 출력 타입과 함께 핸드오프를 사용하는 경우, 에이전트를 생성할 때 `new Agent()` 생성자 대신 `Agent.create()` 메서드를 사용해야 합니다. +서로 다른 출력 타입을 가진 핸드오프를 사용하는 경우 에이전트를 생성할 때 `new Agent()` 생성자 대신 `Agent.create()` 메서드를 사용하는 것이 좋습니다. -이렇게 하면 SDK 가 가능한 모든 핸드오프 전반의 출력 타입을 추론하고 `finalOutput` 속성에 대한 유니온 타입을 제공합니다. +이렇게 하면 SDK가 가능한 모든 핸드오프에 걸쳐 출력 타입을 추론하고 `finalOutput` 속성에 대한 유니온 타입을 제공합니다. 예시: @@ -33,57 +33,57 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? title="핸드오프 최종 출력 타입" /> -## 다음 턴 입력 +## 다음 턴의 입력 다음 턴의 입력에 접근하는 방법은 두 가지입니다: -- `result.history` — 입력과 에이전트 출력의 사본을 포함 +- `result.history` — 입력과 에이전트 출력 모두의 사본을 포함 - `result.output` — 전체 에이전트 실행의 출력을 포함 -`history`는 채팅과 같은 사용 사례에서 전체 히스토리를 유지하기에 편리합니다: +`history`는 채팅과 같은 사용 사례에서 전체 이력을 유지하는 편리한 방법입니다: ## 마지막 에이전트 -`lastAgent` 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라 다음 번에 사용자가 무언가를 입력할 때 유용한 경우가 많습니다. 예를 들어, 프런트라인 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우, 마지막 에이전트를 저장해 두었다가 사용자가 다음에 메시지를 보낼 때 재사용할 수 있습니다. +`lastAgent` 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라 다음에 사용자가 무언가를 입력할 때 유용한 경우가 많습니다. 예를 들어, 1차 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우 마지막 에이전트를 저장해 두었다가 사용자가 다음에 메시지를 보낼 때 재사용할 수 있습니다. 스트리밍 모드에서는 현재 실행 중인 에이전트에 매핑되는 `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` 배열이 됩니다. 인터럽션 작업 방법에 대한 자세한 내용은 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop)을 확인하세요. +에이전트에서 `needsApproval`을 사용하는 경우, 계속 진행하기 전에 처리해야 하는 `interruptions`가 트리거될 수 있습니다. 이 경우 `interruptions`는 인터럽션을 유발한 `ToolApprovalItem`s의 배열이 됩니다. 인터럽션을 다루는 방법에 대한 자세한 내용은 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop) 가이드를 확인하세요. ## 기타 정보 ### 원문 응답 -`rawResponses` 속성에는 에이전트 실행 중 모델이 생성한 원문의 LLM 응답이 포함됩니다. +`rawResponses` 속성에는 에이전트 실행 중 모델이 생성한 원문 LLM 응답이 포함됩니다. ### 마지막 응답 ID -`lastResponseId` 속성에는 에이전트 실행 중 모델이 생성한 마지막 응답의 ID 가 포함됩니다. +`lastResponseId` 속성에는 에이전트 실행 중 모델이 생성한 마지막 응답의 ID가 포함됩니다. ### 가드레일 결과 -`inputGuardrailResults`와 `outputGuardrailResults` 속성에는 가드레일 결과(있는 경우)가 포함됩니다. 가드레일 결과에는 로그를 남기거나 저장하고 싶은 유용한 정보가 포함될 수 있으므로 이를 제공해 드립니다. +`inputGuardrailResults`와 `outputGuardrailResults` 속성에는 가드레일 결과(있는 경우)가 포함됩니다. 가드레일 결과에는 기록하거나 저장하고 싶은 유용한 정보가 포함될 수 있으므로 이를 제공해 드립니다. -### 원본 입력 +### 원래 입력 -`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 72580d1c..32b6e131 100644 --- a/docs/src/content/docs/ko/guides/running-agents.mdx +++ b/docs/src/content/docs/ko/guides/running-agents.mdx @@ -11,23 +11,23 @@ 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 응답 검사 @@ -37,78 +37,78 @@ Runner에서 run 메서드를 사용할 때 시작 에이전트와 입력을 전 3. `maxTurns`에 도달하면 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) 발생 ### Runner 수명 주기 -앱이 시작될 때 `Runner`를 생성하고 요청 간에 재사용하세요. 인스턴스는 모델 프로바이더와 트레이싱 옵션 같은 전역 설정을 저장합니다. 완전히 다른 설정이 필요할 때만 다른 `Runner`를 만드세요. 간단한 스크립트에서는 내부적으로 기본 러너를 사용하는 `run()`을 호출할 수도 있습니다. +앱 시작 시 `Runner`를 생성하고 요청 간에 재사용하세요. 이 인스턴스는 모델 제공자와 트레이싱 옵션 같은 전역 구성을 저장합니다. 완전히 다른 설정이 필요할 때만 다른 `Runner`를 만드세요. 간단한 스크립트의 경우 내부적으로 기본 러너를 사용하는 `run()`을 호출할 수도 있습니다. ## 실행 인수 -`run()` 메서드의 입력은 실행을 시작할 초기 에이전트, 실행을 위한 입력, 그리고 옵션 집합입니다. +`run()` 메서드의 입력은 실행을 시작할 초기 에이전트, 실행 입력, 그리고 옵션 세트입니다. -입력은 문자열(사용자 메시지로 간주), [input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) 목록, 또는 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop) 에이전트를 구축하는 경우 [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) 객체일 수 있습니다. +입력은 문자열(사용자 메시지로 간주됨), [입력 항목](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) 리스트, 또는 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop) 에이전트를 구축하는 경우 [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) 객체일 수 있습니다. 추가 옵션은 다음과 같습니다: -| Option | Default | Description | -| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `stream` | `false` | `true`이면 호출은 `StreamedRunResult`를 반환하고 모델에서 도착하는 이벤트를 즉시 방출합니다. | -| `context` | – | 모든 tool / guardrail / handoff 에 전달되는 컨텍스트 객체. [컨텍스트 관리](/openai-agents-js/ko/guides/context) 가이드에서 자세히 보기 | -| `maxTurns` | `10` | 안전 한도 – 도달 시 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) 발생 | -| `signal` | – | 취소를 위한 `AbortSignal` | +| Option | Default | Description | +| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `stream` | `false` | `true`이면 호출이 `StreamedRunResult`를 반환하고 모델에서 도착하는 대로 이벤트를 내보냅니다. | +| `context` | – | 모든 도구 / 가드레일 / 핸드오프로 전달되는 컨텍스트 객체. [컨텍스트 가이드](/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`만, 때로는 생성된 모든 항목을 보여줍니다. -대화형 버전은 [채팅 code example](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) 을 참고하세요. +대화형 버전은 [채팅 예시](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts)를 참고하세요. -### 서버 관리형 대화 +### 서버 관리 대화 -매 턴마다 전체 로컬 대화 기록을 전송하는 대신 OpenAI Responses API가 대화 이력을 보존하도록 할 수 있습니다. 긴 대화나 여러 서비스를 조정할 때 유용합니다. 자세한 내용은 [Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) 를 참조하세요. +매 턴마다 로컬 전체 대화문을 보내는 대신 OpenAI Responses API가 대화 기록을 유지하도록 할 수 있습니다. 긴 대화나 여러 서비스를 조율할 때 유용합니다. 자세한 내용은 [Conversation state 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참조하세요. OpenAI는 서버 측 상태를 재사용하는 두 가지 방법을 제공합니다: #### 1. 전체 대화를 위한 `conversationId` -[Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) 로 한 번 대화를 생성한 뒤, 매 턴 해당 ID를 재사용할 수 있습니다. SDK는 자동으로 새로 생성된 항목만 포함합니다. +[Conversations API](https://platform.openai.com/docs/api-reference/conversations/create)로 한 번 대화를 만든 뒤, 매 턴에 그 ID를 재사용할 수 있습니다. SDK는 새로 생성된 항목만 자동으로 포함합니다. #### 2. 마지막 턴에서 이어가기 위한 `previousResponseId` -어차피 Responses API만으로 시작하려는 경우, 이전 응답에서 반환된 ID를 사용해 각 요청을 연결할 수 있습니다. 전체 대화 리소스를 만들지 않고도 턴 간 컨텍스트를 유지합니다. +어차피 Responses API만으로 시작하려는 경우, 이전 응답에서 반환된 ID를 사용해 각 요청을 체이닝할 수 있습니다. 별도의 대화 리소스를 만들지 않고도 턴 간 컨텍스트를 유지합니다. 위 예시를 실행하면 다음과 같은 출력이 표시됩니다: @@ -148,6 +148,6 @@ Math homework guardrail tripped ## 다음 단계 -- [모델](/openai-agents-js/ko/guides/models) 구성 방법 알아보기 -- 에이전트에 [도구](/openai-agents-js/ko/guides/tools) 제공 -- 프로덕션 준비를 위해 [가드레일](/openai-agents-js/ko/guides/guardrails) 또는 [트레이싱](/openai-agents-js/ko/guides/tracing) 추가 +- [모델 구성](/openai-agents-js/ko/guides/models)을 알아보세요. +- 에이전트에 [도구](/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/sessions.mdx b/docs/src/content/docs/ko/guides/sessions.mdx index 51eea7fa..3768166f 100644 --- a/docs/src/content/docs/ko/guides/sessions.mdx +++ b/docs/src/content/docs/ko/guides/sessions.mdx @@ -9,15 +9,15 @@ 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가 처리합니다. 세션이 있으면 러너는 자동으로 다음을 수행합니다. +세션은 Agents SDK에 **지속형 메모리 계층**을 제공합니다. `Session` 인터페이스를 구현하는 객체를 `Runner.run`에 전달하면 나머지는 SDK가 처리합니다. 세션이 있으면 러너는 자동으로 다음을 수행합니다. -1. 이전에 저장된 대화 항목을 가져와 다음 턴 앞에 붙입니다. -2. 각 실행이 완료된 후 새 사용자 입력과 어시스턴트 출력을 지속화합니다. -3. 새로운 사용자 텍스트로 러너를 호출하든 인터럽션(중단 처리)된 `RunState`에서 재개하든, 향후 턴을 위해 세션을 계속 사용할 수 있게 유지합니다. +1. 이전에 저장된 대화 항목을 가져와 다음 턴 앞에 추가합니다. +2. 각 실행이 완료된 후 새로운 사용자 입력과 어시스턴트 출력을 영구 저장합니다. +3. 새로운 사용자 텍스트로 러너를 호출하든, 인터럽트된 `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/`의 샘플 세션 백엔드(Prisma, 파일 기반 등)를 참고하세요. -> 팁: 이 페이지의 `OpenAIConversationsSession` 예제를 실행하려면 SDK가 Conversations API를 호출할 수 있도록 환경 변수 `OPENAI_API_KEY`를 설정하거나(또는 세션 생성 시 `apiKey`를 제공) 하세요. +> Tip: 이 페이지의 `OpenAIConversationsSession` 코드 예제를 실행하려면 `OPENAI_API_KEY` 환경 변수를 설정하세요(또는 세션 생성 시 `apiKey`를 제공). 그러면 SDK가 Conversations API를 호출할 수 있습니다. --- @@ -28,63 +28,67 @@ import sessionInputCallback from '../../../../../../examples/docs/sessions/sessi -동일한 세션 인스턴스를 재사용하면, 매 턴마다 에이전트가 전체 대화 히스토리를 수신하고 새 항목이 자동으로 지속화됩니다. 다른 `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 또는 다른 데이터 스토어로 메모리를 지원하세요. 필요한 것은 다섯 개의 비동기 메서드뿐입니다. +`Session` 인터페이스를 구현하여 Redis, DynamoDB, SQLite 또는 다른 데이터스토어로 메모리를 지원하세요. 필요한 비동기 메서드는 5개뿐입니다. -커스텀 세션을 통해 보존 정책을 강제하고, 암호화를 추가하거나, 지속화 전에 각 대화 턴에 메타데이터를 첨부할 수 있습니다. +커스텀 세션을 사용하면 보존 정책을 강제하거나, 암호화를 추가하거나, 영구 저장 전에 각 대화 턴에 메타데이터를 첨부할 수 있습니다. --- -## 히스토리와 새 항목 병합 제어 +## 히스토리와 신규 항목의 병합 제어 -실행 입력으로 `AgentInputItem` 배열을 전달할 때, 저장된 히스토리와 결정적으로 병합하기 위해 `sessionInputCallback`을 제공하세요. 러너는 기존 히스토리를 로드하고, **모델 호출 전에** 콜백을 호출하며, 반환된 배열을 해당 턴의 완전한 입력으로 모델에 전달합니다. 이 후크는 오래된 항목을 잘라내거나, 도구 결과의 중복을 제거하거나, 모델이 보길 원하는 컨텍스트만 강조하는 데 적합합니다. +실행 입력으로 `AgentInputItem` 배열을 전달하는 경우, `sessionInputCallback`을 제공하여 저장된 히스토리와 결정론적으로 병합하세요. 러너는 기존 히스토리를 로드하고, **모델 호출 전에** 콜백을 호출하며, 반환된 배열을 해당 턴의 완전한 입력으로 모델에 전달합니다. 이 훅은 오래된 항목을 잘라내거나, 도구 결과의 중복을 제거하거나, 모델이 보길 원하는 컨텍스트만 강조하는 데 이상적입니다. -문자열 입력의 경우 러너가 히스토리를 자동으로 병합하므로, 콜백은 선택 사항입니다. +문자열 입력의 경우 러너가 히스토리를 자동으로 병합하므로 콜백은 선택 사항입니다. --- ## 승인 및 재개 가능한 실행 처리 -Human-in-the-loop 흐름은 종종 승인을 기다리기 위해 실행을 일시 중지합니다: +휴먼인더루프 (HITL) 플로우는 종종 승인을 기다리기 위해 실행을 일시 중지합니다: ```typescript const result = await runner.run(agent, 'Search the itinerary', { @@ -99,4 +103,4 @@ if (result.requiresApproval) { } ``` -이전에 생성된 `RunState`에서 재개하면, 단일 대화 히스토리를 보존하기 위해 새 턴이 동일한 메모리 레코드에 추가됩니다. Human-in-the-loop (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 d301ffb9..438af5c9 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됩니다. 더 이상 출력이 없음을 보장하려면 반드시 이를 await하세요. +프로미스 `stream.completed`는 실행과 모든 보류 중인 콜백이 완료되면 resolve됩니다. 더 이상 출력이 없음을 보장하려면 항상 이를 기다리세요. ### 모든 이벤트 수신 -`for await` 루프를 사용하여 각 이벤트가 도착할 때 검사할 수 있습니다. 유용한 정보에는 저수준 모델 이벤트, 에이전트 전환, 그리고 SDK 고유의 실행 정보가 포함됩니다: +`for await` 루프를 사용해 이벤트가 도착할 때마다 검사할 수 있습니다. 유용한 정보에는 로우 레벨 모델 이벤트, 에이전트 전환, 그리고 SDK 고유의 실행 정보가 포함됩니다: -전체 텍스트 스트림과 원문 이벤트 스트림을 모두 출력하는 완성된 스크립트는 [the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts)을 참조하세요. +[스트리밍 code examples](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts)를 참고하면 일반 텍스트 스트림과 원문 이벤트 스트림을 모두 출력하는 완전한 스크립트를 볼 수 있습니다. ## 이벤트 유형 -스트림은 세 가지 서로 다른 이벤트 유형을 제공합니다: +스트림은 세 가지 서로 다른 이벤트 유형을 방출합니다: ### raw_model_stream_event @@ -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)입니다. +사용자와 상호작용하는 더 완전한 예시는 +[`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 c001b839..8a3f7e5e 100644 --- a/docs/src/content/docs/ko/guides/tools.mdx +++ b/docs/src/content/docs/ko/guides/tools.mdx @@ -10,10 +10,10 @@ 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 이 호출할 수 있도록 합니다. +2. **함수 도구** – 로컬 함수를 JSON 스키마로 감싸 LLM이 호출할 수 있게 합니다. 3. **에이전트를 도구로** – 전체 에이전트를 호출 가능한 도구로 노출합니다. 4. **로컬 MCP 서버** – 로컬에서 실행되는 Model context protocol 서버를 연결합니다. @@ -21,100 +21,101 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer ## 1. 호스티드 툴 -`OpenAIResponsesModel`을 사용할 때 다음 내장 도구를 추가할 수 있습니다: +`OpenAIResponsesModel`을 사용할 때 다음 기본 제공 도구를 추가할 수 있습니다: -| 도구 | Type 문자열 | 목적 | -| ---------------- | -------------------- | ------------------------------------ | -| 웹 검색 | `'web_search'` | 인터넷 검색 | -| 파일 / 검색 | `'file_search'` | OpenAI가 호스팅하는 벡터 스토어 조회 | -| 컴퓨터 사용 | `'computer'` | GUI 상호작용 자동화 | -| Shell | `'shell'` | 호스트에서 셸 명령 실행 | -| Apply patch | `'apply_patch'` | 호스트 파일에 V4A 패치 적용 | -| Code Interpreter | `'code_interpreter'` | 샌드박스 환경에서 코드 실행 | -| 이미지 생성 | `'image_generation'` | 텍스트 기반 이미지 생성 | +| 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'` | 텍스트 기반 이미지 생성 | - + -정확한 매개변수 세트는 OpenAI Responses API 와 일치합니다. `rankingOptions`나 시맨틱 필터 같은 고급 옵션은 공식 문서를 참고하세요. +정확한 매개변수 세트는 OpenAI Responses API와 일치합니다. `rankingOptions`나 의미론적 필터와 같은 고급 옵션은 공식 문서를 참고하세요. --- ## 2. 함수 도구 -`tool()` 헬퍼로 **어떤** 함수든 도구로 바꿀 수 있습니다. +`tool()` 헬퍼를 사용해 **어떤** 함수든 도구로 만들 수 있습니다. ### 옵션 참조 -| 필드 | 필수 | 설명 | -| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | 아니오 | 기본값은 함수 이름(예: `get_weather`) | -| `description` | 예 | LLM 에 표시되는 명확하고 사람이 읽을 수 있는 설명 | -| `parameters` | 예 | Zod 스키마 또는 원문 JSON 스키마 객체. Zod 매개변수는 자동으로 **strict** 모드를 활성화합니다 | -| `strict` | 아니오 | `true`(기본값)일 때 인자가 유효성 검사를 통과하지 않으면 SDK 가 모델 오류를 반환합니다. 모호한 매칭이 필요하면 `false`로 설정 | -| `execute` | 예 | `(args, context) => string \| Promise`– 비즈니스 로직. 두 번째 매개변수는 선택 사항이며 `RunContext`입니다 | -| `errorFunction` | 아니오 | 내부 오류를 사용자에게 보이는 문자열로 변환하는 커스텀 핸들러 `(context, error) => string` | +| Field | Required | Description | +| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | No | 기본값은 함수 이름입니다(예: `get_weather`) | +| `description` | Yes | LLM에 표시되는 명확하고 사람이 읽기 쉬운 설명 | +| `parameters` | Yes | Zod 스키마 또는 원문 JSON 스키마 객체 중 하나. Zod parameters를 사용하면 자동으로 **strict** 모드가 활성화됩니다 | +| `strict` | No | `true`(기본값)일 때, 인수가 검증에 실패하면 SDK가 모델 오류를 반환합니다. 퍼지 매칭이 필요하면 `false`로 설정하세요 | +| `execute` | Yes | `(args, context) => string \| Promise`– 비즈니스 로직. 두 번째 선택적 매개변수는 `RunContext`입니다 | +| `errorFunction` | No | 내부 오류를 사용자에게 보이는 문자열로 변환하는 커스텀 핸들러 `(context, error) => string` | -### 비엄격 JSON 스키마 도구 +### 비‑strict JSON‑스키마 도구 -유효하지 않거나 부분적인 입력을 모델이 추론하도록 하려면 원문 JSON 스키마를 사용할 때 strict 모드를 비활성화하세요: +유효하지 않거나 일부만 제공된 입력을 모델이 추론하도록 하려면 원문 JSON 스키마를 사용할 때 strict 모드를 비활성화할 수 있습니다: --- ## 3. 에이전트를 도구로 -대화를 완전히 핸드오프하지 않고도 한 에이전트가 다른 에이전트를 *보조*하도록 하고 싶을 때 `agent.asTool()`을 사용하세요: +대화를 완전히 핸드오프하지 않고 한 에이전트가 다른 에이전트를 *보조*하도록 하고 싶을 때 `agent.asTool()`을 사용하세요: - + -SDK 는 내부적으로 다음을 수행합니다: +내부적으로 SDK는 다음을 수행합니다: -- 단일 `input` 매개변수를 가진 함수 도구를 생성 -- 도구가 호출되면 해당 입력으로 하위 에이전트를 실행 -- 마지막 메시지 또는 `customOutputExtractor`가 추출한 출력을 반환 +- 단일 `input` 매개변수를 갖는 함수 도구를 생성 +- 도구가 호출되면 해당 입력으로 서브 에이전트를 실행 +- 마지막 메시지 또는 `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/ko/guides/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)를 참조하세요. --- ## 도구 사용 동작 -모델이 언제, 어떻게 도구를 사용해야 하는지 제어하려면 [에이전트](/openai-agents-js/ko/guides/agents#forcing-tool-use)를 참조하세요 (`tool_choice`, `toolUseBehavior` 등). +모델이 도구를 언제, 어떻게 사용해야 하는지(`tool_choice`, `toolUseBehavior` 등) 제어하려면 [에이전트](/openai-agents-js/ko/guides/agents#forcing-tool-use)를 참고하세요. --- ## 모범 사례 -- **짧고 명시적인 설명** – 도구가 _무엇을_ 하고 _언제 사용하는지_ 설명 -- **입력 유효성 검사** – 가능하면 Zod 스키마로 엄격한 JSON 검증 적용 -- **에러 핸들러에서 부작용 회피** – `errorFunction`은 예외를 던지지 말고 도움이 되는 문자열을 반환 -- **도구당 한 가지 책임** – 작고 조합 가능한 도구가 더 나은 모델 추론으로 이어짐 +- **짧고 명확한 설명** – 도구가 _무엇을 하는지_ 그리고 *언제 사용하는지*를 설명하세요. +- **입력 검증** – 가능하면 Zod 스키마로 엄격한 JSON 검증을 수행하세요. +- **에러 핸들러에서 부작용 회피** – `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 00370527..82421e86 100644 --- a/docs/src/content/docs/ko/guides/tracing.mdx +++ b/docs/src/content/docs/ko/guides/tracing.mdx @@ -7,22 +7,22 @@ import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw'; -Agents SDK에는 빌트인 트레이싱이 포함되어 있으며, 에이전트 실행 중 발생하는 이벤트의 포괄적인 기록을 수집합니다: LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 커스텀 이벤트까지 포함합니다. [Traces dashboard](https://platform.openai.com/traces)를 사용하여 개발 중과 프로덕션에서 워크플로를 디버그, 시각화, 모니터링할 수 있습니다. +Agents SDK에는 빌트인 트레이싱이 포함되어 있어 에이전트 실행 중 발생하는 이벤트의 포괄적인 기록을 수집합니다: LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 발생하는 사용자 지정 이벤트까지 포함됩니다. [Traces 대시보드](https://platform.openai.com/traces)를 사용하면 개발 중과 프로덕션 환경에서 워크플로를 디버그하고 시각화하며 모니터링할 수 있습니다. ## 내보내기 루프 라이프사이클 -대부분의 환경에서는 트레이스가 정기적으로 자동 내보내기됩니다. 브라우저나 Cloudflare Workers에서는 이 기능이 기본적으로 비활성화되어 있습니다. 트레이스가 너무 많이 대기열에 쌓인 경우에는 여전히 내보내기되지만, 정기적으로 내보내기되지는 않습니다. 대신 코드 라이프사이클의 일부로 `getGlobalTraceProvider().forceFlush()`를 사용하여 수동으로 트레이스를 내보내야 합니다. +대부분의 환경에서는 트레이스가 정기적으로 자동 내보내기됩니다. 브라우저 또는 Cloudflare Workers에서는 이 기능이 기본적으로 비활성화되어 있습니다. 너무 많은 트레이스가 대기열에 쌓이면 여전히 내보내기되지만, 정기적으로 내보내기되지는 않습니다. 대신 코드의 라이프사이클 내에서 `getGlobalTraceProvider().forceFlush()`를 사용해 트레이스를 수동으로 내보내야 합니다. 예를 들어 Cloudflare Worker에서는 코드를 `try/catch/finally` 블록으로 감싸고 `waitUntil`과 함께 강제 플러시를 사용하여 워커가 종료되기 전에 트레이스가 내보내지도록 해야 합니다. @@ -35,55 +35,55 @@ Agents SDK에는 빌트인 트레이싱이 포함되어 있으며, 에이전트 ## 트레이스와 스팬 - **트레이스(Traces)** 는 "워크플로"의 단일 엔드 투 엔드 작업을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: - - `workflow_name`: 논리적 워크플로 또는 앱 이름입니다. 예: "Code generation" 또는 "Customer service" - - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동 생성됩니다. 형식은 `trace_<32_alphanumeric>`이어야 합니다 - - `group_id`: 선택적 그룹 ID로, 동일한 대화에서 여러 트레이스를 연결합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다 - - `disabled`: True이면 트레이스가 기록되지 않습니다 - - `metadata`: 트레이스에 대한 선택적 메타데이터 -- **스팬(Spans)** 은 시작과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 포함됩니다: + - `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)으로 이름과 기타 속성을 구성할 수 있습니다. +기본적으로 트레이스 이름은 "Agent workflow"입니다. `withTrace`를 사용해 이 이름을 설정할 수 있으며, 또는 [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname)으로 이름과 기타 속성을 구성할 수 있습니다. -또한 [커스텀 트레이스 프로세서](#custom-tracing-processors)를 설정하여 트레이스를 다른 대상으로 푸시할 수 있습니다(대체 또는 보조 대상으로). +또한 [사용자 지정 트레이스 프로세서](#custom-tracing-processors)를 설정하여 트레이스를 다른 대상으로 전송할 수 있습니다(대체 또는 보조 대상으로). ### 음성 에이전트 트레이싱 -기본 OpenAI Realtime API와 함께 `RealtimeAgent` 및 `RealtimeSession`을 사용하는 경우, `RealtimeSession`에서 `tracingDisabled: true`를 사용하거나 `OPENAI_AGENTS_DISABLE_TRACING` 환경 변수를 사용하여 비활성화하지 않는 한 트레이싱은 Realtime API 측에서 자동으로 수행됩니다. +기본 OpenAI 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. 두 번의 `run` 호출이 `withTrace()`로 감싸져 있으므로, 개별 실행이 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다. +1. `withTrace()`로 두 번의 `run` 호출을 감쌌기 때문에, 개별 실행은 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다 ## 트레이스 생성 -[`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) 또는 해당 환경의 폴리필을 통해 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다. @@ -91,20 +91,20 @@ Agents SDK에는 빌트인 트레이싱이 포함되어 있으며, 에이전트 특정 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다. -`createGenerationSpan()`은 LLM 생성의 입력/출력을 저장하고, `createFunctionSpan()`은 함수 호출의 입력/출력을 저장합니다. 여기에는 민감한 데이터가 포함될 수 있으므로 [`RunConfig.traceIncludeSensitiveData +`createGenerationSpan()`은 LLM 생성의 입력/출력을 저장하고, `createFunctionSpan()`은 함수 호출의 입력/출력을 저장합니다. 여기에는 민감한 데이터가 포함될 수 있으므로, [`RunConfig.traceIncludeSensitiveData `](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata)를 통해 해당 데이터 캡처를 비활성화할 수 있습니다. -## 커스텀 트레이싱 프로세서 +## 사용자 지정 트레이싱 프로세서 트레이싱의 상위 수준 아키텍처는 다음과 같습니다: -- 초기화 시 글로벌 [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider)를 생성하며, 이는 트레이스 생성을 담당하고 [`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/)를 통해 액세스할 수 있습니다 -- `TraceProvider`는 [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/)로 구성되며, 이는 트레이스/스팬을 배치로 [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/)에 전송하고, 이 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/)에 전송합니다. 이 Exporter는 스팬과 트레이스를 OpenAI 백엔드로 배치 내보내기합니다 -이 기본 설정을 커스터마이즈하여 다른 백엔드로 전송하거나 추가 백엔드로도 전송하거나 Exporter 동작을 수정하려면 두 가지 옵션이 있습니다: +기본 설정을 사용자 지정하여 대체 또는 추가 백엔드로 트레이스를 전송하거나 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 30be82ee..3a466b2d 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+ @@ -13,29 +13,29 @@ OpenAI Agents SDK는 다음 서버 환경에서 지원됩니다: ### 제한적 지원 -- **Cloudflare Workers**: Agents SDK는 Cloudflare Workers에서 사용할 수 있지만 현재 몇 가지 제한 사항이 있습니다: - - 현재 SDK는 `nodejs_compat` 활성화가 필요합니다 - - 트레이스는 요청이 끝날 때 수동으로 플러시해야 합니다. 자세한 내용은 [트레이싱 가이드](/openai-agents-js/ko/guides/tracing#export-loop-lifecycle)를 참고하세요. - - Cloudflare Workers의 `AsyncLocalStorage` 제한적 지원으로 일부 트레이스가 정확하지 않을 수 있습니다 - - 아웃바운드 WebSocket 연결은 fetch 기반 업그레이드를 사용해야 합니다(전역 `WebSocket` 생성자 사용 불가). Realtime의 경우 `@openai/agents-extensions`의 Cloudflare 전송(`CloudflareRealtimeTransportLayer`)을 사용하세요. -- **Browsers**: - - 브라우저에서는 현재 트레이싱이 지원되지 않습니다 +- **Cloudflare Workers**: Agents SDK는 Cloudflare Workers에서 사용할 수 있지만, 현재 다음과 같은 제한이 있습니다: + - SDK는 현재 `nodejs_compat` 활성화가 필요함 + - 요청 종료 시 트레이스를 수동으로 플러시해야 합니다. 자세한 내용은 [트레이싱 가이드](/openai-agents-js/ko/guides/tracing#export-loop-lifecycle)를 참조하세요. + - Cloudflare Workers의 `AsyncLocalStorage` 제한적 지원으로 인해 일부 트레이스가 정확하지 않을 수 있음 + - 아웃바운드 WebSocket 연결은 전역 `WebSocket` 생성자가 아닌 fetch 기반 업그레이드를 사용해야 합니다. Realtime의 경우 `@openai/agents-extensions`의 Cloudflare 전송(`CloudflareRealtimeTransportLayer`)을 사용하세요. +- **브라우저**: + - 브라우저에서는 현재 트레이싱이 지원되지 않음 - **v8 isolates**: - - 올바른 브라우저 폴리필이 포함된 번들러를 사용하면 v8 isolates용으로 SDK를 번들링할 수 있지만, 트레이싱은 동작하지 않습니다 - - v8 isolates는 광범위하게 테스트되지 않았습니다 + - 적절한 브라우저 폴리필을 포함한 번들러를 사용하면 v8 isolates용으로 SDK를 번들링할 수 있지만, 트레이싱은 작동하지 않음 + - v8 isolates는 광범위하게 테스트되지 않음 ## 디버그 로깅 -SDK에서 문제가 발생하는 경우, 디버그 로깅을 활성화해 동작에 대한 더 많은 정보를 확인할 수 있습니다. +SDK에서 문제가 발생하는 경우, 디버그 로깅을 활성화하여 동작에 대한 추가 정보를 확인할 수 있습니다. -`DEBUG` 환경 변수를 `openai-agents:*`로 설정해 디버그 로깅을 활성화하세요. +`DEBUG` 환경 변수를 `openai-agents:*`로 설정하여 디버그 로깅을 활성화하세요. ```bash DEBUG=openai-agents:* ``` -또는 SDK의 특정 부분으로 디버깅 범위를 한정할 수 있습니다: +또는 SDK의 특정 부분만 범위를 지정하여 디버깅할 수 있습니다: - `openai-agents:core` — SDK의 주요 실행 로직 - `openai-agents:openai` — OpenAI API 호출 -- `openai-agents:realtime` — 실시간 에이전트 구성 요소 +- `openai-agents:realtime` — Realtime Agents 구성 요소 diff --git a/docs/src/content/docs/ko/guides/voice-agents.mdx b/docs/src/content/docs/ko/guides/voice-agents.mdx index 91a54a9b..e05f6b69 100644 --- a/docs/src/content/docs/ko/guides/voice-agents.mdx +++ b/docs/src/content/docs/ko/guides/voice-agents.mdx @@ -25,27 +25,27 @@ import thinClientExample from '../../../../../../examples/docs/voice-agents/thin ![Realtime Agents](https://cdn.openai.com/API/docs/images/diagram-speech-to-speech.png) -음성 에이전트는 OpenAI 음성-음성 모델을 사용해 실시간 음성 채팅을 제공합니다. 이 모델은 스트리밍 오디오, 텍스트, 도구 호출을 지원하며, 음성/전화 고객 지원, 모바일 앱 경험, 음성 채팅과 같은 애플리케이션에 적합합니다. +Voice Agents 는 OpenAI 음성-음성 모델을 사용해 실시간 음성 채팅을 제공합니다. 이들 모델은 오디오, 텍스트, 도구 호출의 스트리밍을 지원하며 음성/전화 고객 지원, 모바일 앱 경험, 음성 채팅과 같은 애플리케이션에 적합합니다. 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 9e15f446..36bde36d 100644 --- a/docs/src/content/docs/ko/guides/voice-agents/build.mdx +++ b/docs/src/content/docs/ko/guides/voice-agents/build.mdx @@ -30,77 +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)과 일치하는 모든 parameter를 전달할 수 있습니다. +이 전송 계층은 [session](https://platform.openai.com/docs/api-reference/realtime-client-events/session/update)과 일치하는 모든 매개변수를 전달할 수 있습니다. -[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/)에 아직 매칭되는 parameter가 없는 새로운 parameter의 경우 `providerData`를 사용할 수 있습니다. `providerData`에 전달된 내용은 `session` 객체의 일부로 그대로 전달됩니다. +[RealtimeSessionConfig](/openai-agents-js/openai/agents-realtime/type-aliases/realtimesessionconfig/)에 대응되는 매개변수가 아직 없는 새로운 매개변수의 경우 `providerData`를 사용할 수 있습니다. `providerData`에 전달된 모든 내용은 `session` 객체의 일부로 그대로 전달됩니다. ## 핸드오프 -일반 에이전트와 유사하게, 핸드오프를 사용하여 에이전트를 여러 에이전트로 나누고 이들 간을 오케스트레이션하여 에이전트의 성능을 개선하고 문제 범위를 더 잘 설정할 수 있습니다. +일반 에이전트와 마찬가지로 핸드오프를 사용하여 에이전트를 여러 에이전트로 분할하고 이들 사이를 오케스트레이션하여 에이전트의 성능을 개선하고 문제 범위를 더 잘 한정할 수 있습니다. -일반 에이전트와 달리, 실시간 에이전트에서는 핸드오프가 약간 다르게 동작합니다. 핸드오프가 수행되면 진행 중인 세션이 새로운 에이전트 구성으로 업데이트됩니다. 이로 인해 에이전트는 진행 중인 대화 기록에 자동으로 접근할 수 있으며 입력 필터는 현재 적용되지 않습니다. +일반 에이전트와 달리, 실시간 에이전트에서는 핸드오프 동작이 약간 다릅니다. 핸드오프가 수행되면 진행 중인 세션이 새로운 에이전트 구성으로 업데이트됩니다. 이로 인해 에이전트는 진행 중인 대화 기록에 자동으로 접근할 수 있으며, 현재 입력 필터는 적용되지 않습니다. -또한 이는 핸드오프의 일부로 `voice` 또는 `model`을 변경할 수 없음을 의미합니다. 다른 실시간 에이전트에만 연결할 수 있습니다. 예를 들어 `gpt-5-mini` 같은 reasoning 모델이 필요하다면, [delegation through tools](#delegation-through-tools)를 사용할 수 있습니다. +또한 이는 핸드오프의 일부로 `voice` 또는 `model`을 변경할 수 없음을 의미합니다. 다른 실시간 에이전트에만 연결할 수 있습니다. 다른 모델(예: `gpt-5-mini` 같은 reasoning 모델)을 사용해야 하는 경우, [도구를 통한 위임](#delegation-through-tools)을 사용할 수 있습니다. ## 도구 -일반 에이전트와 마찬가지로, 실시간 에이전트는 작업을 수행하기 위해 도구를 호출할 수 있습니다. 일반 에이전트에서 사용하는 것과 동일한 `tool()` 함수를 사용해 도구를 정의할 수 있습니다. +일반 에이전트와 마찬가지로 실시간 에이전트는 작업을 수행하기 위해 도구를 호출할 수 있습니다. 일반 에이전트에서 사용하던 것과 동일한 `tool()` 함수를 사용하여 도구를 정의할 수 있습니다. -실시간 에이전트에서는 function tools만 사용할 수 있으며, 이 도구들은 실시간 세션과 동일한 위치에서 실행됩니다. 즉, 브라우저에서 실시간 세션을 실행 중이라면 도구도 브라우저에서 실행됩니다. 보다 민감한 작업을 수행해야 한다면, 도구 내부에서 백엔드 서버로 HTTP 요청을 보낼 수 있습니다. +실시간 에이전트에서는 함수 도구만 사용할 수 있으며, 이 도구들은 실시간 세션과 동일한 위치에서 실행됩니다. 즉, 실시간 세션을 브라우저에서 실행 중이라면 도구도 브라우저에서 실행됩니다. 더 민감한 작업을 수행해야 한다면 도구 내부에서 백엔드 서버로 HTTP 요청을 보낼 수 있습니다. -도구가 실행되는 동안 에이전트는 사용자로부터의 새로운 요청을 처리할 수 없습니다. 경험을 개선하는 한 가지 방법은 에이전트가 도구를 실행하려고 한다고 알리거나, 도구를 실행할 시간을 벌기 위해 특정 문구를 말하도록 하는 것입니다. +도구가 실행되는 동안 에이전트는 사용자로부터 새로운 요청을 처리할 수 없습니다. 경험을 개선하는 한 가지 방법은 에이전트에게 도구를 실행하려고 할 때 이를 알리도록 하거나, 도구를 실행하는 시간을 벌기 위한 특정 문구를 말하도록 지시하는 것입니다. ### 대화 기록 접근 -에이전트가 특정 도구를 호출할 때 전달한 인자 외에도, 실시간 세션에서 추적하는 현재 대화 기록의 스냅샷에 접근할 수 있습니다. 이는 현재 대화 상태를 기반으로 더 복잡한 작업을 수행해야 하거나 [tools for delegation](#delegation-through-tools)을 사용할 계획일 때 유용합니다. +에이전트가 특정 도구를 호출할 때 전달된 인자 외에도, 실시간 세션이 추적하는 현재 대화 기록의 스냅샷에 접근할 수 있습니다. 이는 현재 대화 상태를 기반으로 더 복잡한 작업을 수행해야 하거나 [도구를 통한 위임](#delegation-through-tools)을 사용할 계획인 경우 유용합니다. ### 도구 실행 전 승인 -도구를 `needsApproval: true`로 정의하면, 에이전트는 도구를 실행하기 전에 `tool_approval_requested` 이벤트를 emit합니다. +도구를 `needsApproval: true`로 정의하면, 에이전트는 도구를 실행하기 전에 `tool_approval_requested` 이벤트를 발생시킵니다. -이 이벤트를 수신하여 사용자에게 도구 호출 승인 또는 거부 UI를 표시할 수 있습니다. +이 이벤트를 수신하여 사용자에게 도구 호출을 승인하거나 거부할 수 있는 UI를 표시할 수 있습니다. ## 가드레일 -가드레일은 에이전트의 발화가 규칙을 위반했는지 모니터링하고 응답을 즉시 차단하는 방법을 제공합니다. 이러한 가드레일 검사는 에이전트 응답의 전사(transcript)를 기반으로 수행되므로 모델의 텍스트 출력이 활성화되어 있어야 합니다(기본적으로 활성화됨). +가드레일은 에이전트의 발화가 규칙 집합을 위반했는지 모니터링하고 응답을 즉시 차단하는 방법을 제공합니다. 이러한 가드레일 검사는 에이전트 응답의 전사를 기반으로 수행되므로 모델의 텍스트 출력이 활성화되어 있어야 합니다(기본적으로 활성화됨). -제공한 가드레일은 모델 응답이 반환되는 동안 비동기적으로 실행되어, 예를 들어 "특정 금지어를 언급" 같은 사전 정의된 분류 트리거를 기반으로 응답을 차단할 수 있습니다. +제공한 가드레일은 모델 응답이 반환되는 동안 비동기로 실행되어, 예를 들어 "특정 금지어를 언급" 같은 사전 정의된 분류 트리거를 기반으로 응답을 차단할 수 있습니다. -가드레일이 작동하면 세션은 `guardrail_tripped` 이벤트를 emit합니다. 이 이벤트는 가드레일을 트리거한 `itemId`를 포함하는 `details` 객체도 제공합니다. +가드레일이 트리거되면 세션은 `guardrail_tripped` 이벤트를 발생시킵니다. 이벤트에는 가드레일을 트리거한 `itemId`를 포함한 `details` 객체도 제공됩니다. -기본적으로 가드레일은 100자마다 또는 응답 텍스트의 끝에서 실행됩니다. -보통 텍스트를 말하는 데 더 오래 걸리므로, 대부분의 경우 사용자에게 들리기 전에 -가드레일이 위반을 포착할 수 있습니다. +기본적으로 가드레일은 100자마다 또는 응답 텍스트가 생성 완료될 때 실행됩니다. 일반적으로 텍스트를 말하는 데 더 오래 걸리므로, 대부분의 경우 가드레일이 사용자가 듣기 전에 위반을 포착하게 됩니다. 이 동작을 수정하려면 세션에 `outputGuardrailSettings` 객체를 전달할 수 있습니다. @@ -108,27 +106,27 @@ import turnDetectionExample from '../../../../../../../examples/docs/voice-agent ## 턴 감지 / 음성 활동 감지 -실시간 세션은 사용자가 말할 때를 자동으로 감지하고 Realtime API의 내장된 [voice activity detection modes of the Realtime API](https://platform.openai.com/docs/guides/realtime-vad)를 사용하여 새로운 턴을 트리거합니다. +실시간 세션은 사용자가 말할 때를 자동으로 감지하고 [Realtime API의 내장 음성 활동 감지 모드](https://platform.openai.com/docs/guides/realtime-vad)를 사용하여 새로운 턴을 트리거합니다. 세션에 `turnDetection` 객체를 전달하여 음성 활동 감지 모드를 변경할 수 있습니다. -턴 감지 설정을 조정하면 원치 않는 인터럽션과 침묵 처리 보정에 도움이 됩니다. 다양한 설정에 대한 자세한 내용은 [Realtime API documentation for more details on the different settings](https://platform.openai.com/docs/guides/realtime-vad)을 참조하세요 +턴 감지 설정을 조정하면 원치 않는 인터럽션과 침묵 처리 보정에 도움이 됩니다. 다양한 설정에 대한 자세한 내용은 [Realtime API 문서](https://platform.openai.com/docs/guides/realtime-vad)를 참고하세요. ## 인터럽션(중단 처리) -내장된 음성 활동 감지를 사용할 때, 사용자가 에이전트의 발화에 겹쳐 말하면 에이전트가 자동으로 그 내용을 감지하고 컨텍스트를 업데이트합니다. 또한 `audio_interrupted` 이벤트를 emit합니다. 이는 모든 오디오 재생을 즉시 중지하는 데 사용할 수 있습니다(웹소켓 연결에만 적용). +내장 음성 활동 감지를 사용할 때, 사용자가 에이전트의 발화 중에 말하면 에이전트는 자동으로 이를 감지하고 말한 내용에 따라 컨텍스트를 업데이트합니다. 또한 `audio_interrupted` 이벤트를 발생시킵니다. 이는 모든 오디오 재생을 즉시 중지하는 데 사용할 수 있습니다(WebSocket 연결에만 적용). -수동 인터럽션을 수행하려는 경우, 예를 들어 UI에 "중지" 버튼을 제공하려면 `interrupt()`를 수동으로 호출할 수 있습니다: +수동 인터럽션을 수행하려면, 예를 들어 UI에 "중지" 버튼을 제공하려는 경우 `interrupt()`를 수동으로 호출할 수 있습니다: -어느 방식이든, 실시간 세션은 에이전트의 생성 중단, 사용자에게 말한 내용의 단절 처리, 그리고 history 업데이트를 모두 처리합니다. +어느 경우든, 실시간 세션은 에이전트의 생성 중단, 사용자에게 말한 내용에 대한 지식 절단, 기록 업데이트를 모두 처리합니다. -에이전트에 WebRTC로 연결하는 경우 오디오 출력도 지워집니다. WebSocket을 사용하는 경우, 재생 대기 중인 오디오의 재생을 중지하는 처리는 직접 구현해야 합니다. +WebRTC로 에이전트에 연결하는 경우 오디오 출력도 지워집니다. WebSocket을 사용하는 경우에는 재생 대기 중인 오디오의 재생을 중지하는 처리를 직접 구현해야 합니다. ## 텍스트 입력 @@ -142,26 +140,26 @@ import turnDetectionExample from '../../../../../../../examples/docs/voice-agent `RealtimeSession`은 `history` 속성에서 대화 기록을 자동으로 관리합니다: -이를 사용하여 고객에게 history를 렌더링하거나 추가 작업을 수행할 수 있습니다. 대화 중에는 history가 지속적으로 변경되므로 `history_updated` 이벤트를 수신할 수 있습니다. +이를 사용해 고객에게 기록을 렌더링하거나 추가 작업을 수행할 수 있습니다. 대화가 진행되는 동안 이 기록은 지속적으로 변경되므로 `history_updated` 이벤트를 수신할 수 있습니다. -history를 수정하고 싶다면, 예를 들어 메시지를 완전히 제거하거나 전사를 업데이트하는 경우 `updateHistory` 메서드를 사용할 수 있습니다. +기록을 수정하고 싶다면, 예를 들어 메시지를 완전히 제거하거나 전사를 업데이트하려면 `updateHistory` 메서드를 사용할 수 있습니다. ### 제한 사항 -1. 현재 시점에서는 function tool 호출을 사후에 업데이트/변경할 수 없습니다 -2. history의 텍스트 출력에는 transcripts와 텍스트 모달리티가 활성화되어 있어야 합니다 +1. 현재로서는 사후에 함수 도구 호출을 업데이트/변경할 수 없습니다 +2. 기록의 텍스트 출력에는 전사와 텍스트 모달리티가 활성화되어 있어야 합니다 3. 인터럽션으로 인해 잘린 응답에는 전사가 없습니다 ## 도구를 통한 위임 ![도구를 통한 위임](https://cdn.openai.com/API/docs/diagram-speech-to-speech-agent-tools.png) -대화 기록과 도구 호출을 결합하여, 대화를 다른 백엔드 에이전트에 위임해 더 복잡한 작업을 수행한 뒤 그 결과를 사용자에게 다시 전달할 수 있습니다. +대화 기록과 도구 호출을 결합하면, 더 복잡한 작업을 수행하기 위해 대화를 다른 백엔드 에이전트에 위임한 다음 그 결과를 사용자에게 다시 전달할 수 있습니다. -아래 코드는 서버에서 실행됩니다. 이 예시는 Next.js의 server actions를 통해 수행됩니다. +아래 코드는 서버에서 실행됩니다. 이 예시에서는 Next.js의 server actions를 통해 실행됩니다. diff --git a/docs/src/content/docs/ko/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/ko/guides/voice-agents/quickstart.mdx index 3ec3b55c..34ee6a48 100644 --- a/docs/src/content/docs/ko/guides/voice-agents/quickstart.mdx +++ b/docs/src/content/docs/ko/guides/voice-agents/quickstart.mdx @@ -26,9 +26,9 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t -0. **프로젝트 만들기** +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 @@ -44,7 +44,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 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'; @@ -74,9 +74,9 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` -4. **세션 만들기** +4. **세션 생성** - 일반 에이전트와 달리, 음성 에이전트는 대화를 지속적으로 실행하며 시간에 따라 모델과의 연결을 처리하는 `RealtimeSession` 내에서 실행되고 청취합니다. 이 세션은 오디오 처리, 인터럽션(중단 처리) 및 이후에 다룰 기타 많은 라이프사이클 기능도 처리합니다. + 일반 에이전트와 달리 음성 에이전트는 대화와 모델과의 장기 연결을 처리하는 `RealtimeSession` 내부에서 지속적으로 실행되고 청취합니다. 이 세션은 오디오 처리, 인터럽션(중단 처리), 그 밖의 이후에 다룰 많은 라이프사이클 기능도 처리합니다. ```typescript import { RealtimeSession } from '@openai/agents/realtime'; @@ -86,7 +86,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` 생성자는 첫 번째 인수로 `agent`를 받습니다. 이 에이전트가 사용자가 처음 상호작용할 수 있는 에이전트가 됩니다. + `RealtimeSession` 생성자는 첫 번째 인자로 `agent`를 받습니다. 이 에이전트는 사용자가 처음 상호작용할 수 있는 에이전트가 됩니다. 5. **세션에 연결** @@ -96,15 +96,15 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t await session.connect({ apiKey: 'ek_...(put your own key here)' }); ``` - 이는 브라우저에서 WebRTC를 사용해 Realtime API에 연결하고 오디오 입력과 출력을 위해 마이크와 스피커를 자동으로 구성합니다. `RealtimeSession`을 백엔드 서버(예: Node.js)에서 실행하는 경우 SDK는 자동으로 WebSocket을 연결로 사용합니다. 다양한 전송 계층에 대한 자세한 내용은 [Realtime 전송 계층](/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 에이전트 코드가 포함된 페이지로 이동하세요. 마이크 접근 권한 요청이 표시됩니다. 접근을 허용하면 에이전트와 대화를 시작할 수 있습니다. + 웹 서버를 시작하고 새 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 2584278a..65caad61 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로 전화 에이전트를 구축할 때 잘 작동합니다. +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에 더 직접 접근하려면 두 가지 옵션이 있습니다. +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 ef5c7dd3..a902f392 100644 --- a/docs/src/content/docs/ko/index.mdx +++ b/docs/src/content/docs/ko/index.mdx @@ -21,37 +21,40 @@ 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는 매우 +구축할 수 있게 해줍니다. 이는 이전 에이전트 실험인 +[Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션급 업그레이드이며, +[Python 버전](https://github.com/openai/openai-agents-python)도 제공됩니다. Agents SDK는 매우 작은 기본 구성 요소 집합을 제공합니다: -- **에이전트**: instructions와 tools가 장착된 LLM -- **핸드오프**: 특정 작업을 다른 에이전트에 위임할 수 있도록 함 -- **가드레일**: 에이전트 입력을 검증할 수 있도록 함 +- **Agents**: instructions와 tools를 갖춘 LLM +- **Handoffs**: 에이전트가 특정 작업을 다른 에이전트에 위임하도록 허용 +- **Guardrails**: 에이전트 입력을 검증할 수 있도록 지원 -TypeScript와 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 +TypeScript와 결합하면, 이 기본 구성 요소만으로도 tools와 에이전트 간의 복잡한 관계를 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 -구축할 수 있습니다. 또한 SDK에는 기본 제공 **트레이싱**이 포함되어 있어 -에이전트 플로우를 시각화하고 디버그하며, 평가하고 애플리케이션에 맞게 -모델을 파인튜닝할 수 있습니다. +구축할 수 있습니다. 또한 SDK에는 에이전트의 흐름을 시각화하고 디버그할 수 +있도록 하는 기본 제공 **트레이싱**이 포함되어 있으며, 이를 평가하고 +애플리케이션에 맞게 모델을 파인튜닝할 수도 있습니다. -## 왜 Agents SDK를 사용해야 하는가 +## Agents SDK를 사용하는 이유 -SDK의 두 가지 핵심 설계 원칙: +SDK의 핵심 설계 원칙은 두 가지입니다: -1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 배움이 빠르도록 기본 구성 요소는 최소화 -2. 기본 설정만으로도 훌륭히 동작하지만, 동작 방식을 정확히 커스터마이즈 가능 +1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 학습할 수 있도록 기본 구성 요소는 최소화 +2. 기본 설정만으로도 충분히 잘 동작하되, 내부 동작을 정확히 원하는 대로 커스터마이즈 가능 -SDK의 주요 기능: +SDK의 주요 기능은 다음과 같습니다: -- **에이전트 루프**: 도구 호출, 결과를 LLM으로 전송, LLM 완료까지 반복을 처리하는 기본 제공 루프 -- **TypeScript 우선**: 새로운 추상화를 배우지 않고도 언어 기능으로 에이전트를 오케스트레이션하고 체이닝 -- **핸드오프**: 여러 에이전트 간의 조정과 위임을 위한 강력한 기능 -- **가드레일**: 에이전트와 병렬로 입력 검증과 체크를 수행하며, 실패 시 조기 중단 -- **함수 도구**: 어떤 TypeScript 함수든 도구로 전환, 자동 스키마 생성 및 Zod 기반 검증 -- **트레이싱**: 워크플로를 시각화, 디버그, 모니터링하고 OpenAI의 평가, 파인튜닝, 증류 도구 사용 가능 -- **실시간 에이전트**: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등 강력한 음성 에이전트 구축 +- **Agent loop**: tools 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 루프를 + 처리하는 기본 제공 에이전트 루프 +- **TypeScript 우선**: 새로운 추상화 학습 없이, 내장 언어 기능으로 에이전트를 + 오케스트레이션하고 체이닝 +- **Handoffs**: 여러 에이전트 간의 조정과 위임을 위한 강력한 기능 +- **Guardrails**: 에이전트와 병렬로 입력 검증과 체크를 실행하고, 실패 시 조기 중단 +- **함수 도구**: 어떤 TypeScript 함수든 자동 스키마 생성과 Zod 기반 검증으로 tool로 전환 +- **트레이싱**: 워크플로를 시각화, 디버그, 모니터링하고 OpenAI의 평가, 파인튜닝, + 증류 도구를 사용할 수 있게 하는 기본 제공 트레이싱 +- **실시간 에이전트**: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등을 포함한 강력한 음성 에이전트 구축 ## 설치 @@ -63,7 +66,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 a90bac34..a5fab867 100644 --- a/docs/src/content/docs/zh/extensions/ai-sdk.mdx +++ b/docs/src/content/docs/zh/extensions/ai-sdk.mdx @@ -7,12 +7,12 @@ import { Aside, Steps, Code } from '@astrojs/starlight/components'; import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw'; -Agents SDK 开箱即可通过 Responses API 或 Chat Completions API 与 OpenAI 模型配合使用。不过，如果您想使用其他模型，[Vercel 的 AI SDK](https://sdk.vercel.ai/) 提供了多种受支持的模型，可以通过此适配器引入到 Agents SDK 中。 +开箱即用时，Agents SDK 通过 Responses API 或 Chat Completions API 与 OpenAI 模型配合工作。不过，如果您想使用其他模型，[Vercel 的 AI SDK](https://sdk.vercel.ai/) 提供了多种受支持的模型，可通过此适配器引入到 Agents SDK 中。 ## 设置 @@ -24,7 +24,7 @@ Agents SDK 开箱即可通过 Responses API 或 Chat Completions API 与 OpenAI 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 @@ -46,8 +46,8 @@ Agents SDK 开箱即可通过 Responses API 或 Chat Completions API 与 OpenAI @@ -56,9 +56,9 @@ Agents SDK 开箱即可通过 Responses API 或 Chat Completions API 与 OpenAI -## 传递提供商元数据 +## 传递提供方元数据 -如果您需要随消息发送特定于提供商的选项，请通过 `providerMetadata` 传递。这些值会直接转发到底层的 AI SDK 模型。例如，以下在 Agents SDK 中的 `providerData` +如果您需要随消息发送提供方特定的选项，请通过 `providerMetadata` 传递。这些值会直接转发给底层的 AI SDK 模型。例如，以下在 Agents SDK 中的 `providerData` ```ts providerData: { @@ -70,7 +70,7 @@ providerData: { } ``` -在使用 AI SDK 集成时将变为 +在使用 AI SDK 集成时会变为 ```ts providerMetadata: { diff --git a/docs/src/content/docs/zh/extensions/cloudflare.mdx b/docs/src/content/docs/zh/extensions/cloudflare.mdx index abd04cd6..3e7d0977 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 连接。为便于在这些环境中连接实时智能体（Realtime Agents），extensions 包提供了一个专用传输，在内部执行基于 `fetch()` 的升级。 +Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构造函数发起出站 WebSocket 连接。为便于在这些环境中连接 实时智能体，扩展包提供了一个专用的传输适配器，在内部使用基于 `fetch()` 的升级方式。 @@ -19,13 +19,13 @@ Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构 -1. **安装 extensions 包。** +1. **安装扩展包。** ```bash npm install @openai/agents-extensions ``` -2. **创建一个传输并将其附加到您的会话。** +2. **创建传输适配器并将其附加到您的会话。** @@ -39,6 +39,6 @@ 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 7c110cf5..8767212e 100644 --- a/docs/src/content/docs/zh/extensions/twilio.mdx +++ b/docs/src/content/docs/zh/extensions/twilio.mdx @@ -7,12 +7,17 @@ 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 的连接， +包括中断处理和音频转发。 @@ -21,13 +26,14 @@ Twilio 提供了一个 [Media Streams API](https://www.twilio.com/docs/voice/med -1. **确保您拥有 Twilio 账户和 Twilio 电话号码。** +1. **确保您拥有 Twilio 账户和一个 Twilio 电话号码。** 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 适配器：** @@ -36,7 +42,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 的所有调试日志。或者，您也可以使用 - `DEBUG=openai-agents:extensions:twilio*` 仅启用 Twilio 适配器的调试日志。 + 有时您可能会遇到需要更多信息的问题。使用 + 环境变量 `DEBUG=openai-agents*` 将显示来自 Agents SDK 的所有调试日志。 + 或者，您也可以仅为 Twilio 适配器启用调试日志： + `DEBUG=openai-agents:extensions:twilio*`。 ## 完整示例服务器 -下面是一个端到端的 WebSocket 服务器示例，它接收来自 Twilio 的请求并将其转发到 `RealtimeSession`。 +下面是一个端到端的 WebSocket 服务器示例，用于接收来自 +Twilio 的请求并将其转发到 `RealtimeSession`。 + 本页其余部分将更详细地介绍每个 Agent 功能。 --- -## 基本配置 +## 基础配置 -`Agent` 构造函数接收一个配置对象。最常用的属性如下： +`Agent` 构造函数接收一个配置对象。最常用的属性如下所示。 -| Property | Required | Description | -| --------------- | -------- | ------------------------------------------------------------------------------------------ | -| `name` | yes | 简短、便于阅读的标识符。 | -| `instructions` | yes | 系统提示（字符串**或**函数——参见[动态 instructions](#dynamic-instructions)）。 | -| `model` | no | 模型名称**或**自定义的 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 实现。 | -| `modelSettings` | no | 调优参数（temperature、top_p 等）。如果所需属性不在顶层，可将其放在 `providerData` 下。 | -| `tools` | no | 模型可调用的 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 实例数组。 | +| 属性 | 必需 | 描述 | +| --------------- | ---- | ------------------------------------------------------------------------------------------ | +| `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) schema（`z.object({...})`）。 -2. 任意兼容 JSON Schema 的对象。 +1. [Zod](https://github.com/colinhacks/zod) 模式（`z.object({...})`）。 +2. 任何兼容 JSON Schema 的对象。 当提供了 `outputType` 时，SDK 会自动使用 -[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)，而非纯文本。 +[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) 而不是纯文本。 --- ## 多智能体系统设计模式 -将智能体组合在一起有多种方式。我们在生产应用中常见的两种模式是： +组合智能体有多种方式。我们在生产应用中经常看到的两种模式是： -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 钩子事件。 +对于高级用例，你可以通过监听事件来观察 Agent 的生命周期。可用事件名称参见[此处](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts)的 agent 钩子事件列表。 --- ## 护栏 -护栏允许你验证或转换用户输入和智能体输出。通过 `inputGuardrails` 和 `outputGuardrails` 数组进行配置。详见[护栏](/openai-agents-js/zh/guides/guardrails)。 +护栏允许你验证或转换用户输入与智能体输出。通过 `inputGuardrails` 与 `outputGuardrails` 数组进行配置。详情参见[护栏](/openai-agents-js/zh/guides/guardrails)指南。 --- -## 克隆/复制智能体 +## 智能体克隆/复制 -需要在现有智能体的基础上做些微调整？使用 `clone()` 方法，它会返回一个全新的 `Agent` 实例。 +需要现有智能体的稍作修改版本？使用 `clone()` 方法，它会返回一个全新的 `Agent` 实例。 --- -## 强制使用工具 +## 强制工具使用 -提供工具并不保证 LLM 一定会调用。你可以通过 `modelSettings.tool_choice` **强制**使用工具： +提供工具并不保证 LLM 会调用它。你可以通过 `modelSettings.tool_choice` **强制**使用工具： -1. `'auto'`（默认）——LLM 决定是否使用工具。 -2. `'required'`——LLM 必须调用某个工具（可自行选择）。 -3. `'none'`——LLM 必须**不**调用工具。 -4. 指定工具名，例如 `'calculator'`——LLM 必须调用该特定工具。 +1. `'auto'`（默认）——由 LLM 决定是否使用工具。 +2. `'required'` —— LLM **必须**调用某个工具（可自行选择）。 +3. `'none'` —— LLM **不得**调用工具。 +4. 指定工具名，如 `'calculator'` —— LLM 必须调用该特定工具。 - + ### 防止无限循环 -在工具调用后，SDK 会自动将 `tool_choice` 重置为 `'auto'`。这样可防止模型进入反复尝试调用工具的无限循环。你可以通过 `resetToolChoice` 标志或配置 `toolUseBehavior` 来覆盖此行为： +在工具调用后，SDK 会自动将 `tool_choice` 重置为 `'auto'`。这可防止模型进入反复尝试调用工具的无限循环。你可以通过 `resetToolChoice` 标志或配置 `toolUseBehavior` 来覆盖该行为： -- `'run_llm_again'`（默认）——用工具结果再次运行 LLM。 -- `'stop_on_first_tool'`——将首次工具结果视为最终答案。 -- `{ stopAtToolNames: ['my_tool'] }`——当调用任一列出的工具时停止。 -- `(context, toolResults) => ...`——返回是否应结束运行的自定义函数。 +- `'run_llm_again'`（默认）——使用工具结果再次运行 LLM。 +- `'stop_on_first_tool'` —— 将第一个工具结果作为最终答案。 +- `{ stopAtToolNames: ['my_tool'] }` —— 当任一列出的工具被调用时停止。 +- `(context, toolResults) => ...` —— 返回是否应结束运行的自定义函数。 ```typescript const agent = new Agent({ @@ -161,7 +161,7 @@ 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)。 diff --git a/docs/src/content/docs/zh/guides/config.mdx b/docs/src/content/docs/zh/guides/config.mdx index bfece6e4..4520917e 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,7 +49,7 @@ import getLoggerExample from '../../../../../../examples/docs/config/getLogger.t -如需了解更多关于追踪功能的信息，请查看[追踪](/openai-agents-js/guides/tracing)。 +如果想进一步了解追踪功能，请查看[追踪](/openai-agents-js/zh/guides/tracing)。 ## 调试日志 @@ -59,21 +59,21 @@ SDK 使用 [`debug`](https://www.npmjs.com/package/debug) 包进行调试日志 export DEBUG=openai-agents* ``` -您可以通过 `@openai/agents` 中的 `getLogger(namespace)` 为自己的模块获取一个带命名空间的日志记录器。 +您可以使用来自 `@openai/agents` 的 `getLogger(namespace)` 为自己的模块获取带命名空间的记录器。 - + ### 日志中的敏感数据 -某些日志可能包含用户数据。可通过设置以下环境变量来禁用。 +某些日志可能包含用户数据。可通过设置以下环境变量禁用。 -禁用记录 LLM 输入和输出： +要禁用记录 LLM 的输入与输出： ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -禁用记录工具输入和输出： +要禁用记录工具的输入与输出： ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/src/content/docs/zh/guides/context.mdx b/docs/src/content/docs/zh/guides/context.mdx index 1dfcd3fa..1853585d 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”一词含义较多。通常有两大类你需要关注的上下文： -1. **本地上下文**：在运行期间你的代码可访问的内容，例如工具所需的依赖或数据、`onHandoff` 等回调，以及生命周期钩子。 -2. **智能体/LLM 上下文**：语言模型在生成响应时可见的内容。 +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 搜索工具，将响应基于来自文件、数据库或网页的相关数据。 diff --git a/docs/src/content/docs/zh/guides/guardrails.mdx b/docs/src/content/docs/zh/guides/guardrails.mdx index 5837cede..63d37213 100644 --- a/docs/src/content/docs/zh/guides/guardrails.mdx +++ b/docs/src/content/docs/zh/guides/guardrails.mdx @@ -7,50 +7,50 @@ import { Code } from '@astrojs/starlight/components'; import inputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-input.ts?raw'; import outputGuardrailExample from '../../../../../../examples/docs/guardrails/guardrails-output.ts?raw'; -护栏与您的智能体*并行*运行，允许您对用户输入或智能体输出执行检查和验证。例如，您可以在调用昂贵的模型之前，先运行一个轻量模型作为护栏。如果护栏检测到恶意用法，它可以触发错误并阻止高成本模型运行。 +护栏与您的智能体*并行*运行，允许您对用户输入或智能体输出进行检查和验证。比如，您可以在调用昂贵模型之前运行一个轻量模型作为护栏。如果护栏检测到恶意使用，它可以触发错误并阻止高成本模型运行。 -护栏分为两类： +护栏分为两种： -1. **输入护栏**在初始用户输入上运行。 -2. **输出护栏**在最终智能体输出上运行。 +1. **输入护栏** 运行在初始用户输入上。 +2. **输出护栏** 运行在最终智能体输出上。 ## 输入护栏 -输入护栏分三步运行： +输入护栏分三步执行： -1. 护栏接收传递给智能体的相同输入。 -2. 护栏函数执行并返回一个[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)，该结果被包装在[`InputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/inputguardrailresult)中。 -3. 如果`tripwireTriggered`为`true`，将抛出[`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/inputguardrailtripwiretriggered)错误。 +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) 错误。 > **注意** -> 输入护栏用于用户输入，因此仅当该智能体是工作流中的*第一个*智能体时才会运行。护栏在智能体本身上配置，因为不同智能体通常需要不同的护栏。 +> 输入护栏面向用户输入，因此仅当该智能体是工作流中的*第一个*智能体时才会运行。护栏在智能体本身上配置，因为不同智能体通常需要不同的护栏。 ## 输出护栏 -输出护栏分三步运行： +输出护栏分三步执行： -1. 护栏接收由智能体生成的输出。 -2. 护栏函数执行并返回一个[`GuardrailFunctionOutput`](/openai-agents-js/openai/agents/interfaces/guardrailfunctionoutput)，该结果被包装在[`OutputGuardrailResult`](/openai-agents-js/openai/agents/interfaces/outputguardrailresult)中。 -3. 如果`tripwireTriggered`为`true`，将抛出[`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents/classes/outputguardrailtripwiretriggered)错误。 +1. 护栏接收由智能体产生的输出。 +2. 护栏函数执行并返回一个被 [`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)。 +> 仅当该智能体是工作流中的*最后一个*智能体时才会运行输出护栏。关于实时语音交互，请参见[构建语音智能体](/openai-agents-js/zh/guides/voice-agents/build#guardrails)。 ## 绊线 -当护栏失败时，会通过绊线发出信号。一旦触发绊线，运行器将抛出相应错误并停止执行。 +当护栏失败时，会通过绊线发出信号。一旦绊线被触发，runner 会抛出相应错误并停止执行。 ## 护栏实现 -护栏本质上是一个返回`GuardrailFunctionOutput`的函数。下面是一个最小示例，通过在内部运行另一个智能体来检查用户是否在寻求数学作业帮助。 +护栏就是一个返回 `GuardrailFunctionOutput` 的函数。下面是一个最小示例：它通过在后台运行另一个智能体来检查用户是否在请求数学作业帮助。 -输出护栏以相同方式工作。 +输出护栏的工作方式相同。 -1. `guardrailAgent`在护栏函数内部使用。 +1. `guardrailAgent` 在护栏函数中使用。 2. 护栏函数接收智能体的输入或输出并返回结果。 -3. 可以在护栏结果中包含额外信息。 -4. `agent`定义应用护栏的实际工作流。 +3. 可在护栏结果中包含额外信息。 +4. `agent` 定义应用护栏的实际工作流。 diff --git a/docs/src/content/docs/zh/guides/handoffs.mdx b/docs/src/content/docs/zh/guides/handoffs.mdx index 6e973baf..1ca7ec82 100644 --- a/docs/src/content/docs/zh/guides/handoffs.mdx +++ b/docs/src/content/docs/zh/guides/handoffs.mdx @@ -10,46 +10,54 @@ import handoffInputExample from '../../../../../../examples/docs/handoffs/handof import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw'; import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw'; -交接让一个智能体可以将对话的一部分委派给另一个智能体。这在不同智能体专攻特定领域时很有用。比如在客户支持应用中，您可能有分别处理预订、退款或常见问题的智能体。 +交接让一个智能体将对话的一部分委托给另一个智能体。这在不同智能体专攻不同领域时很有用。比如在客服应用中，你可能有处理预订、退款或常见问题的智能体。 -交接在 LLM 中被表示为工具。如果您将会话交接给名为 `Refund Agent` 的智能体，其工具名将是 `transfer_to_refund_agent`。 +在 LLM 看来，交接被表示为工具。如果你将对话交接给名为 `Refund Agent` 的智能体，则工具名会是 `transfer_to_refund_agent`。 ## 创建交接 -每个智能体都接受一个 `handoffs` 选项。它可以包含其他 `Agent` 实例，或由 `handoff()` 辅助函数返回的 `Handoff` 对象。 +每个智能体都接受一个 `handoffs` 选项。它可以包含其他 `Agent` 实例，或由 `handoff()` 帮助函数返回的 `Handoff` 对象。 ### 基本用法 - + ### 通过 `handoff()` 自定义交接 -`handoff()` 函数允许您微调生成的工具。 +`handoff()` 函数允许你微调生成的工具。 - `agent` – 要交接到的智能体。 - `toolNameOverride` – 覆盖默认的 `transfer_to_` 工具名。 -- `toolDescriptionOverride` – 覆盖默认的工具描述。 -- `onHandoff` – 发生交接时的回调。接收一个 `RunContext` 和可选的解析输入。 -- `inputType` – 交接期望的输入架构。 -- `inputFilter` – 传递给下一个智能体的历史过滤器。 +- `toolDescriptionOverride` – 覆盖默认工具描述。 +- `onHandoff` – 发生交接时的回调。接收一个 `RunContext` 和可选的已解析输入。 +- `inputType` – 交接所期望的输入模式。 +- `inputFilter` – 过滤传递给下一个智能体的历史记录。 - + ## 交接输入 -有时您希望 LLM 在调用交接时提供数据。定义一个输入架构并在 `handoff()` 中使用它。 +有时你希望 LLM 在调用交接时提供数据。定义一个输入模式并在 `handoff()` 中使用它。 - + ## 输入过滤器 -默认情况下，交接会接收整个对话历史。若要修改传递给下一个智能体的内容，请提供一个 `inputFilter`。 -常用的辅助工具位于 `@openai/agents-core/extensions`。 +默认情况下，交接会接收整个对话历史。要修改传递给下一个智能体的内容，请提供一个 `inputFilter`。 +常用的辅助函数位于 `@openai/agents-core/extensions`。 - + -## 推荐提示 +## 推荐提示词 -当您的提示中提到交接时，LLM 的响应更可靠。SDK 通过 `RECOMMENDED_PROMPT_PREFIX` 提供了推荐前缀。 +当提示词提到交接时，LLM 的响应更可靠。SDK 通过 `RECOMMENDED_PROMPT_PREFIX` 提供一个推荐前缀。 - + diff --git a/docs/src/content/docs/zh/guides/human-in-the-loop.mdx b/docs/src/content/docs/zh/guides/human-in-the-loop.mdx index 1f119b30..0a89d633 100644 --- a/docs/src/content/docs/zh/guides/human-in-the-loop.mdx +++ b/docs/src/content/docs/zh/guides/human-in-the-loop.mdx @@ -7,13 +7,13 @@ import { Aside, Code } from '@astrojs/starlight/components'; import humanInTheLoopExample from '../../../../../../examples/docs/human-in-the-loop/index.ts?raw'; import toolApprovalDefinition from '../../../../../../examples/docs/human-in-the-loop/toolApprovalDefinition.ts?raw'; -本指南演示如何使用 SDK 内置的人工干预支持，根据人为干预来暂停和恢复智能体运行。 +本指南演示如何使用 SDK 内置的人工干预支持，根据人工介入来暂停和恢复智能体运行。 -当前的主要用例是对敏感的工具执行请求批准。 +目前的主要用例是在执行敏感工具调用前请求批准。 ## 审批请求 -你可以通过将 `needsApproval` 选项设置为 `true`，或设置为返回布尔值的异步函数，来定义需要审批的工具。 +可以通过将 `needsApproval` 选项设置为 `true`，或设置为一个返回布尔值的异步函数，来定义需要审批的工具。 -请参见[完整示例脚本](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts)以获取可运行的端到端版本。 +参见[完整示例脚本](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts)以获取可运行的端到端版本。 ## 处理较长审批时间 -人工干预流程被设计为可在较长时间内中断，而无需让你的服务器持续运行。如果你需要关闭请求并稍后继续，你可以序列化状态，之后再恢复。 +人工干预流程被设计为可中断较长时间，而无需保持你的服务器运行。如果你需要先终止请求并稍后继续，可以序列化状态，之后再恢复。 -你可以使用 `JSON.stringify(result.state)` 序列化状态，并在之后将序列化的状态传入 `RunState.fromString(agent, serializedState)` 以恢复，其中 `agent` 是触发整个运行的智能体实例。 +可以使用 `JSON.stringify(result.state)` 序列化状态，并在稍后通过将序列化后的状态传入 `RunState.fromString(agent, serializedState)` 来恢复，其中 `agent` 是触发整个运行的智能体实例。 -这样你就可以将序列化后的状态存储在数据库中，或与请求一同存储。 +这样，你就可以将序列化状态存储到数据库中，或与请求一起存储。 -### 待处理任务的版本管理 +### 挂起任务的版本管理 -如果你的审批请求需要更长时间，并且你希望以有意义的方式为智能体定义做版本化，或升级你的 Agents SDK 版本，我们目前建议你通过使用包别名并行安装两个版本的 Agents SDK，来实现你自己的分支逻辑。 +如果你的审批请求需要较长时间，并且你打算以有意义的方式对智能体定义进行版本化或升级你的 Agents SDK 版本，目前我们建议你通过使用包别名并行安装两个版本的 Agents SDK，来实现你自己的分支逻辑。 -在实践中，这意味着为你的代码分配一个版本号，并与序列化状态一起存储，并在反序列化时引导到正确版本的代码。 +实际做法是给你的代码分配一个版本号，将其与序列化状态一同存储，并在反序列化时引导到你代码的正确版本。 diff --git a/docs/src/content/docs/zh/guides/mcp.mdx b/docs/src/content/docs/zh/guides/mcp.mdx index 9a85038c..a1e38b10 100644 --- a/docs/src/content/docs/zh/guides/mcp.mdx +++ b/docs/src/content/docs/zh/guides/mcp.mdx @@ -13,104 +13,111 @@ import streamableHttpExample from '../../../../../../examples/docs/mcp/streamabl import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; -The [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) is an open protocol that standardizes how applications provide tools and context to LLMs. From the MCP docs: +[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) 是一种开放协议，用于标准化应用如何向 LLMs 提供工具和上下文。来自 MCP 文档： -> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. +> MCP 是一种开放协议，用于标准化应用如何向 LLMs 提供上下文。可以把 MCP 想象成面向 AI 应用的 USB‑C 接口。就像 USB‑C 为设备连接各种外设和配件提供了标准化方式一样，MCP 为 AI 模型连接不同数据源和工具提供了标准化方式。 本 SDK 支持三种 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** – 通过标准输入/输出访问的服务器（最简单的选项） +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 服务器** – 通过标准输入/输出访问的服务器（最简单的选项） -请根据你的用例选择服务器类型： +请根据您的用例选择服务器类型： -| 你的需求 | 推荐选项 | -| ----------------------------------------------------------- | ----------------------- | -| 使用默认的 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. 托管 MCP 工具** | +| 使用可公开访问的远程服务器，但在本地触发工具调用 | **2. Streamable HTTP** | +| 使用本地运行的 Streamable HTTP 服务器 | **2. Streamable HTTP** | +| 使用非 OpenAI‑Responses 模型调用任意 Streamable HTTP 服务器 | **2. Streamable HTTP** | +| 使用仅支持标准 I/O 协议的本地 MCP 服务器 | **3. Stdio** | -## 1. Hosted MCP server tools +## 1. 托管 MCP 服务器工具 -托管工具将整个往返流程推送到模型中。不是你的代码调用 MCP 服务器，而是由 OpenAI Responses API 调用远程工具端点并将结果流式返回给模型。 +托管工具将整个往返流程置于模型内部。不是由您的代码调用 MCP 服务器，而是由 OpenAI Responses API 调用远程工具端点，并将结果流式传回模型。 -下面是使用托管 MCP 工具的最简单示例。你可以将远程 MCP 服务器的标签和 URL 传给 `hostedMcpTool` 实用函数，以便创建托管 MCP 服务器工具。 +以下是使用托管 MCP 工具的最简单示例。您可以将远程 MCP 服务器的标签和 URL 传递给 `hostedMcpTool` 实用函数，便于创建托管 MCP 服务器工具。 -然后，你可以使用 `run` 函数（或你自定义的 `Runner` 实例的 `run` 方法）运行智能体： +然后，您可以使用 `run` 函数（或您自定义的 `Runner` 实例的 `run` 方法）运行该 Agent： - + 若要流式传输增量 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)来批准或拒绝工具调用。若需要人工审批，你可以使用与本地函数工具相同的[人机协作（HITL）方法](/openai-agents-js/zh/guides/human-in-the-loop/)，通过 interruptions 实现。 +如果您可以以编程方式确定某个工具调用是否安全，可以使用 [`onApproval` 回调](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts)批准或拒绝该工具调用。如果需要人工审批，您可以像本地函数工具一样，使用相同的基于 `interruptions` 的[人机协作](/openai-agents-js/zh/guides/human-in-the-loop/)方法。 -### 由连接器支持的托管服务器 +### 由 Connector 支持的托管服务器 -Hosted MCP 也支持 OpenAI connectors。无需提供 `serverUrl`，改为传入连接器的 `connectorId` 和 `authorization` 令牌。Responses API 将处理认证，并通过托管 MCP 接口暴露该连接器的工具。 +托管 MCP 也支持 OpenAI connectors。无需提供 `serverUrl`，改为传入 connector 的 `connectorId` 和 `authorization` 令牌。随后 Responses API 会处理身份验证，并通过托管 MCP 接口暴露该 connector 的工具。 -在该示例中，环境变量 `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 令牌，它授权由 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 servers +## 2. Streamable HTTP MCP 服务器 -当你的智能体直接与 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 servers +## 3. Stdio MCP 服务器 -对于仅通过标准 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 06bf8f1a..ca6ce8e3 100644 --- a/docs/src/content/docs/zh/guides/models.mdx +++ b/docs/src/content/docs/zh/guides/models.mdx @@ -13,9 +13,9 @@ 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 通过两个轻量级接口抽象模型： +每个 Agent 最终都会调用一个 LLM。SDK 通过两个轻量接口抽象了模型： -- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 知道如何对特定 API 发起一次请求。 +- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 知道如何针对特定 API 发起*一次*请求。 - [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 将人类可读的模型**名称**（例如 `'gpt‑4o'`）解析为 `Model` 实例。 在日常使用中，你通常只与模型**名称**交互，偶尔会用到 `ModelSettings`。 @@ -28,18 +28,18 @@ import setTracingExportApiKeyExample from '../../../../../../examples/docs/confi ## 默认模型 -当你在初始化 `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)，有两种方式配置你的智能体。 +如果你想切换到其他模型（如 [`gpt-5`](https://platform.openai.com/docs/models/gpt-5)），有两种方式可以为你的智能体进行配置。 -首先，如果你希望对所有未设置自定义模型的智能体统一使用某个特定模型，可在运行智能体前设置环境变量 `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"` 的推理强度，这也是本 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')` _(默认)_ | +| Responses | 全新以流式为先的生成式 API（工具调用、灵活输出） | `setOpenAIAPI('responses')` _(默认)_ | -### 认证 +### 身份验证 -`Runner` 级别的设置会覆盖任何冲突的智能体级别设置。 +`Runner` 级别的设置会覆盖任何冲突的每个智能体级别设置。 --- -## 提示词 +## Prompt -智能体可以通过 `prompt` 参数进行配置，指示应使用的、存储在服务器上的提示词配置，以控制智能体行为。目前，此选项仅在使用 OpenAI [Responses API](https://platform.openai.com/docs/api-reference/responses) 时受支持。 +可以通过 `prompt` 参数为智能体进行配置，指向一个存储在服务器上的 prompt 配置，用于控制智能体行为。目前，此选项仅在你使用 OpenAI 的 +[Responses API](https://platform.openai.com/docs/api-reference/responses) 时受支持。 -| 字段 | 类型 | 备注 | -| ----------- | -------- | --------------------------------------------------------------------------------- | -| `promptId` | `string` | 提示词的唯一标识符。 | -| `version` | `string` | 你希望使用的提示词版本。 | -| `variables` | `object` | 要替换到提示词中的键/值变量对。值可以是字符串，或文本、图像、文件等内容输入类型。 | +| 字段 | 类型 | 说明 | +| ----------- | -------- | ------------------------------------------------------------------------------------- | +| `promptId` | `string` | prompt 的唯一标识符。 | +| `version` | `string` | 你希望使用的 prompt 版本。 | +| `variables` | `object` | 传入到 prompt 中的键/值变量对。值可以是字符串，或诸如文本、图像、文件等内容输入类型。 | - + -任何额外的智能体配置（如 tools 或 instructions）都会覆盖你在存储提示词中配置的值。 +任何额外的智能体配置（如 tools 或 instructions）都会覆盖你在存储的 prompt 中配置的值。 --- ## 自定义模型提供方 -实现你自己的提供方很简单——实现 `ModelProvider` 和 `Model`，并将该提供方传递给 `Runner` 构造函数： +实现你自己的提供方非常简单——实现 `ModelProvider` 和 `Model`，然后将该提供方传给 `Runner` 构造函数： --- ## 追踪导出器 -使用 OpenAI 提供方时，你可以通过提供 API 密钥来选择启用自动追踪导出： +当使用 OpenAI 提供方时，你可以通过提供 API 密钥选择加入自动追踪导出： -1. 创建项目并初始化 npm。此操作只需进行一次。 +1. 创建项目并初始化 npm。只需执行一次。 ```bash mkdir my_project @@ -25,20 +25,20 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index. npm install @openai/agents zod@3 ``` -3. 设置 OpenAI API key。如果还没有，请按照[这些说明](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)创建一个 OpenAI API key。 +3. 设置 OpenAI API key。如果没有，请按照[这些说明](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)创建一个 OpenAI API key。 ```bash export OPENAI_API_KEY=sk-... ``` - 或者，您可以调用 `setDefaultOpenAIKey('')` 以编程方式设置密钥，并使用 `setTracingExportApiKey('')` 用于追踪。 - 详见[SDK 配置](/openai-agents-js/zh/guides/config)。 + 或者，您可以调用 `setDefaultOpenAIKey('')` 以编程方式设置密钥，并使用 `setTracingExportApiKey('')` 进行追踪导出。 + 查看[SDK 配置](/openai-agents-js/zh/guides/config)以了解更多详情。 -## 第一个智能体创建 +## 创建第一个智能体 -智能体通过 instructions 和名称进行定义。 +智能体由 instructions 和名称定义。 ```typescript import { Agent } from '@openai/agents'; @@ -50,11 +50,11 @@ const agent = new Agent({ }); ``` -## 第一个智能体运行 +## 运行第一个智能体 -您可以使用 `run` 方法来运行智能体。通过同时传入要启动的智能体以及要传递的输入来触发一次运行。 +您可以使用 `run` 方法来运行智能体。通过传入要启动的智能体以及要传入的输入来触发一次运行。 -这将返回一个执行结果，其中包含该次运行期间的最终输出以及执行的任何操作。 +这将返回一个执行结果，其中包含最终输出以及在该次运行期间执行的所有操作。 ```typescript import { Agent, run } from '@openai/agents'; @@ -72,7 +72,7 @@ console.log(result.finalOutput); ## 为智能体提供工具 -您可以为智能体提供工具，以查找信息或执行操作。 +您可以为智能体提供工具，用于查找信息或执行操作。 ```typescript import { Agent, tool } from '@openai/agents'; @@ -99,9 +99,9 @@ const agent = new Agent({ }); ``` -## 更多智能体添加 +## 添加更多智能体 -可以以类似方式定义更多智能体，将问题拆分为更小的部分，使智能体更专注于当前任务。这也允许您通过在智能体上定义模型，为不同问题使用不同的模型。 +可以以类似方式定义更多智能体，将问题拆解为更小的部分，使智能体更专注于当前任务。还可以通过在智能体上定义模型，为不同问题使用不同的模型。 ```typescript const historyTutorAgent = new Agent({ @@ -117,9 +117,9 @@ 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 Dashboard 的 Trace viewer](https://platform.openai.com/traces)。 +[OpenAI 仪表板中的 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 bdcebe14..368b3b5a 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`） -对于未标记为 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`： - Bug 修复 - 新功能 -- 私有接口的更改 +- 对私有接口的更改 - 对 beta 功能的更新 ## 子包版本管理 -主包 `@openai/agents` 由多个可独立使用的子包组成。目前这些包的版本是联动的，即任一包版本提升，其他包也会随之提升。随着我们迈向 `1.0.0`，这一策略可能会调整。 +主包 `@openai/agents` 由多个可独立使用的子包组成。目前这些包的版本是联动的，即某个包版本提升时，其他包也会随之提升。随着我们迈向 `1.0.0`，该策略可能会调整。 ## 更新日志 -我们为每个子包生成更新日志，帮助你了解改动内容。由于变更可能发生在某个子包中，你可能需要查看对应子包的更新日志以了解详情。 +我们为每个子包生成更新日志，便于了解具体变更。由于变更可能发生在某个子包中，您可能需要查看对应的更新日志以获取详情。 - [`@openai/agents`](https://github.com/openai/openai-agents-js/blob/main/packages/agents/CHANGELOG.md) - [`@openai/agents-core`](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/CHANGELOG.md) diff --git a/docs/src/content/docs/zh/guides/results.mdx b/docs/src/content/docs/zh/guides/results.mdx index 5ebb8716..6227762e 100644 --- a/docs/src/content/docs/zh/guides/results.mdx +++ b/docs/src/content/docs/zh/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/zh/guides/running-agents)时，您将会收到以下两种之一： +当你[运行你的智能体](/openai-agents-js/zh/guides/running-agents)时，你将会收到以下之一： -- [`RunResult`](/openai-agents-js/openai/agents/classes/runresult)：当调用 `run` 且未设置 `stream: true` 时 -- [`StreamedRunResult`](/openai-agents-js/openai/agents/classes/streamedrunresult)：当调用 `run` 且设置了 `stream: true` 时。关于流式传输的细节，请参阅[流式传输](/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 schema 定义为输出类型。在这种情况下，JSON 已解析，但你仍需手动验证其类型。 +- `z.infer` — 如果智能体将 Zod schema 定义为输出类型。输出会自动按该 schema 进行解析。 +- `undefined` — 如果智能体未产生输出（例如在产生输出前就停止） -如果您使用了不同输出类型的交接，建议使用 `Agent.create()` 方法而非 `new Agent()` 构造函数来创建智能体。 +如果你在使用具有不同输出类型的交接，应该使用 `Agent.create()` 方法而不是 `new Agent()` 构造函数来创建智能体。 -这将使 SDK 能够在所有可能的交接路径上推断输出类型，并为 `finalOutput` 属性提供联合类型。 +这将使 SDK 能够在所有可能的交接中推断输出类型，并为 `finalOutput` 属性提供联合类型。 例如： @@ -35,55 +35,55 @@ import historyLoop from '../../../../../../examples/docs/results/historyLoop.ts? ## 下一轮的输入 -有两种方式可以获取下一轮所需的输入： +你可以通过两种方式获取下一轮的输入： -- `result.history` —— 包含您的输入和智能体输出的副本。 -- `result.output` —— 包含整个智能体运行的输出。 +- `result.history` — 包含你的输入以及智能体输出的副本。 +- `result.output` — 包含整个智能体运行的输出。 -在类聊天的用例中，使用 `history` 维护完整历史非常方便： +在类似聊天的用例中，`history` 是维护完整历史的便捷方式： ## 最后一个智能体 -`lastAgent` 属性包含最后一个运行的智能体。根据您的应用场景，这对于下次用户输入时通常很有用。比如，如果您有一个前线分诊智能体会交接到特定语言的智能体，您可以存储该最后智能体，并在用户下次发送消息时复用它。 +`lastAgent` 属性包含最后一个运行的智能体。根据你的应用，这通常对用户下次输入时很有用。例如，如果你有一个前线分诊智能体会交接到特定语言的智能体，你可以存储该最后智能体，并在用户下次向智能体发送消息时复用它。 -在流式传输模式下，访问 `currentAgent` 属性也很有用，它对应当前正在运行的智能体。 +在流式模式下，访问映射到当前正在运行的智能体的 `currentAgent` 属性也很有用。 -## 新增项 +## 新条目 -`newItems` 属性包含在此次运行中生成的新项。其项为 [`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem)。运行项封装了由 LLM 生成的原始项。除了用于获取 LLM 的输出之外，还可用来判断这些事件与哪个智能体关联。 +`newItems` 属性包含在此次运行期间生成的新条目。条目是[`RunItem`](/openai-agents-js/openai/agents/type-aliases/runitem)。运行条目包装了 LLM 生成的原始条目。除了访问 LLM 的输出外，还可以用它来确定这些事件关联的是哪个智能体。 -- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) 表示来自 LLM 的消息。原始项为生成的消息。 -- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) 表示 LLM 调用了交接工具。原始项为来自 LLM 的工具调用项。 -- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) 表示已发生交接。原始项为对交接工具调用的工具响应。您也可以从该项访问源/目标智能体。 +- [`RunMessageOutputItem`](/openai-agents-js/openai/agents/classes/runmessageoutputitem) 表示来自 LLM 的消息。原始条目是生成的消息。 +- [`RunHandoffCallItem`](/openai-agents-js/openai/agents/classes/runhandoffcallitem) 表示 LLM 调用了交接工具。原始条目是来自 LLM 的工具调用条目。 +- [`RunHandoffOutputItem`](/openai-agents-js/openai/agents/classes/runhandoffoutputitem) 表示发生了交接。原始条目是对交接工具调用的工具响应。你还可以从条目中访问源/目标智能体。 - [`RunToolCallItem`](/openai-agents-js/openai/agents/classes/runtoolcallitem) 表示 LLM 调用了某个工具。 -- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) 表示某个工具被调用。原始项为工具响应。您也可以从该项访问工具输出。 -- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) 表示来自 LLM 的推理项。原始项为生成的推理。 -- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) 表示 LLM 请求对某个工具调用进行审批。原始项为来自 LLM 的工具调用项。 +- [`RunToolCallOutputItem`](/openai-agents-js/openai/agents/classes/runtoolcalloutputitem) 表示某个工具被调用。原始条目是工具响应。你还可以从条目中访问工具输出。 +- [`RunReasoningItem`](/openai-agents-js/openai/agents/classes/runreasoningitem) 表示来自 LLM 的推理条目。原始条目是生成的推理内容。 +- [`RunToolApprovalItem`](/openai-agents-js/openai/agents/classes/runtoolapprovalitem) 表示 LLM 请求对工具调用进行批准。原始条目是来自 LLM 的工具调用条目。 ## 状态 -`state` 属性包含此次运行的状态。附加在 `result` 上的大部分信息都源自 `state`，但 `state` 是可序列化/反序列化的，并且在需要[从错误中恢复](/openai-agents-js/zh/guides/running-agents#exceptions)或处理 [`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 a763f688..520ff988 100644 --- a/docs/src/content/docs/zh/guides/running-agents.mdx +++ b/docs/src/content/docs/zh/guides/running-agents.mdx @@ -11,100 +11,100 @@ 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 会执行如下循环： 1. 使用当前输入调用当前智能体的模型。 -2. 检查 LLM 的响应。 +2. 检查 LLM 响应。 - **最终输出** → 返回。 - - **交接** → 切换到新的智能体，保留累积的对话历史，返回步骤 1。 - - **工具调用** → 执行工具，将其结果追加到对话中，返回步骤 1。 + - **交接** → 切换到新智能体，保留累积的对话历史，回到步骤 1。 + - **工具调用** → 执行工具，将其结果追加到对话中，回到步骤 1。 3. 一旦达到 `maxTurns`，抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 ### Runner 生命周期 -在应用启动时创建一个 `Runner` 并在多个请求之间复用。该实例存储全局配置，例如模型提供方和追踪选项。只有在需要完全不同的设置时才创建新的 `Runner`。对于简单脚本，你也可以直接调用 `run()`，它会在内部使用默认 runner。 +在应用启动时创建一个 `Runner` 并在请求间复用。该实例存储全局配置，如模型提供方和追踪选项。只有在需要完全不同的设置时才创建另一个 `Runner`。对于简单脚本，您也可以直接调用 `run()`，它会在内部使用默认 runner。 ## 运行参数 -传入 `run()` 方法的参数包括用于启动运行的初始智能体、运行输入以及一组选项。 +`run()` 方法的输入包括用于启动运行的初始智能体、运行的输入以及一组选项。 -输入可以是字符串（被视为用户消息）、[输入项](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem)列表，或者在构建[人机协作](/openai-agents-js/zh/guides/human-in-the-loop)智能体时使用的 [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) 对象。 +输入可以是字符串（被视为用户消息）、[输入项](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem)列表，或在构建[人机协作](/openai-agents-js/zh/guides/human-in-the-loop)智能体时使用的 [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) 对象。 -其他可选项包括： +其他选项包括： -| Option | Default | Description | +| 选项 | 默认值 | 说明 | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------- | -| `stream` | `false` | 若为 `true`，调用将返回 `StreamedRunResult`，并在模型产生事件时实时推送。 | -| `context` | – | 传递给每个 tool / guardrail / handoff 的上下文对象。详情见[上下文管理](/openai-agents-js/zh/guides/context)。 | -| `maxTurns` | `10` | 安全上限——达到时抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 | +| `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。 - -| Field | Type | Purpose | -| --------------------------- | --------------------- | ------------------------------------------------------ | -| `model` | `string \| Model` | 为运行中的**所有**智能体强制指定特定模型。 | -| `modelProvider` | `ModelProvider` | 解析模型名称——默认为 OpenAI 提供方。 | -| `modelSettings` | `ModelSettings` | 全局调优参数，优先于每个智能体的单独设置。 | -| `handoffInputFilter` | `HandoffInputFilter` | 进行交接时变更输入项（如果交接本身未定义过滤器）。 | -| `inputGuardrails` | `InputGuardrail[]` | 应用于“初始”用户输入的护栏。 | -| `outputGuardrails` | `OutputGuardrail[]` | 应用于“最终”输出的护栏。 | -| `tracingDisabled` | `boolean` | 完全禁用 OpenAI 追踪。 | -| `traceIncludeSensitiveData` | `boolean` | 从追踪中排除 LLM/工具的输入与输出，同时仍然发出 span。 | -| `workflowName` | `string` | 显示在 Traces 控制台中——帮助对相关运行进行分组。 | -| `traceId` / `groupId` | `string` | 手动指定 trace 或 group ID，而不是由 SDK 自动生成。 | -| `traceMetadata` | `Record` | 附加到每个 span 的任意元数据。 | +如果您要创建自己的 `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.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 提供两种方式复用服务器端状态： +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 串联每次请求。在不创建完整会话资源的情况下跨轮次保持上下文。 -运行上述示例时，你将看到如下输出： +运行上述示例时，您将看到如下输出： ``` Guardrail execution failed: Error: Input guardrail failed to complete: Error: Something is wrong! @@ -145,5 +145,5 @@ Math homework guardrail tripped ## 后续步骤 - 了解如何[配置模型](/openai-agents-js/zh/guides/models)。 -- 为你的智能体提供[工具](/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/sessions.mdx b/docs/src/content/docs/zh/guides/sessions.mdx index abd1de54..b12d60a4 100644 --- a/docs/src/content/docs/zh/guides/sessions.mdx +++ b/docs/src/content/docs/zh/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 提供了一个**持久化内存层**。向 `Runner.run` 提供任意实现了 `Session` 接口的对象，其余由 SDK 处理。当存在会话时，运行器将自动： +会话为 Agents SDK 提供了一个**持久化内存层**。将任何实现了 `Session` 接口的对象传给 `Runner.run`，其余工作由 SDK 处理。当会话存在时，runner 会自动： -1. 获取先前存储的对话项，并将其添加到下一轮对话的前面。 -2. 在每次运行完成后，持久化新的用户输入和助手输出。 -3. 保持该会话可用于未来的轮次，无论是用新的用户文本调用运行器，还是从中断的 `RunState` 恢复。 +1. 获取先前存储的对话项并在下一轮对话前置。 +2. 在每次运行完成后持久化新的用户输入和助手输出。 +3. 保持会话可用于后续轮次，无论是用新的用户文本调用 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/` 下的示例会话后端（Prisma、文件存储等）。 > 提示：要运行本页中的 `OpenAIConversationsSession` 示例，请设置 `OPENAI_API_KEY` 环境变量（或在构造会话时提供 `apiKey`），以便 SDK 能调用 Conversations API。 @@ -28,45 +28,45 @@ import sessionInputCallback from '../../../../../../examples/docs/sessions/sessi -复用同一个会话实例可确保智能体在每一轮前都收到完整对话历史，并自动持久化新项目。切换到不同的 `Session` 实现无需更改其他代码。 +复用同一个会话实例可确保智能体在每一轮前都能获得完整的对话历史，并自动持久化新条目。切换到不同的 `Session` 实现无需更改其他代码。 --- -## 运行器对会话的使用 +## runner 如何使用会话 -- **每次运行之前**，它会检索会话历史，与新一轮输入合并，并将合并后的列表传递给您的智能体。 -- **对于非流式运行**，通过一次 `session.addItems()` 调用即可同时持久化原始用户输入和最新一轮的模型输出。 -- **对于流式传输运行**，它会先写入用户输入，并在该轮完成后追加流式输出。 -- **从 `RunResult.state` 恢复时**（如审批或其他中断），请继续传入同一个 `session`。恢复的这一轮将被加入内存，而无需重新准备输入。 +- 在每次运行之前，它会检索会话历史，将其与新一轮的输入合并，并将合并后的列表传给您的智能体。 +- 对于非流式运行，一次 `session.addItems()` 调用即可持久化最新一轮中的原始用户输入和模型输出。 +- 对于流式运行，它会先写入用户输入，并在该轮完成后追加流式输出。 +- 当从 `RunResult.state` 恢复（用于审批或其他中断）时，请继续传入相同的 `session`。恢复的该轮会被添加到内存中，而无需重新准备输入。 --- -## 历史记录的查看与编辑 +## 历史的查看与编辑 -会话提供简单的 CRUD 辅助方法，便于构建“撤销”“清空聊天”或审计等功能。 +会话提供简洁的 CRUD 助手，便于构建“撤销”“清空对话”或审计等功能。 - + -`session.getItems()` 返回已存储的 `AgentInputItem[]`。调用 `popItem()` 可移除最后一项——在您重新运行智能体前，这对用户更正很有用。 +`session.getItems()` 会返回已存储的 `AgentInputItem[]`。调用 `popItem()` 可移除最后一条记录——在您重新运行智能体前用于用户更正非常有用。 --- -## 自定义存储 +## 自带存储 -实现 `Session` 接口，以使用 Redis、DynamoDB、SQLite 或其他数据存储为内存提供支持。只需实现五个异步方法。 +实现 `Session` 接口即可使用 Redis、DynamoDB、SQLite 或其他数据存储来支撑内存。只需实现五个异步方法。 - + -自定义会话可让您实施保留策略、添加加密，或在持久化前为每轮对话附加元数据。 +自定义会话可用于实施保留策略、添加加密，或在持久化前为每次对话轮次附加元数据。 --- ## 控制历史与新条目的合并方式 -当您以 `AgentInputItem` 数组作为运行输入时，可提供 `sessionInputCallback`，以确定性地将它们与存储的历史合并。运行器会加载现有历史，在**模型调用之前**调用您的回调，并将回调返回的数组作为该轮的完整输入交给模型。此钩子非常适合裁剪旧项目、去重工具结果，或仅突出您希望模型看到的上下文。 +当您将 `AgentInputItem` 数组作为运行输入时，可提供 `sessionInputCallback` 来以确定性方式与存储的历史合并。runner 会加载现有历史，在模型调用之前调用该回调，并将返回的数组作为该轮的完整输入交给模型。此钩子非常适合裁剪旧条目、去重工具结果，或仅突出您希望模型看到的上下文。 -对于字符串输入，运行器会自动合并历史，因此该回调为可选。 +对于字符串输入，runner 会自动合并历史，因此该回调是可选的。 --- -## 审批与可恢复运行 +## 审批与可恢复运行的处理 -人工干预（Human in the loop）流程常会暂停一次运行以等待审批： +人工干预流程常会暂停一次运行以等待审批： ```typescript const result = await runner.run(agent, 'Search the itinerary', { @@ -95,4 +95,4 @@ if (result.requiresApproval) { } ``` -当您从先前的 `RunState` 恢复时，新一轮会被追加到相同的内存记录中，以保留单一的对话历史。人工干预（HITL）流程保持完全兼容——审批检查点仍通过 `RunState` 往返，而会话则保持完整的对话记录。 +当您从之前的 `RunState` 恢复时，新的一轮会被追加到相同的内存记录中，以保留单一的对话历史。人工干预（HITL）流程仍完全兼容——审批检查点会继续通过 `RunState` 往返，而会话则保持完整的对话记录。 diff --git a/docs/src/content/docs/zh/guides/streaming.mdx b/docs/src/content/docs/zh/guides/streaming.mdx index fb4a116a..f5096e19 100644 --- a/docs/src/content/docs/zh/guides/streaming.mdx +++ b/docs/src/content/docs/zh/guides/streaming.mdx @@ -9,36 +9,36 @@ 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` 这个 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)，其中提供了完整脚本，同时打印纯文本流和原始事件流。 +参见[流式传输示例](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 }` 执行将恢复流式输出。 一个与用户交互的更完整示例见 @@ -125,8 +125,8 @@ type RunAgentUpdatedStreamEvent = { ## 提示 -- 退出前记得等待 `stream.completed`，以确保所有输出已刷新。 -- 初始的 `{ stream: true }` 选项只对提供它的那次调用生效。如果你用 `RunState` 重新执行，必须再次指定该选项。 -- 如果你的应用只关心文本结果，优先使用 `toTextStream()`，以避免处理单独的事件对象。 +- 退出前请记得等待 `stream.completed`，以确保所有输出都已刷新。 +- 初始的 `{ stream: true }` 选项只适用于提供它的那次调用。若你使用 `RunState` 重新运行，必须再次指定该选项。 +- 若你的应用只关心文本结果，优先使用 `toTextStream()`，以免处理单个事件对象。 -借助流式传输和事件系统，你可以将智能体集成到聊天界面、终端应用，或任何用户能从增量更新中受益的场景。 +通过流式传输和事件系统，你可以将智能体集成到聊天界面、终端应用，或任何用户受益于增量更新的场景中。 diff --git a/docs/src/content/docs/zh/guides/tools.mdx b/docs/src/content/docs/zh/guides/tools.mdx index caacceaa..eaab088c 100644 --- a/docs/src/content/docs/zh/guides/tools.mdx +++ b/docs/src/content/docs/zh/guides/tools.mdx @@ -10,10 +10,10 @@ import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStric import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw'; import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer.ts?raw'; -工具让智能体能够**执行操作**——获取数据、调用外部 API、执行代码，甚至进行计算机操作。JavaScript/TypeScript SDK 支持四种类别： +工具让智能体能够**执行操作**——获取数据、调用外部 API、执行代码，甚至使用计算机。JavaScript/TypeScript SDK 支持四种类别： -1. **托管工具**——与模型在 OpenAI 服务器上并行运行。（Web 搜索、文件搜索、计算机操作、code interpreter、图像生成） -2. **函数工具**——用 JSON 模式包装任意本地函数，使 LLM 可以调用。 +1. **托管工具**——与模型一起在 OpenAI 服务器上运行。（Web 搜索、文件搜索、计算机操作、Code Interpreter、图像生成） +2. **函数工具**——使用 JSON schema 包装任意本地函数，让 LLM 可调用。 3. **智能体作为工具**——将整个智能体暴露为可调用的工具。 4. **本地 MCP 服务器**——挂载在你机器上运行的 Model Context Protocol 服务器。 @@ -23,68 +23,68 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer 当你使用 `OpenAIResponsesModel` 时，可以添加以下内置工具： -| 工具 | 类型字符串 | 目的 | -| ---------------- | -------------------- | ---------------------------- | -| Web 搜索 | `'web_search'` | 互联网搜索。 | -| 文件/检索搜索 | `'file_search'` | 查询 OpenAI 托管的向量存储。 | -| 计算机操作 | `'computer'` | 自动化 GUI 交互。 | -| Shell | `'shell'` | 在主机上运行 Shell 命令。 | -| Apply patch | `'apply_patch'` | 对本地文件应用 V4A 补丁。 | -| Code Interpreter | `'code_interpreter'` | 在沙盒环境中运行代码。 | -| 图像生成 | `'image_generation'` | 基于文本生成图像。 | +| 工具 | 类型字符串 | 目的 | +| ----------------------- | -------------------- | -------------------------------- | +| 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'` | 基于文本生成图像。 | - + -具体参数集与 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`，用于将内部错误转换为对用户可见的字符串。 | +| 字段 | 必填 | 描述 | +| --------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | 否 | 默认为函数名（例如 `get_weather`）。 | +| `description` | 是 | 清晰、可读的描述，展示给 LLM。 | +| `parameters` | 是 | 可以是 Zod schema 或原始 JSON schema 对象。使用 Zod 参数会自动启用**严格**模式。 | +| `strict` | 否 | 当为 `true`（默认）时，如果参数验证失败，SDK 会返回模型错误。设置为 `false` 以进行模糊匹配。 | +| `execute` | 是 | `(args, context) => string \| Promise`——你的业务逻辑。可选的第二个参数为 `RunContext`。 | +| `errorFunction` | 否 | 自定义处理器 `(context, error) => string`，用于将内部错误转换为对用户可见的字符串。 | ### 非严格 JSON‑schema 工具 -如果你需要模型在输入无效或不完整时进行“猜测”，可在使用原始 JSON 模式时禁用严格模式： +如果你需要模型在输入无效或不完整时进行“猜测”，可在使用原始 JSON schema 时禁用严格模式： --- ## 3. 智能体作为工具 -有时你希望某个智能体去“协助”另一个智能体，而不是完全交接会话。使用 `agent.asTool()`： +有时你希望一个智能体在不完全交接对话的情况下*协助*另一个智能体。使用 `agent.asTool()`： - + -在底层，SDK 会： +在幕后，SDK 会： -- 创建一个只有单个 `input` 参数的函数工具。 -- 在工具被调用时，使用该输入运行子智能体。 +- 创建一个仅包含 `input` 参数的函数工具。 +- 当该工具被调用时，使用该输入运行子智能体。 - 返回最后一条消息，或由 `customOutputExtractor` 提取的输出。 -当你以工具的方式运行一个智能体时，Agents SDK 会使用默认设置创建一个 runner，并在函数执行期间用它来运行该智能体。如果你想提供任何 `runConfig` 或 `runOptions` 的属性，可以将它们传给 `asTool()` 方法以自定义 runner 的行为。 +当你以工具方式运行一个智能体时，Agents SDK 会使用默认设置创建一个运行器，并在函数执行内用它来运行该智能体。如果你想提供任何 `runConfig` 或 `runOptions` 的属性，可以将它们传给 `asTool()` 方法来自定义运行器行为。 --- @@ -93,29 +93,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 集成](/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 模式进行严格的 JSON 校验。 +- **简短且明确的描述**——描述工具做什么，以及*何时使用*它。 +- **验证输入**——尽可能使用 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/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 ec25e430..f915521c 100644 --- a/docs/src/content/docs/zh/guides/tracing.mdx +++ b/docs/src/content/docs/zh/guides/tracing.mdx @@ -7,22 +7,22 @@ import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw'; -Agents SDK 内置了追踪功能，会在智能体运行期间收集全面的事件记录：LLM 生成、工具调用、交接、护栏，甚至自定义事件。使用 [追踪仪表板](https://platform.openai.com/traces)，你可以在开发与生产环境中调试、可视化并监控工作流。 +Agents SDK 内置了追踪功能，会在智能体运行期间收集完整的事件记录：LLM 生成、工具调用、交接、护栏，以及发生的自定义事件。借助 [Traces dashboard](https://platform.openai.com/traces)，你可以在开发和生产环境中调试、可视化并监控你的工作流。 -## 导出循环生命周期 +## 导出循环的生命周期 -在大多数环境中，追踪会按固定间隔自动导出。在浏览器或 Cloudflare Workers 中，此功能默认禁用。若排队过多，追踪仍会被导出，但不会定期导出。此时应使用 `getGlobalTraceProvider().forceFlush()`，在代码生命周期中手动导出追踪。 +在大多数环境中，追踪会按固定时间间隔自动导出。在浏览器或 Cloudflare Workers 中，此功能默认关闭。追踪在积压过多时仍会导出，但不会定期导出。你应使用 `getGlobalTraceProvider().forceFlush()` 在代码生命周期中手动导出追踪。 例如，在 Cloudflare Worker 中，应将代码包裹在 `try/catch/finally` 中，并结合 `waitUntil` 使用强制刷新，确保在 worker 退出前导出追踪。 @@ -34,77 +34,77 @@ Agents SDK 内置了追踪功能，会在智能体运行期间收集全面的事 ## Trace 与 Span -- **Trace** 表示一次“工作流”的端到端操作，由多个 Span 组成。Trace 具有以下属性： - - `workflow_name`：逻辑上的工作流或应用。例如 “Code generation” 或 “Customer service”。 - - `trace_id`：Trace 的唯一 ID。如果未传入则自动生成。格式必须为 `trace_<32_alphanumeric>`。 - - `group_id`：可选的分组 ID，用于将同一会话中的多个 Trace 关联起来。例如可使用聊天线程 ID。 +- **Traces** 表示一次“工作流”的端到端操作。它由多个 Span 组成。Trace 具备以下属性： + - `workflow_name`：逻辑上的工作流或应用名。例如 “Code generation” 或 “Customer service”。 + - `trace_id`：Trace 的唯一 ID。如果不传会自动生成。格式必须为 `trace_<32_alphanumeric>`。 + - `group_id`：可选的分组 ID，用于将同一会话的多个 Trace 关联起来。例如，你可以使用聊天线程 ID。 - `disabled`：若为 True，则不会记录该 Trace。 - - `metadata`：可选的 Trace 元数据。 -- **Span** 表示具有开始与结束时间的操作。Span 具有： + - `metadata`：Trace 的可选元数据。 +- **Spans** 表示具有开始和结束时间的操作。Span 包含： - `started_at` 和 `ended_at` 时间戳。 - `trace_id`，表示其所属的 Trace - - `parent_id`，指向其父 Span（若有） - - `span_data`，关于该 Span 的信息。例如，`AgentSpanData` 包含智能体信息，`GenerationSpanData` 包含 LLM 生成信息，等等。 + - `parent_id`，指向该 Span 的父 Span（如果有） + - `span_data`，关于该 Span 的信息。例如，`AgentSpanData` 包含有关智能体的信息，`GenerationSpanData` 包含有关 LLM 生成的信息等。 ## 默认追踪 默认情况下，SDK 会追踪以下内容： -- 整个 `run()` 或 `Runner.run()` 被包裹在一个 `Trace` 中。 -- 每次智能体运行都会包裹在 `AgentSpan` 中 -- LLM 生成会包裹在 `GenerationSpan` 中 -- 每次函数工具调用会包裹在 `FunctionSpan` 中 -- 护栏会包裹在 `GuardrailSpan` 中 -- 交接会包裹在 `HandoffSpan` 中 +- 整个 `run()` 或 `Runner.run()` 会被一个 `Trace` 包裹。 +- 每次智能体运行都会被 `AgentSpan` 包裹 +- LLM 生成会被 `GenerationSpan` 包裹 +- 函数工具调用各自被 `FunctionSpan` 包裹 +- 护栏会被 `GuardrailSpan` 包裹 +- 交接会被 `HandoffSpan` 包裹 -默认的 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-tracing-processors)，将追踪推送到其他目的地（替代或作为次要目的地）。 +此外，你可以设置[custom trace processors](#custom-tracing-processors)，将追踪推送到其他目的地（作为替代或附加目的地）。 ### 语音智能体追踪 -如果你使用默认的 OpenAI Realtime API 搭配 `RealtimeAgent` 和 `RealtimeSession`，追踪会自动在 Realtime API 端进行，除非你在 `RealtimeSession` 上通过 `tracingDisabled: true` 或使用 `OPENAI_AGENTS_DISABLE_TRACING` 环境变量禁用它。 +如果你使用 `RealtimeAgent` 和 `RealtimeSession` 且采用默认的 OpenAI Realtime API，追踪会自动在 Realtime API 侧进行，除非你在 `RealtimeSession` 上使用 `tracingDisabled: true` 或设置环境变量 `OPENAI_AGENTS_DISABLE_TRACING` 来禁用它。 查看[语音智能体概述](/openai-agents-js/zh/guides/voice-agents)了解更多详情。 -## 更高层级的追踪 +## 更高层级的 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 之下；该状态通过 [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)，用于创建追踪，并可通过 [`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) 访问。 -- 我们为 `TraceProvider` 配置了一个 [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/)，它会将追踪/Span 批量发送到 [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/)，由其将 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) 允许你添加一个“额外的”追踪处理器，它将在追踪和 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 338d2a49..eda7c4dc 100644 --- a/docs/src/content/docs/zh/guides/troubleshooting.mdx +++ b/docs/src/content/docs/zh/guides/troubleshooting.mdx @@ -3,9 +3,9 @@ title: 故障排除 description: Learn how to troubleshoot issues with the OpenAI Agents SDK. --- -## 支持的环境 +## 支持的运行环境 -OpenAI Agents SDK 在以下服务器环境中受支持： +OpenAI Agents SDK 支持以下服务器环境： - Node.js 22+ - Deno 2.35+ @@ -13,29 +13,29 @@ OpenAI Agents SDK 在以下服务器环境中受支持： ### 限制性支持 -- **Cloudflare Workers**：Agents SDK 可用于 Cloudflare Workers，但目前存在一些限制： - - SDK 目前需要启用 `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 中使用，但目前存在一些限制： + - 当前需要启用 `nodejs_compat` + - 需要在请求结束时手动刷新追踪数据。有关详细信息，[参见追踪指南](/openai-agents-js/zh/guides/tracing#export-loop-lifecycle)。 + - 由于 Cloudflare Workers 对 `AsyncLocalStorage` 的支持有限，部分追踪可能不够准确 + - 出站 WebSocket 连接必须使用基于 fetch 的升级方式（而不是全局的 `WebSocket` 构造函数）。对于 Realtime，请在 `@openai/agents-extensions` 中使用 Cloudflare 传输（`CloudflareRealtimeTransportLayer`）。 - **浏览器**： - 目前在浏览器中不支持追踪 -- **v8 隔离环境（v8 isolates）**： - - 即使用具有合适浏览器 polyfill 的打包器将 SDK 打包用于 v8 隔离环境，追踪也无法工作 - - v8 隔离环境尚未经过广泛测试 +- **v8 isolates**： + - 如果使用带有合适浏览器 polyfill 的打包工具，理论上可以为 v8 isolates 打包 SDK，但追踪将无法工作 + - v8 isolates 尚未经过广泛测试 ## 调试日志 如果您在使用 SDK 时遇到问题，可以启用调试日志以获取更多运行信息。 -通过将 `DEBUG` 环境变量设置为 `openai-agents:*` 启用调试日志。 +通过将 `DEBUG` 环境变量设置为 `openai-agents:*` 来启用调试日志。 ```bash DEBUG=openai-agents:* ``` -或者，您可以将调试范围限定到 SDK 的特定部分： +或者，您也可以将调试范围限定到 SDK 的特定部分： - `openai-agents:core` — SDK 的主要执行逻辑 - `openai-agents:openai` — OpenAI API 调用 -- `openai-agents:realtime` — 实时智能体相关组件 +- `openai-agents:realtime` — Realtime Agents 组件 diff --git a/docs/src/content/docs/zh/guides/voice-agents.mdx b/docs/src/content/docs/zh/guides/voice-agents.mdx index 18e8c1fc..52433e43 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 eb51efc2..187e0eca 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` 对象的一部分传递。 ## 交接 -与常规智能体类似，你可以使用交接将你的智能体拆分为多个智能体，并在它们之间进行编排，以提升智能体性能并更好地限定问题范围。 +与常规智能体类似，你可以使用交接将你的智能体拆分为多个智能体，并在它们之间进行编排，以提升性能并更好地限定问题范围。 -与常规智能体不同，交接在实时智能体（Realtime Agents）中行为略有差异。当执行交接时，进行中的会话会更新为新的智能体配置。因此，智能体会自动访问正在进行的对话历史，并且当前不会应用输入过滤器。 +与常规智能体不同，交接在实时智能体中行为略有差异。执行交接时，进行中的会话会使用新的智能体配置进行更新。因此，智能体会自动访问正在进行的对话历史，并且当前不会应用输入过滤器。 -此外，这意味着在交接过程中无法更改 `voice` 或 `model`。你也只能连接到其他实时智能体。如果你需要使用不同的模型，例如推理模型 `gpt-5-mini`，你可以使用[通过工具进行委派](#delegation-through-tools)。 +此外，这意味着在交接过程中无法更改 `voice` 或 `model`。你也只能连接到其他实时智能体。如果你需要使用不同的模型，例如像 `gpt-5-mini` 这样的推理模型，你可以使用[通过工具进行委派](#delegation-through-tools)。 ## 工具 @@ -60,77 +60,77 @@ 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` 上的 `sendMessage` 方法。 -当你希望让用户以两种模态与智能体交互，或为对话提供额外上下文时，这会很有用。 +这在你希望让用户以两种模态与智能体交互，或为对话提供额外上下文时很有用。 @@ -138,26 +138,26 @@ Realtime Session 将自动检测用户何时在讲话，并使用 Realtime API `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) -通过将会话历史与工具调用结合，你可以将对话委派给另一个后端智能体以执行更复杂的操作，然后将结果传回给用户。 +将会话历史与工具调用结合，你可以将对话委派给另一个后端智能体以执行更复杂的操作，然后将结果返回给用户。 -下面的代码将会在服务器上执行。本示例通过 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 b7621724..edfb0160 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 key 来生成密钥。 + 由于该应用将在用户的浏览器中运行，我们需要一种安全的方式通过 Realtime API 连接到模型。为此可以使用应由后端服务器生成的[临时客户端密钥](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token)。在测试时，您也可以使用 `curl` 和常规的 OpenAI API 密钥来生成密钥。 ```bash export OPENAI_API_KEY="sk-proj-...(your own key here)" @@ -59,11 +59,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }' ``` - 响应会在顶层包含一个以 "ek\_" 为前缀的 "value" 字符串。你可以使用该临时密钥稍后建立 WebRTC 连接。注意此密钥仅在短时间内有效，需要定期重新生成。 + 响应在顶层会包含一个以 "ek\_" 为前缀的 "value" 字符串。您可以使用此临时密钥稍后建立 WebRTC 连接。请注意，该密钥只在短时间内有效，需要重新生成。 -3. **创建你的第一个智能体** +3. **创建您的第一个智能体** - 创建一个新的[`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/)与创建常规的[`Agent`](/openai-agents-js/zh/guides/agents)非常相似。 + 创建一个新的 [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) 与创建常规的 [`Agent`](/openai-agents-js/guides/agents) 非常相似。 ```typescript import { RealtimeAgent } from '@openai/agents/realtime'; @@ -76,7 +76,7 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t 4. **创建会话** - 与常规智能体不同，语音智能体会持续在一个 `RealtimeSession` 中运行并监听，它会随时间处理与模型的对话和连接。该会话还将处理音频处理、打断以及我们稍后将介绍的许多其他生命周期功能。 + 与常规智能体不同，语音智能体会在一个 `RealtimeSession` 中持续运行并监听，该会话会随时间处理与模型的对话与连接。该会话还会处理音频处理、打断以及我们稍后将介绍的其他大量生命周期功能。 ```typescript import { RealtimeSession } from '@openai/agents/realtime'; @@ -86,25 +86,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t }); ``` - `RealtimeSession` 构造函数将 `agent` 作为第一个参数。该智能体将是用户首先能够与之交互的对象。 + `RealtimeSession` 构造函数将 `agent` 作为第一个参数。这个智能体将是用户最先可以交互的对象。 5. **连接到会话** - 要连接到会话，你需要传入之前生成的客户端临时令牌。 + 要连接到会话，您需要传入之前生成的客户端临时令牌。 ```typescript await session.connect({ apiKey: 'ek_...(put your own key here)' }); ``` - 这将通过浏览器中的 WebRTC 连接到 Realtime API，并自动配置你的麦克风和扬声器用于音频输入和输出。如果你在后端服务器（如 Node.js）上运行 `RealtimeSession`，SDK 将自动使用 WebSocket 作为连接。你可以在[传输机制](/openai-agents-js/zh/guides/voice-agents/transport)指南中了解更多不同的传输层。 + 这将在浏览器中通过 WebRTC 连接到 Realtime API，并自动配置麦克风与扬声器进行音频输入和输出。如果您在后端服务器（如 Node.js）上运行 `RealtimeSession`，SDK 将自动使用 WebSocket 作为连接方式。您可以在[传输机制](/openai-agents-js/zh/guides/voice-agents/transport)指南中了解不同的传输层。 -6. **整合到一起** +6. **把它们组合在一起** -7. **启动引擎并开始对话** +7. **启动并开始对话** - 启动你的 Web 服务器并导航到包含新 Realtime Agent 代码的页面。你应该会看到麦克风访问请求。授予权限后，你就可以开始与智能体对话了。 + 启动您的 Web 服务器并打开包含新 Realtime Agent 代码的页面。您应该会看到麦克风访问请求。授予权限后，您即可开始与智能体对话。 ```bash npm run dev @@ -114,16 +114,16 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t ## 后续步骤 -从这里开始，你可以设计并构建你自己的语音智能体。语音智能体包含与常规智能体相同的许多功能，同时也有其独特之处。 +从这里开始，您可以设计并构建自己的语音智能体。语音智能体包含大量与常规智能体相同的功能，同时也有其独特特性。 -- 了解如何为你的语音智能体添加： +- 了解如何为语音智能体添加： - [工具](/openai-agents-js/zh/guides/voice-agents/build#tools) - [交接](/openai-agents-js/zh/guides/voice-agents/build#handoffs) - [护栏](/openai-agents-js/zh/guides/voice-agents/build#guardrails) - [处理音频打断](/openai-agents-js/zh/guides/voice-agents/build#audio-interruptions) - [管理会话历史](/openai-agents-js/zh/guides/voice-agents/build#session-history) -- 了解更多不同的传输层： +- 进一步了解不同的传输层： - [WebRTC](/openai-agents-js/zh/guides/voice-agents/transport#connecting-over-webrtc) - [WebSocket](/openai-agents-js/zh/guides/voice-agents/transport#connecting-over-websocket) - - [构建你自己的传输机制](/openai-agents-js/zh/guides/voice-agents/transport#building-your-own-transport-mechanism) + - [构建您自己的传输机制](/openai-agents-js/zh/guides/voice-agents/transport#building-your-own-transport-mechanism) diff --git a/docs/src/content/docs/zh/guides/voice-agents/transport.mdx b/docs/src/content/docs/zh/guides/voice-agents/transport.mdx index 91377dac..6c315901 100644 --- a/docs/src/content/docs/zh/guides/voice-agents/transport.mdx +++ b/docs/src/content/docs/zh/guides/voice-agents/transport.mdx @@ -29,29 +29,29 @@ import cloudflareTransportExample from '../../../../../../../examples/docs/exten ## 默认传输层 -### 通过 WebRTC 连接 +### WebRTC 连接 -默认传输层使用 WebRTC。音频会从麦克风录制并自动回放。 +默认传输层使用 WebRTC。音频将从麦克风录制并自动播放。 -若要使用您自己的媒体流或音频元素，请在创建会话时提供一个 `OpenAIRealtimeWebRTC` 实例。 +如需使用您自己的媒体流或音频元素，在创建会话时提供一个 `OpenAIRealtimeWebRTC` 实例。 -### 通过 WebSocket 连接 +### WebSocket 连接 -在创建会话时传入 `transport: 'websocket'` 或一个 `OpenAIRealtimeWebSocket` 实例，以使用 WebSocket 连接替代 WebRTC。此方式非常适合服务器端用例，例如使用 Twilio 构建电话智能体。 +在创建会话时传入 `transport: 'websocket'` 或 `OpenAIRealtimeWebSocket` 的实例，以使用 WebSocket 连接替代 WebRTC。这非常适合服务器端用例，例如构建使用 Twilio 的电话智能体。 -使用任意录制/回放库来处理原始 PCM16 音频字节。 +使用任意录制/播放库来处理原始 PCM16 音频字节。 -### 通过 SIP 连接 +### SIP 连接 -使用 `OpenAIRealtimeSIP` 传输来桥接来自 Twilio 等提供商的 SIP 呼叫。该传输会让 Realtime 会话与您的通信服务提供商发出的 SIP 事件保持同步。 +通过使用 `OpenAIRealtimeSIP` 传输，将来自 Twilio 等提供商的 SIP 呼叫进行桥接。该传输会让 Realtime 会话与您的电话服务提供商发出的 SIP 事件保持同步。 -1. 通过 `OpenAIRealtimeSIP.buildInitialConfig()` 生成初始会话配置以接受来电。这可确保 SIP 邀请与 Realtime 会话共享相同的默认值。 +1. 通过 `OpenAIRealtimeSIP.buildInitialConfig()` 生成初始会话配置以接受来电。这可确保 SIP 邀请与 Realtime 会话共享一致的默认值。 2. 附加一个使用 `OpenAIRealtimeSIP` 传输的 `RealtimeSession`，并使用提供商 webhook 发放的 `callId` 进行连接。 -3. 监听会话事件，以驱动通话分析、转录或升级逻辑。 +3. 监听会话事件，用于驱动通话分析、转录或升级逻辑。 @@ -61,24 +61,24 @@ Cloudflare Workers 和其他 workerd 运行时无法使用全局 `WebSocket` 构 -### 构建自定义传输机制 +### 自定义传输机制 -如果您想使用不同的语音到语音 API，或拥有自定义传输机制，可以通过实现 `RealtimeTransportLayer` 接口并发出 `RealtimeTransportEventTypes` 事件来创建自己的传输。 +如果您想使用不同的语音到语音 API，或拥有自己的自定义传输机制，可以通过实现 `RealtimeTransportLayer` 接口并发出 `RealtimeTransportEventTypes` 事件来创建自己的传输层。 -## 更直接地与 Realtime API 交互 +## 与 Realtime API 的更直接交互 -如果您想使用 OpenAI Realtime API，同时需要更直接地访问 Realtime API，有两种选择： +如果您想使用 OpenAI Realtime API，同时对 Realtime API 拥有更直接的访问方式，有两种选项： ### 选项 1 - 访问传输层 如果您仍希望受益于 `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 cde435d2..1cc56731 100644 --- a/docs/src/content/docs/zh/index.mdx +++ b/docs/src/content/docs/zh/index.mdx @@ -17,33 +17,32 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; ## 概述 -[适用于 TypeScript 的 OpenAI Agents SDK](https://github.com/openai/openai-agents-js) -让你以轻量、易用、抽象很少的方式构建智能体应用。它是我们此前 -面向智能体的实验项目 -[Swarm](https://github.com/openai/swarm/tree/main) 的生产级升级版，并且也[提供 Python 版本](https://github.com/openai/openai-agents-python)。Agents SDK 只包含一小组基础组件： +[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）**：使对智能体的输入可以被验证 +- **智能体**：配备指令和工具的 LLM +- **交接**：允许智能体将特定任务委派给其他智能体 +- **护栏**：对传入智能体的输入进行校验 -结合 TypeScript，这些基础组件足以表达工具与智能体之间的复杂关系，让你无需陡峭的学习曲线就能构建真实世界的应用。此外，SDK 内置 **追踪（tracing）**，可帮助你可视化并调试智能体流程，进行评估，甚至为你的应用微调模型。 +配合 TypeScript，这些基础组件足以表达工具与智能体之间的复杂关系，让您以较低的学习成本构建真实世界的应用。此外，SDK 内置 **追踪**，可帮助您可视化并调试智能体流程，进行评估，甚至为您的应用微调模型。 ## 为何使用 Agents SDK -该 SDK 遵循两条核心设计原则： +该 SDK 的两大设计原则： -1. 功能足够丰富，值得使用；同时基础组件足够少，便于快速上手。 -2. 开箱即用体验出色，但你可以精确自定义实际行为。 +1. 功能足够丰富值得使用，但基础组件足够少，便于快速上手。 +2. 开箱即用体验优秀，同时允许您精确自定义行为。 -SDK 的主要特性如下： +主要特性包括： -- **智能体循环（Agent loop）**：内置循环，负责调用工具、将结果发送给 LLM，并循环直至 LLM 完成。 -- **TypeScript 优先（TypeScript-first）**：使用语言内置特性来编排与串联智能体，而无需学习新的抽象。 -- **交接（Handoffs）**：强大的多智能体协调与委派能力。 -- **护栏（Guardrails）**：与智能体并行运行输入校验与检查，若检查失败则尽早中止。 -- **函数工具（Function tools）**：将任意 TypeScript 函数变为工具，自动生成 schema，并由 Zod 提供验证能力。 -- **追踪（Tracing）**：内置追踪，便于可视化、调试与监控工作流，并可使用 OpenAI 的评估、微调与蒸馏工具。 -- **实时智能体（Realtime Agents）**：构建强大的语音智能体，包括自动打断检测、上下文管理、护栏等。 +- **智能体循环**：内置循环，负责调用工具、将结果发送给 LLM，并循环直至 LLM 完成。 +- **TypeScript 优先**：使用内置语言特性来编排与串联智能体，无需学习新的抽象。 +- **交接**：在多个智能体之间进行协调与委派的强大能力。 +- **护栏**：与智能体并行运行输入校验与检查，若失败会尽早中断。 +- **函数工具**：将任意 TypeScript 函数变为工具，自动生成模式并使用 Zod 进行校验。 +- **追踪**：内置追踪，可视化、调试与监控工作流，并可使用 OpenAI 的评估、微调与蒸馏工具。 +- **实时智能体**：构建强大的语音智能体，包括自动打断检测、上下文管理、护栏等。 ## 安装