コンテキスト管理

コンテキストという語は多義的です。気にすべきコンテキストには主に 2 つの種類があります。

コードからローカルに利用できるコンテキスト: これは、ツール関数の実行時、on_handoff のようなコールバック、ライフサイクルフックなどで必要となるデータや依存関係です。
LLM に提供されるコンテキスト: これは、LLM が応答を生成する際に目にできるデータです。

ローカルコンテキスト

これは RunContextWrapper クラスと、その中の context プロパティによって表現されます。仕組みは次のとおりです。

任意の Python オブジェクトを作成します。一般的なパターンとしては、dataclass や Pydantic オブジェクトを使います。
そのオブジェクトを各種の実行メソッド（例: Runner.run(..., **context=whatever**)）に渡します。
すべてのツール呼び出しやライフサイクルフックなどには、RunContextWrapper[T] というラッパーオブジェクトが渡されます。ここで T はコンテキストオブジェクトの型を表し、wrapper.context からアクセスできます。

最も重要な点 は、特定のエージェント実行におけるすべてのエージェント、ツール関数、ライフサイクルなどが、同じ「型」のコンテキストを使用しなければならないことです。

コンテキストは次のような用途に使えます。

実行のためのコンテキストデータ（例: ユーザー名 / UID など、ユーザーに関する情報）
依存関係（例: ロガーオブジェクト、データフェッチャーなど）
ヘルパー関数

注意

コンテキストオブジェクトは 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 関数に渡されます。
エージェントはツールを正しく呼び出して年齢を取得します。

上級: `ToolContext`

場合によっては、実行中のツールに関する追加メタデータ（名前、コール ID、raw な引数文字列など）へアクセスしたいことがあります。
そのために、RunContextWrapper を拡張した ToolContext クラスを使えます。

from typing import Annotated
from pydantic import BaseModel, Field
from agents import Agent, Runner, function_tool
from agents.tool_context import ToolContext

class WeatherContext(BaseModel):
    user_id: str

class Weather(BaseModel):
    city: str = Field(description="The city name")
    temperature_range: str = Field(description="The temperature range in Celsius")
    conditions: str = Field(description="The weather conditions")

@function_tool
def get_weather(ctx: ToolContext[WeatherContext], city: Annotated[str, "The city to get the weather for"]) -> Weather:
    print(f"[debug] Tool context: (name: {ctx.tool_name}, call_id: {ctx.tool_call_id}, args: {ctx.tool_arguments})")
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

agent = Agent(
    name="Weather Agent",
    instructions="You are a helpful agent that can tell the weather of a given city.",
    tools=[get_weather],
)

ToolContext は RunContextWrapper と同じ .context プロパティに加えて、
現在のツール呼び出しに固有の次のフィールドを提供します。

tool_name – 呼び出されるツールの名前
tool_call_id – このツール呼び出しの一意な識別子
tool_arguments – ツールに渡された raw な引数文字列

実行中にツールレベルのメタデータが必要な場合は ToolContext を使用してください。
エージェントとツール間で一般的にコンテキストを共有するだけであれば、RunContextWrapper で十分です。

エージェント / LLM のコンテキスト

LLM が呼び出されるとき、LLM が目にできるデータは会話履歴に含まれるもののみです。したがって、新しいデータを LLM に利用可能にしたい場合は、その履歴で利用できるようにする必要があります。方法はいくつかあります。

エージェントの instructions に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的な関数でもかまいません。これは常に有用な情報（例: ユーザーの名前や現在の日付）に適した一般的な手法です。
Runner.run を呼び出すときの input に追加します。これは instructions の手法に似ていますが、指揮系統の下位にあるメッセージを持てます。
関数ツールで公開します。これはオンデマンドのコンテキストに有用です。LLM がいつデータを必要とするかを判断し、そのデータを取得するためにツールを呼び出せます。
リトリーバルまたは Web 検索を使用します。これらは、ファイルやデータベース（リトリーバル）、または Web（Web 検索）から関連データを取得できる特別なツールです。これは、関連するコンテキストデータで応答を「根拠付け」るのに有用です。

コンテキスト管理

ローカルコンテキスト

上級: ToolContext

エージェント / LLM のコンテキスト

上級: `ToolContext`