컨텍스트 관리

컨텍스트는 여러 의미로 사용되는 용어입니다. 고려해야 할 컨텍스트는 크게 두 가지로 나뉩니다.

로컬 컨텍스트: 실행 중 코드에서 액세스할 수 있는 컨텍스트로, 도구에 필요한 종속성이나 데이터, 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: 현재 실행의 집계된 토큰/요청 사용량
runContext.toolInput: 현재 실행이 agent.asTool() 내부에서 수행될 때 사용하는 구조화된 입력
runContext.approveTool(...) / runContext.rejectTool(...): 프로그래밍 방식으로 승인 상태를 업데이트해야 할 때 사용

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

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

RunContext를 서브클래싱하는 경우 중첩되거나 파생된 실행에서도 사용하는 서브클래스별 인스턴스 상태가 계속 유지되는지 확인하세요. SDK는 중첩 실행 중 내부적으로 분기된 컨텍스트를 생성합니다.

LLM에 표시되는 컨텍스트

LLM이 호출될 때 볼 수 있는 데이터는 대화 기록에서만 제공됩니다. 추가 정보를 제공하는 방법은 다음과 같습니다.

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