コンテキスト管理

コンテキストという言葉には複数の意味があります。ここでは主に 2 つの種類のコンテキストを扱います。

ローカルコンテキスト — 実行中にコードからアクセスできるもの。ツールが必要とする依存関係やデータ、onHandoff のようなコールバック、ライフサイクルフックなど
エージェント／ LLM コンテキスト — 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.
}

if (require.main === module) {
  main().catch(console.error);
}

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

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

実行に関するデータ（ユーザー名、 ID など）
ロガーやデータフェッチャーなどの依存関係
ヘルパー関数

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

LLM が呼び出されるとき、 LLM が参照できるデータは会話履歴だけです。追加情報を渡すには次の方法があります。

エージェントの instructions に追加する — システムメッセージや開発者メッセージとも呼ばれます。静的な文字列でも、コンテキストを受け取って文字列を返す関数でも構いません。
Runner.run() を呼び出す際の input に含める。instructions を使う方法に似ていますが、メッセージを指揮系統内でより下位に配置できます。
関数ツールを介して公開し、 LLM が必要に応じてデータを取得できるようにする
リトリーバルツールや Web 検索ツールを使用し、ファイル・データベース・Web から関連データを取得して回答を裏付ける