vercel-ai-sdk · existential-birds — Claude Code skill: what it does, how to install
Vercel AI SDK patterns for building streaming chat interfaces, handling tool invocations, and rendering complex messages.
Apache-2.0 101 installs ★ 89 updated 2026-09-15
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a claude-codeWhat vercel-ai-sdk 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.
What it helps with
- configure the
useChathook with status listeners and file uploads - set up server routes using
streamTextandtoUIMessageStreamResponse - manage client-side tool states with
onToolCallandaddToolOutput - render parts-based messages containing tools, reasoning traces, and text
Example prompts for the agent
- Implement a chat interface using
useChatfrom@ai-sdk/reactwith error toasts and file uploads - Create a backend endpoint using
streamTextthat executes a custom tool and streams the response - Render tool execution steps based on
part.stateinside aUIMessagelist
How to install vercel-ai-sdk
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a claude-code2Manually: put the files in place
~/.claude/skills/vercel-ai-sdk/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vercel-ai-sdk/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a codex2Manually: put the files in place
.agents/skills/vercel-ai-sdk/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a cursor2Manually: put the files in place
.cursor/skills/vercel-ai-sdk/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install existential-birds/beagle plugins/beagle-ai/skills/vercel-ai-sdk2Manually: put the files in place
.github/skills/vercel-ai-sdk/SKILL.md1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a gemini-cli2Platform CLI
gemini skills install https://github.com/existential-birds/beagle --path plugins/beagle-ai/skills/vercel-ai-sdkManually: put the files in place
.devin/skills/vercel-ai-sdk/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill vercel-ai-sdk -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about vercel-ai-sdk
How to install vercel-ai-sdk in Claude Code?
Run npx skills add existential-birds/beagle --skill vercel-ai-sdk -a claude-code in your terminal. The config will be saved to ~/.claude/skills/vercel-ai-sdk/SKILL.md.
What does vercel-ai-sdk do?
It provides your coding agent with structured reference guides and code examples for building streaming chat applications using the Vercel AI SDK.
How are client-side tools handled compared to server tools?
Server-side tools execute directly inside the endpoint using an execute function, while client tools omit that handler and rely on the onToolCall and addToolOutput hooks in the UI.
Source text
SKILL.md · Apache-2.0
---
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
}
});
```
### Tool Handling Patterns
**Client-Side Tool Execution:**
```typescript
const { addToolOutput } = useChat({
onToolCall: async ({ toolCall }) => {
if (toolCall.toolName === 'getLocation') {
addToolOutput({
tool: 'getLocation',
toolCallId: toolCall.toolCallId,
output: 'San Francisco'
});
}
}
});
```
**Rendering Tool States:**
```typescript
{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](references/use-chat.md)**: Complete useChat API reference
- **[messages.md](references/messages.md)**: UIMessage structure and part types
- **[streaming.md](references/streaming.md)**: Server-side streaming implementation
- **[tools.md](references/tools.md)**: Tool definition and execution patterns
## Common Patterns
### Error Handling
```typescript
const { error, clearError } = useChat({
onError: (error) => {
toast.error(error.message);
}
});
// Clear error and reset to ready state
if (error) {
clearError();
}
```
### Message Regeneration
```typescript
const { regenerate } = useChat();
// Regenerate last assistant message
await regenerate();
// Regenerate specific message
await regenerate({ messageId: 'msg-123' });
```
### Custom Transport
```typescript
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
```typescript
// Throttle UI updates to reduce re-renders
const chat = useChat({
experimental_throttle: 100 // Update max once per 100ms
});
```
### Automatic Message Sending
```typescript
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:
```typescript
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:
1. `input-streaming`: Tool input streaming (optional)
2. `input-available`: Tool input complete
3. `approval-requested`: Waiting for user approval (optional)
4. `approval-responded`: User approved/denied (optional)
5. `output-available`: Tool execution complete
6. `output-error`: Tool execution failed
7. `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”).
1. **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.
2. **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.
3. **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.
4. **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
1. Always handle the `error` state and provide user feedback
2. Use `experimental_throttle` for high-frequency updates
3. Implement proper loading states based on `status`
4. Type your messages with custom metadata and tools
5. Use `sendAutomaticallyWhen` for multi-turn tool workflows
6. Handle all tool states in the UI for better UX
7. Use `stop()` to allow users to cancel long-running requests
8. Validate messages with `validateUIMessages` on the server
© existential-birds · Apache-2.0 · existential-birds/beagle
Similar skills
All skills for Frontend and UI →vercel-ai-sdk by other authors comes first.