エージェント
エージェントはアプリの中核となる構成要素です。エージェントは、 instructions とツールで構成された大規模言語モデル( LLM )です。
基本設定
エージェントで最も一般的に設定するプロパティは次のとおりです。
name
: エージェントを識別する必須の文字列です。instructions
: developer message または system prompt とも呼ばれます。model
: どの LLM を使うか、またmodel_settings
で temperature、top_p などのモデル調整パラメーターを設定できます。tools
: エージェントがタスクを達成するために使用できるツールです。
from agents import Agent, ModelSettings, function_tool
@function_tool
def get_weather(city: str) -> str:
"""returns weather info for the specified city."""
return f"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 オブジェクトをコンテキストとして提供できます。
@dataclass
class UserContext:
name: str
uid: str
is_pro_user: bool
async def fetch_purchases() -> list[Purchase]:
return ...
agent = Agent[UserContext](
...,
)
出力タイプ
デフォルトでは、エージェントはプレーンテキスト(つまり str
)の出力を生成します。特定のタイプの出力を生成したい場合は、output_type
パラメーターを使用できます。一般的な選択は Pydantic オブジェクトを使うことですが、Pydantic の TypeAdapter でラップできる任意の型(dataclasses、lists、TypedDict など)をサポートします。
from pydantic import BaseModel
from agents import Agent
class CalendarEvent(BaseModel):
name: str
date: str
participants: 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
はすべての ユーザー 対応を処理し、ツールとして公開された特化サブエージェントを呼び出します。詳しくは tools のドキュメントを参照してください。
from agents import Agent
booking_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.",
)
],
)
ハンドオフ
ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一のタスクに優れたモジュール型の特化エージェントが可能になります。詳しくは handoffs のドキュメントを参照してください。
from agents import Agent
booking_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
関数の両方が使用できます。
def dynamic_instructions(
context: RunContextWrapper[UserContext], agent: Agent[UserContext]
) -> str:
return f"The user's name is {context.context.name}. Help them with their questions."
agent = Agent[UserContext](
name="Triage agent",
instructions=dynamic_instructions,
)
ライフサイクルイベント(フック)
ときには、エージェントのライフサイクルを観測したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりすることです。hooks
プロパティでエージェントのライフサイクルにフックできます。AgentHooks
クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。
ガードレール
ガードレールにより、エージェントの実行と並行して ユーザー 入力に対するチェック/検証を実行し、エージェントの出力が生成された後にもチェック/検証を実行できます。たとえば、 ユーザー の入力とエージェントの出力を関連性でスクリーニングできます。詳しくは guardrails のドキュメントを参照してください。
エージェントの複製/コピー
エージェントで clone()
メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。
pirate_agent = Agent(
name="Pirate",
instructions="Write like a pirate",
model="gpt-4.1",
)
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 に必須にします。
from agents import Agent, Runner, function_tool, ModelSettings
@function_tool
def get_weather(city: str) -> str:
"""Returns weather info for the specified city."""
return f"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 処理は行いません。
from agents import Agent, Runner, function_tool, ModelSettings
@function_tool
def get_weather(city: str) -> str:
"""Returns weather info for the specified city."""
return f"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=[...])
: 指定したツールのいずれかが呼び出された場合に停止し、その出力を最終応答として使用します。
from agents import Agent, Runner, function_tool
from agents.agent import StopAtTools
@function_tool
def get_weather(city: str) -> str:
"""Returns weather info for the specified city."""
return f"The weather in {city} is sunny"
@function_tool
def sum_numbers(a: int, b: int) -> int:
"""Adds two numbers."""
return a + b
agent = 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 を継続するかを判断するカスタム関数です。
from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
from agents.agent import ToolsToFinalOutputResult
from typing import List, Any
@function_tool
def get_weather(city: str) -> str:
"""Returns weather info for the specified city."""
return f"The weather in {city} is sunny"
def custom_tool_handler(
context: RunContextWrapper[Any],
tool_results: List[FunctionToolResult]
) -> ToolsToFinalOutputResult:
"""Processes tool results to decide final output."""
for result in tool_results:
if result.output and "sunny" in result.output:
return ToolsToFinalOutputResult(
is_final_output=True,
final_output=f"Final weather: {result.output}"
)
return ToolsToFinalOutputResult(
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 が再びツール呼び出しを生成し続けることで発生します。