컨텍스트 관리

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

로컬 컨텍스트: 실행 중 코드에서 접근할 수 있는 컨텍스트로, 도구에 필요한 종속성이나 데이터, 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이 연결될 수 있지만, 기본적으로 애플리케이션 상태의 격리된 복사본이 제공되지는 않습니다.

기능 표시 여부를 위한 로컬 컨텍스트 사용

함수 도구, 로컬 MCP 도구, 핸드오프가 동일한 요청 정책에 의존하는 경우 정책 입력이나 헬퍼를 애플리케이션 컨텍스트에 유지합니다. 각 SDK 인터페이스는 자체 콜백을 통해 현재 실행 컨텍스트를 제공합니다.

tool()로 생성한 함수 도구의 isEnabled 조건자는 현재 RunContext를 runContext 속성으로 포함하는 객체를 받습니다.
핸드오프의 isEnabled 조건자는 현재 RunContext를 runContext 속성으로 포함하는 객체를 받습니다.
호출 가능한 MCP toolFilter는 현재 RunContext를 runContext 속성으로 포함하는 MCPToolFilterContext를 받습니다.

별도의 기능 목록을 관리하는 대신 공유 애플리케이션 정책을 이러한 콜백에 맞게 적용합니다. 콜백은 현재 턴에서 SDK가 모델에 표시되는 집합에 포함할 기능을 제어합니다. 이 콜백은 모델이 도구 또는 핸드오프 인수를 생성하기 전에 실행되므로 모델이 생성한 인수나 리소스 선택을 승인할 수 없습니다. 함수 도구의 경우 execute 내부에서 이러한 결정을 적용하거나, 필요한 경우 도구 입력 가드레일과 승인을 추가합니다. MCP 서버는 자체적으로 보호된 작업을 승인해야 합니다. inputType이 있는 핸드오프의 경우 애플리케이션 부작용이 발생하기 전에 onHandoff 시작 부분에서 파싱된 입력을 확인하고, 승인에 실패하면 예외를 발생시킵니다. onHandoff가 성공적으로 반환되면 전환이 계속되며, 도구 입력 가드레일은 핸드오프에 대해 실행되지 않습니다. 콜백 수명 주기는 핸드오프 입력을 참조하세요.

호출 가능한 MCP toolFilter가 요청 컨텍스트에 의존하는 경우 에이전트가 관리하는 서버에서 cacheToolsList를 비활성화 상태로 유지합니다. 캐시된 항목에는 이미 필터링된 도구 목록이 포함되지만, 호출 가능한 필터의 기본 캐시 키는 요청 컨텍스트별로 구분되지 않습니다. 대신 getAllMcpTools(...)를 직접 호출하는 코드는 관련 정책 ID를 포함하는 generateMCPToolCacheKey를 제공할 수 있습니다. MCP 캐싱 지침을 참조하세요.

`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 기법과 유사하지만 메시지를 명령 체계의 더 낮은 위치에 배치할 수 있습니다.
함수 도구를 통해 추가 정보를 노출하여 LLM이 필요할 때 해당 정보를 가져올 수 있도록 합니다.
검색 또는 웹 검색 도구를 사용하여 파일, 데이터베이스 또는 웹의 관련 데이터를 기반으로 응답을 생성하도록 합니다.