본문으로 건너뛰기

이벤트 메타데이터

서버가 AG-UI를 사용하지만 TanStack useChat에서 finishReason, 모델 ID 또는 잔여 사용량이 누락됩니다. 이러한 추가 정보를 이벤트의 metadata.tanstack에 넣습니다. 사양 필드는 최상위에 둡니다.

먼저 다음 RUN_FINISHED 이벤트를 복사합니다.

{
  "type": "RUN_FINISHED",
  "threadId": "thread-1",
  "runId": "run-1",
  "usage": [
    {
      "inputTokens": 12,
      "outputTokens": 34,
      "totalTokens": 46
    }
  ],
  "metadata": {
    "tanstack": {
      "finishReason": "stop",
      "model": "gpt-5.5"
    }
  }
}

클라이언트는 metadata.tanstack을 청크에 복사합니다. chunk.type === "RUN_FINISHED" 이후에 chunk.metadata?.tanstack?.finishReason을 읽습니다. 프로세스 내부의 usage는 TanStack TokenUsage(promptTokens)입니다. 네트워크에서는 사양 배열(inputTokens)을 사용합니다.

지금 수행할 작업​

성공한 모든 실행에서 다음을 보냅니다.

필드위치클라이언트에 필요한 이유
type, threadId, runId사양 최상위실행을 구성합니다. ID가 없으면 재개와 상관관계 추적이 중단됩니다.
usage[]RUN_FINISHED / RUN_ERROR의 사양 최상위토큰 수입니다. inputTokens, outputTokens, totalTokens을 사용합니다.
finishReasonRUN_FINISHED의 metadata.tanstack도구 결과 후 이 값이 "stop"이 아닐 때만 클라이언트가 계속 진행합니다.
modelmetadata.tanstackSSE [DONE] 폴백 및 생성 복원에 사용합니다.

finishReason은 "stop", "length", "content_filter", "tool_calls" 또는 null 중 하나입니다.

도구 결과 후 finishReason을 생략하면 클라이언트는 이를 "stop"이 아닌 것으로 처리하고 다음 턴을 보낼 수 있습니다.

클라이언트에서 읽기​

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

const { messages } = useChat({
  connection: fetchServerSentEvents("/api/chat"),
  onChunk: (chunk) => {
    if (chunk.type === "RUN_FINISHED") {
      console.log(chunk.usage);
      console.log(chunk.metadata?.tanstack?.finishReason);
      console.log(chunk.metadata?.tanstack?.model);
    }
  },
});

헬퍼를 가져오지 않습니다. chunk.type을 확인한 다음 chunk.metadata?.tanstack을 읽습니다.

RUN_ERROR​

AG-UI RUN_ERROR는 최상위에 message와 선택적인 code를 가집니다. 상관관계 ID는 metadata.tanstack에 넣습니다.

{
  "type": "RUN_ERROR",
  "message": "Provider timeout",
  "code": "TIMEOUT",
  "metadata": {
    "tanstack": {
      "threadId": "thread-1",
      "runId": "run-1",
      "model": "gpt-5.5"
    }
  }
}

나중에 수행할 작업​

해당 기능을 사용할 때 다음을 추가합니다.

  • 잔여 사용량. 사양의 usage[]는 cachedInputTokens와 reasoningTokens도 허용합니다. cost와 기타 잔여 필드는 metadata.tanstack.usage에 넣습니다. 클라이언트는 배열과 해당 잔여 필드로 TanStack TokenUsage(promptTokens)를 다시 구성합니다.
  • 인터럽트 오류. RUN_ERROR에서 metadata.tanstack.interruptErrors를 설정하면 ChatClient가 실패한 인터럽트 제출을 일치시킬 수 있습니다.
  • 도구 출력 오류. 도구 결과가 오류 페이로드이면 TOOL_CALL_RESULT에서 metadata.tanstack.state를 "output-error"로 설정합니다.
  • 메시지 타임스탬프. 네트워크 메시지에서 metadata.tanstack.createdAt은 ISO-8601 문자열입니다.
  • 서명. REASONING_ENCRYPTED_VALUE에서 사고 서명을 스트리밍합니다. 다음 턴 본문에서는 role: "reasoning" 메시지와 toolCalls에 사양의 encryptedValue를 설정합니다. 다른 도구 호출 제공자 필드는 metadata.tanstack.toolCallMetadata에 유지합니다. Thinking & Reasoning을 참조합니다.

TanStack chat() 서버는 이미 이 정보를 기록합니다. AG-UI 이벤트를 직접 발생시킬 때 이 페이지를 사용합니다.

Streaming에서 이벤트 표를, AG-UI Client Compliance에서 요청 본문을 참조합니다.