컨텍스트 관리
컨텍스트는 여러 의미로 사용되는 용어입니다. 여기서 살펴볼 컨텍스트는 크게 두 가지입니다:
- 로컬 컨텍스트는 실행 중 코드에서 접근할 수 있는 컨텍스트입니다. 도구,
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는MCPToolFilterContext를 받으며, 이 객체의runContext속성은 현재RunContext입니다.
별도의 기능 목록을 유지하는 대신, 공유 애플리케이션 정책을 이러한 콜백에 맞게 적용합니다. 콜백은 SDK가 현재 턴에서 모델에 표시되는 집합에 어떤 기능을 포함할지 제어합니다. 콜백은 모델이 도구나 핸드오프 인수를 생성하기 전에 실행되므로, 모델이 생성한 인수나 선택한 리소스에 대한 권한을 검증할 수 없습니다. 함수 도구의 경우 execute 내부에서 이러한 권한 검증을 적용하거나, 필요에 따라 도구 입력 가드레일과 휴먼 인 더 루프 (HITL) 승인을 추가합니다. MCP 서버는 자체적으로 보호 대상 작업에 대한 권한을 검증해야 합니다. inputType이 있는 핸드오프의 경우 애플리케이션에 부수 효과가 발생하기 전인 onHandoff 시작 시점에 파싱된 입력을 확인하고, 권한 검증에 실패하면 예외를 발생시켜야 합니다. onHandoff가 정상적으로 반환되면 제어권 이전이 계속되며, 핸드오프에는 도구 입력 가드레일이 실행되지 않습니다. 콜백의 수명 주기는 핸드오프 입력을 참고하세요.
호출 가능한 MCP toolFilter가 요청 컨텍스트에 의존한다면 에이전트가 관리하는 서버의 cacheToolsList를 비활성화 상태로 유지합니다. 캐시 항목에는 이미 필터링된 도구 목록이 들어 있지만, 호출 가능한 필터의 기본 캐시 키는 요청 컨텍스트별로 구분되지 않습니다. getAllMcpTools(...)를 직접 호출하는 코드는 대신 관련 정책 식별 정보를 포함하는 generateMCPToolCacheKey를 제공할 수 있습니다. MCP 캐싱 지침을 참고하세요.
RunContext가 제공하는 항목
섹션 제목: “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에 표시되는 컨텍스트”LLM이 호출될 때 볼 수 있는 데이터는 대화 기록에 있는 데이터뿐입니다. 추가 정보를 제공하는 방법은 몇 가지가 있습니다:
- 에이전트의
instructions에 추가합니다. 이는 시스템 메시지 또는 개발자 메시지라고도 합니다. 고정된 문자열이나 컨텍스트를 받아 문자열을 반환하는 함수를 사용할 수 있습니다. Runner.run()을 호출할 때input에 포함합니다. 이는 instructions를 사용하는 방식과 비슷하지만, 명령 체계에서 메시지를 더 낮은 위치에 둘 수 있습니다.- 함수 도구를 통해 추가 정보를 제공하여 LLM이 필요할 때 해당 정보를 가져올 수 있도록 합니다.
- 검색 또는 웹 검색 도구를 사용하여 파일, 데이터베이스, 웹의 관련 데이터에 근거한 응답을 생성합니다.