DevTools

DevTools (AI SDK 개발 도구)

AI SDK DevTools는 로컬 개발 전용으로 만들어진 도구입니다. 프로덕션 환경에서는 사용하지 마세요.

DevTools는 generateText, streamText, ToolLoopAgent 호출에 대해 완전한 가시성을 제공합니다. 웹 기반 UI로 LLM 요청, 응답, 툴 호출, 다중 단계 상호작용을 디버깅하고 검사하는 데 도움이 됩니다.

DevTools는 두 부분으로 구성됩니다:

  1. 텔레메트리 통합: 텔레메트리 시스템을 통해 AI SDK 호출에서 실행(run)과 단계(step)를 캡처합니다.
  2. 뷰어: 캡처된 데이터를 검사하는 웹 UI.

출처: 공식문서

본문

설치

pnpm add @ai-sdk/devtools

요구사항

  • AI SDK v7 (ai@latest)
  • Node.js 호환 런타임

DevTools 사용

통합 등록

모든 AI SDK 호출을 캡처하도록 DevToolsTelemetry를 전역 등록합니다:

import { registerTelemetry } from 'ai';
import { DevToolsTelemetry } from '@ai-sdk/devtools';

registerTelemetry(DevToolsTelemetry());

통합이 등록되면 텔레메트리가 자동으로 활성화됩니다. 호출별 구성은 필요 없습니다.

개별 호출에 통합을 전달할 수도 있습니다 (전역 등록 대신):

import { streamText } from 'ai';
import { DevToolsTelemetry } from '@ai-sdk/devtools';

const result = streamText({
  model: openai('gpt-4o'),
  prompt: 'Hello!',
  telemetry: {
    integrations: [DevToolsTelemetry()],
  },
});

뷰어 실행

npx @ai-sdk/devtools@latest

http://localhost:4983을 열어 AI SDK 상호작용을 확인합니다.

뷰어 테마 선택

뷰어는 기본적으로 다크 테마를 사용합니다. 뷰어 헤더의 테마 버튼으로 다크/라이트를 전환할 수 있습니다. 선택은 브라우저에 저장되어 같은 오리진에서 뷰어를 다시 열면 복원됩니다.

모노레포 사용

모노레포(Turborepo, Nx 등)를 쓴다면 AI SDK 코드가 실행되는 같은 워크스페이스에서 DevTools를 시작하세요. @latest 태그를 명시하면 npx가 워크스페이스에 바이너리가 연결되지 않은 전이 의존성을 고르는 대신 실행 가능한 복사본을 설치합니다.

캡처되는 데이터

DevTools는 AI SDK 호출에서 다음 정보를 캡처합니다:

  • 입력 파라미터와 프롬프트: LLM으로 보낸 완전한 입력.
  • 출력 콘텐츠와 툴 호출: 생성된 텍스트, 툴 호출, 툴 결과.
  • 미디어 미리보기: 프롬프트, 툴 입력, 툴 출력에 포함된 이미지·오디오·비디오.
  • 토큰 사용량과 타이밍: 리소스 소비와 성능.
  • 원본 프로바이더 데이터: 본문 보존이 활성화되면 프로바이더 요청·응답 페이로드에 접근.

미디어 미리보기

DevTools는 현재 file 콘텐츠 파트와 구식 image-*, file-*, media 툴 결과 별칭을 인식합니다. 인라인 이미지·오디오·비디오 데이터는 직접 미리보고, 캡처된 JSON 형태와 메타데이터는 검사할 수 있게 유지됩니다. 뷰어는 값당 최대 8개 미리보기, 최대 12개 중첩 수준을 순회하며, 인라인 미리보기를 최대 5 MiB까지 포함합니다. 큰 base64 페이로드 중복을 피하려고 긴 JSON 문자열은 뷰어에서 잘립니다. 인식된 미디어 필드의 바이너리 값은 미리보기 가능하도록 base64로 저장되고, 무관한 바이너리 값은 일반 JSON 표현을 유지합니다.

예를 들어 툴은 toModelOutput로 미디어를 반환할 수 있습니다. 원격 http/https 미디어는 자동으로 로드되지 않습니다. 뷰어에서 Load preview를 선택해 익명 CORS와 no-referrer로 가져옵니다.

AI SDK 7은 단계 결과에서 원본 요청·응답 본문을 기본적으로 제외합니다. generateText에서 DevTools에 제공하려면 호출에서 본문 보존을 활성화하세요:

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Hello!',
  include: {
    requestBody: true,
    responseBody: true,
  },
});

ToolLoopAgent는 생성자에서 같은 include 설정을 받습니다. streamText와 ToolLoopAgent.stream()에서는 요청 본문만 보존할 수 있습니다 (include: { requestBody: true }).

실행과 단계

DevTools는 캡처된 데이터를 실행과 단계로 구성합니다:

  • Run: 초기 프롬프트로 그룹화된 완전한 다중 단계 AI 상호작용.
  • Step: 실행 안의 단일 LLM 호출 (하나의 generateText나 streamText 호출).

툴 호출이나 에이전트 루프가 만든 다중 단계 상호작용은 여러 단계를 가진 단일 실행으로 그룹화됩니다. 중첩된 하위 에이전트 호출은 부모 실행에 연결되어 전체 실행 트리를 추적하기 쉽게 합니다.

동작 방식

DevToolsTelemetry 통합은 AI SDK 텔레메트리 라이프사이클에 연결되어 모든 generateText, streamText, generateObject, streamObject 호출을 캡처합니다. 캡처된 데이터는 JSON 파일(.devtools/generations.json)에 로컬 저장되고 Hono와 React로 만든 웹 UI로 제공됩니다.

통합은 .devtools를 .gitignore에 자동 추가합니다. 민감한 AI 상호작용 데이터를 저장소에 커밋하지 않도록 .devtools가 .gitignore에 있는지 확인하세요.

보안 고려사항

DevTools는 모든 AI 상호작용을 로컬에 평문 파일로 저장합니다:

  • 사용자 프롬프트와 메시지
  • LLM 응답
  • 툴 호출 인자와 결과
  • 본문 보존이 활성화되면 API 요청·응답 데이터

로컬 개발 환경에서만 DevTools를 사용하세요. 프로덕션이나 민감 데이터를 다룰 때는 활성화하지 마세요.

더 알아보기