Devtools

TanStack Devtools는 TanStack AI를 포함한 TanStack 라이브러리를 확인하고 디버깅하는 통합 개발자 도구 패널입니다. AI 상호작용, 도구 호출, 상태 변경을 실시간으로 확인할 수 있어 AI 기반 애플리케이션을 더 쉽게 개발하고 문제를 해결할 수 있습니다.

기능

훅 대시보드 - 채팅, 구조화된 출력, 이미지, 비디오, 오디오, 음성, 전사, 요약 훅을 포함해 페이지에서 활성화된 모든 TanStack AI 훅을 확인합니다.
실행 타임라인 - threadId와 runId별 사용자 턴, 연결된 실행, 스트림 이벤트, 클라이언트 스냅샷 및 서버 전용 이벤트를 확인합니다.
실시간 모니터링 - 실시간 채팅 메시지, 도구 호출 및 AI 응답을 확인합니다.
도구 호출 검사 - 도구 호출의 입력과 출력을 확인합니다.
도구 픽스처 재생 - 도구의 표준 스키마 입력에서 도구 페이로드를 만들고, 결과를 채팅 메시지에 추가하며, 반복적인 UI 작업을 위해 픽스처를 localStorage에 저장합니다.
상태 시각화 - 채팅 상태와 메시지 기록을 시각화합니다.
메모리 검사기 - memoryMiddleware로 연결된 채팅에서 메모리가 각 턴마다 무엇을 검색하고 주입했는지와 현재 저장된 레코드 및 사실을 확인합니다.
오류 추적 - AI 상호작용의 오류와 예외를 모니터링합니다.

훅 대시보드

AI devtools 패널은 활성 TanStack AI 클라이언트를 감지해 왼쪽 사이드바에 표시합니다. 훅은 생성될 때 등록되고 즉시 스냅샷을 내보내며, devtools 패널이 열리거나 상태를 요청할 때마다 다시 응답합니다. 따라서 앱이 이미 렌더링된 후 패널을 열어도 훅을 확인할 수 있습니다.

각 훅 항목에는 타입, 수명 주기, 메시지 수, 실행 수 및 최근 연결된 threadId가 포함됩니다. 훅을 선택하면 해당 훅의 전체 타임라인이 열립니다. 채팅 훅은 현재의 턴 기반 뷰를 유지합니다. 사용자 메시지가 해당 턴에 응답하는 동안 발생한 모든 실행과 이벤트를 감쌉니다. 상세 뷰에는 실행 사이의 간단한 클라이언트/서버 상태 스냅샷도 포함되므로 정확히 무엇이 변경되었는지 확인할 수 있습니다.

훅 이름 지정

페이지에 AI 훅이 둘 이상 있으면 devtools.name을 전달해 대시보드에서 각 훅에 사용자에게 표시할 레이블을 지정합니다. 구성한 이름은 표시 전용이며, 훅 타입, 프레임워크, 스레드 ID 및 실행 상관관계는 계속 TanStack AI 클라이언트에서 가져옵니다.

import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'

export function SupportChat() {
  const chat = useChat({
    threadId: 'support-chat',
    connection: fetchServerSentEvents('/api/chat'),
    devtools: {
      name: 'Support Chat',
    },
  })

  // render your chat UI with `chat.messages`, `chat.sendMessage`, etc.
}

같은 표시 옵션은 특수 생성 훅에서도 작동합니다.

import { fetchServerSentEvents, useGenerateImage } from '@tanstack/ai-react'

export function ImageStudio() {
  const image = useGenerateImage({
    threadId: 'generation-hooks:useGenerateImage',
    connection: fetchServerSentEvents('/api/image'),
    devtools: {
      name: 'Image Studio',
    },
  })

  // render your image generation UI with `image.generate` and `image.result`
}

도구 픽스처

useChat 훅이 도구를 받으면 devtools 패널에 해당 도구와 스키마가 표시됩니다. 표준 스키마 호환 입력의 경우 패널이 입력 스키마에서 간단한 폼을 렌더링하므로 JSON을 직접 작성하지 않고 도구 호출 페이로드를 만들 수 있습니다.

도구 픽스처를 적용하면 해당 훅의 실제 채팅 메시지에 도구 호출과 결과가 추가됩니다. 저장된 픽스처는 AI devtools 네임스페이스 아래의 브라우저 localStorage에 저장되므로 다음에 패널을 열 때 사용할 수 있습니다.

메모리 검사기

채팅이 memoryMiddleware로 연결되면 훅의 Memory 탭에 서버 측 메모리 백엔드가 해당 대화에 수행한 작업이 범위(session)별로 표시됩니다.

작업 타임라인 - 각 턴의 회상: 쿼리, 반환된 조각 수, 시스템 프롬프트에 주입된 문자 수, 메모리가 제공한 도구가 노출되었는지 여부 및 회상 시간입니다.
저장된 레코드 및 사실 - 어댑터가 선택적 inspect/listFacts 메서드를 구현하는 경우 해당 범위의 메모리 스토어 현재 내용입니다(기본 제공 inMemory() 및 redis() 어댑터가 구현합니다). introspection을 지원하지 않는 어댑터에서도 작업 타임라인은 표시됩니다.

메모리는 서버에서 실행되므로 상태가 별도 채널이 아니라 채팅 스트림을 통해 패널로 전송됩니다(클라이언트가 다시 내보내는 CUSTOM 이벤트). 이는 생성 결과가 패널에 도달하는 방식과 같습니다. 스냅샷은 각 턴 시작 시점의 메모리를 반영하므로 한 턴에서 직접 기록한 내용은 다음 턴의 스냅샷에 나타납니다. 턴이 끝난 후 패널을 열면 최신 메모리 상태가 재생되므로 대화 중간에 devtools를 열어도 탭이 채워집니다.

이벤트 소스

클라이언트에서 볼 수 있는 상태는 헤드리스 클라이언트가 내보냅니다. 클라이언트에 존재하지 않는 미들웨어 및 프로바이더 스트림 이벤트와 같은 서버 전용 세부 정보는 서버 측 대응 요소가 내보냅니다. 이벤트에는 소스 설명자와 안정적인 봉투 ID가 포함되므로 패널이 관련 이벤트를 연결하고 중복 표시를 방지할 수 있습니다.

설치

TanStack AI에서 TanStack Devtools를 사용하려면 @tanstack/react-ai-devtools 패키지를 설치합니다.

npm install -D @tanstack/react-ai-devtools @tanstack/react-devtools

또는 SolidJS에서는 @tanstack/solid-ai-devtools 패키지를 설치합니다.

npm install -D @tanstack/solid-ai-devtools @tanstack/solid-devtools

또는 Preact에서는 @tanstack/preact-ai-devtools 패키지를 설치합니다.

npm install -D @tanstack/preact-ai-devtools @tanstack/preact-devtools

또는 Svelte에서는 @tanstack/svelte-ai-devtools 패키지를 설치합니다.

npm install -D @tanstack/svelte-ai-devtools @tanstack/svelte-devtools

사용법

애플리케이션에서 TanStackDevtools 컴포넌트를 가져와 포함합니다.

import { TanStackDevtools } from '@tanstack/react-devtools'
import { aiDevtoolsPlugin } from '@tanstack/react-ai-devtools'

const App = () => {
  return (
    <>
       <TanStackDevtools 
          plugins={[
            // ... other plugins
            aiDevtoolsPlugin(),
          ]}
          // this config is important to connect to the server event bus
          eventBusConfig={{
            connectToServerBus: true,
          }}
        />
    </>
  )
}

Svelte에서는 Svelte Devtools 컴포넌트에 플러그인을 등록합니다.

<script lang="ts">
import { aiDevtoolsPlugin } from '@tanstack/svelte-ai-devtools'
import { TanStackDevtools } from '@tanstack/svelte-devtools'

const plugins = [aiDevtoolsPlugin()]
</script>

<TanStackDevtools
  {plugins}
  eventBusConfig={{
    connectToServerBus: true,
  }}
/>

Next.js와 함께 사용하기(또는 Vite 플러그인 없이 사용하기)

connectToServerBus: true는 일반적으로 @tanstack/devtools-vite가 시작하는 포트 4206의 WebSocket/SSE 서버에 의존합니다. Next.js 또는 Vite가 아닌 번들러를 사용하는 경우 서버 부팅 시 ServerEventBus를 수동으로 시작해야 합니다.

Next.js에서는 instrumentation.ts에서 다음을 수행합니다.

export async function register() {
     if (
         process.env["NEXT_RUNTIME"] === "nodejs" &&
         process.env.NODE_ENV === "development"
     ) {
         const { ServerEventBus } = await import(
             "@tanstack/devtools-event-bus/server"
         );
         const bus = new ServerEventBus();
         await bus.start();
     }
}

이렇게 하면 globalThis.__TANSTACK_EVENT_TARGET__이 설정됩니다. 따라서 서버 측 devtoolsMiddleware(chat() 호출마다 자동으로 실행됨)가 도구 호출 이벤트를 버스로 내보낼 수 있고, 버스는 이를 devtools 패널로 전달합니다.

기능​

훅 대시보드​

훅 이름 지정​

도구 픽스처​

메모리 검사기​

이벤트 소스​

설치​

사용법​

Next.js와 함께 사용하기(또는 Vite 플러그인 없이 사용하기)​

기능