From f05f6fa10f3e735163e43c1d0137b07134167ada Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 9 May 2026 02:59:34 +0000 Subject: [PATCH] Update all translated document pages --- docs/ja/running_agents.md | 208 +++++++++++++++++++------------------- docs/ko/running_agents.md | 173 +++++++++++++++---------------- docs/zh/running_agents.md | 196 +++++++++++++++++------------------ 3 files changed, 293 insertions(+), 284 deletions(-) diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index c66810ce08..d2eeaaecd5 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -[`Runner`][agents.run.Runner] クラスを通じてエージェントを実行できます。選択肢は 3 つあります。 +[`Runner`][agents.run.Runner] クラスを使用してエージェントを実行できます。選択肢は 3 つあります。 1. [`Runner.run()`][agents.run.Runner.run] は async で実行され、[`RunResult`][agents.result.RunResult] を返します。 2. [`Runner.run_sync()`][agents.run.Runner.run_sync] は sync メソッドで、内部的には単に `.run()` を実行します。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] は async で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。ストリーミングモードで LLM を呼び出し、受信したイベントをそのままストリームします。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] は async で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントをストリーミングします。 ```python from agents import Agent, Runner @@ -23,34 +23,34 @@ async def main(): # Infinite loop's dance ``` -詳しくは [実行結果ガイド](results.md) を参照してください。 +詳しくは [実行結果ガイド](results.md) をお読みください。 ## Runner のライフサイクルと設定 ### エージェントループ -`Runner` の run メソッドを使用する場合、開始エージェントと入力を渡します。入力には次のものを指定できます。 +`Runner` の run メソッドを使用するときは、開始エージェントと入力を渡します。入力には次を指定できます。 - 文字列（ユーザーメッセージとして扱われます）、 -- OpenAI Responses API 形式の入力項目のリスト、または +- OpenAI Responses API 形式の入力アイテムのリスト、または - 中断された実行を再開する場合の [`RunState`][agents.run_state.RunState]。 その後、runner はループを実行します。 -1. 現在のエージェントに対して、現在の入力を用いて LLM を呼び出します。 +1. 現在のエージェントに対して、現在の入力で LLM を呼び出します。 2. LLM が出力を生成します。 1. LLM が `final_output` を返した場合、ループは終了し、実行結果を返します。 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 3. LLM がツール呼び出しを生成した場合、それらのツール呼び出しを実行し、実行結果を追加して、ループを再実行します。 -3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を発生させます。このターン制限を無効にするには、`max_turns=None` を渡してください。 +3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を発生させます。このターン制限を無効にするには、`max_turns=None` を渡します。 !!! note - LLM の出力が「最終出力」と見なされる条件は、望ましい型のテキスト出力を生成し、ツール呼び出しがないことです。 + LLM 出力が「最終出力」と見なされるかどうかのルールは、目的の型のテキスト出力を生成し、ツール呼び出しがないことです。 ### ストリーミング -ストリーミングを使用すると、LLM の実行中にストリーミングイベントを追加で受け取ることができます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む実行に関する完全な情報が含まれます。ストリーミングイベントには `.stream_events()` を呼び出せます。詳しくは [ストリーミングガイド](streaming.md) を参照してください。 +ストリーミングを使用すると、LLM の実行中にストリーミングイベントも受信できます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む、実行に関する完全な情報が含まれます。ストリーミングイベントには `.stream_events()` を呼び出せます。詳しくは [ストリーミングガイド](streaming.md) をお読みください。 #### Responses WebSocket トランスポート（任意のヘルパー） @@ -58,11 +58,11 @@ OpenAI Responses websocket トランスポートを有効にしても、通常 これは websocket トランスポート上の Responses API であり、[Realtime API](realtime/guide.md) ではありません。 -トランスポート選択ルール、および具体的なモデルオブジェクトやカスタムプロバイダーに関する注意点については、[モデル](models/index.md#responses-websocket-transport) を参照してください。 +トランスポート選択ルールや、具体的なモデルオブジェクトまたはカスタムプロバイダーに関する注意点については、[モデル](models/index.md#responses-websocket-transport) を参照してください。 -##### パターン 1: セッションヘルパーなし（動作可） +##### パターン 1: セッションヘルパーなし（動作します） -websocket トランスポートだけを使いたく、SDK に共有プロバイダーやセッションを管理させる必要がない場合に使用します。 +websocket トランスポートだけが必要で、SDK に共有プロバイダー / セッションを管理させる必要がない場合に使用します。 ```python import asyncio @@ -87,9 +87,9 @@ asyncio.run(main()) このパターンは単発の実行には問題ありません。`Runner.run()` / `Runner.run_streamed()` を繰り返し呼び出す場合、同じ `RunConfig` / プロバイダーインスタンスを手動で再利用しない限り、各実行で再接続される可能性があります。 -##### パターン 2: `responses_websocket_session()` の使用（複数ターンの再利用に推奨） +##### パターン 2: `responses_websocket_session()` の使用（複数ターンでの再利用に推奨） -複数の実行にまたがって共有の websocket 対応プロバイダーと `RunConfig` を使用したい場合（同じ `run_config` を継承するネストされた agent-as-tool 呼び出しを含む）は、[`responses_websocket_session()`][agents.responses_websocket_session] を使用してください。 +複数の実行（同じ `run_config` を継承するネストされた agent-as-tool 呼び出しを含む）で共有の websocket 対応プロバイダーと `RunConfig` が必要な場合は、[`responses_websocket_session()`][agents.responses_websocket_session] を使用します。 ```python import asyncio @@ -119,9 +119,9 @@ async def main(): asyncio.run(main()) ``` -コンテキストを終了する前に、ストリーミングされた実行結果の消費を完了してください。websocket リクエストがまだ実行中の間にコンテキストを終了すると、共有接続が強制的に閉じられる可能性があります。 +コンテキストを抜ける前に、ストリーミングされた実行結果の消費を完了してください。websocket リクエストがまだ実行中の間にコンテキストを抜けると、共有接続が強制的に閉じられる可能性があります。 -長い reasoning ターンで websocket keepalive のタイムアウトが発生する場合は、`ping_timeout` を増やすか、`ping_timeout=None` を設定して heartbeat タイムアウトを無効にしてください。websocket のレイテンシより信頼性が重要な実行では、HTTP/SSE トランスポートを使用してください。 +長い推論ターンで websocket keepalive タイムアウトが発生する場合は、`ping_timeout` を増やすか、`ping_timeout=None` を設定して heartbeat タイムアウトを無効にしてください。websocket のレイテンシーより信頼性が重要な実行では、HTTP/SSE トランスポートを使用してください。 ### 実行設定 @@ -129,45 +129,45 @@ asyncio.run(main()) #### 一般的な実行設定カテゴリー -各エージェント定義を変更せずに、単一の実行の挙動を上書きするには `RunConfig` を使用します。 +各エージェント定義を変更せずに、単一の実行の動作を上書きするには `RunConfig` を使用します。 ##### モデル、プロバイダー、セッションのデフォルト -- [`model`][agents.run.RunConfig.model]: 各 Agent が持つ `model` に関係なく、使用するグローバルな LLM モデルを設定できます。 +- [`model`][agents.run.RunConfig.model]: 各 Agent が持つ `model` に関係なく、使用するグローバル LLM モデルを設定できます。 - [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を検索するためのモデルプロバイダーで、デフォルトは OpenAI です。 -- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 -- [`session_settings`][agents.run.RunConfig.session_settings]: 実行中に履歴を取得する際のセッションレベルのデフォルト（例: `SessionSettings(limit=...)`）を上書きします。 -- [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions 使用時に、各ターンの前に新しいユーザー入力をセッション履歴とどのようにマージするかをカスタマイズします。コールバックは sync または async にできます。 +- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` または `top_p` を設定できます。 +- [`session_settings`][agents.run.RunConfig.session_settings]: 実行中に履歴を取得する際のセッションレベルのデフォルト（たとえば `SessionSettings(limit=...)`）を上書きします。 +- [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions を使用するとき、各ターンの前に新しいユーザー入力をセッション履歴とどのようにマージするかをカスタマイズします。コールバックは sync または async にできます。 ##### ガードレール、ハンドオフ、モデル入力の整形 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails]、[`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力または出力ガードレールのリストです。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに入力フィルターがまだない場合に、すべてのハンドオフに適用するグローバル入力フィルターです。入力フィルターを使うと、新しいエージェントに送信される入力を編集できます。詳細については [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 次のエージェントを呼び出す前に、以前のトランスクリプトを 1 つの assistant メッセージに折りたたむ opt-in beta です。ネストされたハンドオフを安定化している間はデフォルトで無効です。有効にするには `True` に設定し、raw トランスクリプトをそのまま渡すには `False` のままにしてください。すべての [Runner メソッド][agents.run.Runner] は、渡されない場合に自動的に `RunConfig` を作成するため、クイックスタートとコード例ではデフォルトがオフのままになり、明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] コールバックは引き続きこれを上書きします。個々のハンドオフは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を通じてこの設定を上書きできます。 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` を opt in したときに、正規化されたトランスクリプト（履歴 + ハンドオフ項目）を受け取る任意の callable です。次のエージェントへ転送する入力項目の正確なリストを返す必要があり、完全なハンドオフフィルターを書かずに組み込みの要約を置き換えられます。 -- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: モデル呼び出しの直前に、完全に準備されたモデル入力（instructions と入力項目）を編集するためのフックです。たとえば、履歴をトリムしたり、システムプロンプトを注入したりできます。 -- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner が以前の出力を次ターンのモデル入力に変換する際に、reasoning item ID を保持するか省略するかを制御します。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力または出力ガードレールのリストです。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフにすでにフィルターがない場合に、すべてのハンドオフに適用するグローバル入力フィルターです。入力フィルターを使用すると、新しいエージェントに送信される入力を編集できます。詳細については、[`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 次のエージェントを呼び出す前に、以前の transcript を単一の assistant メッセージに折りたたむ opt-in beta です。ネストされたハンドオフを安定化する間、これはデフォルトで無効です。有効にするには `True` に設定し、raw transcript をそのまま渡すには `False` のままにします。[Runner methods][agents.run.Runner] は `RunConfig` を渡さない場合に自動的に作成するため、クイックスタートとコード例ではデフォルトがオフのままになり、明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] コールバックは引き続きこれを上書きします。個別のハンドオフでは、[`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を介してこの設定を上書きできます。 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` に opt in したときに、正規化済み transcript（履歴 + ハンドオフアイテム）を受け取る任意の callable です。次のエージェントに転送する入力アイテムの正確なリストを返す必要があり、完全なハンドオフフィルターを書かずに組み込み summary を置き換えられます。 +- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: モデル呼び出しの直前に、完全に準備されたモデル入力（instructions と入力アイテム）を編集する hook です。たとえば、履歴を trim したり、システムプロンプトを注入したりできます。 +- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner が以前の出力を次ターンのモデル入力に変換するとき、reasoning item ID を保持するか省略するかを制御します。 ##### トレーシングと可観測性 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体で [トレーシング](tracing.md) を無効にできます。 -- [`tracing`][agents.run.RunConfig.tracing]: 実行ごとのトレーシング API キーなどの trace エクスポート設定を上書きするために、[`TracingConfig`][agents.tracing.TracingConfig] を渡します。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: trace に、LLM やツール呼び出しの入力/出力など、潜在的に機密性のあるデータを含めるかどうかを構成します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name]、[`trace_id`][agents.run.RunConfig.trace_id]、[`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングワークフロー名、trace ID、trace group ID を設定します。少なくとも `workflow_name` を設定することをおすすめします。group ID は、複数の実行にまたがって trace をリンクできる任意フィールドです。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効にできます。 +- [`tracing`][agents.run.RunConfig.tracing]: 実行ごとのトレーシング API キーなど、trace export 設定を上書きするために [`TracingConfig`][agents.tracing.TracingConfig] を渡します。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入力 / 出力など、機密の可能性があるデータを trace に含めるかどうかを構成します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング workflow 名、trace ID、trace group ID を設定します。少なくとも `workflow_name` を設定することをお勧めします。group ID は、複数の実行にわたって trace をリンクできる任意フィールドです。 - [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべての trace に含めるメタデータです。 -##### ツール実行、承認、ツールエラーの挙動 +##### ツール実行、承認、ツールエラー動作 -- [`tool_execution`][agents.run.RunConfig.tool_execution]: 一度に実行される関数ツールの数を制限するなど、ローカルツール呼び出しに対する SDK 側の実行挙動を構成します。 -- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 承認フロー中にツール呼び出しが拒否された場合に、モデルに表示されるメッセージをカスタマイズします。 +- [`tool_execution`][agents.run.RunConfig.tool_execution]: 同時に実行する関数ツールの数を制限するなど、ローカルツール呼び出しに対する SDK 側の実行動作を構成します。 +- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 承認フロー中にツール呼び出しが拒否された場合に、モデルに見えるメッセージをカスタマイズします。 -ネストされたハンドオフは opt-in beta として利用できます。`RunConfig(nest_handoff_history=True)` を渡すか、特定のハンドオフに対して `handoff(..., nest_handoff_history=True)` を設定して、折りたたまれたトランスクリプトの挙動を有効にします。raw トランスクリプト（デフォルト）を保持したい場合は、フラグを未設定のままにするか、会話を必要どおり正確に転送する `handoff_input_filter`（または `handoff_history_mapper`）を指定してください。カスタム mapper を書かずに、生成された要約で使用されるラッパーテキストを変更するには、[`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（デフォルトに戻すには [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出してください。 +ネストされたハンドオフは opt-in beta として利用できます。折りたたまれた transcript の動作を有効にするには `RunConfig(nest_handoff_history=True)` を渡すか、特定のハンドオフで有効にするために `handoff(..., nest_handoff_history=True)` を設定します。raw transcript（デフォルト）を保持したい場合は、フラグを未設定のままにするか、必要どおりに会話を正確に転送する `handoff_input_filter`（または `handoff_history_mapper`）を提供します。カスタム mapper を書かずに、生成される summary で使用される wrapper text を変更するには、[`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（デフォルトを復元するには [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出します。 #### 実行設定の詳細 ##### `tool_execution` -ある実行に対して、SDK にローカル関数ツールの同時実行数を制限させたい場合は `tool_execution` を使用します。 +実行に対して SDK にローカル関数ツールの同時実行数を制限させたい場合は、`tool_execution` を使用します。 ```python from agents import Agent, RunConfig, Runner, ToolExecutionConfig @@ -183,22 +183,22 @@ result = await Runner.run( ) ``` -`max_function_tool_concurrency=None` はデフォルトの挙動を保持します。モデルが 1 ターンで複数の関数ツール呼び出しを発行した場合、SDK は発行されたすべてのローカル関数ツール呼び出しを開始します。同時に実行されるローカル関数ツールの数に上限を設けるには、整数値を設定します。 +`max_function_tool_concurrency=None` はデフォルトの動作を維持します。モデルが 1 ターンで複数の関数ツール呼び出しを出力した場合、SDK は出力されたすべてのローカル関数ツール呼び出しを開始します。同時に実行されるローカル関数ツールの数に上限を設けるには、整数値を設定します。 -これはプロバイダー側の [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls] とは別です。`parallel_tool_calls` は、モデルが 1 つの応答で複数のツール呼び出しを発行できるかどうかを制御します。`tool_execution.max_function_tool_concurrency` は、モデルがそれらを発行した後に SDK がローカル関数ツール呼び出しをどのように実行するかを制御します。 +これはプロバイダー側の [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls] とは別です。`parallel_tool_calls` は、モデルが 1 つのレスポンスで複数のツール呼び出しを出力してよいかどうかを制御します。`tool_execution.max_function_tool_concurrency` は、モデルが出力した後に SDK がローカル関数ツール呼び出しをどのように実行するかを制御します。 ##### `tool_error_formatter` 承認フローでツール呼び出しが拒否されたときにモデルへ返されるメッセージをカスタマイズするには、`tool_error_formatter` を使用します。 -formatter は、次を含む [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs] を受け取ります。 +formatter は [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs] を受け取り、内容は次のとおりです。 -- `kind`: エラーカテゴリーです。現在これは `"approval_rejected"` です。 +- `kind`: エラーカテゴリーです。現時点では `"approval_rejected"` です。 - `tool_type`: ツールランタイム（`"function"`、`"computer"`、`"shell"`、`"apply_patch"`、または `"custom"`）です。 - `tool_name`: ツール名です。 - `call_id`: ツール呼び出し ID です。 -- `default_message`: SDK のデフォルトの、モデルに表示されるメッセージです。 -- `run_context`: アクティブな実行コンテキストラッパーです。 +- `default_message`: SDK のデフォルトの、モデルに見えるメッセージです。 +- `run_context`: アクティブな実行コンテキスト wrapper です。 メッセージを置き換えるには文字列を返し、SDK のデフォルトを使用するには `None` を返します。 @@ -225,56 +225,56 @@ result = Runner.run_sync( ##### `reasoning_item_id_policy` -`reasoning_item_id_policy` は、runner が履歴を引き継ぐとき（たとえば `RunResult.to_input_list()` やセッションに基づく実行を使用する場合）に、reasoning item を次ターンのモデル入力へ変換する方法を制御します。 +`reasoning_item_id_policy` は、runner が履歴を次へ引き継ぐとき（たとえば `RunResult.to_input_list()` やセッションに基づく実行を使用する場合）に、reasoning item を次ターンのモデル入力へどのように変換するかを制御します。 - `None` または `"preserve"`（デフォルト）: reasoning item ID を保持します。 - `"omit"`: 生成される次ターン入力から reasoning item ID を取り除きます。 -`"omit"` は主に、reasoning item が `id` 付きで送信される一方で、必要な後続項目がない場合に発生する Responses API 400 エラーの一種（例: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）に対する opt-in の緩和策として使用します。 +`"omit"` は主に、reasoning item が `id` とともに送信されているものの、必須の後続アイテムがない場合（たとえば `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）に発生する Responses API 400 エラーのクラスに対する opt-in 緩和策として使用します。 -これは、SDK が以前の出力からフォローアップ入力を構築するマルチターンのエージェント実行（セッション永続化、サーバー管理の会話差分、ストリーミング/非ストリーミングのフォローアップターン、再開パスを含む）で、reasoning item ID が保持される一方、プロバイダーがその ID を対応する後続項目とペアのままにすることを要求する場合に発生する可能性があります。 +これは、SDK が以前の出力から follow-up 入力を構築する複数ターンのエージェント実行（セッション永続化、サーバー管理の会話差分、ストリーミング / 非ストリーミングの follow-up ターン、resume paths を含む）で、reasoning item ID が保持されている一方、プロバイダーがその ID を対応する後続アイテムとペアのままにすることを要求する場合に発生することがあります。 -`reasoning_item_id_policy="omit"` を設定すると、reasoning content は保持しつつ reasoning item の `id` を取り除くため、SDK が生成するフォローアップ入力でその API invariant がトリガーされるのを避けられます。 +`reasoning_item_id_policy="omit"` を設定すると、reasoning content は保持しつつ reasoning item の `id` を取り除くため、SDK が生成する follow-up 入力でその API invariant をトリガーするのを回避できます。 -スコープに関する注記: +スコープに関する注意: -- これは、SDK がフォローアップ入力を構築する際に SDK によって生成/転送される reasoning item のみを変更します。 -- ユーザーが指定した初期入力項目は書き換えません。 -- `call_model_input_filter` は、このポリシー適用後でも意図的に reasoning ID を再導入できます。 +- これは、SDK が follow-up 入力を構築するときに SDK によって生成 / 転送される reasoning items のみを変更します。 +- ユーザーが提供した初期入力アイテムは書き換えません。 +- `call_model_input_filter` は、このポリシー適用後でも意図的に reasoning IDs を再導入できます。 ## 状態と会話管理 -### メモリ戦略の選択 +### メモリー戦略の選択 -次のターンに状態を引き継ぐ一般的な方法は 4 つあります。 +状態を次のターンへ引き継ぐ一般的な方法は 4 つあります。 -| 戦略 | 状態の保存場所 | 最適な用途 | 次のターンで渡すもの | +| 戦略 | 状態の所在 | 最適な用途 | 次のターンで渡すもの | | --- | --- | --- | --- | -| `result.to_input_list()` | アプリのメモリ | 小規模なチャットループ、完全な手動制御、任意のプロバイダー | `result.to_input_list()` からのリストに次のユーザーメッセージを加えたもの | -| `session` | 自分のストレージと SDK | 永続的なチャット状態、再開可能な実行、カスタムストア | 同じ `session` インスタンス、または同じストアを指す別のインスタンス | -| `conversation_id` | OpenAI Conversations API | ワーカーやサービス間で共有したい、名前付きのサーバー側会話 | 同じ `conversation_id` と新しいユーザーターンのみ | -| `previous_response_id` | OpenAI Responses API | 会話リソースを作成しない軽量なサーバー管理の継続 | `result.last_response_id` と新しいユーザーターンのみ | +| `result.to_input_list()` | アプリのメモリー | 小規模なチャットループ、完全な手動制御、任意のプロバイダー | `result.to_input_list()` からのリストと次のユーザーメッセージ | +| `session` | ストレージと SDK | 永続的なチャット状態、再開可能な実行、カスタムストア | 同じ `session` インスタンス、または同じストアを指す別のインスタンス | +| `conversation_id` | OpenAI Conversations API | ワーカーやサービス間で共有したい名前付きのサーバー側会話 | 同じ `conversation_id` と新しいユーザーターンのみ | +| `previous_response_id` | OpenAI Responses API | 会話リソースを作成せずに行う軽量なサーバー管理の継続 | `result.last_response_id` と新しいユーザーターンのみ | -`result.to_input_list()` と `session` はクライアント管理です。`conversation_id` と `previous_response_id` は OpenAI 管理であり、OpenAI Responses API を使用している場合にのみ適用されます。ほとんどのアプリケーションでは、会話ごとに 1 つの永続化戦略を選んでください。クライアント管理の履歴と OpenAI 管理の状態を混在させると、両方のレイヤーを意図的に調整している場合を除き、コンテキストが重複する可能性があります。 +`result.to_input_list()` と `session` はクライアント管理です。`conversation_id` と `previous_response_id` は OpenAI 管理であり、OpenAI Responses API を使用している場合にのみ適用されます。ほとんどのアプリケーションでは、会話ごとに 1 つの永続化戦略を選択します。両方のレイヤーを意図的に照合しているのでない限り、クライアント管理の履歴と OpenAI 管理の状態を混在させると、コンテキストが重複する可能性があります。 !!! note セッション永続化は、サーバー管理の会話設定 - （`conversation_id`、`previous_response_id`、または `auto_previous_response_id`）と同じ実行内で組み合わせることはできません。 - 呼び出しごとに 1 つのアプローチを選択してください。 + （`conversation_id`、`previous_response_id`、または `auto_previous_response_id`）と + 同じ実行内で組み合わせることはできません。呼び出しごとに 1 つのアプローチを選択してください。 ### 会話 / チャットスレッド -いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行される（したがって 1 回以上の LLM 呼び出しが行われる）可能性がありますが、これはチャット会話における 1 つの論理的なターンを表します。たとえば次のようになります。 +いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行される（したがって 1 回以上の LLM 呼び出しが行われる）可能性がありますが、チャット会話における単一の論理ターンを表します。例: 1. ユーザーターン: ユーザーがテキストを入力します -2. Runner 実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフし、2 番目のエージェントがさらにツールを実行してから、出力を生成します。 +2. Runner run: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフし、2 番目のエージェントがさらにツールを実行してから出力を生成します。 -エージェント実行の最後に、ユーザーに何を表示するかを選択できます。たとえば、エージェントによって生成されたすべての新しい項目をユーザーに表示することも、最終出力だけを表示することもできます。いずれの場合でも、その後ユーザーがフォローアップの質問をする可能性があり、その場合は run メソッドを再度呼び出せます。 +エージェントの実行の最後に、ユーザーに何を表示するかを選択できます。たとえば、エージェントによって生成されたすべての新しいアイテムをユーザーに表示することも、最終出力だけを表示することもできます。いずれの場合も、ユーザーが続けて質問することがあり、その場合は run メソッドを再度呼び出せます。 #### 手動での会話管理 -次のターンの入力を取得するには、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って会話履歴を手動で管理できます。 +[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して次のターンの入力を取得することで、会話履歴を手動で管理できます。 ```python async def main(): @@ -296,7 +296,7 @@ async def main(): #### セッションによる自動会話管理 -より簡単なアプローチとして、[Sessions](sessions/index.md) を使用すると、`.to_input_list()` を手動で呼び出さずに会話履歴を自動で処理できます。 +よりシンプルな方法として、[Sessions](sessions/index.md) を使用すると、`.to_input_list()` を手動で呼び出さずに会話履歴を自動的に処理できます。 ```python from agents import Agent, Runner, SQLiteSession @@ -324,14 +324,14 @@ Sessions は自動的に次を行います。 - 各実行の前に会話履歴を取得します - 各実行の後に新しいメッセージを保存します -- 異なる session ID ごとに別々の会話を維持します +- 異なるセッション ID ごとに別々の会話を維持します -詳細については [Sessions ドキュメント](sessions/index.md) を参照してください。 +詳細については、[Sessions ドキュメント](sessions/index.md) を参照してください。 #### サーバー管理の会話 -`to_input_list()` や `Sessions` でローカルに処理する代わりに、OpenAI の会話状態機能にサーバー側で会話状態を管理させることもできます。これにより、過去のメッセージをすべて手動で再送せずに会話履歴を保持できます。以下のどちらのサーバー管理アプローチでも、各リクエストでは新しいターンの入力のみを渡し、保存された ID を再利用してください。詳細については [OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 +`to_input_list()` や `Sessions` でローカルに処理する代わりに、OpenAI の会話状態機能にサーバー側で会話状態を管理させることもできます。これにより、過去のすべてのメッセージを手動で再送信することなく、会話履歴を保持できます。以下のいずれのサーバー管理アプローチでも、各リクエストでは新しいターンの入力のみを渡し、保存された ID を再利用します。詳細については、[OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 OpenAI はターン間で状態を追跡する 2 つの方法を提供しています。 @@ -360,7 +360,7 @@ async def main(): ##### 2. `previous_response_id` の使用 -もう 1 つの選択肢は **レスポンスチェイニング** で、各ターンを前のターンのレスポンス ID に明示的にリンクします。 +もう 1 つの選択肢は **response chaining** で、各ターンが前のターンの response ID に明示的にリンクされます。 ```python from agents import Agent, Runner @@ -387,29 +387,29 @@ async def main(): 実行が承認のために一時停止し、[`RunState`][agents.run_state.RunState] から再開する場合、 SDK は保存された `conversation_id` / `previous_response_id` / `auto_previous_response_id` -設定を保持するため、再開されたターンは同じサーバー管理の会話内で継続します。 +設定を保持するため、再開されたターンは同じサーバー管理の会話で継続します。 -`conversation_id` と `previous_response_id` は相互に排他的です。システム間で共有できる名前付きの会話リソースが必要な場合は `conversation_id` を使用します。1 ターンから次のターンへ最も軽量な Responses API の継続用 basic component が必要な場合は `previous_response_id` を使用します。 +`conversation_id` と `previous_response_id` は相互に排他的です。システム間で共有できる名前付きの会話リソースが必要な場合は `conversation_id` を使用します。あるターンから次のターンへ最も軽量な Responses API の継続プリミティブが必要な場合は `previous_response_id` を使用します。 !!! note - SDK は `conversation_locked` エラーを backoff 付きで自動的に再試行します。サーバー管理の - 会話実行では、再試行前に内部の conversation-tracker 入力を巻き戻し、 - 同じ準備済み項目をクリーンに再送できるようにします。 + SDK は `conversation_locked` エラーを backoff 付きで自動的に retry します。サーバー管理の + 会話実行では、同じ準備済みアイテムをきれいに再送できるように、retry 前に内部の conversation-tracker 入力を巻き戻します。 - ローカルのセッションベース実行（`conversation_id`、 - `previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません）では、SDK は再試行後の重複した履歴項目を減らすために、最近永続化された入力項目の best-effort + ローカルセッションベースの実行（`conversation_id`、 + `previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません）では、SDK は retry 後の重複した履歴エントリーを減らすため、 + 最近永続化された入力アイテムの best-effort rollback も実行します。 - この互換性再試行は、`ModelSettings.retry` を設定していない場合でも発生します。モデルリクエストに対するより広範な opt-in retry の挙動については、[Runner 管理の再試行](models/index.md#runner-managed-retries) を参照してください。 + この互換性 retry は、`ModelSettings.retry` を構成していない場合でも発生します。モデルリクエストに対する、より広範な opt-in retry 動作については、[Runner 管理の retry](models/index.md#runner-managed-retries) を参照してください。 ## フックとカスタマイズ -### モデル入力フィルターの呼び出し +### モデル呼び出し入力フィルター -モデル呼び出しの直前にモデル入力を編集するには、`call_model_input_filter` を使用します。このフックは現在のエージェント、コンテキスト、および結合された入力項目（存在する場合はセッション履歴を含む）を受け取り、新しい `ModelInputData` を返します。 +モデル呼び出しの直前にモデル入力を編集するには、`call_model_input_filter` を使用します。この hook は、現在のエージェント、context、および結合された入力アイテム（存在する場合はセッション履歴を含む）を受け取り、新しい `ModelInputData` を返します。 -戻り値は [`ModelInputData`][agents.run.ModelInputData] オブジェクトである必要があります。その `input` フィールドは必須で、入力項目のリストである必要があります。それ以外の形状を返すと `UserError` が発生します。 +戻り値は [`ModelInputData`][agents.run.ModelInputData] オブジェクトである必要があります。その `input` フィールドは必須で、入力アイテムのリストでなければなりません。それ以外の形を返すと `UserError` が発生します。 ```python from agents import Agent, Runner, RunConfig @@ -428,19 +428,19 @@ result = Runner.run_sync( ) ``` -runner は準備済み入力リストのコピーをフックに渡すため、呼び出し元の元のリストをその場で変更せずに、トリム、置換、または並べ替えることができます。 +runner は準備済み入力リストのコピーを hook に渡すため、呼び出し元の元のリストをその場で変更せずに、trim、置換、並べ替えができます。 -セッションを使用している場合、`call_model_input_filter` はセッション履歴がすでに読み込まれ、現在のターンとマージされた後に実行されます。その前のマージ手順自体をカスタマイズしたい場合は、[`session_input_callback`][agents.run.RunConfig.session_input_callback] を使用してください。 +セッションを使用している場合、`call_model_input_filter` はセッション履歴がすでにロードされ、現在のターンとマージされた後に実行されます。その前のマージ手順自体をカスタマイズしたい場合は、[`session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。 -`conversation_id`、`previous_response_id`、または `auto_previous_response_id` を使用する OpenAI サーバー管理の会話状態を使用している場合、このフックは次の Responses API 呼び出し用に準備されたペイロードに対して実行されます。そのペイロードは、以前の履歴の完全な再生ではなく、新しいターンの差分のみをすでに表している場合があります。返した項目のみが、そのサーバー管理の継続に対して送信済みとしてマークされます。 +`conversation_id`、`previous_response_id`、または `auto_previous_response_id` を使用した OpenAI サーバー管理の会話状態を使用している場合、hook は次の Responses API 呼び出しのために準備された payload に対して実行されます。その payload は、以前の履歴全体の再生ではなく、すでに新しいターンの差分のみを表している場合があります。返したアイテムだけが、そのサーバー管理の継続に対して送信済みとしてマークされます。 -機密データを編集したり、長い履歴をトリムしたり、追加のシステムガイダンスを注入したりするには、`run_config` を通じて実行ごとにフックを設定してください。 +機密データを redact したり、長い履歴を trim したり、追加のシステムガイダンスを注入したりするには、`run_config` 経由で実行ごとに hook を設定します。 ## エラーと復旧 ### エラーハンドラー -すべての `Runner` エントリーポイントは、エラー種別をキーとする dict である `error_handlers` を受け入れます。サポートされるキーは `"max_turns"` と `"model_refusal"` です。`MaxTurnsExceeded` または `ModelRefusalError` を発生させる代わりに、制御された最終出力を返したい場合に使用します。 +すべての `Runner` エントリーポイントは `error_handlers` を受け入れます。これはエラー種別をキーとする dict です。サポートされるキーは `"max_turns"` と `"model_refusal"` です。`MaxTurnsExceeded` または `ModelRefusalError` を発生させる代わりに、制御された最終出力を返したい場合に使用します。 ```python from agents import ( @@ -469,9 +469,9 @@ result = Runner.run_sync( print(result.final_output) ``` -フォールバック出力を会話履歴に追加したくない場合は、`include_in_history=False` を設定してください。 +fallback 出力を会話履歴に追加したくない場合は、`include_in_history=False` を設定します。 -モデルの拒否により `ModelRefusalError` で実行を終了する代わりに、アプリケーション固有のフォールバックを生成したい場合は `"model_refusal"` を使用します。 +モデル拒否で `ModelRefusalError` により実行を終了する代わりに、アプリケーション固有の fallback を生成したい場合は `"model_refusal"` を使用します。 ```python from pydantic import BaseModel @@ -503,33 +503,37 @@ result = Runner.run_sync( print(result.final_output) ``` -## 永続的実行インテグレーションと human-in-the-loop +## Durable execution 統合と human-in-the-loop -ツール承認の一時停止/再開パターンについては、専用の [Human-in-the-loop ガイド](human_in_the_loop.md) から始めてください。 -以下のインテグレーションは、実行が長い待機、再試行、またはプロセス再起動にまたがる可能性がある場合の永続的なオーケストレーション向けです。 +ツール承認の pause/resume パターンについては、専用の [Human-in-the-loop ガイド](human_in_the_loop.md) から始めてください。 +以下の統合は、実行が長い待機、retry、またはプロセス再起動にまたがる可能性がある場合の durable orchestration のためのものです。 + +### Dapr + +Agents SDK の [Dapr](https://dapr.io) Diagrid 統合を使用して、人間参加型のサポートにより障害から自動的に復旧する、durable で長時間実行されるエージェントを実行できます。Dapr はベンダー中立の [CNCF](https://cncf.io) workflow orchestrator です。Dapr と OpenAI エージェントの開始方法は [こちら](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai) です。 ### Temporal -Agents SDK の [Temporal](https://temporal.io/) インテグレーションを使用すると、human-in-the-loop タスクを含む、耐久性のある長時間実行ワークフローを実行できます。長時間実行タスクを完了するために Temporal と Agents SDK が連携して動作するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) で確認でき、[ドキュメントはこちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) で参照できます。 +Agents SDK の [Temporal](https://temporal.io/) 統合を使用して、人間参加型タスクを含む durable で長時間実行される workflow を実行できます。長時間実行タスクを完了するために Temporal と Agents SDK が実際に連携するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) で確認でき、[ドキュメントはこちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) です。 ### Restate -Agents SDK の [Restate](https://restate.dev/) インテグレーションは、人による承認、ハンドオフ、セッション管理を含む軽量で耐久性のあるエージェントに使用できます。このインテグレーションは Restate の single-binary ランタイムを依存関係として必要とし、エージェントをプロセス/コンテナまたはサーバーレス関数として実行することをサポートします。 -詳細については [概要](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk) を読むか、[ドキュメント](https://docs.restate.dev/ai) を参照してください。 +Agents SDK の [Restate](https://restate.dev/) 統合を使用して、人間の承認、ハンドオフ、セッション管理を含む軽量で durable なエージェントを利用できます。この統合は依存関係として Restate の single-binary runtime を必要とし、エージェントをプロセス / コンテナーまたはサーバーレス関数として実行することをサポートします。 +詳細については、[概要](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk) を読むか、[ドキュメント](https://docs.restate.dev/ai) を参照してください。 ### DBOS -Agents SDK の [DBOS](https://dbos.dev/) インテグレーションを使用すると、障害や再起動をまたいで進捗を保持する信頼性の高いエージェントを実行できます。長時間実行エージェント、human-in-the-loop ワークフロー、ハンドオフをサポートします。sync メソッドと async メソッドの両方をサポートしています。このインテグレーションに必要なのは SQLite または Postgres データベースのみです。詳細については、インテグレーション [リポジトリ](https://github.com/dbos-inc/dbos-openai-agents) と [ドキュメント](https://docs.dbos.dev/integrations/openai-agents) を参照してください。 +Agents SDK の [DBOS](https://dbos.dev/) 統合を使用して、障害や再起動をまたいで進行状況を保持する信頼性の高いエージェントを実行できます。長時間実行エージェント、人間参加型 workflow、ハンドオフをサポートします。sync と async の両方のメソッドをサポートします。この統合に必要なのは SQLite または Postgres データベースだけです。詳細については、統合 [repo](https://github.com/dbos-inc/dbos-openai-agents) と [ドキュメント](https://docs.dbos.dev/integrations/openai-agents) を参照してください。 ## 例外 -SDK は特定の場合に例外を発生させます。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです。 +SDK は特定の場合に例外を発生させます。完全なリストは [`agents.exceptions`][] にあります。概要は次のとおりです。 -- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で発生するすべての例外の基底クラスです。他のすべての具体的な例外が派生する汎用型として機能します。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: この例外は、エージェントの実行が `Runner.run`、`Runner.run_sync`、または `Runner.run_streamed` メソッドに渡された `max_turns` 制限を超えた場合に発生します。指定された対話ターン数内にエージェントがタスクを完了できなかったことを示します。制限を無効にするには `max_turns=None` を設定してください。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: この例外は、基盤となるモデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。これには次のものが含まれる場合があります。 +- [`AgentsException`][agents.exceptions.AgentsException]: これは SDK 内で発生するすべての例外の基底クラスです。他のすべての具体的な例外が派生する汎用型として機能します。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: この例外は、エージェントの実行が `Runner.run`、`Runner.run_sync`、または `Runner.run_streamed` メソッドに渡された `max_turns` 制限を超えたときに発生します。指定された対話ターン数内でエージェントがタスクを完了できなかったことを示します。制限を無効にするには `max_turns=None` を設定します。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: この例外は、基盤となるモデル（LLM）が予期しない、または無効な出力を生成したときに発生します。これには次が含まれます。 - 不正な JSON: モデルがツール呼び出し用、または直接出力内で不正な JSON 構造を提供した場合。特に特定の `output_type` が定義されている場合です。 - - 予期しないツール関連の失敗: モデルが期待どおりにツールを使用できなかった場合 -- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: この例外は、関数ツール呼び出しが構成されたタイムアウトを超え、そのツールが `timeout_behavior="raise_exception"` を使用している場合に発生します。 -- [`UserError`][agents.exceptions.UserError]: この例外は、SDK を使用してコードを書いているあなたが、SDK の使用中にエラーを起こした場合に発生します。通常、誤ったコード実装、無効な設定、または SDK の API の誤用に起因します。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered]、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: この例外は、入力ガードレールまたは出力ガードレールの条件がそれぞれ満たされた場合に発生します。入力ガードレールは処理前に受信メッセージを確認し、出力ガードレールは配信前にエージェントの最終応答を確認します。 \ No newline at end of file + - 予期しないツール関連の失敗: モデルが期待される方法でツールを使用できなかった場合 +- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: この例外は、関数ツール呼び出しが構成された timeout を超え、そのツールが `timeout_behavior="raise_exception"` を使用している場合に発生します。 +- [`UserError`][agents.exceptions.UserError]: この例外は、あなた（SDK を使用してコードを書く人）が SDK の使用中にエラーを起こした場合に発生します。これは通常、不正なコード実装、無効な設定、または SDK API の誤用によって発生します。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: この例外は、入力ガードレールまたは出力ガードレールの条件がそれぞれ満たされた場合に発生します。入力ガードレールは処理前に受信メッセージをチェックし、出力ガードレールは配信前にエージェントの最終応答をチェックします。 \ No newline at end of file diff --git a/docs/ko/running_agents.md b/docs/ko/running_agents.md index f88eb026dc..ad2ec20a97 100644 --- a/docs/ko/running_agents.md +++ b/docs/ko/running_agents.md @@ -8,7 +8,7 @@ search: 1. [`Runner.run()`][agents.run.Runner.run]: 비동기로 실행되며 [`RunResult`][agents.result.RunResult]를 반환합니다. 2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 동기 메서드이며 내부적으로 `.run()`을 실행합니다. -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 비동기로 실행되며 [`RunResultStreaming`][agents.result.RunResultStreaming]을 반환합니다. 스트리밍 모드로 LLM을 호출하고, 수신되는 이벤트를 스트리밍합니다. +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 비동기로 실행되며 [`RunResultStreaming`][agents.result.RunResultStreaming]을 반환합니다. 스트리밍 모드로 LLM을 호출하고, 이벤트가 수신되는 대로 스트리밍합니다. ```python from agents import Agent, Runner @@ -23,21 +23,21 @@ async def main(): # Infinite loop's dance ``` -자세한 내용은 [결과 가이드](results.md)를 참조하세요. +자세한 내용은 [결과 가이드](results.md)를 읽어보세요. ## Runner 수명 주기 및 구성 ### 에이전트 루프 -`Runner`에서 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 다음 중 하나일 수 있습니다. +`Runner`의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 다음 중 하나일 수 있습니다. - 문자열(사용자 메시지로 처리됨) - OpenAI Responses API 형식의 입력 항목 목록 - 중단된 실행을 재개할 때의 [`RunState`][agents.run_state.RunState] -그런 다음 runner가 루프를 실행합니다. +그러면 runner가 루프를 실행합니다. -1. 현재 에이전트에 대해 현재 입력으로 LLM을 호출합니다. +1. 현재 입력으로 현재 에이전트에 대해 LLM을 호출합니다. 2. LLM이 출력을 생성합니다. 1. LLM이 `final_output`을 반환하면 루프가 종료되고 결과를 반환합니다. 2. LLM이 핸드오프를 수행하면 현재 에이전트와 입력을 업데이트하고 루프를 다시 실행합니다. @@ -46,23 +46,23 @@ async def main(): !!! note - LLM 출력이 "최종 출력"으로 간주되는 규칙은 원하는 타입의 텍스트 출력을 생성하고 도구 호출이 없다는 것입니다. + LLM 출력이 "최종 출력"으로 간주되는 규칙은, 원하는 타입의 텍스트 출력을 생성하고 도구 호출이 없는 경우입니다. ### 스트리밍 -스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트를 추가로 받을 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming]에는 생성된 모든 새 출력을 포함하여 실행에 대한 전체 정보가 포함됩니다. 스트리밍 이벤트를 받으려면 `.stream_events()`를 호출할 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참조하세요. +스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트를 추가로 받을 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming]에는 생성된 모든 새 출력을 포함해 실행에 대한 전체 정보가 포함됩니다. 스트리밍 이벤트는 `.stream_events()`를 호출해 받을 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 읽어보세요. #### Responses WebSocket 전송(선택적 헬퍼) -OpenAI Responses websocket 전송을 활성화하면 일반 `Runner` API를 계속 사용할 수 있습니다. 연결 재사용을 위해 websocket 세션 헬퍼를 권장하지만 필수는 아닙니다. +OpenAI Responses websocket 전송을 활성화하면 일반 `Runner` API를 계속 사용할 수 있습니다. 연결 재사용을 위해 websocket 세션 헬퍼가 권장되지만 필수는 아닙니다. -이는 [Realtime API](realtime/guide.md)가 아니라 websocket 전송을 통한 Responses API입니다. +이는 websocket 전송을 통한 Responses API이며, [Realtime API](realtime/guide.md)가 아닙니다. 전송 선택 규칙과 구체적인 모델 객체 또는 사용자 지정 제공자 관련 주의 사항은 [모델](models/index.md#responses-websocket-transport)을 참조하세요. -##### 패턴 1: 세션 헬퍼 없음(작동) +##### 패턴 1: 세션 헬퍼 없음(동작함) -websocket 전송만 필요하고 SDK가 공유 제공자/세션을 관리할 필요가 없을 때 사용하세요. +websocket 전송만 원하고 SDK가 공유 제공자/세션을 관리할 필요가 없을 때 사용하세요. ```python import asyncio @@ -85,11 +85,11 @@ async def main(): asyncio.run(main()) ``` -이 패턴은 단일 실행에 적합합니다. `Runner.run()` / `Runner.run_streamed()`를 반복해서 호출하면 동일한 `RunConfig` / 제공자 인스턴스를 수동으로 재사용하지 않는 한 각 실행이 다시 연결될 수 있습니다. +이 패턴은 단일 실행에는 적합합니다. `Runner.run()` / `Runner.run_streamed()`를 반복해서 호출하면 동일한 `RunConfig` / 제공자 인스턴스를 수동으로 재사용하지 않는 한 각 실행이 다시 연결될 수 있습니다. -##### 패턴 2: `responses_websocket_session()` 사용(다중 턴 재사용 권장) +##### 패턴 2: `responses_websocket_session()` 사용(다중 턴 재사용에 권장) -여러 실행(동일한 `run_config`를 상속하는 중첩 agent-as-tool 호출 포함)에서 공유 websocket 지원 제공자와 `RunConfig`를 원할 때 [`responses_websocket_session()`][agents.responses_websocket_session]을 사용하세요. +여러 실행에서(동일한 `run_config`를 상속하는 중첩 agent-as-tool 호출 포함) 공유 websocket 지원 제공자와 `RunConfig`를 사용하려면 [`responses_websocket_session()`][agents.responses_websocket_session]을 사용하세요. ```python import asyncio @@ -119,32 +119,32 @@ async def main(): asyncio.run(main()) ``` -컨텍스트가 종료되기 전에 스트리밍된 결과 소비를 완료하세요. websocket 요청이 아직 진행 중일 때 컨텍스트를 종료하면 공유 연결이 강제로 닫힐 수 있습니다. +컨텍스트가 종료되기 전에 스트리밍 결과 소비를 마치세요. websocket 요청이 아직 진행 중일 때 컨텍스트를 종료하면 공유 연결이 강제로 닫힐 수 있습니다. -긴 추론 턴이 websocket keepalive 타임아웃에 도달하면 `ping_timeout`을 늘리거나 `ping_timeout=None`으로 설정해 heartbeat 타임아웃을 비활성화하세요. websocket 지연 시간보다 안정성이 더 중요한 실행에는 HTTP/SSE 전송을 사용하세요. +긴 추론 턴에서 websocket keepalive 타임아웃이 발생하면 `ping_timeout`을 늘리거나 `ping_timeout=None`으로 설정해 heartbeat 타임아웃을 비활성화하세요. 신뢰성이 websocket 지연 시간보다 중요한 실행에는 HTTP/SSE 전송을 사용하세요. -### 실행 구성 +### Run config `run_config` 매개변수를 사용하면 에이전트 실행에 대한 일부 전역 설정을 구성할 수 있습니다. -#### 일반적인 실행 구성 카테고리 +#### 일반적인 run config 카테고리 각 에이전트 정의를 변경하지 않고 단일 실행의 동작을 재정의하려면 `RunConfig`를 사용하세요. ##### 모델, 제공자 및 세션 기본값 - [`model`][agents.run.RunConfig.model]: 각 Agent가 가진 `model`과 관계없이 사용할 전역 LLM 모델을 설정할 수 있습니다. -- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름을 조회하기 위한 모델 제공자이며 기본값은 OpenAI입니다. +- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름 조회에 사용할 모델 제공자이며 기본값은 OpenAI입니다. - [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의합니다. 예를 들어 전역 `temperature` 또는 `top_p`를 설정할 수 있습니다. -- [`session_settings`][agents.run.RunConfig.session_settings]: 실행 중 기록을 검색할 때 세션 수준 기본값(예: `SessionSettings(limit=...)`)을 재정의합니다. +- [`session_settings`][agents.run.RunConfig.session_settings]: 실행 중 기록을 가져올 때 세션 수준 기본값(예: `SessionSettings(limit=...)`)을 재정의합니다. - [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions를 사용할 때 각 턴 전에 새 사용자 입력이 세션 기록과 병합되는 방식을 사용자 지정합니다. 콜백은 동기 또는 비동기일 수 있습니다. -##### 가드레일, 핸드오프 및 모델 입력 구성 +##### 가드레일, 핸드오프 및 모델 입력 형성 - [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력 또는 출력 가드레일 목록입니다. - [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 이미 필터가 없는 경우 모든 핸드오프에 적용할 전역 입력 필터입니다. 입력 필터를 사용하면 새 에이전트로 전송되는 입력을 편집할 수 있습니다. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참조하세요. -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 다음 에이전트를 호출하기 전에 이전 대화 내용을 단일 assistant 메시지로 축소하는 옵트인 베타입니다. 중첩 핸드오프를 안정화하는 동안 기본적으로 비활성화되어 있습니다. 활성화하려면 `True`로 설정하거나 원문 대화 내용을 그대로 전달하려면 `False`로 두세요. 모든 [Runner 메서드][agents.run.Runner]는 전달된 `RunConfig`가 없을 때 자동으로 `RunConfig`를 생성하므로 빠른 시작과 예제에서는 기본값이 꺼진 상태로 유지되며, 명시적인 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백은 계속 이를 재정의합니다. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 통해 이 설정을 재정의할 수 있습니다. -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history`를 옵트인할 때마다 정규화된 대화 내용(기록 + 핸드오프 항목)을 받는 선택적 callable입니다. 다음 에이전트로 전달할 정확한 입력 항목 목록을 반환해야 하며, 전체 핸드오프 필터를 작성하지 않고도 내장 요약을 대체할 수 있습니다. +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 다음 에이전트를 호출하기 전에 이전 대화 기록을 단일 assistant 메시지로 축약하는 옵트인 베타입니다. 중첩 핸드오프를 안정화하는 동안 기본적으로 비활성화되어 있습니다. 활성화하려면 `True`로 설정하고, 원문 대화 기록을 그대로 전달하려면 `False`로 둡니다. 모든 [Runner 메서드][agents.run.Runner]는 전달된 `RunConfig`가 없을 때 자동으로 `RunConfig`를 생성하므로, 빠른 시작과 예제는 기본적으로 꺼진 상태를 유지하며, 명시적인 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백은 계속 이를 재정의합니다. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 통해 이 설정을 재정의할 수 있습니다. +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history`에 옵트인할 때마다 정규화된 대화 기록(기록 + 핸드오프 항목)을 받는 선택적 callable입니다. 다음 에이전트로 전달할 정확한 입력 항목 목록을 반환해야 하며, 전체 핸드오프 필터를 작성하지 않고도 내장 요약을 대체할 수 있습니다. - [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: 모델 호출 직전에 완전히 준비된 모델 입력(instructions 및 입력 항목)을 편집하는 훅입니다. 예를 들어 기록을 줄이거나 시스템 프롬프트를 삽입할 수 있습니다. - [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner가 이전 출력을 다음 턴 모델 입력으로 변환할 때 reasoning 항목 ID를 보존할지 생략할지 제어합니다. @@ -152,22 +152,22 @@ asyncio.run(main()) - [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [트레이싱](tracing.md)을 비활성화할 수 있습니다. - [`tracing`][agents.run.RunConfig.tracing]: 실행별 트레이싱 API 키와 같은 trace 내보내기 설정을 재정의하려면 [`TracingConfig`][agents.tracing.TracingConfig]를 전달합니다. -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: trace에 LLM 및 도구 호출 입력/출력과 같은 잠재적으로 민감한 데이터가 포함될지 여부를 구성합니다. -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, trace ID 및 trace group ID를 설정합니다. 최소한 `workflow_name`은 설정하는 것을 권장합니다. group ID는 여러 실행에 걸쳐 trace를 연결할 수 있게 해주는 선택적 필드입니다. +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: trace에 LLM 및 도구 호출 입력/출력과 같이 잠재적으로 민감한 데이터를 포함할지 여부를 구성합니다. +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, trace ID 및 trace 그룹 ID를 설정합니다. 최소한 `workflow_name`은 설정하는 것을 권장합니다. 그룹 ID는 여러 실행 간 trace를 연결할 수 있는 선택적 필드입니다. - [`trace_metadata`][agents.run.RunConfig.trace_metadata]: 모든 trace에 포함할 메타데이터입니다. ##### 도구 실행, 승인 및 도구 오류 동작 -- [`tool_execution`][agents.run.RunConfig.tool_execution]: 한 번에 실행되는 함수 도구 수를 제한하는 등 로컬 도구 호출에 대한 SDK 측 실행 동작을 구성합니다. +- [`tool_execution`][agents.run.RunConfig.tool_execution]: 한 번에 실행되는 함수 도구 수 제한과 같이 로컬 도구 호출에 대한 SDK 측 실행 동작을 구성합니다. - [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 승인 흐름 중 도구 호출이 거부될 때 모델에 표시되는 메시지를 사용자 지정합니다. -중첩 핸드오프는 옵트인 베타로 제공됩니다. `RunConfig(nest_handoff_history=True)`를 전달하거나 특정 핸드오프에 대해 `handoff(..., nest_handoff_history=True)`를 설정해 축소된 대화 내용 동작을 활성화하세요. 원문 대화 내용(기본값)을 유지하려면 플래그를 설정하지 않거나 필요한 방식 그대로 대화를 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`)를 제공하세요. 사용자 지정 mapper를 작성하지 않고 생성된 요약에 사용되는 래퍼 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(기본값을 복원하려면 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]). +중첩 핸드오프는 옵트인 베타로 제공됩니다. 축약된 대화 기록 동작을 활성화하려면 `RunConfig(nest_handoff_history=True)`를 전달하거나 특정 핸드오프에 대해 `handoff(..., nest_handoff_history=True)`를 설정하세요. 원문 대화 기록을 유지하려는 경우(기본값), 플래그를 설정하지 않거나 필요한 방식 그대로 대화를 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`)를 제공하세요. 사용자 지정 mapper를 작성하지 않고 생성된 요약에 사용되는 래퍼 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(기본값으로 복원하려면 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]). -#### 실행 구성 세부 정보 +#### Run config 세부 정보 ##### `tool_execution` -SDK가 실행에 대해 로컬 함수 도구 동시성을 제한하도록 하려면 `tool_execution`을 사용하세요. +실행에 대해 SDK가 로컬 함수 도구 동시성을 제한하도록 하려면 `tool_execution`을 사용하세요. ```python from agents import Agent, RunConfig, Runner, ToolExecutionConfig @@ -183,9 +183,9 @@ result = await Runner.run( ) ``` -`max_function_tool_concurrency=None`은 기본 동작을 유지합니다. 모델이 한 턴에서 여러 함수 도구 호출을 내보내면 SDK는 내보낸 모든 로컬 함수 도구 호출을 시작합니다. 한 번에 실행되는 로컬 함수 도구 수를 제한하려면 정수 값을 설정하세요. +`max_function_tool_concurrency=None`은 기본 동작을 유지합니다. 모델이 한 턴에 여러 함수 도구 호출을 내보내면 SDK는 내보낸 모든 로컬 함수 도구 호출을 시작합니다. 동시에 실행되는 로컬 함수 도구 수를 제한하려면 정수 값을 설정하세요. -이는 제공자 측 [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls]와는 별개입니다. `parallel_tool_calls`는 모델이 단일 응답에서 여러 도구 호출을 내보낼 수 있는지 제어합니다. `tool_execution.max_function_tool_concurrency`는 모델이 도구 호출을 내보낸 후 SDK가 로컬 함수 도구 호출을 실행하는 방식을 제어합니다. +이는 제공자 측 [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls]와 별개입니다. `parallel_tool_calls`는 모델이 단일 응답에서 여러 도구 호출을 내보낼 수 있는지 여부를 제어합니다. `tool_execution.max_function_tool_concurrency`는 모델이 도구 호출을 내보낸 후 SDK가 로컬 함수 도구 호출을 실행하는 방식을 제어합니다. ##### `tool_error_formatter` @@ -193,7 +193,7 @@ result = await Runner.run( formatter는 다음을 포함하는 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]를 받습니다. -- `kind`: 오류 카테고리입니다. 현재는 `"approval_rejected"`입니다. +- `kind`: 오류 카테고리입니다. 현재 이는 `"approval_rejected"`입니다. - `tool_type`: 도구 런타임입니다(`"function"`, `"computer"`, `"shell"`, `"apply_patch"` 또는 `"custom"`). - `tool_name`: 도구 이름입니다. - `call_id`: 도구 호출 ID입니다. @@ -225,22 +225,22 @@ result = Runner.run_sync( ##### `reasoning_item_id_policy` -`reasoning_item_id_policy`는 runner가 기록을 앞으로 전달할 때(예: `RunResult.to_input_list()` 또는 세션 기반 실행을 사용할 때) reasoning 항목이 다음 턴 모델 입력으로 변환되는 방식을 제어합니다. +`reasoning_item_id_policy`는 runner가 기록을 다음으로 전달할 때(예: `RunResult.to_input_list()` 또는 세션 기반 실행 사용 시) reasoning 항목이 다음 턴 모델 입력으로 변환되는 방식을 제어합니다. - `None` 또는 `"preserve"`(기본값): reasoning 항목 ID를 유지합니다. - `"omit"`: 생성된 다음 턴 입력에서 reasoning 항목 ID를 제거합니다. -`"omit"`은 주로 reasoning 항목이 `id`와 함께 전송되었지만 필요한 다음 항목 없이 전송되는 Responses API 400 오류 유형에 대한 옵트인 완화책으로 사용하세요(예: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`). +`"omit"`는 주로 reasoning 항목이 `id`와 함께 전송되었지만 필수 후속 항목이 없는 경우 발생하는 Responses API 400 오류 범주에 대한 옵트인 완화책으로 사용하세요(예: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`). -이는 SDK가 이전 출력에서 후속 입력을 구성할 때(세션 지속성, 서버 관리 대화 델타, 스트리밍/비스트리밍 후속 턴, 재개 경로 포함) reasoning 항목 ID가 보존되지만 제공자가 해당 ID가 대응되는 다음 항목과 함께 유지되도록 요구하는 경우 다중 턴 에이전트 실행에서 발생할 수 있습니다. +이는 SDK가 이전 출력에서 후속 입력을 구성하는 다중 턴 에이전트 실행에서 발생할 수 있습니다(세션 지속성, 서버 관리 대화 델타, 스트리밍/비스트리밍 후속 턴, 재개 경로 포함). 이때 reasoning 항목 ID는 보존되지만 제공자는 해당 ID가 대응되는 후속 항목과 계속 짝을 이루도록 요구합니다. -`reasoning_item_id_policy="omit"`을 설정하면 reasoning 내용은 유지하되 reasoning 항목 `id`를 제거하므로 SDK가 생성한 후속 입력에서 해당 API 불변 조건이 트리거되는 것을 피할 수 있습니다. +`reasoning_item_id_policy="omit"`를 설정하면 reasoning 내용은 유지하되 reasoning 항목 `id`를 제거하여, SDK가 생성한 후속 입력에서 해당 API 불변 조건이 트리거되는 것을 방지합니다. 범위 참고 사항: -- 이는 SDK가 후속 입력을 빌드할 때 SDK가 생성/전달한 reasoning 항목만 변경합니다. +- 이는 SDK가 후속 입력을 빌드할 때 생성/전달하는 reasoning 항목만 변경합니다. - 사용자가 제공한 초기 입력 항목은 다시 작성하지 않습니다. -- 이 정책이 적용된 후에도 `call_model_input_filter`는 의도적으로 reasoning ID를 다시 도입할 수 있습니다. +- `call_model_input_filter`는 이 정책이 적용된 후에도 의도적으로 reasoning ID를 다시 도입할 수 있습니다. ## 상태 및 대화 관리 @@ -248,33 +248,33 @@ result = Runner.run_sync( 다음 턴으로 상태를 전달하는 일반적인 방법은 네 가지입니다. -| 전략 | 상태가 위치하는 곳 | 적합한 경우 | 다음 턴에 전달하는 것 | +| 전략 | 상태가 있는 위치 | 적합한 용도 | 다음 턴에 전달하는 내용 | | --- | --- | --- | --- | | `result.to_input_list()` | 앱 메모리 | 작은 채팅 루프, 완전한 수동 제어, 모든 제공자 | `result.to_input_list()`의 목록과 다음 사용자 메시지 | -| `session` | 스토리지와 SDK | 지속적인 채팅 상태, 재개 가능한 실행, 사용자 지정 저장소 | 동일한 `session` 인스턴스 또는 같은 저장소를 가리키는 다른 인스턴스 | -| `conversation_id` | OpenAI Conversations API | 워커나 서비스 간에 공유하려는 이름 있는 서버 측 대화 | 동일한 `conversation_id`와 새 사용자 턴만 | -| `previous_response_id` | OpenAI Responses API | 대화 리소스를 만들지 않는 가벼운 서버 관리 연속 처리 | `result.last_response_id`와 새 사용자 턴만 | +| `session` | 사용자의 스토리지와 SDK | 지속형 채팅 상태, 재개 가능한 실행, 사용자 지정 저장소 | 동일한 `session` 인스턴스 또는 같은 저장소를 가리키는 다른 인스턴스 | +| `conversation_id` | OpenAI Conversations API | 작업자나 서비스 간 공유하려는 명명된 서버 측 대화 | 동일한 `conversation_id`와 새 사용자 턴만 | +| `previous_response_id` | OpenAI Responses API | 대화 리소스를 만들지 않는 경량 서버 관리형 이어가기 | `result.last_response_id`와 새 사용자 턴만 | -`result.to_input_list()`와 `session`은 클라이언트 관리 방식입니다. `conversation_id`와 `previous_response_id`는 OpenAI 관리 방식이며 OpenAI Responses API를 사용할 때만 적용됩니다. 대부분의 애플리케이션에서는 대화마다 하나의 지속성 전략을 선택하세요. 두 계층을 의도적으로 조정하지 않는 한 클라이언트 관리 기록과 OpenAI 관리 상태를 혼합하면 컨텍스트가 중복될 수 있습니다. +`result.to_input_list()`와 `session`은 클라이언트 관리형입니다. `conversation_id`와 `previous_response_id`는 OpenAI 관리형이며 OpenAI Responses API를 사용할 때만 적용됩니다. 대부분의 애플리케이션에서는 대화당 하나의 지속성 전략을 선택하세요. 두 계층을 의도적으로 조정하지 않는 한 클라이언트 관리 기록과 OpenAI 관리 상태를 혼합하면 컨텍스트가 중복될 수 있습니다. !!! note - 세션 지속성은 같은 실행에서 서버 관리 대화 설정 - (`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`)과 - 결합할 수 없습니다. 호출마다 하나의 접근 방식을 선택하세요. + 세션 지속성은 동일한 실행에서 서버 관리 대화 설정 + (`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`)과 함께 사용할 수 없습니다. + 호출마다 하나의 접근 방식을 선택하세요. ### 대화/채팅 스레드 -run 메서드 중 하나를 호출하면 하나 이상의 에이전트가 실행될 수 있고(따라서 하나 이상의 LLM 호출이 발생할 수 있음), 채팅 대화에서는 단일 논리적 턴을 나타냅니다. 예를 들면 다음과 같습니다. +run 메서드 중 하나를 호출하면 하나 이상의 에이전트가 실행될 수 있고(따라서 하나 이상의 LLM 호출이 발생할 수 있음), 이는 채팅 대화에서 하나의 논리적 턴을 나타냅니다. 예를 들면 다음과 같습니다. -1. 사용자 턴: 사용자가 텍스트를 입력합니다. -2. Runner 실행: 첫 번째 에이전트가 LLM을 호출하고, 도구를 실행하고, 두 번째 에이전트로 핸드오프하며, 두 번째 에이전트가 더 많은 도구를 실행한 뒤 출력을 생성합니다. +1. 사용자 턴: 사용자가 텍스트 입력 +2. Runner 실행: 첫 번째 에이전트가 LLM을 호출하고 도구를 실행하며 두 번째 에이전트로 핸드오프하고, 두 번째 에이전트가 더 많은 도구를 실행한 뒤 출력을 생성합니다. -에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어 에이전트가 생성한 모든 새 항목을 사용자에게 보여주거나 최종 출력만 보여줄 수 있습니다. 어느 쪽이든 사용자가 후속 질문을 할 수 있으며, 이 경우 run 메서드를 다시 호출할 수 있습니다. +에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어 에이전트가 생성한 모든 새 항목을 사용자에게 보여줄 수도 있고, 최종 출력만 보여줄 수도 있습니다. 어느 쪽이든 사용자가 후속 질문을 할 수 있으며, 이 경우 run 메서드를 다시 호출할 수 있습니다. #### 수동 대화 관리 -[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드를 사용해 다음 턴의 입력을 가져와 대화 기록을 수동으로 관리할 수 있습니다. +다음 턴의 입력을 얻기 위해 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드를 사용하여 대화 기록을 수동으로 관리할 수 있습니다. ```python async def main(): @@ -294,9 +294,9 @@ async def main(): # California ``` -#### 세션을 통한 자동 대화 관리 +#### 세션을 사용한 자동 대화 관리 -더 간단한 접근 방식으로 [Sessions](sessions/index.md)를 사용해 `.to_input_list()`를 수동으로 호출하지 않고 대화 기록을 자동으로 처리할 수 있습니다. +더 간단한 접근 방식으로, `.to_input_list()`를 수동으로 호출하지 않고도 대화 기록을 자동으로 처리하기 위해 [Sessions](sessions/index.md)를 사용할 수 있습니다. ```python from agents import Agent, Runner, SQLiteSession @@ -322,16 +322,16 @@ async def main(): Sessions는 자동으로 다음을 수행합니다. -- 각 실행 전에 대화 기록을 검색합니다 -- 각 실행 후 새 메시지를 저장합니다 -- 서로 다른 세션 ID에 대해 별도의 대화를 유지합니다 +- 각 실행 전에 대화 기록을 가져옵니다. +- 각 실행 후 새 메시지를 저장합니다. +- 서로 다른 세션 ID에 대해 별도의 대화를 유지합니다. 자세한 내용은 [Sessions 문서](sessions/index.md)를 참조하세요. #### 서버 관리 대화 -`to_input_list()` 또는 `Sessions`로 로컬에서 처리하는 대신 OpenAI 대화 상태 기능이 서버 측에서 대화 상태를 관리하도록 할 수도 있습니다. 이를 통해 과거 메시지를 모두 수동으로 다시 보내지 않고도 대화 기록을 보존할 수 있습니다. 아래 서버 관리 접근 방식 중 어느 것이든 각 요청에는 새 턴의 입력만 전달하고 저장된 ID를 재사용하세요. 자세한 내용은 [OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참조하세요. +`to_input_list()` 또는 `Sessions`로 로컬에서 처리하는 대신, OpenAI 대화 상태 기능이 서버 측에서 대화 상태를 관리하도록 할 수도 있습니다. 이를 통해 과거 메시지를 모두 수동으로 다시 보내지 않고도 대화 기록을 보존할 수 있습니다. 아래 서버 관리 접근 방식 중 어느 것이든 각 요청에는 새 턴의 입력만 전달하고 저장된 ID를 재사용하세요. 자세한 내용은 [OpenAI Conversation 상태 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참조하세요. OpenAI는 턴 간 상태를 추적하는 두 가지 방법을 제공합니다. @@ -360,7 +360,7 @@ async def main(): ##### 2. `previous_response_id` 사용 -또 다른 옵션은 각 턴이 이전 턴의 응답 ID에 명시적으로 연결되는 **response chaining**입니다. +또 다른 옵션은 **응답 체이닝**으로, 각 턴이 이전 턴의 응답 ID에 명시적으로 연결됩니다. ```python from agents import Agent, Runner @@ -385,33 +385,32 @@ async def main(): print(f"Assistant: {result.final_output}") ``` -실행이 승인을 위해 일시 중지되고 [`RunState`][agents.run_state.RunState]에서 재개하는 경우 +실행이 승인을 위해 일시 중지되고 [`RunState`][agents.run_state.RunState]에서 재개하는 경우, SDK는 저장된 `conversation_id` / `previous_response_id` / `auto_previous_response_id` 설정을 유지하므로 재개된 턴은 동일한 서버 관리 대화에서 계속됩니다. -`conversation_id`와 `previous_response_id`는 상호 배타적입니다. 시스템 간 공유할 수 있는 이름 있는 대화 리소스를 원할 때는 `conversation_id`를 사용하세요. 한 턴에서 다음 턴으로 이어지는 가장 가벼운 Responses API 연속 처리 기본 구성 요소를 원할 때는 `previous_response_id`를 사용하세요. +`conversation_id`와 `previous_response_id`는 상호 배타적입니다. 여러 시스템 간 공유할 수 있는 명명된 대화 리소스를 원하면 `conversation_id`를 사용하세요. 한 턴에서 다음 턴으로 이어지는 가장 가벼운 Responses API 이어가기 기본 구성 요소를 원하면 `previous_response_id`를 사용하세요. !!! note SDK는 `conversation_locked` 오류를 backoff로 자동 재시도합니다. 서버 관리 - 대화 실행에서는 재시도 전에 내부 대화 추적기 입력을 되감아 동일하게 - 준비된 항목을 깔끔하게 다시 보낼 수 있도록 합니다. + 대화 실행에서는 재시도 전에 내부 대화 추적기 입력을 되감아 + 동일하게 준비된 항목을 깔끔하게 다시 전송할 수 있도록 합니다. 로컬 세션 기반 실행(`conversation_id`, - `previous_response_id` 또는 `auto_previous_response_id`와 결합할 수 없음)에서도 SDK는 재시도 후 - 기록 항목 중복을 줄이기 위해 최근에 지속된 입력 항목을 최선의 노력으로 - rollback합니다. + `previous_response_id` 또는 `auto_previous_response_id`와 함께 사용할 수 없음)에서도 SDK는 재시도 후 중복 기록 항목을 줄이기 위해 최근 지속된 입력 항목을 최선의 노력으로 + 롤백합니다. 이 호환성 재시도는 `ModelSettings.retry`를 구성하지 않아도 발생합니다. 모델 요청에 대한 - 더 넓은 옵트인 재시도 동작은 [Runner 관리 재시도](models/index.md#runner-managed-retries)를 참조하세요. + 더 폭넓은 옵트인 재시도 동작은 [Runner 관리 재시도](models/index.md#runner-managed-retries)를 참조하세요. ## 훅 및 사용자 지정 ### 모델 입력 필터 호출 -모델 호출 직전에 모델 입력을 편집하려면 `call_model_input_filter`를 사용하세요. 이 훅은 현재 에이전트, 컨텍스트, 결합된 입력 항목(있는 경우 세션 기록 포함)을 받고 새 `ModelInputData`를 반환합니다. +모델 호출 직전에 모델 입력을 편집하려면 `call_model_input_filter`를 사용하세요. 이 훅은 현재 에이전트, 컨텍스트, 결합된 입력 항목(있는 경우 세션 기록 포함)을 받고 새로운 `ModelInputData`를 반환합니다. -반환값은 [`ModelInputData`][agents.run.ModelInputData] 객체여야 합니다. 해당 `input` 필드는 필수이며 입력 항목 목록이어야 합니다. 다른 형태를 반환하면 `UserError`가 발생합니다. +반환 값은 [`ModelInputData`][agents.run.ModelInputData] 객체여야 합니다. 해당 `input` 필드는 필수이며 입력 항목 목록이어야 합니다. 다른 형태를 반환하면 `UserError`가 발생합니다. ```python from agents import Agent, Runner, RunConfig @@ -430,19 +429,19 @@ result = Runner.run_sync( ) ``` -runner는 준비된 입력 목록의 복사본을 훅에 전달하므로 호출자의 원본 목록을 제자리에서 변경하지 않고도 줄이거나, 대체하거나, 재정렬할 수 있습니다. +runner는 준비된 입력 목록의 복사본을 훅에 전달하므로 호출자의 원본 목록을 제자리에서 변경하지 않고도 이를 줄이거나, 교체하거나, 재정렬할 수 있습니다. -세션을 사용하는 경우 `call_model_input_filter`는 세션 기록이 이미 로드되어 현재 턴과 병합된 후 실행됩니다. 그 이전 병합 단계 자체를 사용자 지정하려면 [`session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. +세션을 사용하는 경우 `call_model_input_filter`는 세션 기록이 이미 로드되어 현재 턴과 병합된 후에 실행됩니다. 해당 이전 병합 단계 자체를 사용자 지정하려면 [`session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. -`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`를 사용해 OpenAI 서버 관리 대화 상태를 사용하는 경우 훅은 다음 Responses API 호출을 위해 준비된 페이로드에서 실행됩니다. 해당 페이로드는 이전 기록의 전체 재생이 아니라 이미 새 턴 델타만 나타낼 수 있습니다. 반환한 항목만 해당 서버 관리 연속 처리에 전송된 것으로 표시됩니다. +`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`와 함께 OpenAI 서버 관리 대화 상태를 사용하는 경우, 훅은 다음 Responses API 호출을 위해 준비된 페이로드에서 실행됩니다. 해당 페이로드는 이전 기록 전체를 재생한 것이 아니라 이미 새 턴 델타만 나타낼 수 있습니다. 반환하는 항목만 해당 서버 관리 이어가기에서 전송된 것으로 표시됩니다. -민감한 데이터를 수정하거나, 긴 기록을 줄이거나, 추가 시스템 지침을 삽입하려면 `run_config`를 통해 실행별로 훅을 설정하세요. +민감한 데이터를 수정하거나, 긴 기록을 줄이거나, 추가 시스템 지침을 삽입하려면 실행별로 `run_config`를 통해 훅을 설정하세요. ## 오류 및 복구 ### 오류 핸들러 -모든 `Runner` 진입점은 오류 종류를 키로 하는 dict인 `error_handlers`를 허용합니다. 지원되는 키는 `"max_turns"`와 `"model_refusal"`입니다. `MaxTurnsExceeded` 또는 `ModelRefusalError`를 발생시키는 대신 제어된 최종 출력을 반환하려는 경우 사용하세요. +모든 `Runner` 진입점은 오류 종류를 키로 하는 dict인 `error_handlers`를 받습니다. 지원되는 키는 `"max_turns"`와 `"model_refusal"`입니다. `MaxTurnsExceeded` 또는 `ModelRefusalError`를 발생시키는 대신 제어된 최종 출력을 반환하려는 경우 사용하세요. ```python from agents import ( @@ -471,9 +470,9 @@ result = Runner.run_sync( print(result.final_output) ``` -fallback 출력이 대화 기록에 추가되는 것을 원하지 않으면 `include_in_history=False`로 설정하세요. +대체 출력이 대화 기록에 추가되지 않도록 하려면 `include_in_history=False`를 설정하세요. -모델 거부가 `ModelRefusalError`로 실행을 종료하는 대신 애플리케이션별 fallback을 생성해야 하는 경우 `"model_refusal"`을 사용하세요. +모델 거부가 `ModelRefusalError`로 실행을 종료하는 대신 애플리케이션별 대체 출력을 생성해야 하는 경우 `"model_refusal"`을 사용하세요. ```python from pydantic import BaseModel @@ -505,33 +504,37 @@ result = Runner.run_sync( print(result.final_output) ``` -## Durable execution 통합 및 휴먼인더루프 +## 내구성 있는 실행 통합 및 휴먼인더루프 도구 승인 일시 중지/재개 패턴은 전용 [휴먼인더루프 가이드](human_in_the_loop.md)부터 시작하세요. -아래 통합은 실행이 긴 대기, 재시도 또는 프로세스 재시작에 걸칠 수 있는 경우의 durable orchestration을 위한 것입니다. +아래 통합은 실행이 긴 대기, 재시도 또는 프로세스 재시작에 걸칠 수 있는 내구성 있는 오케스트레이션을 위한 것입니다. + +### Dapr + +Agents SDK [Dapr](https://dapr.io) Diagrid 통합을 사용하면 휴먼인더루프 지원으로 장애에서 자동 복구되는 내구성 있고 장기 실행되는 에이전트를 실행할 수 있습니다. Dapr은 벤더 중립적인 [CNCF](https://cncf.io) 워크플로 오케스트레이터입니다. Dapr 및 OpenAI 에이전트를 [여기](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai)에서 시작하세요. ### Temporal -Agents SDK [Temporal](https://temporal.io/) 통합을 사용해 휴먼인더루프 작업을 포함한 durable한 장기 실행 워크플로를 실행할 수 있습니다. 장기 실행 작업을 완료하기 위해 Temporal과 Agents SDK가 함께 동작하는 데모를 [이 동영상](https://www.youtube.com/watch?v=fFBZqzT4DD8)에서 보고, [문서는 여기](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)에서 확인하세요. +Agents SDK [Temporal](https://temporal.io/) 통합을 사용하면 휴먼인더루프 작업을 포함해 내구성 있고 장기 실행되는 워크플로를 실행할 수 있습니다. Temporal과 Agents SDK가 함께 작동하여 장기 실행 작업을 완료하는 데모를 [이 동영상](https://www.youtube.com/watch?v=fFBZqzT4DD8)에서 보고, [문서는 여기에서 확인하세요](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents). ### Restate -Agents SDK [Restate](https://restate.dev/) 통합을 사용해 인간 승인, 핸드오프, 세션 관리를 포함한 가벼운 durable 에이전트를 사용할 수 있습니다. 이 통합은 Restate의 단일 바이너리 런타임을 의존성으로 필요로 하며, 에이전트를 프로세스/컨테이너 또는 서버리스 함수로 실행하는 것을 지원합니다. +Agents SDK [Restate](https://restate.dev/) 통합을 사용하면 사람 승인, 핸드오프, 세션 관리를 포함한 경량의 내구성 있는 에이전트를 사용할 수 있습니다. 이 통합은 Restate의 단일 바이너리 런타임을 종속성으로 필요로 하며, 에이전트를 프로세스/컨테이너 또는 서버리스 함수로 실행하는 것을 지원합니다. 자세한 내용은 [개요](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)를 읽거나 [문서](https://docs.restate.dev/ai)를 확인하세요. ### DBOS -Agents SDK [DBOS](https://dbos.dev/) 통합을 사용해 실패와 재시작 간에도 진행 상황을 보존하는 신뢰할 수 있는 에이전트를 실행할 수 있습니다. 장기 실행 에이전트, 휴먼인더루프 워크플로, 핸드오프를 지원합니다. 동기 및 비동기 메서드를 모두 지원합니다. 이 통합에는 SQLite 또는 Postgres 데이터베이스만 필요합니다. 자세한 내용은 통합 [repo](https://github.com/dbos-inc/dbos-openai-agents)와 [문서](https://docs.dbos.dev/integrations/openai-agents)를 확인하세요. +Agents SDK [DBOS](https://dbos.dev/) 통합을 사용하면 장애 및 재시작 전반에서 진행 상황을 보존하는 신뢰할 수 있는 에이전트를 실행할 수 있습니다. 장기 실행 에이전트, 휴먼인더루프 워크플로, 핸드오프를 지원합니다. 동기 및 비동기 메서드를 모두 지원합니다. 이 통합에는 SQLite 또는 Postgres 데이터베이스만 필요합니다. 자세한 내용은 통합 [repo](https://github.com/dbos-inc/dbos-openai-agents)와 [문서](https://docs.dbos.dev/integrations/openai-agents)를 확인하세요. ## 예외 -SDK는 특정 경우에 예외를 발생시킵니다. 전체 목록은 [`agents.exceptions`][]에 있습니다. 개요는 다음과 같습니다. +SDK는 특정 경우 예외를 발생시킵니다. 전체 목록은 [`agents.exceptions`][]에 있습니다. 개요는 다음과 같습니다. - [`AgentsException`][agents.exceptions.AgentsException]: SDK 내에서 발생하는 모든 예외의 기본 클래스입니다. 다른 모든 특정 예외가 파생되는 일반 타입 역할을 합니다. -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 이 예외는 에이전트 실행이 `Runner.run`, `Runner.run_sync` 또는 `Runner.run_streamed` 메서드에 전달된 `max_turns` 제한을 초과할 때 발생합니다. 에이전트가 지정된 상호작용 턴 수 내에 작업을 완료하지 못했음을 나타냅니다. 제한을 비활성화하려면 `max_turns=None`으로 설정하세요. -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 이 예외는 기반 모델(LLM)이 예상치 못한 출력 또는 잘못된 출력을 생성할 때 발생합니다. 다음이 포함될 수 있습니다. +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 이 예외는 에이전트 실행이 `Runner.run`, `Runner.run_sync` 또는 `Runner.run_streamed` 메서드에 전달된 `max_turns` 제한을 초과할 때 발생합니다. 에이전트가 지정된 상호작용 턴 수 내에 작업을 완료하지 못했음을 나타냅니다. 제한을 비활성화하려면 `max_turns=None`을 설정하세요. +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 이 예외는 기본 모델(LLM)이 예기치 않거나 잘못된 출력을 생성할 때 발생합니다. 여기에는 다음이 포함될 수 있습니다. - 잘못된 JSON: 모델이 도구 호출 또는 직접 출력에서 잘못된 JSON 구조를 제공하는 경우, 특히 특정 `output_type`이 정의된 경우 - - 예상치 못한 도구 관련 실패: 모델이 예상된 방식으로 도구를 사용하지 못하는 경우 + - 예기치 않은 도구 관련 실패: 모델이 예상된 방식으로 도구를 사용하지 못하는 경우 - [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: 이 예외는 함수 도구 호출이 구성된 타임아웃을 초과하고 도구가 `timeout_behavior="raise_exception"`을 사용할 때 발생합니다. -- [`UserError`][agents.exceptions.UserError]: 이 예외는 사용자(SDK를 사용해 코드를 작성하는 사람)가 SDK 사용 중 오류를 만들 때 발생합니다. 일반적으로 잘못된 코드 구현, 유효하지 않은 구성 또는 SDK API 오용으로 인해 발생합니다. +- [`UserError`][agents.exceptions.UserError]: 이 예외는 (SDK를 사용해 코드를 작성하는) 사용자가 SDK 사용 중 오류를 만들 때 발생합니다. 일반적으로 잘못된 코드 구현, 유효하지 않은 구성 또는 SDK API의 오용으로 인해 발생합니다. - [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 이 예외는 각각 입력 가드레일 또는 출력 가드레일의 조건이 충족될 때 발생합니다. 입력 가드레일은 처리 전에 들어오는 메시지를 확인하고, 출력 가드레일은 전달 전에 에이전트의 최종 응답을 확인합니다. \ No newline at end of file diff --git a/docs/zh/running_agents.md b/docs/zh/running_agents.md index da7c7237f3..7acf4a2161 100644 --- a/docs/zh/running_agents.md +++ b/docs/zh/running_agents.md @@ -8,7 +8,7 @@ search: 1. [`Runner.run()`][agents.run.Runner.run]，异步运行并返回 [`RunResult`][agents.result.RunResult]。 2. [`Runner.run_sync()`][agents.run.Runner.run_sync]，这是一个同步方法，底层只是运行 `.run()`。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]，异步运行并返回 [`RunResultStreaming`][agents.result.RunResultStreaming]。它以流式传输模式调用 LLM，并在事件收到时将这些事件流式传输给你。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]，异步运行并返回 [`RunResultStreaming`][agents.result.RunResultStreaming]。它以流式传输模式调用 LLM，并在收到事件时将这些事件流式传输给你。 ```python from agents import Agent, Runner @@ -31,18 +31,18 @@ async def main(): 当你使用 `Runner` 中的 run 方法时，需要传入一个起始智能体和输入。输入可以是： -- 一个字符串（视为用户消息）， +- 一个字符串（被视为用户消息）， - OpenAI Responses API 格式的输入项列表，或 -- 在恢复中断的运行时使用的 [`RunState`][agents.run_state.RunState]。 +- 在恢复被中断的运行时使用的 [`RunState`][agents.run_state.RunState]。 然后 runner 会运行一个循环： -1. 我们使用当前输入为当前智能体调用 LLM。 +1. 我们用当前输入为当前智能体调用 LLM。 2. LLM 生成其输出。 - 1. 如果 LLM 返回 `final_output`，循环结束并返回结果。 + 1. 如果 LLM 返回 `final_output`，循环结束，并返回结果。 2. 如果 LLM 执行任务转移，我们会更新当前智能体和输入，并重新运行循环。 3. 如果 LLM 生成工具调用，我们会运行这些工具调用、追加结果，并重新运行循环。 -3. 如果超过传入的 `max_turns`，我们会引发 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 异常。传入 `max_turns=None` 可禁用此轮次限制。 +3. 如果超过传入的 `max_turns`，我们会抛出 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 异常。传入 `max_turns=None` 可禁用此轮数限制。 !!! note @@ -50,19 +50,19 @@ async def main(): ### 流式传输 -流式传输允许你在 LLM 运行时额外接收流式事件。流完成后，[`RunResultStreaming`][agents.result.RunResultStreaming] 将包含有关该运行的完整信息，包括生成的所有新输出。你可以调用 `.stream_events()` 获取流式事件。在[流式传输指南](streaming.md)中阅读更多内容。 +流式传输允许你在 LLM 运行时额外接收流式传输事件。流结束后，[`RunResultStreaming`][agents.result.RunResultStreaming] 将包含此次运行的完整信息，包括生成的所有新输出。你可以调用 `.stream_events()` 获取流式传输事件。在[流式传输指南](streaming.md)中阅读更多内容。 #### Responses WebSocket 传输（可选辅助工具） -如果你启用 OpenAI Responses websocket 传输，可以继续使用普通的 `Runner` API。建议使用 websocket 会话辅助工具来复用连接，但这不是必需的。 +如果启用 OpenAI Responses websocket 传输，你可以继续使用常规的 `Runner` API。建议使用 websocket 会话辅助工具来复用连接，但这不是必需的。 -这是基于 websocket 传输的 Responses API，而不是 [Realtime API](realtime/guide.md)。 +这是通过 websocket 传输的 Responses API，不是 [Realtime API](realtime/guide.md)。 -有关传输选择规则以及具体模型对象或自定义提供方的注意事项，请参阅[模型](models/index.md#responses-websocket-transport)。 +有关传输选择规则以及具体模型对象或自定义提供方相关的注意事项，请参阅[模型](models/index.md#responses-websocket-transport)。 -##### 模式 1：无会话辅助工具（可用） +##### 模式 1：不使用会话辅助工具（可用） -当你只需要 websocket 传输，并且不需要 SDK 为你管理共享提供方/会话时，请使用此模式。 +当你只想使用 websocket 传输，并且不需要 SDK 为你管理共享的提供方/会话时，请使用此模式。 ```python import asyncio @@ -85,11 +85,11 @@ async def main(): asyncio.run(main()) ``` -此模式适合单次运行。如果你反复调用 `Runner.run()` / `Runner.run_streamed()`，除非手动复用同一个 `RunConfig` / 提供方实例，否则每次运行都可能重新连接。 +此模式适合单次运行。如果你反复调用 `Runner.run()` / `Runner.run_streamed()`，除非你手动复用同一个 `RunConfig` / 提供方实例，否则每次运行都可能重新连接。 -##### 模式 2：使用 `responses_websocket_session()`（推荐用于多轮复用） +##### 模式 2：使用 `responses_websocket_session()`（建议用于多轮复用） -当你希望在多次运行中共享支持 websocket 的提供方和 `RunConfig`（包括继承相同 `run_config` 的嵌套 agent-as-tool 调用）时，请使用 [`responses_websocket_session()`][agents.responses_websocket_session]。 +当你希望在多次运行之间（包括继承同一 `run_config` 的嵌套 agent-as-tool 调用）共享支持 websocket 的提供方和 `RunConfig` 时，请使用 [`responses_websocket_session()`][agents.responses_websocket_session]。 ```python import asyncio @@ -119,9 +119,9 @@ async def main(): asyncio.run(main()) ``` -在上下文退出前完成对流式结果的消费。如果在 websocket 请求仍在进行时退出上下文，可能会强制关闭共享连接。 +在上下文退出前完成对流式传输结果的消费。如果 websocket 请求仍在进行中时退出上下文，可能会强制关闭共享连接。 -如果长推理轮次触发 websocket keepalive 超时，请增加 `ping_timeout` 或设置 `ping_timeout=None` 以禁用心跳超时。对于可靠性比 websocket 延迟更重要的运行，请使用 HTTP/SSE 传输。 +如果长推理轮次触发 websocket keepalive 超时，请增大 `ping_timeout`，或设置 `ping_timeout=None` 以禁用心跳超时。对于可靠性比 websocket 延迟更重要的运行，请使用 HTTP/SSE 传输。 ### 运行配置 @@ -129,45 +129,45 @@ asyncio.run(main()) #### 常见运行配置目录 -使用 `RunConfig` 可在不更改每个智能体定义的情况下覆盖单次运行的行为。 +使用 `RunConfig` 可在不更改每个智能体定义的情况下，覆盖单次运行的行为。 ##### 模型、提供方和会话默认值 -- [`model`][agents.run.RunConfig.model]：允许设置要使用的全局 LLM 模型，而不考虑每个 Agent 拥有的 `model`。 +- [`model`][agents.run.RunConfig.model]：允许设置要使用的全局 LLM 模型，而不管每个 Agent 各自的 `model` 是什么。 - [`model_provider`][agents.run.RunConfig.model_provider]：用于查找模型名称的模型提供方，默认值为 OpenAI。 - [`model_settings`][agents.run.RunConfig.model_settings]：覆盖智能体特定的设置。例如，你可以设置全局 `temperature` 或 `top_p`。 -- [`session_settings`][agents.run.RunConfig.session_settings]：在运行期间检索历史记录时覆盖会话级默认值（例如 `SessionSettings(limit=...)`）。 -- [`session_input_callback`][agents.run.RunConfig.session_input_callback]：使用 Sessions 时，自定义每轮之前新用户输入与会话历史合并的方式。回调可以是同步或异步的。 +- [`session_settings`][agents.run.RunConfig.session_settings]：在运行期间检索历史记录时，覆盖会话级默认值（例如 `SessionSettings(limit=...)`）。 +- [`session_input_callback`][agents.run.RunConfig.session_input_callback]：使用 Sessions 时，自定义每轮之前如何将新的用户输入与会话历史合并。回调可以是同步或异步的。 ##### 安全防护措施、任务转移和模型输入塑形 - [`input_guardrails`][agents.run.RunConfig.input_guardrails]、[`output_guardrails`][agents.run.RunConfig.output_guardrails]：要包含在所有运行中的输入或输出安全防护措施列表。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]：应用于所有任务转移的全局输入过滤器，前提是该任务转移尚未有一个过滤器。输入过滤器允许你编辑发送给新智能体的输入。有关更多详细信息，请参阅 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 中的文档。 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]：选择启用的 beta 功能，会在调用下一个智能体之前，将先前的转录折叠为一条 assistant 消息。在我们稳定嵌套任务转移期间，此功能默认禁用；设置为 `True` 以启用，或保留 `False` 以传递原始转录。当你未传入 `RunConfig` 时，所有 [Runner 方法][agents.run.Runner]都会自动创建一个 `RunConfig`，因此快速入门和示例会保持默认关闭，并且任何显式的 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 回调都会继续覆盖它。单个任务转移可以通过 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 覆盖此设置。 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]：可选的可调用对象，当你选择启用 `nest_handoff_history` 时，它会接收规范化转录（历史记录 + 任务转移项）。它必须返回要转发给下一个智能体的确切输入项列表，允许你替换内置摘要，而无需编写完整的任务转移过滤器。 -- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]：用于在模型调用前立即编辑完全准备好的模型输入（instructions 和输入项）的钩子，例如修剪历史记录或注入系统提示词。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]：应用于所有任务转移的全局输入过滤器，前提是该任务转移尚未有自己的过滤器。输入过滤器允许你编辑发送给新智能体的输入。更多详情请参阅 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 中的文档。 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]：一个选择启用的 beta 功能，会在调用下一个智能体之前，将先前的记录折叠为一条 assistant 消息。在我们稳定嵌套任务转移期间，该功能默认禁用；设置为 `True` 可启用，或保持 `False` 以传递原始记录。当你未传入 `RunConfig` 时，所有 [Runner 方法][agents.run.Runner] 都会自动创建一个 `RunConfig`，因此 quickstarts 和代码示例会保持默认关闭，而任何显式的 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 回调仍会继续覆盖它。单个任务转移可以通过 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 覆盖此设置。 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]：可选 callable；当你选择启用 `nest_handoff_history` 时，它会接收规范化后的记录（历史 + 任务转移项）。它必须返回要转发给下一个智能体的确切输入项列表，从而允许你在不编写完整任务转移过滤器的情况下替换内置摘要。 +- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]：在模型调用前立即编辑已完全准备好的模型输入（instructions 和输入项）的钩子，例如用于裁剪历史或注入系统提示词。 - [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]：控制 runner 将先前输出转换为下一轮模型输入时，是保留还是省略 reasoning item ID。 ##### 追踪和可观测性 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]：允许你对整个运行禁用[追踪](tracing.md)。 -- [`tracing`][agents.run.RunConfig.tracing]：传入 [`TracingConfig`][agents.tracing.TracingConfig] 以覆盖 trace 导出设置，例如每次运行的追踪 API 密钥。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]：配置 trace 是否包含可能敏感的数据，例如 LLM 和工具调用的输入/输出。 -- [`workflow_name`][agents.run.RunConfig.workflow_name]、[`trace_id`][agents.run.RunConfig.trace_id]、[`group_id`][agents.run.RunConfig.group_id]：设置该运行的追踪工作流名称、trace ID 和 trace group ID。我们建议至少设置 `workflow_name`。group ID 是一个可选字段，可让你将多次运行的 trace 关联起来。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]：允许你为整个运行禁用[追踪](tracing.md)。 +- [`tracing`][agents.run.RunConfig.tracing]：传入 [`TracingConfig`][agents.tracing.TracingConfig] 以覆盖 trace 导出设置，例如每次运行的 tracing API key。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]：配置 trace 是否包含潜在敏感数据，例如 LLM 和工具调用的输入/输出。 +- [`workflow_name`][agents.run.RunConfig.workflow_name]、[`trace_id`][agents.run.RunConfig.trace_id]、[`group_id`][agents.run.RunConfig.group_id]：设置运行的 tracing 工作流名称、trace ID 和 trace group ID。我们建议至少设置 `workflow_name`。group ID 是一个可选字段，可用于关联多次运行的 trace。 - [`trace_metadata`][agents.run.RunConfig.trace_metadata]：要包含在所有 trace 中的元数据。 ##### 工具执行、审批和工具错误行为 -- [`tool_execution`][agents.run.RunConfig.tool_execution]：为本地工具调用配置 SDK 端执行行为，例如限制同时运行的 function tools 数量。 -- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]：自定义在审批流程中拒绝工具调用时模型可见的消息。 +- [`tool_execution`][agents.run.RunConfig.tool_execution]：配置本地工具调用在 SDK 侧的执行行为，例如限制同时运行的工具调用数量。 +- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]：自定义审批流程中工具调用被拒绝时对模型可见的消息。 -嵌套任务转移作为选择启用的 beta 功能提供。通过传入 `RunConfig(nest_handoff_history=True)` 启用折叠转录行为，或设置 `handoff(..., nest_handoff_history=True)` 为特定任务转移启用它。如果你希望保留原始转录（默认），请保持该标志未设置，或提供一个 `handoff_input_filter`（或 `handoff_history_mapper`）来按你的需求精确转发对话。若要更改生成摘要中使用的包装文本而不编写自定义 mapper，请调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（以及 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 以恢复默认值）。 +嵌套任务转移是一个可选择启用的 beta 功能。通过传入 `RunConfig(nest_handoff_history=True)` 启用折叠记录行为，或设置 `handoff(..., nest_handoff_history=True)` 以仅对特定任务转移启用。如果你更希望保留原始记录（默认行为），请不要设置该标志，或提供一个 `handoff_input_filter`（或 `handoff_history_mapper`），以按你的需要精确转发对话。若要更改生成摘要中使用的包装文本，而不编写自定义 mapper，请调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（以及 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 来恢复默认值）。 #### 运行配置详情 ##### `tool_execution` -当你希望 SDK 限制某次运行中的本地 function-tool 并发时，请使用 `tool_execution`。 +当你希望 SDK 为一次运行限制本地 function-tool 并发时，请使用 `tool_execution`。 ```python from agents import Agent, RunConfig, Runner, ToolExecutionConfig @@ -183,24 +183,24 @@ result = await Runner.run( ) ``` -`max_function_tool_concurrency=None` 会保留默认行为：当模型在一轮中发出多个 function tool 调用时，SDK 会启动所有发出的本地 function tool 调用。设置一个整数值可限制这些本地 function tools 同时运行的数量。 +`max_function_tool_concurrency=None` 会保留默认行为：当模型在一轮中发出多个 function tool 调用时，SDK 会启动所有发出的本地 function tool 调用。设置一个整数值可限制这些本地 function tool 同时运行的数量。 -这与提供方侧的 [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls] 是分开的。`parallel_tool_calls` 控制模型是否允许在单个响应中发出多个工具调用。`tool_execution.max_function_tool_concurrency` 控制 SDK 在模型发出本地 function tool 调用后如何执行它们。 +这与提供方侧的 [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls] 是分开的。`parallel_tool_calls` 控制是否允许模型在单个响应中发出多个工具调用。`tool_execution.max_function_tool_concurrency` 控制模型发出本地 function tool 调用后，SDK 如何执行它们。 ##### `tool_error_formatter` -使用 `tool_error_formatter` 可自定义在审批流程中拒绝工具调用时返回给模型的消息。 +使用 `tool_error_formatter` 可自定义审批流程中工具调用被拒绝时返回给模型的消息。 -formatter 接收 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]，其中包含： +formatter 会接收 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]，其中包含： - `kind`：错误目录。当前为 `"approval_rejected"`。 - `tool_type`：工具运行时（`"function"`、`"computer"`、`"shell"`、`"apply_patch"` 或 `"custom"`）。 - `tool_name`：工具名称。 - `call_id`：工具调用 ID。 -- `default_message`：SDK 默认的模型可见消息。 +- `default_message`：SDK 的默认模型可见消息。 - `run_context`：活动运行上下文包装器。 -返回字符串以替换消息，或返回 `None` 使用 SDK 默认值。 +返回一个字符串以替换消息，或返回 `None` 以使用 SDK 默认值。 ```python from agents import Agent, RunConfig, Runner, ToolErrorFormatterArgs @@ -225,50 +225,50 @@ result = Runner.run_sync( ##### `reasoning_item_id_policy` -`reasoning_item_id_policy` 控制当 runner 携带历史记录向前推进时（例如使用 `RunResult.to_input_list()` 或基于会话的运行时），reasoning items 如何转换为下一轮模型输入。 +`reasoning_item_id_policy` 控制当 runner 向前传递历史记录时（例如使用 `RunResult.to_input_list()` 或由会话支持的运行），如何将 reasoning items 转换为下一轮模型输入。 - `None` 或 `"preserve"`（默认）：保留 reasoning item ID。 -- `"omit"`：从生成的下一轮输入中移除 reasoning item ID。 +- `"omit"`：从生成的下一轮输入中剥离 reasoning item ID。 -主要将 `"omit"` 用作选择启用的缓解措施，用于处理一类 Responses API 400 错误：reasoning item 带有 `id` 发送，但没有所需的后续项（例如，`Item 'rs_...' of type 'reasoning' was provided without its required following item.`）。 +使用 `"omit"` 主要是作为一种选择启用的缓解措施，用于处理一类 Responses API 400 错误：某个 reasoning item 携带了 `id`，但没有随后的必需项（例如，`Item 'rs_...' of type 'reasoning' was provided without its required following item.`）。 -在多轮智能体运行中，如果 SDK 从先前输出构造后续输入（包括会话持久化、服务管理的对话增量、流式/非流式后续轮次以及恢复路径），并且保留了 reasoning item ID，但提供方要求该 ID 与其对应的后续项保持配对，就可能发生这种情况。 +在多轮智能体运行中，当 SDK 从先前输出构造后续输入（包括会话持久化、服务管理的对话增量、流式/非流式后续轮次以及恢复路径）时，如果保留了 reasoning item ID，但提供方要求该 ID 必须与其对应的后续项保持配对，就可能发生这种情况。 -设置 `reasoning_item_id_policy="omit"` 会保留 reasoning 内容，但移除 reasoning item 的 `id`，从而避免在 SDK 生成的后续输入中触发该 API 不变量。 +设置 `reasoning_item_id_policy="omit"` 会保留推理内容，但剥离 reasoning item 的 `id`，从而避免在 SDK 生成的后续输入中触发该 API 不变量。 范围说明： - 这只会更改 SDK 在构建后续输入时生成/转发的 reasoning items。 - 它不会重写用户提供的初始输入项。 -- 在应用此策略后，`call_model_input_filter` 仍可有意重新引入 reasoning ID。 +- `call_model_input_filter` 仍可在应用此策略后有意重新引入 reasoning ID。 ## 状态和对话管理 -### 记忆策略选择 +### 内存策略选择 -有四种常见方式可以将状态带入下一轮： +有四种常见方式可将状态带入下一轮： -| 策略 | 状态所在位置 | 最适合 | 下一轮传入的内容 | +| 策略 | 状态所在位置 | 最适合 | 下一轮传入内容 | | --- | --- | --- | --- | | `result.to_input_list()` | 你的应用内存 | 小型聊天循环、完全手动控制、任何提供方 | 来自 `result.to_input_list()` 的列表加上下一个用户消息 | -| `session` | 你的存储加上 SDK | 持久聊天状态、可恢复运行、自定义存储 | 相同的 `session` 实例，或指向同一存储的另一个实例 | -| `conversation_id` | OpenAI Conversations API | 你希望跨工作器或服务共享的具名服务端对话 | 相同的 `conversation_id`，并且只加上新的用户轮次 | -| `previous_response_id` | OpenAI Responses API | 无需创建对话资源的轻量级服务管理延续 | `result.last_response_id`，并且只加上新的用户轮次 | +| `session` | 你的存储加 SDK | 持久聊天状态、可恢复运行、自定义存储 | 同一个 `session` 实例，或指向同一存储的另一个实例 | +| `conversation_id` | OpenAI Conversations API | 你希望跨 worker 或服务共享的命名服务端对话 | 同一个 `conversation_id` 加上仅新的用户轮次 | +| `previous_response_id` | OpenAI Responses API | 无需创建对话资源的轻量级服务管理延续 | `result.last_response_id` 加上仅新的用户轮次 | -`result.to_input_list()` 和 `session` 由客户端管理。`conversation_id` 和 `previous_response_id` 由 OpenAI 管理，并且仅在你使用 OpenAI Responses API 时适用。在大多数应用中，每个对话选择一种持久化策略。混合客户端管理的历史与 OpenAI 管理的状态可能会导致上下文重复，除非你有意协调这两层。 +`result.to_input_list()` 和 `session` 由客户端管理。`conversation_id` 和 `previous_response_id` 由 OpenAI 管理，并且仅在使用 OpenAI Responses API 时适用。在大多数应用中，每个对话选择一种持久化策略。混合使用客户端管理的历史和 OpenAI 管理的状态可能会导致上下文重复，除非你有意协调这两层。 !!! note 会话持久化不能与服务管理的对话设置 - （`conversation_id`、`previous_response_id` 或 `auto_previous_response_id`）在同一次运行中组合使用。 - 每次调用请选择一种方法。 + （`conversation_id`、`previous_response_id` 或 `auto_previous_response_id`）在 + 同一次运行中组合使用。每次调用请选择一种方法。 ### 对话/聊天线程 -调用任何运行方法都可能导致一个或多个智能体运行（因此也会有一次或多次 LLM 调用），但它表示聊天对话中的单个逻辑轮次。例如： +调用任何 run 方法都可能导致一个或多个智能体运行（因此也可能有一次或多次 LLM 调用），但它表示聊天对话中的一个逻辑轮次。例如： 1. 用户轮次：用户输入文本 -2. Runner 运行：第一个智能体调用 LLM、运行工具、向第二个智能体执行任务转移；第二个智能体运行更多工具，然后生成输出。 +2. Runner 运行：第一个智能体调用 LLM、运行工具、向第二个智能体执行任务转移，第二个智能体运行更多工具，然后生成输出。 在智能体运行结束时，你可以选择向用户展示什么。例如，你可以向用户展示智能体生成的每个新项，或者只展示最终输出。无论哪种方式，用户随后都可能提出后续问题，在这种情况下你可以再次调用 run 方法。 @@ -294,9 +294,9 @@ async def main(): # California ``` -#### 使用 Sessions 自动管理对话 +#### 使用会话自动管理对话 -为了更简单的方法，你可以使用 [Sessions](sessions/index.md) 自动处理对话历史，而无需手动调用 `.to_input_list()`： +为简化流程，你可以使用 [Sessions](sessions/index.md) 自动处理对话历史，而无需手动调用 `.to_input_list()`： ```python from agents import Agent, Runner, SQLiteSession @@ -324,20 +324,20 @@ Sessions 会自动： - 在每次运行前检索对话历史 - 在每次运行后存储新消息 -- 为不同的 session ID 维护独立对话 +- 为不同的会话 ID 维护独立对话 -更多详细信息请参阅 [Sessions 文档](sessions/index.md)。 +更多详情请参阅 [Sessions 文档](sessions/index.md)。 #### 服务管理的对话 -你还可以让 OpenAI 对话状态功能在服务端管理对话状态，而不是使用 `to_input_list()` 或 `Sessions` 在本地处理。这样你就可以保留对话历史，而无需手动重新发送所有过去的消息。对于下面任一服务管理方法，每次请求只传入新轮次的输入，并复用保存的 ID。更多详细信息请参阅 [OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。 +你也可以让 OpenAI 的对话状态功能在服务端管理对话状态，而不是在本地用 `to_input_list()` 或 `Sessions` 处理。这样你无需手动重新发送所有过去消息，也能保留对话历史。对于下面任一服务管理方法，每次请求只传入新轮次的输入，并复用保存的 ID。更多详情请参阅 [OpenAI 对话状态指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。 -OpenAI 提供两种跨轮次跟踪状态的方式： +OpenAI 提供两种方式跨轮次跟踪状态： ##### 1. 使用 `conversation_id` -你首先使用 OpenAI Conversations API 创建一个对话，然后在之后每次调用中复用其 ID： +你首先使用 OpenAI Conversations API 创建一个对话，然后在后续每次调用中复用其 ID： ```python from agents import Agent, Runner @@ -360,7 +360,7 @@ async def main(): ##### 2. 使用 `previous_response_id` -另一种选项是**响应链式连接**，其中每个轮次都显式链接到上一轮的响应 ID。 +另一种选择是**响应链式衔接**，其中每个轮次都会显式链接到上一轮的响应 ID。 ```python from agents import Agent, Runner @@ -385,32 +385,30 @@ async def main(): print(f"Assistant: {result.final_output}") ``` -如果某次运行因审批而暂停，并且你从 [`RunState`][agents.run_state.RunState] 恢复， -SDK 会保留已保存的 `conversation_id` / `previous_response_id` / `auto_previous_response_id` -设置，使恢复的轮次继续处于同一个服务管理的对话中。 +如果运行因审批而暂停，并且你从 [`RunState`][agents.run_state.RunState] 恢复，SDK 会保留已保存的 `conversation_id` / `previous_response_id` / `auto_previous_response_id` 设置，因此恢复后的轮次会继续在同一个服务管理的对话中进行。 -`conversation_id` 和 `previous_response_id` 互斥。当你希望使用可跨系统共享的具名对话资源时，请使用 `conversation_id`。当你希望获得从一轮到下一轮最轻量的 Responses API 延续基本组件时，请使用 `previous_response_id`。 +`conversation_id` 和 `previous_response_id` 互斥。当你需要一个可跨系统共享的命名对话资源时，请使用 `conversation_id`。当你需要从一轮到下一轮的最轻量 Responses API 延续基本组件时，请使用 `previous_response_id`。 !!! note - SDK 会自动以退避方式重试 `conversation_locked` 错误。在服务管理的 + SDK 会自动使用退避重试 `conversation_locked` 错误。在服务管理的 对话运行中，它会在重试前回退内部对话跟踪器输入，以便 - 相同的已准备项可以被干净地重新发送。 + 可以干净地重新发送相同的已准备项。 - 在基于本地 session 的运行中（不能与 `conversation_id`、 - `previous_response_id` 或 `auto_previous_response_id` 组合使用），SDK 还会尽最大努力 + 在基于本地会话的运行中（不能与 `conversation_id`、 + `previous_response_id` 或 `auto_previous_response_id` 组合使用），SDK 还会尽力 回滚最近持久化的输入项，以减少重试后重复的历史条目。 即使你未配置 `ModelSettings.retry`，也会发生此兼容性重试。有关 - 模型请求上更广泛的选择启用重试行为，请参阅 [Runner-managed retries](models/index.md#runner-managed-retries)。 + 模型请求上更广泛的选择启用重试行为，请参阅 [Runner 管理的重试](models/index.md#runner-managed-retries)。 ## 钩子和自定义 ### 调用模型输入过滤器 -使用 `call_model_input_filter` 在模型调用前立即编辑模型输入。该钩子接收当前智能体、上下文和合并后的输入项（存在会话历史时包括会话历史），并返回一个新的 `ModelInputData`。 +使用 `call_model_input_filter` 可在模型调用前立即编辑模型输入。该钩子会接收当前智能体、上下文以及组合后的输入项（存在会话历史时包括会话历史），并返回一个新的 `ModelInputData`。 -返回值必须是 [`ModelInputData`][agents.run.ModelInputData] 对象。其 `input` 字段是必需的，并且必须是输入项列表。返回任何其他形状都会引发 `UserError`。 +返回值必须是 [`ModelInputData`][agents.run.ModelInputData] 对象。其 `input` 字段是必需的，并且必须是输入项列表。返回任何其他形状都会抛出 `UserError`。 ```python from agents import Agent, Runner, RunConfig @@ -429,19 +427,19 @@ result = Runner.run_sync( ) ``` -runner 会将准备好的输入列表副本传递给该钩子，因此你可以修剪、替换或重新排序它，而不会就地改变调用方的原始列表。 +runner 会将已准备输入列表的副本传给该钩子，因此你可以裁剪、替换或重新排序它，而不会就地修改调用方的原始列表。 -如果你正在使用 session，`call_model_input_filter` 会在会话历史已经加载并与当前轮次合并之后运行。当你希望自定义更早的合并步骤本身时，请使用 [`session_input_callback`][agents.run.RunConfig.session_input_callback]。 +如果你正在使用会话，`call_model_input_filter` 会在会话历史已加载并与当前轮次合并后运行。当你想要自定义更早的合并步骤本身时，请使用 [`session_input_callback`][agents.run.RunConfig.session_input_callback]。 -如果你正在使用带有 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 的 OpenAI 服务管理对话状态，该钩子会在下一次 Responses API 调用的已准备 payload 上运行。该 payload 可能已经只表示新轮次增量，而不是对早期历史的完整重放。只有你返回的项会被标记为已发送到该服务管理的延续。 +如果你正在使用带有 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 的 OpenAI 服务管理对话状态，该钩子会在下一次 Responses API 调用的已准备载荷上运行。该载荷可能已经只表示新轮次增量，而不是对早期历史的完整重放。只有你返回的项会被标记为已发送，用于该服务管理的延续。 -通过 `run_config` 为每次运行设置该钩子，以编辑敏感数据、修剪较长历史记录或注入额外系统指导。 +通过 `run_config` 为每次运行设置该钩子，以编辑敏感数据、裁剪较长历史或注入额外系统指导。 ## 错误和恢复 -### 错误处理器 +### 错误处理程序 -所有 `Runner` 入口点都接受 `error_handlers`，这是一个按错误类型作为键的 dict。支持的键为 `"max_turns"` 和 `"model_refusal"`。当你希望返回受控的最终输出，而不是引发 `MaxTurnsExceeded` 或 `ModelRefusalError` 时，请使用它们。 +所有 `Runner` 入口点都接受 `error_handlers`，这是一个按错误种类作为键的字典。支持的键是 `"max_turns"` 和 `"model_refusal"`。当你希望返回受控的最终输出，而不是抛出 `MaxTurnsExceeded` 或 `ModelRefusalError` 时，请使用它们。 ```python from agents import ( @@ -472,7 +470,7 @@ print(result.final_output) 当你不希望将回退输出追加到对话历史时，请设置 `include_in_history=False`。 -当模型拒绝应生成应用特定的回退，而不是以 `ModelRefusalError` 结束运行时，请使用 `"model_refusal"`。 +当模型拒绝应产生应用特定的回退，而不是以 `ModelRefusalError` 结束运行时，请使用 `"model_refusal"`。 ```python from pydantic import BaseModel @@ -504,33 +502,37 @@ result = Runner.run_sync( print(result.final_output) ``` -## 持久执行集成和人工参与 +## 持久执行集成和人类参与回路 -对于工具审批暂停/恢复模式，请从专门的[人工参与指南](human_in_the_loop.md)开始。 -以下集成适用于运行可能跨越长时间等待、重试或进程重启的持久编排。 +对于工具审批暂停/恢复模式，请从专门的[人类参与回路指南](human_in_the_loop.md)开始。 +以下集成用于持久编排，适用于运行可能跨越长时间等待、重试或进程重启的场景。 + +### Dapr + +你可以使用 Agents SDK [Dapr](https://dapr.io) Diagrid 集成来运行持久、长时间运行的智能体，这些智能体会在失败后自动恢复，并支持人类参与回路。Dapr 是一个供应商中立的 [CNCF](https://cncf.io) 工作流编排器。请在[这里](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai)开始使用 Dapr 和 OpenAI agents。 ### Temporal -你可以使用 Agents SDK [Temporal](https://temporal.io/) 集成来运行持久、长时间运行的工作流，包括人工参与任务。观看 Temporal 和 Agents SDK 实际协同完成长时间运行任务的演示[视频](https://www.youtube.com/watch?v=fFBZqzT4DD8)，并[在此查看文档](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)。 +你可以使用 Agents SDK [Temporal](https://temporal.io/) 集成来运行持久、长时间运行的工作流，包括人类参与回路任务。在[此视频](https://www.youtube.com/watch?v=fFBZqzT4DD8)中查看 Temporal 与 Agents SDK 协同完成长时间运行任务的演示，并[在此查看文档](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)。 ### Restate -你可以使用 Agents SDK [Restate](https://restate.dev/) 集成来实现轻量、持久的智能体，包括人工审批、任务转移和会话管理。该集成需要 Restate 的单二进制运行时作为依赖，并支持将智能体作为进程/容器或 serverless functions 运行。 -阅读[概览](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)或查看[文档](https://docs.restate.dev/ai)以获取更多详细信息。 +你可以使用 Agents SDK [Restate](https://restate.dev/) 集成来构建轻量、持久的智能体，包括人工审批、任务转移和会话管理。该集成需要 Restate 的单二进制运行时作为依赖，并支持将智能体作为进程/容器或 serverless 函数运行。 +阅读[概览](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)或查看[文档](https://docs.restate.dev/ai)以获取更多详情。 ### DBOS -你可以使用 Agents SDK [DBOS](https://dbos.dev/) 集成来运行可靠的智能体，在故障和重启时保留进度。它支持长时间运行的智能体、人工参与工作流和任务转移。它同时支持同步和异步方法。该集成只需要一个 SQLite 或 Postgres 数据库。查看集成[仓库](https://github.com/dbos-inc/dbos-openai-agents)和[文档](https://docs.dbos.dev/integrations/openai-agents)以获取更多详细信息。 +你可以使用 Agents SDK [DBOS](https://dbos.dev/) 集成来运行可靠的智能体，它们可在失败和重启之间保留进度。它支持长时间运行的智能体、人类参与回路工作流和任务转移。它同时支持同步和异步方法。该集成仅需要 SQLite 或 Postgres 数据库。查看集成[仓库](https://github.com/dbos-inc/dbos-openai-agents)和[文档](https://docs.dbos.dev/integrations/openai-agents)以获取更多详情。 ## 异常 -SDK 在某些情况下会引发异常。完整列表位于 [`agents.exceptions`][]。概览如下： +SDK 会在某些情况下抛出异常。完整列表位于 [`agents.exceptions`][]。概览如下： -- [`AgentsException`][agents.exceptions.AgentsException]：这是 SDK 内部引发的所有异常的基类。它作为通用类型，所有其他特定异常都派生自它。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]：当智能体的运行超过传递给 `Runner.run`、`Runner.run_sync` 或 `Runner.run_streamed` 方法的 `max_turns` 限制时，会引发此异常。它表示智能体无法在指定数量的交互轮次内完成任务。设置 `max_turns=None` 可禁用该限制。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：当底层模型（LLM）生成意外或无效输出时，会发生此异常。这可能包括： +- [`AgentsException`][agents.exceptions.AgentsException]：这是 SDK 内部抛出的所有异常的基类。它是一个通用类型，所有其他特定异常都派生自它。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]：当智能体运行超过传给 `Runner.run`、`Runner.run_sync` 或 `Runner.run_streamed` 方法的 `max_turns` 限制时，会抛出此异常。它表示智能体未能在指定的交互轮数内完成任务。设置 `max_turns=None` 可禁用限制。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：当底层模型（LLM）生成意外或无效的输出时，会发生此异常。这可能包括： - 格式错误的 JSON：当模型为工具调用或在其直接输出中提供格式错误的 JSON 结构时，尤其是在定义了特定 `output_type` 的情况下。 - - 意外的工具相关失败：当模型未能以预期方式使用工具时 -- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]：当工具调用超过其配置的超时时间，并且该工具使用 `timeout_behavior="raise_exception"` 时，会引发此异常。 -- [`UserError`][agents.exceptions.UserError]：当你（使用 SDK 编写代码的人）在使用 SDK 时出错，会引发此异常。这通常源于不正确的代码实现、无效配置或误用 SDK API。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered]、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]：当分别满足输入安全防护措施或输出安全防护措施的条件时，会引发此异常。输入安全防护措施会在处理前检查传入消息，而输出安全防护措施会在交付前检查智能体的最终响应。 \ No newline at end of file + - 意外的工具相关故障：当模型未能按预期方式使用工具时 +- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]：当工具调用超过其配置的超时时间，并且该工具使用 `timeout_behavior="raise_exception"` 时，会抛出此异常。 +- [`UserError`][agents.exceptions.UserError]：当你（使用 SDK 编写代码的人）在使用 SDK 时出错，会抛出此异常。这通常是由错误的代码实现、无效配置或误用 SDK 的 API 导致的。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered]、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]：当输入安全防护措施或输出安全防护措施的条件分别满足时，会抛出此异常。输入安全防护措施会在处理前检查传入消息，而输出安全防护措施会在交付前检查智能体的最终响应。 \ No newline at end of file