bjornmelin/ai-sdk-core

AI SDK Core

Use AI SDK Core to generate text/structured output, call tools, and connect to MCP servers with consistent APIs across providers.

Quick Start

pnpm add ai @ai-sdk/openai zod@^4.3.5

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'openai/gpt-4o',
  prompt: 'Explain quantum computing in one paragraph.',
});

Function Selection

| Need | Function | Streaming | |------|----------|-----------| | Text response | generateText | No | | Streaming text | streamText | Yes | | Structured JSON | generateObject | No | | Streaming JSON | streamObject | Yes | | Embeddings | embed / embedMany | No | | Rerank | rerank | No |

Core Patterns

Generate Text

import { generateText } from 'ai';

const { text, usage } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  system: 'You are a helpful assistant.',
  prompt: 'What is the capital of France?',
});

Stream Text

import { streamText } from 'ai';

const result = streamText({
  model: 'openai/gpt-4o',
  prompt: 'Write a short story.',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Generate Structured Data

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

const { object } = await generateObject({
  model: 'openai/gpt-4o',
  schema: z.object({
    recipe: z.object({
      name: z.string(),
      ingredients: z.array(z.object({ name: z.string(), amount: z.string() })),
      steps: z.array(z.string()),
    }),
  }),
  prompt: 'Generate a recipe for chocolate chip cookies.',
});

Tool Calling (Typed)

import { generateText, tool } from 'ai';
import { z } from 'zod';

const { text, toolCalls } = await generateText({
  model: 'openai/gpt-4o',
  tools: {
    weather: tool({
      description: 'Get weather for a location',
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => ({ temperature: 72, condition: 'sunny' }),
    }),
  },
  prompt: 'What is the weather in San Francisco?',
});

Dynamic Tools (Runtime Schemas)

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

const customTool = dynamicTool({
  description: 'Execute a custom function',
  inputSchema: z.object({}),
  execute: async input => ({ ok: true, input }),
});

Multi-Step Tool Execution

import { generateText, stepCountIs } from 'ai';

const { steps } = await generateText({
  model: 'openai/gpt-4o',
  tools: { search, analyze, summarize },
  stopWhen: stepCountIs(5),
  prompt: 'Research and summarize AI developments.',
});

Tooling Checklist

• Use tool() for typed inputs and dynamicTool() for unknown schemas.
• Use needsApproval for sensitive actions (tool-approval-request/response flow).
• Use stopWhen with stepCountIs/hasToolCall for multi-step loops.
• Use prepareStep for per-step controls (model swap, toolChoice, activeTools, prompt compression).
• Use experimental_context when tools need app-specific context.
• Use inputExamples and strict to improve tool call reliability.

MCP Integration (Model Context Protocol)

• Use createMCPClient() to load MCP tools, resources, and prompts.
• Prefer HTTP transport for production; use Experimental_StdioMCPTransport only for local Node.js servers.
• Close MCP clients after use (try/finally or onFinish).

See references/mcp-integration.md for transports, schema definition, outputSchema typing, and elicitation.

Reference Files

| Reference | When to Use | |-----------|-------------| | references/text-generation.md | generateText/streamText callbacks, streaming, response handling | | references/structured-data.md | generateObject/streamObject, Output API, Zod patterns | | references/tool-calling.md | tool/dynamicTool, approval flow, repair, activeTools, hooks | | references/dynamic-tools.md | dynamicTool patterns, MCP + dynamic tools, large tool sets | | references/embeddings-rag.md | embed/embedMany, rerank, chunking | | references/providers.md | OpenAI/Anthropic/Google setup, registry, AI Gateway | | references/middleware.md | wrapLanguageModel, built-in/custom middleware | | references/mcp-integration.md | MCP client, transports, tools/resources/prompts/elicitation | | references/production.md | Telemetry, error handling, testing, cost control | | references/migration.md | v6 upgrade notes |

Error Handling

import { generateText, AI_APICallError } from 'ai';

try {
  await generateText({ model: 'openai/gpt-4o', prompt: 'Hello' });
} catch (error) {
  if (error instanceof AI_APICallError) {
    console.error('API Error:', error.message);
  }
}

Provider Setup

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

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Hello!',
});

Version Guidance

• Use AI SDK v6+ with matching provider packages.
• Pin major versions in package.json to avoid breaking changes.

Offline Stack Scanner

Before AI SDK migrations or reviews, run the deterministic scanner from the target repository:

python3 skills/ai-sdk-core/scripts/ai_stack_scan.py --root <repo> --family ai-sdk-core --pretty

The scanner emits ai_stack_scan.v1 JSON, performs no network calls, skips symlinks, and checks package manifests plus source signals such as legacy maxSteps, removed stream response helpers, missing inputSchema, and MCP clients without visible cleanup. Treat every signal as a review prompt, then verify with the current AI SDK docs or package source before editing. Keep full scanner JSON local; share only specific redacted signals externally.