コンテキスト管理

コンテキストという用語は多義的です。主に気にするべきコンテキストには 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 など）
ロガーやデータフェッチャーのような依存関係
ヘルパー関数

単一の実行内では、派生コンテキストは同じ基盤アプリコンテキスト、承認、使用量追跡を共有します。ネストされた agent.asTool() 実行では別の toolInput が付与される場合がありますが、デフォルトではアプリ状態の分離されたコピーは取得しません。

`RunContext` の公開要素

RunContext<T> は、アプリで定義したコンテキストオブジェクトのラッパーです。実際には、主に次を使います。

runContext.context: アプリ独自の可変な状態と依存関係
runContext.usage: 現在の実行における集計済みのトークン / リクエスト使用量
runContext.toolInput: 現在の実行が agent.asTool() 内で動作しているときの構造化入力
runContext.approveTool(...) / runContext.rejectTool(...): 承認状態をプログラムから更新する必要がある場合

アプリ定義のオブジェクトは runContext.context のみです。その他のフィールドは SDK が管理する実行時メタデータです。

後で human-in-the-loop のために RunState をシリアライズする場合、その実行時メタデータは状態とともに保存されます。シリアライズした状態を永続化または送信する予定があるなら、runContext.context にシークレットを入れるのは避けてください。

RunContext をサブクラス化する場合は、ネストされた実行や派生実行でも、依存しているサブクラス固有のインスタンス状態が保持されることを確認してください。SDK はネスト実行中に内部でフォークされたコンテキストを作成します。

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

LLM が呼び出されるとき、参照できるデータは会話履歴に含まれるものだけです。追加情報を使えるようにするには、いくつか方法があります。

エージェントの instructions に追加する（システムメッセージまたは開発者メッセージとも呼ばれます）。これは静的な文字列でも、コンテキストを受け取って文字列を返す関数でも構いません
Runner.run() 呼び出し時の input に含める。これは instructions の手法に似ていますが、chain of command のより下位にメッセージを置けます
関数ツールとして公開し、LLM が必要時にデータを取得できるようにする
取得（retrieval）や Web 検索ツールを使い、ファイル、データベース、または Web の関連データに基づいてレスポンスを生成する