diff --git a/docs/src/content/docs/ja/guides/agents.mdx b/docs/src/content/docs/ja/guides/agents.mdx index e7eb2a124..1dbe9b9d6 100644 --- a/docs/src/content/docs/ja/guides/agents.mdx +++ b/docs/src/content/docs/ja/guides/agents.mdx @@ -16,56 +16,57 @@ import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agen import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw'; import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw'; -エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** は、次のように設定された Large Language Model (LLM) です。 +エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** とは、以下で設定された Large Language Model (LLM) です。 -- **Instructions** – モデルに _何者であるか_ と _どのように応答すべきか_ を伝えるシステムプロンプト +- **Instructions** – モデルに _自分が何者であるか_ と _どのように応答すべきか_ を伝えるシステムプロンプト - **Model** – 呼び出す OpenAI モデルと、任意のモデル調整パラメーター -- **Tools** – タスクを達成するために LLM が呼び出せる関数または API の一覧 +- **Tools** – タスク達成のために LLM が呼び出せる関数や API の一覧 -> 単一の `Agent` を定義またはカスタマイズしたい場合は、このページを利用してください。複数のエージェントをどのように連携させるかを検討している場合は、[エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) を参照してください。 +> 単一の `Agent` を定義またはカスタマイズしたい場合は、このページを使ってください。複数のエージェントをどのように連携させるかを検討している場合は、[エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) を参照してください。 ### 次のガイドの選択 -このページはエージェント定義のハブとして利用できます。次に判断したい内容に応じて、対応する関連ガイドへ進んでください。 +このページはエージェント定義のハブとして使えます。次に必要な判断に応じて、対応する隣接ガイドへ進んでください。 -| If you want to... | Read next | +| 次のようなことをしたい場合 | 次に読むもの | | --- | --- | | モデルを選ぶ、または保存済みプロンプトを設定する | [モデル](/openai-agents-js/guides/models) | | エージェントに機能を追加する | [ツール](/openai-agents-js/guides/tools) | -| マネージャーとハンドオフのどちらにするか決める | [エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) | -| ハンドオフの動作を設定する | [ハンドオフ](/openai-agents-js/guides/handoffs) | -| ターンを実行する、イベントをストリーミングする、または状態を管理する | [エージェントの実行](/openai-agents-js/guides/running-agents) | +| エージェントに分離されたファイルシステムのワークスペースを与える | [Sandbox clients](/openai-agents-js/guides/sandbox-agents/concepts) | +| manager と handoff のどちらにするか決める | [エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) | +| handoff の動作を設定する | [ハンドオフ](/openai-agents-js/guides/handoffs) | +| turn を実行する、イベントをストリーミングする、または状態を管理する | [エージェントの実行](/openai-agents-js/guides/running-agents) | | 最終出力、実行項目、または再開を確認する | [エージェントの実行結果](/openai-agents-js/guides/results) | このページの残りでは、Agent の各機能をさらに詳しく説明します。 --- -## エージェントの基礎 +## エージェントの基本 ### 基本設定 -`Agent` コンストラクターは 1 つの設定オブジェクトを受け取ります。最もよく使われるプロパティを以下に示します。 +`Agent` コンストラクターは単一の設定オブジェクトを受け取ります。最もよく使われるプロパティは以下のとおりです。 | Property | Required | Description | | --- | --- | --- | -| `name` | yes | 人間が読める短い識別子 | +| `name` | yes | 人が読める短い識別子 | | `instructions` | yes | システムプロンプト（文字列 **または** 関数。詳細は [動的 instructions](#dynamic-instructions) を参照） | -| `prompt` | no | OpenAI Responses API のプロンプト設定です。静的なプロンプトオブジェクトまたは関数を受け取ります。[Prompt](/openai-agents-js/guides/models#prompt) を参照してください | -| `handoffDescription` | no | このエージェントがハンドオフツールとして提供される際に使われる短い説明 | -| `handoffs` | no | 会話を専門エージェントに委譲します。[構成パターン](#composition-patterns) および [ハンドオフ ガイド](/openai-agents-js/guides/handoffs) を参照してください | +| `prompt` | no | OpenAI Responses API の prompt 設定。静的な prompt オブジェクトまたは関数を受け取ります。[Prompt](/openai-agents-js/guides/models#prompt) を参照してください | +| `handoffDescription` | no | このエージェントが handoff ツールとして提示される際に使われる短い説明 | +| `handoffs` | no | 会話を専門エージェントに委譲します。[構成パターン](#composition-patterns) と [ハンドオフ ガイド](/openai-agents-js/guides/handoffs) を参照してください | | `model` | no | モデル名 **または** カスタム [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装 | -| `modelSettings` | no | 調整パラメーター（temperature、top_p など）。[モデル](/openai-agents-js/guides/models#modelsettings) を参照してください。必要なプロパティがトップレベルにない場合は、`providerData` 配下に含められます | -| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列です。[ツール](/openai-agents-js/guides/tools) を参照してください | -| `mcpServers` | no | エージェント向けの MCP ベースのツールです。[MCP 連携](/openai-agents-js/guides/mcp) を参照してください | -| `inputGuardrails` | no | このエージェントチェーンの最初のユーザー入力に適用されるガードレールです。[ガードレール](/openai-agents-js/guides/guardrails) を参照してください | -| `outputGuardrails` | no | このエージェントの最終出力に適用されるガードレールです。[ガードレール](/openai-agents-js/guides/guardrails) を参照してください | -| `outputType` | no | プレーンテキストの代わりに structured outputs を返します。[出力型](#output-types) および [エージェントの実行結果](/openai-agents-js/guides/results#final-output) を参照してください | -| `toolUseBehavior` | no | 関数ツールの結果をモデルに戻すか、実行を終了するかを制御します。[ツール使用の強制](#forcing-tool-use) を参照してください | -| `resetToolChoice` | no | ツール呼び出し後に `toolChoice` をデフォルトにリセットします（デフォルト: `true`）。ツール使用ループを防ぐためです。[ツール使用の強制](#forcing-tool-use) を参照してください | -| `handoffOutputTypeWarningEnabled` | no | ハンドオフ先で出力型が異なる場合に警告を出します（デフォルト: `true`）。[エージェントの実行結果](/openai-agents-js/guides/results#final-output) を参照してください | +| `modelSettings` | no | 調整パラメーター（temperature、top_p など）。[モデル](/openai-agents-js/guides/models#modelsettings) を参照してください。必要なプロパティがトップレベルにない場合は、`providerData` の下に含められます | +| `tools` | no | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列。[ツール](/openai-agents-js/guides/tools) を参照してください | +| `mcpServers` | no | エージェント向けの MCP ベースのツール。[MCP 連携](/openai-agents-js/guides/mcp) を参照してください | +| `inputGuardrails` | no | このエージェントチェーンの最初のユーザー入力に適用されるガードレール。[ガードレール](/openai-agents-js/guides/guardrails) を参照してください | +| `outputGuardrails` | no | このエージェントの最終出力に適用されるガードレール。[ガードレール](/openai-agents-js/guides/guardrails) を参照してください | +| `outputType` | no | プレーンテキストの代わりに structured outputs を返します。[出力型](#output-types) と [エージェントの実行結果](/openai-agents-js/guides/results#final-output) を参照してください | +| `toolUseBehavior` | no | 関数ツールの結果をモデルに戻してループさせるか、実行を終了するかを制御します。[ツール使用の強制](#forcing-tool-use) を参照してください | +| `resetToolChoice` | no | ツール呼び出し後に `toolChoice` をデフォルトに戻します（デフォルト: `true`）。ツール使用ループを防ぎます。[ツール使用の強制](#forcing-tool-use) を参照してください | +| `handoffOutputTypeWarningEnabled` | no | handoff の出力型が異なる場合に警告を出します（デフォルト: `true`）。[エージェントの実行結果](/openai-agents-js/guides/results#final-output) を参照してください | @@ -73,7 +74,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### コンテキスト -エージェントは **コンテキスト型に対してジェネリック** です。つまり `Agent` です。_context_ は依存性注入用のオブジェクトであり、これを作成して `Runner.run()` に渡します。これはすべてのツール、ガードレール、ハンドオフなどに渡され、状態の保存や共有サービス（データベース接続、ユーザーメタデータ、機能フラグなど）の提供に役立ちます。 +エージェントは **コンテキスト型に対してジェネリック** です。つまり `Agent` です。_context_ は、作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、handoff などに渡され、状態の保存や共有サービス（データベース接続、ユーザーメタデータ、feature flag など）の提供に役立ちます。 @@ -92,46 +93,46 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor title="Structured output with Zod" /> -`outputType` が指定されている場合、SDK はプレーンテキストの代わりに自動的に [structured outputs](https://developers.openai.com/api/docs/guides/structured-outputs) を使用します。 +`outputType` を指定すると、SDK はプレーンテキストの代わりに自動的に [structured outputs](https://developers.openai.com/api/docs/guides/structured-outputs) を使用します。 --- -### OpenAI プラットフォームとの対応 +### OpenAI プラットフォームとの対応関係 -一部のエージェントの概念は OpenAI プラットフォームの概念に直接対応していますが、他はエージェント定義時ではなく実行時に設定されます。 +一部のエージェント概念は OpenAI プラットフォームの概念に直接対応していますが、他はエージェント定義時ではなく、実行時に設定します。 | SDK concept | OpenAI guide | When it matters | | --- | --- | --- | -| `outputType` | [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) | エージェントがテキストの代わりに型付き JSON または Zod で検証されたオブジェクトを返す必要がある場合 | -| `tools` / hosted tools | [Tools guide](https://developers.openai.com/api/docs/guides/tools) | モデルに検索、取得、コード実行、または関数 / ツール呼び出しをさせたい場合 | -| `conversationId` / `previousResponseId` | [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) | OpenAI にターン間の会話状態を永続化または連結させたい場合 | +| `outputType` | [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) | エージェントがテキストではなく、型付き JSON または Zod で検証されたオブジェクトを返すべき場合 | +| `tools` / hosted tools | [Tools guide](https://developers.openai.com/api/docs/guides/tools) | モデルが検索、取得、コード実行、または独自の関数 / ツール呼び出しを行うべき場合 | +| `conversationId` / `previousResponseId` | [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) | OpenAI に turn 間の会話状態を永続化または連結させたい場合 | -`conversationId` と `previousResponseId` は実行時の制御であり、`Agent` コンストラクターのフィールドではありません。これらの SDK エントリーポイントが必要な場合は [エージェントの実行](/openai-agents-js/guides/running-agents) を利用してください。 +`conversationId` と `previousResponseId` は実行時の制御であり、`Agent` コンストラクターのフィールドではありません。これらの SDK エントリーポイントが必要な場合は、[エージェントの実行](/openai-agents-js/guides/running-agents) を使ってください。 --- ## 構成パターン -エージェントがより大きなワークフローに参加する場合、最もよく使われる SDK のエントリーポイントは 2 つあります。 +エージェントがより大きなワークフローに参加する場合、よく登場する SDK エントリーポイントは 2 つあります。 1. **Manager（Agents as tools）** – 中央のエージェントが会話を管理し、ツールとして公開された専門エージェントを呼び出します -2. **ハンドオフ** – 最初のエージェントが、ユーザーの要求を特定した時点で会話全体を専門エージェントに委譲します +2. **ハンドオフ** – 最初のエージェントが、ユーザーの要求を特定したら会話全体を専門エージェントに委譲します -これらのアプローチは相補的です。Manager はガードレールやレート制限を一元的に適用する場所を提供し、ハンドオフは各エージェントが会話の制御を保持せずに単一のタスクに集中できるようにします。設計上のトレードオフや、どのパターンを選ぶべきかについては、[エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) を参照してください。 +これらのアプローチは相補的です。manager ではガードレールや rate limit を適用する場所を 1 つに集約でき、handoff では各エージェントが会話の制御を持ち続けることなく 1 つのタスクに集中できます。設計上のトレードオフや、どちらのパターンを選ぶべきかについては、[エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) を参照してください。 #### Manager（Agents as tools） -このパターンでは Manager は制御を渡しません。LLM がツールを使用し、Manager が最終回答を要約します。詳しくは [ツール ガイド](/openai-agents-js/guides/tools#agents-as-tools) を参照してください。 +このパターンでは、manager は制御を渡しません。LLM がツールを使い、manager が最終回答を要約します。詳細は [ツール ガイド](/openai-agents-js/guides/tools#agents-as-tools) を参照してください。 #### ハンドオフ -ハンドオフでは、トリアージエージェントがリクエストを振り分けますが、ひとたびハンドオフが発生すると、専門エージェントが最終出力を生成するまで会話を担当します。これによりプロンプトを短く保て、各エージェントを独立して考えやすくなります。詳しくは [ハンドオフ ガイド](/openai-agents-js/guides/handoffs) を参照してください。 +handoff では、triage エージェントがリクエストを振り分けますが、handoff が発生すると、専門エージェントが最終出力を生成するまで会話を担当します。これによりプロンプトを短く保てて、各エージェントを独立して考えやすくなります。詳細は [ハンドオフ ガイド](/openai-agents-js/guides/handoffs) を参照してください。 -ハンドオフ先が異なる出力型を返す可能性がある場合は、`new Agent(...)` よりも `Agent.create(...)` を優先してください。これにより TypeScript がハンドオフグラフ全体で起こり得る `finalOutput` の形の union を推論でき、`handoffOutputTypeWarningEnabled` で制御される実行時警告も回避できます。エンドツーエンドの例については [エージェントの実行結果 ガイド](/openai-agents-js/guides/results#final-output) を参照してください。 +handoff 先が異なる出力型を返す可能性がある場合は、`new Agent(...)` より `Agent.create(...)` を使うことをおすすめします。これにより TypeScript が handoff グラフ全体で取りうる `finalOutput` の shape の union を推論でき、`handoffOutputTypeWarningEnabled` で制御される実行時警告も避けられます。エンドツーエンドの例は [エージェントの実行結果 ガイド](/openai-agents-js/guides/results#final-output) を参照してください。 --- @@ -139,7 +140,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### 動的 instructions -`instructions` は文字列ではなく **関数** にすることもできます。この関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返せます。 +`instructions` には文字列の代わりに **関数** を指定できます。この関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise` を返せます。 -同期関数と `async` 関数の両方がサポートされています。 +同期関数と `async` 関数の両方に対応しています。 --- -### 動的プロンプト +### 動的 prompt -`prompt` は `instructions` と同じコールバック形式をサポートしますが、文字列ではなくプロンプト設定オブジェクトを返します。これは、プロンプト ID、バージョン、または変数が現在の実行コンテキストに依存する場合に便利です。 +`prompt` は `instructions` と同じコールバック形をサポートしますが、文字列ではなく prompt 設定オブジェクトを返します。これは、prompt ID、version、または variables が現在の実行コンテキストに依存する場合に便利です。 -これは OpenAI Responses API を使用している場合にのみサポートされます。同期関数と `async` 関数の両方がサポートされています。 +これは OpenAI Responses API を使う場合にのみサポートされます。同期関数と `async` 関数の両方に対応しています。 --- ### ライフサイクルフック -高度なユースケースでは、イベントを監視することで Agent のライフサイクルを観察できます。 +高度なユースケースでは、イベントを listen することで Agent のライフサイクルを監視できます。 -`Agent` インスタンスはその特定のエージェントインスタンスに対するライフサイクルイベントを発行し、`Runner` は同じイベント名を実行全体にわたる単一のストリームとして発行します。これは、ハンドオフやツール呼び出しを 1 か所で観察したいマルチエージェントワークフローで役立ちます。 +`Agent` インスタンスはその特定のエージェントインスタンス向けのライフサイクルイベントを発行し、`Runner` は実行全体にわたる単一のストリームとして同じイベント名を発行します。これは、handoff やツール呼び出しを 1 か所で監視したいマルチエージェントワークフローで便利です。 共通のイベント名は次のとおりです。 @@ -191,13 +192,13 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### ガードレール -ガードレールを使うと、ユーザー入力やエージェント出力を検証または変換できます。`inputGuardrails` および `outputGuardrails` 配列で設定します。詳細は [ガードレール ガイド](/openai-agents-js/guides/guardrails) を参照してください。 +ガードレールを使うと、ユーザー入力やエージェント出力を検証または変換できます。これらは `inputGuardrails` と `outputGuardrails` の配列で設定します。詳細は [ガードレール ガイド](/openai-agents-js/guides/guardrails) を参照してください。 --- ### エージェントの複製 / コピー -既存のエージェントを少しだけ変更した版が必要ですか。`clone()` メソッドを使うと、まったく新しい `Agent` インスタンスを返します。 +既存のエージェントを少しだけ変更したバージョンが必要ですか。`clone()` メソッドを使ってください。完全に新しい `Agent` インスタンスを返します。 @@ -205,27 +206,27 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### ツール使用の強制 -ツールを渡しても、LLM が必ずそれを呼び出すとは限りません。`modelSettings.toolChoice` を使うと、ツール使用を **強制** できます。 +ツールを渡しても、LLM がそれを呼び出すとは限りません。`modelSettings.toolChoice` を使うと、ツール使用を **強制** できます。 -1. `'auto'`（デフォルト）– ツールを使うかどうかを LLM が判断します -2. `'required'` – LLM は必ずツールを呼び出さなければなりません（どれを使うかは選べます） -3. `'none'` – LLM はツールを呼び出しては **いけません** -4. 特定のツール名（例: `'calculator'`）– LLM はその特定のツールを呼び出さなければなりません +1. `'auto'`（デフォルト）– LLM がツールを使うかどうかを決めます +2. `'required'` – LLM はツールを必ず呼び出さなければなりません（どれを使うかは選べます） +3. `'none'` – LLM はツールを **呼び出してはいけません** +4. 特定のツール名。たとえば `'calculator'` – LLM はその特定のツールを呼び出さなければなりません -利用可能なツールが OpenAI Responses の `computerTool()` の場合、`toolChoice: 'computer'` は特別です。`'computer'` を通常の関数名として扱うのではなく、GA の組み込みコンピュータツールを強制します。SDK は古い統合向けに preview 互換のコンピュータセレクターも受け付けますが、新しいコードでは `'computer'` を優先してください。利用可能なコンピュータツールがない場合、この文字列は他の関数ツール名と同様に動作します。 +利用可能なツールが OpenAI Responses 上の `computerTool()` の場合、`toolChoice: 'computer'` は特別です。これは `'computer'` を通常の関数名として扱うのではなく、GA の組み込み computer tool を強制します。SDK は古い連携向けに preview 互換の computer selector も受け付けますが、新しいコードでは `'computer'` を使うべきです。computer tool が利用できない場合、この文字列は他の関数ツール名と同様に振る舞います。 -`toolNamespace()` のような遅延 Responses ツール、`deferLoading: true` を持つ関数ツール、または `deferLoading: true` を持つ hosted MCP ツールを使う場合は、`modelSettings.toolChoice` を `'auto'` のままにしてください。SDK は、遅延ツールや組み込みの `tool_search` ヘルパーを名前で強制することを拒否します。これらの定義をいつ読み込むかはモデルが判断する必要があるためです。完全な tool-search の設定については、[ツール ガイド](/openai-agents-js/guides/tools#deferred-tool-loading-with-tool-search) を参照してください。 +`toolNamespace()` のような deferred Responses ツール、`deferLoading: true` を持つ関数ツール、または `deferLoading: true` を持つ hosted MCP ツールを使う場合は、`modelSettings.toolChoice` を `'auto'` のままにしてください。SDK は deferred tool や組み込みの `tool_search` ヘルパーを名前指定で強制することを拒否します。これは、モデルがそれらの定義をいつ読み込むかを決める必要があるためです。完全な tool search の設定については、[ツール ガイド](/openai-agents-js/guides/tools#deferred-tool-loading-with-tool-search) を参照してください。 #### 無限ループの防止 -ツール呼び出し後、SDK は自動的に `toolChoice` を `'auto'` に戻します。これにより、モデルがツールを繰り返し呼び出そうとして無限ループに入るのを防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定によって上書きできます。 +ツール呼び出しの後、SDK は自動的に `toolChoice` を `'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({ @@ -240,10 +241,10 @@ const agent = new Agent({ ## 関連ガイド -- モデル選択、保存済みプロンプト、プロバイダー設定については [モデル](/openai-agents-js/guides/models) +- モデル選択、保存済みプロンプト、provider 設定については [モデル](/openai-agents-js/guides/models) - 関数ツール、hosted tools、MCP、`agent.asTool()` については [ツール](/openai-agents-js/guides/tools) -- Manager、ハンドオフ、コード主導のオーケストレーションの選び方については [エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) +- manager、handoff、コード駆動のオーケストレーションの選び方については [エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) - 専門エージェントへの委譲設定については [ハンドオフ](/openai-agents-js/guides/handoffs) -- ターン実行、ストリーミング、会話状態については [エージェントの実行](/openai-agents-js/guides/running-agents) +- turn の実行、ストリーミング、会話状態については [エージェントの実行](/openai-agents-js/guides/running-agents) - `finalOutput`、実行項目、再開状態については [エージェントの実行結果](/openai-agents-js/guides/results) -- サイドバーの **@openai/agents** 配下にある完全な TypeDoc リファレンスも参照してください +- サイドバーの **@openai/agents** から完全な TypeDoc リファレンスを参照できます diff --git a/docs/src/content/docs/ja/guides/running-agents.mdx b/docs/src/content/docs/ja/guides/running-agents.mdx index e10421a7a..96874589a 100644 --- a/docs/src/content/docs/ja/guides/running-agents.mdx +++ b/docs/src/content/docs/ja/guides/running-agents.mdx @@ -13,45 +13,45 @@ import previousResponseIdExample from '../../../../../../examples/docs/running-a エージェントはそれ自体では何もしません。`Runner` クラスまたは `run()` ユーティリティで **実行** します。 -> ターンの実行、イベントのストリーミング、会話状態の管理を行いたくなったら、このページを [エージェント](/openai-agents-js/ja/guides/agents) の後に読んでください。エージェントをどのように定義するかをまだ検討中であれば、まずは [エージェント](/openai-agents-js/ja/guides/agents) から始めてください。 +> このページは、ターンを実行したい、イベントをストリーミングしたい、または会話の状態を管理したい段階で、[エージェント](/openai-agents-js/ja/guides/agents) の後に読んでください。エージェントをどう定義すべきかまだ検討中であれば、まずは [エージェント](/openai-agents-js/ja/guides/agents) から始めてください。 -カスタム runner が不要な場合は、`run()` ユーティリティも使用できます。これはデフォルトの `Runner` シングルトンインスタンスを実行します。 +カスタム runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスを実行する `run()` ユーティリティも使えます。 -あるいは、独自の runner インスタンスを作成することもできます。 +または、自分で runner インスタンスを作成することもできます。 -エージェントを実行すると、最終出力と実行の完全な履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 +エージェントを実行すると、最終出力と実行の完全な履歴を含む [実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。 ## Runner のライフサイクルと設定 ### エージェントループ -`Runner` の run メソッドを使うときは、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージとして扱われます）か、OpenAI Responses API の項目である入力項目のリストのいずれかです。 +`Runner` の run メソッドを使うときは、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージとして扱われます）か、OpenAI Responses API の項目である input items のリストのいずれかです。 runner は次のループを実行します。 1. 現在の入力で現在のエージェントのモデルを呼び出す -2. LLM の応答を確認する - - **最終出力** → 戻る - - **ハンドオフ** → 新しいエージェントに切り替え、蓄積された会話履歴を保持して 1 に戻る - - **ツール呼び出し** → ツールを実行し、その結果を会話に追加して 1 に戻る +2. LLM のレスポンスを確認する + - **最終出力** → return + - **ハンドオフ** → 新しいエージェントに切り替え、蓄積された会話履歴を保持し、1 に戻る + - **ツール呼び出し** → ツールを実行し、その結果を会話に追加し、1 に戻る 3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローする #### Runner のライフサイクル -`Runner` はアプリの起動時に作成し、リクエスト間で再利用してください。インスタンスには、モデル provider やトレーシングオプションなどのグローバル設定が保存されます。まったく異なる設定が必要な場合にのみ、別の `Runner` を作成してください。単純なスクリプトであれば、内部でデフォルト runner を使う `run()` を呼び出すこともできます。 +アプリの起動時に `Runner` を作成し、リクエスト間で再利用してください。このインスタンスには、モデル provider やトレーシング設定などのグローバル設定が保存されます。完全に異なるセットアップが必要な場合にのみ、別の `Runner` を作成してください。単純なスクリプトでは、内部でデフォルト runner を使う `run()` を呼ぶこともできます。 ### 実行引数 -`run()` メソッドへの入力は、実行を開始する初期エージェント、実行用の入力、およびオプションのセットです。 +`run()` メソッドへの入力は、実行を開始する初期エージェント、実行用の入力、および一連のオプションです。 入力は、文字列（ユーザーメッセージとして扱われます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [human-in-the-loop](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。 @@ -59,65 +59,69 @@ runner は次のループを実行します。 | 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) をスローします | +| `stream` | `false` | `true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから届いたイベントをその都度出力します | +| `context` | – | すべてのツール / ガードレール / ハンドオフに渡されるコンテキストオブジェクトです。詳細は [コンテキスト管理ガイド](/openai-agents-js/ja/guides/context) を参照してください | +| `maxTurns` | `10` | 安全上の上限です。到達すると [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローします | | `signal` | – | キャンセル用の `AbortSignal` | | `session` | – | セッション永続化の実装です。[セッションガイド](/openai-agents-js/ja/guides/sessions) を参照してください | | `sessionInputCallback` | – | セッション履歴と新しい入力をマージするカスタムロジックです。モデル呼び出し前に実行されます。[セッション](/openai-agents-js/ja/guides/sessions) を参照してください | -| `callModelInputFilter` | – | モデル呼び出し直前にモデル入力（項目 + オプションの instructions）を編集するフックです。[Call model input filter](#call-model-input-filter) を参照してください | -| `toolErrorFormatter` | – | モデルに返されるツール承認拒否メッセージをカスタマイズするフックです。[Tool error formatter](#tool-error-formatter) を参照してください | -| `reasoningItemIdPolicy` | – | 以前の実行項目をモデル入力に戻すときに、reasoning-item の `id` を保持するか省略するかを制御します。[Reasoning item ID policy](#reasoning-item-id-policy) を参照してください | -| `tracing` | – | 実行ごとのトレーシング設定の上書きです（例: export API key） | -| `errorHandlers` | – | サポートされているランタイムエラー用のハンドラーです（現在は `maxTurns`）。[Error handlers](#error-handlers) を参照してください | +| `callModelInputFilter` | – | モデル呼び出し直前にモデル入力（items + オプションの instructions）を編集する hook です。[Call model input filter](#call-model-input-filter) を参照してください | +| `toolErrorFormatter` | – | モデルに返すツール承認拒否メッセージをカスタマイズする hook です。[Tool error formatter](#tool-error-formatter) を参照してください | +| `reasoningItemIdPolicy` | – | 以前の実行項目をモデル入力に戻す際に、reasoning-item の `id` を保持するか省略するかを制御します。[Reasoning item ID policy](#reasoning-item-id-policy) を参照してください | +| `tracing` | – | 実行単位のトレーシング設定上書きです（例: export API key） | +| `sandbox` | – | `SandboxAgent` 実行用の sandbox client、live session、session state、snapshot、manifest override、または並行実行数制限です。[Sandbox agents](/openai-agents-js/ja/guides/sandbox-agents/concepts) を参照してください | +| `errorHandlers` | – | サポートされている実行時エラーのハンドラーです（現在は `maxTurns` のみ）。[Error handlers](#error-handlers) を参照してください | | `conversationId` | – | サーバー側の会話を再利用します（OpenAI Responses API + Conversations API のみ） | -| `previousResponseId` | – | 会話を作成せずに、前回の Responses API 呼び出しから継続します（OpenAI Responses API のみ） | +| `previousResponseId` | – | 会話を作成せずに前回の Responses API 呼び出しから継続します（OpenAI Responses API のみ） | ### ストリーミング -ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリームが開始されると、`StreamedRunResult` には、新たに生成されたすべての出力を含む実行の完全な情報が含まれます。ストリーミングイベントは `for await` ループで反復処理できます。詳細は [ストリーミングガイド](/openai-agents-js/ja/guides/streaming) を参照してください。 +ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリームが開始されると、`StreamedRunResult` には、生成されたすべての新しい出力を含む実行の完全な情報が格納されます。ストリーミングイベントは `for await` ループで反復できます。詳細は [ストリーミングガイド](/openai-agents-js/ja/guides/streaming) を参照してください。 -### RunConfig +### 実行設定 -独自の `Runner` インスタンスを作成する場合は、runner を設定するために `RunConfig` オブジェクトを渡せます。 +独自の `Runner` インスタンスを作成する場合は、runner を設定するための `RunConfig` オブジェクトを渡せます。 | Field | Type | Purpose | | --- | --- | --- | -| `model` | `string \| Model` | 実行内の **すべての** エージェントに対して特定のモデルを強制します | +| `model` | `string \| Model` | 実行内の **すべて** のエージェントに対して特定のモデルを強制します | | `modelProvider` | `ModelProvider` | モデル名を解決します。デフォルトは OpenAI provider です | -| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルな調整パラメーターです。詳細と opt-in の retry 設定については [モデルガイド](/openai-agents-js/ja/guides/models#modelsettings) を参照してください | -| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ実行時に入力項目を変更します（ハンドオフ自体で未定義の場合） | +| `modelSettings` | `ModelSettings` | エージェントごとの設定を上書きするグローバルなチューニングパラメーターです。opt-in の retry 設定を含む詳細は [モデルガイド](/openai-agents-js/ja/guides/models#modelsettings) を参照してください | +| `handoffInputFilter` | `HandoffInputFilter` | ハンドオフ実行時に input items を変更します（ハンドオフ自体で未定義の場合） | | `inputGuardrails` | `InputGuardrail[]` | _初期_ ユーザー入力に適用されるガードレール | | `outputGuardrails` | `OutputGuardrail[]` | _最終_ 出力に適用されるガードレール | | `tracingDisabled` | `boolean` | OpenAI Tracing を完全に無効化します | | `traceIncludeSensitiveData` | `boolean` | span は出力しつつ、トレースから LLM / ツールの入力と出力を除外します | -| `workflowName` | `string` | Traces ダッシュボードに表示され、関連する実行のグループ化に役立ちます | -| `traceId` / `groupId` | `string` | SDK に生成させる代わりに、trace または group ID を手動指定します | -| `traceMetadata` | `Record` | 各 span に付与する任意のメタデータ | -| `tracing` | `TracingConfig` | 実行ごとのトレーシング上書きです（例: export API key） | +| `workflowName` | `string` | Traces ダッシュボードに表示されます。関連する実行のグループ化に役立ちます | +| `traceId` / `groupId` | `string` | SDK に生成させる代わりに trace または group ID を手動指定します | +| `traceMetadata` | `Record` | すべての span に付与する任意のメタデータ | +| `tracing` | `TracingConfig` | 実行単位のトレーシング上書きです（例: export API key） | | `sessionInputCallback` | `SessionInputCallback` | この runner 上のすべての実行に対するデフォルトの履歴マージ戦略です | -| `callModelInputFilter` | `CallModelInputFilter` | 各モデル呼び出し前にモデル入力を編集するグローバルフックです | -| `toolErrorFormatter` | `ToolErrorFormatter` | モデルに返されるツール承認拒否メッセージをカスタマイズするグローバルフックです | -| `reasoningItemIdPolicy` | `ReasoningItemIdPolicy` | 後続のモデル呼び出しに生成済み項目を再利用するとき、reasoning-item の `id` を保持するか省略するかのデフォルトポリシーです | +| `callModelInputFilter` | `CallModelInputFilter` | 各モデル呼び出し前にモデル入力を編集するグローバル hook です | +| `toolErrorFormatter` | `ToolErrorFormatter` | モデルに返すツール承認拒否メッセージをカスタマイズするグローバル hook です | +| `reasoningItemIdPolicy` | `ReasoningItemIdPolicy` | 生成済み項目を後続のモデル呼び出しへ再投入する際に、reasoning-item の `id` を保持または省略するデフォルトポリシーです | +| `sandbox` | `SandboxRunConfig` | `SandboxAgent` 実行用のデフォルト sandbox ランタイム設定です | -## 状態と会話管理 +## 状態と会話の管理 ### メモリ戦略の選択 -状態を次のターンに引き継ぐ一般的な方法は 4 つあります。 +次のターンへ状態を引き継ぐ一般的な方法は 4 つあります。 | Strategy | Where state lives | Best for | What you pass on the next turn | | --- | --- | --- | --- | | `result.history` | アプリのメモリ | 小規模なチャットループ、完全な手動制御、任意の provider | `result.history` | -| `session` | ストレージ + SDK | 永続的なチャット状態、再開可能な実行、カスタムストア | 同じ `session` インスタンス（またはストアをバックエンドに持つもの） | +| `session` | ストレージ + SDK | 永続的なチャット状態、再開可能な実行、カスタムストア | 同じ `session` インスタンス（またはストア backed のもの） | | `conversationId` | OpenAI Conversations API | worker / service 間で共有されるサーバー側状態 | 同じ `conversationId` と新しいユーザーターンのみ | -| `previousResponseId` | OpenAI Responses API のみ | 会話を作らずに行う最もシンプルなサーバー管理の継続 | `result.lastResponseId` と新しいユーザーターンのみ | +| `previousResponseId` | OpenAI Responses API のみ | 会話を作らずに行う最もシンプルなサーバー管理継続 | `result.lastResponseId` と新しいユーザーターンのみ | -`result.history` と `session` はクライアント管理です。`conversationId` と `previousResponseId` は OpenAI 管理であり、OpenAI Responses API を使用している場合にのみ適用されます。ほとんどのアプリケーションでは、会話ごとに 1 つの永続化戦略を選んでください。クライアント管理の履歴とサーバー管理の状態を混在させると、意図的に両レイヤーを調整していない限り、コンテキストが重複する可能性があります。 +`result.history` と `session` はクライアント管理です。`conversationId` と `previousResponseId` は OpenAI 管理で、OpenAI Responses API を使っている場合にのみ適用されます。ほとんどのアプリケーションでは、会話ごとに 1 つの永続化戦略を選んでください。クライアント管理の履歴とサーバー管理の状態を混在させると、両レイヤーを意図的に調整していない限りコンテキストが重複する可能性があります。 -### Conversations / チャットスレッド +Sandbox agents では、さらに別の状態レイヤーである live sandbox workspace が追加されます。会話履歴には通常の SDK の `session`、`conversationId`、または `previousResponseId` を使い、sandbox のファイルシステム状態には `sandbox.session`、`sandbox.sessionState`、`RunState`、または snapshots を使ってください。workspace のライフサイクルについては [Sandbox agents](/openai-agents-js/ja/guides/sandbox-agents/concepts) を参照してください。 -`runner.run()`（または `run()` ユーティリティ）の各呼び出しは、アプリケーションレベルの会話における 1 つの **ターン** を表します。`RunResult` のどこまでをエンドユーザーに見せるかは選択できます。`finalOutput` のみの場合もあれば、生成されたすべての項目を表示する場合もあります。 +### 会話 / チャットスレッド + +`runner.run()`（または `run()` ユーティリティ）の各呼び出しは、アプリケーションレベルの会話における 1 つの **ターン** を表します。`RunResult` のどこまでをエンドユーザーに見せるかは選べます。`finalOutput` だけの場合もあれば、生成されたすべての項目を見せる場合もあります。 -対話形式のバージョンについては、[chat example](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 +対話型バージョンについては、[chat example](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。 #### サーバー管理の会話 -ターンごとにローカル会話履歴全体を送信する代わりに、OpenAI Responses API に会話履歴を永続化させることができます。これは、長い会話や複数のサービスを調整する場合に便利です。以下のいずれのサーバー管理アプローチでも、各リクエストでは新しいターンの入力だけを渡します。API が以前の状態を再利用します。詳細は [Conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state) を参照してください。 +各ターンでローカルの会話履歴全体を送る代わりに、OpenAI Responses API に会話履歴を永続化させることができます。これは、長い会話や複数サービスを調整する場合に便利です。以下のいずれのサーバー管理アプローチでも、各リクエストでは新しいターンの入力だけを渡してください。API が以前の状態を再利用します。詳細は [Conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state) を参照してください。 -OpenAI は、サーバー側状態を再利用する 2 つの方法を提供しています。 +OpenAI では、サーバー側状態を再利用する方法が 2 つ提供されています。 ##### 1. 会話全体に対する `conversationId` @@ -145,7 +149,7 @@ OpenAI は、サーバー側状態を再利用する 2 つの方法を提供し ##### 2. 最後のターンから継続する `previousResponseId` -Responses API だけで始めたい場合は、前回の response から返された ID を使って各リクエストをつなげられます。これにより、完全な会話リソースを作成せずに、ターンをまたいでコンテキストを維持できます。 +そもそも Responses API だけで始めたい場合は、前回のレスポンスで返された ID を使って各リクエストを連結できます。これにより、完全な会話リソースを作成せずにターンをまたいでコンテキストを維持できます。 -`conversationId` と `previousResponseId` は相互排他的です。システム間で共有できる名前付きの会話リソースが必要なら `conversationId` を使い、単に 1 つの response から次へと最も低コストな SDK レベルの継続機能がほしいだけなら `previousResponseId` を使ってください。 +`conversationId` と `previousResponseId` は同時には使えません。システム間で共有できる名前付きの会話リソースが必要なら `conversationId` を使い、1 つのレスポンスから次へと最小コストで SDK レベルの継続をしたいだけなら `previousResponseId` を使ってください。 -## フックとカスタマイズ +## Hook とカスタマイズ ### Call model input filter -`callModelInputFilter` を使うと、モデル呼び出しの _直前_ にモデル入力を編集できます。このフックは、現在のエージェント、コンテキスト、および結合済みの入力項目（存在する場合はセッション履歴を含む）を受け取ります。機微データのマスキング、古いメッセージの削除、追加のシステムガイダンスの挿入を行うために、更新後の `input` 配列とオプションの `instructions` を返します。 +`callModelInputFilter` を使うと、モデル呼び出しの _直前_ にモデル入力を編集できます。この hook は、現在のエージェント、コンテキスト、および結合済みの input items（存在する場合はセッション履歴を含む）を受け取ります。機密データのマスキング、古いメッセージの削除、追加のシステムガイダンスの注入のために、更新後の `input` 配列とオプションの `instructions` を返してください。 -実行ごとに `runner.run(..., { callModelInputFilter })` で設定するか、`Runner` 設定のデフォルト（`RunConfig` の `callModelInputFilter`）として設定します。 +`runner.run(..., { callModelInputFilter })` で実行単位に設定するか、`Runner` の設定（`RunConfig` の `callModelInputFilter`）でデフォルトとして設定します。 戻り値は `ModelInputData` オブジェクト、すなわち `{ input: AgentInputItem[], instructions? }` である必要があります。`input` フィールドは必須で、配列でなければなりません。これ以外の形を返すと `UserError` がスローされます。 -SDK は、filter を呼び出す前に準備済みのターン入力を複製します。`session` も使用している場合、永続化されるのはこの filter 済みの複製なので、ここで適用したマスキングや切り詰めは保存されるセッション履歴にも反映されます。 +SDK は filter を呼び出す前に準備済みターン入力を clone します。`session` も使っている場合、永続化されるのは filter 後の clone なので、ここで適用したマスキングや切り詰めは保存されるセッション履歴にも反映されます。 -`conversationId` または `previousResponseId` を使う場合、このフックは次の Responses API 呼び出し用に準備されたペイロードに対して実行されます。以前のサーバー管理コンテキストは API によって復元されるため、その呼び出し用の filter 済み配列は、以前の履歴全体の再生ではなく、新しいターンの差分のみを表している場合があります。この最終 filter ステップの前に、保存済み履歴と現在のターンをどのようにマージするかを変更したい場合は、`sessionInputCallback` を使用してください。 +`conversationId` または `previousResponseId` では、この hook は次の Responses API 呼び出し用に準備された payload に対して実行されます。以前のサーバー管理コンテキストは API によって復元されるため、その呼び出し用の filter 済み配列は、過去の履歴全体の再送ではなく、新しいターンの差分のみをすでに表している場合があります。この最終 filter ステップ前に、保存済み履歴と現在のターンのマージ方法を変更したい場合は、`sessionInputCallback` を使ってください。 ### Tool error formatter -`toolErrorFormatter` を使うと、ツール呼び出しが拒否されたときにモデルへ返される承認拒否メッセージをカスタマイズできます。これにより、SDK のデフォルトメッセージではなく、ドメイン固有の文言（たとえばコンプライアンスガイダンス）を返せます。 +`toolErrorFormatter` を使うと、ツール呼び出しが拒否されたときにモデルへ返す承認拒否メッセージをカスタマイズできます。これにより、SDK のデフォルトメッセージの代わりに、ドメイン固有の文言（たとえばコンプライアンスガイダンス）を返せます。 -formatter は実行ごと（`runner.run(..., { toolErrorFormatter })`）にも、`RunConfig` 内でグローバル（`new Runner(...)` の `toolErrorFormatter`）にも設定できます。 +formatter は、実行単位（`runner.run(..., { toolErrorFormatter })`）または `RunConfig` 内でグローバル（`new Runner(...)` の `toolErrorFormatter`）に設定できます。 -この formatter は、承認拒否に対するグローバルなフォールバックです。特定の interruption を `result.state.reject(interruption, { message: '...' })` で拒否した場合、その呼び出し単位の `message` が `toolErrorFormatter` より優先されます。どちらも指定されていない場合、SDK はデフォルトの拒否テキスト `Tool execution was not approved.` にフォールバックします。 +この formatter は承認拒否に対するグローバルな fallback です。特定の interruption を `result.state.reject(interruption, { message: '...' })` で拒否した場合、その呼び出し単位の `message` が `toolErrorFormatter` より優先されます。どちらも指定されない場合、SDK はデフォルトの拒否テキスト `Tool execution was not approved.` を使います。 現在この formatter は `approval_rejected` イベントで実行され、次を受け取ります。 @@ -183,74 +187,73 @@ formatter は実行ごと（`runner.run(..., { toolErrorFormatter })`）にも - `toolType`（`'function'`、`'computer'`、`'shell'`、または `'apply_patch'`） - `toolName` - `callId` -- `defaultMessage`（SDK のフォールバックメッセージ。現在は `Tool execution was not approved.`） +- `defaultMessage`（SDK の fallback メッセージ。現在は `Tool execution was not approved.`） - `runContext` -メッセージを上書きするには文字列を返し、SDK のデフォルトを維持するには `undefined` を返します。formatter が例外をスローした場合（または文字列以外を返した場合）、SDK は警告をログに出し、デフォルトの承認拒否メッセージにフォールバックします。 +メッセージを上書きするには文字列を返し、SDK デフォルトを維持するには `undefined` を返します。formatter が例外をスローした場合（または文字列以外を返した場合）、SDK は警告をログ出力し、デフォルトの承認拒否メッセージにフォールバックします。 ### Reasoning item ID policy -`reasoningItemIdPolicy` を使うと、SDK が以前に生成された実行項目を後続のモデル入力用 `AgentInputItem[]` に戻すときに、reasoning item の `id` フィールドを保持するかどうかを制御できます。 +`reasoningItemIdPolicy` を使うと、SDK が以前に生成された実行項目を後続のモデル入力用 `AgentInputItem[]` に戻す際に、reasoning items が `id` フィールドを保持するかどうかを制御できます。 -これは、SDK が生成済みのモデル項目を入力として再利用する次のような箇所に影響します。 +これは、SDK が生成済みモデル項目を入力として再利用する次のような箇所に影響します。 - 同一実行内の後続モデル呼び出し（たとえばツール実行後） - 生成済み項目を入力 / 履歴として再利用する後続ターン -- 保存された `RunState` から再開された実行 -- `result.history` / `result.output` のような派生結果ビュー（モデル入力の形をした配列） - -- `'preserve'`（デフォルト）は reasoning item の ID を保持します -- `'omit'` は、入力として再送される前に reasoning item から `id` フィールドを削除します -- reasoning 以外の項目には影響しません +- 保存済み `RunState` から再開された実行 +- `result.history` / `result.output` のような派生 result view（モデル入力形式の配列） +- `'preserve'`（デフォルト）は reasoning-item ID を保持します +- `'omit'` は、入力として再送する前に reasoning items から `id` フィールドを取り除きます +- reasoning items 以外は影響を受けません -これによって **変更されない** もの: +この設定で **変わらない** ものは次のとおりです。 -- 元のモデル応答（`result.rawResponses`） +- 元 のモデルレスポンス（`result.rawResponses`） - 実行項目（`result.newItems`） -- provider から返されるモデルの現在ターン出力 +- provider が返す現在ターンのモデル出力 つまり、このポリシーは SDK が以前に生成された項目から **次の入力** を構築するときに適用されます。 -ポリシーは実行ごと（`runner.run(..., { reasoningItemIdPolicy: 'omit' })`）にも、runner のデフォルト（`new Runner({ reasoningItemIdPolicy: 'omit', ... })`）にも設定できます。保存された `RunState` から再開する場合、上書きしない限り以前に解決されたポリシーが再利用されます。 +ポリシーは実行単位（`runner.run(..., { reasoningItemIdPolicy: 'omit' })`）または runner のデフォルト（`new Runner({ reasoningItemIdPolicy: 'omit', ... })`）として設定できます。保存済み `RunState` から再開する場合、上書きしない限り、以前に解決されたポリシーが再利用されます。 #### `callModelInputFilter` との相互作用 -`reasoningItemIdPolicy` は `callModelInputFilter` の前に適用されます。カスタム動作が必要な場合でも、`callModelInputFilter` は準備済み入力を確認し、モデル呼び出し前に reasoning ID を手動で再導入または削除できます。 +`reasoningItemIdPolicy` は `callModelInputFilter` の前に適用されます。カスタム動作が必要な場合でも、`callModelInputFilter` で準備済み入力を確認し、モデル呼び出し前に reasoning ID を手動で再導入または削除できます。 -#### `'omit'` を使う場面 +#### `'omit'` を使うタイミング -再利用される reasoning item を ID なしで正規化したい場合（たとえば、転送 / 再生されるモデル入力をよりシンプルに保ちたい場合や、アプリのパイプラインにおける統合要件に合わせたい場合）は `'omit'` を使ってください。 +再送される reasoning items を ID なしで正規化したい場合（たとえば転送 / 再送されるモデル入力をより単純に保ちたい場合や、アプリのパイプラインにおける統合要件に合わせたい場合）は、`'omit'` を使ってください。 -また、バックエンド / provider が再利用される reasoning item をリクエスト検証エラーで拒否する場合の有効なトラブルシューティング手段にもなります（たとえば、後続入力中の reasoning item ID に関連する HTTP `400` エラー）。そのような場合は、`'omit'` で再利用される reasoning ID を削除することで、バックエンドが新しいリクエストでは無効と見なす ID の送信を避けられます。 +また、backend / provider が再送された reasoning items をリクエスト検証エラーで拒否する場合の有用なトラブルシューティング手段でもあります（たとえば、後続入力内の reasoning item ID に関連する HTTP `400` エラー）。そのような場合、`'omit'` で再送される reasoning ID を除去すれば、backend が新規リクエストでは無効とみなす ID を送らずに済みます。 -再利用入力でも reasoning item ID を引き継ぎたく、かつ統合先がそれを受け入れる場合は `'preserve'` を維持してください。 +SDK に replay された入力で reasoning-item ID を保持させたい、かつ統合先がそれを受け入れるなら、`'preserve'` を維持してください。 ## エラーと復旧 ### Error handlers -`errorHandlers` を使うと、サポートされているランタイムエラーをスローせずに最終出力へ変換できます。現在サポートされているのは `maxTurns` のみです。 +`errorHandlers` を使うと、サポートされている実行時エラーをスローせず最終出力に変換できます。現在サポートされているのは `maxTurns` のみです。 - `errorHandlers.maxTurns` は max-turn エラーのみを処理します -- `errorHandlers.default` はサポートされている種類に対するフォールバックとして使われます +- `errorHandlers.default` はサポートされている種類に対する fallback として使われます - ハンドラーは `{ error, context, runData }` を受け取り、`{ finalOutput, includeInHistory? }` を返せます ### 例外 -SDK は、catch できる少数のエラーをスローします。 +SDK は、catch 可能な少数のエラーをスローします。 - [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` に到達した - [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが無効な出力を生成した（例: 不正な JSON、未知のツール） - [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) – ガードレール違反 - [`ToolInputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/toolinputguardrailtripwiretriggered) / [`ToolOutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/tooloutputguardrailtripwiretriggered) – ツールガードレール違反 -- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールの完了に失敗した +- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールが完了できなかった - [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror) – 関数ツールが `timeoutMs` を超過し、`timeoutBehavior: 'raise_exception'` を使っていた -- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – タイムアウト以外のエラーで関数ツールの実行に失敗した -- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 設定またはユーザー入力に基づいてスローされる任意のエラー +- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 関数ツールの実行が timeout 以外のエラーで失敗した +- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 設定またはユーザー入力に基づいてスローされた任意のエラー -これらはすべて基底の `AgentsError` クラスを継承しており、現在の実行状態にアクセスするための `state` プロパティを提供する場合があります。 +これらはすべて基底クラス `AgentsError` を継承しており、現在の実行状態にアクセスするための `state` プロパティを持つ場合があります。 -以下は `GuardrailExecutionError` を処理するコード例です。入力ガードレールは最初のユーザー入力でしか実行されないため、この例では元の入力とコンテキストで実行を再開始します。また、保存済み状態を再利用して、モデルを再度呼び出さずに出力ガードレールを再試行する方法も示しています。 +以下は `GuardrailExecutionError` を処理するコード例です。input guardrails は最初のユーザー入力でしか実行されないため、この例では元の入力とコンテキストで実行を再開しています。また、保存済み state を再利用して、モデルを再度呼び出さずに output guardrails を再試行する方法も示しています。 + Sandbox agents はベータ版です。 API の詳細、デフォルト値、対応機能は + 正式提供前に変更される可能性があり、より高度な機能も 今後追加される予定です。 + + +モダンなエージェントは、ファイルシステム上の実際のファイルを操作できるときに最も効果的に機能します。 Agents SDK の **Sandbox Agents** は、モデルに永続的なワークスペースを提供し、そこでは大規模なドキュメント群の検索、ファイルの編集、コマンドの実行、成果物の生成、保存された sandbox state からの作業再開が可能です。 + +SDK は、ファイルのステージング、ファイルシステムツール、シェルアクセス、sandbox のライフサイクル、スナップショット、プロバイダー固有の接着コードを自分で組み合わせることなく、その実行ハーネスを提供します。 通常どおり `Agent` と `Runner` のフローを維持したまま、ワークスペース用の `Manifest`、sandbox ネイティブツール向けの capabilities、そして処理の実行場所を指定する `sandbox` 実行オプションを追加できます。 + +## 前提条件 + +- Node.js 22 以上 +- OpenAI Agents SDK の基本的な知識 +- sandbox client。 ローカル開発では、まず `UnixLocalSandboxClient` を使います + +## インストール + +まだ SDK をインストールしていない場合: + +```bash +npm install @openai/agents +``` + +Docker ベースの sandbox を使う場合は、ローカルに Docker をインストールし、`@openai/agents/sandbox/local` の `DockerSandboxClient` を使用します。 + +`tty: true` を指定したインタラクティブなローカル PTY セッションを使う場合、SDK を実行するプロセスでも `python3` として、または `OPENAI_AGENTS_PYTHON` 経由で Python 3 を利用できる必要があります。 PTY でないシェルコマンドでは Python は不要です。 + +## ローカル sandbox エージェントの作成 + +この例では、ローカルリポジトリを `repo/` 配下にステージし、ローカルスキルを遅延ロードし、実行時に runner が Unix ローカル sandbox セッションを作成できるようにします。 + + + +この例は意図的に Python SDK のクイックスタートに近い形にしてあります。 エージェント定義が manifest と capabilities を持ち、実行設定はこの実行で使う sandbox client を選ぶだけです。 + +## 主な選択肢 + +基本的な実行が動いたら、多くの人が次に選ぶのは次の項目です。 + +- `defaultManifest`: 新しい sandbox セッション向けのファイル、リポジトリ、ディレクトリ、マウント +- `instructions`: プロンプト全体に適用される短いワークフロールール +- `baseInstructions`: SDK の sandbox プロンプトを置き換えるための高度なエスケープハッチ +- `capabilities`: ファイルシステム編集 / 画像検査、シェル、スキル、メモリ、compact などの sandbox ネイティブツール +- `runAs`: モデル向けツールで使う sandbox ユーザー ID +- `sandbox.client`: sandbox バックエンド +- `sandbox.session`、`sandbox.sessionState`、または `sandbox.snapshot`: 後続の実行を以前の作業に再接続する方法 + +## 次のステップ + +- [Concepts](/openai-agents-js/guides/sandbox-agents/concepts): manifest、capabilities、権限、スナップショット、実行設定、構成パターンを理解します +- [Sandbox clients](/openai-agents-js/guides/sandbox-agents/clients): Unix ローカル、Docker、ホスト型プロバイダー、マウント戦略を選びます +- [Agent memory](/openai-agents-js/guides/sandbox-agents/memory): 以前の sandbox 実行から得た学びを保持し、再利用します + +シェルアクセスがときどき使う 1 つのツールにすぎない場合は、まず [ツール](/openai-agents-js/ja/guides/tools) ガイドの hosted shell から始めてください。 ワークスペースの分離、sandbox client の選択、または sandbox セッションの再開動作が設計の一部である場合に sandbox agents を選ぶとよいです。 diff --git a/docs/src/content/docs/ja/guides/tools.mdx b/docs/src/content/docs/ja/guides/tools.mdx index f3c1d297c..1bb5d1d4c 100644 --- a/docs/src/content/docs/ja/guides/tools.mdx +++ b/docs/src/content/docs/ja/guides/tools.mdx @@ -16,60 +16,64 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer import codexToolExample from '../../../../../../examples/docs/tools/codexTool.ts?raw'; import codexRunContextThreadExample from '../../../../../../examples/docs/tools/codexRunContextThread.ts?raw'; -ツールを使うと、Agent は **アクションの実行** ができます。たとえば、データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータ操作も可能です。 JavaScript / TypeScript SDK は 6 つのカテゴリーをサポートしています。 +ツールを使うと、エージェントは **アクションを実行** できます。たとえば、データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの操作も可能です。 JavaScript / TypeScript SDK では、7 つのカテゴリーをサポートしています。 -> どの agent にそのタスクを持たせるべきかが分かり、そこに機能を持たせたい段階になったら、このページを [エージェント](/openai-agents-js/guides/agents) の後に読んでください。委譲パターンをまだ検討中であれば、[エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) を参照してください。 +> どのエージェントがタスクを担うべきかがわかり、そのエージェントに機能を持たせたい場合は、まず [Agents](/openai-agents-js/guides/agents) を読んだうえでこのページを参照してください。委譲パターンをまだ検討中であれば、[Agent orchestration](/openai-agents-js/guides/multi-agent) を参照してください。 -1. **OpenAI がホストするツール** – OpenAI サーバー上でモデルと並行して実行されます。 _(Web 検索、ファイル検索、Code Interpreter、画像生成、tool search)_ -2. **組み込み実行ツール** – SDK が提供する、モデルの外側で実行されるツールです。 _(computer use と apply_patch はローカルで実行され、shell はローカルまたは Hosted コンテナで実行できます)_ -3. **関数ツール** – 任意のローカル関数を JSON schema でラップし、LLM が呼び出せるようにします。 -4. **Agents as tools** – Agent 全体を呼び出し可能なツールとして公開します。 -5. **MCP サーバー** – Model context protocol サーバー（ローカルまたはリモート）を接続します。 -6. **Experimental: Codex tool** – Codex SDK を関数ツールとしてラップし、workspace を認識したタスクを実行します。 +1. **OpenAI がホストするツール** – OpenAI のサーバー上でモデルと並行して実行されます。 _(Web 検索、ファイル検索、Code Interpreter、画像生成、tool search)_ +2. **組み込み実行ツール** – SDK が提供するツールで、モデルの外側で実行されます。 _(computer use と apply_patch はローカルで実行され、 shell はローカルまたはホストされたコンテナで実行できます)_ +3. **関数ツール** – 任意のローカル関数を JSON schema でラップし、LLM から呼び出せるようにします +4. **Agents as tools** – エージェント全体を呼び出し可能なツールとして公開します +5. **MCP サーバー** – Model Context Protocol サーバー（ローカルまたはリモート）を接続します +6. **Sandbox capabilities** – `SandboxAgent` に、ワークスペース単位の shell、filesystem、skills、memory、compaction ツールを追加します +7. **Experimental: Codex tool** – Codex SDK を関数ツールとしてラップし、ワークスペースを意識したタスクを実行します --- -## ツールカテゴリー +## ツールのカテゴリー このガイドの残りでは、まず各ツールカテゴリーを説明し、その後でツール選択とプロンプト設計に関する横断的な指針をまとめます。 -### 1. Hosted ツール（OpenAI Responses API） +### 1. Hosted tools (OpenAI Responses API) `OpenAIResponsesModel` を使う場合、次の組み込みツールを追加できます。 -| Tool | Type string | Purpose | +| ツール | 型文字列 | 用途 | | --- | --- | --- | | Web 検索 | `'web_search'` | インターネット検索 | -| ファイル / 検索 | `'file_search'` | OpenAI 上でホストされるベクトルストアにクエリを実行します | +| ファイル / 検索 | `'file_search'` | OpenAI 上でホストされるベクトルストアをクエリします | | Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行します | | 画像生成 | `'image_generation'` | テキストに基づいて画像を生成します | -| Tool search | `'tool_search'` | 遅延読み込みされた関数ツール、名前空間、または検索可能な MCP ツールを実行時に読み込みます | +| Tool search | `'tool_search'` | 遅延関数ツール、名前空間、または検索可能な MCP ツールを実行時に読み込みます | -SDK は Hosted ツール定義を返すヘルパー関数を提供しています。 +SDK には、ホスト型ツール定義を返すヘルパー関数が用意されています。 -| Helper function | Notes | +| ヘルパー関数 | メモ | | --- | --- | -| `webSearchTool(options?)` | `searchContextSize`、`userLocation`、`filters.allowedDomains` などの JS 向けオプション | -| `fileSearchTool(ids, options?)` | 最初の引数として 1 つ以上のベクトルストア ID を受け取り、`maxNumResults`、`includeSearchResults`、`rankingOptions`、フィルターなどのオプションも指定できます | -| `codeInterpreterTool(options?)` | `container` が指定されていない場合は、自動管理されるコンテナをデフォルトで使用します | -| `imageGenerationTool(options?)` | `model`、`size`、`quality`、`background`、`inputFidelity`、`inputImageMask`、`moderation`、`outputCompression`、`partialImages`、出力形式などの画像生成設定をサポートします | -| `toolSearchTool(options?)` | 組み込みの `tool_search` ヘルパーを追加します。`deferLoading: true` を設定した遅延関数ツールまたは Hosted MCP ツールと組み合わせて使います。デフォルトでは Hosted 実行をサポートし、`execution: 'client'` と `execute` を指定するとクライアント実行も可能です | +| `webSearchTool(options?)` | `searchContextSize`、`userLocation`、`filters.allowedDomains` などの JavaScript 向けオプション | +| `fileSearchTool(ids, options?)` | 最初の引数に 1 つ以上のベクトルストア ID を受け取り、`maxNumResults`、`includeSearchResults`、`rankingOptions`、filters などのオプションも指定可能 | +| `codeInterpreterTool(options?)` | `container` を指定しない場合は、自動管理コンテナがデフォルトになります | +| `imageGenerationTool(options?)` | `model`、`size`、`quality`、`background`、`inputFidelity`、`inputImageMask`、`moderation`、`outputCompression`、`partialImages`、出力形式などの画像生成設定をサポート | +| `toolSearchTool(options?)` | 組み込みの `tool_search` ヘルパーを追加します。 `deferLoading: true` を設定した遅延関数ツールまたはホスト型 MCP ツールと組み合わせて使います。デフォルトではホスト実行をサポートし、`execution: 'client'` と `execute` を併用するとクライアント実行も可能です | -これらのヘルパーは、JavaScript / TypeScript 向けのオプション名を、基盤となる OpenAI Responses API のツールペイロードにマッピングします。完全なツール schema や、ranking options や semantic filters といった高度なオプションについては、公式の [OpenAI tools guide](https://developers.openai.com/api/docs/guides/tools) を参照してください。現在の組み込み tool-search フローと対応モデルについては、公式の [Tool search guide](https://developers.openai.com/api/docs/guides/tools-tool-search) を参照してください。 +これらのヘルパーは、JavaScript / TypeScript 向けのオプション名を、基盤となる OpenAI Responses API のツールペイロードにマッピングします。完全なツール schema や、ranking options・semantic filters などの高度なオプションについては公式の [OpenAI tools guide](https://developers.openai.com/api/docs/guides/tools) を参照してください。現在の組み込み tool-search フローや利用可能なモデルについては、公式の [Tool search guide](https://developers.openai.com/api/docs/guides/tools-tool-search) を参照してください。 --- ### 2. 組み込み実行ツール -これらのツールは SDK に組み込まれていますが、実行はモデルのレスポンス自体の外側で行われます。 +これらのツールは SDK に組み込まれていますが、実行はモデル応答自体の外側で行われます。 -- **コンピュータ操作** – `Computer` インターフェースを実装し、それを `computerTool()` に渡します。これは常に、あなたが提供するローカルの `Computer` 実装に対して実行されます -- **Shell** – ローカルの `Shell` 実装を提供するか、`shellTool({ environment })` で Hosted コンテナ環境を設定します -- **Apply patch** – `Editor` インターフェースを実装し、それを `applyPatchTool()` に渡します。これは常に、あなたが提供するローカルの `Editor` 実装に対して実行されます +- **コンピュータ操作** – `Computer` インターフェースを実装し、`computerTool()` に渡します。これは常に、あなたが提供するローカル `Computer` 実装に対して実行されます +- **Shell** – ローカルの `Shell` 実装を渡すか、`shellTool({ environment })` でホスト型コンテナ環境を設定します +- **Apply patch** – `Editor` インターフェースを実装し、`applyPatchTool()` に渡します。これは常に、あなたが提供するローカル `Editor` 実装に対して実行されます +- **Sandbox shell / filesystem ツール** – アクションをサンドボックスワークスペース内で実行したい場合は、`SandboxAgent` 上で `shell()`、`filesystem()`、`skills()`、`memory()`、`compaction()` を使います -ツール呼び出し自体は引き続きモデルによって要求されますが、実際の作業はあなたのアプリケーション、または設定済みの実行環境が行います。 +ツール呼び出し自体は引き続きモデルによって要求されますが、実際の処理はアプリケーションまたは設定された実行環境が行います。 + +Sandbox capability ツールは、プロセス全体で使う組み込みツールとは異なります。これらは現在の `SandboxAgent` 実行のライブなサンドボックスセッションに結び付けられています。ツールをアプリケーションプロセスではなくエージェントの分離されたワークスペース上で動作させたい場合は、[Sandbox agents](/openai-agents-js/guides/sandbox-agents) を使ってください。 -#### Computer ツールの詳細 +#### コンピュータツールの詳細 -`computerTool()` は以下のいずれかを受け取ります。 +`computerTool()` は次のいずれかを受け取ります。 - 具体的な `Computer` インスタンス -- 実行ごとに `Computer` を作成する initializer 関数 +- 実行ごとに `Computer` を生成する初期化関数 - 実行スコープのセットアップとクリーンアップが必要な場合の `{ create, dispose }` を持つ provider オブジェクト -OpenAI の現在の computer-use パスを使うには、[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) などの computer 対応モデルを設定してください。リクエストモデルが明示的な場合、SDK は GA の組み込み `computer` ツール形式を送信します。一方、有効なモデルが保存済みプロンプトや他の古い統合から来ている場合、明示的に `modelSettings.toolChoice: 'computer'` で GA パスを選ばない限り、SDK は互換性のために従来の `computer_use_preview` wire 形式を維持します。 +OpenAI の現在のコンピュータ操作パスを使うには、[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) のようなコンピュータ対応モデルを設定してください。リクエストモデルが明示されている場合、SDK は GA の組み込み `computer` ツール形式を送信します。実効モデルが保存済みプロンプトや別の古い統合から来ている場合は、`modelSettings.toolChoice: 'computer'` で明示的に GA パスを選ばない限り、互換性のため従来の `computer_use_preview` ワイヤー形式を維持します。 -GA の computer 呼び出しには、単一の `computer_call` 内にバッチ化された `actions[]` を含めることができます。SDK はそれらを順番に実行し、各アクションに対して `needsApproval` を評価し、最終的なスクリーンショットをツール出力として返します。`interruption.rawItem` から承認 UI を構築する場合は、存在すれば `actions` を読み、従来の preview 項目に対しては `action` にフォールバックしてください。 +GA の computer 呼び出しには、1 つの `computer_call` に複数の `actions[]` が含まれる場合があります。SDK はそれらを順に実行し、各アクションに対して `needsApproval` を評価し、最終スクリーンショットをツール出力として返します。`interruption.rawItem` から承認 UI を構築する場合、`actions` があればそれを読み、従来 preview 項目用には `action` にフォールバックしてください。 -影響の大きい computer アクションをユーザー確認で一時停止したい場合は `needsApproval` を使い、computer 呼び出しに対して報告された保留中の safety checks を承認または拒否したい場合は `onSafetyCheck` を使います。モデル側のガイダンスと移行の詳細については、公式の [OpenAI computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use/) と、その [migration note](https://developers.openai.com/api/docs/guides/tools-computer-use/#migration-from-computer-use-preview) を参照してください。 +影響の大きいコンピュータ操作をユーザー確認のために一時停止したい場合は `needsApproval` を使います。computer 呼び出しに対して報告される保留中の安全性チェックを承認または拒否したい場合は `onSafetyCheck` を使います。モデル側のガイダンスと移行の詳細は、公式の [OpenAI computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use/) とその [migration note](https://developers.openai.com/api/docs/guides/tools-computer-use/#migration-from-computer-use-preview) を参照してください。 #### Shell ツールの詳細 `shellTool()` には 2 つのモードがあります。 -- ローカルモード: `shell` を指定し、必要に応じて `environment: { type: 'local', skills }` に加えて、自動承認処理のための `needsApproval` と `onApproval` を指定します -- Hosted コンテナモード: `type: 'container_auto'` または `type: 'container_reference'` を持つ `environment` を指定します +- ローカルモード: `shell` を渡し、必要に応じて `environment: { type: 'local', skills }`、および自動承認処理用の `needsApproval` と `onApproval` を指定します +- ホスト型コンテナモード: `type: 'container_auto'` または `type: 'container_reference'` を含む `environment` を渡します -ローカルモードでは、`environment.skills` によって、`name`、`description`、ファイルシステム上の `path` でローカル skill をマウントできます。 +ローカルモードでは、`environment.skills` により、`name`、`description`、filesystem の `path` でローカル skills をマウントできます。 -Hosted コンテナモードでは、以下のいずれかで `shellTool({ environment })` を設定します。 +ホスト型コンテナモードでは、`shellTool({ environment })` を次のいずれかで設定します。 -- 実行用の管理コンテナを作成する `type: 'container_auto'` -- `containerId` で既存コンテナを再利用する `type: 'container_reference'` +- `type: 'container_auto'` で、その実行用の管理コンテナを作成する +- `type: 'container_reference'` で、`containerId` によって既存コンテナを再利用する -Hosted の `container_auto` 環境は以下をサポートします。 +ホスト型の `container_auto` 環境では以下をサポートします。 - `domainSecrets` を含む allowlist を含めた `networkPolicy` - アップロード済みファイルをマウントするための `fileIds` - コンテナサイズ指定のための `memoryLimit` - `skill_reference` またはインライン zip バンドルによる `skills` -Hosted shell 環境では、実行がローカルプロセスではなく Hosted コンテナ環境で行われるため、`shell`、`needsApproval`、`onApproval` は受け付けません。 +ホスト型 shell 環境では、実行がローカルプロセスではなくホスト型コンテナ環境で行われるため、`shell`、`needsApproval`、`onApproval` は受け付けません。 -エンドツーエンドの使用例は、`examples/tools/local-shell.ts`、`examples/tools/container-shell-skill-ref.ts`、`examples/tools/container-shell-inline-skill.ts` を参照してください。 +エンドツーエンドの使い方については、`examples/tools/local-shell.ts`、`examples/tools/container-shell-skill-ref.ts`、`examples/tools/container-shell-inline-skill.ts` を参照してください。 #### Apply-patch ツールの詳細 -`applyPatchTool()` は、`shellTool()` のローカル承認フローを踏襲しています。ファイル編集の前に一時停止したい場合は `needsApproval` を使い、アプリレベルのコールバックで自動承認または拒否したい場合は `onApproval` を使います。 +`applyPatchTool()` は `shellTool()` のローカル承認フローを踏襲します。ファイル編集前に一時停止するには `needsApproval` を使い、自動承認または拒否のためにアプリレベルのコールバックが必要な場合は `onApproval` を使います。 --- ### 3. 関数ツール -`tool()` ヘルパーを使うと、**任意の** 関数をツールに変換できます。 +`tool()` ヘルパーを使うと、**任意の** 関数をツールにできます。 string \| unknown \| Promise<...>` – あなたのビジネスロジック。文字列以外の出力はモデル向けにシリアライズされます。`context` は省略可能な `RunContext` で、`details` には `toolCall`、`resumeState`、`signal` などのメタデータが含まれます | -| `errorFunction` | No | 内部エラーをユーザー向け文字列に変換するカスタムハンドラー `(context, error) => string` | -| `timeoutMs` | No | 呼び出しごとのタイムアウト（ミリ秒）。0 より大きく、`2147483647` 以下である必要があります | -| `timeoutBehavior` | No | タイムアウトモード: `error_as_result`（デフォルト）はモデルに見えるタイムアウトメッセージを返し、`raise_exception` は `ToolTimeoutError` を投げます | -| `timeoutErrorFunction` | No | `timeoutBehavior` が `error_as_result` のときのタイムアウト出力用カスタムハンドラー `(context, timeoutError) => string` | -| `needsApproval` | No | 実行前に人間の承認を要求します。[人間の介入（HITL）](/openai-agents-js/guides/human-in-the-loop) を参照してください | -| `isEnabled` | No | 実行ごとにツールを条件付きで公開します。真偽値または predicate を受け付けます | -| `inputGuardrails` | No | ツール実行前に動作するガードレール。拒否または例外送出が可能です。[ガードレール](/openai-agents-js/guides/guardrails#tool-guardrails) を参照してください | -| `outputGuardrails` | No | ツール実行後に動作するガードレール。拒否または例外送出が可能です。[ガードレール](/openai-agents-js/guides/guardrails#tool-guardrails) を参照してください | +| `name` | いいえ | デフォルトは関数名（例: `get_weather`）です | +| `description` | はい | LLM に表示される、明確で人が読める説明 | +| `parameters` | はい | Zod schema または生の JSON schema オブジェクトのいずれか。Zod parameters は自動的に **strict** モードを有効にします | +| `strict` | いいえ | `true`（デフォルト）の場合、引数の検証に失敗すると SDK はモデルエラーを返します。あいまい一致を許可するには `false` にします | +| `execute` | はい | `(args, context, details) => string \| unknown \| Promise<...>` – あなたのビジネスロジックです。文字列以外の出力はモデル向けにシリアライズされます。`context` は省略可能な `RunContext`、`details` には `toolCall`、`resumeState`、`signal` などのメタデータが含まれます | +| `errorFunction` | いいえ | 内部エラーをユーザーに見える文字列へ変換するカスタムハンドラー `(context, error) => string` | +| `timeoutMs` | いいえ | 呼び出し単位のタイムアウト（ミリ秒）。0 より大きく、`2147483647` 以下である必要があります | +| `timeoutBehavior` | いいえ | タイムアウトモード: `error_as_result`（デフォルト）はモデルに見えるタイムアウトメッセージを返し、`raise_exception` は `ToolTimeoutError` を送出します | +| `timeoutErrorFunction` | いいえ | `timeoutBehavior` が `error_as_result` のときにタイムアウト出力を生成するカスタムハンドラー `(context, timeoutError) => string` | +| `needsApproval` | いいえ | 実行前に人間の承認を要求します。[human-in-the-loop guide](/openai-agents-js/guides/human-in-the-loop) を参照してください | +| `isEnabled` | いいえ | 実行ごとにツールを条件付きで公開します。真偽値または述語を受け付けます | +| `inputGuardrails` | いいえ | ツール実行前に走るガードレール。拒否または例外送出が可能です。[Guardrails](/openai-agents-js/guides/guardrails#tool-guardrails) を参照してください | +| `outputGuardrails` | いいえ | ツール実行後に走るガードレール。拒否または例外送出が可能です。[Guardrails](/openai-agents-js/guides/guardrails#tool-guardrails) を参照してください | #### 関数ツールのタイムアウト 各関数ツール呼び出しの上限時間を設定するには `timeoutMs` を使います。 - `timeoutBehavior: 'error_as_result'`（デフォルト）は、`Tool '' timed out after ms.` をモデルに返します -- `timeoutBehavior: 'raise_exception'` は [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror) を投げます。これは [エージェントの実行](/openai-agents-js/guides/running-agents#exceptions) における実行例外の一部として捕捉できます -- `timeoutErrorFunction` を使うと、`error_as_result` モードでタイムアウト文言をカスタマイズできます -- タイムアウト時には `details.signal` が中断されるため、長時間実行するツールもキャンセルを監視していればすぐに停止できます +- `timeoutBehavior: 'raise_exception'` は [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror) を送出し、[run exceptions](/openai-agents-js/guides/running-agents#exceptions) の一部としてキャッチできます +- `timeoutErrorFunction` を使うと、`error_as_result` モードのタイムアウト文言をカスタマイズできます +- タイムアウト時には `details.signal` が中断されるため、長時間動くツールもキャンセルを監視していればすぐ停止できます -関数ツールを直接呼び出す場合は、通常の agent 実行と同じタイムアウト動作を適用するために [`invokeFunctionTool`](/openai-agents-js/openai/agents/functions/invokefunctiontool) を使ってください。 +関数ツールを直接呼び出す場合は、[`invokeFunctionTool`](/openai-agents-js/openai/agents/functions/invokefunctiontool) を使うことで、通常のエージェント実行と同じタイムアウト動作を強制できます。 #### Non‑strict JSON‑schema ツール -無効または部分的な入力をモデルに _推測_ させたい場合は、生の JSON schema を使う際に strict モードを無効にできます。 +無効または部分的な入力をモデルに _推測_ させたい場合は、生の JSON schema を使う際に strict モードを無効化できます。 -この例では意図的に両方のスタイルを混在させています。 +この例では、意図的に両方のスタイルを混在させています。 -- `shippingLookup` は、単独で検索可能な 1 つの機能であるためトップレベルのままです +- `shippingLookup` は、単独の検索可能機能であるためトップレベルのままにしています - `crmTools` は、関連する CRM ツールが 1 つの上位ラベルと説明を共有するため `toolNamespace()` を使っています -- 同じリクエスト内で名前空間付きとトップレベルの遅延ツールを混在させることはサポートされています。tool search は `crm` のような名前空間パスと `get_shipping_eta` のようなトップレベルパスの両方を読み込めます +- 同一リクエスト内で名前空間付きとトップレベルの遅延ツールを混在させることは可能です。tool search は `crm` のような名前空間パスと、`get_shipping_eta` のようなトップレベルパスの両方を読み込めます -Tool search を使う場合は、以下に注意してください。 +Tool search を使うときは、次の点に注意してください。 - 各遅延関数ツールに `deferLoading: true` を設定する - 複数の関連ツールが 1 つのドメイン説明を共有し、グループとして読み込まれるべき場合は `toolNamespace({ name, description, tools })` を使う -- 単独の独立した機能であり、ツール名自体が良い検索対象になる場合はトップレベルのままにする -- 遅延関数ツールまたは Hosted MCP ツールのいずれかが `deferLoading: true` を使う場合は、同じ `tools` 配列に `toolSearchTool()` を追加する -- `modelSettings.toolChoice` は `'auto'` のままにする。SDK は組み込み `tool_search` ツールや、名前指定された遅延関数ツールの強制を拒否します -- Hosted 実行がデフォルトです。`toolSearchTool({ execution: 'client', execute })` を設定した場合、標準の `run()` ループがサポートするのは組み込みの `{ paths: string[] }` クライアントクエリ形式のみであり、カスタムのクライアント側 schema を使うには独自の Responses ループが必要です -- 名前空間には即時メンバーと遅延メンバーを混在させられます。即時メンバーは tool search なしでも呼び出し可能であり、同じ名前空間内の遅延メンバーは必要時に読み込まれます -- 遅延関数ツールと `toolNamespace()` は Responses 専用です。Chat Completions では拒否され、AI SDK アダプターも遅延 Responses ツール読み込みフローをサポートしていません +- 単一の独立した機能であり、ツール名自体が適切な検索対象になる場合はトップレベルのままにする +- いずれかの遅延関数ツールまたはホスト型 MCP ツールが `deferLoading: true` を使う場合は、同じ `tools` 配列に `toolSearchTool()` を追加する +- `modelSettings.toolChoice` は `'auto'` のままにする。SDK は組み込み `tool_search` ツールや遅延関数ツールを名前で強制することを拒否します +- デフォルトはホスト実行です。`toolSearchTool({ execution: 'client', execute })` を設定した場合、標準の `run()` ループは組み込みの `{ paths: string[] }` というクライアントクエリ形式のみをサポートします。独自のクライアント側 schema には独自の Responses ループが必要です +- 1 つの名前空間に即時メンバーと遅延メンバーを混在させることができます。即時メンバーは tool search なしで呼び出し可能なままであり、同じ名前空間内の遅延メンバーは必要時に読み込まれます +- 遅延関数ツールと `toolNamespace()` は Responses 専用です。Chat Completions はこれらを拒否し、AI SDK adapter は遅延 Responses ツール読み込みフローをサポートしません --- ### 4. Agents as tools -会話を完全に handoff せずに、ある Agent に別の Agent を _補助_ させたいことがあります。その場合は `agent.asTool()` を使います。 +会話を完全にハンドオフせずに、あるエージェントが別のエージェントを _支援_ するようにしたい場合があります。その場合は `agent.asTool()` を使います。 -`agent.asTool()` と `handoff()` のどちらを使うべきかをまだ検討中なら、[エージェント](/openai-agents-js/guides/agents#composition-patterns) と [エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) のパターン比較を参照してください。 +`agent.asTool()` と `handoff()` のどちらを使うべきかまだ判断中であれば、[Agents guide](/openai-agents-js/guides/agents#composition-patterns) と [Agent orchestration](/openai-agents-js/guides/multi-agent) のパターン比較を参照してください。 -SDK は内部で次のことを行います。 +内部的には SDK は次のことを行います。 -- 単一の `input` パラメーターを持つ関数ツールを作成する -- ツールが呼び出されたときに、その入力で sub‑agent を実行する -- 最後のメッセージ、または `customOutputExtractor` によって抽出された出力を返す +- 単一の `input` パラメーターを持つ関数ツールを作成します +- ツールが呼び出されたときに、その入力でサブエージェントを実行します +- 最後のメッセージ、または `customOutputExtractor` によって抽出された出力を返します -agent をツールとして実行すると、Agents SDK はデフォルト設定で runner を作成し、関数実行の中でその runner により agent を実行します。`runConfig` や `runOptions` のプロパティを渡したい場合は、それらを `asTool()` メソッドに渡して runner の動作をカスタマイズできます。 +エージェントをツールとして実行すると、Agents SDK はデフォルト設定で runner を作成し、関数実行内でその runner を使ってエージェントを実行します。`runConfig` や `runOptions` の各種プロパティを渡したい場合は、`asTool()` メソッドに渡して runner の挙動をカスタマイズできます。 -また、`asTool()` オプションで agent tool に `needsApproval` と `isEnabled` を設定することで、人間の介入フローや条件付きツール公開と統合することもできます。 +`asTool()` オプションで、エージェントツールに `needsApproval` と `isEnabled` を設定することもでき、Human in the loop (人間の介入) フローや条件付きツール可用性と統合できます。 -`customOutputExtractor` の内部では、`result.agentToolInvocation` を使って現在の `Agent.asTool()` 呼び出しを確認できます。このコールバックでは結果は常に `Agent.asTool()` 由来なので、`agentToolInvocation` は常に定義されており、`toolName`、`toolCallId`、`toolArguments` を参照できます。通常のアプリコンテキストと `toolInput` には `result.runContext` を使ってください。このメタデータは現在のネストされた呼び出しスコープに限定されており、`RunState` にシリアライズされません。 +`customOutputExtractor` の内部では、`result.agentToolInvocation` を使って現在の `Agent.asTool()` 呼び出しを確認できます。このコールバックでは結果は常に `Agent.asTool()` から来るため、`agentToolInvocation` は常に定義されており、`toolName`、`toolCallId`、`toolArguments` を公開します。通常のアプリコンテキストと `toolInput` には `result.runContext` を使ってください。このメタデータは現在のネストされた呼び出しに限定されており、`RunState` にシリアライズされません。 -`agent.asTool()` の高度な structured-input オプション: +`agent.asTool()` の高度な構造化入力オプション: -- `inputBuilder`: 構造化されたツール引数を、ネストされた agent 入力ペイロードにマッピングします -- `includeInputSchema`: より強い schema 認識動作のために、ネストされた実行に入力 JSON schema を含めます -- `resumeState`: ネストされたシリアライズ済み `RunState` を再開する際のコンテキスト統合戦略を制御します。`'merge'`（デフォルト）は live の承認 / コンテキスト状態をシリアライズ済み状態にマージし、`'replace'` は代わりに現在の実行コンテキストを使い、`'preferSerialized'` はシリアライズ済みコンテキストを変更せずそのまま再開します +- `inputBuilder`: 構造化されたツール引数を、ネストされたエージェント入力ペイロードへマッピングします +- `includeInputSchema`: より強い schema-aware な振る舞いのために、入力 JSON schema をネスト実行に含めます +- `resumeState`: ネストされたシリアライズ済み `RunState` を再開する際のコンテキスト統合戦略を制御します。`'merge'`（デフォルト）はライブの承認 / コンテキスト状態をシリアライズ済み状態にマージし、`'replace'` は代わりに現在の実行コンテキストを使い、`'preferSerialized'` はシリアライズ済みコンテキストを変更せずに再開します -#### Agent ツールからのストリーミングイベント +#### エージェントツールからのストリーミングイベント -Agent ツールは、ネストされた実行イベントをすべてアプリにストリーミングで返せます。ツールの構築方法に応じて、適したフックスタイルを選んでください。 +エージェントツールは、ネストされた実行イベントをすべてアプリへストリーミングできます。ツールの構築方法に応じて適したフックスタイルを選んでください。 -- イベントタイプは `RunStreamEvent['type']` に一致します: `raw_model_stream_event`、`run_item_stream_event`、`agent_updated_stream_event` -- `onStream` は最もシンプルな「全件受け取り」であり、ツールをインライン宣言する場合（`tools: [agent.asTool({ onStream })]`）に適しています。イベントごとの振り分けが不要ならこれを使ってください -- `on(eventName, handler)` は選択的に（または `'*'` で）購読でき、より細かい処理が必要な場合や作成後にリスナーを追加したい場合に適しています -- `onStream` またはいずれかの `on(...)` ハンドラーを指定すると、agent-as-tool は自動的にストリーミングモードで実行されます。指定しない場合は非ストリーミング経路のままです +- イベント型は `RunStreamEvent['type']` に一致します: `raw_model_stream_event`、`run_item_stream_event`、`agent_updated_stream_event` +- `onStream` は最も単純な「すべて受け取る」方法で、ツールをインラインで宣言する場合（`tools: [agent.asTool({ onStream })]`）に適しています。イベントごとの振り分けが不要ならこれを使ってください +- `on(eventName, handler)` を使うと、選択的に（または `'*'` で）購読でき、より細かい処理が必要な場合や作成後にリスナーを付けたい場合に向いています +- `onStream` またはいずれかの `on(...)` ハンドラーを指定すると、agent-as-tool は自動的にストリーミングモードで実行されます。これらがなければ非ストリーミング経路のままです - ハンドラーは並列に呼び出されるため、遅い `onStream` コールバックが `on(...)` ハンドラーをブロックすることはありません（逆も同様です） -- `toolCallId` は、モデルのツール呼び出し経由でツールが実行された場合に提供されます。直接の `invoke()` 呼び出しや provider 側の挙動によっては省略されることがあります +- `toolCallId` は、ツールがモデルのツール呼び出し経由で起動された場合に提供されます。直接の `invoke()` 呼び出しや provider の挙動によっては省略されることがあります --- ### 5. MCP サーバー -[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) サーバーを通じてツールを公開し、それを agent に接続できます。たとえば、`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/guides/mcp) を参照してください。複数サーバーを管理する場合（または部分的な失敗がある場合）は、`connectMcpServers` と [MCP 連携](/openai-agents-js/guides/mcp#managing-mcp-server-lifecycle) のライフサイクル指針を使ってください。 +完全な例については [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) を参照してください。また、MCP サーバーツール統合の包括的なガイドを探している場合は、詳細について [MCP guide](/openai-agents-js/guides/mcp) を参照してください。複数サーバーを管理する場合（または部分的な障害がある場合）は、`connectMcpServers` と [MCP guide](/openai-agents-js/guides/mcp#managing-mcp-server-lifecycle) のライフサイクル指針を使ってください。 --- ### 6. Experimental: Codex tool -`@openai/agents-extensions/experimental/codex` は `codexTool()` を提供します。これはモデルのツール呼び出しを Codex SDK にルーティングする関数ツールで、agent が workspace スコープのタスク（shell、ファイル編集、MCP ツール）を自律的に実行できるようにします。この機能は experimental であり、変更される可能性があります。 +`@openai/agents-extensions/experimental/codex` は `codexTool()` を提供します。これは関数ツールで、モデルのツール呼び出しを Codex SDK にルーティングし、エージェントがワークスペース単位のタスク（shell、ファイル編集、MCP ツール）を自律的に実行できるようにします。このインターフェースは実験的であり、変更される可能性があります。 まず依存関係をインストールします。 @@ -284,18 +288,18 @@ npm install @openai/agents-extensions @openai/codex-sdk 知っておくべきこと: - 認証: `CODEX_API_KEY`（推奨）または `OPENAI_API_KEY` を指定するか、`codexOptions.apiKey` を渡します -- 入力: strict schema です。`inputs` には少なくとも 1 つの `{ type: 'text', text }` または `{ type: 'local_image', path }` を含める必要があります -- 安全性: `sandboxMode` と `workingDirectory` を組み合わせて使います。ディレクトリが Git リポジトリでない場合は `skipGitRepoCheck` を設定してください -- スレッド管理: `useRunContextThreadId: true` は最新の thread id を `runContext.context` に読み書きします。これはアプリ状態でのターン間再利用に便利です -- Thread ID の優先順位: ツール呼び出しの `threadId`（schema に含まれている場合）が最優先で、その次に run-context の thread id、最後に `codexTool({ threadId })` です -- Run context キー: `name: 'codex'` の場合はデフォルトで `codexThreadId`、`name: 'engineer'` のような名前では `codexThreadId_`（正規化後は `codex_engineer`）です -- 可変コンテキスト要件: `useRunContextThreadId` を有効にする場合、`run(..., { context })` には可変オブジェクトまたは `Map` を渡してください -- 命名: ツール名は `codex` 名前空間に正規化されます（`engineer` は `codex_engineer` になります）。また、同一 agent 内で重複する Codex ツール名は拒否されます -- ストリーミング: `onStream` は Codex イベント（reasoning、コマンド実行、MCP ツール呼び出し、ファイル変更、Web 検索）を反映するため、進行状況のログ出力やトレースが可能です +- 入力: strict schema — `inputs` には少なくとも 1 つの `{ type: 'text', text }` または `{ type: 'local_image', path }` を含める必要があります +- 安全性: `sandboxMode` と `workingDirectory` を組み合わせて使います。ディレクトリが Git リポジトリでない場合は `skipGitRepoCheck` を設定します +- スレッド管理: `useRunContextThreadId: true` は最新の thread id を `runContext.context` に読み書きし、アプリ状態でターンをまたいで再利用するのに役立ちます +- Thread ID の優先順位: ツール呼び出しの `threadId`（schema に含まれている場合）が最優先され、次に run-context の thread id、その次に `codexTool({ threadId })` が使われます +- Run context キー: `name: 'codex'` の場合のデフォルトは `codexThreadId`、`name: 'engineer'` のような名前では `codexThreadId_` です（正規化後は `codex_engineer`） +- 可変コンテキスト要件: `useRunContextThreadId` が有効な場合は、`run(..., { context })` に可変オブジェクトまたは `Map` を渡してください +- 命名: ツール名は `codex` 名前空間内に正規化されます（`engineer` は `codex_engineer` になります）。また、1 つのエージェント内で重複する Codex ツール名は拒否されます +- ストリーミング: `onStream` は Codex イベント（reasoning、コマンド実行、MCP ツール呼び出し、ファイル変更、Web 検索）を反映するため、進捗をログまたはトレースできます - 出力: ツール結果には `response`、`usage`、`threadId` が含まれ、Codex のトークン使用量は `RunContext` に記録されます -- 構造: `outputSchema` には descriptor、JSON schema オブジェクト、または Zod オブジェクトを使えます。JSON object schema では `additionalProperties` は `false` である必要があります +- 構造: `outputSchema` には descriptor、JSON schema オブジェクト、または Zod オブジェクトを使えます。JSON object schema の場合、`additionalProperties` は `false` である必要があります -run-context の thread 再利用例: +Run-context のスレッド再利用例: OpenAI Agents SDK - 少数の基本コンポーネントで、テキストおよび音声エージェントを構築します。 + 少数の基本コンポーネントで、sandbox・テキスト・音声エージェントを構築できます。 はじめる ## 概要 -[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 には、ごく少数の基本コンポーネントがあります。 +[TypeScript 向け OpenAI Agents SDK](https://github.com/openai/openai-agents-js) を使うと、ごく少ない抽象化で、軽量かつ使いやすいパッケージによって agentic AI アプリを構築できます。これは、以前のエージェント向け実験的プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) を本番利用向けに強化したもので、[Python 版](https://github.com/openai/openai-agents-python) も利用できます。Agents SDK には、ごく少数の基本コンポーネントがあります。 - **エージェント**: instructions と tools を備えた LLM -- **Agents as tools / ハンドオフ**: 特定のタスクをほかのエージェントに委譲できる仕組み +- **Sandbox エージェント**: エージェントを分離されたファイルシステムワークスペース、シェルコマンド、ファイル編集、スナップショット、sandbox セッション状態と組み合わせたもの +- **Agents as tools / ハンドオフ**: エージェントが特定のタスクをほかのエージェントに委任できる仕組み - **ガードレール**: エージェントへの入力を検証できる仕組み -TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェントの複雑な関係を表現するのに十分な力を発揮し、学習コストを大きくかけずに実用的なアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が用意されており、エージェントフローの可視化やデバッグに加え、評価や、アプリケーション向けのモデルのファインチューニングまで行えます。 +これらの基本コンポーネントを TypeScript と組み合わせることで、ツールとエージェントの複雑な関係を表現でき、必要なときにはエージェントに実際のワークスペースを与えつつ、急な学習コストなしで実用的なアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、agentic なフローを可視化・デバッグできるほか、評価の実行や、アプリケーション向けのモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 -SDK には、次の 2 つの設計原則があります。 +この SDK には、2 つの中核となる設計原則があります。 -1. 使う価値があるだけの十分な機能を備えつつ、すばやく学べるよう基本コンポーネントは少なくする -2. そのままですぐに使えて、しかも動作を必要なだけ正確にカスタマイズできる +1. 使う価値があるだけの十分な機能を備えつつ、学習を素早く始められるよう基本コンポーネント数は少なくすること +2. そのままですぐに優れた動作をしつつ、何が起きるかを正確にカスタマイズできること SDK の主な機能は次のとおりです。 - **エージェントループ**: ツール呼び出しを処理し、結果を LLM に返し、タスク完了まで継続する組み込みのエージェントループ -- **TypeScript ファースト**: 新しい抽象化を学ぶことなく、TypeScript 本来の言語機能でエージェントをオーケストレーションし、連結できます -- **Agents as tools / ハンドオフ**: 複数のエージェント間で作業を調整し委譲するための強力な仕組み -- **ガードレール**: 入力検証と安全性チェックをエージェント実行と並行して実行し、チェックを通過しない場合は即座に失敗させます -- **関数ツール**: 任意の TypeScript 関数を、自動スキーマ生成と Zod ベースの検証付きツールに変換します -- **MCP サーバーツール呼び出し**: 関数ツールと同じ方法で使える、組み込みの MCP サーバーツール連携 -- **セッション**: エージェントループ内で作業コンテキストを維持するための永続的なメモリレイヤー -- **Human in the loop (人間の介入)**: エージェント実行全体で人間を関与させるための組み込みメカニズム -- **トレーシング**: ワークフローの可視化、デバッグ、監視のための組み込みトレーシング。OpenAI の評価、ファインチューニング、蒸留ツール群にも対応しています -- **リアルタイムエージェント**: 自動割り込み検出、コンテキスト管理、ガードレールなどの機能を備えた強力な音声エージェントを構築できます +- **Sandbox 実行**: 作業にワークスペースが必要な場合に、分離されたファイルシステムワークスペース、シェルコマンド、ファイル編集、スナップショット、sandbox セッション状態を使ってエージェントを実行 +- **TypeScript ファースト**: 新しい抽象化を学ばなくても、TypeScript のネイティブな言語機能でエージェントをオーケストレーションし、連結可能 +- **Agents as tools / ハンドオフ**: 複数のエージェント間で作業を調整・委任するための強力な仕組み +- **ガードレール**: 入力検証と安全性チェックをエージェント実行と並行して行い、チェック不合格時には早期に失敗 +- **関数ツール**: 自動スキーマ生成と Zod ベースの検証により、任意の TypeScript 関数をツール化 +- **MCP サーバーツール呼び出し**: 関数ツールと同じ方法で使える組み込みの MCP サーバーツール連携 +- **セッション**: エージェントループ内で作業コンテキストを維持するための永続メモリレイヤー +- **Human in the loop (人間の介入)**: 複数のエージェント実行にまたがって人間を関与させるための組み込み機構 +- **トレーシング**: ワークフローの可視化・デバッグ・監視のための組み込みトレーシング。OpenAI の評価、ファインチューニング、蒸留ツール群をサポート +- **リアルタイムエージェント**: 自動割り込み検出、コンテキスト管理、ガードレールなどの機能を備えた強力な音声エージェントを構築 ## インストール @@ -53,54 +56,78 @@ SDK の主な機能は次のとおりです。 npm install @openai/agents zod ``` -この SDK には Zod v4 が必要です。npm 経由で `zod` をインストールすると、最新の v4 リリースが取得されます。 +SDK には Zod v4 が必要です。npm で `zod` をインストールすると、最新の v4 リリースが取得されます。 ## 開始ポイントの選択 -初めて使うほとんどのユーザーは、次のいずれか 1 つのエントリーポイントだけで十分です。 +初めて使うユーザーの多くは、次のいずれか 1 つのエントリーポイントだけで十分です。 | Start with | Use it when | Notes | | --- | --- | --- | -| `@openai/agents` | ほとんどのテキストまたは音声アプリケーションを構築する場合 | 推奨のデフォルトです。OpenAI provider のセットアップが含まれており、音声 API は `@openai/agents/realtime` で利用できます | +| `@openai/agents` | テキスト、sandbox、または音声アプリケーションの大半を構築する場合 | 推奨のデフォルトです。OpenAI provider のセットアップ、`@openai/agents/sandbox` 配下の sandbox エージェント API、`@openai/agents/realtime` 配下の音声 API が含まれます | | `@openai/agents-realtime` | スタンドアロンの Realtime パッケージだけが必要な場合 | ブラウザ専用の音声アプリや、より狭いパッケージ境界にしたい場合に便利です | -| Lower-level packages (`@openai/agents-core`, `@openai/agents-openai`, `@openai/agents-extensions`) | より低レベルな構成、カスタム provider の接続、または特定の連携が必要な場合 | 多くの新規ユーザーは、具体的な必要性が出るまでこれらは無視して問題ありません | - -## Hello world の例 - - - -(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定していることを確認してください_) +| 下位レベルのパッケージ (`@openai/agents-core`, `@openai/agents-openai`, `@openai/agents-extensions`) | より低レベルな構成、カスタム provider の配線、または特定の連携が必要な場合 | 具体的な必要性が出るまでは、多くの新規ユーザーはこれらを無視して問題ありません | + +## Hello world のコード例 + +エージェントがファイルシステム上で作業する必要がある場合は、Sandbox エージェントから始めてください。ワークフローに sandbox ワークスペースや sandbox ライフサイクルが不要な場合は、通常の `Agent` も利用できます。 + + + + + + + + + + +(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) ```bash export OPENAI_API_KEY=sk-... ``` -## ここから開始 +## まずはこちら -まず 1 つの進め方を選んで、最初から最後まで動かしてみてください。その後で、より詳しいガイドに戻るのがおすすめです。 +まずは 1 つのパスを選び、エンドツーエンドで動かしてみてから、必要に応じてより詳しいガイドに戻ってください。 + + ## パスの選択 -やりたい作業は分かっているものの、どのページを見ればよいか分からないときは、この表を使ってください。 +やりたいことは決まっているものの、どのページに説明があるかわからない場合は、この表を使ってください。 | Goal | Start here | | --- | --- | -| 最初のテキストエージェントを構築し、1 回の完全な実行を確認する | [クイックスタート](/openai-agents-js/guides/quickstart) | +| 最初のテキストエージェントを構築し、1 回の完全な実行を確認する | [Quickstart](/openai-agents-js/guides/quickstart) | | 関数ツール、組み込みツール（Hosted）、または Agents as tools を追加する | [ツール](/openai-agents-js/guides/tools) | -| ハンドオフとマネージャー型オーケストレーションのどちらにするか判断する | [エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) | +| エージェントに分離されたファイルシステムとシェルのワークスペースを与える | [Sandbox agents](/openai-agents-js/guides/sandbox-agents) | +| ハンドオフとマネージャースタイルのオーケストレーションのどちらにするか決める | [エージェントオーケストレーション](/openai-agents-js/guides/multi-agent) | | ターンをまたいでメモリを保持する | [エージェントの実行](/openai-agents-js/guides/running-agents) と [セッション](/openai-agents-js/guides/sessions) | | OpenAI モデル、websocket トランスポート、または非 OpenAI provider を使う | [モデル](/openai-agents-js/guides/models) | -| outputs、run items、割り込み、再開状態を確認する | [エージェントの実行結果](/openai-agents-js/guides/results) | -| 低遅延の音声エージェントを構築する | [Voice Agents Quickstart](/openai-agents-js/guides/voice-agents/quickstart) | +| 出力、実行アイテム、割り込み、再開状態を確認する | [エージェントの実行結果](/openai-agents-js/guides/results) | +| 低レイテンシの音声エージェントを構築する | [Voice Agents Quickstart](/openai-agents-js/guides/voice-agents/quickstart) | diff --git a/docs/src/content/docs/ko/guides/agents.mdx b/docs/src/content/docs/ko/guides/agents.mdx index e2208ac57..d6827295f 100644 --- a/docs/src/content/docs/ko/guides/agents.mdx +++ b/docs/src/content/docs/ko/guides/agents.mdx @@ -16,34 +16,35 @@ import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agen import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw'; import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw'; -에이전트는 OpenAI Agents SDK의 주요 구성 요소입니다. **Agent**는 다음과 같이 구성된 Large Language Model (LLM)입니다: +에이전트는 OpenAI Agents SDK의 핵심 구성 요소입니다. **Agent**는 다음과 같이 구성된 Large Language Model (LLM)입니다. -- **Instructions** – 모델이 _자신이 누구인지_ 그리고 _어떻게 응답해야 하는지_ 알려주는 시스템 프롬프트 -- **Model** – 호출할 OpenAI 모델과 선택적인 모델 튜닝 매개변수 -- **Tools** – 작업을 수행하기 위해 LLM이 호출할 수 있는 함수 또는 API 목록 +- **Instructions** – 모델에 _자신이 누구인지_ 그리고 _어떻게 응답해야 하는지_ 알려주는 시스템 프롬프트 +- **Model** – 호출할 OpenAI 모델과 선택적 모델 튜닝 매개변수 +- **Tools** – 작업 수행을 위해 LLM이 호출할 수 있는 함수 또는 API 목록 -> 단일 `Agent`를 정의하거나 사용자 지정하려는 경우 이 페이지를 사용하세요. 여러 에이전트가 어떻게 협력해야 할지 결정하는 중이라면 [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent)을 읽어보세요. +> 단일 `Agent`를 정의하거나 커스터마이즈하려는 경우 이 페이지를 사용하세요. 여러 에이전트가 어떻게 협업해야 할지 결정하는 중이라면 [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent)을 읽어보세요. ### 다음 가이드 선택 이 페이지를 에이전트 정의의 허브로 사용하세요. 다음에 내려야 할 결정에 맞는 인접 가이드로 바로 이동할 수 있습니다. -| 다음을 하고 싶다면... | 다음에 읽을 내용 | +| If you want to... | Read next | | --- | --- | -| 모델을 선택하거나 저장된 프롬프트를 설정 | [모델](/openai-agents-js/ko/guides/models) | -| 에이전트에 기능을 추가 | [도구](/openai-agents-js/ko/guides/tools) | -| 관리자와 핸드오프 중에서 결정 | [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent) | -| 핸드오프 동작을 설정 | [핸드오프](/openai-agents-js/ko/guides/handoffs) | -| 턴 실행, 이벤트 스트리밍 또는 상태 관리 | [에이전트 실행](/openai-agents-js/ko/guides/running-agents) | -| 최종 출력, 실행 항목 검사 또는 재개 | [실행 결과](/openai-agents-js/ko/guides/results) | +| 모델을 선택하거나 저장된 프롬프트를 구성하고 싶다면 | [모델](/openai-agents-js/ko/guides/models) | +| 에이전트에 기능을 추가하고 싶다면 | [도구](/openai-agents-js/ko/guides/tools) | +| 에이전트에 격리된 파일시스템 작업 공간을 제공하고 싶다면 | [Sandbox clients](/openai-agents-js/ko/guides/sandbox-agents/concepts) | +| 관리자와 핸드오프 중 무엇을 사용할지 결정하고 싶다면 | [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent) | +| 핸드오프 동작을 구성하고 싶다면 | [핸드오프](/openai-agents-js/ko/guides/handoffs) | +| 턴을 실행하거나, 이벤트를 스트리밍하거나, 상태를 관리하고 싶다면 | [에이전트 실행](/openai-agents-js/ko/guides/running-agents) | +| 최종 출력, 실행 항목을 확인하거나 재개하고 싶다면 | [실행 결과](/openai-agents-js/ko/guides/results) | 이 페이지의 나머지 부분에서는 모든 Agent 기능을 더 자세히 설명합니다. --- -## Agent 기초 +## 에이전트 기본 사항 ### 기본 설정 @@ -51,21 +52,21 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor | Property | Required | Description | | --- | --- | --- | -| `name` | yes | 사람이 읽기 쉬운 짧은 식별자 | -| `instructions` | yes | 시스템 프롬프트(문자열 **또는** 함수 - [동적 instructions](#dynamic-instructions) 참고) | -| `prompt` | no | OpenAI Responses API 프롬프트 설정입니다. 정적 프롬프트 객체 또는 함수를 받을 수 있습니다. [Prompt](/openai-agents-js/ko/guides/models#prompt)를 참고하세요 | -| `handoffDescription` | no | 이 에이전트가 핸드오프 도구로 제공될 때 사용되는 짧은 설명 | -| `handoffs` | no | 대화를 전문 에이전트에게 위임합니다. [구성 패턴](#composition-patterns)과 [핸드오프 가이드](/openai-agents-js/ko/guides/handoffs)를 참고하세요 | -| `model` | no | 모델 이름 **또는** 사용자 지정 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 구현 | -| `modelSettings` | no | 튜닝 매개변수(temperature, top_p 등)입니다. [모델](/openai-agents-js/ko/guides/models#modelsettings)을 참고하세요. 필요한 속성이 최상위 수준에 없다면 `providerData` 아래에 포함할 수 있습니다 | -| `tools` | no | 모델이 호출할 수 있는 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 인스턴스 배열입니다. [도구](/openai-agents-js/ko/guides/tools)를 참고하세요 | -| `mcpServers` | no | 에이전트를 위한 MCP 기반 도구입니다. [모델 컨텍스트 프로토콜 (MCP) 가이드](/openai-agents-js/ko/guides/mcp)를 참고하세요 | -| `inputGuardrails` | no | 이 에이전트 체인의 첫 번째 사용자 입력에 적용되는 가드레일입니다. [가드레일](/openai-agents-js/ko/guides/guardrails)을 참고하세요 | -| `outputGuardrails` | no | 이 에이전트의 최종 출력에 적용되는 가드레일입니다. [가드레일](/openai-agents-js/ko/guides/guardrails)을 참고하세요 | -| `outputType` | no | 일반 텍스트 대신 structured outputs을 반환합니다. [출력 타입](#output-types)과 [실행 결과](/openai-agents-js/ko/guides/results#final-output)를 참고하세요 | -| `toolUseBehavior` | no | 함수 도구 결과를 모델로 다시 전달할지 또는 실행을 종료할지 제어합니다. [도구 사용 강제](#forcing-tool-use)를 참고하세요 | -| `resetToolChoice` | no | 도구 호출 후 `toolChoice`를 기본값으로 재설정하여(기본값: `true`) 도구 사용 루프를 방지합니다. [도구 사용 강제](#forcing-tool-use)를 참고하세요 | -| `handoffOutputTypeWarningEnabled` | no | 핸드오프 출력 타입이 다를 때 경고를 발생시킵니다(기본값: `true`). [실행 결과](/openai-agents-js/ko/guides/results#final-output)를 참고하세요 | +| `name` | 예 | 사람이 읽기 쉬운 짧은 식별자 | +| `instructions` | 예 | 시스템 프롬프트(문자열 **또는** 함수 – [동적 instructions](#dynamic-instructions) 참고) | +| `prompt` | 아니요 | OpenAI Responses API 프롬프트 설정입니다. 정적 프롬프트 객체 또는 함수를 받습니다. [Prompt](/openai-agents-js/ko/guides/models#prompt)를 참고하세요. | +| `handoffDescription` | 아니요 | 이 에이전트가 핸드오프 도구로 제공될 때 사용되는 짧은 설명 | +| `handoffs` | 아니요 | 대화를 전문 에이전트에 위임합니다. [구성 패턴](#composition-patterns)과 [핸드오프 가이드](/openai-agents-js/ko/guides/handoffs)를 참고하세요. | +| `model` | 아니요 | 모델 이름 **또는** 사용자 정의 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 구현 | +| `modelSettings` | 아니요 | 튜닝 매개변수(temperature, top_p 등)입니다. [모델](/openai-agents-js/ko/guides/models#modelsettings)을 참고하세요. 필요한 속성이 최상위에 없다면 `providerData` 아래에 포함할 수 있습니다. | +| `tools` | 아니요 | 모델이 호출할 수 있는 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 인스턴스 배열입니다. [도구](/openai-agents-js/ko/guides/tools)를 참고하세요. | +| `mcpServers` | 아니요 | 에이전트를 위한 MCP 기반 도구입니다. [모델 컨텍스트 프로토콜 (MCP) 가이드](/openai-agents-js/ko/guides/mcp)를 참고하세요. | +| `inputGuardrails` | 아니요 | 이 에이전트 체인의 첫 번째 사용자 입력에 적용되는 가드레일입니다. [가드레일](/openai-agents-js/ko/guides/guardrails)을 참고하세요. | +| `outputGuardrails` | 아니요 | 이 에이전트의 최종 출력에 적용되는 가드레일입니다. [가드레일](/openai-agents-js/ko/guides/guardrails)을 참고하세요. | +| `outputType` | 아니요 | 일반 텍스트 대신 구조화된 출력을 반환합니다. [출력 타입](#output-types)과 [실행 결과](/openai-agents-js/ko/guides/results#final-output)를 참고하세요. | +| `toolUseBehavior` | 아니요 | 함수 도구 결과를 다시 모델로 보낼지, 아니면 실행을 종료할지 제어합니다. [도구 사용 강제](#forcing-tool-use)를 참고하세요. | +| `resetToolChoice` | 아니요 | 도구 호출 후 `toolChoice`를 기본값으로 재설정합니다(기본값: `true`). 도구 사용 루프를 방지합니다. [도구 사용 강제](#forcing-tool-use)를 참고하세요. | +| `handoffOutputTypeWarningEnabled` | 아니요 | 핸드오프 출력 타입이 다를 때 경고를 발생시킵니다(기본값: `true`). [실행 결과](/openai-agents-js/ko/guides/results#final-output)를 참고하세요. | @@ -73,7 +74,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### 컨텍스트 -에이전트는 **컨텍스트 타입에 대해 제네릭**입니다. 즉 `Agent`입니다. *컨텍스트*는 사용자가 생성하여 `Runner.run()`에 전달하는 의존성 주입 객체입니다. 이는 모든 도구, 가드레일, 핸드오프 등에 전달되며 상태 저장이나 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등) 제공에 유용합니다. +에이전트는 **컨텍스트 타입에 대해 제네릭입니다**. 즉, `Agent`입니다. *컨텍스트*는 사용자가 생성하여 `Runner.run()`에 전달하는 의존성 주입 객체입니다. 이는 모든 도구, 가드레일, 핸드오프 등에 전달되며 상태 저장이나 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등) 제공에 유용합니다. @@ -81,7 +82,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### 출력 타입 -기본적으로 Agent는 **일반 텍스트**(`string`)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 `outputType` 속성을 지정할 수 있습니다. SDK는 다음을 허용합니다: +기본적으로 Agent는 **일반 텍스트**(`string`)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 `outputType` 속성을 지정할 수 있습니다. SDK는 다음을 지원합니다. 1. [Zod](https://github.com/colinhacks/zod) 스키마(`z.object({...})`) 2. JSON 스키마와 호환되는 모든 객체 @@ -92,19 +93,19 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor title="Structured output with Zod" /> -`outputType`이 제공되면 SDK는 일반 텍스트 대신 자동으로 [structured outputs](https://developers.openai.com/api/docs/guides/structured-outputs)을 사용합니다. +`outputType`이 제공되면 SDK는 일반 텍스트 대신 자동으로 [structured outputs](https://developers.openai.com/api/docs/guides/structured-outputs)를 사용합니다. --- ### OpenAI 플랫폼 매핑 -일부 에이전트 개념은 OpenAI 플랫폼 개념에 직접 대응되며, 다른 개념은 에이전트를 정의할 때가 아니라 실행할 때 설정됩니다. +일부 에이전트 개념은 OpenAI 플랫폼 개념에 직접 대응되며, 일부는 에이전트를 정의할 때가 아니라 실행할 때 구성됩니다. | SDK concept | OpenAI guide | When it matters | | --- | --- | --- | -| `outputType` | [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) | 에이전트가 텍스트 대신 타입이 지정된 JSON 또는 Zod로 검증된 객체를 반환해야 할 때 | +| `outputType` | [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) | 에이전트가 텍스트 대신 타입이 지정된 JSON 또는 Zod 검증 객체를 반환해야 할 때 | | `tools` / hosted tools | [Tools guide](https://developers.openai.com/api/docs/guides/tools) | 모델이 검색, 조회, 코드 실행 또는 사용자 함수/도구 호출을 수행해야 할 때 | -| `conversationId` / `previousResponseId` | [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) | 턴 간 대화 상태를 OpenAI가 유지하거나 연결하도록 하려는 경우 | +| `conversationId` / `previousResponseId` | [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) | 턴 사이의 대화 상태를 OpenAI가 유지하거나 연결하도록 하려는 경우 | `conversationId`와 `previousResponseId`는 `Agent` 생성자 필드가 아니라 런타임 제어 항목입니다. 이러한 SDK 진입점이 필요하다면 [에이전트 실행](/openai-agents-js/ko/guides/running-agents)을 사용하세요. @@ -112,16 +113,16 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ## 구성 패턴 -에이전트가 더 큰 워크플로에 참여할 때 가장 자주 등장하는 SDK 진입점은 두 가지입니다: +에이전트가 더 큰 워크플로에 참여할 때 가장 자주 등장하는 SDK 진입점은 두 가지입니다. -1. **관리자(도구로서의 에이전트)** – 중앙 에이전트가 대화를 소유하고 도구로 노출된 전문 에이전트를 호출합니다 -2. **핸드오프** – 초기 에이전트가 사용자의 요청을 식별한 뒤 전체 대화를 전문 에이전트에 위임합니다 +1. **관리자(Agents as tools)** – 중앙 에이전트가 대화를 소유하고, 도구로 노출된 전문 에이전트를 호출합니다. +2. **핸드오프** – 초기 에이전트가 사용자의 요청을 식별한 뒤 전체 대화를 전문 에이전트에 위임합니다. -이 접근 방식들은 상호 보완적입니다. 관리자는 가드레일이나 속도 제한을 강제할 단일 지점을 제공하고, 핸드오프는 각 에이전트가 대화의 제어권을 유지하지 않고도 하나의 작업에 집중할 수 있게 해줍니다. 설계상의 절충점과 각 패턴을 언제 선택해야 하는지는 [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent)을 참고하세요. +이 접근 방식들은 상호 보완적입니다. 관리자는 가드레일이나 속도 제한을 적용할 단일 지점을 제공하고, 핸드오프는 각 에이전트가 대화 제어를 유지하지 않고도 단일 작업에 집중할 수 있게 합니다. 설계상 트레이드오프와 각 패턴을 언제 선택해야 하는지는 [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent)을 참고하세요. -#### 관리자(도구로서의 에이전트) +#### 관리자(Agents as tools) -이 패턴에서 관리자는 제어권을 넘기지 않습니다. LLM이 도구를 사용하고 관리자가 최종 답변을 요약합니다. 자세한 내용은 [도구 가이드](/openai-agents-js/ko/guides/tools#agents-as-tools)를 참고하세요. +이 패턴에서 관리자는 제어를 넘기지 않습니다. LLM이 도구를 사용하고 관리자가 최종 답변을 요약합니다. 자세한 내용은 [도구 가이드](/openai-agents-js/ko/guides/tools#agents-as-tools)를 참고하세요. @@ -131,7 +132,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor -핸드오프 대상이 서로 다른 출력 타입을 반환할 수 있다면 `new Agent(...)`보다 `Agent.create(...)`를 사용하는 것이 좋습니다. 이렇게 하면 TypeScript가 핸드오프 그래프 전반에서 가능한 `finalOutput` 형태의 유니온을 추론할 수 있고, `handoffOutputTypeWarningEnabled`로 제어되는 런타임 경고를 피할 수 있습니다. 엔드투엔드 예시는 [실행 결과 가이드](/openai-agents-js/ko/guides/results#final-output)를 참고하세요. +핸드오프 대상이 서로 다른 출력 타입을 반환할 수 있다면 `new Agent(...)`보다 `Agent.create(...)`를 사용하는 것이 좋습니다. 이렇게 하면 TypeScript가 핸드오프 그래프 전반의 가능한 `finalOutput` 형태의 유니온을 추론할 수 있고, `handoffOutputTypeWarningEnabled`로 제어되는 런타임 경고도 피할 수 있습니다. 전체 예제는 [실행 결과 가이드](/openai-agents-js/ko/guides/results#final-output)를 참고하세요. --- @@ -153,7 +154,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### 동적 프롬프트 -`prompt`는 `instructions`와 동일한 콜백 형태를 지원하지만 문자열 대신 프롬프트 설정 객체를 반환합니다. 이는 프롬프트 ID, 버전 또는 변수가 현재 실행 컨텍스트에 따라 달라질 때 유용합니다. +`prompt`는 `instructions`와 동일한 콜백 형태를 지원하지만, 문자열 대신 프롬프트 설정 객체를 반환합니다. 이는 프롬프트 ID, 버전 또는 변수가 현재 실행 컨텍스트에 따라 달라질 때 유용합니다. @@ -205,27 +206,27 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### 도구 사용 강제 -도구를 제공한다고 해서 LLM이 반드시 도구를 호출하는 것은 아닙니다. `modelSettings.toolChoice`를 사용해 도구 사용을 **강제**할 수 있습니다: +도구를 제공한다고 해서 LLM이 반드시 도구를 호출하는 것은 아닙니다. `modelSettings.toolChoice`로 도구 사용을 **강제**할 수 있습니다. 1. `'auto'` (기본값) – LLM이 도구 사용 여부를 결정합니다 -2. `'required'` – LLM이 _반드시_ 도구를 호출해야 합니다(어떤 도구인지는 선택 가능) -3. `'none'` – LLM은 도구를 **호출하면 안 됩니다** +2. `'required'` – LLM이 도구를 _반드시_ 호출해야 합니다(어떤 도구인지는 선택 가능) +3. `'none'` – LLM이 도구를 **호출하면 안 됩니다** 4. 특정 도구 이름(예: `'calculator'`) – LLM이 해당 도구를 반드시 호출해야 합니다 -사용 가능한 도구가 OpenAI Responses의 `computerTool()`인 경우 `toolChoice: 'computer'`는 특별합니다. `'computer'`를 일반 함수 이름으로 취급하는 대신 GA 내장 컴퓨터 도구를 강제합니다. SDK는 오래된 연동을 위해 preview 호환 컴퓨터 선택자도 허용하지만, 새 코드에서는 `'computer'`를 사용하는 것이 좋습니다. 사용 가능한 컴퓨터 도구가 없다면 이 문자열은 다른 함수 도구 이름과 동일하게 동작합니다. +사용 가능한 도구가 OpenAI Responses의 `computerTool()`일 때 `toolChoice: 'computer'`는 특별하게 처리됩니다. `'computer'`를 일반 함수 이름으로 취급하는 대신 GA 기본 제공 컴퓨터 도구를 강제합니다. SDK는 이전 통합을 위한 preview 호환 컴퓨터 선택자도 지원하지만, 새 코드에서는 `'computer'`를 사용하는 것이 좋습니다. 사용 가능한 컴퓨터 도구가 없다면 이 문자열은 다른 함수 도구 이름과 동일하게 동작합니다. -`toolNamespace()` 같은 지연된 Responses 도구, `deferLoading: true`가 설정된 함수 도구, 또는 `deferLoading: true`가 설정된 호스티드 MCP 도구를 사용할 때는 `modelSettings.toolChoice`를 `'auto'`로 유지하세요. SDK는 지연된 도구나 내장 `tool_search` 헬퍼를 이름으로 강제하는 것을 거부합니다. 모델이 해당 정의를 언제 로드할지 스스로 결정해야 하기 때문입니다. 전체 tool-search 설정은 [도구 가이드](/openai-agents-js/ko/guides/tools#deferred-tool-loading-with-tool-search)를 참고하세요. +`toolNamespace()` 같은 지연 Responses 도구, `deferLoading: true`가 설정된 함수 도구, 또는 `deferLoading: true`가 설정된 호스티드 MCP 도구를 사용할 때는 `modelSettings.toolChoice`를 `'auto'`로 유지하세요. SDK는 지연 도구나 기본 제공 `tool_search` 헬퍼를 이름으로 강제하는 것을 거부합니다. 모델이 해당 정의를 언제 로드할지 스스로 결정해야 하기 때문입니다. 전체 tool-search 설정은 [도구 가이드](/openai-agents-js/ko/guides/tools#deferred-tool-loading-with-tool-search)를 참고하세요. #### 무한 루프 방지 -도구 호출 후 SDK는 자동으로 `toolChoice`를 다시 `'auto'`로 재설정합니다. 이는 모델이 반복적으로 도구를 호출하려고 시도하는 무한 루프에 빠지는 것을 방지합니다. 이 동작은 `resetToolChoice` 플래그 또는 `toolUseBehavior` 설정으로 재정의할 수 있습니다: +도구 호출 후 SDK는 자동으로 `toolChoice`를 `'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({ @@ -234,16 +235,16 @@ const agent = new Agent({ }); ``` -참고: `toolUseBehavior`는 **함수 도구**에만 적용됩니다. 호스티드 툴은 항상 처리를 위해 모델로 다시 돌아갑니다. +참고: `toolUseBehavior`는 **함수 도구**에만 적용됩니다. 호스티드 툴은 항상 처리를 위해 모델로 다시 반환됩니다. --- ## 관련 가이드 -- 모델 선택, 저장된 프롬프트, provider 설정은 [모델](/openai-agents-js/ko/guides/models) -- 함수 도구, 호스티드 툴, MCP, `agent.asTool()`은 [도구](/openai-agents-js/ko/guides/tools) -- 관리자, 핸드오프, 코드 기반 오케스트레이션 중 선택은 [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent) -- 전문 에이전트 위임 설정은 [핸드오프](/openai-agents-js/ko/guides/handoffs) -- 턴 실행, 스트리밍, 대화 상태는 [에이전트 실행](/openai-agents-js/ko/guides/running-agents) -- `finalOutput`, 실행 항목, 재개 상태는 [실행 결과](/openai-agents-js/ko/guides/results) -- 사이드바의 **@openai/agents** 아래에서 전체 TypeDoc 참조를 살펴보세요 +- 모델 선택, 저장된 프롬프트, provider 설정은 [모델](/openai-agents-js/ko/guides/models)을 참고하세요 +- 함수 도구, 호스티드 툴, MCP, `agent.asTool()`은 [도구](/openai-agents-js/ko/guides/tools)를 참고하세요 +- 관리자, 핸드오프, 코드 기반 오케스트레이션 중 선택은 [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent)을 참고하세요 +- 전문 에이전트 위임 구성은 [핸드오프](/openai-agents-js/ko/guides/handoffs)를 참고하세요 +- 턴 실행, 스트리밍, 대화 상태는 [에이전트 실행](/openai-agents-js/ko/guides/running-agents)을 참고하세요 +- `finalOutput`, 실행 항목, 재개 상태는 [실행 결과](/openai-agents-js/ko/guides/results)를 참고하세요 +- 사이드바의 **@openai/agents** 아래에서 전체 TypeDoc 레퍼런스를 살펴보세요 diff --git a/docs/src/content/docs/ko/guides/running-agents.mdx b/docs/src/content/docs/ko/guides/running-agents.mdx index 6df11bba0..29b6d7e89 100644 --- a/docs/src/content/docs/ko/guides/running-agents.mdx +++ b/docs/src/content/docs/ko/guides/running-agents.mdx @@ -13,92 +13,94 @@ import previousResponseIdExample from '../../../../../../examples/docs/running-a 에이전트는 스스로 아무 작업도 하지 않습니다. `Runner` 클래스나 `run()` 유틸리티로 **실행**해야 합니다. -> 턴 실행, 이벤트 스트리밍, 대화 상태 관리를 하려면 [에이전트](/openai-agents-js/ko/guides/agents) 문서를 읽은 다음 이 페이지를 읽으세요. 아직 에이전트를 어떻게 정의할지 결정 중이라면 먼저 [에이전트](/openai-agents-js/ko/guides/agents)부터 시작하세요. +> 턴을 실행하거나, 이벤트를 스트리밍하거나, 대화 상태를 관리하려는 경우 [에이전트](/openai-agents-js/ko/guides/agents) 다음에 이 페이지를 읽어보세요. 에이전트를 어떻게 정의해야 할지 아직 결정 중이라면 먼저 [에이전트](/openai-agents-js/ko/guides/agents)부터 시작하세요. -커스텀 runner 가 필요하지 않다면, 싱글턴 기본 `Runner` 인스턴스를 실행하는 `run()` 유틸리티를 사용할 수도 있습니다. +커스텀 runner가 필요하지 않다면, 싱글턴 기본 `Runner` 인스턴스를 실행하는 `run()` 유틸리티를 사용할 수도 있습니다. -또는 직접 runner 인스턴스를 만들 수도 있습니다: +또는 직접 runner 인스턴스를 만들 수 있습니다: -에이전트를 실행하면 최종 출력과 전체 실행 이력을 담고 있는 [실행 결과](/openai-agents-js/ko/guides/results) 객체를 받게 됩니다. +에이전트를 실행한 후에는 최종 출력과 실행의 전체 기록이 담긴 [실행 결과](/openai-agents-js/ko/guides/results) 객체를 받게 됩니다. ## Runner 수명 주기 및 설정 ### 에이전트 루프 -Runner 의 run 메서드를 사용할 때는 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주됨)이거나, OpenAI Responses API 의 항목들인 입력 항목 목록일 수 있습니다. +Runner의 run 메서드를 사용할 때는 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주됨)일 수도 있고, OpenAI Responses API의 항목들인 입력 항목 목록일 수도 있습니다. -그러면 runner 는 다음 루프를 실행합니다: +그러면 runner는 다음 루프를 실행합니다: -1. 현재 입력으로 현재 에이전트의 모델을 호출합니다. -2. LLM 응답을 검사합니다. +1. 현재 입력으로 현재 에이전트의 모델을 호출합니다 +2. LLM 응답을 검사합니다 - **최종 출력** → 반환 - - **핸드오프** → 새 에이전트로 전환하고, 누적된 대화 이력을 유지한 채 1로 이동 + - **핸드오프** → 새 에이전트로 전환하고, 누적된 대화 기록을 유지한 뒤 1로 이동 - **도구 호출** → 도구를 실행하고, 그 결과를 대화에 추가한 뒤 1로 이동 -3. `maxTurns` 에 도달하면 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)를 발생시킵니다. +3. `maxTurns`에 도달하면 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)를 발생시킵니다 #### Runner 수명 주기 -앱이 시작할 때 `Runner` 를 생성하고 요청 간에 재사용하세요. 인스턴스는 모델 provider 나 트레이싱 옵션 같은 전역 설정을 저장합니다. 완전히 다른 설정이 필요할 때만 다른 `Runner` 를 만드세요. 간단한 스크립트에서는 내부적으로 기본 runner 를 사용하는 `run()` 을 호출해도 됩니다. +앱이 시작될 때 `Runner`를 생성하고 요청 전반에서 재사용하세요. 이 인스턴스는 모델 provider나 트레이싱 옵션 같은 전역 설정을 저장합니다. 완전히 다른 설정이 필요한 경우에만 다른 `Runner`를 생성하세요. 단순한 스크립트에서는 내부적으로 기본 runner를 사용하는 `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` 를 반환하고 모델에서 이벤트가 도착하는 대로 방출합니다. | +| `stream` | `false` | `true`이면 호출은 `StreamedRunResult`를 반환하고 모델에서 이벤트가 도착하는 대로 방출합니다. | | `context` | – | 모든 도구 / 가드레일 / 핸드오프에 전달되는 컨텍스트 객체입니다. 자세한 내용은 [컨텍스트 관리 가이드](/openai-agents-js/ko/guides/context)를 참고하세요. | -| `maxTurns` | `10` | 안전 제한입니다. 도달하면 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)를 발생시킵니다. | -| `signal` | – | 취소를 위한 `AbortSignal` 입니다. | -| `session` | – | 세션 지속성 구현입니다. [세션 가이드](/openai-agents-js/ko/guides/sessions)를 참고하세요. | -| `sessionInputCallback` | – | 세션 이력과 새 입력을 병합하는 커스텀 로직입니다. 모델 호출 전에 실행됩니다. [세션](/openai-agents-js/ko/guides/sessions)을 참고하세요. | -| `callModelInputFilter` | – | 모델 호출 직전에 모델 입력(항목 + 선택적 instructions)을 편집하는 훅입니다. [Call model input filter](#call-model-input-filter)를 참고하세요. | +| `maxTurns` | `10` | 안전 제한값으로, 도달 시 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)를 발생시킵니다. | +| `signal` | – | 취소를 위한 `AbortSignal`입니다. | +| `session` | – | 세션 영속성 구현입니다. [세션 가이드](/openai-agents-js/ko/guides/sessions)를 참고하세요. | +| `sessionInputCallback` | – | 세션 기록과 새 입력에 대한 커스텀 병합 로직으로, 모델 호출 전에 실행됩니다. [세션](/openai-agents-js/ko/guides/sessions)을 참고하세요. | +| `callModelInputFilter` | – | 모델 호출 직전에 모델 입력(항목 + 선택적 instructions)을 수정하는 훅입니다. [Call model input filter](#call-model-input-filter)를 참고하세요. | | `toolErrorFormatter` | – | 모델에 반환되는 도구 승인 거부 메시지를 커스터마이즈하는 훅입니다. [Tool error formatter](#tool-error-formatter)를 참고하세요. | -| `reasoningItemIdPolicy` | – | 이전 실행 항목을 다시 모델 입력으로 변환할 때 reasoning-item `id` 를 유지할지 생략할지 제어합니다. [Reasoning item ID policy](#reasoning-item-id-policy)를 참고하세요. | +| `reasoningItemIdPolicy` | – | 이전 실행 항목을 다시 모델 입력으로 변환할 때 reasoning-item `id`를 유지할지 생략할지를 제어합니다. [Reasoning item ID policy](#reasoning-item-id-policy)를 참고하세요. | | `tracing` | – | 실행별 트레이싱 설정 재정의입니다(예: export API key). | -| `errorHandlers` | – | 지원되는 런타임 오류용 핸들러입니다(현재는 `maxTurns`). [Error handlers](#error-handlers)를 참고하세요. | +| `sandbox` | – | `SandboxAgent` 실행을 위한 Sandbox client, live session, session state, snapshot, manifest override 또는 동시성 제한입니다. [Sandbox agents](/openai-agents-js/ko/guides/sandbox-agents/concepts)를 참고하세요. | +| `errorHandlers` | – | 지원되는 런타임 오류(현재는 `maxTurns`)용 핸들러입니다. [Error handlers](#error-handlers)를 참고하세요. | | `conversationId` | – | 서버 측 대화를 재사용합니다(OpenAI Responses API + Conversations API 전용). | -| `previousResponseId` | – | 대화를 만들지 않고 이전 Responses API 호출에서 이어갑니다(OpenAI Responses API 전용). | +| `previousResponseId` | – | 대화를 생성하지 않고 이전 Responses API 호출에서 이어갑니다(OpenAI Responses API 전용). | ### 스트리밍 -스트리밍을 사용하면 LLM 이 실행되는 동안 스트리밍 이벤트도 함께 받을 수 있습니다. 스트림이 시작되면 `StreamedRunResult` 에는 새로 생성된 모든 출력을 포함해 실행에 대한 전체 정보가 들어 있습니다. `for await` 루프로 스트리밍 이벤트를 순회할 수 있습니다. 자세한 내용은 [스트리밍 가이드](/openai-agents-js/ko/guides/streaming)를 참고하세요. +스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트도 추가로 받을 수 있습니다. 스트림이 시작되면 `StreamedRunResult`에는 새로 생성된 모든 출력을 포함해 실행에 대한 전체 정보가 담깁니다. `for await` 루프를 사용해 스트리밍 이벤트를 순회할 수 있습니다. 자세한 내용은 [스트리밍 가이드](/openai-agents-js/ko/guides/streaming)를 참고하세요. ### 실행 설정 -직접 `Runner` 인스턴스를 만드는 경우, runner 를 설정하기 위해 `RunConfig` 객체를 전달할 수 있습니다. +직접 `Runner` 인스턴스를 만드는 경우 runner를 설정하기 위해 `RunConfig` 객체를 전달할 수 있습니다. | Field | Type | Purpose | | --- | --- | --- | | `model` | `string \| Model` | 실행의 **모든** 에이전트에 대해 특정 모델을 강제합니다. | -| `modelProvider` | `ModelProvider` | 모델 이름을 해석합니다. 기본값은 OpenAI provider 입니다. | -| `modelSettings` | `ModelSettings` | 에이전트별 설정을 덮어쓰는 전역 튜닝 매개변수입니다. opt-in 재시도 설정을 포함한 자세한 내용은 [모델 가이드](/openai-agents-js/ko/guides/models#modelsettings)를 참고하세요. | +| `modelProvider` | `ModelProvider` | 모델 이름을 해석하며, 기본값은 OpenAI provider입니다. | +| `modelSettings` | `ModelSettings` | 에이전트별 설정을 재정의하는 전역 튜닝 매개변수입니다. opt-in 재시도 설정을 포함한 자세한 내용은 [모델 가이드](/openai-agents-js/ko/guides/models#modelsettings)를 참고하세요. | | `handoffInputFilter` | `HandoffInputFilter` | 핸드오프 수행 시 입력 항목을 변경합니다(핸드오프 자체에 이미 정의되어 있지 않은 경우). | | `inputGuardrails` | `InputGuardrail[]` | _초기_ 사용자 입력에 적용되는 가드레일입니다. | | `outputGuardrails` | `OutputGuardrail[]` | _최종_ 출력에 적용되는 가드레일입니다. | -| `tracingDisabled` | `boolean` | OpenAI Tracing 을 완전히 비활성화합니다. | -| `traceIncludeSensitiveData` | `boolean` | span 은 계속 방출하면서 trace 에서 LLM/도구 입력 및 출력을 제외합니다. | +| `tracingDisabled` | `boolean` | OpenAI Tracing을 완전히 비활성화합니다. | +| `traceIncludeSensitiveData` | `boolean` | span은 계속 내보내면서 trace에서 LLM/도구 입력 및 출력을 제외합니다. | | `workflowName` | `string` | Traces 대시보드에 표시되며 관련 실행을 그룹화하는 데 도움이 됩니다. | -| `traceId` / `groupId` | `string` | SDK 가 생성하도록 두는 대신 trace 또는 group ID 를 수동으로 지정합니다. | -| `traceMetadata` | `Record` | 모든 span 에 첨부할 임의의 메타데이터입니다. | +| `traceId` / `groupId` | `string` | SDK가 생성하도록 두는 대신 trace 또는 group ID를 수동으로 지정합니다. | +| `traceMetadata` | `Record` | 모든 span에 첨부할 임의 메타데이터입니다. | | `tracing` | `TracingConfig` | 실행별 트레이싱 재정의입니다(예: export API key). | -| `sessionInputCallback` | `SessionInputCallback` | 이 runner 의 모든 실행에 대한 기본 이력 병합 전략입니다. | -| `callModelInputFilter` | `CallModelInputFilter` | 각 모델 호출 전에 모델 입력을 편집하는 전역 훅입니다. | +| `sessionInputCallback` | `SessionInputCallback` | 이 runner의 모든 실행에 대한 기본 기록 병합 전략입니다. | +| `callModelInputFilter` | `CallModelInputFilter` | 각 모델 호출 전에 모델 입력을 수정하는 전역 훅입니다. | | `toolErrorFormatter` | `ToolErrorFormatter` | 모델에 반환되는 도구 승인 거부 메시지를 커스터마이즈하는 전역 훅입니다. | -| `reasoningItemIdPolicy` | `ReasoningItemIdPolicy` | 생성된 항목을 이후 모델 호출에 다시 재생할 때 reasoning-item `id` 를 유지하거나 생략하는 기본 정책입니다. | +| `reasoningItemIdPolicy` | `ReasoningItemIdPolicy` | 생성된 항목을 이후 모델 호출에 다시 재생할 때 reasoning-item `id`를 유지하거나 생략하는 기본 정책입니다. | +| `sandbox` | `SandboxRunConfig` | `SandboxAgent` 실행을 위한 기본 sandbox 런타임 설정입니다. | ## 상태 및 대화 관리 @@ -109,15 +111,17 @@ Runner 의 run 메서드를 사용할 때는 시작 에이전트와 입력을 | Strategy | Where state lives | Best for | What you pass on the next turn | | --- | --- | --- | --- | | `result.history` | 앱 메모리 | 작은 채팅 루프, 완전한 수동 제어, 모든 provider | `result.history` | -| `session` | 사용자 스토리지 + SDK | 영속적인 채팅 상태, 재개 가능한 실행, 커스텀 스토어 | 동일한 `session` 인스턴스(또는 스토어 기반 인스턴스) | -| `conversationId` | OpenAI Conversations API | 워커/서비스 간 공유되는 서버 측 상태 | 동일한 `conversationId` 와 새 사용자 턴만 | -| `previousResponseId` | OpenAI Responses API 전용 | 대화를 만들지 않는 가장 단순한 서버 관리형 이어가기 | `result.lastResponseId` 와 새 사용자 턴만 | +| `session` | 사용자 저장소 + SDK | 영속적인 채팅 상태, 재개 가능한 실행, 커스텀 저장소 | 동일한 `session` 인스턴스(또는 저장소 기반 인스턴스) | +| `conversationId` | OpenAI Conversations API | 워커/서비스 간 공유되는 서버 측 상태 | 동일한 `conversationId`와 새 사용자 턴만 | +| `previousResponseId` | OpenAI Responses API 전용 | 대화를 만들지 않는 가장 단순한 서버 관리형 이어가기 | `result.lastResponseId`와 새 사용자 턴만 | -`result.history` 와 `session` 은 클라이언트 관리형입니다. `conversationId` 와 `previousResponseId` 는 OpenAI 관리형이며 OpenAI Responses API 를 사용할 때만 적용됩니다. 대부분의 애플리케이션에서는 대화마다 하나의 지속성 전략을 선택하세요. 의도적으로 두 계층을 조정하는 경우가 아니라면 클라이언트 관리형 이력과 서버 관리형 상태를 섞으면 컨텍스트가 중복될 수 있습니다. +`result.history`와 `session`은 클라이언트 관리형입니다. `conversationId`와 `previousResponseId`는 OpenAI 관리형이며 OpenAI Responses API를 사용할 때만 적용됩니다. 대부분의 애플리케이션에서는 대화당 하나의 영속성 전략을 선택하세요. 클라이언트 관리형 기록과 서버 관리형 상태를 섞으면, 두 계층을 의도적으로 조정하지 않는 한 컨텍스트가 중복될 수 있습니다. + +Sandbox agents는 또 하나의 상태 계층인 live sandbox workspace를 추가합니다. 대화 기록에는 일반 SDK의 `session`, `conversationId`, `previousResponseId`를 사용하고, sandbox 파일시스템 상태에는 `sandbox.session`, `sandbox.sessionState`, `RunState`, 또는 snapshots를 사용하세요. workspace 수명 주기에 대해서는 [Sandbox agents](/openai-agents-js/ko/guides/sandbox-agents/concepts)를 참고하세요. ### 대화 / 채팅 스레드 -`runner.run()`(또는 `run()` 유틸리티)의 각 호출은 애플리케이션 수준 대화의 한 **턴** 을 나타냅니다. `RunResult` 중 최종 사용자에게 얼마나 보여줄지는 직접 선택합니다. 때로는 `finalOutput` 만, 다른 경우에는 생성된 모든 항목을 보여줄 수 있습니다. +`runner.run()`(또는 `run()` 유틸리티)을 호출할 때마다 애플리케이션 수준 대화의 한 **턴**을 나타냅니다. `RunResult` 중 어느 정도를 최종 사용자에게 보여줄지는 사용자가 결정합니다. 경우에 따라 `finalOutput`만 보여줄 수도 있고, 생성된 모든 항목을 보여줄 수도 있습니다. -대화형 버전은 [chat 예제](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 가 대화 이력을 대신 저장하도록 할 수 있습니다. 이는 긴 대화나 여러 서비스를 조율할 때 유용합니다. 아래의 두 서버 관리형 접근 방식 모두에서 각 요청마다 새 턴의 입력만 전달하면 됩니다. API 가 이전 상태를 재사용합니다. 자세한 내용은 [Conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state)를 참고하세요. +매 턴마다 전체 로컬 대화 기록을 보내는 대신, OpenAI Responses API가 대화 기록을 대신 영속화하도록 할 수 있습니다. 이는 긴 대화나 여러 서비스를 조율할 때 유용합니다. 아래의 두 서버 관리형 접근법에서는 매 요청마다 새 턴의 입력만 전달하세요. API가 이전 상태를 재사용해 줍니다. 자세한 내용은 [Conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state)를 참고하세요. -OpenAI 는 서버 측 상태를 재사용하는 두 가지 방법을 제공합니다: +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는 새로 생성된 항목만 자동으로 포함합니다. -`conversationId` 와 `previousResponseId` 는 함께 사용할 수 없습니다. 시스템 간에 공유할 수 있는 이름 있는 대화 리소스가 필요하면 `conversationId` 를, 한 응답에서 다음 응답으로 이어지는 가장 저렴한 SDK 수준 이어가기 기본 요소만 원하면 `previousResponseId` 를 사용하세요. +`conversationId`와 `previousResponseId`는 함께 사용할 수 없습니다. 여러 시스템 간에 공유할 수 있는 이름 있는 대화 리소스가 필요하다면 `conversationId`를 사용하고, 한 응답에서 다음 응답으로 이어지는 가장 저렴한 SDK 수준 이어가기 기본 구성 요소가 필요하다면 `previousResponseId`를 사용하세요. ## 훅 및 커스터마이즈 ### Call model input filter -`callModelInputFilter` 를 사용하면 모델이 호출되기 _직전_ 에 모델 입력을 편집할 수 있습니다. 이 훅은 현재 에이전트, 컨텍스트, 그리고 결합된 입력 항목(`session` 이 있으면 세션 이력 포함)을 받습니다. 민감한 데이터를 가리거나, 오래된 메시지를 제거하거나, 추가 시스템 가이드를 주입하려면 업데이트된 `input` 배열과 선택적 `instructions` 를 반환하세요. +`callModelInputFilter`를 사용하면 모델이 호출되기 _직전_ 에 모델 입력을 수정할 수 있습니다. 이 훅은 현재 에이전트, 컨텍스트, 그리고 결합된 입력 항목(세션 기록이 있는 경우 포함)을 받습니다. 민감한 데이터를 마스킹하거나, 오래된 메시지를 제거하거나, 추가 시스템 가이드를 주입하기 위해 업데이트된 `input` 배열과 선택적 `instructions`를 반환하세요. -실행별로는 `runner.run(..., { callModelInputFilter })` 에서 설정하거나, `Runner` 설정(`RunConfig` 의 `callModelInputFilter`)에서 기본값으로 설정할 수 있습니다. +실행별로 `runner.run(..., { callModelInputFilter })`에서 설정하거나 `Runner` 설정의 기본값(`RunConfig`의 `callModelInputFilter`)으로 설정할 수 있습니다. -반환값은 반드시 `ModelInputData` 객체여야 합니다: `{ input: AgentInputItem[], instructions? }`. `input` 필드는 필수이며 배열이어야 합니다. 다른 형태를 반환하면 `UserError` 가 발생합니다. +반환값은 반드시 `ModelInputData` 객체여야 합니다: `{ input: AgentInputItem[], instructions? }`. `input` 필드는 필수이며 배열이어야 합니다. 다른 형태를 반환하면 `UserError`가 발생합니다. -SDK 는 필터를 호출하기 전에 준비된 턴 입력을 복제합니다. `session` 도 함께 사용 중이라면 필터링된 복제본이 저장되므로, 여기서 적용한 마스킹이나 잘라내기는 저장된 세션 이력에도 반영됩니다. +SDK는 필터를 호출하기 전에 준비된 턴 입력을 복제합니다. `session`도 함께 사용하는 경우, 필터링된 복제본이 영속화되므로 여기서 적용한 마스킹이나 잘라내기가 저장된 세션 기록에도 반영됩니다. -`conversationId` 또는 `previousResponseId` 를 사용할 때 이 훅은 다음 Responses API 호출을 위한 준비된 payload 에서 실행됩니다. 이전 서버 관리형 컨텍스트는 API 가 복원하므로, 해당 호출에 대한 필터링 배열은 이미 이전 이력 전체 재생이 아니라 새 턴의 delta 만 나타낼 수 있습니다. 이 최종 필터 단계 전에 저장된 이력과 현재 턴이 병합되는 방식을 바꾸고 싶다면 `sessionInputCallback` 을 사용하세요. +`conversationId` 또는 `previousResponseId`를 사용할 때 이 훅은 다음 Responses API 호출을 위해 준비된 payload에서 실행됩니다. 이전 서버 관리형 컨텍스트는 API가 복구하므로, 해당 호출의 필터링된 배열은 이미 이전 기록 전체 재생이 아니라 새 턴의 차이분만 나타낼 수 있습니다. 이 최종 필터 단계 전에 저장된 기록과 현재 턴이 병합되는 방식을 바꿔야 한다면 `sessionInputCallback`을 사용하세요. ### Tool error formatter -`toolErrorFormatter` 를 사용하면 도구 호출이 거부되었을 때 모델로 다시 전송되는 승인 거부 메시지를 커스터마이즈할 수 있습니다. 이를 통해 SDK 기본 메시지 대신 도메인별 표현(예: 컴플라이언스 가이드)을 반환할 수 있습니다. +`toolErrorFormatter`를 사용하면 도구 호출이 거부될 때 모델로 다시 전송되는 승인 거부 메시지를 커스터마이즈할 수 있습니다. 이를 통해 SDK 기본 메시지 대신 도메인 특화된 문구(예: 컴플라이언스 가이드)를 반환할 수 있습니다. -formatter 는 실행별(`runner.run(..., { toolErrorFormatter })`) 또는 전역적으로 `RunConfig`(`new Runner(...)` 의 `toolErrorFormatter`)에서 설정할 수 있습니다. +포매터는 실행별(`runner.run(..., { toolErrorFormatter })`) 또는 전역(`RunConfig`의 `toolErrorFormatter`, `new Runner(...)`)으로 설정할 수 있습니다. -이 formatter 는 승인 거부에 대한 전역 fallback 입니다. 특정 인터럽션을 `result.state.reject(interruption, { message: '...' })` 로 거부하면, 호출별 `message` 가 `toolErrorFormatter` 보다 우선합니다. 둘 다 제공되지 않으면 SDK 는 기본 거부 텍스트인 `Tool execution was not approved.` 를 사용합니다. +이 포매터는 승인 거부에 대한 전역 fallback입니다. 특정 인터럽션을 `result.state.reject(interruption, { message: '...' })`로 거부하면 호출별 `message`가 `toolErrorFormatter`보다 우선합니다. 둘 다 제공되지 않으면 SDK는 기본 거부 텍스트인 `Tool execution was not approved.`로 fallback합니다. -현재 formatter 는 `approval_rejected` 이벤트에서 실행되며 다음을 받습니다: +현재 이 포매터는 `approval_rejected` 이벤트에서 실행되며 다음을 받습니다: - `kind` (현재는 항상 `'approval_rejected'`) - `toolType` (`'function'`, `'computer'`, `'shell'`, 또는 `'apply_patch'`) @@ -186,70 +190,70 @@ formatter 는 실행별(`runner.run(..., { toolErrorFormatter })`) 또는 전역 - `defaultMessage` (SDK fallback 메시지, 현재 `Tool execution was not approved.`) - `runContext` -메시지를 재정의하려면 문자열을 반환하고, SDK 기본값을 유지하려면 `undefined` 를 반환하세요. formatter 가 예외를 발생시키거나(또는 문자열이 아닌 값을 반환하면) SDK 는 경고를 기록하고 기본 승인 거부 메시지로 fallback 합니다. +메시지를 재정의하려면 문자열을 반환하고, SDK 기본값을 유지하려면 `undefined`를 반환하세요. 포매터가 예외를 발생시키거나(또는 문자열이 아닌 값을 반환하면) SDK는 경고를 기록하고 기본 승인 거부 메시지로 fallback합니다. ### Reasoning item ID policy -`reasoningItemIdPolicy` 를 사용하면 SDK 가 이전에 생성된 실행 항목을 이후 모델 입력용 `AgentInputItem[]` 로 다시 변환할 때 reasoning item 이 `id` 필드를 유지할지 제어할 수 있습니다. +`reasoningItemIdPolicy`를 사용하면 SDK가 이전에 생성된 실행 항목을 이후 모델 입력을 위한 `AgentInputItem[]`로 다시 변환할 때 reasoning item이 `id` 필드를 유지할지 제어할 수 있습니다. -이는 SDK 가 생성된 모델 항목을 입력으로 다시 재생하는 다음과 같은 경우에 영향을 줍니다: +이는 SDK가 생성된 모델 항목을 입력으로 재생하는 다음과 같은 위치에 영향을 줍니다: - 같은 실행 내의 후속 모델 호출(예: 도구 실행 후) -- 생성된 항목을 입력/이력으로 재사용하는 후속 턴 -- 저장된 `RunState` 에서 재개된 실행 -- `result.history` / `result.output` 같은 파생된 결과 뷰(모델 입력 형태의 배열) -- `'preserve'` (기본값)는 reasoning-item ID 를 유지합니다 -- `'omit'` 는 입력으로 다시 보내기 전에 reasoning item 에서 `id` 필드를 제거합니다 -- reasoning item 이 아닌 항목은 영향을 받지 않습니다 +- 생성된 항목을 입력/기록으로 재사용하는 이후 턴 +- 저장된 `RunState`에서 재개된 실행 +- `result.history` / `result.output` 같은 파생 결과 뷰(모델 입력 형태의 배열) +- `'preserve'` (기본값)은 reasoning-item ID를 유지합니다 +- `'omit'`는 입력으로 다시 보내기 전에 reasoning item에서 `id` 필드를 제거합니다 +- reasoning item이 아닌 항목은 영향을 받지 않습니다 -이 설정으로 **변경되지 않는 것**: +이 정책으로 **변경되지 않는** 것은 다음과 같습니다: -- 원문 모델 응답(`result.rawResponses`) +- 원시 모델 응답(`result.rawResponses`) - 실행 항목(`result.newItems`) -- provider 가 반환한 모델의 현재 턴 출력 +- provider가 반환한 모델의 현재 턴 출력 -즉, 이 정책은 SDK 가 이전에 생성된 항목으로부터 **다음 입력** 을 구성할 때 적용됩니다. +즉, 이 정책은 SDK가 이전 생성 항목으로부터 **다음 입력**을 구성할 때 적용됩니다. -정책은 실행별로 (`runner.run(..., { reasoningItemIdPolicy: 'omit' })`) 또는 runner 기본값으로 (`new Runner({ reasoningItemIdPolicy: 'omit', ... })`) 설정할 수 있습니다. 저장된 `RunState` 에서 재개할 때는 재정의하지 않는 한 이전에 결정된 정책이 재사용됩니다. +정책은 실행별(`runner.run(..., { reasoningItemIdPolicy: 'omit' })`) 또는 runner 기본값(`new Runner({ reasoningItemIdPolicy: 'omit', ... })`)으로 설정할 수 있습니다. 저장된 `RunState`에서 재개할 때는 재정의하지 않는 한 이전에 결정된 정책이 재사용됩니다. -#### `callModelInputFilter` 와의 상호작용 +#### `callModelInputFilter`와의 상호작용 -`reasoningItemIdPolicy` 는 `callModelInputFilter` 보다 먼저 적용됩니다. 커스텀 동작이 필요하다면, `callModelInputFilter` 가 준비된 입력을 검사하고 모델 호출 전에 reasoning ID 를 수동으로 다시 추가하거나 제거할 수 있습니다. +`reasoningItemIdPolicy`는 `callModelInputFilter`보다 먼저 적용됩니다. 커스텀 동작이 필요하다면 `callModelInputFilter`에서 준비된 입력을 검사하고 모델 호출 전에 reasoning ID를 수동으로 다시 추가하거나 제거할 수 있습니다. -#### `'omit'` 을 사용할 때 +#### `'omit'`를 사용할 때 -재생된 reasoning item 을 ID 없이 정규화하고 싶다면 `'omit'` 을 사용하세요(예: 전달/재생되는 모델 입력을 더 단순하게 유지하거나 앱 파이프라인의 통합 요구사항에 맞추기 위해). +ID 없는 형태로 재생된 reasoning item을 정규화하고 싶다면 `'omit'`를 사용하세요(예: 전달/재생되는 모델 입력을 더 단순하게 유지하거나 앱 파이프라인의 통합 요구사항에 맞추기 위해). -또한 백엔드/provider 가 재생된 reasoning item 을 요청 검증 오류로 거부하는 경우(예: 후속 입력의 reasoning item ID 와 관련된 HTTP `400` 오류) 유용한 문제 해결 옵션이기도 합니다. 이런 경우 `'omit'` 으로 재생된 reasoning ID 를 제거하면 백엔드가 새 요청에 대해 유효하지 않다고 간주하는 ID 전송을 피할 수 있습니다. +또한 백엔드/provider가 재생된 reasoning item을 요청 검증 오류로 거부하는 경우(예: 후속 입력의 reasoning item ID와 관련된 HTTP `400` 오류) 유용한 문제 해결 옵션이기도 합니다. 이런 경우 `'omit'`로 재생된 reasoning ID를 제거하면 백엔드가 새 요청에 대해 유효하지 않다고 간주하는 ID를 보내지 않게 할 수 있습니다. -SDK 가 재생된 입력 전반에 reasoning-item ID 를 유지하길 원하고 통합 환경에서도 이를 허용한다면 `'preserve'` 를 유지하세요. +재생된 입력에서도 SDK가 reasoning-item ID를 유지하길 원하고 통합 환경이 이를 허용한다면 `'preserve'`를 유지하세요. ## 오류 및 복구 ### Error handlers -`errorHandlers` 를 사용하면 지원되는 런타임 오류를 throw 하지 않고 최종 출력으로 변환할 수 있습니다. 현재는 `maxTurns` 만 지원됩니다. +`errorHandlers`를 사용하면 지원되는 런타임 오류를 예외로 던지는 대신 최종 출력으로 변환할 수 있습니다. 현재는 `maxTurns`만 지원됩니다. -- `errorHandlers.maxTurns` 는 max-turn 오류만 처리합니다 -- `errorHandlers.default` 는 지원되는 종류에 대한 fallback 으로 사용됩니다 -- 핸들러는 `{ error, context, runData }` 를 받고 `{ finalOutput, includeInHistory? }` 를 반환할 수 있습니다 +- `errorHandlers.maxTurns`는 max-turn 오류만 처리합니다 +- `errorHandlers.default`는 지원되는 종류에 대한 fallback으로 사용됩니다 +- 핸들러는 `{ error, context, runData }`를 받고 `{ finalOutput, includeInHistory? }`를 반환할 수 있습니다 ### 예외 -SDK 는 잡아서 처리할 수 있는 소수의 오류를 발생시킵니다: +SDK는 catch할 수 있는 소수의 오류를 발생시킵니다: -- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` 도달 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – 모델이 잘못된 출력을 생성함(예: 잘못된 JSON, 알 수 없는 도구) +- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns`에 도달한 경우 +- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – 모델이 유효하지 않은 출력(예: 잘못된 JSON, 알 수 없는 도구)을 생성한 경우 - [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) – 가드레일 위반 - [`ToolInputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/toolinputguardrailtripwiretriggered) / [`ToolOutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/tooloutputguardrailtripwiretriggered) – 도구 가드레일 위반 -- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – 가드레일이 완료되지 못함 -- [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror) – 함수 도구가 `timeoutMs` 를 초과했고 `timeoutBehavior: 'raise_exception'` 을 사용함 -- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 함수 도구 실행이 타임아웃이 아닌 오류로 실패함 -- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 설정 또는 사용자 입력을 기반으로 발생한 모든 오류 +- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – 가드레일이 완료되지 못한 경우 +- [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror) – 함수 도구가 `timeoutMs`를 초과했고 `timeoutBehavior: 'raise_exception'`을 사용한 경우 +- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – timeout이 아닌 오류로 함수 도구 실행이 실패한 경우 +- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 설정 또는 사용자 입력에 기반해 발생한 모든 오류 -모두 기본 `AgentsError` 클래스를 확장하며, 현재 실행 상태에 접근할 수 있는 `state` 속성을 제공할 수 있습니다. +이들은 모두 기본 `AgentsError` 클래스를 확장하며, 현재 실행 상태에 접근할 수 있는 `state` 속성을 제공할 수 있습니다. -다음은 `GuardrailExecutionError` 를 처리하는 코드 예제입니다. 입력 가드레일은 첫 번째 사용자 입력에서만 실행되므로, 이 예제는 원래 입력과 컨텍스트로 실행을 다시 시작합니다. 또한 저장된 상태를 재사용해 모델을 다시 호출하지 않고 출력 가드레일을 재시도하는 방법도 보여줍니다: +다음은 `GuardrailExecutionError`를 처리하는 코드 예제입니다. 입력 가드레일은 첫 번째 사용자 입력에서만 실행되므로, 이 예제에서는 원래 입력과 컨텍스트로 실행을 다시 시작합니다. 또한 저장된 상태를 재사용해 모델을 다시 호출하지 않고 출력 가드레일을 재시도하는 방법도 보여줍니다: -입력 vs. 출력 재시도: +입력 재시도와 출력 재시도의 차이: -- 입력 가드레일은 실행의 첫 번째 사용자 입력에서만 실행되므로, 재시도하려면 같은 입력/컨텍스트로 새 실행을 시작해야 합니다. 저장된 `state` 를 전달해도 입력 가드레일은 다시 실행되지 않습니다 -- 출력 가드레일은 모델 응답 후에 실행되므로, `GuardrailExecutionError` 의 저장된 `state` 를 재사용해 모델을 다시 호출하지 않고 출력 가드레일을 다시 실행할 수 있습니다 +- 입력 가드레일은 실행의 첫 번째 사용자 입력에서만 실행되므로, 이를 재시도하려면 같은 입력/컨텍스트로 새 실행을 시작해야 합니다. 저장된 `state`를 전달해도 입력 가드레일은 다시 트리거되지 않습니다. +- 출력 가드레일은 모델 응답 후에 실행되므로, `GuardrailExecutionError`의 저장된 `state`를 재사용해 추가 모델 호출 없이 출력 가드레일을 다시 실행할 수 있습니다. 위 예제를 실행하면 다음 출력이 표시됩니다: @@ -275,9 +279,9 @@ Output guardrail tripped after retry with saved state ## 관련 가이드 -- 실행하기 전에 에이전트를 정의하려면 [에이전트](/openai-agents-js/ko/guides/agents) +- 실행 전에 에이전트를 정의하는 방법은 [에이전트](/openai-agents-js/ko/guides/agents) - `finalOutput`, 실행 항목, 인터럽션(중단 처리), 재개 상태는 [실행 결과](/openai-agents-js/ko/guides/results) - 영속적인 SDK 관리형 메모리는 [세션](/openai-agents-js/ko/guides/sessions) - 실행 루프 중 사용되는 기능은 [도구](/openai-agents-js/ko/guides/tools) - provider 설정과 Responses 전송은 [모델](/openai-agents-js/ko/guides/models) -- 프로덕션 준비를 위해 [가드레일](/openai-agents-js/ko/guides/guardrails) 또는 [트레이싱](/openai-agents-js/ko/guides/tracing) 추가 +- 프로덕션 준비를 위해 [가드레일](/openai-agents-js/ko/guides/guardrails) 또는 [트레이싱](/openai-agents-js/ko/guides/tracing)을 추가하세요 diff --git a/docs/src/content/docs/ko/guides/sandbox-agents.mdx b/docs/src/content/docs/ko/guides/sandbox-agents.mdx new file mode 100644 index 000000000..288081c87 --- /dev/null +++ b/docs/src/content/docs/ko/guides/sandbox-agents.mdx @@ -0,0 +1,66 @@ +--- +title: 빠른 시작 +description: Create your first sandbox agent with an isolated workspace, filesystem tools, shell commands, and sandbox session state. +--- + +import { Aside, Code } from '@astrojs/starlight/components'; +import basicExample from '../../../../../../examples/docs/sandbox-agents/basic.ts?raw'; + + + +현대적인 에이전트는 파일시스템의 실제 파일을 대상으로 작업할 수 있을 때 가장 잘 동작합니다. Agents SDK의 **Sandbox Agents**는 모델에 지속적인 워크스페이스를 제공하여 대규모 문서 집합 검색, 파일 편집, 명령 실행, 아티팩트 생성, 저장된 sandbox 상태에서 작업 재개를 가능하게 합니다. + +SDK는 파일 스테이징, 파일시스템 도구, 셸 접근, sandbox 수명 주기, 스냅샷, 제공자별 연결 코드를 직접 조합하지 않아도 이 실행 하네스를 제공합니다. 일반적인 `Agent` 및 `Runner` 흐름은 그대로 유지하면서, 워크스페이스용 `Manifest`, sandbox 네이티브 도구용 capabilities, 그리고 작업 실행 위치를 지정하는 `sandbox` 실행 옵션만 추가하면 됩니다. + +## 사전 요구 사항 + +- Node.js 22 이상 +- OpenAI Agents SDK에 대한 기본적인 이해 +- sandbox 클라이언트. 로컬 개발에서는 `UnixLocalSandboxClient`로 시작하세요 + +## 설치 + +아직 SDK를 설치하지 않았다면 다음을 실행하세요: + +```bash +npm install @openai/agents +``` + +Docker 기반 sandbox를 사용하려면 로컬에 Docker를 설치하고 `@openai/agents/sandbox/local`의 `DockerSandboxClient`를 사용하세요. + +`tty: true`로 대화형 로컬 PTY 세션을 사용하는 경우, SDK를 실행하는 프로세스에도 `python3`로 사용할 수 있는 Python 3 또는 `OPENAI_AGENTS_PYTHON`을 통한 Python 3가 필요합니다. PTY가 아닌 셸 명령에는 Python이 필요하지 않습니다. + +## 로컬 sandbox 에이전트 생성 + +이 예제는 `repo/` 아래의 로컬 리포지토리를 스테이징하고, 로컬 skills를 지연 로드하며, runner가 실행을 위해 Unix-local sandbox 세션을 생성하도록 합니다. + + + +이 예제는 의도적으로 Python SDK 빠른 시작과 유사한 형태로 구성되어 있습니다. 에이전트 정의가 manifest와 capabilities를 소유하고, 실행 구성은 이번 실행에 사용할 sandbox 클라이언트만 선택합니다. + +## 주요 선택 사항 + +기본 실행이 동작하면, 대부분의 사용자가 다음으로 선택하는 항목은 다음과 같습니다: + +- `defaultManifest`: 새 sandbox 세션에 사용할 파일, 리포지토리, 디렉터리, 마운트 +- `instructions`: 프롬프트 전반에 적용할 짧은 워크플로 규칙 +- `baseInstructions`: SDK sandbox 프롬프트를 대체하기 위한 고급 escape hatch +- `capabilities`: 파일시스템 편집/이미지 검사, 셸, skills, 메모리, compaction 같은 sandbox 네이티브 도구 +- `runAs`: 모델 대상 도구에 사용할 sandbox 사용자 ID +- `sandbox.client`: sandbox 백엔드 +- `sandbox.session`, `sandbox.sessionState`, 또는 `sandbox.snapshot`: 이후 실행이 이전 작업에 다시 연결하는 방법 + +## 다음 단계 + +- [Concepts](/openai-agents-js/ko/guides/sandbox-agents/concepts): manifest, capabilities, 권한, 스냅샷, 실행 구성, 조합 패턴을 이해합니다 +- [Sandbox clients](/openai-agents-js/ko/guides/sandbox-agents/clients): Unix-local, Docker, 호스티드 제공자, 마운트 전략 중에서 선택합니다 +- [Agent memory](/openai-agents-js/ko/guides/sandbox-agents/memory): 이전 sandbox 실행에서 얻은 교훈을 보존하고 재사용합니다 + +셸 접근이 가끔 사용하는 도구 하나에 불과하다면 [도구](/openai-agents-js/ko/guides/tools)에서 호스티드 셸로 시작하세요. 워크스페이스 격리, sandbox 클라이언트 선택, 또는 sandbox 세션 재개 동작이 설계의 일부라면 sandbox 에이전트를 선택하세요. diff --git a/docs/src/content/docs/ko/guides/tools.mdx b/docs/src/content/docs/ko/guides/tools.mdx index d3918ef59..c7c4d8a82 100644 --- a/docs/src/content/docs/ko/guides/tools.mdx +++ b/docs/src/content/docs/ko/guides/tools.mdx @@ -16,60 +16,64 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer import codexToolExample from '../../../../../../examples/docs/tools/codexTool.ts?raw'; import codexRunContextThreadExample from '../../../../../../examples/docs/tools/codexRunContextThread.ts?raw'; -도구를 사용하면 에이전트가 **작업을 수행**할 수 있습니다. 데이터를 가져오고, 외부 API 를 호출하고, 코드를 실행하고, 심지어 컴퓨터를 사용할 수도 있습니다. JavaScript/TypeScript SDK 는 여섯 가지 카테고리를 지원합니다. +도구를 사용하면 Agent가 **작업을 수행**할 수 있습니다. 예를 들어 데이터를 가져오고, 외부 API를 호출하고, 코드를 실행하거나, 심지어 컴퓨터를 사용할 수도 있습니다. JavaScript/TypeScript SDK는 7가지 카테고리를 지원합니다. -> 이 페이지는 [에이전트](/openai-agents-js/ko/guides/agents)를 읽은 뒤, 어떤 에이전트가 작업을 담당해야 하는지 알고 그 에이전트에 기능을 부여하려고 할 때 읽어보세요. 아직 위임 패턴 사이에서 결정 중이라면 [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent)을 참고하세요. +> 어떤 에이전트가 작업을 맡아야 하는지 알고 있고 그 에이전트에 기능을 부여하려는 경우, 먼저 [에이전트](/openai-agents-js/guides/agents) 다음에 이 페이지를 읽어보세요. 아직 위임 패턴을 결정하는 중이라면 [에이전트 오케스트레이션](/openai-agents-js/guides/multi-agent)을 참고하세요. -1. **Hosted OpenAI tools** – OpenAI 서버에서 모델과 함께 실행됩니다. _(웹 검색, 파일 검색, 코드 인터프리터, 이미지 생성, 도구 검색)_ -2. **기본 제공 실행 도구** – 모델 외부에서 실행되는 SDK 제공 도구입니다. _(computer use 와 apply_patch 는 로컬에서 실행되고, shell 은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다)_ -3. **함수 도구** – JSON 스키마로 로컬 함수를 감싸 LLM 이 호출할 수 있게 합니다. -4. **Agents as tools** – 전체 에이전트를 호출 가능한 도구로 노출합니다. +1. **OpenAI 호스트하는 도구** – OpenAI 서버에서 모델과 함께 실행됩니다. _(웹 검색, 파일 검색, code interpreter, 이미지 생성, tool search)_ +2. **내장 실행 도구** – 모델 외부에서 실행되는 SDK 제공 도구입니다. _(computer use와 apply_patch는 로컬에서 실행되며, shell은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다)_ +3. **함수 도구** – JSON schema로 로컬 함수를 감싸 LLM이 호출할 수 있게 합니다. +4. **Agents as tools** – 전체 Agent를 호출 가능한 도구로 노출합니다. 5. **MCP 서버** – Model Context Protocol 서버(로컬 또는 원격)를 연결합니다. -6. **실험적 기능: Codex 도구** – Codex SDK 를 함수 도구로 감싸 workspace 인식 작업을 실행합니다. +6. **Sandbox 기능** – `SandboxAgent`에 작업 공간 범위의 shell, 파일 시스템, skills, memory 또는 compaction 도구를 연결합니다. +7. **실험적 기능: Codex 도구** – Codex SDK를 함수 도구로 감싸 작업 공간 인식 작업을 실행합니다. --- ## 도구 카테고리 -이 가이드의 나머지 부분에서는 먼저 각 도구 카테고리를 설명한 뒤, 공통으로 적용되는 도구 선택 및 프롬프팅 지침을 요약합니다. +이 가이드의 나머지 부분에서는 먼저 각 도구 카테고리를 설명한 다음, 여러 카테고리에 공통되는 도구 선택 및 프롬프팅 지침을 요약합니다. -### 1. Hosted tool(OpenAI Responses API) +### 1. 호스티드 툴 (OpenAI Responses API) -`OpenAIResponsesModel` 을 사용할 때 다음과 같은 기본 제공 도구를 추가할 수 있습니다. +`OpenAIResponsesModel`을 사용할 때 다음 내장 도구를 추가할 수 있습니다. -| Tool | Type string | Purpose | +| 도구 | 타입 문자열 | 용도 | | --- | --- | --- | | 웹 검색 | `'web_search'` | 인터넷 검색 | -| 파일 / 검색 검색 | `'file_search'` | OpenAI 에 호스팅된 벡터 스토어를 조회합니다 | +| 파일 / 검색 검색 | `'file_search'` | OpenAI에 호스팅된 벡터 스토어를 조회합니다 | | Code Interpreter | `'code_interpreter'` | 샌드박스 환경에서 코드를 실행합니다 | | 이미지 생성 | `'image_generation'` | 텍스트를 기반으로 이미지를 생성합니다 | -| 도구 검색 | `'tool_search'` | 지연 함수 도구, 네임스페이스 또는 검색 가능한 MCP 도구를 런타임에 로드합니다 | +| 도구 검색 | `'tool_search'` | 런타임에 지연 함수 도구, 네임스페이스 또는 검색 가능한 MCP 도구를 로드합니다 | -SDK 는 hosted tool 정의를 반환하는 헬퍼 함수를 제공합니다. +SDK는 호스티드 툴 정의를 반환하는 헬퍼 함수를 제공합니다. -| Helper function | Notes | +| 헬퍼 함수 | 참고 | | --- | --- | -| `webSearchTool(options?)` | `searchContextSize`, `userLocation`, `filters.allowedDomains` 와 같은 JS 친화적 옵션을 제공합니다 | -| `fileSearchTool(ids, options?)` | 첫 번째 인수로 하나 이상의 벡터 스토어 ID 를 받고, `maxNumResults`, `includeSearchResults`, `rankingOptions`, 필터 등의 옵션을 추가로 받습니다 | -| `codeInterpreterTool(options?)` | `container` 를 제공하지 않으면 자동 관리 컨테이너를 기본값으로 사용합니다 | -| `imageGenerationTool(options?)` | `model`, `size`, `quality`, `background`, `inputFidelity`, `inputImageMask`, `moderation`, `outputCompression`, `partialImages`, 출력 형식 등 이미지 생성 설정을 지원합니다 | -| `toolSearchTool(options?)` | 기본 제공 `tool_search` 헬퍼를 추가합니다. `deferLoading: true` 를 설정한 지연 함수 도구 또는 호스티드 MCP 도구와 함께 사용하세요. 기본적으로 hosted execution 을 지원하며, `execution: 'client'` 와 `execute` 를 함께 사용하면 클라이언트 실행도 가능합니다 | +| `webSearchTool(options?)` | `searchContextSize`, `userLocation`, `filters.allowedDomains` 같은 JS 친화적 옵션을 제공합니다 | +| `fileSearchTool(ids, options?)` | 첫 번째 인수로 하나 이상의 벡터 스토어 ID를 받고, `maxNumResults`, `includeSearchResults`, `rankingOptions`, filters 같은 옵션을 추가로 받습니다 | +| `codeInterpreterTool(options?)` | `container`를 제공하지 않으면 자동 관리 컨테이너를 기본값으로 사용합니다 | +| `imageGenerationTool(options?)` | `model`, `size`, `quality`, `background`, `inputFidelity`, `inputImageMask`, `moderation`, `outputCompression`, `partialImages`, 출력 형식 등의 이미지 생성 구성을 지원합니다 | +| `toolSearchTool(options?)` | 내장 `tool_search` 헬퍼를 추가합니다. `deferLoading: true`를 설정한 지연 함수 도구 또는 호스티드 MCP 도구와 함께 사용하세요. 기본적으로 호스티드 실행을 지원하며, `execution: 'client'`와 `execute`를 함께 사용하면 클라이언트 실행도 가능합니다 | -이 헬퍼들은 JavaScript/TypeScript 친화적인 옵션 이름을 기반 OpenAI Responses API 도구 페이로드로 매핑합니다. 전체 도구 스키마와 ranking options 또는 semantic filters 같은 고급 옵션은 공식 [OpenAI tools guide](https://developers.openai.com/api/docs/guides/tools)를, 현재 기본 제공 도구 검색 흐름과 모델 지원 범위는 공식 [Tool search guide](https://developers.openai.com/api/docs/guides/tools-tool-search)를 참고하세요. +이 헬퍼들은 JavaScript/TypeScript 친화적인 옵션 이름을 내부 OpenAI Responses API 도구 payload로 매핑합니다. 전체 도구 schema와 ranking options, semantic filters 같은 고급 옵션은 공식 [OpenAI 도구 가이드](https://developers.openai.com/api/docs/guides/tools)를 참고하고, 현재 내장 도구 검색 흐름과 모델 지원 여부는 공식 [Tool search guide](https://developers.openai.com/api/docs/guides/tools-tool-search)를 참고하세요. --- -### 2. 기본 제공 실행 도구 +### 2. 내장 실행 도구 -이 도구들은 SDK 에 내장되어 있지만, 실행은 모델 응답 자체 바깥에서 이루어집니다. +이 도구들은 SDK에 내장되어 있지만, 실행은 모델 응답 자체 밖에서 이루어집니다. -- **컴퓨터 사용** – `Computer` 인터페이스를 구현하고 `computerTool()` 에 전달합니다. 이것은 항상 사용자가 제공한 로컬 `Computer` 구현을 대상으로 실행됩니다 -- **Shell** – 로컬 `Shell` 구현을 제공하거나, `shellTool({ environment })` 로 호스티드 컨테이너 환경을 설정할 수 있습니다 -- **Apply patch** – `Editor` 인터페이스를 구현하고 `applyPatchTool()` 에 전달합니다. 이것은 항상 사용자가 제공한 로컬 `Editor` 구현을 대상으로 실행됩니다 +- **컴퓨터 사용** – `Computer` 인터페이스를 구현하고 `computerTool()`에 전달합니다. 이는 항상 사용자가 제공한 로컬 `Computer` 구현을 대상으로 실행됩니다 +- **Shell** – 로컬 `Shell` 구현을 제공하거나, `shellTool({ environment })`로 호스티드 컨테이너 환경을 구성합니다 +- **Apply patch** – `Editor` 인터페이스를 구현하고 `applyPatchTool()`에 전달합니다. 이는 항상 사용자가 제공한 로컬 `Editor` 구현을 대상으로 실행됩니다 +- **Sandbox shell 및 파일 시스템 도구** – 해당 작업을 sandbox 작업 공간 내부에서 실행해야 한다면 `SandboxAgent`에서 `shell()`, `filesystem()`, `skills()`, `memory()`, `compaction()`을 사용합니다 -도구 호출은 여전히 모델이 요청하지만, 실제 작업은 애플리케이션이나 설정된 실행 환경이 수행합니다. +도구 호출은 여전히 모델이 요청하지만, 실제 작업은 애플리케이션이나 구성된 실행 환경이 수행합니다. + +Sandbox 기능 도구는 프로세스 전역 내장 도구와 다릅니다. 이 도구들은 현재 `SandboxAgent` 실행의 활성 sandbox 세션에 바인딩됩니다. 도구가 애플리케이션 프로세스 대신 에이전트의 격리된 작업 공간에서 작동해야 한다면 [Sandbox agents](/openai-agents-js/guides/sandbox-agents)를 사용하세요. string \| unknown \| Promise<...>` – 비즈니스 로직입니다. 문자열이 아닌 출력은 모델용으로 직렬화됩니다. `context` 는 선택적 `RunContext` 이고, `details` 에는 `toolCall`, `resumeState`, `signal` 같은 메타데이터가 포함됩니다 | -| `errorFunction` | 아니요 | 내부 오류를 사용자에게 보이는 문자열로 변환하는 사용자 정의 핸들러 `(context, error) => string` | -| `timeoutMs` | 아니요 | 호출별 타임아웃(밀리초)입니다. 0 보다 커야 하고 `2147483647` 이하여야 합니다 | -| `timeoutBehavior` | 아니요 | 타임아웃 모드입니다. `error_as_result`(기본값)는 모델에 보이는 타임아웃 메시지를 반환하고, `raise_exception` 은 `ToolTimeoutError` 를 발생시킵니다 | -| `timeoutErrorFunction` | 아니요 | `timeoutBehavior` 가 `error_as_result` 일 때 타임아웃 출력을 위한 사용자 정의 핸들러 `(context, timeoutError) => string` | -| `needsApproval` | 아니요 | 실행 전에 사람의 승인을 요구합니다. [휴먼 인 더 루프 (HITL) 가이드](/openai-agents-js/ko/guides/human-in-the-loop)를 참고하세요 | -| `isEnabled` | 아니요 | 실행별로 도구 노출 여부를 조건부로 설정합니다. boolean 또는 predicate 를 받을 수 있습니다 | -| `inputGuardrails` | 아니요 | 도구 실행 전에 동작하는 가드레일입니다. 거부하거나 예외를 던질 수 있습니다. [가드레일](/openai-agents-js/ko/guides/guardrails#tool-guardrails)을 참고하세요 | -| `outputGuardrails` | 아니요 | 도구 실행 후에 동작하는 가드레일입니다. 거부하거나 예외를 던질 수 있습니다. [가드레일](/openai-agents-js/ko/guides/guardrails#tool-guardrails)을 참고하세요 | +| `name` | 아니요 | 기본값은 함수 이름입니다(예: `get_weather`) | +| `description` | 예 | LLM에 표시되는 명확하고 사람이 읽기 쉬운 설명 | +| `parameters` | 예 | Zod schema 또는 원시 JSON schema 객체입니다. Zod 매개변수는 자동으로 **strict** 모드를 활성화합니다 | +| `strict` | 아니요 | `true`(기본값)일 때 인수가 검증에 실패하면 SDK가 모델 오류를 반환합니다. 유연한 매칭을 원하면 `false`로 설정하세요 | +| `execute` | 예 | `(args, context, details) => string \| unknown \| Promise<...>` – 비즈니스 로직입니다. 문자열이 아닌 출력은 모델용으로 직렬화됩니다. `context`는 선택적인 `RunContext`이며, `details`에는 `toolCall`, `resumeState`, `signal` 같은 메타데이터가 포함됩니다 | +| `errorFunction` | 아니요 | 내부 오류를 사용자에게 보이는 문자열로 변환하는 사용자 지정 핸들러 `(context, error) => string` | +| `timeoutMs` | 아니요 | 호출별 제한 시간(밀리초)입니다. 0보다 커야 하고 `2147483647` 이하여야 합니다 | +| `timeoutBehavior` | 아니요 | 제한 시간 모드입니다. `error_as_result`(기본값)는 모델에 보이는 제한 시간 메시지를 반환하고, `raise_exception`은 `ToolTimeoutError`를 던집니다 | +| `timeoutErrorFunction` | 아니요 | `timeoutBehavior`가 `error_as_result`일 때 제한 시간 출력을 위한 사용자 지정 핸들러 `(context, timeoutError) => string` | +| `needsApproval` | 아니요 | 실행 전에 사람의 승인을 요구합니다. [휴먼 인 더 루프 (HITL)](/openai-agents-js/guides/human-in-the-loop)를 참고하세요 | +| `isEnabled` | 아니요 | 실행별로 도구를 조건부로 노출합니다. boolean 또는 predicate를 받을 수 있습니다 | +| `inputGuardrails` | 아니요 | 도구 실행 전에 실행되는 가드레일입니다. 거부하거나 예외를 던질 수 있습니다. [가드레일](/openai-agents-js/guides/guardrails#tool-guardrails)을 참고하세요 | +| `outputGuardrails` | 아니요 | 도구 실행 후에 실행되는 가드레일입니다. 거부하거나 예외를 던질 수 있습니다. [가드레일](/openai-agents-js/guides/guardrails#tool-guardrails)을 참고하세요 | -#### 함수 도구 타임아웃 +#### 함수 도구 제한 시간 -각 함수 도구 호출 시간을 제한하려면 `timeoutMs` 를 사용하세요. +각 함수 도구 호출 시간을 제한하려면 `timeoutMs`를 사용하세요. -- `timeoutBehavior: 'error_as_result'`(기본값)는 모델에 `Tool '' timed out after ms.` 를 반환합니다 -- `timeoutBehavior: 'raise_exception'` 은 [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror)를 발생시키며, 이를 [실행 예외](/openai-agents-js/ko/guides/running-agents#exceptions)의 일부로 잡을 수 있습니다 -- `timeoutErrorFunction` 을 사용하면 `error_as_result` 모드에서 타임아웃 메시지를 사용자 정의할 수 있습니다 -- 타임아웃이 발생하면 `details.signal` 이 중단되므로, 장시간 실행 도구는 취소를 감지할 때 빠르게 멈출 수 있습니다 +- `timeoutBehavior: 'error_as_result'`(기본값)는 모델에 `Tool '' timed out after ms.`를 반환합니다 +- `timeoutBehavior: 'raise_exception'`은 [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror)를 던지며, 이는 [에이전트 실행](/openai-agents-js/guides/running-agents#exceptions)의 실행 예외 처리 일부로 잡을 수 있습니다 +- `timeoutErrorFunction`을 사용하면 `error_as_result` 모드에서 제한 시간 텍스트를 사용자 지정할 수 있습니다 +- 제한 시간이 발생하면 `details.signal`이 중단되므로, 오래 실행되는 도구는 취소를 감지할 때 즉시 중단할 수 있습니다 -함수 도구를 직접 호출하는 경우 [`invokeFunctionTool`](/openai-agents-js/openai/agents/functions/invokefunctiontool)을 사용하면 일반 에이전트 실행과 동일한 타임아웃 동작을 적용할 수 있습니다. +함수 도구를 직접 호출하는 경우, 일반 에이전트 실행과 동일한 제한 시간 동작을 강제하려면 [`invokeFunctionTool`](/openai-agents-js/openai/agents/functions/invokefunctiontool)을 사용하세요. -#### Non-strict JSON-schema 도구 +#### 비엄격 JSON-schema 도구 -모델이 잘못되거나 불완전한 입력을 _추정_ 하게 해야 한다면 원문 JSON 스키마를 사용할 때 strict 모드를 비활성화할 수 있습니다. +모델이 잘못되었거나 부분적인 입력을 _추정_ 하도록 해야 한다면 원시 JSON schema 사용 시 strict 모드를 비활성화할 수 있습니다. -#### 도구 검색을 통한 지연 도구 로딩 +#### 도구 검색을 사용한 지연 도구 로딩 -도구 검색을 사용하면 모든 스키마를 미리 보내는 대신, 모델이 런타임에 필요한 도구 정의만 로드할 수 있습니다. SDK 에서는 이를 통해 지연 top-level 함수 도구, `toolNamespace()` 그룹, 그리고 `deferLoading: true` 로 설정된 호스티드 MCP 도구를 사용할 수 있습니다. +도구 검색을 사용하면 모든 schema를 미리 보내는 대신, 모델이 런타임에 필요한 도구 정의만 로드할 수 있습니다. SDK에서는 지연 최상위 함수 도구, `toolNamespace()` 그룹, 그리고 `deferLoading: true`로 구성된 호스티드 MCP 도구를 이런 방식으로 사용할 수 있습니다. -도구 검색은 Responses API 에서 이를 지원하는 GPT-5.4 이상 모델 릴리스에서만 사용하세요. +도구 검색은 Responses API에서 이를 지원하는 GPT-5.4 이상 모델 릴리스에서만 사용하세요. -이 예제는 의도적으로 두 스타일을 혼합합니다. +이 예제는 의도적으로 두 가지 스타일을 섞어 사용합니다. -- `shippingLookup` 은 독립적인 검색 가능 기능 하나이므로 top-level 로 유지됩니다 -- `crmTools` 는 관련된 CRM 도구들이 하나의 상위 레이블과 설명을 공유하므로 `toolNamespace()` 를 사용합니다 -- 같은 요청에서 네임스페이스가 있는 지연 도구와 top-level 지연 도구를 함께 사용하는 것이 지원됩니다. 도구 검색은 `crm` 같은 네임스페이스 경로와 `get_shipping_eta` 같은 top-level 경로를 모두 로드할 수 있습니다 +- `shippingLookup`은 독립적인 검색 가능 기능 하나이므로 최상위로 유지됩니다 +- `crmTools`는 관련된 CRM 도구들이 하나의 상위 레이블과 설명을 공유하므로 `toolNamespace()`를 사용합니다 +- 동일한 요청에서 네임스페이스 도구와 최상위 지연 도구를 함께 사용하는 것이 지원됩니다. 도구 검색은 `crm` 같은 네임스페이스 경로와 `get_shipping_eta` 같은 최상위 경로를 모두 로드할 수 있습니다 도구 검색을 사용할 때는 다음을 따르세요. -- 각 지연 함수 도구에 `deferLoading: true` 를 설정하세요 -- 여러 관련 도구가 하나의 도메인 설명을 공유하고 그룹으로 로드되어야 한다면 `toolNamespace({ name, description, tools })` 를 사용하세요 -- 도구가 하나의 독립 기능이고 도구 이름 자체가 좋은 검색 대상이라면 top-level 로 유지하세요 -- 지연 함수 도구나 호스티드 MCP 도구 중 하나라도 `deferLoading: true` 를 사용한다면 같은 `tools` 배열에 `toolSearchTool()` 을 추가하세요 -- `modelSettings.toolChoice` 는 `'auto'` 로 두세요. SDK 는 기본 제공 `tool_search` 도구를 강제하거나 지연 함수 도구를 이름으로 강제하는 것을 거부합니다 -- 기본값은 hosted execution 입니다. `toolSearchTool({ execution: 'client', execute })` 를 설정한 경우 표준 `run()` 루프는 기본 제공 `{ paths: string[] }` 클라이언트 쿼리 형태만 지원하며, 사용자 정의 클라이언트 측 스키마는 별도의 Responses 루프가 필요합니다 -- 네임스페이스는 즉시 로드되는 멤버와 지연 멤버를 함께 포함할 수 있습니다. 즉시 멤버는 도구 검색 없이도 계속 호출 가능하고, 같은 네임스페이스의 지연 멤버는 필요 시 로드됩니다 -- 지연 함수 도구와 `toolNamespace()` 는 Responses 전용입니다. Chat Completions 는 이를 거부하며, AI SDK 어댑터도 지연 Responses 도구 로딩 흐름을 지원하지 않습니다 +- 각 지연 함수 도구에 `deferLoading: true`를 설정합니다 +- 여러 관련 도구가 하나의 도메인 설명을 공유하고 그룹으로 로드되어야 한다면 `toolNamespace({ name, description, tools })`를 사용합니다 +- 단일 독립 기능이고 도구 이름 자체가 좋은 검색 대상이라면 도구를 최상위에 둡니다 +- 지연 함수 도구 또는 호스티드 MCP 도구에서 `deferLoading: true`를 사용하는 경우 같은 `tools` 배열에 `toolSearchTool()`을 추가합니다 +- `modelSettings.toolChoice`는 `'auto'`로 유지합니다. SDK는 내장 `tool_search` 도구 또는 지연 함수 도구를 이름으로 강제하는 것을 거부합니다 +- 기본값은 호스티드 실행입니다. `toolSearchTool({ execution: 'client', execute })`를 설정하면 표준 `run()` 루프는 내장 `{ paths: string[] }` 클라이언트 질의 형식만 지원하며, 사용자 지정 클라이언트 측 schema를 사용하려면 자체 Responses 루프가 필요합니다 +- 네임스페이스는 즉시 로드 멤버와 지연 로드 멤버를 혼합할 수 있습니다. 즉시 멤버는 도구 검색 없이도 호출 가능하며, 동일 네임스페이스 내 지연 멤버는 필요 시 로드됩니다 +- 지연 함수 도구와 `toolNamespace()`는 Responses 전용입니다. Chat Completions는 이를 거부하며, AI SDK 어댑터는 지연 Responses 도구 로딩 흐름을 지원하지 않습니다 --- ### 4. Agents as tools -때로는 한 에이전트가 대화를 완전히 핸드오프하지 않고 다른 에이전트를 _보조_ 하게 만들고 싶을 수 있습니다. 이럴 때 `agent.asTool()` 을 사용하세요. +때로는 대화를 완전히 핸드오프하지 않고 한 Agent가 다른 Agent를 _보조_ 하도록 하고 싶을 수 있습니다. 이때 `agent.asTool()`을 사용하세요. -아직 `agent.asTool()` 과 `handoff()` 중에서 선택 중이라면 [에이전트 가이드](/openai-agents-js/ko/guides/agents#composition-patterns)와 [에이전트 오케스트레이션](/openai-agents-js/ko/guides/multi-agent)의 패턴 비교를 참고하세요. +아직 `agent.asTool()`과 `handoff()` 중 무엇을 사용할지 결정 중이라면 [에이전트](/openai-agents-js/guides/agents#composition-patterns)와 [에이전트 오케스트레이션](/openai-agents-js/guides/multi-agent)에서 패턴을 비교해 보세요. -내부적으로 SDK 는 다음을 수행합니다. +내부적으로 SDK는 다음을 수행합니다. - 단일 `input` 매개변수를 가진 함수 도구를 생성합니다 - 도구가 호출되면 해당 입력으로 하위 에이전트를 실행합니다 -- 마지막 메시지 또는 `customOutputExtractor` 가 추출한 출력을 반환합니다 +- 마지막 메시지 또는 `customOutputExtractor`가 추출한 출력을 반환합니다 -에이전트를 도구로 실행하면 Agents SDK 는 기본 설정으로 runner 를 생성하고 함수 실행 안에서 그 runner 로 에이전트를 실행합니다. `runConfig` 또는 `runOptions` 의 속성을 제공하려면 `asTool()` 메서드에 전달하여 runner 동작을 사용자 정의할 수 있습니다. +에이전트를 도구로 실행하면 Agents SDK는 기본 설정으로 runner를 생성하고 함수 실행 안에서 해당 runner로 에이전트를 실행합니다. `runConfig` 또는 `runOptions`의 속성을 제공하려면 `asTool()` 메서드에 전달하여 runner 동작을 사용자 지정할 수 있습니다. -또한 `asTool()` 옵션을 통해 에이전트 도구에 `needsApproval` 과 `isEnabled` 를 설정하여 휴먼 인 더 루프 흐름 및 조건부 도구 가용성과 통합할 수 있습니다. +또한 `asTool()` 옵션을 통해 에이전트 도구에 `needsApproval`과 `isEnabled`를 설정하여 휴먼인더루프 (HITL) 흐름 및 조건부 도구 가용성과 통합할 수 있습니다. -`customOutputExtractor` 내부에서는 `result.agentToolInvocation` 을 사용해 현재 `Agent.asTool()` 호출을 확인하세요. 이 콜백에서 결과는 항상 `Agent.asTool()` 에서 오므로 `agentToolInvocation` 은 항상 정의되어 있고 `toolName`, `toolCallId`, `toolArguments` 를 노출합니다. 일반 앱 컨텍스트와 `toolInput` 은 `result.runContext` 를 사용하세요. 이 메타데이터는 현재 중첩 호출 범위로 제한되며 `RunState` 에 직렬화되지 않습니다. +`customOutputExtractor` 내부에서는 `result.agentToolInvocation`을 사용해 현재 `Agent.asTool()` 호출을 확인하세요. 이 콜백에서 결과는 항상 `Agent.asTool()`에서 오므로 `agentToolInvocation`은 항상 정의되어 있으며 `toolName`, `toolCallId`, `toolArguments`를 노출합니다. 일반 애플리케이션 컨텍스트와 `toolInput`에는 `result.runContext`를 사용하세요. 이 메타데이터는 현재 중첩 호출 범위에 한정되며 `RunState`에 직렬화되지 않습니다. -`agent.asTool()` 의 고급 structured-input 옵션: +`agent.asTool()`의 고급 구조화 입력 옵션: -- `inputBuilder`: 구조화된 도구 인수를 중첩 에이전트 입력 페이로드로 매핑합니다 -- `includeInputSchema`: 더 강한 스키마 인식 동작을 위해 중첩 실행에 입력 JSON 스키마를 포함합니다 -- `resumeState`: 중첩 직렬화 `RunState` 를 재개할 때 컨텍스트 조정 전략을 제어합니다. `'merge'`(기본값)는 현재 승인/컨텍스트 상태를 직렬화된 상태에 병합하고, `'replace'` 는 대신 현재 실행 컨텍스트를 사용하며, `'preferSerialized'` 는 직렬화된 컨텍스트를 변경하지 않고 그대로 재개합니다 +- `inputBuilder`: 구조화된 도구 인수를 중첩 에이전트 입력 payload로 매핑합니다 +- `includeInputSchema`: 더 강한 schema 인식 동작을 위해 입력 JSON schema를 중첩 실행에 포함합니다 +- `resumeState`: 중첩된 직렬화 `RunState`를 재개할 때 컨텍스트 조정 전략을 제어합니다. `'merge'`(기본값)는 활성 승인/컨텍스트 상태를 직렬화된 상태에 병합하고, `'replace'`는 대신 현재 실행 컨텍스트를 사용하며, `'preferSerialized'`는 직렬화된 컨텍스트를 변경하지 않고 그대로 재개합니다 #### 에이전트 도구의 스트리밍 이벤트 -에이전트 도구는 모든 중첩 실행 이벤트를 앱으로 스트리밍할 수 있습니다. 도구를 구성하는 방식에 맞는 hook 스타일을 선택하세요. +에이전트 도구는 모든 중첩 실행 이벤트를 애플리케이션으로 스트리밍할 수 있습니다. 도구를 구성하는 방식에 맞는 훅 스타일을 선택하세요. -- 이벤트 타입은 `RunStreamEvent['type']` 과 일치합니다: `raw_model_stream_event`, `run_item_stream_event`, `agent_updated_stream_event` -- `onStream` 은 가장 단순한 "catch-all" 방식이며 도구를 인라인으로 선언할 때(`tools: [agent.asTool({ onStream })]`) 잘 맞습니다. 이벤트별 분기가 필요 없다면 이것을 사용하세요 -- `on(eventName, handler)` 는 선택적으로(또는 `'*'` 로) 구독할 수 있게 해주며, 더 세밀한 처리가 필요하거나 생성 후 리스너를 붙이고 싶을 때 가장 적합합니다 -- `onStream` 이나 어떤 `on(...)` 핸들러라도 제공하면 agent-as-tool 은 자동으로 스트리밍 모드로 실행됩니다. 이것들이 없으면 비스트리밍 경로를 유지합니다 -- 핸들러는 병렬로 호출되므로 느린 `onStream` 콜백이 `on(...)` 핸들러를 막지 않으며(그 반대도 마찬가지입니다) -- `toolCallId` 는 도구가 모델 도구 호출로 호출되었을 때 제공됩니다. 직접 `invoke()` 로 호출했거나 provider 특성에 따라 누락될 수 있습니다 +- 이벤트 타입은 `RunStreamEvent['type']`와 일치합니다: `raw_model_stream_event`, `run_item_stream_event`, `agent_updated_stream_event` +- `onStream`은 가장 단순한 "catch-all" 방식이며 도구를 인라인으로 선언할 때(`tools: [agent.asTool({ onStream })]`) 잘 맞습니다. 이벤트별 분기가 필요 없다면 이 방식을 사용하세요 +- `on(eventName, handler)`를 사용하면 선택적으로(또는 `'*'`로) 구독할 수 있으며, 더 세밀한 처리가 필요하거나 생성 후 리스너를 연결하고 싶을 때 적합합니다 +- `onStream` 또는 하나 이상의 `on(...)` 핸들러를 제공하면 agent-as-tool은 자동으로 스트리밍 모드에서 실행되며, 제공하지 않으면 비스트리밍 경로를 유지합니다 +- 핸들러는 병렬로 호출되므로 느린 `onStream` 콜백이 `on(...)` 핸들러를 막지 않으며 그 반대도 마찬가지입니다 +- `toolCallId`는 도구가 모델 도구 호출을 통해 호출된 경우 제공됩니다. 직접 `invoke()`를 호출하거나 provider의 특성에 따라 생략될 수 있습니다 --- ### 5. MCP 서버 -[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 서버를 통해 도구를 노출하고 이를 에이전트에 연결할 수 있습니다. 예를 들어 `MCPServerStdio` 를 사용해 stdio MCP 서버를 생성하고 연결할 수 있습니다. +[MCP(Model Context Protocol)](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)를 참고하세요. 여러 서버를 관리하거나(또는 부분 실패를 다루려면) `connectMcpServers` 와 [MCP 가이드](/openai-agents-js/ko/guides/mcp#managing-mcp-server-lifecycle)의 라이프사이클 지침을 사용하세요. +완전한 예시는 [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts)를 참고하세요. 또한 MCP 서버 도구 통합에 대한 포괄적인 가이드를 찾고 있다면 자세한 내용은 [모델 컨텍스트 프로토콜 (MCP)](/openai-agents-js/guides/mcp)를 참고하세요. 여러 서버를 관리하거나 부분 실패를 처리할 때는 `connectMcpServers`와 [모델 컨텍스트 프로토콜 (MCP)](/openai-agents-js/guides/mcp#managing-mcp-server-lifecycle)의 lifecycle 지침을 사용하세요. --- ### 6. 실험적 기능: Codex 도구 -`@openai/agents-extensions/experimental/codex` 는 모델 도구 호출을 Codex SDK 로 라우팅하는 함수 도구 `codexTool()` 을 제공합니다. 이를 통해 에이전트가 workspace 범위 작업(shell, 파일 편집, MCP 도구)을 자율적으로 실행할 수 있습니다. 이 표면은 실험적 기능이며 변경될 수 있습니다. +`@openai/agents-extensions/experimental/codex`는 `codexTool()`을 제공합니다. 이는 모델의 도구 호출을 Codex SDK로 라우팅하여 에이전트가 작업 공간 범위 작업(shell, 파일 편집, MCP 도구)을 자율적으로 실행할 수 있게 하는 함수 도구입니다. 이 표면은 실험적이며 변경될 수 있습니다. 먼저 의존성을 설치하세요. @@ -283,19 +287,19 @@ npm install @openai/agents-extensions @openai/codex-sdk 알아둘 점: -- 인증: `CODEX_API_KEY`(권장) 또는 `OPENAI_API_KEY` 를 제공하거나 `codexOptions.apiKey` 를 전달하세요 -- 입력: strict 스키마입니다. `inputs` 에는 최소 하나의 `{ type: 'text', text }` 또는 `{ type: 'local_image', path }` 가 포함되어야 합니다 -- 안전성: `sandboxMode` 를 `workingDirectory` 와 함께 사용하세요. 디렉터리가 Git 저장소가 아니라면 `skipGitRepoCheck` 를 설정하세요 -- 스레드 처리: `useRunContextThreadId: true` 는 최신 스레드 ID 를 `runContext.context` 에서 읽고 저장하며, 앱 상태에서 턴 간 재사용에 유용합니다 -- 스레드 ID 우선순위: 도구 호출 `threadId`(스키마에 포함된 경우)가 가장 우선하고, 그다음 run-context 스레드 ID, 마지막으로 `codexTool({ threadId })` 입니다 -- 실행 컨텍스트 키: `name: 'codex'` 일 때 기본값은 `codexThreadId` 이고, `name: 'engineer'` 같은 이름일 때는 `codexThreadId_` 입니다(정규화 후 `codex_engineer`) -- 변경 가능한 컨텍스트 요구 사항: `useRunContextThreadId` 를 활성화한 경우 `run(..., { context })` 에 변경 가능한 객체 또는 `Map` 을 전달하세요 -- 이름 지정: 도구 이름은 `codex` 네임스페이스로 정규화됩니다(`engineer` 는 `codex_engineer` 가 됨). 에이전트 내 중복된 Codex 도구 이름은 거부됩니다 -- 스트리밍: `onStream` 은 Codex 이벤트(reasoning, 명령 실행, MCP 도구 호출, 파일 변경, 웹 검색)를 반영하므로 진행 상황을 로그로 남기거나 추적할 수 있습니다 -- 출력: 도구 결과에는 `response`, `usage`, `threadId` 가 포함되며, Codex 토큰 사용량은 `RunContext` 에 기록됩니다 -- 구조: `outputSchema` 는 descriptor, JSON 스키마 객체 또는 Zod 객체가 될 수 있습니다. JSON 객체 스키마의 경우 `additionalProperties` 는 `false` 여야 합니다 +- 인증: `CODEX_API_KEY`(권장) 또는 `OPENAI_API_KEY`를 제공하거나 `codexOptions.apiKey`를 전달하세요 +- 입력: strict schema입니다. `inputs`에는 최소 하나 이상의 `{ type: 'text', text }` 또는 `{ type: 'local_image', path }`가 포함되어야 합니다 +- 안전성: `sandboxMode`를 `workingDirectory`와 함께 사용하세요. 디렉터리가 Git 저장소가 아니라면 `skipGitRepoCheck`를 설정하세요 +- 스레딩: `useRunContextThreadId: true`는 최신 thread id를 `runContext.context`에서 읽고 저장하며, 이는 앱 상태에서 여러 턴에 걸쳐 재사용할 때 유용합니다 +- Thread ID 우선순위: 도구 호출 `threadId`(schema에 포함된 경우)가 가장 우선이고, 그다음 run-context thread id, 마지막으로 `codexTool({ threadId })` 순입니다 +- 실행 컨텍스트 키: `name: 'codex'`일 때 기본값은 `codexThreadId`이며, `name: 'engineer'` 같은 이름일 때는 `codexThreadId_`입니다(정규화 후 `codex_engineer`) +- 변경 가능한 컨텍스트 요구 사항: `useRunContextThreadId`가 활성화된 경우 `run(..., { context })`에는 변경 가능한 객체 또는 `Map`을 전달하세요 +- 이름 지정: 도구 이름은 `codex` 네임스페이스로 정규화됩니다(`engineer`는 `codex_engineer`가 됨). 하나의 에이전트 안에서 중복된 Codex 도구 이름은 거부됩니다 +- 스트리밍: `onStream`은 Codex 이벤트(reasoning, 명령 실행, MCP 도구 호출, 파일 변경, 웹 검색)를 반영하므로 진행 상황을 기록하거나 추적할 수 있습니다 +- 출력: 도구 결과에는 `response`, `usage`, `threadId`가 포함되며 Codex 토큰 사용량은 `RunContext`에 기록됩니다 +- 구조: `outputSchema`는 descriptor, JSON schema 객체 또는 Zod 객체가 될 수 있습니다. JSON 객체 schema에서는 `additionalProperties`가 `false`여야 합니다 -run-context 스레드 재사용 예시: +run-context thread 재사용 예시: OpenAI Agents SDK - 적은 수의 기본 구성 요소로 텍스트 및 음성 에이전트를 구축합니다. + 작은 수의 기본 구성 요소로 샌드박스, 텍스트, 음성 에이전트를 구축합니다. 시작하기 ## 개요 -[TypeScript용 OpenAI Agents SDK](https://github.com/openai/openai-agents-js)를 사용하면 매우 적은 추상화만으로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있습니다. 이 SDK는 에이전트를 위한 이전 실험 프로젝트인 [Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션 준비 버전 업그레이드이며, [Python에서도 사용할 수 있습니다](https://github.com/openai/openai-agents-python). Agents SDK는 매우 작은 수의 기본 구성 요소를 제공합니다. +[TypeScript용 OpenAI Agents SDK](https://github.com/openai/openai-agents-js)는 매우 적은 추상화로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있게 해줍니다. 이는 에이전트를 위한 이전 실험 프로젝트인 [Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션 준비 버전 업그레이드이며, [Python 버전도 제공됩니다](https://github.com/openai/openai-agents-python). Agents SDK에는 매우 작은 수의 기본 구성 요소가 있습니다. -- **에이전트**: instructions 와 tools 가 갖춰진 LLM -- **Agents as tools / 핸드오프**: 특정 작업을 위해 에이전트가 다른 에이전트에 작업을 위임할 수 있게 해주는 메커니즘 -- **가드레일**: 에이전트에 대한 입력을 검증할 수 있게 해주는 기능 +- **에이전트**: instructions와 tools가 갖춰진 LLM +- **샌드박스 에이전트**: 에이전트를 격리된 파일시스템 작업공간, 셸 명령, 파일 편집, 스냅샷, 샌드박스 세션 상태와 결합한 것 +- **Agents as tools / 핸드오프**: 에이전트가 특정 작업을 위해 다른 에이전트에 위임할 수 있게 하는 기능 +- **가드레일**: 에이전트에 대한 입력을 검증할 수 있게 하는 기능 -TypeScript와 함께 사용하면 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트형 흐름을 시각화하고 디버깅할 수 있는 기본 제공 **트레이싱**이 포함되어 있어, 이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝하는 것도 가능합니다. +TypeScript와 결합하면 이러한 기본 구성 요소는 도구와 에이전트 간의 복잡한 관계를 표현하고, 필요할 때 에이전트에 실제 작업공간을 제공하며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있을 만큼 강력합니다. 또한 SDK에는 에이전트형 흐름을 시각화하고 디버그할 수 있게 해주는 기본 제공 **트레이싱**이 포함되어 있으며, 이를 평가하고 애플리케이션에 맞게 모델을 미세 조정하는 것도 가능합니다. ## Agents SDK 사용 이유 SDK에는 두 가지 핵심 설계 원칙이 있습니다. 1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 배울 수 있을 만큼 기본 구성 요소는 적게 유지합니다. -2. 기본 설정만으로도 잘 동작하지만, 정확히 어떤 일이 일어날지 세밀하게 커스터마이즈할 수 있습니다. +2. 별도 설정 없이도 잘 작동하지만, 정확히 어떤 일이 일어날지는 직접 사용자화할 수 있습니다. 다음은 SDK의 주요 기능입니다. - **에이전트 루프**: 도구 호출을 처리하고, 결과를 LLM에 다시 보내며, 작업이 완료될 때까지 계속하는 기본 제공 에이전트 루프 -- **TypeScript 우선**: 새로운 추상화를 배울 필요 없이, TypeScript의 기본 언어 기능을 사용해 에이전트를 오케스트레이션하고 연결합니다 +- **샌드박스 실행**: 작업에 작업공간이 필요할 때, 격리된 파일시스템 작업공간, 셸 명령, 파일 편집, 스냅샷, 샌드박스 세션 상태와 함께 에이전트를 실행 +- **TypeScript 우선**: 새로운 추상화를 배울 필요 없이, TypeScript 고유 언어 기능을 사용해 에이전트를 오케스트레이션하고 연결 - **Agents as tools / 핸드오프**: 여러 에이전트 간 작업을 조정하고 위임하기 위한 강력한 메커니즘 -- **가드레일**: 입력 검증과 안전성 검사를 에이전트 실행과 병렬로 수행하고, 검사를 통과하지 못하면 즉시 실패 처리합니다 -- **함수 도구**: 자동 스키마 생성과 Zod 기반 검증으로 모든 TypeScript 함수를 도구로 변환합니다 -- **MCP 서버 도구 호출**: 함수 도구와 동일한 방식으로 동작하는 기본 제공 MCP 서버 도구 연동 -- **세션**: 에이전트 루프 내에서 작업 컨텍스트를 유지하기 위한 영속 메모리 계층 -- **휴먼인더루프 (HITL)**: 에이전트 실행 전반에 걸쳐 사람을 참여시키기 위한 기본 제공 메커니즘 -- **트레이싱**: 워크플로를 시각화, 디버깅, 모니터링하기 위한 기본 제공 트레이싱으로, OpenAI의 평가, 파인튜닝, 증류 도구 모음을 지원합니다 -- **실시간 에이전트**: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등의 기능을 갖춘 강력한 음성 에이전트를 구축합니다 +- **가드레일**: 입력 검증과 안전성 검사를 에이전트 실행과 병렬로 수행하고, 검사를 통과하지 못하면 빠르게 실패 처리 +- **함수 도구**: 자동 스키마 생성과 Zod 기반 검증을 통해 모든 TypeScript 함수를 도구로 변환 +- **MCP 서버 도구 호출**: 함수 도구와 동일한 방식으로 작동하는 기본 제공 MCP 서버 도구 통합 +- **세션**: 에이전트 루프 내에서 작업 컨텍스트를 유지하기 위한 지속형 메모리 계층 +- **휴먼인더루프 (HITL)**: 에이전트 실행 전반에 사람을 참여시키기 위한 기본 제공 메커니즘 +- **트레이싱**: 워크플로를 시각화, 디버그, 모니터링하기 위한 기본 제공 트레이싱으로, OpenAI 평가, 미세 조정, 증류 도구 제품군 지원 포함 +- **실시간 에이전트**: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등의 기능을 갖춘 강력한 음성 에이전트 구축 ## 설치 @@ -55,52 +58,76 @@ npm install @openai/agents zod SDK는 Zod v4를 필요로 하며, npm으로 `zod`를 설치하면 최신 v4 릴리스를 가져옵니다. -## 시작점 선택 +## 시작 지점 선택 처음 사용하는 대부분의 사용자는 다음 진입점 중 하나만 있으면 됩니다. -| 시작 항목 | 사용 시점 | 참고 | +| Start with | Use it when | Notes | | --- | --- | --- | -| `@openai/agents` | 대부분의 텍스트 또는 음성 애플리케이션을 구축하는 경우 | 권장 기본값입니다. OpenAI provider 설정을 포함하며, 음성 API는 `@openai/agents/realtime` 아래에 노출됩니다. | +| `@openai/agents` | 대부분의 텍스트, 샌드박스 또는 음성 애플리케이션을 구축하는 경우 | 권장 기본값입니다. OpenAI provider 설정, `@openai/agents/sandbox` 아래의 샌드박스 에이전트 API, `@openai/agents/realtime` 아래의 음성 API가 포함됩니다. | | `@openai/agents-realtime` | 독립형 Realtime 패키지만 필요한 경우 | 브라우저 전용 음성 앱이나 더 좁은 패키지 경계를 원하는 경우에 유용합니다. | -| 하위 수준 패키지 (`@openai/agents-core`, `@openai/agents-openai`, `@openai/agents-extensions`) | 하위 수준 조합, 커스텀 provider 연결, 또는 특정 통합이 필요한 경우 | 대부분의 신규 사용자는 구체적인 필요가 생길 때까지 이 항목은 무시해도 됩니다. | - -## Hello World 예제 - - - -(_이 예제를 실행하는 경우 `OPENAI_API_KEY` 환경 변수를 설정해야 합니다_) +| Lower-level packages (`@openai/agents-core`, `@openai/agents-openai`, `@openai/agents-extensions`) | 더 낮은 수준의 조합, 사용자 정의 provider 연결, 또는 특정 통합이 필요한 경우 | 대부분의 신규 사용자는 구체적인 필요가 생길 때까지는 이를 무시해도 됩니다. | + +## Hello world 예제 + +에이전트가 파일시스템에서 작업해야 한다면 샌드박스 에이전트로 시작하세요. 워크플로에 샌드박스 작업공간이나 샌드박스 생명주기가 필요하지 않다면 일반 `Agent`를 계속 사용할 수도 있습니다. + + + + + + + + + + +(_이를 실행하려면 `OPENAI_API_KEY` 환경 변수가 설정되어 있는지 확인하세요_) ```bash export OPENAI_API_KEY=sk-... ``` -## 시작하기 +## 시작 안내 -우선 하나의 경로를 선택해 처음부터 끝까지 동작하게 만든 다음, 더 깊이 있는 가이드를 보러 돌아오세요. +먼저 한 경로를 선택해 처음부터 끝까지 동작하게 만든 다음, 더 깊이 있는 가이드로 돌아오세요. + + ## 경로 선택 -수행하려는 작업은 알고 있지만 어떤 페이지에서 설명하는지 모를 때 이 표를 사용하세요. +무엇을 하고 싶은지는 알지만 어떤 페이지에서 설명하는지 모를 때 이 표를 사용하세요. -| 목표 | 시작 위치 | +| Goal | Start here | | --- | --- | -| 첫 번째 텍스트 에이전트를 만들고 하나의 완전한 실행을 확인하기 | [빠른 시작](/openai-agents-js/guides/quickstart) | -| 함수 도구, 호스티드 툴 또는 Agents as tools 추가하기 | [도구](/openai-agents-js/guides/tools) | -| 핸드오프와 매니저 스타일 오케스트레이션 중 선택하기 | [에이전트 오케스트레이션](/openai-agents-js/guides/multi-agent) | -| 여러 턴에 걸쳐 메모리 유지하기 | [에이전트 실행](/openai-agents-js/guides/running-agents) 및 [세션](/openai-agents-js/guides/sessions) | -| OpenAI 모델, websocket 전송, 또는 OpenAI 이외 provider 사용하기 | [모델](/openai-agents-js/guides/models) | -| 출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토하기 | [실행 결과](/openai-agents-js/guides/results) | -| 저지연 음성 에이전트 구축하기 | [빠른 시작](/openai-agents-js/guides/voice-agents/quickstart) | +| 첫 번째 텍스트 에이전트를 만들고 하나의 완전한 실행을 확인 | [빠른 시작](/openai-agents-js/guides/quickstart) | +| 함수 도구, 호스티드 툴 또는 Agents as tools 추가 | [도구](/openai-agents-js/guides/tools) | +| 에이전트에 격리된 파일시스템 및 셸 작업공간 제공 | [Sandbox agents](/openai-agents-js/guides/sandbox-agents) | +| 핸드오프와 매니저 스타일 오케스트레이션 중 선택 | [에이전트 오케스트레이션](/openai-agents-js/guides/multi-agent) | +| 여러 턴에 걸쳐 메모리 유지 | [에이전트 실행](/openai-agents-js/guides/running-agents) 및 [세션](/openai-agents-js/guides/sessions) | +| OpenAI 모델, websocket 전송 또는 비OpenAI provider 사용 | [모델](/openai-agents-js/guides/models) | +| 출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토 | [실행 결과](/openai-agents-js/guides/results) | +| 지연 시간이 낮은 음성 에이전트 구축 | [빠른 시작](/openai-agents-js/guides/voice-agents/quickstart) | diff --git a/docs/src/content/docs/zh/guides/agents.mdx b/docs/src/content/docs/zh/guides/agents.mdx index 26e6bc10c..7a79aab10 100644 --- a/docs/src/content/docs/zh/guides/agents.mdx +++ b/docs/src/content/docs/zh/guides/agents.mdx @@ -18,28 +18,29 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor 智能体是 OpenAI Agents SDK 的主要构建模块。**Agent** 是一个经过如下配置的大语言模型（LLM）： -- **Instructions**——告诉模型*它是谁*以及*应如何响应*的系统提示。 +- **Instructions**——告诉模型*它是谁*以及*应该如何响应*的系统提示。 - **Model**——要调用的 OpenAI 模型，以及任何可选的模型调优参数。 - **Tools**——LLM 可调用以完成任务的函数或 API 列表。 -> 当您想要定义或自定义单个 `Agent` 时，请使用本页。如果您正在决定多个智能体应如何协作，请阅读[智能体编排](/openai-agents-js/guides/multi-agent)。 +> 当您想要定义或自定义单个 `Agent` 时，请使用本页。如果您正在决定多个智能体应如何协作，请阅读[智能体编排](/openai-agents-js/zh/guides/multi-agent)。 ### 下一指南选择 -将本页作为智能体定义的中心页。根据您下一步需要做出的决策，跳转到相邻的对应指南。 +将本页作为智能体定义的中心页。根据您接下来需要做出的决策，跳转到对应的相邻指南。 | 如果您想要…… | 接下来阅读 | | --- | --- | -| 选择模型或配置存储的提示 | [模型](/openai-agents-js/guides/models) | -| 为智能体添加能力 | [工具](/openai-agents-js/guides/tools) | -| 在管理者和交接之间做选择 | [智能体编排](/openai-agents-js/guides/multi-agent) | -| 配置交接行为 | [交接](/openai-agents-js/guides/handoffs) | -| 运行轮次、流式传输事件或管理状态 | [运行智能体](/openai-agents-js/guides/running-agents) | -| 检查最终输出、运行项或恢复执行 | [执行结果](/openai-agents-js/guides/results) | +| 选择模型或配置存储的提示 | [模型](/openai-agents-js/zh/guides/models) | +| 为智能体添加能力 | [工具](/openai-agents-js/zh/guides/tools) | +| 为智能体提供隔离的文件系统工作区 | [Sandbox clients](/openai-agents-js/zh/guides/sandbox-agents/concepts) | +| 在管理者与交接之间做选择 | [智能体编排](/openai-agents-js/zh/guides/multi-agent) | +| 配置交接行为 | [交接](/openai-agents-js/zh/guides/handoffs) | +| 运行轮次、流式传输事件或管理状态 | [运行智能体](/openai-agents-js/zh/guides/running-agents) | +| 检查最终输出、运行项或恢复执行 | [执行结果](/openai-agents-js/zh/guides/results) | -本页其余部分将更详细地介绍 Agent 的每项功能。 +本页其余部分将更详细地介绍 Agent 的每一项功能。 --- @@ -47,25 +48,25 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### 基本配置 -`Agent` 构造函数接受一个配置对象。最常用的属性如下所示。 +`Agent` 构造函数接收一个配置对象。最常用的属性如下所示。 -| 属性 | 必需 | 说明 | +| 属性 | 必填 | 说明 | | --- | --- | --- | | `name` | 是 | 简短、便于人类阅读的标识符。 | -| `instructions` | 是 | 系统提示（字符串**或**函数——参见[动态 instructions](#dynamic-instructions)）。 | -| `prompt` | 否 | OpenAI Responses API 的提示配置。可接受静态提示对象或函数。参见[Prompt](/openai-agents-js/guides/models#prompt)。 | -| `handoffDescription` | 否 | 当该智能体作为交接工具提供时使用的简短描述。 | -| `handoffs` | 否 | 将对话委派给专门智能体。参见[组合模式](#composition-patterns)和[交接指南](/openai-agents-js/guides/handoffs)。 | -| `model` | 否 | 模型名称**或**自定义的 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 实现。 | -| `modelSettings` | 否 | 调优参数（temperature、top_p 等）。参见[模型](/openai-agents-js/guides/models#modelsettings)。如果您需要的属性不在顶层，可以将其放在 `providerData` 下。 | -| `tools` | 否 | 模型可调用的 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 实例数组。参见[工具](/openai-agents-js/guides/tools)。 | -| `mcpServers` | 否 | 智能体可使用的 MCP 支持工具。参见[MCP 集成](/openai-agents-js/guides/mcp)。 | -| `inputGuardrails` | 否 | 应用于该智能体链中首次用户输入的护栏。参见[护栏](/openai-agents-js/guides/guardrails)。 | -| `outputGuardrails` | 否 | 应用于该智能体最终输出的护栏。参见[护栏](/openai-agents-js/guides/guardrails)。 | -| `outputType` | 否 | 返回结构化输出而非纯文本。参见[输出类型](#output-types)和[执行结果](/openai-agents-js/guides/results#final-output)。 | -| `toolUseBehavior` | 否 | 控制函数工具结果是回传给模型继续处理，还是直接结束运行。参见[强制工具使用](#forcing-tool-use)。 | -| `resetToolChoice` | 否 | 工具调用后将 `toolChoice` 重置为默认值（默认：`true`），以防止工具调用循环。参见[强制工具使用](#forcing-tool-use)。 | -| `handoffOutputTypeWarningEnabled` | 否 | 当交接输出类型不一致时发出警告（默认：`true`）。参见[执行结果](/openai-agents-js/guides/results#final-output)。 | +| `instructions` | 是 | 系统提示（字符串**或**函数——参见[动态说明](#dynamic-instructions)）。 | +| `prompt` | 否 | OpenAI Responses API 的提示配置。接受静态提示对象或函数。参见[Prompt](/openai-agents-js/zh/guides/models#prompt)。 | +| `handoffDescription` | 否 | 当该智能体作为交接工具提供时使用的简短说明。 | +| `handoffs` | 否 | 将对话委派给专门的智能体。参见[组合模式](#composition-patterns)和[交接指南](/openai-agents-js/zh/guides/handoffs)。 | +| `model` | 否 | 模型名称**或**自定义 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 实现。 | +| `modelSettings` | 否 | 调优参数（temperature、top_p 等）。参见[模型](/openai-agents-js/zh/guides/models#modelsettings)。如果您需要的属性不在顶层，也可以将它们放在 `providerData` 下。 | +| `tools` | 否 | 模型可调用的 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 实例数组。参见[工具](/openai-agents-js/zh/guides/tools)。 | +| `mcpServers` | 否 | 供智能体使用的 MCP 支持工具。参见[MCP 集成](/openai-agents-js/zh/guides/mcp)。 | +| `inputGuardrails` | 否 | 应用于该智能体链中首次用户输入的护栏。参见[护栏](/openai-agents-js/zh/guides/guardrails)。 | +| `outputGuardrails` | 否 | 应用于该智能体最终输出的护栏。参见[护栏](/openai-agents-js/zh/guides/guardrails)。 | +| `outputType` | 否 | 返回结构化输出而非纯文本。参见[输出类型](#output-types)和[执行结果](/openai-agents-js/zh/guides/results#final-output)。 | +| `toolUseBehavior` | 否 | 控制函数工具结果是回传给模型，还是直接结束运行。参见[强制工具使用](#forcing-tool-use)。 | +| `resetToolChoice` | 否 | 在工具调用后将 `toolChoice` 重置为默认值（默认：`true`），以防止工具使用循环。参见[强制工具使用](#forcing-tool-use)。 | +| `handoffOutputTypeWarningEnabled` | 否 | 当交接输出类型不一致时发出警告（默认：`true`）。参见[执行结果](/openai-agents-js/zh/guides/results#final-output)。 | @@ -73,7 +74,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### 上下文 -智能体**在其上下文类型上是泛型的**——即 `Agent`。*上下文*是您创建并传递给 `Runner.run()` 的依赖注入对象。它会被传递给每个工具、护栏、交接等，适合用于存储状态或提供共享服务（数据库连接、用户元数据、功能开关等）。 +智能体的**上下文类型是泛型的**——即 `Agent`。*上下文*是一个依赖注入对象，由您创建并传递给 `Runner.run()`。它会被传递给每个工具、护栏、交接等，适合用于存储状态或提供共享服务（数据库连接、用户元数据、功能开关等）。 @@ -83,8 +84,8 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor 默认情况下，Agent 返回**纯文本**（`string`）。如果您希望模型返回结构化对象，可以指定 `outputType` 属性。SDK 接受： -1. [Zod](https://github.com/colinhacks/zod) schema（`z.object({...})`）。 -2. 任何兼容 JSON schema 的对象。 +1. 一个 [Zod](https://github.com/colinhacks/zod) schema（`z.object({...})`）。 +2. 任何兼容 JSON Schema 的对象。 -提供 `outputType` 后，SDK 会自动使用[structured outputs](https://developers.openai.com/api/docs/guides/structured-outputs)，而不是纯文本。 +提供 `outputType` 后，SDK 会自动使用[structured outputs](https://developers.openai.com/api/docs/guides/structured-outputs)而不是纯文本。 --- ### OpenAI 平台映射 -有些智能体概念可直接映射到 OpenAI 平台概念，另一些则是在运行智能体时配置，而不是在定义智能体时配置。 +一些智能体概念可直接映射到 OpenAI 平台概念，另一些则是在运行智能体时而不是定义智能体时进行配置。 -| SDK 概念 | OpenAI 指南 | 适用时机 | +| SDK 概念 | OpenAI 指南 | 适用场景 | | --- | --- | --- | -| `outputType` | [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) | 智能体应返回带类型的 JSON 或经 Zod 验证的对象，而不是文本。 | -| `tools` / 托管工具 | [Tools guide](https://developers.openai.com/api/docs/guides/tools) | 模型应执行搜索、检索、运行代码，或调用您的函数/工具。 | -| `conversationId` / `previousResponseId` | [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) | 您希望 OpenAI 在多轮之间持久化或串联对话状态。 | +| `outputType` | [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) | 智能体应返回带类型的 JSON 或经过 Zod 验证的对象，而不是文本。 | +| `tools` / 托管工具 | [Tools guide](https://developers.openai.com/api/docs/guides/tools) | 模型应搜索、检索、执行代码，或调用您的函数/工具。 | +| `conversationId` / `previousResponseId` | [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) | 您希望 OpenAI 在多个轮次之间持久化或串联对话状态。 | -`conversationId` 和 `previousResponseId` 是运行时控制项，不是 `Agent` 构造函数字段。当您需要这些 SDK 入口时，请使用[运行智能体](/openai-agents-js/guides/running-agents)。 +`conversationId` 和 `previousResponseId` 是运行时控制项，不是 `Agent` 构造函数字段。当您需要这些 SDK 入口时，请使用[运行智能体](/openai-agents-js/zh/guides/running-agents)。 --- ## 组合模式 -当智能体参与更大的工作流时，最常出现的两个 SDK 入口是： +当一个智能体参与更大的工作流时，最常见的两个 SDK 入口是： -1. **管理者（Agents as tools）**——一个中心智能体负责整个对话，并调用以工具形式暴露的专门智能体。 +1. **管理者（Agents as tools）**——一个中央智能体拥有对话控制权，并调用作为工具暴露出来的专门智能体。 2. **交接**——初始智能体在识别出用户请求后，将整个对话委派给某个专门智能体。 -这两种方式是互补的。管理者为您提供一个统一位置来实施护栏或速率限制，而交接则让每个智能体专注于单一任务，而无需持续控制整个对话。关于设计权衡以及何时选择每种模式，请参见[智能体编排](/openai-agents-js/guides/multi-agent)。 +这两种方式是互补的。管理者为您提供了统一的位置来实施护栏或速率限制，而交接则让每个智能体专注于单一任务，而无需保留对对话的控制权。关于设计权衡以及何时选择每种模式，请参见[智能体编排](/openai-agents-js/zh/guides/multi-agent)。 #### 管理者（Agents as tools） -在这种模式下，管理者永远不会移交控制权——LLM 使用工具，而管理者对最终答案进行总结。更多内容请参见[工具指南](/openai-agents-js/guides/tools#agents-as-tools)。 +在这种模式中，管理者永远不会移交控制权——LLM 使用工具，而管理者汇总最终答案。更多内容请参见[工具指南](/openai-agents-js/zh/guides/tools#agents-as-tools)。 #### 交接 -使用交接时，分流智能体会路由请求，但一旦发生交接，专门智能体就会接管对话，直到生成最终输出。这能让提示更简短，也便于您独立分析每个智能体。更多信息请参见[交接指南](/openai-agents-js/guides/handoffs)。 +使用交接时，分流智能体会路由请求；但一旦发生交接，专门智能体将拥有对话控制权，直到生成最终输出为止。这能让提示更简短，也让您可以独立地分析每个智能体。更多内容请参见[交接指南](/openai-agents-js/zh/guides/handoffs)。 -如果您的交接目标可能返回不同的输出类型，优先使用 `Agent.create(...)` 而不是 `new Agent(...)`。这样 TypeScript 就能推断交接图中可能出现的 `finalOutput` 形状联合类型，并避免由 `handoffOutputTypeWarningEnabled` 控制的运行时警告。完整示例请参见[执行结果指南](/openai-agents-js/guides/results#final-output)。 +如果您的交接目标可能返回不同的输出类型，请优先使用 `Agent.create(...)` 而不是 `new Agent(...)`。这样 TypeScript 就能推断整个交接图中可能的 `finalOutput` 形状联合类型，并避免由 `handoffOutputTypeWarningEnabled` 控制的运行时警告。完整示例请参见[执行结果指南](/openai-agents-js/zh/guides/results#final-output)。 --- ## 高级配置与运行时控制 -### 动态 instructions +### 动态说明 -`instructions` 可以是**函数**，而不仅仅是字符串。该函数会接收当前的 `RunContext` 和 Agent 实例，并可返回字符串*或*`Promise`。 +`instructions` 可以是**函数**，而不只是字符串。该函数会接收当前的 `RunContext` 和 Agent 实例，并可返回字符串*或*`Promise`。 -支持同步函数和 `async` 函数。 +同时支持同步函数和 `async` 函数。 --- ### 动态提示 -`prompt` 支持与 `instructions` 相同的回调形式，但返回的是提示配置对象而不是字符串。当提示 ID、版本或变量依赖于当前运行上下文时，这非常有用。 +`prompt` 支持与 `instructions` 相同的回调形式，但返回的是提示配置对象，而不是字符串。当提示 ID、版本或变量取决于当前运行上下文时，这很有用。 -这仅在您使用 OpenAI Responses API 时受支持。支持同步函数和 `async` 函数。 +这仅在您使用 OpenAI Responses API 时受支持。同时支持同步函数和 `async` 函数。 --- @@ -169,7 +170,7 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor 对于高级用例，您可以通过监听事件来观察 Agent 生命周期。 -`Agent` 实例会为该特定智能体实例发出生命周期事件，而 `Runner` 会在整个运行期间以单一事件流发出相同的事件名称。这对于多智能体工作流特别有用，因为您可以在一个地方观察交接和工具调用。 +`Agent` 实例会为该特定智能体实例发出生命周期事件，而 `Runner` 会以单一事件流的形式在整个运行过程中发出相同的事件名称。这对于多智能体工作流很有用，因为您可以在一个地方观察交接和工具调用。 共享的事件名称如下： @@ -191,13 +192,13 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### 护栏 -护栏允许您验证或转换用户输入和智能体输出。它们通过 `inputGuardrails` 和 `outputGuardrails` 数组进行配置。详情请参见[护栏指南](/openai-agents-js/guides/guardrails)。 +护栏允许您验证或转换用户输入和智能体输出。它们通过 `inputGuardrails` 和 `outputGuardrails` 数组进行配置。详情请参见[护栏指南](/openai-agents-js/zh/guides/guardrails)。 --- ### 智能体克隆 / 复制 -需要现有智能体的一个稍作修改的版本？使用 `clone()` 方法，它会返回一个全新的 `Agent` 实例。 +需要对现有智能体做些小改动的版本吗？请使用 `clone()` 方法，它会返回一个全新的 `Agent` 实例。 @@ -205,26 +206,26 @@ import agentForcingToolUse from '../../../../../../examples/docs/agents/agentFor ### 强制工具使用 -提供工具并不保证 LLM 会调用它。您可以通过 `modelSettings.toolChoice` **强制**工具使用： +提供工具并不能保证 LLM 一定会调用它。您可以通过 `modelSettings.toolChoice` **强制**工具使用： 1. `'auto'`（默认）——由 LLM 决定是否使用工具。 -2. `'required'`——LLM *必须*调用某个工具（可自行选择调用哪一个）。 +2. `'required'`——LLM *必须*调用某个工具（可以自行选择调用哪个）。 3. `'none'`——LLM **不得**调用工具。 4. 指定某个工具名称，例如 `'calculator'`——LLM 必须调用该特定工具。 -当可用工具是在 OpenAI Responses 中的 `computerTool()` 时，`toolChoice: 'computer'` 有特殊含义：它会强制使用 GA 内置的计算机工具，而不是将 `'computer'` 视为普通函数名。对于旧版集成，SDK 也接受兼容预览版的计算机选择器，但新代码应优先使用 `'computer'`。如果没有可用的计算机工具，该字符串会像其他函数工具名称一样处理。 +当可用工具是 OpenAI Responses 上的 `computerTool()` 时，`toolChoice: 'computer'` 是特殊值：它会强制使用 GA 内置的计算机工具，而不会将 `'computer'` 视为普通函数名称。SDK 也接受与预览版兼容的计算机选择器，以支持旧集成，但新代码应优先使用 `'computer'`。如果没有可用的计算机工具，这个字符串就会像其他函数工具名称一样处理。 -当您使用延迟加载的 Responses 工具（例如 `toolNamespace()`）、设置了 `deferLoading: true` 的函数工具，或设置了 `deferLoading: true` 的托管 MCP 工具时，请将 `modelSettings.toolChoice` 保持为 `'auto'`。SDK 会拒绝通过名称强制调用延迟工具或内置的 `tool_search` 辅助工具，因为模型需要自行决定何时加载这些定义。完整的 tool-search 设置请参见[工具指南](/openai-agents-js/guides/tools#deferred-tool-loading-with-tool-search)。 +当您使用延迟加载的 Responses 工具（例如 `toolNamespace()`）、带有 `deferLoading: true` 的函数工具，或带有 `deferLoading: true` 的托管 MCP 工具时，请将 `modelSettings.toolChoice` 保持为 `'auto'`。SDK 会拒绝按名称强制调用延迟工具或内置的 `tool_search` 辅助工具，因为模型需要自行决定何时加载这些定义。完整的 tool-search 配置请参见[工具指南](/openai-agents-js/zh/guides/tools#deferred-tool-loading-with-tool-search)。 #### 防止无限循环 -工具调用后，SDK 会自动将 `toolChoice` 重置回 `'auto'`。这可防止模型陷入反复尝试调用工具的无限循环。您可以通过 `resetToolChoice` 标志或配置 `toolUseBehavior` 来覆盖此行为： +工具调用后，SDK 会自动将 `toolChoice` 重置回 `'auto'`。这样可以防止模型进入无限循环，不断尝试调用工具。您可以通过 `resetToolChoice` 标志或配置 `toolUseBehavior` 来覆盖此行为： - `'run_llm_again'`（默认）——使用工具结果再次运行 LLM。 - `'stop_on_first_tool'`——将第一个工具结果视为最终答案。 -- `{ stopAtToolNames: ['my_tool'] }`——当调用了列出的任意工具时停止。 +- `{ stopAtToolNames: ['my_tool'] }`——当调用了列出的任一工具时停止。 - `(context, toolResults) => ...`——返回运行是否应结束的自定义函数。 ```typescript @@ -240,10 +241,10 @@ const agent = new Agent({ ## 相关指南 -- [模型](/openai-agents-js/guides/models)：模型选择、存储提示和提供方配置。 -- [工具](/openai-agents-js/guides/tools)：函数工具、托管工具、MCP 和 `agent.asTool()`。 -- [智能体编排](/openai-agents-js/guides/multi-agent)：在管理者、交接和代码驱动的编排之间做选择。 -- [交接](/openai-agents-js/guides/handoffs)：配置专门智能体委派。 -- [运行智能体](/openai-agents-js/guides/running-agents)：执行轮次、流式传输和对话状态。 -- [执行结果](/openai-agents-js/guides/results)：`finalOutput`、运行项和恢复状态。 -- 在侧边栏中 **@openai/agents** 下浏览完整的 TypeDoc 参考。 +- [模型](/openai-agents-js/zh/guides/models)：用于模型选择、存储提示和提供方配置。 +- [工具](/openai-agents-js/zh/guides/tools)：用于函数工具、托管工具、MCP 和 `agent.asTool()`。 +- [智能体编排](/openai-agents-js/zh/guides/multi-agent)：用于在管理者、交接和代码驱动编排之间做选择。 +- [交接](/openai-agents-js/zh/guides/handoffs)：用于配置专门智能体委派。 +- [运行智能体](/openai-agents-js/zh/guides/running-agents)：用于执行轮次、流式传输和对话状态管理。 +- [执行结果](/openai-agents-js/zh/guides/results)：用于 `finalOutput`、运行项和恢复状态。 +- 在侧边栏的 **@openai/agents** 下探索完整的 TypeDoc 参考文档。 diff --git a/docs/src/content/docs/zh/guides/running-agents.mdx b/docs/src/content/docs/zh/guides/running-agents.mdx index 0b4f49696..15916e811 100644 --- a/docs/src/content/docs/zh/guides/running-agents.mdx +++ b/docs/src/content/docs/zh/guides/running-agents.mdx @@ -13,163 +13,175 @@ import previousResponseIdExample from '../../../../../../examples/docs/running-a 智能体本身不会执行任何操作——您需要使用 `Runner` 类或 `run()` 工具来**运行**它们。 -> 当您希望执行轮次、流式传输事件或管理对话状态时，请在阅读完[智能体](/openai-agents-js/zh/guides/agents)后再阅读本页。如果您仍在决定应如何定义智能体，请先从[智能体](/openai-agents-js/zh/guides/agents)开始。 +> 当您想要执行轮次、流式传输事件或管理对话状态时，请在阅读完[智能体](/openai-agents-js/zh/guides/agents)后再阅读本页。如果您仍在决定应如何定义智能体，请先从[智能体](/openai-agents-js/zh/guides/agents)开始。 - + 当您不需要自定义 runner 时，也可以使用 `run()` 工具，它会运行一个单例的默认 `Runner` 实例。 或者，您也可以创建自己的 runner 实例： - + -运行智能体后，您会收到一个[执行结果](/openai-agents-js/zh/guides/results)对象，其中包含最终输出以及本次运行的完整历史记录。 +运行智能体后，您将收到一个[执行结果](/openai-agents-js/zh/guides/results)对象，其中包含最终输出以及本次运行的完整历史记录。 ## Runner 生命周期与配置 ### 智能体循环 -当您使用 Runner 中的 run 方法时，需要传入一个起始智能体和输入。输入可以是字符串（会被视为一条用户消息），也可以是输入项列表，即 OpenAI Responses API 中的条目。 +当您在 Runner 中使用 run 方法时，需要传入一个起始智能体和输入。输入可以是字符串（会被视为一条用户消息），也可以是一组输入项，即 OpenAI Responses API 中的条目。 -随后 runner 会运行一个循环： +随后，runner 会运行一个循环： 1. 使用当前输入调用当前智能体的模型。 2. 检查 LLM 响应。 - **最终输出** → 返回。 - - **交接** → 切换到新智能体，保留累计的对话历史，然后回到 1。 - - **工具调用** → 执行工具，将其结果附加到对话中，然后回到 1。 -3. 一旦达到 `maxTurns`，抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 + - **交接** → 切换到新的智能体，保留已累积的对话历史，转到 1。 + - **工具调用** → 执行工具，将其结果追加到对话中，转到 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` | – | 传递给每个工具 / 护栏 / 交接的上下文对象。详见[上下文管理指南](/openai-agents-js/zh/guides/context)。 | +| `stream` | `false` | 如果为 `true`，调用将返回一个 `StreamedRunResult`，并在模型返回事件时持续发出事件。 | +| `context` | – | 转发给每个工具 / 护栏 / 交接的上下文对象。更多信息请参见[上下文管理指南](/openai-agents-js/zh/guides/context)。 | | `maxTurns` | `10` | 安全限制——达到时会抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 | -| `signal` | – | 用于取消的 `AbortSignal`。 | +| `signal` | – | 用于取消操作的 `AbortSignal`。 | | `session` | – | 会话持久化实现。参见[会话指南](/openai-agents-js/zh/guides/sessions)。 | | `sessionInputCallback` | – | 用于合并会话历史与新输入的自定义逻辑；在模型调用前运行。参见[会话](/openai-agents-js/zh/guides/sessions)。 | -| `callModelInputFilter` | – | 在调用模型之前，用于编辑模型输入（条目 + 可选 instructions）的 hook。参见[模型输入过滤器](#call-model-input-filter)。 | -| `toolErrorFormatter` | – | 用于自定义返回给模型的工具审批拒绝消息的 hook。参见[工具错误格式化器](#tool-error-formatter)。 | -| `reasoningItemIdPolicy` | – | 控制在将先前运行条目重新转换为模型输入时，是否保留或省略 reasoning-item 的 `id`。参见[Reasoning item ID 策略](#reasoning-item-id-policy)。 | +| `callModelInputFilter` | – | 在调用模型之前，用于编辑模型输入（条目 + 可选 instructions）的钩子。参见[模型输入过滤器](#call-model-input-filter)。 | +| `toolErrorFormatter` | – | 用于自定义返回给模型的工具审批拒绝消息的钩子。参见[工具错误格式化器](#tool-error-formatter)。 | +| `reasoningItemIdPolicy` | – | 控制当前一次运行中的条目在被转回模型输入时，是否保留或省略 reasoning-item 的 `id`。参见[Reasoning 条目 ID 策略](#reasoning-item-id-policy)。 | | `tracing` | – | 每次运行的追踪配置覆盖项（例如导出 API key）。 | +| `sandbox` | – | 用于 `SandboxAgent` 运行的 Sandbox 客户端、实时会话、会话状态、快照、manifest 覆盖项或并发限制。参见[Sandbox agents](/openai-agents-js/zh/guides/sandbox-agents/concepts)。 | | `errorHandlers` | – | 支持的运行时错误处理器（当前为 `maxTurns`）。参见[错误处理器](#error-handlers)。 | | `conversationId` | – | 复用服务器端对话（仅适用于 OpenAI Responses API + Conversations API）。 | -| `previousResponseId` | – | 在不创建对话的情况下，从上一次 Responses API 调用继续（仅适用于 OpenAI Responses API）。 | +| `previousResponseId` | – | 从上一次 Responses API 调用继续，而不创建对话（仅适用于 OpenAI Responses API）。 | ### 流式传输 -流式传输允许您在 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` | 为本次运行中的**所有**智能体强制指定特定模型。 | +| `model` | `string \| Model` | 为本次运行中的**所有**智能体强制指定一个特定模型。 | | `modelProvider` | `ModelProvider` | 解析模型名称——默认为 OpenAI provider。 | -| `modelSettings` | `ModelSettings` | 全局调优参数，会覆盖每个智能体各自的设置。详见[模型指南](/openai-agents-js/zh/guides/models#modelsettings)，其中还包括选择启用的重试配置。 | -| `handoffInputFilter` | `HandoffInputFilter` | 在执行交接时变更输入项（如果交接本身尚未定义过滤器）。 | +| `modelSettings` | `ModelSettings` | 覆盖每个智能体设置的全局调优参数。详细信息（包括选择性启用的重试配置）请参见[模型指南](/openai-agents-js/zh/guides/models#modelsettings)。 | +| `handoffInputFilter` | `HandoffInputFilter` | 在执行交接时变更输入项（前提是交接本身未定义该项）。 | | `inputGuardrails` | `InputGuardrail[]` | 应用于*初始*用户输入的护栏。 | | `outputGuardrails` | `OutputGuardrail[]` | 应用于*最终*输出的护栏。 | | `tracingDisabled` | `boolean` | 完全禁用 OpenAI 追踪。 | -| `traceIncludeSensitiveData` | `boolean` | 在仍然发出 span 的同时，排除追踪中的 LLM/工具输入与输出。 | +| `traceIncludeSensitiveData` | `boolean` | 从 trace 中排除 LLM/工具输入与输出，同时仍发出 span。 | | `workflowName` | `string` | 显示在 Traces 仪表板中——有助于对相关运行进行分组。 | -| `traceId` / `groupId` | `string` | 手动指定 trace 或 group ID，而不是让 SDK 自动生成。 | +| `traceId` / `groupId` | `string` | 手动指定 trace 或 group ID，而不是由 SDK 自动生成。 | | `traceMetadata` | `Record` | 附加到每个 span 的任意元数据。 | | `tracing` | `TracingConfig` | 每次运行的追踪覆盖项（例如导出 API key）。 | | `sessionInputCallback` | `SessionInputCallback` | 此 runner 上所有运行的默认历史合并策略。 | -| `callModelInputFilter` | `CallModelInputFilter` | 在每次模型调用前编辑模型输入的全局 hook。 | -| `toolErrorFormatter` | `ToolErrorFormatter` | 用于自定义返回给模型的工具审批拒绝消息的全局 hook。 | -| `reasoningItemIdPolicy` | `ReasoningItemIdPolicy` | 在将生成的条目重放到后续模型调用时，保留或省略 reasoning-item `id` 的默认策略。 | +| `callModelInputFilter` | `CallModelInputFilter` | 在每次模型调用前编辑模型输入的全局钩子。 | +| `toolErrorFormatter` | `ToolErrorFormatter` | 用于自定义返回给模型的工具审批拒绝消息的全局钩子。 | +| `reasoningItemIdPolicy` | `ReasoningItemIdPolicy` | 在将已生成条目回放到后续模型调用时，保留或省略 reasoning-item `id` 的默认策略。 | +| `sandbox` | `SandboxRunConfig` | `SandboxAgent` 运行的默认 Sandbox 运行时配置。 | ## 状态与对话管理 ### 选择一种记忆策略 -将状态带入下一轮的常见方式有四种： +将状态带入下一轮通常有四种方式： -| 策略 | 状态存储位置 | 最适合 | 下一轮传递的内容 | +| Strategy | Where state lives | Best for | What you pass on the next turn | | --- | --- | --- | --- | | `result.history` | 您应用的内存 | 小型聊天循环、完全手动控制、任意 provider | `result.history` | -| `session` | 您的存储 + SDK | 持久聊天状态、可恢复运行、自定义存储 | 同一个 `session` 实例（或基于存储的实例） | -| `conversationId` | OpenAI Conversations API | 跨 worker/服务共享的服务器端状态 | 同一个 `conversationId` 加上仅新的用户轮次 | -| `previousResponseId` | 仅 OpenAI Responses API | 不创建对话时，最简单的服务器管理式延续 | `result.lastResponseId` 加上仅新的用户轮次 | +| `session` | 您的存储 + SDK | 持久化聊天状态、可恢复运行、自定义存储 | 同一个 `session` 实例（或基于存储的实例） | +| `conversationId` | OpenAI Conversations API | 在多个 worker/服务之间共享服务器端状态 | 相同的 `conversationId`，外加仅新的用户轮次 | +| `previousResponseId` | 仅 OpenAI Responses API | 不创建对话时最简单的服务器托管延续方式 | `result.lastResponseId`，外加仅新的用户轮次 | -`result.history` 和 `session` 由客户端管理。`conversationId` 和 `previousResponseId` 由 OpenAI 管理，并且仅适用于您使用 OpenAI Responses API 的情况。在大多数应用中，每段对话选择一种持久化策略即可。除非您有意对两层状态进行协调，否则混合使用客户端管理的历史与服务器管理的状态可能会导致上下文重复。 +`result.history` 和 `session` 由客户端管理。`conversationId` 和 `previousResponseId` 由 OpenAI 管理，并且仅适用于您使用 OpenAI Responses API 的情况。在大多数应用中，每段对话选择一种持久化策略即可。除非您有意协调这两层，否则混用客户端管理的历史和服务器端管理的状态可能会造成上下文重复。 + +Sandbox 智能体还会增加另一层状态：实时 Sandbox 工作区。对话历史请使用常规 SDK 的 `session`、`conversationId` 或 `previousResponseId`；而 Sandbox 文件系统状态请使用 `sandbox.session`、`sandbox.sessionState`、`RunState` 或快照。工作区生命周期请参见[Sandbox agents](/openai-agents-js/zh/guides/sandbox-agents/concepts)。 ### 对话 / 聊天线程 -每次调用 `runner.run()`（或 `run()` 工具）都表示您应用层对话中的一个**轮次**。您可以自行决定向终端用户展示多少 `RunResult` 内容——有时只展示 `finalOutput`，有时则展示每一个生成条目。 +每次调用 `runner.run()`（或 `run()` 工具）都表示应用层对话中的一个**轮次**。您可以自行决定向最终用户展示多少 `RunResult` 内容——有时只展示 `finalOutput`，有时则展示每个生成条目。 - + 交互版本请参见[聊天示例](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts)。 -#### 服务器管理的对话 +#### 服务器托管的对话 -您可以让 OpenAI Responses API 为您持久化对话历史，而不必在每一轮都发送整个本地对话历史。这在您协调长对话或多个服务时非常有用。使用下面任一服务器管理方式时，每次请求只需传递新一轮的输入。API 会为您复用先前状态。详见[对话状态指南](https://developers.openai.com/api/docs/guides/conversation-state)。 +您可以让 OpenAI Responses API 为您持久化对话历史，而不是在每一轮都发送整个本地对话历史。当您需要协调长对话或多个服务时，这非常有用。使用以下任一服务器托管方式时，每次请求只需传入新一轮的输入。API 会为您复用先前状态。详情请参见[对话状态指南](https://developers.openai.com/api/docs/guides/conversation-state)。 OpenAI 提供了两种复用服务器端状态的方式： -##### 1. 使用 `conversationId` 表示整个对话 +##### 1. 使用 `conversationId` 表示整段对话 -您可以使用 [Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) 创建一次对话，然后在每一轮中复用它的 ID。SDK 会自动只包含新生成的条目。 +您可以通过 [Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) 创建一次对话，然后在每一轮复用其 ID。SDK 会自动仅包含新生成的条目。 - + ##### 2. 使用 `previousResponseId` 从上一轮继续 -如果您本来就只想从 Responses API 开始，也可以使用上一个响应返回的 ID 将每个请求串联起来。这样无需创建完整的对话资源，也能在多轮之间保持上下文。 +如果您只想基于 Responses API 开始，也可以使用上一次响应返回的 ID 串联每次请求。这样无需创建完整的对话资源，也能在多轮之间保持上下文。 -`conversationId` 和 `previousResponseId` 互斥。如果您希望拥有一个可在多个系统间共享的具名对话资源，请使用 `conversationId`；如果您只是想要从一个响应延续到下一个响应的、成本最低的 SDK 级延续机制，请使用 `previousResponseId`。 +`conversationId` 和 `previousResponseId` 互斥。若您希望拥有一个可在多个系统间共享的具名对话资源，请使用 `conversationId`；若您只想要从一个响应延续到下一个响应的、成本最低的 SDK 级延续机制，请使用 `previousResponseId`。 -## Hook 与自定义 +## 钩子与自定义 ### 模型输入过滤器 -使用 `callModelInputFilter` 在调用模型**之前**编辑模型输入。这个 hook 会接收当前智能体、上下文以及合并后的输入项（包括存在时的会话历史）。返回更新后的 `input` 数组和可选的 `instructions`，以便隐藏敏感数据、丢弃旧消息或注入额外的系统指导。 +使用 `callModelInputFilter` 可在调用模型**之前**编辑模型输入。该钩子会接收当前智能体、上下文以及合并后的输入项（包括存在时的会话历史）。您可以返回更新后的 `input` 数组和可选的 `instructions`，以便隐藏敏感数据、丢弃旧消息，或注入额外的系统指导。 -您可以在每次运行中通过 `runner.run(..., { callModelInputFilter })` 设置它，也可以在 `Runner` 配置中将其设为默认值（即 `RunConfig` 中的 `callModelInputFilter`）。 +您可以在单次运行中通过 `runner.run(..., { callModelInputFilter })` 设置它，也可以在 `Runner` 配置中将其作为默认值设置（即 `RunConfig` 中的 `callModelInputFilter`）。 -返回值必须是一个 `ModelInputData` 对象：`{ input: AgentInputItem[], instructions? }`。其中 `input` 字段是必需的，且必须为数组。返回其他任何结构都会抛出 `UserError`。 +返回值必须是一个 `ModelInputData` 对象：`{ input: AgentInputItem[], instructions? }`。其中 `input` 字段是必需的，并且必须是数组。返回任何其他结构都会抛出 `UserError`。 -SDK 会在调用过滤器之前复制已准备好的轮次输入。如果您同时使用了 `session`，那么被过滤后的副本就是最终被持久化的内容，因此这里执行的脱敏或截断也会反映在存储的会话历史中。 +SDK 会在调用过滤器前克隆准备好的当前轮输入。如果您同时使用了 `session`，那么被过滤后的克隆对象也会被持久化，因此这里执行的脱敏或截断同样会反映在存储的会话历史中。 -使用 `conversationId` 或 `previousResponseId` 时，该 hook 会作用于为下一次 Responses API 调用准备的载荷。先前由服务器管理的上下文会由 API 恢复，因此该次调用中的过滤后数组，可能已经只表示新一轮的增量，而不是对更早历史的完整重放。如果您需要在此最终过滤步骤之前，改变已存储历史与当前轮次的合并方式，请使用 `sessionInputCallback`。 +对于 `conversationId` 或 `previousResponseId`，该钩子会在下一次 Responses API 调用的准备负载上运行。先前由服务器托管的上下文会由 API 恢复，因此该次调用中经过过滤的数组可能仅表示新一轮的增量，而不是更早历史的完整回放。如果您需要在最终过滤步骤之前更改已存储历史与当前轮次的合并方式，请使用 `sessionInputCallback`。 ### 工具错误格式化器 -使用 `toolErrorFormatter` 自定义当工具调用被拒绝时，回传给模型的审批拒绝消息。这样您就可以返回特定领域的措辞（例如合规性指导），而不是使用 SDK 的默认消息。 +使用 `toolErrorFormatter` 可以自定义当工具调用被拒绝时发送回模型的审批拒绝消息。这样，您可以返回领域特定的措辞（例如合规指导），而不是使用 SDK 的默认消息。 -该格式化器可以按运行设置（`runner.run(..., { toolErrorFormatter })`），也可以在 `RunConfig` 中全局设置（即 `new Runner(...)` 中的 `toolErrorFormatter`）。 +格式化器既可以按单次运行设置（`runner.run(..., { toolErrorFormatter })`），也可以在 `RunConfig` 中全局设置（`new Runner(...)` 中的 `toolErrorFormatter`）。 -该格式化器是审批拒绝场景下的全局后备方案。如果您使用 `result.state.reject(interruption, { message: '...' })` 拒绝某个特定中断，则该次调用中的 `message` 优先于 `toolErrorFormatter`。如果两者都未提供，SDK 会回退到默认拒绝文本：`Tool execution was not approved.` +该格式化器是审批拒绝消息的全局后备方案。如果您使用 `result.state.reject(interruption, { message: '...' })` 拒绝某个特定中断，则该次调用的 `message` 优先级高于 `toolErrorFormatter`。如果两者都未提供，SDK 会回退到默认拒绝文本：`Tool execution was not approved.` -该格式化器当前会在 `approval_rejected` 事件中运行，并接收： +该格式化器当前在 `approval_rejected` 事件中运行，并接收以下内容： - `kind`（当前始终为 `'approval_rejected'`） - `toolType`（`'function'`、`'computer'`、`'shell'` 或 `'apply_patch'`） @@ -178,21 +190,21 @@ SDK 会在调用过滤器之前复制已准备好的轮次输入。如果您同 - `defaultMessage`（SDK 的后备消息，当前为 `Tool execution was not approved.`） - `runContext` -返回一个字符串以覆盖该消息，或返回 `undefined` 以保留 SDK 默认值。如果格式化器抛出异常（或返回非字符串值），SDK 会记录一条警告，并回退到默认审批拒绝消息。 +返回一个字符串以覆盖该消息，或返回 `undefined` 以保留 SDK 默认值。如果格式化器抛出异常（或返回非字符串值），SDK 会记录一条警告，并回退到默认的审批拒绝消息。 -### Reasoning item ID 策略 +### Reasoning 条目 ID 策略 -使用 `reasoningItemIdPolicy` 来控制：当 SDK 将先前生成的运行条目重新转换为 `AgentInputItem[]` 以供后续模型输入时，reasoning item 是否保留其 `id` 字段。 +使用 `reasoningItemIdPolicy` 可以控制：当 SDK 将先前生成的运行条目重新转换为 `AgentInputItem[]`，供后续模型输入使用时，reasoning 条目是否保留其 `id` 字段。 -这会影响 SDK 将生成的模型条目重放为输入的场景，例如： +这会影响 SDK 将已生成模型条目回放为输入的场景，例如： -- 同一次运行中的后续模型调用（例如工具执行之后）； -- 后续轮次中，将生成条目复用为输入/历史记录； -- 从保存的 `RunState` 恢复运行； -- 派生的结果视图，例如 `result.history` / `result.output`（它们是模型输入形状的数组）。 -- `'preserve'`（默认）会保留 reasoning item ID。 -- `'omit'` 会在这些 reasoning item 被重新作为输入发送前去掉其 `id` 字段。 -- 非 reasoning item 不受影响。 +- 同一次运行中的后续模型调用（例如在工具执行后）； +- 后续轮次中复用已生成条目作为输入/历史； +- 从已保存的 `RunState` 恢复的运行； +- 派生结果视图，例如 `result.history` / `result.output`（它们是模型输入形状的数组）。 +- `'preserve'`（默认）保留 reasoning 条目的 ID。 +- `'omit'` 会在这些 reasoning 条目作为输入再次发送前移除其 `id` 字段。 +- 非 reasoning 条目不受影响。 以下内容**不会**因此改变： @@ -200,27 +212,27 @@ SDK 会在调用过滤器之前复制已准备好的轮次输入。如果您同 - 运行条目（`result.newItems`）； - provider 返回的当前轮模型输出。 -换句话说，该策略作用于 SDK 如何基于先前生成的条目构建**下一次输入**。 +换句话说，该策略适用于 SDK 根据先前已生成条目构建**下一次输入**时。 -您可以按运行设置该策略（`runner.run(..., { reasoningItemIdPolicy: 'omit' })`），也可以将其设为 runner 的默认值（`new Runner({ reasoningItemIdPolicy: 'omit', ... })`）。从保存的 `RunState` 恢复时，除非您显式覆盖，否则会复用之前已解析出的策略。 +您可以按单次运行设置该策略（`runner.run(..., { reasoningItemIdPolicy: 'omit' })`），也可以将其设为 runner 默认值（`new Runner({ reasoningItemIdPolicy: 'omit', ... })`）。当从已保存的 `RunState` 恢复时，除非您覆盖它，否则会复用先前已解析出的策略。 #### 与 `callModelInputFilter` 的交互 -`reasoningItemIdPolicy` 会先于 `callModelInputFilter` 应用。如果您需要自定义行为，`callModelInputFilter` 仍然可以在模型调用前检查准备好的输入，并手动重新引入或移除 reasoning ID。 +`reasoningItemIdPolicy` 会先于 `callModelInputFilter` 应用。如果您需要自定义行为，`callModelInputFilter` 仍然可以检查准备好的输入，并在模型调用前手动重新引入或移除 reasoning ID。 #### 何时使用 `'omit'` -当您希望被重放的 reasoning item 以不带 ID 的方式标准化时，请使用 `'omit'`（例如，为了让转发/重放的模型输入更简单，或满足您应用流程中的集成要求）。 +当您希望回放的 reasoning 条目以不带 ID 的形式被标准化时，请使用 `'omit'`（例如，为了让转发/回放的模型输入更简单，或满足应用流水线中的集成要求）。 -如果您的后端/provider 会因重放的 reasoning item 而拒绝请求并返回校验错误（例如，后续输入中与 reasoning item ID 有关的 HTTP `400` 错误），这也是一个有用的故障排除选项。在这类情况下，使用 `'omit'` 去除重放的 reasoning ID，可以避免发送那些会被后端视为新请求中的无效 ID。 +如果您的后端/provider 因请求校验错误而拒绝回放的 reasoning 条目（例如，与后续输入中的 reasoning 条目 ID 相关的 HTTP `400` 错误），这也是一个有用的故障排除选项。在这些情况下，使用 `'omit'` 去掉回放的 reasoning ID，可以避免发送那些被后端视为新请求中无效的 ID。 -如果您希望 SDK 在重放输入中保留 reasoning item ID，并且您的集成能够接受它们，请继续使用 `'preserve'`。 +如果您希望 SDK 在回放输入中保留 reasoning 条目 ID，且您的集成能够接受它们，请保持使用 `'preserve'`。 ## 错误与恢复 ### 错误处理器 -使用 `errorHandlers` 将支持的运行时错误转换为最终输出，而不是直接抛出异常。当前仅支持 `maxTurns`。 +使用 `errorHandlers` 可将受支持的运行时错误转换为最终输出，而不是直接抛出。目前仅支持 `maxTurns`。 - `errorHandlers.maxTurns` 仅处理最大轮次错误。 - `errorHandlers.default` 用作受支持类型的后备处理器。 @@ -230,31 +242,31 @@ SDK 会在调用过滤器之前复制已准备好的轮次输入。如果您同 SDK 会抛出一小组可供捕获的错误： -- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)——已达到 `maxTurns`。 -- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror)——模型生成了无效输出（例如格式错误的 JSON、未知工具）。 -- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered)——护栏违规。 -- [`ToolInputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/toolinputguardrailtripwiretriggered) / [`ToolOutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/tooloutputguardrailtripwiretriggered)——工具护栏违规。 -- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror)——护栏未能完成执行。 -- [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror)——某个函数工具超出了 `timeoutMs`，且使用了 `timeoutBehavior: 'raise_exception'`。 -- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror)——函数工具执行因非超时错误而失败。 -- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror)——任何基于配置或用户输入抛出的错误。 +- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) —— 达到 `maxTurns`。 +- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) —— 模型产生了无效输出（例如格式错误的 JSON、未知工具）。 +- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) —— 护栏违规。 +- [`ToolInputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/toolinputguardrailtripwiretriggered) / [`ToolOutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/tooloutputguardrailtripwiretriggered) —— 工具护栏违规。 +- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) —— 护栏未能完成执行。 +- [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror) —— 函数工具超过了 `timeoutMs`，并使用了 `timeoutBehavior: 'raise_exception'`。 +- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) —— 函数工具因非超时错误而执行失败。 +- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) —— 基于配置或用户输入抛出的任意错误。 -它们都继承自基础 `AgentsError` 类，该类可能提供 `state` 属性，用于访问当前的运行状态。 +这些错误都继承自基础类 `AgentsError`，其可能提供 `state` 属性以访问当前运行状态。 -下面是一个处理 `GuardrailExecutionError` 的代码示例。由于输入护栏只会在第一条用户输入上运行，该示例会使用原始输入和上下文重新启动运行。它还展示了如何复用保存的状态，在不再次调用模型的情况下重试输出护栏： +下面是一个处理 `GuardrailExecutionError` 的代码示例。由于输入护栏只会在第一次用户输入时运行，因此该示例会使用原始输入和上下文重新启动运行。它还展示了如何复用已保存的状态，在不再次调用模型的情况下重试输出护栏： -输入重试与输出重试的区别： +输入与输出重试的区别： -- 输入护栏只会在一次运行的第一条用户输入上运行，因此如果要重试，您必须使用相同的输入/上下文启动一次新的运行——传入已保存的 `state` 不会重新触发输入护栏。 -- 输出护栏在模型响应之后运行，因此您可以复用 `GuardrailExecutionError` 中保存的 `state`，在不再次调用模型的情况下重新运行输出护栏。 +- 输入护栏只会在一次运行中的第一次用户输入上执行，因此若要重试它们，必须使用相同的输入/上下文启动一次全新的运行——传入已保存的 `state` 不会再次触发输入护栏。 +- 输出护栏会在模型响应后运行，因此您可以复用 `GuardrailExecutionError` 中保存的 `state`，在不再次调用模型的情况下重新运行输出护栏。 -运行上述示例时，您会看到如下输出： +运行上述示例时，您将看到以下输出： ``` Guardrail execution failed (input): Error: Input guardrail failed to complete: Error: Something is wrong! @@ -272,4 +284,4 @@ Output guardrail tripped after retry with saved state - [会话](/openai-agents-js/zh/guides/sessions)：了解由 SDK 管理的持久化记忆。 - [工具](/openai-agents-js/zh/guides/tools)：了解运行循环中使用的能力。 - [模型](/openai-agents-js/zh/guides/models)：了解 provider 配置和 Responses 传输。 -- 添加[护栏](/openai-agents-js/zh/guides/guardrails)或[追踪](/openai-agents-js/zh/guides/tracing)，以满足生产就绪需求。 +- 为生产环境准备可添加[护栏](/openai-agents-js/zh/guides/guardrails)或[追踪](/openai-agents-js/zh/guides/tracing)。 diff --git a/docs/src/content/docs/zh/guides/sandbox-agents.mdx b/docs/src/content/docs/zh/guides/sandbox-agents.mdx new file mode 100644 index 000000000..e31aa3900 --- /dev/null +++ b/docs/src/content/docs/zh/guides/sandbox-agents.mdx @@ -0,0 +1,66 @@ +--- +title: 快速上手 +description: Create your first sandbox agent with an isolated workspace, filesystem tools, shell commands, and sandbox session state. +--- + +import { Aside, Code } from '@astrojs/starlight/components'; +import basicExample from '../../../../../../examples/docs/sandbox-agents/basic.ts?raw'; + + + +现代智能体在能够对文件系统中的真实文件进行操作时效果最佳。Agents SDK 中的 **Sandbox Agents** 为模型提供了一个持久化工作区，使其可以搜索大型文档集、编辑文件、运行命令、生成产物，并从已保存的 sandbox 状态中继续工作。 + +SDK 为您提供了这套执行基础设施，而无需您自己拼装文件暂存、文件系统工具、shell 访问、sandbox 生命周期、快照以及特定提供商的胶水代码。您仍然保持常规的 `Agent` 和 `Runner` 流程，然后再添加工作区的 `Manifest`、用于 sandbox 原生工具的 capabilities，以及用于指定工作运行位置的 `sandbox` 运行选项。 + +## 前提条件 + +- Node.js 22 或更高版本。 +- 对 OpenAI Agents SDK 有基本了解。 +- 一个 sandbox client。对于本地开发，建议从 `UnixLocalSandboxClient` 开始。 + +## 安装 + +如果您尚未安装 SDK： + +```bash +npm install @openai/agents +``` + +对于基于 Docker 的 sandbox，请在本地安装 Docker，并使用来自 `@openai/agents/sandbox/local` 的 `DockerSandboxClient`。 + +如果您使用带有 `tty: true` 的交互式本地 PTY 会话，运行 SDK 的进程还需要能以 `python3` 的形式使用 Python 3，或通过 `OPENAI_AGENTS_PYTHON` 指定。非 PTY shell 命令不需要 Python。 + +## 本地 sandbox 智能体的创建 + +此示例会将本地仓库暂存到 `repo/` 下，延迟加载本地 skills，并让 runner 为本次运行创建一个 Unix 本地 sandbox 会话。 + + + +该示例特意设计得类似 Python SDK 的快速开始：智能体定义拥有 manifest 和 capabilities，而运行配置仅为本次运行选择 sandbox client。 + +## 关键选择 + +当基础运行成功后，大多数人接下来会关注这些选择： + +- `defaultManifest`：为新的 sandbox 会话提供的文件、仓库、目录和挂载。 +- `instructions`：应在各个提示之间统一适用的简短工作流规则。 +- `baseInstructions`：用于替换 SDK sandbox 提示的高级兜底选项。 +- `capabilities`：sandbox 原生工具，例如文件系统编辑/图像检查、shell、skills、memory 和 compaction。 +- `runAs`：供面向模型的工具使用的 sandbox 用户身份。 +- `sandbox.client`：sandbox 后端。 +- `sandbox.session`、`sandbox.sessionState` 或 `sandbox.snapshot`：后续运行如何重新连接到先前的工作。 + +## 后续阅读 + +- [Concepts](/openai-agents-js/zh/guides/sandbox-agents/concepts)：了解 manifest、capabilities、权限、快照、运行配置和组合模式。 +- [Sandbox clients](/openai-agents-js/zh/guides/sandbox-agents/clients)：选择 Unix 本地、Docker、托管提供商和挂载策略。 +- [Agent memory](/openai-agents-js/zh/guides/sandbox-agents/memory)：保留并复用先前 sandbox 运行中的经验。 + +如果 shell 访问只是偶尔使用的单一工具，请先从[工具](/openai-agents-js/zh/guides/tools)指南中的托管 shell 开始。当工作区隔离、sandbox client 的选择或 sandbox 会话恢复行为是设计的一部分时，再考虑使用 sandbox 智能体。 diff --git a/docs/src/content/docs/zh/guides/tools.mdx b/docs/src/content/docs/zh/guides/tools.mdx index 174e177ad..6a3dd1984 100644 --- a/docs/src/content/docs/zh/guides/tools.mdx +++ b/docs/src/content/docs/zh/guides/tools.mdx @@ -16,22 +16,23 @@ import mcpLocalServer from '../../../../../../examples/docs/tools/mcpLocalServer import codexToolExample from '../../../../../../examples/docs/tools/codexTool.ts?raw'; import codexRunContextThreadExample from '../../../../../../examples/docs/tools/codexRunContextThread.ts?raw'; -工具让智能体能够**执行操作**——获取数据、调用外部 API、执行代码，甚至使用计算机。JavaScript/TypeScript SDK 支持六类工具： +工具让智能体能够**执行操作**——获取数据、调用外部 API、执行代码，甚至使用计算机。JavaScript/TypeScript SDK 支持七类工具： -> 在阅读过[智能体](/openai-agents-js/zh/guides/agents)并明确应由哪个智能体负责该任务、且希望为其赋予能力后，再阅读本页。如果您仍在不同委派模式之间做选择，请参阅[智能体编排](/openai-agents-js/zh/guides/multi-agent)。 +> 在了解应由哪个智能体负责该任务，并希望为其赋予能力后，请在阅读[智能体](/openai-agents-js/zh/guides/agents)之后再阅读本页。如果您仍在权衡不同的委派模式，请参阅[智能体编排](/openai-agents-js/zh/guides/multi-agent)。 1. **OpenAI 托管工具**——与模型一起在 OpenAI 服务器上运行。_（Web 搜索、文件搜索、Code Interpreter、图像生成、工具搜索）_ -2. **内置执行工具**——由 SDK 提供、在模型之外执行的工具。_（computer use 和 apply_patch 在本地运行；shell 可在本地或托管容器中运行）_ -3. **函数工具**——用 JSON schema 封装任意本地函数，以便 LLM 调用它。 -4. **Agents as tools**——将整个智能体作为可调用工具暴露出来。 -5. **MCP 服务器**——连接一个 Model Context Protocol 服务器（本地或远程）。 -6. **实验性：Codex 工具**——将 Codex SDK 封装为函数工具，以运行感知工作区的任务。 +2. **内置执行工具**——由 SDK 提供、在模型之外执行的工具。_（计算机操作和 apply_patch 在本地运行；shell 可在本地或托管容器中运行）_ +3. **函数工具**——用 JSON schema 封装任意本地函数，以便 LLM 调用。 +4. **Agents as tools**——将整个智能体暴露为可调用工具。 +5. **MCP 服务器**——挂载一个 Model Context Protocol 服务器（本地或远程）。 +6. **Sandbox 能力**——将工作区作用域的 shell、文件系统、技能、内存或压缩工具附加到 `SandboxAgent`。 +7. **实验性：Codex 工具**——将 Codex SDK 封装为函数工具，以运行具备工作区感知能力的任务。 --- ## 工具类别 -本指南的其余部分将先介绍每类工具，然后总结跨类别的工具选择与提示编写建议。 +本指南其余部分将先介绍各类工具，然后总结跨类别的工具选择与提示编写建议。 ### 1. 托管工具（OpenAI Responses API） @@ -40,24 +41,24 @@ import codexRunContextThreadExample from '../../../../../../examples/docs/tools/ | 工具 | 类型字符串 | 用途 | | --- | --- | --- | | Web 搜索 | `'web_search'` | 互联网搜索。 | -| 文件 / 检索搜索 | `'file_search'` | 查询托管在 OpenAI 上的向量存储。 | +| 文件 / 检索搜索 | `'file_search'` | 查询由 OpenAI 托管的向量存储。 | | Code Interpreter | `'code_interpreter'` | 在沙箱环境中运行代码。 | -| 图像生成 | `'image_generation'` | 根据文本生成图像。 | +| 图像生成 | `'image_generation'` | 基于文本生成图像。 | | 工具搜索 | `'tool_search'` | 在运行时加载延迟函数工具、命名空间或可搜索的 MCP 工具。 | -SDK 提供了返回托管工具定义的辅助函数： +SDK 提供了一些辅助函数，用于返回托管工具定义： | 辅助函数 | 说明 | | --- | --- | | `webSearchTool(options?)` | 提供适合 JS 的选项，例如 `searchContextSize`、`userLocation` 和 `filters.allowedDomains`。 | -| `fileSearchTool(ids, options?)` | 第一个参数接收一个或多个向量存储 ID，另可传入 `maxNumResults`、`includeSearchResults`、`rankingOptions` 和过滤器等选项。 | +| `fileSearchTool(ids, options?)` | 第一个参数接受一个或多个向量存储 ID，另可传入 `maxNumResults`、`includeSearchResults`、`rankingOptions` 和过滤器等选项。 | | `codeInterpreterTool(options?)` | 未提供 `container` 时，默认使用自动管理的容器。 | -| `imageGenerationTool(options?)` | 支持图像生成配置，例如 `model`、`size`、`quality`、`background`、`inputFidelity`、`inputImageMask`、`moderation`、`outputCompression`、`partialImages` 和输出格式。 | -| `toolSearchTool(options?)` | 添加内置的 `tool_search` 辅助工具。可与设置了 `deferLoading: true` 的延迟函数工具或托管 MCP 工具配合使用。默认支持托管执行，也可通过 `execution: 'client'` 加上 `execute` 使用客户端执行。 | +| `imageGenerationTool(options?)` | 支持图像生成配置，如 `model`、`size`、`quality`、`background`、`inputFidelity`、`inputImageMask`、`moderation`、`outputCompression`、`partialImages` 和输出格式。 | +| `toolSearchTool(options?)` | 添加内置的 `tool_search` 辅助工具。可与设置了 `deferLoading: true` 的延迟函数工具或托管 MCP 工具配合使用。默认支持托管执行，也可通过 `execution: 'client'` 加上 `execute` 启用客户端执行。 | -这些辅助函数会将 JavaScript/TypeScript 友好的选项名映射到底层 OpenAI Responses API 工具负载。完整工具 schema 以及排序选项、语义过滤器等高级选项，请参阅官方[OpenAI 工具指南](https://developers.openai.com/api/docs/guides/tools)；当前内置工具搜索流程和模型可用性，请参阅官方[工具搜索指南](https://developers.openai.com/api/docs/guides/tools-tool-search)。 +这些辅助函数会将适合 JavaScript/TypeScript 的选项名称映射到底层 OpenAI Responses API 工具负载。完整工具 schema 以及排名选项、语义过滤器等高级选项，请参阅官方[OpenAI 工具指南](https://developers.openai.com/api/docs/guides/tools)；当前内置工具搜索流程及模型可用性，请参阅官方[工具搜索指南](https://developers.openai.com/api/docs/guides/tools-tool-search)。 --- @@ -65,62 +66,65 @@ SDK 提供了返回托管工具定义的辅助函数： 这些工具内置于 SDK 中，但执行发生在模型响应之外： -- **计算机操作**——实现 `Computer` 接口并将其传给 `computerTool()`。这始终针对您提供的本地 `Computer` 实现运行。 -- **Shell**——可以提供本地 `Shell` 实现，或通过 `shellTool({ environment })` 配置托管容器环境。 -- **Apply patch**——实现 `Editor` 接口并将其传给 `applyPatchTool()`。这始终针对您提供的本地 `Editor` 实现运行。 +- **计算机操作**——实现 `Computer` 接口并将其传给 `computerTool()`。它始终针对您提供的本地 `Computer` 实现运行。 +- **Shell**——可提供本地 `Shell` 实现，或使用 `shellTool({ environment })` 配置托管容器环境。 +- **Apply patch**——实现 `Editor` 接口并将其传给 `applyPatchTool()`。它始终针对您提供的本地 `Editor` 实现运行。 +- **Sandbox shell 和文件系统工具**——当这些操作应在沙箱工作区内运行时，在 `SandboxAgent` 上使用 `shell()`、`filesystem()`、`skills()`、`memory()` 或 `compaction()`。 -工具调用仍由模型发起请求，但具体工作由您的应用程序或已配置的执行环境完成。 +工具调用仍由模型发起请求，但实际工作由您的应用程序或已配置的执行环境完成。 + +Sandbox 能力工具与进程级内置工具不同：它们绑定到当前 `SandboxAgent` 运行所对应的活动沙箱会话。如果工具应在智能体的隔离工作区中操作，而不是在您的应用进程中操作，请使用[Sandbox agents](/openai-agents-js/zh/guides/sandbox-agents)。 -#### Computer 工具细节 +#### 计算机工具细节 -`computerTool()` 可以接受以下任一形式： +`computerTool()` 可接受以下任一形式： - 一个具体的 `Computer` 实例。 - 一个为每次运行创建 `Computer` 的初始化函数。 -- 一个包含 `{ create, dispose }` 的提供者对象，用于需要按运行范围进行初始化与清理的场景。 +- 一个带有 `{ create, dispose }` 的 provider 对象，用于需要按运行范围进行初始化和清理的场景。 -要使用 OpenAI 当前的计算机操作路径，请设置支持计算机操作的模型，例如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)。当请求模型显式指定时，SDK 会发送 GA 内置的 `computer` 工具格式。如果生效模型仍来自存储的提示或其他旧集成，SDK 会继续使用旧版 `computer_use_preview` 线格式以保持兼容，除非您通过 `modelSettings.toolChoice: 'computer'` 显式启用 GA 路径。 +要使用 OpenAI 当前的计算机操作能力路径，请设置支持计算机操作的模型，例如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)。当请求模型被显式指定时，SDK 会发送 GA 内置的 `computer` 工具结构。如果最终生效的模型仍来自存储提示或其他较旧集成，SDK 会继续使用旧版 `computer_use_preview` 传输结构以保持兼容性，除非您通过 `modelSettings.toolChoice: 'computer'` 显式启用 GA 路径。 -GA 的计算机调用可以在单个 `computer_call` 中包含批量 `actions[]`。SDK 会按顺序执行它们，对每个 action 评估 `needsApproval`，并将最终截图作为工具输出返回。如果您基于 `interruption.rawItem` 构建审批 UI，在存在 `actions` 时请读取它，否则回退到旧版预览项中的 `action`。 +GA 计算机调用可在单个 `computer_call` 中包含批量 `actions[]`。SDK 会按顺序执行它们，对每个操作评估 `needsApproval`，并将最终截图作为工具输出返回。如果您基于 `interruption.rawItem` 构建审批 UI，在存在 `actions` 时请读取 `actions`，对于旧版预览项则回退到 `action`。 -当高影响的计算机操作需要暂停供用户审核时，请使用 `needsApproval`；如果您希望确认或拒绝某次计算机调用报告的待处理安全检查，请使用 `onSafetyCheck`。关于模型侧指导和迁移细节，请参阅官方[OpenAI 计算机操作指南](https://developers.openai.com/api/docs/guides/tools-computer-use/)及其[迁移说明](https://developers.openai.com/api/docs/guides/tools-computer-use/#migration-from-computer-use-preview)。 +当高影响的计算机操作应暂停以供用户审核时，请使用 `needsApproval`；当您希望确认或拒绝计算机调用所报告的待处理安全检查时，请使用 `onSafetyCheck`。关于模型侧的指导和迁移细节，请参阅官方[OpenAI 计算机操作指南](https://developers.openai.com/api/docs/guides/tools-computer-use/)及其[迁移说明](https://developers.openai.com/api/docs/guides/tools-computer-use/#migration-from-computer-use-preview)。 #### Shell 工具细节 `shellTool()` 有两种模式： -- 本地模式：提供 `shell`，并可选提供 `environment: { type: 'local', skills }`，以及用于自动审批处理的 `needsApproval` 和 `onApproval`。 -- 托管容器模式：提供 `environment`，其中 `type` 为 `container_auto` 或 `container_reference`。 +- 本地模式：提供 `shell`，并可选择提供 `environment: { type: 'local', skills }`，以及用于自动审批处理的 `needsApproval` 和 `onApproval`。 +- 托管容器模式：提供 `environment`，其 `type` 为 `container_auto` 或 `container_reference`。 在本地模式下，`environment.skills` 允许您通过 `name`、`description` 和文件系统 `path` 挂载本地技能。 在托管容器模式下，可通过以下任一方式配置 `shellTool({ environment })`： -- `type: 'container_auto'`，为当前运行创建托管容器。 -- `type: 'container_reference'`，通过 `containerId` 复用现有容器。 +- `type: 'container_auto'`：为当前运行创建托管容器。 +- `type: 'container_reference'`：通过 `containerId` 复用已有容器。 -托管的 `container_auto` 环境支持： +托管 `container_auto` 环境支持： - `networkPolicy`，包括带 `domainSecrets` 的允许列表。 - `fileIds`，用于挂载已上传文件。 -- `memoryLimit`，用于指定容器大小。 +- `memoryLimit`，用于容器规格设定。 - `skills`，可通过 `skill_reference` 或内联 zip 包提供。 -托管 shell 环境不接受 `shell`、`needsApproval` 或 `onApproval`，因为执行发生在托管容器环境中，而不是您的本地进程中。 +托管 shell 环境不接受 `shell`、`needsApproval` 或 `onApproval`，因为执行发生在托管容器环境中，而非您的本地进程中。 完整用法请参见 `examples/tools/local-shell.ts`、`examples/tools/container-shell-skill-ref.ts` 和 `examples/tools/container-shell-inline-skill.ts`。 #### Apply-patch 工具细节 -`applyPatchTool()` 复用了 `shellTool()` 的本地审批流程：在文件编辑前使用 `needsApproval` 暂停；如果您希望由应用层回调自动批准或拒绝，则使用 `onApproval`。 +`applyPatchTool()` 与 `shellTool()` 的本地审批流程一致：使用 `needsApproval` 在文件编辑前暂停；当您希望通过应用层回调自动批准或拒绝时，使用 `onApproval`。 --- ### 3. 函数工具 -您可以使用 `tool()` 辅助函数把**任意**函数变成工具。 +您可以使用 `tool()` 辅助函数将**任何**函数转换为工具。 string \| unknown \| Promise<...>`——您的业务逻辑。非字符串输出会被序列化后提供给模型。`context` 是可选的 `RunContext`；`details` 包含 `toolCall`、`resumeState` 和 `signal` 等元数据。 | | `errorFunction` | 否 | 自定义处理器 `(context, error) => string`，用于将内部错误转换为用户可见字符串。 | | `timeoutMs` | 否 | 每次调用的超时时间（毫秒）。必须大于 0 且小于等于 `2147483647`。 | | `timeoutBehavior` | 否 | 超时模式：`error_as_result`（默认）返回模型可见的超时消息，`raise_exception` 则抛出 `ToolTimeoutError`。 | | `timeoutErrorFunction` | 否 | 当 `timeoutBehavior` 为 `error_as_result` 时，用于超时输出的自定义处理器 `(context, timeoutError) => string`。 | -| `needsApproval` | 否 | 执行前需要人工审批。参见[人机协作指南](/openai-agents-js/zh/guides/human-in-the-loop)。 | -| `isEnabled` | 否 | 按运行条件性暴露工具；接受布尔值或谓词。 | -| `inputGuardrails` | 否 | 在工具执行前运行的护栏；可拒绝或抛错。参见[护栏](/openai-agents-js/zh/guides/guardrails#tool-guardrails)。 | -| `outputGuardrails` | 否 | 在工具执行后运行的护栏；可拒绝或抛错。参见[护栏](/openai-agents-js/zh/guides/guardrails#tool-guardrails)。 | +| `needsApproval` | 否 | 执行前要求人工审批。参见[人机协作](/openai-agents-js/zh/guides/human-in-the-loop)。 | +| `isEnabled` | 否 | 按运行条件决定是否暴露工具；接受布尔值或谓词函数。 | +| `inputGuardrails` | 否 | 在工具执行前运行的护栏；可拒绝或抛出异常。参见[护栏](/openai-agents-js/zh/guides/guardrails#tool-guardrails)。 | +| `outputGuardrails` | 否 | 在工具执行后运行的护栏；可拒绝或抛出异常。参见[护栏](/openai-agents-js/zh/guides/guardrails#tool-guardrails)。 | #### 函数工具超时 -使用 `timeoutMs` 来限制每次函数工具调用的时间。 +使用 `timeoutMs` 为每次函数工具调用设置时限。 - `timeoutBehavior: 'error_as_result'`（默认）会向模型返回 `Tool '' timed out after ms.`。 -- `timeoutBehavior: 'raise_exception'` 会抛出[`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror)，您可以将其作为[运行异常](/openai-agents-js/zh/guides/running-agents#exceptions)的一部分进行捕获。 +- `timeoutBehavior: 'raise_exception'` 会抛出 [`ToolTimeoutError`](/openai-agents-js/openai/agents-core/classes/tooltimeouterror)，您可将其作为[运行智能体](/openai-agents-js/zh/guides/running-agents#exceptions)中的运行异常来捕获。 - `timeoutErrorFunction` 允许您在 `error_as_result` 模式下自定义超时文本。 -- 超时会中止 `details.signal`，因此长时间运行的工具在侦听取消信号时可以及时停止。 +- 超时会中止 `details.signal`，因此长时间运行的工具在监听取消信号时可以及时停止。 -如果您直接调用函数工具，请使用 [`invokeFunctionTool`](/openai-agents-js/openai/agents/functions/invokefunctiontool) 来强制执行与常规智能体运行相同的超时行为。 +如果您直接调用函数工具，请使用 [`invokeFunctionTool`](/openai-agents-js/openai/agents/functions/invokefunctiontool)，以强制采用与正常智能体运行相同的超时行为。 -#### 非严格 JSON schema 工具 +#### 非严格 JSON-schema 工具 -如果您需要模型对无效或不完整输入进行*猜测*，那么在使用原始 JSON schema 时可以禁用严格模式： +如果您需要模型对无效或不完整输入进行*猜测*，则在使用原始 JSON schema 时可以禁用严格模式： -该示例有意混用了两种风格： +该示例有意混合了两种风格： -- `shippingLookup` 保持为顶层，因为它是一个独立的可搜索能力。 -- `crmTools` 使用 `toolNamespace()`，因为相关的 CRM 工具共享一个高层标签和描述。 -- 在同一请求中混合命名空间和顶层延迟工具是受支持的；工具搜索既可加载如 `crm` 这样的命名空间路径，也可加载如 `get_shipping_eta` 这样的顶层路径。 +- `shippingLookup` 保持为顶层工具，因为它是一个独立的可搜索能力。 +- `crmTools` 使用 `toolNamespace()`，因为相关的 CRM 工具共享同一个高级标签和描述。 +- 在同一请求中混合命名空间工具和顶层延迟工具是受支持的；工具搜索既可以加载 `crm` 这样的命名空间路径，也可以加载 `get_shipping_eta` 这样的顶层路径。 使用工具搜索时： - 为每个延迟函数工具标记 `deferLoading: true`。 -- 当多个相关工具应共享一个领域描述并作为一组加载时，使用 `toolNamespace({ name, description, tools })`。 -- 当工具是单一独立能力且工具名本身就是良好的搜索目标时，让它保持在顶层。 -- 只要任意延迟函数工具或托管 MCP 工具使用了 `deferLoading: true`，就要在同一个 `tools` 数组中添加 `toolSearchTool()`。 -- 将 `modelSettings.toolChoice` 保持为 `'auto'`。SDK 会拒绝按名称强制使用内置 `tool_search` 工具或某个延迟函数工具。 -- 默认使用托管执行。如果设置 `toolSearchTool({ execution: 'client', execute })`，标准 `run()` 循环仅支持内置的 `{ paths: string[] }` 客户端查询格式；自定义客户端 schema 需要您自己实现 Responses 循环。 -- 一个命名空间可以同时包含即时成员和延迟成员。即时成员无需工具搜索即可调用，而同一命名空间中的延迟成员会按需加载。 +- 当多个相关工具应共享同一个领域描述并作为一组加载时，使用 `toolNamespace({ name, description, tools })`。 +- 当某个工具是单一独立能力，且工具名称本身就是良好的搜索目标时，将其保持为顶层工具。 +- 只要任意延迟函数工具或托管 MCP 工具使用了 `deferLoading: true`，就要在同一个 `tools` 数组中加入 `toolSearchTool()`。 +- 将 `modelSettings.toolChoice` 保持为 `'auto'`。SDK 不允许通过名称强制选择内置 `tool_search` 工具或某个延迟函数工具。 +- 默认使用托管执行。如果您设置 `toolSearchTool({ execution: 'client', execute })`，标准 `run()` 循环只支持内置的 `{ paths: string[] }` 客户端查询结构；自定义客户端 schema 需要您自行实现 Responses 循环。 +- 一个命名空间可以同时包含即时成员和延迟成员。即时成员无需工具搜索即可调用，而同一命名空间中的延迟成员则按需加载。 - 延迟函数工具和 `toolNamespace()` 仅适用于 Responses。Chat Completions 会拒绝它们，AI SDK 适配器也不支持延迟 Responses 工具加载流程。 --- ### 4. Agents as tools -有时，您希望一个智能体*协助*另一个智能体，而不是完全接管对话。此时可使用 `agent.asTool()`： +有时，您希望一个智能体*协助*另一个智能体，而不是完全接管对话。这时可使用 `agent.asTool()`： -如果您仍在 `agent.asTool()` 和 `handoff()` 之间做选择，请对照[智能体](/openai-agents-js/zh/guides/agents#composition-patterns)与[智能体编排](/openai-agents-js/zh/guides/multi-agent)中的模式说明。 +如果您仍在 `agent.asTool()` 和 `handoff()` 之间做选择，请对照查看[智能体](/openai-agents-js/zh/guides/agents#composition-patterns)和[智能体编排](/openai-agents-js/zh/guides/multi-agent)中的模式比较。 在底层，SDK 会： -- 创建一个只包含 `input` 参数的函数工具。 -- 当该工具被调用时，使用该输入运行子智能体。 -- 返回最后一条消息，或由 `customOutputExtractor` 提取的输出。 +- 创建一个只有 `input` 参数的函数工具。 +- 在该工具被调用时，以该输入运行子智能体。 +- 返回最后一条消息，或由 `customOutputExtractor` 提取出的输出。 -当您将智能体作为工具运行时，Agents SDK 会使用默认设置创建一个 runner，并在函数执行过程中用它来运行该智能体。如果您希望提供 `runConfig` 或 `runOptions` 中的任意属性，可以将它们传给 `asTool()` 方法，以自定义 runner 的行为。 +当您将智能体作为工具运行时，Agents SDK 会使用默认设置创建一个 runner，并在函数执行期间通过它运行该智能体。如果您想提供 `runConfig` 或 `runOptions` 的任意属性，可以将它们传给 `asTool()` 方法，以自定义 runner 的行为。 -您还可以通过 `asTool()` 选项在智能体工具上设置 `needsApproval` 和 `isEnabled`，以便集成人工干预流程和按条件控制工具可用性。 +您还可以通过 `asTool()` 选项为智能体工具设置 `needsApproval` 和 `isEnabled`，以集成人工干预流程和条件性工具可用性。 -在 `customOutputExtractor` 内，可使用 `result.agentToolInvocation` 检查当前的 `Agent.asTool()` 调用。在该回调中，结果始终来自 `Agent.asTool()`，因此 `agentToolInvocation` 始终已定义，并暴露 `toolName`、`toolCallId` 和 `toolArguments`。常规应用上下文和 `toolInput` 则使用 `result.runContext` 获取。此元数据仅限当前嵌套调用作用域，不会序列化到 `RunState` 中。 +在 `customOutputExtractor` 内，可使用 `result.agentToolInvocation` 检查当前的 `Agent.asTool()` 调用。在该回调中，结果始终来自 `Agent.asTool()`，因此 `agentToolInvocation` 总是已定义，并暴露 `toolName`、`toolCallId` 和 `toolArguments`。常规应用上下文和 `toolInput` 请通过 `result.runContext` 获取。该元数据仅作用于当前嵌套调用，不会序列化到 `RunState` 中。 - 事件类型与 `RunStreamEvent['type']` 一致：`raw_model_stream_event`、`run_item_stream_event`、`agent_updated_stream_event`。 -- `onStream` 是最简单的“全量捕获”方式，适合内联声明工具时使用（`tools: [agent.asTool({ onStream })]`）。如果您不需要按事件分别路由，使用它即可。 -- `on(eventName, handler)` 允许您选择性订阅（或使用 `'*'`），更适合需要细粒度处理或希望在创建后再附加监听器的场景。 -- 如果您提供了 `onStream` 或任意 `on(...)` 处理器，agent-as-tool 会自动以流式模式运行；否则将保持非流式路径。 -- 处理器会并行调用，因此缓慢的 `onStream` 回调不会阻塞 `on(...)` 处理器（反之亦然）。 -- 当工具通过模型工具调用被触发时，会提供 `toolCallId`；直接 `invoke()` 调用或某些 provider 的特殊行为可能不会提供它。 +- `onStream` 是最简单的“统一捕获”方式，适合内联声明工具时使用（`tools: [agent.asTool({ onStream })]`）。如果您不需要按事件分别路由，可优先使用它。 +- `on(eventName, handler)` 允许您选择性订阅事件（或使用 `'*'`），适合需要更细粒度处理或希望在创建后附加监听器的场景。 +- 只要提供了 `onStream` 或任意 `on(...)` 处理器，agent-as-tool 就会自动以流式模式运行；否则将保持非流式路径。 +- 各处理器会并行调用，因此较慢的 `onStream` 回调不会阻塞 `on(...)` 处理器（反之亦然）。 +- 当工具通过模型工具调用被触发时会提供 `toolCallId`；直接调用 `invoke()` 或某些 provider 的特殊行为可能不会提供它。 --- ### 5. MCP 服务器 -您可以通过 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 服务器暴露工具，并将其附加到智能体。例如，您可以使用 `MCPServerStdio` 来启动并连接到 stdio MCP 服务器： +您可以通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器暴露工具，并将其附加到智能体。例如，您可以使用 `MCPServerStdio` 启动并连接到 stdio MCP 服务器： -完整示例请参见 [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts)。此外，如果您在寻找 MCP 服务器工具集成的完整指南，请参阅[MCP 集成](/openai-agents-js/zh/guides/mcp)。在管理多个服务器（或处理部分失败）时，请使用 `connectMcpServers`，并参考[MCP 集成](/openai-agents-js/zh/guides/mcp#managing-mcp-server-lifecycle)中的生命周期管理建议。 +完整示例请参见 [`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)了解详情。在管理多个服务器（或处理部分失败）时，请使用 `connectMcpServers` 以及[MCP 集成](/openai-agents-js/zh/guides/mcp#managing-mcp-server-lifecycle)中的生命周期指导。 --- ### 6. 实验性：Codex 工具 -`@openai/agents-extensions/experimental/codex` 提供 `codexTool()`，这是一个函数工具，会将模型的工具调用路由到 Codex SDK，使智能体能够自主运行工作区范围内的任务（shell、文件编辑、MCP 工具）。该接口为实验性功能，后续可能发生变化。 +`@openai/agents-extensions/experimental/codex` 提供了 `codexTool()`。这是一个函数工具，可将模型工具调用路由到 Codex SDK，从而让智能体自主运行工作区作用域任务（shell、文件编辑、MCP 工具）。这一接口仍属实验性，未来可能会发生变化。 请先安装依赖： @@ -273,18 +277,18 @@ npm install @openai/agents-extensions @openai/codex-sdk -需要了解的内容： +需要了解的要点： -- 认证：提供 `CODEX_API_KEY`（推荐）或 `OPENAI_API_KEY`，也可传入 `codexOptions.apiKey`。 -- 输入：严格 schema——`inputs` 至少必须包含一个 `{ type: 'text', text }` 或 `{ type: 'local_image', path }`。 -- 安全性：将 `sandboxMode` 与 `workingDirectory` 搭配使用；如果目录不是 Git 仓库，请设置 `skipGitRepoCheck`。 -- 线程：`useRunContextThreadId: true` 会在 `runContext.context` 中读取/存储最新线程 ID，这对于在应用状态中跨轮次复用很有帮助。 -- 线程 ID 优先级：工具调用中的 `threadId`（如果您的 schema 包含它）优先，其次是 run-context 中的线程 ID，最后才是 `codexTool({ threadId })`。 -- 运行上下文键：对于 `name: 'codex'`，默认是 `codexThreadId`；对于 `name: 'engineer'` 这类名称，则为 `codexThreadId_`（规范化后得到 `codex_engineer`）。 +- 认证：提供 `CODEX_API_KEY`（推荐）或 `OPENAI_API_KEY`，也可以传入 `codexOptions.apiKey`。 +- 输入：严格 schema——`inputs` 必须至少包含一个 `{ type: 'text', text }` 或 `{ type: 'local_image', path }`。 +- 安全：将 `sandboxMode` 与 `workingDirectory` 配对使用；如果目录不是 Git 仓库，请设置 `skipGitRepoCheck`。 +- 线程：`useRunContextThreadId: true` 会在 `runContext.context` 中读取/存储最新线程 ID，这对在您的应用状态中跨轮次复用很有帮助。 +- 线程 ID 优先级：工具调用的 `threadId`（如果您的 schema 包含它）优先，其次是运行上下文中的线程 ID，最后是 `codexTool({ threadId })`。 +- 运行上下文键：对于 `name: 'codex'`，默认使用 `codexThreadId`；对于 `name: 'engineer'` 这类名称，则使用 `codexThreadId_`（规范化后为 `codex_engineer`）。 - 可变上下文要求：启用 `useRunContextThreadId` 时，请将可变对象或 `Map` 作为 `run(..., { context })` 传入。 -- 命名：工具名会被规范化到 `codex` 命名空间中（`engineer` 会变为 `codex_engineer`），并且同一智能体中的重复 Codex 工具名会被拒绝。 +- 命名：工具名称会被规范化到 `codex` 命名空间中（`engineer` 会变成 `codex_engineer`），并且同一智能体中不允许出现重复的 Codex 工具名。 - 流式传输：`onStream` 会镜像 Codex 事件（推理、命令执行、MCP 工具调用、文件变更、Web 搜索），便于您记录或追踪进度。 -- 输出：工具结果包含 `response`、`usage` 和 `threadId`，并且 Codex token 用量会记录到 `RunContext` 中。 +- 输出：工具结果包含 `response`、`usage` 和 `threadId`，并且 Codex token 使用量会记录到 `RunContext` 中。 - 结构：`outputSchema` 可以是描述符、JSON schema 对象或 Zod 对象。对于 JSON 对象 schema，`additionalProperties` 必须为 `false`。 运行上下文线程复用示例： @@ -301,24 +305,24 @@ npm install @openai/agents-extensions @openai/codex-sdk ### 工具使用行为 -关于如何控制模型必须在何时、以何种方式使用工具（`modelSettings.toolChoice`、`toolUseBehavior` 等），请参阅[智能体](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 +关于控制模型何时以及如何必须使用工具（`modelSettings.toolChoice`、`toolUseBehavior` 等），请参阅[智能体](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 --- ### 最佳实践 -- **简短且明确的描述**——说明工具*做什么*以及*何时使用它*。 +- **简短、明确的描述**——说明工具*做什么*，以及*何时使用它*。 - **校验输入**——尽可能使用 Zod schema 进行严格 JSON 校验。 - **避免在错误处理器中产生副作用**——`errorFunction` 应返回有帮助的字符串，而不是抛出异常。 -- **一个工具只负责一件事**——小而可组合的工具更有利于模型推理。 +- **每个工具只负责一件事**——小而可组合的工具更有利于模型推理。 --- ## 相关指南 -- [智能体](/openai-agents-js/zh/guides/agents)：定义携带工具的智能体并控制 `toolUseBehavior`。 -- [智能体编排](/openai-agents-js/zh/guides/multi-agent)：帮助决定何时使用 agents as tools，何时使用交接。 +- [智能体](/openai-agents-js/zh/guides/agents)：定义带工具的智能体，并控制 `toolUseBehavior`。 +- [智能体编排](/openai-agents-js/zh/guides/multi-agent)：判断何时应使用 agents as tools，何时应使用交接。 - [运行智能体](/openai-agents-js/zh/guides/running-agents)：了解执行流程、流式传输和对话状态。 -- [模型](/openai-agents-js/zh/guides/models)：了解 OpenAI 托管模型配置和 Responses 传输方式选择。 +- [模型](/openai-agents-js/zh/guides/models)：了解 OpenAI 托管模型配置和 Responses 传输选择。 - [护栏](/openai-agents-js/zh/guides/guardrails)：校验工具输入或输出。 -- 深入阅读 [`tool()`](/openai-agents-js/openai/agents/functions/tool) 及各种托管工具类型的 TypeDoc 参考。 +- 深入阅读 [`tool()`](/openai-agents-js/openai/agents/functions/tool) 及各类托管工具类型的 TypeDoc 参考文档。 diff --git a/docs/src/content/docs/zh/index.mdx b/docs/src/content/docs/zh/index.mdx index 9592a5f1b..d4026f06c 100644 --- a/docs/src/content/docs/zh/index.mdx +++ b/docs/src/content/docs/zh/index.mdx @@ -4,47 +4,50 @@ description: The OpenAI Agents SDK for TypeScript enables you to build agentic A --- import { LinkCard } from '@astrojs/starlight/components'; -import { Code } from '@astrojs/starlight/components'; +import { Code, TabItem, Tabs } from '@astrojs/starlight/components'; import Hero from '../../../components/Hero.astro'; import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; +import helloWorldSandboxExample from '../../../../../examples/docs/toppage/sandboxAgent.ts?raw'; OpenAI Agents SDK - 使用一小组基本组件构建文本和语音智能体。 + 使用一组精简的基本组件构建沙箱、文本和语音智能体。 开始构建 ## 概述 -[TypeScript 版 OpenAI Agents SDK](https://github.com/openai/openai-agents-js) 让您能够通过一个轻量、易用且几乎无需抽象层的包来构建智能体式 AI 应用。它是我们此前智能体实验项目 [Swarm](https://github.com/openai/swarm/tree/main) 的生产就绪升级版，同时也[提供 Python 版本](https://github.com/openai/openai-agents-python)。Agents SDK 只包含一小组基本组件： +[TypeScript 版 OpenAI Agents SDK](https://github.com/openai/openai-agents-js) 让您能够使用一个轻量、易用且几乎没有额外抽象的包来构建智能体 AI 应用。它是在我们之前面向智能体的实验项目 [Swarm](https://github.com/openai/swarm/tree/main) 基础上的生产就绪升级版本，同时也[提供 Python 版本](https://github.com/openai/openai-agents-python)。Agents SDK 只有一组非常精简的基本组件： -- **智能体**，即配备了 instructions 和工具的 LLM -- **Agents as tools / 交接**，允许智能体将特定任务委派给其他智能体 -- **护栏**，用于验证传入智能体的输入 +- **智能体**：配备 instructions 和 tools 的 LLM +- **沙箱智能体**：将智能体与隔离的文件系统工作区、shell 命令、文件编辑、快照以及沙箱会话状态结合起来 +- **Agents as tools / 交接**：允许智能体将特定任务委派给其他智能体 +- **护栏**：可对传入智能体的输入进行验证 -结合 TypeScript，这些基本组件足以表达工具与智能体之间的复杂关系，并让您无需陡峭的学习曲线即可构建真实世界应用。此外，SDK 内置了**追踪**功能，可帮助您可视化和调试智能体流程，还能对其进行评估，甚至为您的应用微调模型。 +结合 TypeScript，这些基本组件足以表达工具与智能体之间的复杂关系，在需要时为智能体提供真实工作区，并让您无需陡峭的学习曲线就能构建真实世界应用。此外，SDK 内置了**追踪**功能，可帮助您可视化和调试智能体流程，还可以对其进行评估，甚至为您的应用微调模型。 ## 使用 Agents SDK 的原因 SDK 有两个核心设计原则： -1. 功能足够丰富，值得使用；但基本组件足够少，因此学习起来很快。 -2. 开箱即用，效果出色；同时您也可以精确自定义每一步的行为。 +1. 功能足够丰富，值得使用；同时基本组件足够少，便于快速上手。 +2. 开箱即用，同时您也可以精确自定义实际发生的行为。 以下是 SDK 的主要特性： -- **智能体循环**：内置智能体循环，可处理工具调用、将结果返回给 LLM，并持续执行直到任务完成。 -- **TypeScript 优先**：使用原生 TypeScript 语言特性来编排和串联智能体，无需学习新的抽象。 -- **Agents as tools / 交接**：一种强大的机制，用于在多个智能体之间协调与委派工作。 +- **智能体循环**：内置智能体循环，负责处理工具调用、将结果发回 LLM，并持续执行直到任务完成。 +- **沙箱执行**：当工作需要工作区时，可使用隔离的文件系统工作区、shell 命令、文件编辑、快照和沙箱会话状态来运行智能体。 +- **TypeScript 优先**：使用原生 TypeScript 语言特性来编排和串联智能体，无需学习新的抽象概念。 +- **Agents as tools / 交接**：一种强大的机制，用于跨多个智能体协调和委派工作。 - **护栏**：与智能体执行并行运行输入验证和安全检查，并在检查未通过时快速失败。 -- **函数工具**：将任何 TypeScript 函数转为工具，并自动生成 schema 以及基于 Zod 的验证。 +- **函数工具**：将任何 TypeScript 函数转换为工具，并自动生成 schema 和基于 Zod 的验证。 - **MCP 服务器工具调用**：内置 MCP 服务器工具集成，使用方式与函数工具相同。 -- **会话**：持久化记忆层，用于在智能体循环中维护工作上下文。 -- **人机协作**：内置机制，可在智能体运行过程中引入人工参与。 -- **追踪**：内置追踪能力，用于工作流的可视化、调试与监控，并支持 OpenAI 的评估、微调和蒸馏工具套件。 +- **会话**：一个持久化记忆层，用于在智能体循环中维护工作上下文。 +- **人工干预**：内置机制，可在智能体多次运行过程中引入人工参与。 +- **追踪**：内置追踪功能，用于工作流的可视化、调试和监控，并支持 OpenAI 的评估、微调和蒸馏工具套件。 - **实时智能体**：构建强大的语音智能体，支持自动打断检测、上下文管理、护栏等功能。 ## 安装 @@ -53,21 +56,38 @@ SDK 有两个核心设计原则： npm install @openai/agents zod ``` -SDK 需要 Zod v4；通过 npm 安装 `zod` 将会获取最新的 v4 版本。 +SDK 需要 Zod v4；通过 npm 安装 `zod` 时会获取最新的 v4 版本。 -## 起点选择 +## 选择起点 大多数首次使用的用户只需要以下入口之一： | 起点 | 适用场景 | 说明 | | --- | --- | --- | -| `@openai/agents` | 您正在构建大多数文本或语音应用。 | 推荐默认选择。它包含 OpenAI provider 配置，并通过 `@openai/agents/realtime` 暴露语音 API。 | -| `@openai/agents-realtime` | 您只需要独立的 Realtime 包。 | 适用于纯浏览器语音应用，或您希望包边界更小的情况。 | -| 底层包（`@openai/agents-core`、`@openai/agents-openai`、`@openai/agents-extensions`） | 您需要更底层的组合、自定义 provider 接线或特定集成。 | 大多数新用户在有明确需求之前都可以忽略这些包。 | +| `@openai/agents` | 您正在构建大多数文本、沙箱或语音应用。 | 推荐默认选择。它包含 OpenAI provider 配置、位于 `@openai/agents/sandbox` 下的沙箱智能体 API，以及位于 `@openai/agents/realtime` 下的语音 API。 | +| `@openai/agents-realtime` | 您只需要独立的 Realtime 包。 | 适用于纯浏览器语音应用，或当您希望包边界更清晰时。 | +| 更底层的包（`@openai/agents-core`、`@openai/agents-openai`、`@openai/agents-extensions`） | 您需要更底层的组合方式、自定义 provider 连接或特定集成。 | 大多数新用户在有明确需求之前都可以忽略这些。 | ## Hello World 示例 - +当智能体需要在文件系统中工作时，请从沙箱智能体开始。如果您的工作流不需要沙箱工作区或沙箱生命周期，也仍然可以使用常规的 `Agent`。 + + + + + + + + + （_如果要运行此示例，请确保已设置 `OPENAI_API_KEY` 环境变量_） @@ -77,30 +97,37 @@ export OPENAI_API_KEY=sk-... ## 从这里开始 -先选择一条路径，把它完整跑通，再回来阅读更深入的指南。 +先选择一条路径，把它完整跑通，然后再回来阅读更深入的指南。 + + ## 路径选择 -当您清楚自己要完成什么工作，但不确定该看哪一页说明时，请使用下表。 +当您知道自己想完成什么工作，但不确定该看哪个页面时，可使用下表。 | 目标 | 从这里开始 | | --- | --- | -| 构建第一个文本智能体并查看一次完整运行 | [快速开始](/openai-agents-js/guides/quickstart) | +| 构建第一个文本智能体，并查看一次完整运行 | [快速开始](/openai-agents-js/guides/quickstart) | | 添加函数工具、托管工具或 Agents as tools | [工具](/openai-agents-js/guides/tools) | -| 在交接与管理者式编排之间做出选择 | [智能体编排](/openai-agents-js/guides/multi-agent) | -| 在多轮之间保留记忆 | [运行智能体](/openai-agents-js/guides/running-agents) 和 [会话](/openai-agents-js/guides/sessions) | +| 为智能体提供隔离的文件系统和 shell 工作区 | [Sandbox clients](/openai-agents-js/guides/sandbox-agents) | +| 在交接和管理者式编排之间做出选择 | [智能体编排](/openai-agents-js/guides/multi-agent) | +| 跨轮次保留记忆 | [运行智能体](/openai-agents-js/guides/running-agents) 和 [会话](/openai-agents-js/guides/sessions) | | 使用 OpenAI 模型、websocket 传输或非 OpenAI provider | [模型](/openai-agents-js/guides/models) | | 查看输出、运行项、中断和恢复状态 | [执行结果](/openai-agents-js/guides/results) | | 构建低延迟语音智能体 | [快速开始](/openai-agents-js/guides/voice-agents/quickstart) |