コンテキスト管理
コンテキストという語は多義的です。主に気に掛けるべきコンテキストには、次の 2 種類があります。
- コード内でローカルに利用できるコンテキスト: これはツール関数の実行時や
on_handoff
のようなコールバック、ライフサイクルフックなどで必要となるデータや依存関係です。 - LLM が利用できるコンテキスト: これは LLM がレスポンスを生成する際に参照できるデータです。
ローカルコンテキスト
ローカルコンテキストは RunContextWrapper
クラスと、その中の context
プロパティによって表現されます。仕組みは以下のとおりです。
- 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトがよく使われます。
- そのオブジェクトを各種
run
メソッド(例:Runner.run(..., **context=whatever**)
)に渡します。 - すべてのツール呼び出しやライフサイクルフックには
RunContextWrapper[T]
というラッパーオブジェクトが渡されます。ここでT
はコンテキストオブジェクトの型を表し、wrapper.context
からアクセスできます。
最も重要なのは、特定のエージェント実行(run)において、エージェント・ツール関数・ライフサイクルフックなどが 同じ型 のコンテキストを共有しなければならない点です。
コンテキストは次のような用途で利用できます。
- 実行時の状況依存データ(例: ユーザー名 / UID やユーザーに関するその他情報)
- 依存関係(例: ロガーオブジェクト、データフェッチャーなど)
- ヘルパー関数
Note
コンテキストオブジェクトは LLM に送信されません。純粋にローカルなオブジェクトであり、読み書きやメソッド呼び出しのみが行えます。
import asyncio
from dataclasses import dataclass
from agents import Agent, RunContextWrapper, Runner, function_tool
@dataclass
class UserInfo: # (1)!
name: str
uid: int
@function_tool
async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str: # (2)!
"""Fetch the age of the user. Call this function to get user's age information."""
return f"The user {wrapper.context.name} is 47 years old"
async def main():
user_info = UserInfo(name="John", uid=123)
agent = Agent[UserInfo]( # (3)!
name="Assistant",
tools=[fetch_user_age],
)
result = await Runner.run( # (4)!
starting_agent=agent,
input="What is the age of the user?",
context=user_info,
)
print(result.final_output) # (5)!
# The user John is 47 years old.
if __name__ == "__main__":
asyncio.run(main())
- これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を利用できます。
- これはツールです。
RunContextWrapper[UserInfo]
を受け取り、実装側でコンテキストを読み取ります。 - エージェントをジェネリック型
UserInfo
でマークし、型チェッカーでエラーを検出できるようにします(例: 別のコンテキスト型を受け取るツールを渡そうとした場合)。 run
関数にコンテキストを渡します。- エージェントはツールを正しく呼び出し、年齢を取得します。
エージェント/LLM コンテキスト
LLM が呼び出されるとき、LLM が参照可能なデータは会話履歴だけです。そのため、新しいデータを LLM に渡したい場合は、そのデータが会話履歴に含まれるようにしなければなりません。方法は次のとおりです。
- Agent の
instructions
に追加する。これは「system prompt」や「developer message」とも呼ばれます。System prompt は静的な文字列でも、コンテキストを受け取って文字列を返す動的関数でも構いません。たとえばユーザー名や現在の日付など、常に役立つ情報を渡す一般的な方法です。 Runner.run
を呼び出す際のinput
に追加する。この方法はinstructions
と似ていますが、chain of command でより下位にメッセージを配置できます。- 関数ツールを通じて公開する。これはオンデマンドで使うコンテキストに適しています。LLM が必要と判断したときにツールを呼び出してデータを取得できます。
- リトリーバルや Web 検索を使用する。これらはファイルやデータベースから関連データを取得する(リトリーバル)あるいは Web から取得する(Web 検索)特別なツールです。レスポンスを関連コンテキストに基づいて「グラウンディング」したい場合に便利です。