From d88da1d831b7925abc8d041a05e5fff090e470d9 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 6 Feb 2026 22:49:27 +0000 Subject: [PATCH] Update all translated document pages --- docs/ja/examples.md | 69 ++++++++++---------- docs/ja/tools.md | 128 +++++++++++++++++++------------------ docs/ko/examples.md | 47 +++++++------- docs/ko/tools.md | 131 ++++++++++++++++++++------------------ docs/zh/examples.md | 51 +++++++-------- docs/zh/tools.md | 151 +++++++++++++++++++++++--------------------- 6 files changed, 296 insertions(+), 281 deletions(-) diff --git a/docs/ja/examples.md b/docs/ja/examples.md index f87d5b2a6..c4165006c 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,58 +4,58 @@ search: --- # コード例 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の code examples セクションで、SDK のさまざまなサンプル実装をご覧ください。code examples は、異なるパターンと機能を示す複数のカテゴリーに整理されています。 +[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、SDK のさまざまなサンプル実装をご覧ください。examples は、異なるパターンと機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーの code examples は、次のような一般的な エージェント の設計パターンを示します。 + このカテゴリーのコード例は、次のような一般的なエージェント設計パターンを示します。 - 決定論的ワークフロー - Agents as tools - - 並列 エージェント 実行 - - 条件付きツール利用 - - 入出力 ガードレール - - 判定者としての LLM + - 並列エージェント実行 + - 条件付きツール使用 + - 入出力ガードレール + - 審査員としての LLM - ルーティング - ストリーミング ガードレール - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - これらの code examples は、次のような SDK の基礎機能を紹介します。 + これらのコード例では、次のような SDK の基礎的な機能を紹介します。 - - Hello World の例 (デフォルトモデル、GPT-5、open-weight モデル) - - エージェント のライフサイクル管理 - - 動的な システムプロンプト - - ストリーミング出力 (テキスト、アイテム、関数呼び出し args) + - Hello World コード例 (デフォルトモデル、GPT-5、オープンウェイトモデル) + - エージェントのライフサイクル管理 + - 動的なシステムプロンプト + - ストリーミング 出力 (テキスト、items、関数呼び出し args) - プロンプトテンプレート - - ファイル処理 (ローカル/リモート、画像/PDF) - - 利用状況トラッキング - - 非 strict な出力型 - - 以前の response ID の利用 + - ファイル処理 (ローカルとリモート、画像と PDF) + - 使用状況トラッキング + - 非厳密な出力型 + - 以前の response ID の使用 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** - 航空会社向けのカスタマーサービスシステム例です。 + 航空会社向けのカスタマーサービスシステムの例です。 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 金融データ分析向けの エージェント とツールを用いた structured なリサーチワークフローを示す、金融リサーチ エージェント です。 + 金融データ分析のためのエージェントとツールを用いた structured なリサーチワークフローを示す、金融リサーチエージェントです。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - メッセージフィルタリングを用いた エージェント の ハンドオフ の実用例をご覧ください。 + メッセージフィルタリングを伴うエージェントのハンドオフの実践的なコード例をご覧ください。 - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - hosted MCP (Model context protocol) のコネクターと承認の使い方を示す code examples です。 + hosted MCP (Model context protocol) のコネクターと承認を使用する方法を示すコード例です。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP (Model context protocol) を使って エージェント を構築する方法を学びます。内容は次のとおりです。 + 次を含め、MCP (Model context protocol) を用いてエージェントを構築する方法を学びます。 - - ファイルシステムの例 - - Git の例 - - MCP プロンプトサーバーの例 - - SSE (Server-Sent Events) の例 - - ストリーム可能な HTTP の例 + - Filesystem コード例 + - Git コード例 + - MCP プロンプトサーバーのコード例 + - SSE (Server-Sent Events) コード例 + - ストリーミング可能な HTTP コード例 - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - エージェント 向けのさまざまなメモリ実装の code examples です。内容は次のとおりです。 + 次を含め、エージェント向けのさまざまなメモリ実装のコード例です。 - SQLite セッションストレージ - 高度な SQLite セッションストレージ @@ -65,30 +65,31 @@ search: - OpenAI セッションストレージ - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - カスタムプロバイダーや LiteLLM 連携を含め、SDK で OpenAI 以外のモデルを使う方法を確認します。 + カスタムプロバイダーや LiteLLM 統合を含め、SDK で OpenAI 以外のモデルを使用する方法を確認します。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使ってリアルタイム体験を構築する方法を示す code examples です。内容は次のとおりです。 + 次を含め、SDK を使用してリアルタイムの体験を構築する方法を示すコード例です。 - Web アプリケーション - コマンドラインインターフェース - - Twilio 連携 + - Twilio 統合 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - reasoning content と structured outputs の扱い方を示す code examples です。 + reasoning content と structured outputs を扱う方法を示すコード例です。 - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 複雑なマルチ エージェント のリサーチワークフローを示す、シンプルな ディープリサーチ のクローンです。 + 複雑なマルチエージェントのリサーチワークフローを示す、シンプルな ディープリサーチ クローンです。 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - OpenAI がホストするツール と、次のような実験的な Codex ツールの実装方法を学びます。 + 次を含め、OpenAI がホストするツール と、実験的な Codex ツール群を実装する方法を学びます。 - Web 検索 と、フィルター付き Web 検索 - ファイル検索 - Code Interpreter - コンピュータ操作 - 画像生成 - - 実験的な Codex ツールワークフロー (`examples/tools/codex.py`) + - 実験的な Codex ツールのワークフロー (`examples/tools/codex.py`) + - 実験的な Codex 同一スレッドのワークフロー (`examples/tools/codex_same_thread.py`) - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - ストリーミング音声の例を含め、TTS および STT モデルを使用した音声 エージェント の code examples をご覧ください。 \ No newline at end of file + ストリーミング音声のコード例を含め、TTS と STT モデルを使用した音声エージェントのコード例をご覧ください。 \ No newline at end of file diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 7a3d2e9e9..378218d91 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,13 +4,13 @@ search: --- # ツール -ツールにより、エージェントはアクションを実行できます。たとえば、データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。この SDK は 5 つのカテゴリーをサポートします。 +ツールは、エージェントがアクションを実行できるようにします。たとえば、データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。この SDK は、5 つのカテゴリーをサポートしています。 -- OpenAI がホストするツール: OpenAI サーバー上でモデルと並行して実行されます。 -- ローカル実行環境ツール: お使いの環境で実行されます (コンピュータ操作、シェル、パッチ適用)。 -- Function calling: 任意の Python 関数をツールとしてラップします。 +- OpenAI がホストするツール: OpenAI サーバー上で、モデルと並行して実行されます。 +- ローカルランタイムツール: お使いの環境で実行されます (コンピュータ操作、シェル、パッチ適用)。 +- Function Calling: 任意の Python 関数をツールとしてラップします。 - Agents as tools: 完全なハンドオフなしに、エージェントを呼び出し可能なツールとして公開します。 -- 実験的: Codex ツール: ツール呼び出しから、ワークスペース範囲の Codex タスクを実行します。 +- 実験的: Codex ツール: ツール呼び出しから、ワークスペーススコープの Codex タスクを実行します。 ## ホストされるツール @@ -18,8 +18,8 @@ OpenAI は、[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIRespo - [`WebSearchTool`][agents.tool.WebSearchTool] は、エージェントが Web 検索を行えるようにします。 - [`FileSearchTool`][agents.tool.FileSearchTool] は、OpenAI ベクトルストアから情報を取得できるようにします。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は、LLM がサンドボックス化された環境でコードを実行できるようにします。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] は、リモート MCP サーバーのツールをモデルに公開します。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は、LLM がサンドボックス環境でコードを実行できるようにします。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] は、リモートの MCP サーバーのツールをモデルに公開します。 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] は、プロンプトから画像を生成します。 ```python @@ -41,13 +41,13 @@ async def main(): print(result.final_output) ``` -## ローカル実行環境ツール +## ローカルランタイムツール -ローカル実行環境ツールはお使いの環境で実行され、実装はお客様が提供する必要があります。 +ローカルランタイムツールはお使いの環境で実行され、実装の提供が必要です。 - [`ComputerTool`][agents.tool.ComputerTool]: [`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] インターフェースを実装して、GUI / ブラウザの自動化を有効にします。 - [`ShellTool`][agents.tool.ShellTool] または [`LocalShellTool`][agents.tool.LocalShellTool]: コマンドを実行するためのシェル実行器を提供します。 -- [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor] を実装して、差分をローカルで適用します。 +- [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor] を実装して、差分をローカルに適用します。 ```python from agents import Agent, ApplyPatchTool, ShellTool @@ -91,14 +91,14 @@ agent = Agent( ## 関数ツール -任意の Python 関数をツールとして使用できます。Agents SDK が自動的にツールをセットアップします。 +任意の Python 関数をツールとして利用できます。Agents SDK がツールを自動的にセットアップします。 - ツール名は Python 関数名になります (または名前を指定できます) -- ツールの説明は関数の docstring から取得されます (または説明を指定できます) +- ツールの説明は、関数の docstring から取得されます (または説明を指定できます) - 関数入力のスキーマは、関数の引数から自動的に作成されます - 各入力の説明は、無効化されていない限り、関数の docstring から取得されます -Python の `inspect` モジュールを使って関数シグネチャを抽出し、docstring の解析に [`griffe`](https://mkdocstrings.github.io/griffe/) を、スキーマ作成に `pydantic` を使用します。 +関数シグネチャの抽出には Python の `inspect` モジュールを使用し、docstring の解析には [`griffe`](https://mkdocstrings.github.io/griffe/) を、スキーマ作成には `pydantic` を使用します。 ```python import json @@ -150,9 +150,9 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型を使用でき、関数は同期でも非同期でも構いません。 -2. docstring が存在する場合、説明および引数の説明を取得するために使用されます。 -3. 関数は任意で `context` を受け取れます (第 1 引数である必要があります)。また、ツール名、説明、使用する docstring スタイルなどのオーバーライドも設定できます。 +1. 関数の引数には任意の Python 型を使用でき、関数は同期でも非同期でもかまいません。 +2. docstring が存在する場合は、説明および引数の説明を取得するために使用されます。 +3. 関数は任意で `context` を受け取れます (最初の引数である必要があります)。また、ツール名、説明、使用する docstring スタイルなどの上書きも設定できます。 4. デコレートした関数をツールのリストに渡せます。 ??? note "出力を表示するには展開してください" @@ -227,20 +227,20 @@ for tool in agent.tools: ### 関数ツールからの画像またはファイルの返却 -テキスト出力に加えて、関数ツールの出力として 1 つまたは複数の画像やファイルを返せます。そのためには、次のいずれかを返します。 +関数ツールの出力としてテキストを返すことに加えて、1 つ以上の画像またはファイルを返せます。これを行うには、次のいずれかを返せます。 - 画像: [`ToolOutputImage`][agents.tool.ToolOutputImage] (または TypedDict 版の [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]) - ファイル: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent] (または TypedDict 版の [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]) -- テキスト: 文字列または文字列化可能なオブジェクト、または [`ToolOutputText`][agents.tool.ToolOutputText] (または TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]) +- テキスト: 文字列または文字列化可能なオブジェクト、あるいは [`ToolOutputText`][agents.tool.ToolOutputText] (または TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]) ### カスタム関数ツール -場合によっては、Python 関数をツールとして使いたくないこともあります。その場合、必要に応じて [`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次を提供する必要があります。 +場合によっては、Python 関数をツールとして使いたくないことがあります。その場合は、必要に応じて [`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次の提供が必要です。 - `name` - `description` -- `params_json_schema` (引数の JSON スキーマ) -- `on_invoke_tool` ( [`ToolContext`][agents.tool_context.ToolContext] と、JSON 文字列としての引数を受け取り、ツール出力を文字列として返す必要がある async 関数) +- `params_json_schema` (引数の JSON Schema) +- `on_invoke_tool` ([`ToolContext`][agents.tool_context.ToolContext] と、JSON 文字列としての引数を受け取る async 関数で、ツール出力を文字列として返す必要があります) ```python from typing import Any @@ -273,18 +273,18 @@ tool = FunctionTool( ) ``` -### 引数と docstring の自動解析 +### 引数および docstring の自動解析 -前述のとおり、ツール用のスキーマを抽出するために関数シグネチャを自動的に解析し、ツールおよび個々の引数の説明を抽出するために docstring を解析します。これに関する注意点は次のとおりです。 +前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動的に解析し、ツールおよび個々の引数の説明を抽出するために docstring を解析します。これに関する補足は次のとおりです。 -1. シグネチャの解析は `inspect` モジュールで行います。引数の型を理解するために型アノテーションを使用し、全体スキーマを表す Pydantic モデルを動的に構築します。Python のプリミティブ、Pydantic モデル、TypedDict などを含むほとんどの型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートされる docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式は自動検出を試みますが、これは best-effort であり、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` に設定して docstring 解析を無効化することもできます。 +1. シグネチャの解析は `inspect` モジュールで行います。引数の型を理解するために型アノテーションを使用し、全体スキーマを表す Pydantic モデルを動的に構築します。Python のプリミティブ、Pydantic モデル、TypedDict などを含む多くの型をサポートしています。 +2. docstring の解析には `griffe` を使用します。サポートされる docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式は自動検出を試みますが、これはベストエフォートであり、`function_tool` 呼び出し時に明示的に設定できます。また、`use_docstring_info` を `False` に設定することで docstring 解析を無効化できます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 ## Agents as tools -一部のワークフローでは、制御をハンドオフする代わりに、中央のエージェントが専門エージェントのネットワークをオーケストレーションしたい場合があります。これは、エージェントをツールとしてモデル化することで実現できます。 +一部のワークフローでは、制御をハンドオフする代わりに、中心となるエージェントが専門エージェントのネットワークをオーケストレーションしたい場合があります。これは、エージェントをツールとしてモデル化することで実現できます。 ```python from agents import Agent, Runner @@ -325,7 +325,7 @@ async def main(): ### ツールエージェントのカスタマイズ -`agent.as_tool` 関数は、エージェントをツールに変換しやすくするための便利メソッドです。`max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session`、`needs_approval` などの一般的な実行時オプションをサポートします。また、`parameters`、`input_builder`、`include_input_schema` による構造化入力もサポートします。高度なオーケストレーション (たとえば、条件付きリトライ、フォールバック動作、複数のエージェント呼び出しのチェーン) には、ツール実装内で `Runner.run` を直接使用してください。 +`agent.as_tool` 関数は、エージェントをツールに変換しやすくするための便利メソッドです。`max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session`、`needs_approval` といった一般的なランタイムオプションをサポートします。また、`parameters`、`input_builder`、`include_input_schema` による構造化入力もサポートします。高度なオーケストレーション (たとえば、条件付きのリトライ、フォールバック動作、複数のエージェント呼び出しの連鎖) には、ツール実装内で `Runner.run` を直接使用してください。 ```python @function_tool @@ -344,15 +344,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### ツールエージェントの構造化入力 +### ツールエージェント向けの構造化入力 -デフォルトでは、`Agent.as_tool()` は単一の文字列入力 (`{"input": "..."}`) を想定しますが、`parameters` (Pydantic モデルまたは dataclass 型) を渡すことで構造化スキーマを公開できます。 +デフォルトでは、`Agent.as_tool()` は単一の文字列入力 (`{"input": "..."}`) を想定しますが、`parameters` (Pydantic モデルまたは dataclass 型) を渡すことで、構造化されたスキーマを公開できます。 追加オプション: - `include_input_schema=True` は、生成されるネストされた入力に完全な JSON Schema を含めます。 - `input_builder=...` は、構造化されたツール引数をネストされたエージェント入力へ変換する方法を完全にカスタマイズできます。 -- `RunContextWrapper.tool_input` には、ネストされた実行コンテキスト内で解析済みの構造化ペイロードが含まれます。 +- `RunContextWrapper.tool_input` には、ネストされた実行コンテキスト内でパース済みの構造化ペイロードが含まれます。 ```python from pydantic import BaseModel, Field @@ -372,21 +372,21 @@ translator_tool = translator_agent.as_tool( ) ``` -完全に実行可能な例は `examples/agent_patterns/agents_as_tools_structured.py` を参照してください。 +完全に実行可能な例については `examples/agent_patterns/agents_as_tools_structured.py` を参照してください。 ### ツールエージェントの承認ゲート -`Agent.as_tool(..., needs_approval=...)` は `function_tool` と同じ承認フローを使用します。承認が必要な場合、実行は一時停止し、保留中の項目が `result.interruptions` に表示されます。続いて `result.to_state()` を使用し、`state.approve(...)` または `state.reject(...)` を呼び出した後に再開してください。完全な pause/resume パターンについては、[Human-in-the-loop ガイド](human_in_the_loop.md) を参照してください。 +`Agent.as_tool(..., needs_approval=...)` は `function_tool` と同じ承認フローを使用します。承認が必要な場合、実行は一時停止し、保留中アイテムが `result.interruptions` に表示されます。その後 `result.to_state()` を使用し、`state.approve(...)` または `state.reject(...)` を呼び出してから再開します。完全な一時停止/再開パターンについては [Human-in-the-loop ガイド](human_in_the_loop.md) を参照してください。 ### カスタム出力抽出 -特定のケースでは、中央のエージェントへ返す前に、ツールエージェントの出力を変更したい場合があります。これは、次を行いたい場合に有用です。 +特定のケースでは、中心エージェントに返す前に、ツールエージェントの出力を変更したい場合があります。これは次のような場合に有用です。 - サブエージェントのチャット履歴から特定の情報 (例: JSON ペイロード) を抽出する。 -- エージェントの最終回答を変換または再整形する (例: Markdown をプレーンテキストや CSV に変換する)。 +- エージェントの最終回答を変換または整形し直す (例: Markdown をプレーンテキストや CSV に変換する)。 - 出力を検証する、またはエージェントの応答が欠落している/不正な形式である場合にフォールバック値を提供する。 -これを行うには、`as_tool` メソッドに `custom_output_extractor` 引数を指定します。 +これは、`as_tool` メソッドに `custom_output_extractor` 引数を指定することで行えます。 ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -407,7 +407,7 @@ json_tool = data_agent.as_tool( ### ネストされたエージェント実行のストリーミング -`as_tool` に `on_stream` コールバックを渡すと、ストリーム完了後に最終出力を返しつつ、ネストされたエージェントが発行するストリーミングイベントを監視できます。 +`as_tool` に `on_stream` コールバックを渡すことで、ストリームが完了した後に最終出力を返しつつ、ネストされたエージェントが発行するストリーミングイベントを監視できます。 ```python from agents import AgentToolStreamEvent @@ -425,17 +425,17 @@ billing_agent_tool = billing_agent.as_tool( ) ``` -期待されること: +期待される動作: -- イベントタイプは `StreamEvent["type"]` を反映します: `raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。 -- `on_stream` を指定すると、ネストされたエージェントは自動的にストリーミングモードで実行され、最終出力を返す前にストリームがドレインされます。 -- ハンドラーは同期でも非同期でも構いません。各イベントは到着順に配信されます。 -- `tool_call` は、モデルのツール呼び出しを介してツールが呼び出された場合に存在します。直接呼び出しでは `None` のままの場合があります。 -- 完全に実行可能なサンプルは `examples/agent_patterns/agents_as_tools_streaming.py` を参照してください。 +- イベント種別は `StreamEvent["type"]` を反映します: `raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。 +- `on_stream` を指定すると、ネストされたエージェントは自動的にストリーミングモードで実行され、最終出力を返す前にストリームを最後まで消費します。 +- ハンドラーは同期でも非同期でもよく、各イベントは到着順に配信されます。 +- `tool_call` は、モデルのツール呼び出し経由でツールが起動された場合に存在します。直接呼び出しでは `None` のままの場合があります。 +- 完全に実行可能なサンプルについては `examples/agent_patterns/agents_as_tools_streaming.py` を参照してください。 ### 条件付きツール有効化 -`is_enabled` パラメーターを使用して、実行時にエージェントツールを条件付きで有効化または無効化できます。これにより、コンテキスト、ユーザーの好み、または実行時条件に基づいて、LLM が利用可能なツールを動的にフィルタリングできます。 +`is_enabled` パラメーターを使用して、実行時にエージェントツールを条件付きで有効/無効にできます。これにより、コンテキスト、ユーザー設定、またはランタイム条件に基づいて、LLM が利用できるツールを動的にフィルタリングできます。 ```python import asyncio @@ -493,19 +493,19 @@ asyncio.run(main()) `is_enabled` パラメーターが受け付けるもの: - **ブール値**: `True` (常に有効) または `False` (常に無効) -- **呼び出し可能関数**: `(context, agent)` を受け取り、ブール値を返す関数 -- **Async 関数**: 複雑な条件ロジックのための Async 関数 +- **呼び出し可能関数**: `(context, agent)` を受け取りブール値を返す関数 +- **非同期関数**: 複雑な条件ロジックのための async 関数 -無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に便利です。 +無効化されたツールは、実行時に LLM から完全に隠されるため、次の用途に有用です。 - ユーザー権限に基づく機能ゲーティング -- 環境固有のツール可用性 (dev vs prod) +- 環境別のツール可用性 (dev vs prod) - 異なるツール構成の A/B テスト - 実行時状態に基づく動的なツールフィルタリング ## 実験的: Codex ツール -`codex_tool` は Codex CLI をラップし、ツール呼び出し中にエージェントがワークスペース範囲のタスク (シェル、ファイル編集、MCP ツール) を実行できるようにします。このサーフェスは実験的であり、変更される可能性があります。 +`codex_tool` は Codex CLI をラップし、エージェントがツール呼び出し中にワークスペーススコープのタスク (シェル、ファイル編集、MCP ツール) を実行できるようにします。このインターフェースは実験的であり、変更される可能性があります。デフォルトではツール名は `codex` です。カスタム名を設定する場合、`codex` であるか、`codex_` で始まる必要があります。エージェントが複数の Codex ツールを含む場合、それぞれは (Codex 以外のツールを含めて) 一意の名前を使用する必要があります。 ```python from agents import Agent @@ -536,28 +536,30 @@ agent = Agent( 知っておくべきこと: -- 認証: `CODEX_API_KEY` (推奨) または `OPENAI_API_KEY` を設定するか、`codex_options={"api_key": "..."}` を渡します。 -- 実行時: `codex_options.base_url` は CLI の base URL を上書きします。 -- バイナリ解決: `codex_options.codex_path_override` (または `CODEX_PATH`) を設定して CLI パスを固定します。そうでない場合、SDK はまず `PATH` から `codex` を解決し、次に同梱の vendor バイナリへフォールバックします。 +- 認証: `CODEX_API_KEY` (推奨) または `OPENAI_API_KEY` を設定するか、`codex_options={"api_key": "..."}` を渡してください。 +- ランタイム: `codex_options.base_url` は CLI の base URL を上書きします。 +- バイナリ解決: `codex_options.codex_path_override` (または `CODEX_PATH`) を設定して CLI パスを固定します。設定しない場合、SDK は `PATH` から `codex` を解決し、それでも見つからなければ同梱の vendor バイナリへフォールバックします。 - 環境: `codex_options.env` はサブプロセス環境を完全に制御します。これが提供されると、サブプロセスは `os.environ` を継承しません。 -- ストリーム制限: `codex_options.codex_subprocess_stream_limit_bytes` (または `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`) は stdout/stderr のリーダー制限を制御します。有効範囲は `65536` から `67108864`、デフォルトは `8388608` です。 -- 入力: ツール呼び出しには、`inputs` に少なくとも 1 件の `{ "type": "text", "text": ... }` または `{ "type": "local_image", "path": ... }` を含める必要があります。 -- スレッドのデフォルト: `model_reasoning_effort`、`web_search_mode` (レガシーの `web_search_enabled` より推奨)、`approval_policy`、`additional_directories` について `default_thread_options` を構成します。 -- ターンのデフォルト: `idle_timeout_seconds` とキャンセル用の `signal` について `default_turn_options` を構成します。 -- 安全性: `sandbox_mode` を `working_directory` と組み合わせます。Git リポジトリ外では `skip_git_repo_check=True` を設定します。 -- 動作: `persist_session=True` は単一の Codex スレッドを再利用し、その `thread_id` を返します。 -- ストリーミング: `on_stream` は Codex イベント (推論、コマンド実行、MCP ツール呼び出し、ファイル変更、Web 検索) を受け取ります。 +- ストリーム制限: `codex_options.codex_subprocess_stream_limit_bytes` (または `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`) は stdout/stderr リーダーの制限を制御します。有効範囲は `65536` から `67108864` で、デフォルトは `8388608` です。 +- 入力: ツール呼び出しは、`inputs` に少なくとも 1 つの `{ "type": "text", "text": ... }` または `{ "type": "local_image", "path": ... }` を含む必要があります。 +- スレッドのデフォルト: `default_thread_options` で `model_reasoning_effort`、`web_search_mode` (レガシーの `web_search_enabled` より推奨)、`approval_policy`、`additional_directories` を構成します。 +- ターンのデフォルト: `default_turn_options` で `idle_timeout_seconds` とキャンセル用 `signal` を構成します。 +- 安全性: `sandbox_mode` は `working_directory` と組み合わせてください。Git リポジトリ外では `skip_git_repo_check=True` を設定してください。 +- 実行コンテキストのスレッド永続化: `use_run_context_thread_id=True` は、同じコンテキストを共有する実行間で、実行コンテキスト内の `thread_id` を保存して再利用します。これは、変更可能な実行コンテキスト (例: `dict` や書き込み可能なオブジェクトフィールド) を必要とします。 +- 実行コンテキストのキーのデフォルト: 保存されるキーは、`name="codex"` の場合は `codex_thread_id`、`name="codex_"` の場合は `codex_thread_id_` がデフォルトです。上書きするには `run_context_thread_id_key` を設定してください。 +- スレッド ID の優先順位: 呼び出しごとの `thread_id` 入力が最優先で、次に (有効な場合) 実行コンテキストの `thread_id`、次に設定された `thread_id` オプションが続きます。 +- ストリーミング: `on_stream` は、スレッド/ターンのライフサイクルイベントと、アイテムイベント (`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list`、および `error` のアイテム更新) を受け取ります。 - 出力: 結果には `response`、`usage`、`thread_id` が含まれます。usage は `RunContextWrapper.usage` に追加されます。 - 構造: `output_schema` は、型付き出力が必要な場合に、構造化された Codex 応答を強制します。 -- 完全に実行可能なサンプルは `examples/tools/codex.py` を参照してください。 +- 完全に実行可能なサンプルについては `examples/tools/codex.py` と `examples/tools/codex_same_thread.py` を参照してください。 ## 関数ツールにおけるエラー処理 -`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へエラー応答を提供する関数です。 +`@function_tool` で関数ツールを作成する際に `failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に、LLM へ返すエラー応答を提供する関数です。 -- デフォルト (つまり何も渡さない場合) では、エラーが発生したことを LLM に伝える `default_tool_error_function` が実行されます。 -- 独自のエラー関数を渡すと、代わりにそれが実行され、その応答が LLM に送信されます。 -- 明示的に `None` を渡すと、ツール呼び出しエラーは再送出され、お客様側で処理できます。たとえば、モデルが不正な JSON を生成した場合の `ModelBehaviorError`、コードがクラッシュした場合の `UserError` などです。 +- デフォルトでは (つまり何も渡さない場合)、`default_tool_error_function` が実行され、エラーが発生したことを LLM に伝えます。 +- 独自のエラー関数を渡すと、代わりにそれが実行され、応答が LLM に送信されます。 +- 明示的に `None` を渡した場合、ツール呼び出しエラーは再送出され、ユーザー側で処理できます。これは、モデルが無効な JSON を生成した場合の `ModelBehaviorError` や、コードがクラッシュした場合の `UserError` などになりえます。 ```python from agents import function_tool, RunContextWrapper diff --git a/docs/ko/examples.md b/docs/ko/examples.md index 13598afec..59d3a4df2 100644 --- a/docs/ko/examples.md +++ b/docs/ko/examples.md @@ -4,58 +4,58 @@ search: --- # 예제 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 예제 섹션에서 SDK의 다양한 샘플 구현을 확인하세요. 예제는 서로 다른 패턴과 기능을 보여주는 여러 카테고리로 구성되어 있습니다. +[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 SDK의 다양한 샘플 구현을 확인해 보세요. 예제는 여러 카테고리로 구성되어 있으며, 서로 다른 패턴과 기능을 보여 줍니다. ## 카테고리 - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - 이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여줍니다 + 이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여 줍니다 - 결정적 워크플로 - Agents as tools - 병렬 에이전트 실행 - 조건부 도구 사용 - - 입출력 가드레일 + - 입력/출력 가드레일 - 심판으로서의 LLM - 라우팅 - 스트리밍 가드레일 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - 이 예제는 다음과 같은 SDK의 기초 기능을 보여줍니다 + 이 예제는 다음과 같은 SDK의 기본 기능을 보여 줍니다 - - Hello World 예제 (기본 모델, GPT-5, 오픈 웨이트 모델) + - Hello World 예제(기본 모델, GPT-5, 오픈 웨이트 모델) - 에이전트 라이프사이클 관리 - 동적 시스템 프롬프트 - - 스트리밍 출력 (텍스트, 항목, 함수 호출 인자) + - 스트리밍 출력(텍스트, 항목, 함수 호출 인자) - 프롬프트 템플릿 - - 파일 처리 (로컬 및 원격, 이미지 및 PDF) + - 파일 처리(로컬 및 원격, 이미지 및 PDF) - 사용량 추적 - - 엄격하지 않은 출력 타입 + - 비엄격 출력 타입 - 이전 응답 ID 사용 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** - 항공사를 위한 예시 고객 서비스 시스템입니다. + 항공사를 위한 고객 서비스 시스템 예제입니다 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 금융 데이터 분석을 위한 에이전트와 도구를 사용해 구조화된 리서치 워크플로를 보여주는 금융 리서치 에이전트입니다. + 금융 데이터 분석을 위한 에이전트와 도구로 구조화된 리서치 워크플로를 보여 주는 금융 리서치 에이전트입니다 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - 메시지 필터링을 활용한 에이전트 핸드오프의 실용적인 예제를 확인하세요. + 메시지 필터링과 함께 에이전트 핸드오프의 실용적인 예제를 확인하세요 - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - 호스티드 MCP (Model context protocol) 커넥터와 승인 기능을 사용하는 방법을 보여주는 예제입니다. + 호스티드 MCP (Model context protocol) 커넥터와 승인 기능을 사용하는 방법을 보여 주는 예제입니다 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - 다음을 포함하여 MCP (Model context protocol)로 에이전트를 구축하는 방법을 알아보세요 + 다음을 포함해 MCP (Model context protocol)로 에이전트를 구축하는 방법을 알아보세요 - - 파일시스템 예제 + - 파일 시스템 예제 - Git 예제 - MCP 프롬프트 서버 예제 - SSE (Server-Sent Events) 예제 - 스트리밍 가능한 HTTP 예제 - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - 다음을 포함하여 에이전트를 위한 다양한 메모리 구현 예제입니다 + 다음을 포함해 에이전트용 다양한 메모리 구현 예제입니다 - SQLite 세션 스토리지 - 고급 SQLite 세션 스토리지 @@ -65,30 +65,31 @@ search: - OpenAI 세션 스토리지 - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 커스텀 프로바이더와 LiteLLM 통합을 포함하여 SDK에서 OpenAI가 아닌 모델을 사용하는 방법을 살펴보세요. + 커스텀 프로바이더와 LiteLLM 통합을 포함해 SDK에서 비 OpenAI 모델을 사용하는 방법을 살펴보세요 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - 다음을 포함하여 SDK를 사용해 실시간 경험을 구축하는 방법을 보여주는 예제입니다 + 다음을 포함해 SDK로 실시간 경험을 구축하는 방법을 보여 주는 예제입니다 - 웹 애플리케이션 - 커맨드라인 인터페이스 - Twilio 통합 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - 추론 콘텐츠와 structured outputs를 다루는 방법을 보여주는 예제입니다. + reasoning content 및 structured outputs를 다루는 방법을 보여 주는 예제입니다 - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 복잡한 멀티 에이전트 리서치 워크플로를 보여주는 간단한 딥 리서치 클론입니다. + 복잡한 멀티 에이전트 리서치 워크플로를 보여 주는 간단한 딥 리서치 클론입니다 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - 다음과 같은 OpenAI 호스트하는 도구 및 실험적 Codex 툴링을 구현하는 방법을 알아보세요 + 다음과 같은 OpenAI 호스트하는 도구 및 실험적 Codex 도구 워크플로를 구현하는 방법을 알아보세요 - - 웹 검색 및 필터가 있는 웹 검색 + - 웹 검색 및 필터를 적용한 웹 검색 - 파일 검색 - Code Interpreter - 컴퓨터 사용 - 이미지 생성 - - 실험적 Codex 도구 워크플로 (`examples/tools/codex.py`) + - 실험적 Codex 도구 워크플로(`examples/tools/codex.py`) + - 실험적 Codex 동일 스레드 워크플로(`examples/tools/codex_same_thread.py`) - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 스트리밍 음성 예제를 포함하여 TTS 및 STT 모델을 사용하는 음성 에이전트 예제를 확인하세요. \ No newline at end of file + 스트리밍 음성 예제를 포함해 TTS 및 STT 모델을 사용하는 보이스 에이전트 예제를 확인하세요 \ No newline at end of file diff --git a/docs/ko/tools.md b/docs/ko/tools.md index 7af119b21..abcd9810d 100644 --- a/docs/ko/tools.md +++ b/docs/ko/tools.md @@ -6,18 +6,18 @@ search: 도구는 에이전트가 행동을 취할 수 있게 합니다. 예를 들어 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용까지 가능합니다. SDK 는 다섯 가지 카테고리를 지원합니다: -- OpenAI 호스티드 툴: OpenAI 서버에서 모델과 함께 실행됩니다 -- 로컬 런타임 도구: 사용자의 환경에서 실행됩니다 (컴퓨터 사용, shell, apply patch) -- 함수 호출: 어떤 Python 함수든 도구로 래핑합니다 -- Agents as tools: 전체 핸드오프 없이 에이전트를 호출 가능한 도구로 노출합니다 +- OpenAI 호스트하는 도구: OpenAI 서버에서 모델과 함께 실행됩니다 +- 로컬 런타임 도구: 사용자 환경에서 실행됩니다(컴퓨터 사용, 셸, 패치 적용) +- 함수 호출: 어떤 Python 함수든 도구로 감쌉니다 +- Agents as tools: 완전한 핸드오프 없이 에이전트를 호출 가능한 도구로 노출합니다 - 실험적: Codex 도구: 도구 호출로 워크스페이스 범위의 Codex 작업을 실행합니다 ## 호스티드 툴 -OpenAI 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 을 사용할 때 몇 가지 내장 도구를 제공합니다: +OpenAI 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 사용 시 몇 가지 내장 도구를 제공합니다: - [`WebSearchTool`][agents.tool.WebSearchTool] 은 에이전트가 웹을 검색할 수 있게 합니다 -- [`FileSearchTool`][agents.tool.FileSearchTool] 은 OpenAI Vector Stores 에서 정보를 가져올 수 있게 합니다 +- [`FileSearchTool`][agents.tool.FileSearchTool] 은 OpenAI 벡터 스토어에서 정보를 검색할 수 있게 합니다 - [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] 은 LLM 이 샌드박스 환경에서 코드를 실행할 수 있게 합니다 - [`HostedMCPTool`][agents.tool.HostedMCPTool] 은 원격 MCP 서버의 도구를 모델에 노출합니다 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] 은 프롬프트로부터 이미지를 생성합니다 @@ -43,10 +43,10 @@ async def main(): ## 로컬 런타임 도구 -로컬 런타임 도구는 사용자의 환경에서 실행되며, 구현을 직접 제공해야 합니다: +로컬 런타임 도구는 사용자 환경에서 실행되며, 사용자가 구현을 제공해야 합니다: - [`ComputerTool`][agents.tool.ComputerTool]: GUI/브라우저 자동화를 활성화하려면 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 인터페이스를 구현합니다 -- [`ShellTool`][agents.tool.ShellTool] 또는 [`LocalShellTool`][agents.tool.LocalShellTool]: 명령을 실행할 수 있도록 셸 실행기를 제공합니다 +- [`ShellTool`][agents.tool.ShellTool] 또는 [`LocalShellTool`][agents.tool.LocalShellTool]: 명령을 실행할 셸 실행기를 제공합니다 - [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: 로컬에서 diff 를 적용하려면 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor] 를 구현합니다 ```python @@ -93,12 +93,12 @@ agent = Agent( 어떤 Python 함수든 도구로 사용할 수 있습니다. Agents SDK 가 도구를 자동으로 설정합니다: -- 도구의 이름은 Python 함수의 이름이 됩니다 (또는 이름을 제공할 수 있습니다) -- 도구 설명은 함수의 docstring 에서 가져옵니다 (또는 설명을 제공할 수 있습니다) -- 함수 입력에 대한 스키마는 함수의 인자에서 자동으로 생성됩니다 +- 도구 이름은 Python 함수 이름이 됩니다(또는 이름을 제공할 수 있습니다) +- 도구 설명은 함수의 docstring 에서 가져옵니다(또는 설명을 제공할 수 있습니다) +- 함수 입력의 스키마는 함수 인자에서 자동으로 생성됩니다 - 각 입력에 대한 설명은 비활성화하지 않는 한 함수의 docstring 에서 가져옵니다 -함수 시그니처를 추출하기 위해 Python 의 `inspect` 모듈을 사용하고, docstring 파싱을 위해 [`griffe`](https://mkdocstrings.github.io/griffe/) 를, 스키마 생성을 위해 `pydantic` 을 사용합니다. +Python 의 `inspect` 모듈을 사용해 함수 시그니처를 추출하고, [`griffe`](https://mkdocstrings.github.io/griffe/) 로 docstring 을 파싱하며, `pydantic` 으로 스키마를 생성합니다. ```python import json @@ -150,12 +150,12 @@ for tool in agent.tools: ``` -1. 함수 인자로 어떤 Python 타입이든 사용할 수 있으며, 함수는 sync 또는 async 일 수 있습니다 -2. docstring 이 있으면 설명과 인자 설명을 캡처하는 데 사용됩니다 -3. 함수는 선택적으로 `context` 를 받을 수 있습니다 (`context` 는 첫 번째 인자여야 합니다). 또한 도구의 이름, 설명, 사용할 docstring 스타일 등과 같은 오버라이드를 설정할 수 있습니다 -4. 데코레이트된 함수를 도구 목록에 전달할 수 있습니다 +1. 함수 인자로 어떤 Python 타입이든 사용할 수 있으며, 함수는 동기 또는 비동기일 수 있습니다 +2. docstring 이 있으면, 설명과 인자 설명을 캡처하는 데 사용됩니다 +3. 함수는 선택적으로 `context` 를 받을 수 있습니다(첫 번째 인자여야 함). 또한 도구 이름, 설명, 사용할 docstring 스타일 등 오버라이드도 설정할 수 있습니다 +4. 데코레이트된 함수를 tools 리스트에 전달할 수 있습니다 -??? note "출력 보기" +??? note "출력 보기 위해 펼치기" ``` fetch_weather @@ -227,7 +227,7 @@ for tool in agent.tools: ### 함수 도구에서 이미지 또는 파일 반환 -텍스트 출력 외에도, 함수 도구의 출력으로 하나 이상의 이미지 또는 파일을 반환할 수 있습니다. 이를 위해 다음 중 아무 것이나 반환할 수 있습니다: +텍스트 출력뿐 아니라, 함수 도구의 출력으로 하나 또는 여러 개의 이미지나 파일을 반환할 수 있습니다. 이를 위해 다음 중 아무 것이나 반환할 수 있습니다: - 이미지: [`ToolOutputImage`][agents.tool.ToolOutputImage] (또는 TypedDict 버전인 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]) - 파일: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent] (또는 TypedDict 버전인 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]) @@ -235,12 +235,12 @@ for tool in agent.tools: ### 커스텀 함수 도구 -때로는 Python 함수를 도구로 쓰고 싶지 않을 수 있습니다. 원한다면 [`FunctionTool`][agents.tool.FunctionTool] 을 직접 만들 수 있습니다. 다음을 제공해야 합니다: +때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 원한다면 [`FunctionTool`][agents.tool.FunctionTool] 을 직접 만들 수 있습니다. 다음을 제공해야 합니다: - `name` - `description` -- 인자에 대한 JSON 스키마인 `params_json_schema` -- [`ToolContext`][agents.tool_context.ToolContext] 와 JSON 문자열로 된 인자를 받는 async 함수인 `on_invoke_tool` (도구 출력을 문자열로 반환해야 합니다) +- `params_json_schema`: 인자에 대한 JSON 스키마 +- `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext] 와 인자를 JSON 문자열로 받아, 도구 출력을 문자열로 반환해야 하는 비동기 함수 ```python from typing import Any @@ -275,16 +275,16 @@ tool = FunctionTool( ### 인자 및 docstring 자동 파싱 -앞서 언급했듯이, 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구 및 개별 인자에 대한 설명을 추출하기 위해 docstring 을 파싱합니다. 몇 가지 참고 사항은 다음과 같습니다: +앞서 언급했듯이, 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구 및 개별 인자에 대한 설명을 추출하기 위해 docstring 을 파싱합니다. 이에 대한 참고 사항은 다음과 같습니다: -1. 시그니처 파싱은 `inspect` 모듈로 수행됩니다. 타입 애너테이션을 사용해 인자 타입을 이해하고, 전체 스키마를 나타내는 Pydantic 모델을 동적으로 빌드합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다 -2. docstring 파싱에는 `griffe` 를 사용합니다. 지원하는 docstring 형식은 `google`, `sphinx`, `numpy` 입니다. docstring 형식을 자동 감지하려고 시도하지만 이는 best-effort 이며, `function_tool` 호출 시 명시적으로 설정할 수 있습니다. `use_docstring_info` 를 `False` 로 설정해 docstring 파싱을 비활성화할 수도 있습니다 +1. 시그니처 파싱은 `inspect` 모듈로 수행됩니다. 인자 타입을 이해하기 위해 타입 어노테이션을 사용하고, 전체 스키마를 나타내는 Pydantic 모델을 동적으로 구성합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다 +2. docstring 파싱에는 `griffe` 를 사용합니다. 지원되는 docstring 형식은 `google`, `sphinx`, `numpy` 입니다. docstring 형식을 자동으로 감지하려고 시도하지만 최선의 노력(best-effort)이며, `function_tool` 호출 시 명시적으로 설정할 수 있습니다. 또한 `use_docstring_info` 를 `False` 로 설정해 docstring 파싱을 비활성화할 수 있습니다 스키마 추출 코드는 [`agents.function_schema`][] 에 있습니다. ## Agents as tools -일부 워크플로에서는 제어권을 핸드오프하기보다는, 중앙 에이전트가 전문화된 에이전트 네트워크를 멀티 에이전트 오케스트레이션 하기를 원할 수 있습니다. 이를 위해 에이전트를 도구로 모델링할 수 있습니다. +일부 워크플로에서는 제어권을 핸드오프하기보다, 중앙 에이전트가 전문화된 에이전트 네트워크를 멀티 에이전트 오케스트레이션하도록 만들고 싶을 수 있습니다. 이를 위해 에이전트를 도구로 모델링할 수 있습니다. ```python from agents import Agent, Runner @@ -325,7 +325,7 @@ async def main(): ### 도구-에이전트 커스터마이징 -`agent.as_tool` 함수는 에이전트를 도구로 쉽게 전환할 수 있도록 하는 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval` 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema` 를 통한 구조화된 입력도 지원합니다. 고급 오케스트레이션(예: 조건부 재시도, 폴백 동작, 여러 에이전트 호출 체이닝)의 경우, 도구 구현에서 `Runner.run` 을 직접 사용하세요: +`agent.as_tool` 함수는 에이전트를 도구로 쉽게 바꾸기 위한 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval` 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema` 로 구조화된 입력도 지원합니다. 고급 오케스트레이션(예: 조건부 재시도, 폴백 동작, 여러 에이전트 호출 체이닝)의 경우, 도구 구현에서 `Runner.run` 을 직접 사용하세요: ```python @function_tool @@ -346,13 +346,13 @@ async def run_my_agent() -> str: ### 도구-에이전트를 위한 구조화된 입력 -기본적으로 `Agent.as_tool()` 은 단일 문자열 입력(`{"input": "..."}`)을 기대하지만, `parameters`(Pydantic 모델 또는 dataclass 타입)를 전달하여 구조화된 스키마를 노출할 수 있습니다. +기본적으로 `Agent.as_tool()` 은 단일 문자열 입력(`{"input": "..."}`)을 기대하지만, `parameters`(Pydantic 모델 또는 dataclass 타입)를 전달해 구조화된 스키마를 노출할 수 있습니다. 추가 옵션: - `include_input_schema=True` 는 생성된 중첩 입력에 전체 JSON Schema 를 포함합니다 - `input_builder=...` 는 구조화된 도구 인자가 중첩된 에이전트 입력이 되는 방식을 완전히 커스터마이징할 수 있게 합니다 -- `RunContextWrapper.tool_input` 에는 중첩된 실행 컨텍스트 내부에서 파싱된 구조화된 페이로드가 들어 있습니다 +- `RunContextWrapper.tool_input` 에는 중첩 run 컨텍스트 내부에서 파싱된 구조화 페이로드가 들어 있습니다 ```python from pydantic import BaseModel, Field @@ -372,19 +372,19 @@ translator_tool = translator_agent.as_tool( ) ``` -완전한 실행 가능 예제는 `examples/agent_patterns/agents_as_tools_structured.py` 를 참고하세요. +완전히 실행 가능한 예시는 `examples/agent_patterns/agents_as_tools_structured.py` 를 참고하세요. -### 도구-에이전트에 대한 승인 게이트 +### 도구-에이전트를 위한 승인 게이트 -`Agent.as_tool(..., needs_approval=...)` 는 `function_tool` 과 동일한 승인 플로를 사용합니다. 승인이 필요하면 실행이 일시 중지되고 보류 항목이 `result.interruptions` 에 나타납니다. 이후 `result.to_state()` 를 사용한 다음 `state.approve(...)` 또는 `state.reject(...)` 를 호출한 뒤 재개하세요. 전체 일시 중지/재개 패턴은 [Human-in-the-loop 가이드](human_in_the_loop.md)를 참고하세요. +`Agent.as_tool(..., needs_approval=...)` 는 `function_tool` 과 동일한 승인 플로우를 사용합니다. 승인이 필요하면 run 이 일시정지되고 보류 항목이 `result.interruptions` 에 나타납니다. 이후 `result.to_state()` 를 사용하고, `state.approve(...)` 또는 `state.reject(...)` 호출 후 재개하세요. 전체 일시정지/재개 패턴은 [Human-in-the-loop guide](human_in_the_loop.md) 를 참고하세요. ### 커스텀 출력 추출 -특정한 경우에는 도구-에이전트의 출력을 중앙 에이전트에 반환하기 전에 수정하고 싶을 수 있습니다. 이는 다음을 원할 때 유용할 수 있습니다: +일부 경우에는 도구-에이전트의 출력을 중앙 에이전트에 반환하기 전에 수정하고 싶을 수 있습니다. 이는 다음과 같은 경우에 유용할 수 있습니다: -- 서브 에이전트의 채팅 히스토리에서 특정 정보(예: JSON 페이로드)를 추출 +- 하위 에이전트의 채팅 히스토리에서 특정 정보(예: JSON 페이로드)를 추출 - 에이전트의 최종 답변을 변환 또는 재포맷(예: Markdown 을 일반 텍스트 또는 CSV 로 변환) -- 출력 유효성 검사 또는 에이전트 응답이 누락되었거나 형식이 잘못된 경우 폴백 값 제공 +- 출력 유효성 검증 또는 응답이 누락되었거나 형식이 잘못된 경우 폴백 값 제공 이를 위해 `as_tool` 메서드에 `custom_output_extractor` 인자를 제공할 수 있습니다: @@ -405,9 +405,9 @@ json_tool = data_agent.as_tool( ) ``` -### 중첩된 에이전트 실행 스트리밍 +### 중첩 에이전트 run 스트리밍 -`as_tool` 에 `on_stream` 콜백을 전달하면, 스트림이 완료된 뒤 최종 출력을 반환하면서도 중첩된 에이전트가 방출하는 스트리밍 이벤트를 수신할 수 있습니다. +`as_tool` 에 `on_stream` 콜백을 전달하면, 스트림이 완료된 뒤 최종 출력을 반환하면서도 중첩 에이전트가 내보내는 스트리밍 이벤트를 수신할 수 있습니다. ```python from agents import AgentToolStreamEvent @@ -425,17 +425,17 @@ billing_agent_tool = billing_agent.as_tool( ) ``` -기대할 수 있는 내용: +예상 동작: -- 이벤트 타입은 `StreamEvent["type"]` 와 동일합니다: `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event` -- `on_stream` 을 제공하면 중첩된 에이전트가 자동으로 스트리밍 모드로 실행되고, 최종 출력을 반환하기 전에 스트림을 모두 소비합니다 +- 이벤트 타입은 `StreamEvent["type"]` 를 미러링합니다: `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event` +- `on_stream` 을 제공하면 중첩 에이전트가 자동으로 스트리밍 모드로 실행되며, 최종 출력을 반환하기 전에 스트림을 모두 소비합니다 - 핸들러는 동기 또는 비동기일 수 있으며, 각 이벤트는 도착하는 순서대로 전달됩니다 -- 도구가 모델의 도구 호출을 통해 호출되면 `tool_call` 이 존재하며, 직접 호출은 `None` 일 수 있습니다 -- 완전한 실행 가능 샘플은 `examples/agent_patterns/agents_as_tools_streaming.py` 를 참고하세요 +- 도구가 모델 도구 호출을 통해 호출되면 `tool_call` 이 존재하며, 직접 호출은 `None` 으로 남을 수 있습니다 +- 완전히 실행 가능한 샘플은 `examples/agent_patterns/agents_as_tools_streaming.py` 를 참고하세요 ### 조건부 도구 활성화 -`is_enabled` 매개변수를 사용해 런타임에 에이전트 도구를 조건부로 활성화 또는 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호, 런타임 조건에 따라 LLM 이 사용할 수 있는 도구를 동적으로 필터링할 수 있습니다. +`is_enabled` 매개변수를 사용해 런타임에 에이전트 도구를 조건부로 활성화 또는 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호, 또는 런타임 조건에 따라 LLM 에 사용 가능한 도구를 동적으로 필터링할 수 있습니다. ```python import asyncio @@ -492,20 +492,23 @@ asyncio.run(main()) `is_enabled` 매개변수는 다음을 받을 수 있습니다: -- **불리언 값**: `True` (항상 활성화) 또는 `False` (항상 비활성화) +- **불리언 값**: `True` (항상 활성) 또는 `False` (항상 비활성) - **호출 가능한 함수**: `(context, agent)` 를 받아 불리언을 반환하는 함수 -- **비동기 함수**: 복잡한 조건 로직을 위한 async 함수 +- **비동기 함수**: 복잡한 조건 로직을 위한 비동기 함수 -비활성화된 도구는 런타임에서 LLM 에게 완전히 숨겨지므로, 다음에 유용합니다: +비활성화된 도구는 런타임에서 LLM 에 완전히 숨겨지므로, 다음에 유용합니다: -- 사용자 권한 기반 기능 게이팅 -- 환경별 도구 가용성 (dev vs prod) +- 사용자 권한에 따른 기능 게이팅 +- 환경별 도구 가용성(dev vs prod) - 서로 다른 도구 구성에 대한 A/B 테스트 - 런타임 상태에 따른 동적 도구 필터링 ## 실험적: Codex 도구 -`codex_tool` 은 Codex CLI 를 래핑하여, 에이전트가 도구 호출 중에 워크스페이스 범위의 작업(shell, 파일 편집, MCP 도구)을 실행할 수 있게 합니다. 이 표면은 실험적이며 변경될 수 있습니다. +`codex_tool` 은 Codex CLI 를 래핑하여, 에이전트가 도구 호출 중에 워크스페이스 범위 작업(셸, 파일 편집, MCP 도구)을 실행할 수 있게 합니다. +이 인터페이스는 실험적이며 변경될 수 있습니다. +기본적으로 도구 이름은 `codex` 입니다. 커스텀 이름을 설정한다면 `codex` 이거나 `codex_` 로 시작해야 합니다. +에이전트에 여러 Codex 도구가 포함될 때는, 각각이 고유한 이름을 사용해야 합니다(Codex 도구끼리뿐 아니라 비 Codex 도구와도 포함하여). ```python from agents import Agent @@ -534,30 +537,32 @@ agent = Agent( ) ``` -알아둘 사항: +알아둘 점: - 인증: `CODEX_API_KEY`(권장) 또는 `OPENAI_API_KEY` 를 설정하거나, `codex_options={"api_key": "..."}` 를 전달하세요 - 런타임: `codex_options.base_url` 이 CLI base URL 을 오버라이드합니다 -- 바이너리 해석: CLI 경로를 고정하려면 `codex_options.codex_path_override`(또는 `CODEX_PATH`)를 설정하세요. 그렇지 않으면 SDK 가 `PATH` 에서 `codex` 를 해석한 다음, 번들된 vendor 바이너리로 폴백합니다 -- 환경: `codex_options.env` 는 서브프로세스 환경을 완전히 제어합니다. 제공되면 서브프로세스는 `os.environ` 을 상속하지 않습니다 -- 스트림 제한: `codex_options.codex_subprocess_stream_limit_bytes`(또는 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`)가 stdout/stderr 리더 제한을 제어합니다. 유효 범위는 `65536` ~ `67108864` 이며, 기본값은 `8388608` 입니다 -- 입력: 도구 호출에는 `inputs` 에 최소 1개 항목이 포함되어야 하며, `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }` 여야 합니다 +- 바이너리 해석: CLI 경로를 고정하려면 `codex_options.codex_path_override`(또는 `CODEX_PATH`)를 설정하세요. 그렇지 않으면 SDK 가 `PATH` 에서 `codex` 를 찾고, 이후 번들된 vendor 바이너리로 폴백합니다 +- 환경: `codex_options.env` 가 서브프로세스 환경을 완전히 제어합니다. 이것이 제공되면 서브프로세스는 `os.environ` 을 상속하지 않습니다 +- 스트림 제한: `codex_options.codex_subprocess_stream_limit_bytes`(또는 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`)가 stdout/stderr 리더 제한을 제어합니다. 유효 범위는 `65536` ~ `67108864` 이며 기본값은 `8388608` 입니다 +- 입력: 도구 호출에는 `inputs` 에 `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }` 항목이 최소 1개 포함되어야 합니다 - 스레드 기본값: `model_reasoning_effort`, `web_search_mode`(레거시 `web_search_enabled` 보다 권장), `approval_policy`, `additional_directories` 를 위해 `default_thread_options` 를 구성하세요 - 턴 기본값: `idle_timeout_seconds` 와 취소 `signal` 을 위해 `default_turn_options` 를 구성하세요 -- 안전: `sandbox_mode` 를 `working_directory` 와 함께 사용하고, Git 리포지토리 밖에서는 `skip_git_repo_check=True` 를 설정하세요 -- 동작: `persist_session=True` 는 단일 Codex 스레드를 재사용하고 해당 `thread_id` 를 반환합니다 -- 스트리밍: `on_stream` 이 Codex 이벤트(추론, 명령 실행, MCP 도구 호출, 파일 변경, 웹 검색)를 수신합니다 +- 안전: `sandbox_mode` 를 `working_directory` 와 함께 사용하고, Git 저장소 밖에서는 `skip_git_repo_check=True` 를 설정하세요 +- run 컨텍스트 스레드 지속성: `use_run_context_thread_id=True` 는 동일한 컨텍스트를 공유하는 run 들에 걸쳐 run 컨텍스트에 `thread_id` 를 저장하고 재사용합니다. 이를 위해서는 변경 가능한 run 컨텍스트(예: `dict` 또는 쓰기 가능한 객체 필드)가 필요합니다 +- run 컨텍스트 키 기본값: 저장 키는 `name="codex"` 일 때 기본적으로 `codex_thread_id`, `name="codex_"` 일 때는 `codex_thread_id_` 입니다. 오버라이드하려면 `run_context_thread_id_key` 를 설정하세요 +- Thread ID 우선순위: 호출별 `thread_id` 입력이 최우선이며, 그 다음은(활성화된 경우) run 컨텍스트 `thread_id`, 그 다음은 구성된 `thread_id` 옵션입니다 +- 스트리밍: `on_stream` 은 스레드/턴 라이프사이클 이벤트와 아이템 이벤트(`reasoning`, `command_execution`, `mcp_tool_call`, `file_change`, `web_search`, `todo_list`, `error` 아이템 업데이트)를 받습니다 - 출력: 결과에는 `response`, `usage`, `thread_id` 가 포함되며, usage 는 `RunContextWrapper.usage` 에 추가됩니다 -- 구조: `output_schema` 는 타입이 있는 출력이 필요할 때 구조화된 Codex 응답을 강제합니다 -- 완전한 실행 가능 샘플은 `examples/tools/codex.py` 를 참고하세요 +- 구조: `output_schema` 는 타입 있는 출력이 필요할 때 구조화된 Codex 응답을 강제합니다 +- 완전히 실행 가능한 샘플은 `examples/tools/codex.py` 와 `examples/tools/codex_same_thread.py` 를 참고하세요 -## 함수 도구에서의 오류 처리 +## 함수 도구에서 오류 처리 -`@function_tool` 로 함수 도구를 만들 때 `failure_error_function` 을 전달할 수 있습니다. 이는 도구 호출이 크래시했을 때 LLM 에게 오류 응답을 제공하는 함수입니다. +`@function_tool` 로 함수 도구를 만들 때 `failure_error_function` 을 전달할 수 있습니다. 이는 도구 호출이 크래시했을 때 LLM 에 제공할 오류 응답을 만들어주는 함수입니다. -- 기본값(즉, 아무것도 전달하지 않으면)으로 `default_tool_error_function` 이 실행되어 LLM 에 오류가 발생했음을 알려줍니다 -- 사용자 정의 오류 함수를 전달하면, 대신 그것이 실행되어 응답이 LLM 으로 전송됩니다 -- 명시적으로 `None` 을 전달하면, 어떤 도구 호출 오류든 사용자가 처리할 수 있도록 다시 raise 됩니다. 이는 모델이 잘못된 JSON 을 생성한 경우 `ModelBehaviorError` 일 수도 있고, 코드가 크래시한 경우 `UserError` 일 수도 있습니다 +- 기본값(아무것도 전달하지 않으면)으로는 `default_tool_error_function` 이 실행되며, LLM 에 오류가 발생했다고 알립니다 +- 사용자 정의 오류 함수를 전달하면, 대신 그 함수가 실행되어 응답이 LLM 으로 전송됩니다 +- `None` 을 명시적으로 전달하면, 도구 호출 오류가 다시 raise 되어 사용자가 처리해야 합니다. 이는 모델이 유효하지 않은 JSON 을 생성한 경우의 `ModelBehaviorError` 일 수도 있고, 코드가 크래시한 경우의 `UserError` 일 수도 있습니다 ```python from agents import function_tool, RunContextWrapper diff --git a/docs/zh/examples.md b/docs/zh/examples.md index 6ad6fa4bb..e56b53f2d 100644 --- a/docs/zh/examples.md +++ b/docs/zh/examples.md @@ -4,58 +4,58 @@ search: --- # 代码示例 -请查看 [repo](https://github.com/openai/openai-agents-python/tree/main/examples) 的 examples 部分中 SDK 的多种示例实现。这些 code examples 按多个目录组织，展示了不同的模式与能力。 +请查看 [repo](https://github.com/openai/openai-agents-python/tree/main/examples) 的 examples 部分，其中包含多种 SDK 的 sample implementations。这些代码示例按多个目录组织，用于展示不同的模式与能力。 ## 目录 - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - 此目录中的示例展示了常见的智能体设计模式，例如： + 此目录中的代码示例展示常见的智能体设计模式，例如： - 确定性工作流 - Agents as tools - 并行智能体执行 - 条件式工具使用 - 输入/输出安全防护措施 - - LLM 作为裁判 + - LLM 作为评审 - 路由 - - 流式安全防护措施 + - 流式传输安全防护措施 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - 这些 code examples 展示了 SDK 的基础能力，例如： + 这些代码示例展示 SDK 的基础能力，例如： - - Hello World 代码示例（默认模型、GPT-5、开源权重模型） + - Hello World 代码示例（Default model、GPT-5、open-weight model） - 智能体生命周期管理 - 动态系统提示词 - - 流式输出（文本、条目、函数调用参数） + - 流式传输输出（文本、条目、函数调用参数） - 提示词模板 - 文件处理（本地与远程、图片与 PDF） - 用量追踪 - 非严格输出类型 - - 先前响应 ID 的使用 + - 先前 response ID 的使用 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** 面向航空公司的示例客服系统。 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 一个金融研究智能体，展示了使用智能体与工具的结构化研究工作流，用于金融数据分析。 + 一个金融研究智能体，展示使用智能体与工具构建结构化研究工作流，以进行金融数据分析。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - 查看带消息过滤的智能体任务转移的实用示例。 + 查看带消息过滤的智能体任务转移的实用代码示例。 - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - 展示如何使用托管的 MCP（Model context protocol）连接器与审批的 code examples。 + 展示如何使用 hosted MCP (Model Context Protocol) 连接器与审批的代码示例。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - 学习如何使用 MCP（Model context protocol）构建智能体，包括： + 了解如何使用 MCP (Model Context Protocol) 构建智能体，包括： - - 文件系统 code examples - - Git code examples - - MCP 提示词服务 code examples - - SSE（Server-Sent Events）code examples - - 可流式的 HTTP code examples + - 文件系统代码示例 + - Git 代码示例 + - MCP prompt server 代码示例 + - SSE (Server-Sent Events) 代码示例 + - 可流式 HTTP 代码示例 - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - 智能体的不同记忆实现 code examples，包括： + 面向智能体的不同记忆实现的代码示例，包括： - SQLite 会话存储 - 高级 SQLite 会话存储 @@ -65,30 +65,31 @@ search: - OpenAI 会话存储 - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 探索如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方与 LiteLLM 集成。 + 探索如何在 SDK 中使用非 OpenAI 模型，包括自定义 provider 与 LiteLLM 集成。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - 展示如何使用 SDK 构建实时体验的 code examples，包括： + 展示如何使用 SDK 构建实时体验的代码示例，包括： - Web 应用 - 命令行界面 - Twilio 集成 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - 展示如何使用推理内容与 structured outputs 的 code examples。 + 展示如何处理 reasoning content 与 structured outputs 的代码示例。 - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 简易深度研究克隆版，展示复杂的多智能体研究工作流。 + 一个简单的深度研究克隆，展示复杂的多智能体研究工作流。 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - 学习如何实现由OpenAI托管的工具与实验性的 Codex 工具能力，例如： + 了解如何实现由OpenAI托管的工具与实验性 Codex tooling，例如： - - 网络检索与带过滤条件的网络检索 + - 网络检索以及带过滤条件的网络检索 - 文件检索 - Code Interpreter - 计算机操作 - 图像生成 - 实验性 Codex 工具工作流（`examples/tools/codex.py`） + - 实验性 Codex 同线程工作流（`examples/tools/codex_same_thread.py`） - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 查看语音智能体 code examples，使用我们的 TTS 与 STT 模型，包括流式语音示例。 \ No newline at end of file + 查看语音智能体的代码示例，使用我们的 TTS 与 STT 模型，包括流式语音代码示例。 \ No newline at end of file diff --git a/docs/zh/tools.md b/docs/zh/tools.md index f0c10c539..f8f765b5c 100644 --- a/docs/zh/tools.md +++ b/docs/zh/tools.md @@ -4,13 +4,13 @@ search: --- # 工具 -工具让智能体执行操作：例如获取数据、运行代码、调用外部 API，甚至使用计算机。SDK 支持五类工具： +工具让智能体能够采取行动：例如获取数据、运行代码、调用外部 API，甚至进行计算机操作。SDK 支持五个类别： -- 由OpenAI托管的工具：与模型一起在 OpenAI 服务上运行。 -- 本地运行时工具：在你的环境中运行（计算机操作、shell、apply patch）。 -- 工具调用：将任意 Python 函数封装为工具。 +- 由OpenAI托管的工具：与模型一同在 OpenAI 服务器上运行。 +- 本地运行时工具：在你的环境中运行（计算机操作、shell、应用补丁）。 +- Function Calling：将任意 Python 函数封装为工具。 - Agents as tools：将智能体暴露为可调用工具，而无需完整的任务转移。 -- 实验性：Codex tool：通过工具调用运行工作区范围的 Codex 任务。 +- 实验性：Codex 工具：通过工具调用运行工作区范围的 Codex 任务。 ## 由OpenAI托管的工具 @@ -18,7 +18,7 @@ search: - [`WebSearchTool`][agents.tool.WebSearchTool] 让智能体进行网络检索。 - [`FileSearchTool`][agents.tool.FileSearchTool] 允许从你的 OpenAI 向量存储中检索信息。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] 让 LLM 在沙盒环境中执行代码。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] 让 LLM 在沙箱环境中执行代码。 - [`HostedMCPTool`][agents.tool.HostedMCPTool] 将远程 MCP 服务的工具暴露给模型。 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] 根据提示词生成图像。 @@ -43,10 +43,10 @@ async def main(): ## 本地运行时工具 -本地运行时工具在你的环境中执行，需要你提供实现： +本地运行时工具在你的环境中执行，并且需要你提供实现： -- [`ComputerTool`][agents.tool.ComputerTool]：实现 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 接口以启用 GUI/浏览器自动化。 -- [`ShellTool`][agents.tool.ShellTool] 或 [`LocalShellTool`][agents.tool.LocalShellTool]：提供 shell 执行器来运行命令。 +- [`ComputerTool`][agents.tool.ComputerTool]：实现 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 接口，以启用 GUI/浏览器自动化。 +- [`ShellTool`][agents.tool.ShellTool] 或 [`LocalShellTool`][agents.tool.LocalShellTool]：提供一个 shell 执行器来运行命令。 - [`ApplyPatchTool`][agents.tool.ApplyPatchTool]：实现 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor] 以在本地应用 diff。 ```python @@ -91,14 +91,14 @@ agent = Agent( ## 工具调用 -你可以将任何 Python 函数作为工具使用。Agents SDK 会自动设置该工具： +你可以将任意 Python 函数用作工具。Agents SDK 会自动设置该工具： -- 工具名称将是 Python 函数的名称（或你可以提供名称） +- 工具的名称将是 Python 函数的名称（或你可以提供一个名称） - 工具描述将来自函数的 docstring（或你可以提供描述） -- 函数输入的 schema 会从函数参数自动创建 -- 每个输入的描述来自函数的 docstring，除非禁用 +- 函数输入的 schema 会根据函数参数自动创建 +- 除非禁用，否则每个输入的描述将从函数 docstring 中获取 -我们使用 Python 的 `inspect` 模块来提取函数签名，并结合 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析 docstring，以及使用 `pydantic` 创建 schema。 +我们使用 Python 的 `inspect` 模块提取函数签名，并结合 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析 docstring，以及使用 `pydantic` 创建 schema。 ```python import json @@ -150,10 +150,10 @@ for tool in agent.tools: ``` -1. 你可以将任何 Python 类型作为函数参数，函数可以是同步或异步。 -2. 如果存在 docstring，会用于捕获描述以及参数描述。 -3. 函数可以选择性地接收 `context`（必须是第一个参数）。你也可以设置覆盖项，例如工具名称、描述、使用哪种 docstring 风格等。 -4. 你可以将被装饰的函数传入 tools 列表。 +1. 你可以在函数参数中使用任意 Python 类型，函数也可以是同步或异步的。 +2. 如果存在 docstring，将用于获取描述以及参数描述。 +3. 函数可选地接收 `context`（必须是第一个参数）。你也可以设置覆盖项，例如工具名称、描述、要使用的 docstring 风格等。 +4. 你可以将装饰后的函数传入工具列表。 ??? note "展开查看输出" @@ -227,20 +227,20 @@ for tool in agent.tools: ### 从工具调用返回图像或文件 -除了返回文本输出外，你还可以返回一个或多个图像或文件作为工具调用的输出。为此，你可以返回以下任意一种： +除了返回文本输出之外，你还可以将一个或多个图像或文件作为工具调用的输出返回。为此，你可以返回以下任意一种： -- 图像：[`ToolOutputImage`][agents.tool.ToolOutputImage]（或其 TypedDict 版本 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]） -- 文件：[`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（或其 TypedDict 版本 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]） -- 文本：字符串或可转换为字符串的对象，或 [`ToolOutputText`][agents.tool.ToolOutputText]（或其 TypedDict 版本 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]） +- 图像：[`ToolOutputImage`][agents.tool.ToolOutputImage]（或 TypedDict 版本 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]） +- 文件：[`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（或 TypedDict 版本 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]） +- 文本：字符串或可转换为字符串的对象，或 [`ToolOutputText`][agents.tool.ToolOutputText]（或 TypedDict 版本 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]） ### 自定义工具调用 -有时，你不希望使用 Python 函数作为工具。如果你愿意，也可以直接创建一个 [`FunctionTool`][agents.tool.FunctionTool]。你需要提供： +有时，你不想把 Python 函数作为工具使用。若你愿意，也可以直接创建一个 [`FunctionTool`][agents.tool.FunctionTool]。你需要提供： - `name` - `description` -- `params_json_schema`：参数的 JSON schema -- `on_invoke_tool`：一个异步函数，接收 [`ToolContext`][agents.tool_context.ToolContext] 和以 JSON 字符串形式提供的参数，并且必须以字符串形式返回工具输出。 +- `params_json_schema`，即参数的 JSON schema +- `on_invoke_tool`，一个异步函数，它接收 [`ToolContext`][agents.tool_context.ToolContext] 与以 JSON 字符串形式提供的参数，并且必须以字符串形式返回工具输出。 ```python from typing import Any @@ -273,18 +273,18 @@ tool = FunctionTool( ) ``` -### 自动解析参数与 docstring +### 自动参数与 docstring 解析 -如前所述，我们会自动解析函数签名以提取工具 schema，并解析 docstring 以提取工具及其各个参数的描述。注意事项如下： +如前所述，我们会自动解析函数签名以提取工具 schema，并解析 docstring 以提取工具及各参数的描述。补充说明如下： -1. 签名解析通过 `inspect` 模块完成。我们使用类型注解来理解参数类型，并动态构建一个 Pydantic 模型来表示整体 schema。它支持大多数类型，包括 Python 基元类型、Pydantic 模型、TypedDict 等。 -2. 我们使用 `griffe` 来解析 docstring。支持的 docstring 格式为 `google`、`sphinx` 和 `numpy`。我们会尽力自动检测 docstring 格式，但这只是 best-effort；你也可以在调用 `function_tool` 时显式设置。你还可以将 `use_docstring_info` 设为 `False` 来禁用 docstring 解析。 +1. 签名解析通过 `inspect` 模块完成。我们使用类型注解来理解参数类型，并动态构建一个 Pydantic model 来表示整体 schema。它支持大多数类型，包括 Python 基本类型、Pydantic model、TypedDict 等。 +2. 我们使用 `griffe` 解析 docstring。支持的 docstring 格式包括 `google`、`sphinx` 和 `numpy`。我们会尝试自动检测 docstring 格式，但这是尽力而为；你也可以在调用 `function_tool` 时显式设置。你还可以将 `use_docstring_info` 设为 `False` 来禁用 docstring 解析。 -用于提取 schema 的代码位于 [`agents.function_schema`][]。 +schema 提取相关代码位于 [`agents.function_schema`][] 中。 ## Agents as tools -在某些工作流中，你可能希望由一个中心智能体来编排一组专门化智能体，而不是进行任务转移。你可以通过将智能体建模为工具来实现这一点。 +在一些工作流中，你可能希望由一个中心智能体来编排一组专门智能体的网络，而不是移交控制权。你可以通过将智能体建模为工具来实现这一点。 ```python from agents import Agent, Runner @@ -323,9 +323,9 @@ async def main(): print(result.final_output) ``` -### 自定义工具型智能体 +### 自定义工具智能体 -`agent.as_tool` 函数是一个便捷方法，便于将智能体转换为工具。它支持常见的运行时选项，例如 `max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session` 和 `needs_approval`。它也支持通过 `parameters`、`input_builder` 与 `include_input_schema` 提供结构化输入。对于高级编排（例如条件重试、回退行为，或串联多个智能体调用），请在你的工具实现中直接使用 `Runner.run`： +`agent.as_tool` 函数是一个便捷方法，可以轻松将智能体转换为工具。它支持常见的运行时选项，例如 `max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session` 和 `needs_approval`。它也支持通过 `parameters`、`input_builder` 和 `include_input_schema` 提供结构化输入。对于高级编排（例如条件重试、回退行为或串联多个智能体调用），请在你的工具实现中直接使用 `Runner.run`： ```python @function_tool @@ -344,15 +344,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### 工具型智能体的结构化输入 +### 工具智能体的结构化输入 -默认情况下，`Agent.as_tool()` 期望单个字符串输入（`{"input": "..."}`），但你可以通过传入 `parameters`（Pydantic 模型或 dataclass 类型）来暴露一个结构化 schema。 +默认情况下，`Agent.as_tool()` 期望单个字符串输入（`{"input": "..."}`），但你可以通过传入 `parameters`（Pydantic model 或 dataclass 类型）来暴露一个结构化 schema。 其他选项： - `include_input_schema=True` 会在生成的嵌套输入中包含完整的 JSON Schema。 - `input_builder=...` 允许你完全自定义结构化工具参数如何转换为嵌套的智能体输入。 -- `RunContextWrapper.tool_input` 在嵌套的运行上下文中包含已解析的结构化载荷。 +- `RunContextWrapper.tool_input` 在嵌套 run context 内包含已解析的结构化 payload。 ```python from pydantic import BaseModel, Field @@ -372,18 +372,18 @@ translator_tool = translator_agent.as_tool( ) ``` -完整的可运行示例请参见 `examples/agent_patterns/agents_as_tools_structured.py`。 +完整可运行示例请参见 `examples/agent_patterns/agents_as_tools_structured.py`。 -### 工具型智能体的审批门控 +### 工具智能体的审批关口 -`Agent.as_tool(..., needs_approval=...)` 使用与 `function_tool` 相同的审批流程。如果需要审批，运行会暂停，待处理项会出现在 `result.interruptions` 中；然后使用 `result.to_state()`，并在调用 `state.approve(...)` 或 `state.reject(...)` 后恢复。完整的暂停/恢复模式请参见 [Human-in-the-loop guide](human_in_the_loop.md)。 +`Agent.as_tool(..., needs_approval=...)` 使用与 `function_tool` 相同的审批流程。如果需要审批，运行会暂停，待处理项会出现在 `result.interruptions` 中；随后使用 `result.to_state()`，并在调用 `state.approve(...)` 或 `state.reject(...)` 后恢复。完整的暂停/恢复模式请参见 [Human-in-the-loop guide](human_in_the_loop.md)。 ### 自定义输出提取 -在某些情况下，你可能希望在将工具型智能体的输出返回给中心智能体之前对其进行修改。这在以下场景中可能有用： +在某些情况下，你可能希望在将工具智能体的输出返回给中心智能体之前对其进行修改。这在以下场景中可能有用： -- 从子智能体的聊天记录中提取特定信息（例如 JSON 载荷）。 -- 转换或重新格式化智能体的最终答案（例如将 Markdown 转为纯文本或 CSV）。 +- 从子智能体的聊天历史中提取特定信息（例如 JSON payload）。 +- 转换或重新格式化智能体的最终答案（例如将 Markdown 转换为纯文本或 CSV）。 - 校验输出，或在智能体响应缺失或格式不正确时提供回退值。 你可以通过向 `as_tool` 方法提供 `custom_output_extractor` 参数来实现： @@ -405,9 +405,9 @@ json_tool = data_agent.as_tool( ) ``` -### 流式传输嵌套智能体运行 +### 嵌套智能体运行的流式传输 -向 `as_tool` 传入 `on_stream` 回调，以监听嵌套智能体发出的流式事件，同时在流结束后仍返回其最终输出。 +向 `as_tool` 传入 `on_stream` 回调，以监听嵌套智能体发出的流式事件，同时仍在流结束后返回其最终输出。 ```python from agents import AgentToolStreamEvent @@ -425,17 +425,17 @@ billing_agent_tool = billing_agent.as_tool( ) ``` -预期行为： +可预期行为： -- 事件类型与 `StreamEvent["type"]` 一致：`raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。 -- 提供 `on_stream` 会自动以流式模式运行嵌套智能体，并在返回最终输出前耗尽该流。 -- 处理器可以是同步或异步；每个事件会按到达顺序交付。 -- 当工具是通过模型工具调用触发时，会包含 `tool_call`；直接调用可能使其为 `None`。 +- 事件类型与 `StreamEvent["type"]` 对应：`raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。 +- 提供 `on_stream` 会自动以流式模式运行嵌套智能体，并在返回最终输出前消费完流。 +- 处理器可以是同步或异步；每个事件会按到达顺序传递。 +- 当工具通过模型工具调用触发时，会存在 `tool_call`；直接调用可能为 `None`。 - 完整可运行示例请参见 `examples/agent_patterns/agents_as_tools_streaming.py`。 ### 条件启用工具 -你可以使用 `is_enabled` 参数在运行时有条件地启用或禁用智能体工具。这使你能够基于上下文、用户偏好或运行时条件，动态过滤 LLM 可用的工具。 +你可以在运行时使用 `is_enabled` 参数有条件地启用或禁用智能体工具。这使你能够基于上下文、用户偏好或运行时条件，动态筛选哪些工具对 LLM 可用。 ```python import asyncio @@ -490,22 +490,25 @@ async def main(): asyncio.run(main()) ``` -`is_enabled` 参数接受： +`is_enabled` 参数支持： - **布尔值**：`True`（始终启用）或 `False`（始终禁用） - **可调用函数**：接收 `(context, agent)` 并返回布尔值的函数 - **异步函数**：用于复杂条件逻辑的异步函数 -被禁用的工具在运行时对 LLM 完全隐藏，因此这对于以下场景很有用： +被禁用的工具在运行时会对 LLM 完全隐藏，因此可用于： -- 基于用户权限的功能门控 -- 环境特定的工具可用性（dev vs prod） +- 基于用户权限的功能开关 +- 特定环境的工具可用性（开发 vs 生产） - 对不同工具配置进行 A/B 测试 - 基于运行时状态的动态工具过滤 -## 实验性：Codex tool +## 实验性：Codex 工具 -`codex_tool` 封装了 Codex CLI，使智能体能够在工具调用期间运行工作区范围的任务（shell、文件编辑、MCP 工具）。该能力是实验性的，可能会发生变化。 +`codex_tool` 封装了 Codex CLI，使智能体能够在工具调用期间运行工作区范围的任务（shell、文件编辑、MCP 工具）。 +该接口为实验性，可能会发生变化。 +默认情况下，工具名称为 `codex`。如果你设置自定义名称，它必须是 `codex` 或以 `codex_` 开头。 +当一个智能体包含多个 Codex 工具时，每个工具必须使用唯一名称（包括与非 Codex 工具之间的唯一性）。 ```python from agents import Agent @@ -534,30 +537,32 @@ agent = Agent( ) ``` -要点： +注意事项： - 认证：设置 `CODEX_API_KEY`（推荐）或 `OPENAI_API_KEY`，或传入 `codex_options={"api_key": "..."}`。 -- 运行时：`codex_options.base_url` 覆盖 CLI base URL。 -- 二进制解析：设置 `codex_options.codex_path_override`（或 `CODEX_PATH`）以固定 CLI 路径。否则 SDK 会从 `PATH` 解析 `codex`，然后回退到随附的 vendor 二进制文件。 -- 环境：`codex_options.env` 完全控制子进程环境。提供该值时，子进程不会继承 `os.environ`。 +- 运行时：`codex_options.base_url` 会覆盖 CLI base URL。 +- 二进制解析：设置 `codex_options.codex_path_override`（或 `CODEX_PATH`）以固定 CLI 路径。否则 SDK 会从 `PATH` 解析 `codex`，再回退到打包的 vendor 二进制文件。 +- 环境：`codex_options.env` 完全控制子进程环境。提供该项时，子进程不会继承 `os.environ`。 - 流限制：`codex_options.codex_subprocess_stream_limit_bytes`（或 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`）控制 stdout/stderr 读取器限制。有效范围为 `65536` 到 `67108864`；默认值为 `8388608`。 -- 输入：工具调用必须在 `inputs` 中至少包含一个条目，形如 `{ "type": "text", "text": ... }` 或 `{ "type": "local_image", "path": ... }`。 +- 输入：工具调用必须在 `inputs` 中至少包含一项 `{ "type": "text", "text": ... }` 或 `{ "type": "local_image", "path": ... }`。 - 线程默认值：为 `model_reasoning_effort`、`web_search_mode`（优先于旧版 `web_search_enabled`）、`approval_policy` 和 `additional_directories` 配置 `default_thread_options`。 -- Turn 默认值：为 `idle_timeout_seconds` 和取消 `signal` 配置 `default_turn_options`。 +- 回合默认值：为 `idle_timeout_seconds` 和取消 `signal` 配置 `default_turn_options`。 - 安全：将 `sandbox_mode` 与 `working_directory` 配对使用；在 Git 仓库之外设置 `skip_git_repo_check=True`。 -- 行为：`persist_session=True` 复用单个 Codex 线程并返回其 `thread_id`。 -- 流式传输：`on_stream` 接收 Codex 事件（推理、命令执行、MCP 工具调用、文件变更、网络检索）。 -- 输出：结果包含 `response`、`usage` 和 `thread_id`；usage 会添加到 `RunContextWrapper.usage`。 -- 结构：当你需要类型化输出时，`output_schema` 强制 Codex 使用结构化响应。 -- 完整可运行示例请参见 `examples/tools/codex.py`。 +- Run-context 线程持久化：`use_run_context_thread_id=True` 会在 run context 中存储并复用 `thread_id`，跨共享该 context 的多次运行。这需要可变的 run context（例如 `dict` 或可写对象字段）。 +- Run-context key 默认值：当 `name="codex"` 时，存储 key 默认为 `codex_thread_id`；当 `name="codex_"` 时，默认为 `codex_thread_id_`。可通过 `run_context_thread_id_key` 覆盖。 +- Thread ID 优先级：每次调用提供的 `thread_id` 输入优先，其次是 run-context `thread_id`（若启用），最后是配置的 `thread_id` 选项。 +- 流式传输：`on_stream` 接收线程/回合生命周期事件与条目事件（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list` 以及 `error` 条目更新）。 +- 输出：结果包含 `response`、`usage` 和 `thread_id`；usage 会被加入到 `RunContextWrapper.usage`。 +- 结构：当你需要类型化输出时，`output_schema` 会强制 Codex 返回结构化响应。 +- 完整可运行示例请参见 `examples/tools/codex.py` 与 `examples/tools/codex_same_thread.py`。 -## 在工具调用中处理错误 +## 处理工具调用中的错误 -当你通过 `@function_tool` 创建工具调用时，可以传入 `failure_error_function`。这是一个函数，用于在工具调用崩溃时向 LLM 提供错误响应。 +当你通过 `@function_tool` 创建工具调用时，可以传入 `failure_error_function`。这是一个在工具调用崩溃时向 LLM 提供错误响应的函数。 -- 默认情况下（即不传任何内容），会运行 `default_tool_error_function` 来告知 LLM 发生了错误。 -- 如果你传入自己的错误函数，则会运行该函数并将响应发送给 LLM。 -- 如果你显式传入 `None`，则任何工具调用错误都会被重新抛出以便你处理。这可能是 `ModelBehaviorError`（如果模型生成了无效 JSON），或 `UserError`（如果你的代码崩溃）等。 +- 默认情况下（即不传任何值），会运行 `default_tool_error_function`，它会告知 LLM 发生了错误。 +- 如果你传入自己的错误函数，则会运行它，并将其响应发送给 LLM。 +- 如果你显式传入 `None`，则任何工具调用错误都会被重新抛出，由你处理。这可能是 `ModelBehaviorError`（例如模型生成了无效 JSON），或 `UserError`（例如你的代码崩溃）等。 ```python from agents import function_tool, RunContextWrapper @@ -580,4 +585,4 @@ def get_user_profile(user_id: str) -> str: ``` -如果你是手动创建 `FunctionTool` 对象，则必须在 `on_invoke_tool` 函数内处理错误。 \ No newline at end of file +如果你是手动创建 `FunctionTool` 对象，那么必须在 `on_invoke_tool` 函数内部处理错误。 \ No newline at end of file