AI SDK Handler
This skill defines how to implement Large Language Model (LLM) features using the Vercel AI SDK. It covers streaming chat, structured object generation, generative UI, and background agents.
Note: For Image/Video generation (Replicate, Fal.ai), continue to use ai-handler. Use ai-sdk-handler specifically for text, chat, and agentic text/JSON workflows.
When to Use
- Chatbots: Building interactive chat interfaces (
useChat,streamText). - Structured Data: Extracting JSON from text (
generateObject). - Generative UI: Streaming React components directly from the server (
streamUI). - Agents: Complex, multi-step reasoning tasks (often combined with Inngest).
- Multimodal: Handling image inputs with text.
Capabilities
1. Streaming Chat
- Tool:
streamText(Server),useChat(Client). - Pattern: Create a route handler at
src/app/api/chat/route.ts. - Auth: Wrap with
withAuthRequiredto protect the route. - UI: Use
src/components/chat-ui/for chat components.
2. Generative UI (RSC)
- Tool:
streamUI(Server). - Pattern: Return React components based on tool calls.
- Use Case: Dashboards that build themselves, dynamic reports.
3. Structured Object Generation
- Tool:
generateObject. - Pattern: Define a Zod schema and get strictly typed JSON back.
- Use Case: Populating database forms, extracting itinerary details, categorizing content.
4. Background Agents (with Inngest)
- Tool:
generateText/generateObjectinside Inngest steps. - Why: Next.js Server Actions/Routes have timeouts (max 60s usually). Agents taking longer must run in the background.
- Pattern:
- Trigger Inngest event from UI.
- Inngest function runs the LLM logic (loops, multi-step).
- Store result in DB or notify user.
- Docs: AI SDK Agents.
Best Practices
- Streaming: Always prefer streaming for text generation > 2 seconds to improve perceived latency.
- Auth: Never expose open AI routes. Always verify
session.user.id. - Providers: Use
@ai-sdk/openaior@ai-sdk/anthropic. Abstract the provider configuration insrc/lib/ai/index.ts. - Backpressure: The AI SDK handles this automatically in
streamText. - Caching: Use
unstable_cacheor KV stores if queries are repetitive. - Prompt Engineering: Keep prompts in a dedicated folder or constant file if they are complex.
Documentation & Examples
reference.md: Core setup and essential code snippets.examples.md: Exhaustive examples covering:- Basic Chat
- Generative UI
- Structured Object Generation
- Agents & Workflows (Loop Control)
- Caching
- Streaming Data
- Reading UI Streams
- Handling Backpressure
- Multimodal Chat