エージェント
エージェントはアプリの中核となる構成要素です。エージェントは、instructions とツールで設定された大規模言語モデル（ LLM ）です。
基本構成
エージェントで最も一般的に設定するプロパティは次のとおりです。
name: エージェントを識別する必須の文字列です。instructions: developer メッセージまたは system prompt とも呼ばれます。model: どの LLM を使用するか、またmodel_settingsで temperature、top_p などのモデル調整パラメーターを設定できます。tools: エージェントがタスクを達成するために使用できるツールです。
fromagentsimportAgent,ModelSettings,function_tool@function_tooldefget_weather(city:str)->str:"""returns weather info for the specified city."""returnf"The weather in{city} is sunny"agent=Agent(name="Haiku agent",instructions="Always respond in haiku form",model="gpt-5-nano",tools=[get_weather],)コンテキスト
エージェントはそのcontext 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、あなたが作成してRunner.run() に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行の依存関係と状態をまとめて保持します。コンテキストとして任意の Python オブジェクトを提供できます。
@dataclassclassUserContext:name:struid:stris_pro_user:boolasyncdeffetch_purchases()->list[Purchase]:return...agent=Agent[UserContext](...,)出力タイプ
デフォルトでは、エージェントはプレーンテキスト（すなわちstr）の出力を生成します。特定のタイプの出力を生成したい場合は、output_type パラメーターを使用できます。一般的な選択肢はPydantic オブジェクトですが、Pydantic のTypeAdapter でラップできる任意の型（dataclasses、list、TypedDict など）をサポートします。
frompydanticimportBaseModelfromagentsimportAgentclassCalendarEvent(BaseModel):name:strdate:strparticipants:list[str]agent=Agent(name="Calendar extractor",instructions="Extract calendar events from text",output_type=CalendarEvent,)Note
output_type を渡すと、モデルは通常のプレーンテキスト応答ではなくstructured outputs を使用するよう指示されます。
マルチ エージェントシステムの設計パターン
マルチ エージェントシステムの設計方法は多数ありますが、一般的に幅広く適用できるパターンとして次の 2 つがよく見られます。
- マネージャー（エージェントをツールとして）: 中央のマネージャー／オーケストレーターが、専門のサブエージェントをツールとして呼び出し、会話の制御を保持します。
- ハンドオフ: ピアのエージェントが制御を専門のエージェントに引き渡し、そのエージェントが会話を引き継ぎます。こちらは分散型です。
詳細は、エージェント構築の実践ガイドをご覧ください。
マネージャー（エージェントをツールとして）
customer_facing_agent はすべてのユーザー対応を処理し、ツールとして公開された専門のサブエージェントを呼び出します。詳細はツール のドキュメントをご覧ください。
fromagentsimportAgentbooking_agent=Agent(...)refund_agent=Agent(...)customer_facing_agent=Agent(name="Customer-facing agent",instructions=("Handle all direct user communication. ""Call the relevant tools when specialized expertise is needed."),tools=[booking_agent.as_tool(tool_name="booking_expert",tool_description="Handles booking questions and requests.",),refund_agent.as_tool(tool_name="refund_expert",tool_description="Handles refund questions and requests.",)],)ハンドオフ
ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントが会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一のタスクに秀でたモジュール式で専門的なエージェントが実現します。詳細はハンドオフ のドキュメントをご覧ください。
fromagentsimportAgentbooking_agent=Agent(...)refund_agent=Agent(...)triage_agent=Agent(name="Triage agent",instructions=("Help the user with their questions. ""If they ask about booking, hand off to the booking agent. ""If they ask about refunds, hand off to the refund agent."),handoffs=[booking_agent,refund_agent],)動的 instructions
多くの場合、エージェントの作成時に instructions を指定できますが、関数を介して動的な instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数とasync 関数のどちらも使用できます。
defdynamic_instructions(context:RunContextWrapper[UserContext],agent:Agent[UserContext])->str:returnf"The user's name is{context.context.name}. Help them with their questions."agent=Agent[UserContext](name="Triage agent",instructions=dynamic_instructions,)ライフサイクルイベント（フック）
エージェントのライフサイクルを観測したい場合があります。たとえば、イベントをログに記録したり、特定のイベントが発生したときにデータを事前取得したりできます。hooks プロパティでエージェントのライフサイクルにフックできます。AgentHooks クラスをサブクラス化し、関心のあるメソッドをオーバーライドします。
ガードレール
ガードレールにより、エージェントの実行と並行してユーザー入力に対するチェック／検証を行い、生成後のエージェント出力に対してもチェックできます。たとえば、ユーザー入力とエージェント出力の関連性をスクリーニングできます。詳細はガードレール のドキュメントをご覧ください。
エージェントのクローン／コピー
エージェントのclone() メソッドを使うと、エージェントを複製し、必要に応じて任意のプロパティを変更できます。
pirate_agent=Agent(name="Pirate",instructions="Write like a pirate",model="gpt-5.2",)robot_agent=pirate_agent.clone(name="Robot",instructions="Write like a robot",)ツール使用の強制
ツールのリストを指定しても、必ずしも LLM がツールを使用するとは限りません。ModelSettings.tool_choice を設定してツール使用を強制できます。有効な値は次のとおりです。
auto: LLM がツールを使用するかどうかを判断します。required: LLM にツールの使用を要求します（ただし、どのツールを使うかは賢く判断できます）。none: LLM にツールを使用しない（not）よう要求します。- 特定の文字列（例:
my_tool）を設定すると、LLM にその特定のツールを使用させます。
fromagentsimportAgent,Runner,function_tool,ModelSettings@function_tooldefget_weather(city:str)->str:"""Returns weather info for the specified city."""returnf"The weather in{city} is sunny"agent=Agent(name="Weather Agent",instructions="Retrieve weather details.",tools=[get_weather],model_settings=ModelSettings(tool_choice="get_weather"))ツール使用の動作
Agent のtool_use_behavior パラメーターは、ツール出力の扱いを制御します。
"run_llm_again": デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。"stop_on_first_tool": 最初のツール呼び出しの出力を、その後の LLM 処理なしに最終応答として使用します。
fromagentsimportAgent,Runner,function_tool,ModelSettings@function_tooldefget_weather(city:str)->str:"""Returns weather info for the specified city."""returnf"The weather in{city} is sunny"agent=Agent(name="Weather Agent",instructions="Retrieve weather details.",tools=[get_weather],tool_use_behavior="stop_on_first_tool")StopAtTools(stop_at_tool_names=[...]): 指定したいずれかのツールが呼び出された時点で停止し、その出力を最終応答として使用します。
fromagentsimportAgent,Runner,function_toolfromagents.agentimportStopAtTools@function_tooldefget_weather(city:str)->str:"""Returns weather info for the specified city."""returnf"The weather in{city} is sunny"@function_tooldefsum_numbers(a:int,b:int)->int:"""Adds two numbers."""returna+bagent=Agent(name="Stop At Stock Agent",instructions="Get weather or sum numbers.",tools=[get_weather,sum_numbers],tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"]))ToolsToFinalOutputFunction: ツール結果を処理し、停止するか LLM を継続するかを決定するカスタム関数です。
fromagentsimportAgent,Runner,function_tool,FunctionToolResult,RunContextWrapperfromagents.agentimportToolsToFinalOutputResultfromtypingimportList,Any@function_tooldefget_weather(city:str)->str:"""Returns weather info for the specified city."""returnf"The weather in{city} is sunny"defcustom_tool_handler(context:RunContextWrapper[Any],tool_results:List[FunctionToolResult])->ToolsToFinalOutputResult:"""Processes tool results to decide final output."""forresultintool_results:ifresult.outputand"sunny"inresult.output:returnToolsToFinalOutputResult(is_final_output=True,final_output=f"Final weather:{result.output}")returnToolsToFinalOutputResult(is_final_output=False,final_output=None)agent=Agent(name="Weather Agent",instructions="Retrieve weather details.",tools=[get_weather],tool_use_behavior=custom_tool_handler)Note
無限ループを防ぐため、フレームワークはツール呼び出し後にtool_choice を自動的に "auto" にリセットします。この動作はagent.reset_tool_choice で設定可能です。無限ループは、ツール結果が LLM に送られ、tool_choice によって LLM がさらに別のツール呼び出しを生成し続けるために発生します。