エージェントの実行

エージェントは Runner クラスで実行できます。方法は 3 つあります:

Runner.run(): 非同期で実行され、RunResult を返します。
Runner.run_sync(): 同期メソッドで、内部的には .run() を実行します。
Runner.run_streamed(): 非同期で実行され、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

詳細は実行結果ガイドを参照してください。

エージェントループ

Runner の run メソッドを使うとき、開始するエージェントと入力を渡します。入力は文字列（ユーザーメッセージと見なされます）か、OpenAI Responses API のアイテムに相当する入力アイテムのリストのどちらかです。

Runner は次のループを実行します:

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

Note

LLM の出力が「最終出力 (final output)」と見なされる条件は、望ましい型のテキスト出力を生成し、ツール呼び出しがないことです。

ストリーミング

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

実行設定

run_config パラメーターでは、エージェント実行のグローバル設定を構成できます:

model: 各 Agent の model 設定に関わらず、使用するグローバルな LLM モデルを設定します。
model_provider: モデル名を解決するためのモデルプロバイダーで、デフォルトは OpenAI です。
model_settings: エージェント固有の設定を上書きします。たとえば、グローバルな temperature や top_p を設定できます。
input_guardrails, output_guardrails: すべての実行に含める入力/出力のガードレールのリストです。
handoff_input_filter: ハンドオフに対して、既に設定されていない場合に適用するグローバルな入力フィルターです。入力フィルターにより、新しいエージェントへ送る入力を編集できます。詳細は Handoff.input_filter のドキュメントを参照してください。
tracing_disabled: 実行全体の trレーシングを無効化できます。
trace_include_sensitive_data: LLM やツール呼び出しの入出力など、機微なデータをトレースに含めるかどうかを設定します。
workflow_name, trace_id, group_id: この実行のトレーシングのワークフロー名、trace ID、トレースグループ ID を設定します。少なくとも workflow_name の設定を推奨します。グループ ID は任意で、複数の実行にまたがるトレースを関連付けるのに使えます。
trace_metadata: すべてのトレースに含めるメタデータです。

会話/チャットスレッド

いずれの run メソッドを呼び出しても、1 つ以上のエージェント（つまり 1 回以上の LLM 呼び出し）が実行される場合がありますが、チャット会話における 1 回の論理ターンを表します。例:

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

エージェントの実行が終わったら、ユーザーに何を表示するかを選べます。たとえば、エージェントが生成したすべての新しいアイテムを表示することも、最終出力だけを表示することもできます。いずれの場合も、ユーザーがフォローアップの質問をする可能性があり、その場合は再度 run メソッドを呼び出せます。

手動の会話管理

次のターンの入力を取得するために、RunResultBase.to_input_list() メソッドを使って、会話履歴を手動で管理できます:

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

    thread_id = "thread_123"  # Example thread ID
    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

Sessions による自動会話管理

より簡単な方法として、Sessions を使うと、.to_input_list() を手動で呼び出さずに会話履歴を自動的に処理できます:

from agents import Agent, Runner, SQLiteSession

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

    # Create session instance
    session = SQLiteSession("conversation_123")

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

        # Second turn - agent automatically remembers previous context
        result = await Runner.run(agent, "What state is it in?", session=session)
        print(result.final_output)
        # California

Sessions は自動で以下を行います:

各実行前に会話履歴を取得
各実行後に新しいメッセージを保存
異なるセッション ID ごとに個別の会話を維持

詳細は Sessions のドキュメントを参照してください。

長時間実行エージェントと人間参加 (human-in-the-loop)

Agents SDK の Temporal 連携を使うと、human-in-the-loop タスクを含む耐久性のある長時間実行ワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモはこの動画を参照し、こちらのドキュメントも参照してください。

例外

SDK は特定の状況で例外を送出します。完全な一覧は agents.exceptions にあります。概要は次のとおりです:

AgentsException: SDK 内で発生するすべての例外の基底クラスです。他の特定の例外はすべてこの型から派生します。
MaxTurnsExceeded: エージェントの実行が Runner.run、Runner.run_sync、Runner.run_streamed メソッドに渡した max_turns 制限を超えた場合に送出されます。指定されたインタラクション回数内にエージェントがタスクを完了できなかったことを示します。
ModelBehaviorError: 基盤のモデル (LLM) が想定外または無効な出力を生成したときに発生します。例:
- 不正な JSON: 特定の output_type が定義されている場合などに、ツール呼び出しや直接の出力で不正な JSON 構造を返したとき
- 想定外のツール関連の失敗: モデルが期待された方法でツールを使用できなかったとき
UserError: SDK を使用するあなた（この SDK を用いてコードを書く人）が誤りを犯した場合に送出されます。これは通常、不正なコード実装、無効な設定、または SDK の API の誤用が原因です。
InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered: それぞれ入力ガードレールや出力ガードレールの条件が満たされたときに送出されます。入力ガードレールは処理前に受信メッセージをチェックし、出力ガードレールは配信前にエージェントの最終応答をチェックします。