Required dependencies

npm install ai @ai-sdk/provider-utils @ai-sdk/gateway
# Choose at least one provider, e.g.:
npm install @ai-sdk/openai
# For schema/tool validation:
npm install zod

No native modules, no pod install, no prebuild steps required. Runs in Node.js 18+ and edge runtimes.

Project setup

1. Copy the source/ directory into your project, e.g. lib/ai-sdk/.
2. Update tsconfig.json to include the source:

{
  "compilerOptions": {
    "paths": {
      "ai-sdk-core": ["./lib/ai-sdk/index.ts"]
    }
  },
  "include": ["lib/ai-sdk/src/**/*"]
}

3. If you use the package directly via npm (ai), skip the path alias—imports from "ai" resolve automatically.
4. Set provider API keys as environment variables, e.g.:

OPENAI_API_KEY=sk-...

5. No special Babel config is required; the source is plain TypeScript with standard ESM imports.

Public API

tool

import { tool } from 'ai';

const myTool = tool({
  description: string;
  parameters: Schema<TInput>;
  execute?: ToolExecuteFunction<TInput, TOutput>;
});

Defines a typed tool that can be passed to generateText or streamText. Use this whenever you want the model to call a function with validated input. The parameters field accepts a Zod schema (via zodSchema) or a JSON schema (via jsonSchema).

generateId

import { generateId } from 'ai';

const id: string = generateId(); // URL-safe random ID

Generates a URL-safe unique identifier. Use it to create message IDs, request IDs, or correlation tokens without pulling in a separate UUID library.

ToolLoopAgent

import { ToolLoopAgent, type ToolLoopAgentSettings } from 'ai';

const agent = new ToolLoopAgent(settings: ToolLoopAgentSettings);
await agent.run(params: AgentCallParameters);
await agent.stream(params: AgentStreamParameters);

Implements an agentic tool-use loop: the model calls tools repeatedly until it produces a final answer. Use when you need multi-step reasoning with tool invocations managed automatically. ToolLoopAgentSettings configures the model, tools, max steps, and callbacks.

createAgentUIStream

import { createAgentUIStream } from 'ai';

const stream = createAgentUIStream(options);

Creates a UI-compatible agent stream that emits structured message parts for frontend rendering. Use when piping agent output to a web client that consumes the AI SDK UI message protocol.

zodSchema

import { zodSchema } from 'ai';
import { z } from 'zod';

const schema = zodSchema(z.object({ city: z.string() }));

Wraps a Zod schema into the AI SDK Schema interface accepted by tool, generateObject, and similar APIs. Always use this adapter instead of passing a raw Zod schema directly.

Working examples

Scenario - Generate structured JSON from a prompt

Use generateObject with a Zod schema to extract typed data from a model response.

import { generateObject, zodSchema } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const result = await generateObject({
  model: openai('gpt-4o'),
  schema: zodSchema(z.object({
    name: z.string(),
    population: z.number(),
  })),
  prompt: 'Give me facts about Paris.',
});

console.log(result.object.name);       // "Paris"
console.log(result.object.population); // e.g. 2161000

Scenario - Tool-use agent loop

Run a ToolLoopAgent that can call a weather tool and produce a final answer.

import { ToolLoopAgent, tool, zodSchema } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const weatherTool = tool({
  description: 'Get current temperature for a city',
  parameters: zodSchema(z.object({ city: z.string() })),
  execute: async ({ city }) => ({ temperature: 22, unit: 'C', city }),
});

const agent = new ToolLoopAgent({
  model: openai('gpt-4o'),
  tools: { weather: weatherTool },
  maxSteps: 5,
});

const result = await agent.run({
  prompt: 'What is the weather in Tokyo?',
});

console.log(result.text);

Scenario - Batch embeddings for semantic search indexing

Embed a list of documents in one call using embedMany.

import { embedMany } from 'ai';
import { openai } from '@ai-sdk/openai';

const documents = [
  'The Eiffel Tower is in Paris.',
  'Mount Fuji is in Japan.',
  'The Colosseum is in Rome.',
];

const { embeddings } = await embedMany({
  model: openai.embedding('text-embedding-3-small'),
  values: documents,
});

// embeddings[i] is a number[] vector for documents[i]
console.log(embeddings[0].length); // e.g. 1536

Scenario - Streaming agent output to a web response

Pipe an agent's UI stream directly into an HTTP response for a Next.js / Express route.

import { ToolLoopAgent, createAgentUIStreamResponse, zodSchema, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

export async function POST(req: Request): Promise<Response> {
  const { prompt } = await req.json();

  const agent = new ToolLoopAgent({
    model: openai('gpt-4o'),
    tools: {},
    maxSteps: 3,
  });

  return createAgentUIStreamResponse({
    agent,
    params: { prompt },
  });
}

File walkthrough

• index.ts - Thin re-export shim; forwards everything from src/ so the package root resolves correctly.
• internal/index.ts - Exports internal helpers (prompt preparation, retry, usage types) intended only for provider packages, not end users.
• src/index.ts - Aggregates all domain exports plus re-exports from @ai-sdk/provider-utils and @ai-sdk/gateway.
• src/agent/ - ToolLoopAgent class, agent settings types, UI stream creation, and response piping utilities.
• src/embed/ - embed (single), embedMany (batch), result types, and embedding event types.
• src/error/ - Typed errors: InvalidArgumentError, NoObjectGeneratedError, NoSuchToolError, ToolCallRepairError, and others.
• src/generate-image/ - Image generation result wrapper and related types.
• src/generate-object/ - Structured LLM output with schema validation and repair.
• src/generate-speech/ - Speech synthesis interface.
• src/generate-text/ - Core generateText and streamText implementations.
• src/generate-video/ - Video generation interface.
• src/logger/ - Pluggable logger interface used throughout the library.
• src/middleware/ - LanguageModelMiddleware interface for wrapping models.
• src/model/ - resolveLanguageModel and registry resolution helpers.
• src/prompt/ - Prompt standardization, tool preparation, and call-options normalization.
• src/registry/ - ModelRegistry for managing multiple provider models.
• src/rerank/ - Reranking function and result type.
• src/telemetry/ - OpenTelemetry attribute helpers and span utilities.
• src/text-stream/ - Async-iterable and ReadableStream stream utilities.
• src/transcribe/ - Audio transcription function and result type.
• src/types/ - Shared types: usage counters, finish reasons, message parts.
• src/ui/ - UI message types and client-facing data shapes.
• src/ui-message-stream/ - Server-to-client streaming protocol for UI messages.
• src/upload-file/ - File upload helpers for multimodal prompts.
• src/upload-skill/ - Composable upload skill abstraction.
• src/util/ - Utilities: generateId, retry logic, abort signal merging, stream helpers.
• scripts/check-bundle-size.ts - CI script to assert the built bundle stays within size limits.

Common pitfalls and fixes

• Missing provider package: tool and generation functions require a concrete model from a provider package (@ai-sdk/openai, etc.); importing only ai gives you the interface, not a model implementation. Fix: npm install @ai-sdk/openai and import { openai } from '@ai-sdk/openai'.
• Raw Zod schema passed to tool: Passing a Zod schema directly without zodSchema() wrapper causes a type error at compile time and a runtime validation miss. Fix: always wrap with zodSchema(z.object(...)).
• ESM/CJS interop in bundlers: The package ships dual ESM/CJS via tsup; if your bundler resolves the CJS build and you see duplicate module issues, add "moduleResolution": "bundler" or "node16" to tsconfig.json.
• Edge runtime incompatibility: Some Node.js built-ins (fs, crypto via node: prefix) are not available in edge runtimes. The SDK targets edge-compatible APIs, but any custom execute function you write must also avoid Node-only APIs.
• generateObject schema mismatch: If the model returns JSON that does not match your schema, an NoObjectGeneratedError is thrown. Fix: catch it, inspect error.text, and consider enabling repair mode or loosening your schema.
• OPENAI_API_KEY not set: Calls silently fail or throw an auth error at runtime, not at import time. Fix: assert process.env.OPENAI_API_KEY in your server startup before any model calls.

Vibe-coding prompt template

I have dropped the AI SDK core source into `source/` in my project.
I also have `USAGE.md` open which documents the public API and working examples.

The upstream package is `ai` (Vercel AI SDK core, `packages/ai`).

Please help me integrate it into my existing TypeScript/Node.js project step by step:

1. Read `USAGE.md` and `source/src/index.ts` to understand all available exports.
2. Install any missing dependencies listed in the "Required dependencies" section of USAGE.md.
3. Wire the TypeScript path alias (if I am using the local source) or confirm
   the `ai` npm package resolves correctly.
4. Show me how to call `generateObject` with a Zod schema using my chosen provider.
5. Show me how to build a `ToolLoopAgent` with at least one tool that calls an
   external API, and stream the result to an HTTP response.
6. Show me how to use `embedMany` to index a list of strings for semantic search.
7. Add error handling using the typed error classes from `source/src/error/`.
8. Point out any pitfalls specific to my runtime (edge / Node.js / serverless).

Use only symbols that appear in `source/src/index.ts` and `USAGE.md`.
Do not invent function names. Show complete, runnable TypeScript snippets.

License and credit

License: see source/LICENSE if present, or refer to the Vercel AI SDK repository for the current license terms (Apache-2.0 as of the latest release). Upstream package: ai by Vercel.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Unified TypeScript SDK for Multi-Provider AI Inference

SaaS, AI & Subscription Products

Free