const { messages, status, sendMessage, stop, regenerate } = useChat({ id: 'chat-id', messages: initialMessages, onFinish: ({ message, messages, isAbort, isError }) => { console.log('Chat finished'); }, onError: (error) => { console.error('Chat error:', error); } });

// Send a message sendMessage({ text: 'Hello', metadata: { createdAt: Date.now() } });

// Send with files sendMessage({ text: 'Analyze this', files: fileList // FileList or FileUIPart[] });


### ChatStatus States

The `status` field indicates the current state of the chat:

- **`ready`**: Chat is idle and ready to accept new messages
- **`submitted`**: Message sent to API, awaiting response stream start
- **`streaming`**: Response actively streaming from the API
- **`error`**: An error occurred during the request

### Message Structure

Messages use the `UIMessage` type with a parts-based structure:

```typescript
interface UIMessage {
  id: string;
  role: 'system' | 'user' | 'assistant';
  metadata?: unknown;
  parts: Array<UIMessagePart>; // text, file, tool-*, reasoning, etc.
}

Part types include:

text: Text content with optional streaming state
file: File attachments (images, documents)
tool-{toolName}: Tool invocations with state machine
reasoning: AI reasoning traces
data-{typeName}: Custom data parts

Server-Side Streaming

import { streamText } from 'ai';
import { convertToModelMessages } from 'ai';

const result = streamText({
  model: openai('gpt-4'),
  messages: convertToModelMessages(uiMessages),
  tools: {
    getWeather: tool({
      description: 'Get weather',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => {
        return { temperature: 72, weather: 'sunny' };
      }
    })
  }
});

return result.toUIMessageStreamResponse({
  originalMessages: uiMessages,
  onFinish: ({ messages }) => {
    // Save to database
  }
});

Tool Handling Patterns

Client-Side Tool Execution:

const { addToolOutput } = useChat({
  onToolCall: async ({ toolCall }) => {
    if (toolCall.toolName === 'getLocation') {
      addToolOutput({
        tool: 'getLocation',
        toolCallId: toolCall.toolCallId,
        output: 'San Francisco'
      });
    }
  }
});

Rendering Tool States:

{message.parts.map(part => {
  if (part.type === 'tool-getWeather') {
    switch (part.state) {
      case 'input-streaming':
        return <pre>{JSON.stringify(part.input, null, 2)}</pre>;
      case 'input-available':
        return <div>Getting weather for {part.input.city}...</div>;
      case 'output-available':
        return <div>Weather: {part.output.weather}</div>;
      case 'output-error':
        return <div>Error: {part.errorText}</div>;
    }
  }
})}

Reference Files

Detailed documentation on specific aspects:

use-chat.md: Complete useChat API reference
messages.md: UIMessage structure and part types
streaming.md: Server-side streaming implementation
tools.md: Tool definition and execution patterns

Common Patterns

Error Handling

const { error, clearError } = useChat({
  onError: (error) => {
    toast.error(error.message);
  }
});

// Clear error and reset to ready state
if (error) {
  clearError();
}

Message Regeneration

const { regenerate } = useChat();

// Regenerate last assistant message
await regenerate();

// Regenerate specific message
await regenerate({ messageId: 'msg-123' });

Custom Transport

import { DefaultChatTransport } from 'ai';

const { messages } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/chat',
    prepareSendMessagesRequest: ({ id, messages, trigger, messageId }) => ({
      body: {
        chatId: id,
        lastMessage: messages[messages.length - 1],
        trigger,
        messageId
      }
    })
  })
});

Performance Optimization

// Throttle UI updates to reduce re-renders
const chat = useChat({
  experimental_throttle: 100 // Update max once per 100ms
});

Automatic Message Sending

import { lastAssistantMessageIsCompleteWithToolCalls } from 'ai';

const chat = useChat({
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls
  // Automatically resend when all tool calls have outputs
});

Type Safety

The SDK provides full type inference for tools and messages:

import { InferUITools, UIMessage } from 'ai';

const tools = {
  getWeather: tool({
    inputSchema: z.object({ city: z.string() }),
    execute: async ({ city }) => ({ weather: 'sunny' })
  })
};

type MyMessage = UIMessage<
  { createdAt: number }, // Metadata type
  UIDataTypes,
  InferUITools<typeof tools> // Tool types
>;

const { messages } = useChat<MyMessage>();

Key Concepts

Parts-Based Architecture

Messages use a parts array instead of a single content field. This allows:

Streaming text while maintaining other parts
Tool calls with independent state machines
File attachments and custom data mixed with text

Tool State Machine

Tool parts progress through states:

input-streaming: Tool input streaming (optional)
input-available: Tool input complete
approval-requested: Waiting for user approval (optional)
approval-responded: User approved/denied (optional)
output-available: Tool execution complete
output-error: Tool execution failed
output-denied: User denied approval

Streaming Protocol

The SDK uses Server-Sent Events (SSE) with UIMessageChunk types:

text-start, text-delta, text-end
tool-input-available, tool-output-available
reasoning-start, reasoning-delta, reasoning-end
start, finish, abort

Client vs Server Tools

Server-side tools have an execute function and run on the API route.

Client-side tools omit execute and are handled via onToolCall and addToolOutput.

Gates

Use this sequence; treat a step as incomplete until the pass condition is true in code or UI (not “should work”).

Streaming route — Pass if: the chat handler chains convertToModelMessages → streamText (or the SDK pattern your app standardizes) → toUIMessageStreamResponse (or equivalent stream response). Fail if: responses are plain JSON strings without the UI message stream contract.
Client ↔ route — Pass if: useChat id / DefaultChatTransport api (and prepareSendMessagesRequest body) matches the route path and the body the server reads. Fail if: client posts to a different path or shape than the handler expects.
Tools closed loop — Pass if: every tool in tools has server execute or onToolCall + addToolOutput with the same toolCallId, and the UI handles the tool-* part states you surface. Fail if: a tool name exists in tools but has no handler or missing states in the renderer.
Persistence (if any) — Pass if: before saving, the server runs validateUIMessages (or stricter validation). Fail if: unvalidated client payloads are written to storage.

Best Practices

Always handle the error state and provide user feedback
Use experimental_throttle for high-frequency updates
Implement proper loading states based on status
Type your messages with custom metadata and tools
Use sendAutomaticallyWhen for multi-turn tool workflows
Handle all tool states in the UI for better UX
Use stop() to allow users to cancel long-running requests
Validate messages with validateUIMessages on the server

vercel-ai-sdk

Vercel AI SDK

Quick Reference

Basic useChat Setup