コンテキスト管理
「コンテキスト」という用語は、複数の意味で使われます。ここで関係するコンテキストは、大きく 2 種類に分けられます。
- ローカルコンテキスト は、実行中にコードからアクセスできるものです。ツール、
onHandoffなどのコールバック、ライフサイクルフックが必要とする依存関係やデータを含みます。 - LLM から見えるコンテキスト は、応答を生成する際に言語モデルが参照できるものです。
ローカルコンテキスト
Section titled “ローカルコンテキスト”ローカルコンテキストは、RunContext<T> 型で表されます。状態や依存関係を保持する任意のオブジェクトを作成し、Runner.run() に渡します。すべてのツール呼び出しとフックは RunContext ラッパーを受け取り、そのオブジェクトを読み取ったり変更したりできます。
import { Agent, run, RunContext, tool } from '@openai/agents';import { z } from 'zod';
interface UserInfo { name: string; uid: number;}
const fetchUserAge = tool({ name: 'fetch_user_age', description: 'Return the age of the current user', parameters: z.object({}), execute: async ( _args, runContext?: RunContext<UserInfo>, ): Promise<string> => { return `User ${runContext?.context.name} is 47 years old`; },});
async function main() { const userInfo: UserInfo = { name: 'John', uid: 123 };
const agent = new Agent<UserInfo>({ name: 'Assistant', tools: [fetchUserAge], });
const result = await run(agent, 'What is the age of the user?', { context: userInfo, });
console.log(result.finalOutput); // The user John is 47 years old.}
main().catch((error) => { console.error(error); process.exit(1);});単一の実行に参加するすべてのエージェント、ツール、フックは、同じ 型 のコンテキストを使用する必要があります。
ローカルコンテキストは、次のような用途に使用します。
- 実行に関するデータ(ユーザー名、ID など)
- ロガーやデータ取得処理などの依存関係
- ヘルパー関数
単一の実行内では、派生コンテキストは基盤となる同じアプリケーションコンテキスト、承認情報、使用量の追跡情報を共有します。ネストされた agent.asTool() の実行には、異なる toolInput が付与される場合がありますが、デフォルトではアプリケーションの状態の独立したコピーは作成されません。
ローカルコンテキストによる機能の可視性の制御
Section titled “ローカルコンテキストによる機能の可視性の制御”関数ツール、ローカル MCP ツール、ハンドオフが同じリクエストポリシーに依存する場合は、ポリシーの入力値やヘルパーをアプリケーションコンテキストに保持してください。SDK の各インターフェースは、それぞれのコールバックを通じて現在の実行コンテキストを公開します。
tool()で作成した関数ツールのisEnabled述語は、runContextプロパティに現在のRunContextを持つオブジェクトを受け取ります。- ハンドオフの
isEnabled述語は、runContextプロパティに現在のRunContextを持つオブジェクトを受け取ります。 - 呼び出し可能な MCP
toolFilterは、runContextプロパティに現在のRunContextを持つMCPToolFilterContextを受け取ります。
機能のリストを個別に管理するのではなく、共通のアプリケーションポリシーをこれらのコールバックに適用してください。コールバックは、SDK が現在のターンでどの機能をモデルに公開するかを制御します。モデルがツールやハンドオフの引数を生成する前に実行されるため、モデルが生成した引数やリソースの選択を認可することはできません。関数ツールでは、そのような認可判断を execute 内で適用するか、必要に応じて ツール入力のガードレール と 人間の介入(HITL) による承認を追加してください。MCP サーバーは、保護対象の操作について自ら認可を行う必要があります。inputType を持つハンドオフでは、onHandoff の冒頭で、アプリケーションの副作用が発生する前にパース済みの入力を確認し、認可に失敗した場合は例外をスローしてください。onHandoff が正常に終了すると引き継ぎが続行されます。また、ツール入力のガードレールはハンドオフでは実行されません。コールバックのライフサイクルについては、ハンドオフの入力 を参照してください。
呼び出し可能な MCP toolFilter がリクエストコンテキストに依存する場合は、エージェントが管理するサーバーの cacheToolsList を無効のままにしてください。キャッシュエントリにはフィルタリング済みのツールリストが含まれますが、呼び出し可能なフィルターのデフォルトのキャッシュキーは、リクエストコンテキストごとに区別されません。getAllMcpTools(...) を直接呼び出すコードでは、代わりに、関連するポリシーの識別情報を含む generateMCPToolCacheKey を指定できます。MCP のキャッシュに関するガイダンス を参照してください。
RunContext が公開する情報
Section titled “RunContext が公開する情報”RunContext<T> は、アプリケーションで定義したコンテキストオブジェクトのラッパーです。実際には、主に次のものを使用します。
runContext.contextは、独自の変更可能なアプリケーションの状態や依存関係に使用します。runContext.usageは、現在の実行で集計されたトークンやリクエストの使用量に使用します。runContext.toolInputは、現在の実行がagent.asTool()内で行われている場合の構造化された入力に使用します。runContext.approveTool(...)/runContext.rejectTool(...)は、承認状態をプログラムから更新する必要がある場合に使用します。
アプリケーションで定義したオブジェクトは runContext.context だけです。その他のフィールドは、SDK が管理するランタイムメタデータです。
後で 人間の介入(HITL) のために RunState をシリアライズすると、そのランタイムメタデータも状態とともに保存されます。シリアライズした状態を永続化または送信する予定がある場合は、runContext.context に機密情報を入れないでください。
RunContext をサブクラス化する場合は、ネストされた実行や派生した実行でも、利用しているサブクラス固有のインスタンス状態が保持されることを確認してください。SDK は、ネストされた実行中に内部でコンテキストを分岐させます。
LLM から見えるコンテキスト
Section titled “LLM から見えるコンテキスト”LLM が呼び出されるとき、参照できるデータは会話履歴に含まれるものだけです。追加の情報を利用できるようにするには、いくつかの方法があります。
- エージェントの
instructions(システムメッセージまたは開発者メッセージとも呼ばれます)に追加します。これは固定の文字列でも、コンテキストを受け取って文字列を返す関数でもかまいません。 Runner.run()を呼び出すときにinputに含めます。これは instructions を使う方法に似ていますが、指示の優先順位 でメッセージをより低い位置に置くことができます。- 関数ツールを通じて追加情報を公開し、LLM が必要に応じてその情報を取得できるようにします。
- 検索ツールや Web 検索ツールを使用し、ファイル、データベース、Web にある関連データに基づいた応答を生成します。