컨텍스트 관리

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

로컬 컨텍스트는 실행 중 코드가 접근할 수 있는 컨텍스트로, 도구에 필요한 종속성이나 데이터, 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이 필요할 때 데이터를 가져올 수 있도록 합니다.
검색 또는 웹 검색 도구를 사용하여 파일, 데이터베이스 또는 웹의 관련 데이터를 기반으로 응답을 생성하도록 합니다.