런타임과 도구 컨텍스트

런타임과 도구 컨텍스트 (Runtime and Tool Context)

한 번의 생성이나 에이전트 루프 안에서 프롬프트에 넣지 않고 서버 쪽 상태를 전달하고 싶을 때가 있어요. 컨텍스트(context)는 바로 그 역할을 합니다. AI SDK는 공유되는 런타임 상태와 도구별 실행 상태를 분리해서, 에이전트는 자신이 진행 중인 작업을 계속 추적할 수 있고 도구는 필요한 값만 받도록 설계했어요.

출처: 공식문서

본문

컨텍스트는 테넌트(tenant) 정보·피처 플래그·세션 데이터·요청 ID·API 자격 증명·액세스 토큰처럼 실행에 영향을 줘야 하는 애플리케이션 상태를 담는 데 씁니다.

컨텍스트 유형

개념	정의하는 곳	읽는 곳	용도
`runtimeContext`	`generateText`·`streamText`·`ToolLoopAgent` 호출	`prepareStep`, 생명주기 콜백, 스텝 결과, 텔레메트리	공유되는 생성·에이전트 상태
`toolsContext`	`generateText`·`streamText`·`ToolLoopAgent` 호출	`prepareStep`, 승인 콜백, 도구 컨텍스트 해석, 도구 설명 함수	도구 이름을 키로 하는 도구별 컨텍스트 값 맵
도구 `context`	각 도구의 `toolsContext` 항목, `contextSchema`로 검증	도구 설명 함수, 도구 `execute`·`needsApproval`, 도구 입력 생명주기 콜백	한 도구에 필요한 값
`toolContext`	한 도구의 컨텍스트에서 유도	도구 승인 콜백, 도구 실행 이벤트	한 도구 컨텍스트의 이벤트·콜백 이름
`telemetry.includeRuntimeContext`	생성·에이전트 호출	텔레메트리 필터링	텔레메트리에 포함할 최상위 `runtimeContext` 속성
`telemetry.includeToolsContext`	생성·에이전트 호출	텔레메트리 필터링	텔레메트리에 포함할 최상위 도구 컨텍스트 속성

에이전트에서 runtimeContext는 에이전트의 공유 런타임 상태예요. 이 값은 루프를 타고 흐르며, 모델 호출 사이 prepareStep에서 읽거나 갱신할 수 있습니다. 도구별 데이터는 toolsContext에 남고, 각 도구는 자신의 검증된 context만 받아요.

generateText / streamText / ToolLoopAgent
  -> runtimeContext
    -> prepareStep, lifecycle callbacks, step results
    -> telemetry, filtered by telemetry.includeRuntimeContext
  -> toolsContext
    -> prepareStep
    -> one tool's context / toolContext
      -> execute, approval callbacks, tool events
    -> telemetry, filtered by telemetry.includeToolsContext

런타임 컨텍스트

전체 생성이나 에이전트 루프에 걸쳐 쓸 공유 상태가 필요하다면 runtimeContext를 넘기세요. 이 값은 모델 프롬프트에 자동으로 더해지지 않아요. 스텝 준비를 구성하거나 서버 쪽 상태를 추적하거나 생명주기 이벤트를 연결하는 데 쓰면 됩니다.

const result = await generateText({
  model: "xai/grok-4.5",
  prompt: 'Help the user plan their trip.',
  runtimeContext: {
    tenantId: 'tenant_123',
    plan: 'enterprise',
    requestId: 'req_abc',
  },
  prepareStep: async ({ runtimeContext }) => {
    if (runtimeContext.plan === 'enterprise') {
      return { temperature: 0.2 };
    }
    return {};
  },
});

prepareStep은 각 모델 호출 전에 실행되어 다음 스텝의 옵션을 준비할 수 있어요. 위 예시에서는 테넌트가 enterprise 요금제면 temperature를 낮춥니다.

더 알아보기

텔레메트리(Telemetry)의 메타데이터와 runtimeContext 활용
에이전트 만들기(Building Agents)에서의 컨텍스트 흐름
도구(Tools) 통합과 toolsContext/contextSchema