admin-valentin/openai-agents-python
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
openai-agents-python/docs/ja/running_agents.md
Kazuhiro Sera ece647b93f
Add i18n support to the documents (#460)
2025-04-08 09:41:48 -04:00

7.7 KiB
Raw Blame History

エージェントの実行

エージェントは [Runner][agents.run.Runner] クラスを通じて実行できます。以下の 3 つの方法があります。

  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 をストリーミングモードで呼び出し、受信したイベントを順次ストリームします。
from agents import Agent, Runner

async def main():
    agent = Agent(name="Assistant", instructions="You are a helpful assistant")

    result = await Runner.run(agent, "Write a haiku about recursion in programming.")
    print(result.final_output)
    # Code within the code,
    # Functions calling themselves,
    # Infinite loop's dance.

詳細は results ガイド を参照してください。

エージェントの実行ループ

Runner の run メソッドを使用する際、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージとして扱われる）または OpenAI Responses API の項目リストのいずれかです。

Runner は以下のループを実行します。

  1. 現在のエージェントと入力を用いて LLM を呼び出します。
  2. LLM が出力を生成します。
    1. LLM が final_output を返した場合、ループを終了し結果を返します。
    2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、再度ループを実行します。
    3. LLM がツール呼び出しを生成した場合、それらのツール呼び出しを実行し、結果を追加して再度ループを実行します。
  3. 指定された max_turns を超えた場合、[MaxTurnsExceeded][agents.exceptions.MaxTurnsExceeded] 例外を発生させます。

!!! note

LLM の出力が「最終出力（final output）」とみなされる条件は、望ましいタイプのテキスト出力を生成し、かつツール呼び出しがない場合です。

ストリーミング

ストリーミングを使用すると、LLM の実行中にストリーミングイベントを受け取ることができます。ストリームが完了すると、[RunResultStreaming][agents.result.RunResultStreaming] に実行に関する完全な情報（生成されたすべての新しい出力を含む）が格納されます。ストリーミングイベントを取得するには .stream_events() を呼び出します。詳細は streaming ガイド を参照してください。

実行設定（Run config）

run_config パラメータを使用すると、エージェント実行時のグローバル設定を構成できます。

  • [model][agents.run.RunConfig.model]：各エージェントの model 設定に関係なく、グローバルな LLM モデルを指定します。
  • [model_provider][agents.run.RunConfig.model_provider]：モデル名を検索するためのモデルプロバイダーを指定します（デフォルトは OpenAI）。
  • [model_settings][agents.run.RunConfig.model_settings]：エージェント固有の設定を上書きします。例えば、グローバルな temperature や top_p を設定できます。
  • [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] のドキュメントを参照してください。
  • [tracing_disabled][agents.run.RunConfig.tracing_disabled]：実行全体の トレーシング を無効にします。
  • [trace_include_sensitive_data][agents.run.RunConfig.trace_include_sensitive_data]：トレースに LLM やツール呼び出しの入出力など、機密性の高いデータを含めるかどうかを設定します。
  • [workflow_name][agents.run.RunConfig.workflow_name]、[trace_id][agents.run.RunConfig.trace_id]、[group_id][agents.run.RunConfig.group_id]：トレーシングのワークフロー名、トレース ID、トレースグループ ID を設定します。少なくとも workflow_name を設定することを推奨します。グループ ID はオプションで、複数の実行間でトレースを関連付けることができます。
  • [trace_metadata][agents.run.RunConfig.trace_metadata]：すべてのトレースに含めるメタデータです。

会話／チャットスレッド

いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行され（したがって 1 つ以上の LLM 呼び出しが発生）、チャット会話における単一の論理的ターンを表します。例えば：

  1. ユーザーのターン：ユーザーがテキストを入力
  2. Runner の実行：最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントにハンドオフし、2 番目のエージェントがさらにツールを実行して出力を生成

エージェントの実行終了時に、ユーザーに何を表示するかを選択できます。例えば、エージェントが生成したすべての新しい項目を表示するか、最終出力のみを表示するかを選択できます。いずれの場合も、ユーザーが追加の質問をした場合、再度 run メソッドを呼び出します。

次のターンの入力を取得するには、基本クラスの [RunResultBase.to_input_list()][agents.result.RunResultBase.to_input_list] メソッドを使用できます。

async def main():
    agent = Agent(name="Assistant", instructions="Reply very concisely.")

    with trace(workflow_name="Conversation", group_id=thread_id):
        # First turn
        result = await Runner.run(agent, "What city is the Golden Gate Bridge in?")
        print(result.final_output)
        # San Francisco

        # Second turn
        new_input = result.to_input_list() + [{"role": "user", "content": "What state is it in?"}]
        result = await Runner.run(agent, new_input)
        print(result.final_output)
        # California

例外

SDK は特定の状況で例外を発生させます。完全なリストは [agents.exceptions][] にあります。概要は以下の通りです。

  • [AgentsException][agents.exceptions.AgentsException]：SDK 内で発生するすべての例外の基底クラスです。
  • [MaxTurnsExceeded][agents.exceptions.MaxTurnsExceeded]：実行が指定された max_turns を超えた場合に発生します。
  • [ModelBehaviorError][agents.exceptions.ModelBehaviorError]：モデルが不正な出力（不正な JSON や存在しないツールの使用など）を生成した場合に発生します。
  • [UserError][agents.exceptions.UserError]：SDK を使用するコードに誤りがある場合に発生します。
  • [InputGuardrailTripwireTriggered][agents.exceptions.InputGuardrailTripwireTriggered]、[OutputGuardrailTripwireTriggered][agents.exceptions.OutputGuardrailTripwireTriggered]：ガードレール がトリガーされた場合に発生します。