/ai-orchestration-vercel-ai-sdk

name: ai-orchestration-vercel-ai-sdk
description: Vercel AI SDK patterns - providers, text generation, streaming, structured output, tool calling, chat UI hooks, embeddings, and RAG

Vercel AI SDK Patterns

> **Quick Guide:** Use Vercel AI SDK (v6) to build AI-powered applications with a unified provider API. Use `generateText`/`streamText` for text generation and streaming, `Output.object()`/`Output.array()` for structured data with Zod, `tool()` for function calling, and `useChat`/`useCompletion` hooks for React chat UIs. Supports OpenAI, Anthropic, Google, and 20+ providers through a single API.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use the `ai` package (v6) with `Output.object()` / `Output.array()` for structured output -- NOT the deprecated `generateObject` / `streamObject` functions)**

**(You MUST define tool input schemas with `z.object()` and use `.describe()` on each property to help the model understand expected inputs)**

**(You MUST use `streamText` for user-facing responses to enable progressive rendering -- use `generateText` only for background/non-interactive tasks)**

**(You MUST handle streaming errors via `onError` callback -- streamText errors become part of the stream and are NOT thrown)**

**(You MUST use `inputSchema` (not `parameters`) when defining tools -- `parameters` was renamed in SDK v5+)**

</critical_requirements>

---

**Auto-detection:** AI SDK, Vercel AI, generateText, streamText, generateObject, streamObject, Output.object, Output.array, useChat, useCompletion, @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google, tool(), toolChoice, embedMany, embed, cosineSimilarity, ToolLoopAgent, smoothStream

**When to use:**

• Building AI chat interfaces with streaming responses
• Generating structured data (JSON objects, arrays) from LLMs with Zod schema validation
• Implementing tool calling / function calling with LLMs
• Creating multi-provider AI applications (OpenAI, Anthropic, Google, etc.)
• Building RAG pipelines with embeddings and vector similarity
• Adding AI text completion or generation to any TypeScript app

**Key patterns covered:**

• Provider setup and model configuration (OpenAI, Anthropic, Google, custom)
• Text generation (`generateText`) and streaming (`streamText`)
• Structured output with Zod schemas (`Output.object`, `Output.array`, `Output.choice`)
• Tool calling with `tool()`, multi-step execution, and approval flows
• React hooks: `useChat` for chat UIs, `useCompletion` for text completion
• Embeddings (`embed`, `embedMany`) and RAG patterns with `cosineSimilarity`

**When NOT to use:**

• Simple static content that doesn't need AI generation
• Server-side-only batch jobs where a direct provider SDK (e.g., `openai` npm package) is simpler
• Image generation only (AI SDK supports it, but dedicated image SDKs may be more feature-rich)

**Detailed Resources:**

• For provider setup, text generation, and error handling, see [examples/core.md](examples/core.md)
• For chat UI patterns with useChat, see [examples/chat.md](examples/chat.md)
• For tool definitions and multi-step calling, see [examples/tools.md](examples/tools.md)
• For Zod-based structured output, see [examples/structured-output.md](examples/structured-output.md)
• For embeddings and RAG, see [examples/rag.md](examples/rag.md)
• For quick reference tables, see [reference.md](reference.md)

---

<philosophy>

Philosophy

The Vercel AI SDK provides a **unified TypeScript API** for building AI-powered applications across providers. Instead of learning each provider's unique SDK, you write one set of code that works with OpenAI, Anthropic, Google, and 20+ other providers.

**Core principles:**

1. **Provider agnostic** -- Switch models by changing a string, not rewriting code. The provider abstraction means `generateText({ model: 'openai/gpt-4o' })` and `generateText({ model: 'anthropic/claude-sonnet-4.5' })` use the same API. 2. **Streaming first** -- `streamText` starts delivering tokens immediately. Use it for all user-facing responses. `generateText` blocks until completion and is better for background tasks and agent loops. 3. **Type-safe structured output** -- Define Zod schemas and get validated, typed objects back from the model. Use `.describe()` on schema properties to guide the model. 4. **Tools as first-class citizens** -- Define tools with Zod input schemas and execute functions. The SDK handles the tool call loop, including multi-step execution and human approval. 5. **Framework-agnostic UI hooks** -- `useChat` and `useCompletion` work with React, Svelte, Vue, and Angular. They manage streaming state, message history, and input handling.

**When to use Vercel AI SDK:**

• Multi-provider applications where you want to switch models easily
• Streaming chat interfaces with React (or Svelte, Vue, Angular)
• Structured data extraction from natural language
• Agent-style applications with tool calling loops
• RAG systems with embedding and retrieval

**When NOT to use:**

• Single-provider scripts where the native SDK is simpler and has fewer dependencies
• Extremely high-throughput batch processing (direct API calls avoid SDK overhead)
• Non-TypeScript environments (the SDK is TypeScript-first)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Provider Setup

Configure providers via direct imports (auto-reads env vars), custom instances, or AI Gateway. See [examples/core.md](examples/core.md) for full examples.

import { gateway } from "ai";
import { openai } from "@ai-sdk/openai";

// Gateway: provider/model string routing
const model = gateway("anthropic/claude-sonnet-4.5");

// Direct: auto-reads OPENAI_API_KEY from env
const openaiModel = openai("gpt-4o");

Use `customProvider` for semantic model aliases (`models('fast')`, `models('smart')`). Neve