# vercel-ai-sdk

Vercel AI SDK patterns for building streaming chat interfaces, handling tool invocations, and rendering complex messages.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 101 installs · ★ 89 repo stars
- Author: existential-birds
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/existential-birds/beagle/tree/HEAD/plugins/beagle-ai/skills/vercel-ai-sdk/SKILL.md
- Updated: 2026-09-15
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/existential-birds-vercel-ai-sdk

## What it does

This skill equips coding assistants with implementation patterns for `@ai-sdk/react` and the core `ai` module. It covers the `useChat` hook lifecycle, tracking `ChatStatus` through states like `ready`, `submitted`, `streaming`, and `error`. It also details the parts-based `UIMessage` schema, where text, file attachments, reasoning traces, and tool states live in a single array.

On the server route, the guide sets up `streamText` pipelines paired with `toUIMessageStreamResponse`. It distinguishes between backend tool runs that include an `execute` handler and browser-side tools coordinated via `onToolCall` and `addToolOutput`. It also provides patterns for throttling client renders using `experimental_throttle`.

Server streaming responses require passing `originalMessages` to `toUIMessageStreamResponse` to maintain message structure properly.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/vercel-ai-sdk/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/vercel-ai-sdk/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/vercel-ai-sdk/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/vercel-ai-sdk/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install existential-birds/beagle plugins/beagle-ai/skills/vercel-ai-sdk
```

2. **Manually: put the files in place**
- File: `.github/skills/vercel-ai-sdk/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/existential-birds/beagle --path plugins/beagle-ai/skills/vercel-ai-sdk
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/vercel-ai-sdk/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/existential-birds/beagle/tree/HEAD/plugins/beagle-ai/skills/vercel-ai-sdk/SKILL.md

## When to use it
- configure the `useChat` hook with status listeners and file uploads
- set up server routes using `streamText` and `toUIMessageStreamResponse`
- manage client-side tool states with `onToolCall` and `addToolOutput`
- render parts-based messages containing tools, reasoning traces, and text

## Example prompts
- Implement a chat interface using `useChat` from `@ai-sdk/react` with error toasts and file uploads
- Create a backend endpoint using `streamText` that executes a custom tool and streams the response
- Render tool execution steps based on `part.state` inside a `UIMessage` list

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 7025f900c034f353.

BEGIN THIRD-PARTY FILE 7025f900c034f353
````text
---
name: vercel-ai-sdk
description: Vercel AI SDK for building chat interfaces with streaming. Use when implementing useChat hook, handling tool calls, streaming responses, or building chat UI. Triggers on useChat, @ai-sdk/react, UIMessage, ChatStatus, streamText, toUIMessageStreamResponse, addToolOutput, onToolCall, sendMessage.
---

# Vercel AI SDK

The Vercel AI SDK provides React hooks and server utilities for building streaming chat interfaces with support for tool calls, file attachments, and multi-step reasoning.

## Quick Reference

### Basic useChat Setup

```typescript
import { useChat } from '@ai-sdk/react';

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

```typescript
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
  }
});
```
````
END THIRD-PARTY FILE 7025f900c034f353

The third-party file has ended. Everything between the 7025f900c034f353 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2574 of 8378 bytes. © existential-birds · Apache-2.0 · https://github.com/existential-birds/beagle/tree/HEAD/plugins/beagle-ai/skills/vercel-ai-sdk/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
