コンテキスト管理

コンテキストは多義的に使われる用語です。主に考慮すべきコンテキストには、次の 2 種類があります。

ローカルコンテキスト は、実行中にコードからアクセスできるコンテキストです。これには、ツールが必要とする依存関係やデータ、onHandoff などのコールバック、ライフサイクルフックが含まれます。
LLM から見えるコンテキスト は、言語モデルが回答を生成するときに参照できるコンテキストです。

ローカルコンテキスト

ローカルコンテキストは、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);
});

1 回の実行に関与するすべてのエージェント、ツール、フックでは、同じ型のコンテキストを使用する必要があります。

ローカルコンテキストは、次のような用途に使用します。

実行に関するデータ（ユーザー名、ID など）
ロガーやデータ取得機能などの依存関係
ヘルパー関数

1 回の実行内では、派生コンテキストは、基盤となる同一のアプリコンテキスト、承認状態、使用量の追跡情報を共有します。ネストされた agent.asTool() の実行には異なる toolInput が設定される場合がありますが、デフォルトではアプリ状態の独立したコピーは作成されません。

`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 から見えるコンテキスト

LLM が呼び出されたとき、LLM が参照できるデータは会話履歴に含まれるものだけです。追加情報を利用できるようにするには、次の選択肢があります。

エージェントの instructions に追加します。これは、システムメッセージまたは開発者メッセージとも呼ばれます。静的な文字列のほか、コンテキストを受け取って文字列を返す関数も使用できます。
Runner.run() を呼び出すときに input に含めます。これは instructions を使う方法と似ていますが、メッセージを指揮系統のより下位に配置できます。
関数ツールを通じて追加情報を公開し、LLM が必要に応じてその情報を取得できるようにします。
情報取得ツールまたは Web 検索ツールを使用し、ファイル、データベース、Web の関連データに基づいて回答を生成します。