/develop-ai-functions-example

name: develop-ai-functions-example
description: Develop examples for AI SDK functions. Use when creating, running, or modifying examples under examples/ai-functions/src to validate provider support, demonstrate features, or create test fixtures.
metadata:
  internal: true

AI Functions Examples

The `examples/ai-functions/` directory contains reusable scripts for validating, testing, and iterating on AI SDK functions across providers. Place examples under `examples/ai-functions/src/<function>/<provider>/`. Reproduction-only scripts belong only in the PR description's **End-to-End Verification** section and must never be committed; see [Bug Reproductions](#bug-reproductions).

Example Categories

Examples are organized by AI SDK function in `examples/ai-functions/src/`:

| Directory | Purpose | | ------------------ | ---------------------------------------------------- | | `generate-text/` | Non-streaming text generation with `generateText()` | | `stream-text/` | Streaming text generation with `streamText()` | | `generate-object/` | Structured output generation with `generateObject()` | | `stream-object/` | Streaming structured output with `streamObject()` | | `agent/` | `ToolLoopAgent` examples for agentic workflows | | `embed/` | Single embedding generation with `embed()` | | `embed-many/` | Batch embedding generation with `embedMany()` | | `generate-image/` | Image generation with `generateImage()` | | `generate-speech/` | Text-to-speech with `generateSpeech()` | | `transcribe/` | Audio transcription with `transcribe()` | | `rerank/` | Document reranking with `rerank()` | | `middleware/` | Custom middleware implementations | | `registry/` | Provider registry setup and usage | | `telemetry/` | OpenTelemetry integration | | `complex/` | Multi-component examples (agents, routers) | | `lib/` | Shared utilities (not examples) | | `tools/` | Reusable tool definitions |

File Naming Convention

Group examples by function and provider. Name the entry example `basic.ts` and use descriptive `kebab-case.ts` names for additional examples:

| Pattern | Example | Description | | --------------------------------------------------- | ------------------------------------------------------ | -------------------------- | | `<function>/<provider>/basic.ts` | `generate-text/openai/basic.ts` | Basic provider usage | | `<function>/<provider>/<feature>.ts` | `stream-text/openai/tool-call.ts` | Specific feature | | `<function>/<provider>/<sub-provider>.ts` | `stream-text/amazon-bedrock/anthropic.ts` | Provider with sub-provider | | `<function>/<provider>/<sub-provider>-<feature>.ts` | `stream-text/google/vertex-anthropic-cache-control.ts` | Sub-provider with feature |

Do not create flat provider files such as `generate-text/openai.ts`.

Example Structure

All examples use the `run()` wrapper from `lib/run.ts` which:

• Loads environment variables from `.env`
• Provides error handling with detailed API error logging

Basic Template

import { providerName } from '@ai-sdk/provider-name';
import { generateText } from 'ai';
import { run } from '../../lib/run';

run(async () => {
  const result = await generateText({
    model: providerName('model-id'),
    prompt: 'Your prompt here.',
  });

  console.log(result.text);
  console.log('Token usage:', result.usage);
  console.log('Finish reason:', result.finishReason);
});

Streaming Template

import { providerName } from '@ai-sdk/provider-name';
import { streamText } from 'ai';
import { printFullStream } from '../../lib/print-full-stream';
import { run } from '../../lib/run';

run(async () => {
  const result = streamText({
    model: providerName('model-id'),
    prompt: 'Your prompt here.',
  });

  await printFullStream({ result });
});

Tool Calling Template

import { providerName } from '@ai-sdk/provider-name';
import { generateText, tool } from 'ai';
import { z } from 'zod';
import { run } from '../../lib/run';

run(async () => {
  const result = await generateText({
    model: providerName('model-id'),
    tools: {
      myTool: tool({
        description: 'Tool description',
        inputSchema: z.object({
          param: z.string().describe('Parameter description'),
        }),
        execute: async ({ param }) => {
          return { result: `Processed: ${param}` };
        },
      }),
    },
    prompt: 'Use the tool to...',
  });

  console.log(JSON.stringify(result, null, 2));
});

Structured Output Template

import { providerName } from '@ai-sdk/provider-name';
import { generateObject } from 'ai';
import { z } from 'zod';
import { run } from '../../lib/run';

run(async () => {
  const result = await generateObject({
    model: providerName('model-id'),
    schema: z.object({
      name: z.string(),
      items: z.array(z.string()),
    }),
    prompt: 'Generate a...',
  });

  console.log(JSON.stringify(result.object, null, 2));
  console.log('Token usage:', result.usage);
});

Running Examples

From the `examples/ai-functions` directory:

pnpm tsx src/generate-text/openai/basic.ts
pnpm tsx src/stream-text/openai/tool-call.ts
pnpm tsx src/agent/openai/generate.ts

When to Write Examples

Write examples when:

1. **Adding a new provider**: Create basic examples for each supported API (`generateText`, `streamText`, `generateObject`, etc.)

2. **Imple