컨텍스트 관리

컨텍스트는 여러 의미로 쓰이는 용어입니다. 주로 신경 써야 할 컨텍스트는 두 가지 주요 범주가 있습니다.

실행 중 코드에서 접근할 수 있는 로컬 컨텍스트: 도구에 필요한 의존성이나 데이터, 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);
});

단일 실행에 참여하는 모든 에이전트, 도구, 훅은 동일한 컨텍스트 타입을 사용해야 합니다.

로컬 컨텍스트는 다음과 같은 용도로 사용합니다.

실행 관련 데이터(사용자 이름, ID 등)
로거나 데이터 페처 같은 의존성
헬퍼 함수

단일 실행 내에서 파생된 컨텍스트는 동일한 기반 앱 컨텍스트, 승인, 사용량 추적을 공유합니다. 중첩된 agent.asTool() 실행은 다른 toolInput을 붙일 수 있지만, 기본적으로 앱 상태의 격리된 복사본을 받지는 않습니다.

`RunContext` 노출 항목

RunContext<T>는 앱에서 정의한 컨텍스트 객체를 감싸는 래퍼입니다. 실제로는 보통 다음을 가장 자주 사용합니다.

자체적으로 변경 가능한 앱 상태와 의존성을 위한 runContext.context
현재 실행의 집계된 토큰/요청 사용량을 위한 runContext.usage
현재 실행이 agent.asTool() 내부에서 동작할 때 구조화된 입력을 위한 runContext.toolInput
승인 상태를 코드로 갱신해야 할 때의 runContext.approveTool(...) / runContext.rejectTool(...)

runContext.context만 앱에서 정의한 객체입니다. 나머지 필드는 SDK가 관리하는 런타임 메타데이터입니다.

나중에 휴먼 인 더 루프 (HITL)를 위해 RunState를 직렬화하면, 해당 런타임 메타데이터도 상태와 함께 저장됩니다. 직렬화된 상태를 저장하거나 전송할 계획이라면 runContext.context에 비밀 정보를 넣지 마세요.

RunContext를 서브클래싱하는 경우, 중첩 실행이나 파생 실행에서도 의존하는 서브클래스별 인스턴스 상태가 유지되는지 확인하세요. SDK는 중첩 실행 중 내부적으로 포크된 컨텍스트를 생성합니다.

에이전트/LLM 컨텍스트

LLM이 호출될 때 모델이 볼 수 있는 데이터는 대화 히스토리에서 오는 것뿐입니다. 추가 정보를 사용할 수 있게 하려면 몇 가지 방법이 있습니다.

에이전트 instructions에 추가합니다. 이는 시스템 또는 개발자 메시지라고도 합니다. 정적 문자열일 수도 있고, 컨텍스트를 받아 문자열을 반환하는 함수일 수도 있습니다
Runner.run() 호출 시 input에 포함합니다. 이는 instructions 기법과 유사하지만, 메시지를 chain of command에서 더 낮은 위치에 둘 수 있습니다
함수 도구를 통해 노출하여 LLM이 필요할 때 데이터를 가져오도록 합니다
검색(retrieval) 또는 웹 검색 도구를 사용해 파일, 데이터베이스, 웹의 관련 데이터에 기반하도록 응답을 고정합니다