컨텍스트 관리

컨텍스트는 여러 의미로 쓰이는 용어입니다. 관심을 가질 만한 컨텍스트에는 크게 두 가지 클래스가 있습니다.

실행 중 코드가 접근할 수 있는 로컬 컨텍스트: 도구에 필요한 종속성이나 데이터, 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이 호출될 때 LLM이 볼 수 있는 유일한 데이터는 대화 기록에서 옵니다. 추가 정보를 사용할 수 있게 하려면 몇 가지 옵션이 있습니다.

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