Event metadata

TanStack AI puts the finish reason and the model id in AG-UI metadata. useChat reads those fields from there.

Put these extras in metadata.tanstack on the event. The spec fields stay at the top level.

Quick setup#

1. Send a complete RUN_FINISHED event#

Copy this event. Change the ids, the counts, and the model:

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

2. Read the fields on the client#

Check chunk.type, then read chunk.metadata?.tanstack. You do not need a helper:

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

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

  return <pre>{JSON.stringify(messages, null, 2)}</pre>;
}

Send a message. The console now shows the token usage, "stop", and the model id.

How it works#

The client copies metadata.tanstack from the wire event onto the chunk. Spec fields such as usage stay where the spec puts them.

Send these fields on every successful run:

finishReason is one of these values: "stop", "length", "content_filter", "tool_calls", or null.

For the full event list, see Stream Events. For the request body, see AG-UI Client Compliance.

Advanced#

Usage on the wire and in process#

The wire uses the spec usage[] array with inputTokens. In process, usage is the TanStack TokenUsage type with promptTokens. The client rebuilds TokenUsage from the array.

RUN_ERROR#

An AG-UI RUN_ERROR has message and an optional code at the top level. Put the correlation ids in metadata.tanstack:

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

For a rate limit, put the wait time in metadata.tanstack.retryAfterMs, in milliseconds. Clients read it from there. See Rate limits.

Put the provider error type in metadata.tanstack.errorType and the request id in metadata.tanstack.requestId. See Read the provider error type and request id.

Fields for other features#

When you use one of these features, add its field:

• Extra usage. Spec usage[] also accepts cachedInputTokens and reasoningTokens. Put cost and other usage fields without a spec slot in metadata.tanstack.usage. The client merges them into TokenUsage.
• Interrupt errors. On RUN_ERROR, set metadata.tanstack.interruptErrors. Then ChatClient can match a failed interrupt submit.
• Tool output error. On TOOL_CALL_RESULT, set metadata.tanstack.state to "output-error" when the tool result is an error payload.
• Message timestamps. On wire messages, metadata.tanstack.createdAt is an ISO-8601 string.
• Signatures. Stream thinking signatures on REASONING_ENCRYPTED_VALUE. In the next-turn body, set the spec encryptedValue on role: "reasoning" messages and on toolCalls. Other provider fields for a tool call go in metadata.tanstack.toolCallMetadata. See Thinking & Reasoning.