エージェントの実行
エージェントは 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 が出力を生成します。
- LLM が
final_output
を返した場合、ループは終了し結果を返します。 - LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。
- LLM がツール呼び出しを生成した場合、それらを実行し結果を追加して再度ループを実行します。
- LLM が
- 渡された
max_turns
を超えた場合、MaxTurnsExceeded
例外を送出します。
Note
LLM 出力が「final output」と見なされる条件は、望ましい型のテキスト出力であり、かつツール呼び出しが 1 つも含まれていない場合です。
ストリーミング
ストリーミングを使うと、LLM 実行中にストリーミングイベントを受け取れます。ストリーム完了後、RunResultStreaming
には実行に関する完全な情報(生成されたすべての新しい出力を含む)が格納されます。.stream_events()
を呼び出してストリーミングイベントを取得してください。詳細は ストリーミングガイド を参照してください。
Run config
run_config
パラメーターでは、エージェント実行のグローバル設定を行えます。
model
: 各エージェントのmodel
設定に関わらず、グローバルで使用する LLM モデルを設定します。model_provider
: モデル名を解決するモデルプロバイダー。デフォルトは OpenAI です。model_settings
: エージェント固有の設定を上書きします。たとえば、グローバルなtemperature
やtop_p
を設定できます。input_guardrails
,output_guardrails
: すべての実行に含める入力/出力ガードレールのリスト。handoff_input_filter
: ハンドオフに個別のフィルターが設定されていない場合に適用されるグローバル入力フィルター。新しいエージェントへ送信される入力を編集できます。詳細はHandoff.input_filter
のドキュメントを参照してください。tracing_disabled
: 実行全体の トレーシング を無効化します。trace_include_sensitive_data
: LLM やツール呼び出しの入出力など、機微情報をトレースに含めるかどうかを設定します。workflow_name
,trace_id
,group_id
: 実行時のトレーシング用 workflow 名、trace ID、trace group ID を設定します。少なくともworkflow_name
の設定を推奨します。group ID は複数実行間でトレースを関連付けるための任意フィールドです。trace_metadata
: すべてのトレースに含めるメタデータ。
会話/チャットスレッド
いずれの run メソッドを呼び出しても、1 回の実行で 1 つ以上のエージェント(すなわち複数の LLM 呼び出し)が走る可能性がありますが、チャット会話としては 1 つの論理的ターンを表します。例:
- ユーザーターン: ユーザーがテキストを入力
- Runner 実行: 1 つ目のエージェントが 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 は次のことを自動で行います。
- 各実行前に会話履歴を取得
- 各実行後に新しいメッセージを保存
- 異なる session ID ごとに別々の会話を維持
詳細は Sessions ドキュメント を参照してください。
例外
特定の状況で SDK は例外を送出します。完全な一覧は agents.exceptions
にあります。概要は以下のとおりです。
AgentsException
: SDK が送出するすべての例外の基底クラスです。MaxTurnsExceeded
: 実行が run メソッドに渡したmax_turns
を超えた場合に送出されます。ModelBehaviorError
: モデルが不正な出力(不正な JSON や存在しないツールの呼び出しなど)を生成した場合に送出されます。UserError
: SDK を使用するコードの記述者であるあなたが誤った使い方をした場合に送出されます。InputGuardrailTripwireTriggered
,OutputGuardrailTripwireTriggered
: ガードレール がトリップした場合に送出されます。