ai-sdk

name	ai-sdk
description	Use AI SDK 6 with OpenAI models - gpt-5.2 for complex tasks, gpt-5-mini for fast actions
license	MIT
compatibility	opencode
metadata	{"audience":"developers","workflow":"ai-integration"}

What I Do

• Provide correct patterns for AI SDK 6 with OpenAI
• Ensure consistent model usage across the codebase
• Handle text generation, structured output, and tool calling

Model Selection

Model	Use Case	Examples
gpt-5.2	Complex reasoning, multi-step tasks	Email agents, document analysis, KYB assistance
gpt-5-mini	Fast actions, simple extraction	Invoice field extraction, quick classifications

Default to gpt-5.2 unless speed is critical and the task is simple.

Setup Pattern

Always create the OpenAI provider inline - no abstraction layer needed:

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

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY || '' });

Core Patterns

1. Text Generation

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

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY || '' });

const result = await generateText({
  model: openai('gpt-5.2'),
  system: 'You are a helpful assistant.',
  messages: [{ role: 'user', content: 'Hello!' }],
});

console.log(result.text);

2. Structured Output (generateObject)

For extracting structured data with type safety:

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

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY || '' });

const schema = z.object({
  name: z.string(),
  email: z.string().email(),
  amount: z.number(),
});

const result = await generateObject({
  model: openai('gpt-5-mini'), // Use mini for simple extraction
  schema,
  messages: [
    { role: 'user', content: 'Extract: John Doe, [e-mail], $500' },
  ],
});

console.log(result.object); // Typed as { name: string, email: string, amount: number }

3. Tool Calling with Agentic Loops

For multi-step AI agents:

import { generateText, tool, stepCountIs } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';
import { z } from 'zod';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY || '' });

const result = await generateText({
  model: openai('gpt-5.2'), // Use full model for complex tool orchestration
  system: 'You are an assistant that can look up information.',
  messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }],
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      inputSchema: z.object({
        city: z.string().describe('City name'),
      }),
      execute: async ({ city }) => {
        // Your implementation
        return { temperature: 22, condition: 'sunny' };
      },
    }),
  },
  stopWhen: stepCountIs(5), // Allow up to 5 tool call steps
});

// Access tool calls made
const toolCalls = result.steps.flatMap(
  (step) => step.toolCalls?.map((tc) => tc.toolName) || [],
);

4. Streaming (for UI)

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

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY || '' });

const result = await streamText({
  model: openai('gpt-5.2'),
  messages: [{ role: 'user', content: 'Write a poem' }],
});

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

Schema Tips for AI SDK 6

When using generateObject, schemas must be carefully structured:

// GOOD: Use nullable() for optional fields in AI extraction
const schema = z.object({
  required: z.string(),
  optional: z.string().nullable(), // AI can return null
});

// GOOD: Describe fields for better extraction
const schema = z.object({
  amount: z.number().describe('Invoice amount as a positive number'),
  currency: z.string().describe('Currency code: USD, EUR, GBP'),
});

// BAD: Don't use optional() - use nullable() instead
const schema = z.object({
  field: z.string().optional(), // May cause issues with some models
});

Lazy Loading

For edge runtimes or to reduce bundle size, use dynamic imports:

// Lazily import to avoid bundling in edge runtimes if unused
const { createOpenAI } = await import('@ai-sdk/openai');
const { generateObject } = await import('ai');

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY || '' });

Error Handling

try {
  const result = await generateObject({
    model: openai('gpt-5-mini'),
    schema,
    messages,
  });
  return result.object;
} catch (error) {
  if (error instanceof Error) {
    console.error('[AI] Generation failed:', error.message);
  }
  // Optionally retry with simpler schema or different model
  throw error;
}

Existing Usage in Codebase

File	Model	Purpose
src/app/api/ai-email/route.ts	gpt-5.2	Email agent with tools
src/server/routers/invoice-router.ts	gpt-5-mini	Invoice field extraction
src/app/api/kyb-assistant/route.ts	gpt-5.2	KYB form assistance
src/app/api/generate-shareholder-registry/route.ts	gpt-5.2	Document generation
src/server/routers/funding-source-router.ts	gpt-5-mini	Quick extraction

When to Use This Skill

• Adding new AI-powered features
• Implementing structured data extraction
• Building AI agents with tool calling
• Migrating from older AI SDK versions
• Choosing between gpt-5.2 and gpt-5-mini