Develop Ai Functions Example

1---2name: develop-ai-functions-example3description: 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.4metadata:5  internal: true6---7 8## AI Functions Examples9 10The `examples/ai-functions/` directory contains scripts for validating, testing, and iterating on AI SDK functions across providers.11 12## Example Categories13 14Examples are organized by AI SDK function in `examples/ai-functions/src/`:15 16| Directory          | Purpose                                              |17| ------------------ | ---------------------------------------------------- |18| `generate-text/`   | Non-streaming text generation with `generateText()`  |19| `stream-text/`     | Streaming text generation with `streamText()`        |20| `generate-object/` | Structured output generation with `generateObject()` |21| `stream-object/`   | Streaming structured output with `streamObject()`    |22| `agent/`           | `ToolLoopAgent` examples for agentic workflows       |23| `embed/`           | Single embedding generation with `embed()`           |24| `embed-many/`      | Batch embedding generation with `embedMany()`        |25| `generate-image/`  | Image generation with `generateImage()`              |26| `generate-speech/` | Text-to-speech with `generateSpeech()`               |27| `transcribe/`      | Audio transcription with `transcribe()`              |28| `rerank/`          | Document reranking with `rerank()`                   |29| `middleware/`      | Custom middleware implementations                    |30| `registry/`        | Provider registry setup and usage                    |31| `telemetry/`       | OpenTelemetry integration                            |32| `complex/`         | Multi-component examples (agents, routers)           |33| `lib/`             | Shared utilities (not examples)                      |34| `tools/`           | Reusable tool definitions                            |35 36## File Naming Convention37 38Examples follow the pattern: `{provider}-{feature}.ts`39 40| Pattern                                  | Example                                    | Description                |41| ---------------------------------------- | ------------------------------------------ | -------------------------- |42| `{provider}.ts`                          | `openai.ts`                                | Basic provider usage       |43| `{provider}-{feature}.ts`                | `openai-tool-call.ts`                      | Specific feature           |44| `{provider}-{sub-provider}.ts`           | `amazon-bedrock-anthropic.ts`              | Provider with sub-provider |45| `{provider}-{sub-provider}-{feature}.ts` | `google-vertex-anthropic-cache-control.ts` | Sub-provider with feature  |46 47## Example Structure48 49All examples use the `run()` wrapper from `lib/run.ts` which:50 51- Loads environment variables from `.env`52- Provides error handling with detailed API error logging53 54### Basic Template55 56```typescript57import { providerName } from '@ai-sdk/provider-name';58import { generateText } from 'ai';59import { run } from '../lib/run';60 61run(async () => {62  const result = await generateText({63    model: providerName('model-id'),64    prompt: 'Your prompt here.',65  });66 67  console.log(result.text);68  console.log('Token usage:', result.usage);69  console.log('Finish reason:', result.finishReason);70});71```72 73### Streaming Template74 75```typescript76import { providerName } from '@ai-sdk/provider-name';77import { streamText } from 'ai';78import { printFullStream } from '../lib/print-full-stream';79import { run } from '../lib/run';80 81run(async () => {82  const result = streamText({83    model: providerName('model-id'),84    prompt: 'Your prompt here.',85  });86 87  await printFullStream({ result });88});89```90 91### Tool Calling Template92 93```typescript94import { providerName } from '@ai-sdk/provider-name';95import { generateText, tool } from 'ai';96import { z } from 'zod';97import { run } from '../lib/run';98 99run(async () => {100  const result = await generateText({101    model: providerName('model-id'),102    tools: {103      myTool: tool({104        description: 'Tool description',105        inputSchema: z.object({106          param: z.string().describe('Parameter description'),107        }),108        execute: async ({ param }) => {109          return { result: `Processed: ${param}` };110        },111      }),112    },113    prompt: 'Use the tool to...',114  });115 116  console.log(JSON.stringify(result, null, 2));117});118```119 120### Structured Output Template121 122```typescript123import { providerName } from '@ai-sdk/provider-name';124import { generateObject } from 'ai';125import { z } from 'zod';126import { run } from '../lib/run';127 128run(async () => {129  const result = await generateObject({130    model: providerName('model-id'),131    schema: z.object({132      name: z.string(),133      items: z.array(z.string()),134    }),135    prompt: 'Generate a...',136  });137 138  console.log(JSON.stringify(result.object, null, 2));139  console.log('Token usage:', result.usage);140});141```142 143## Running Examples144 145From the `examples/ai-functions` directory:146 147```bash148pnpm tsx src/generate-text/openai.ts149pnpm tsx src/stream-text/openai-tool-call.ts150pnpm tsx src/agent/openai-generate.ts151```152 153## When to Write Examples154 155Write examples when:156 1571. **Adding a new provider**: Create basic examples for each supported API (`generateText`, `streamText`, `generateObject`, etc.)158 1592. **Implementing a new feature**: Demonstrate the feature with at least one provider example160 1613. **Reproducing a bug**: Create an example that shows the issue for debugging162 1634. **Adding provider-specific options**: Show how to use `providerOptions` for provider-specific settings164 1655. **Creating test fixtures**: Use examples to generate API response fixtures (see `capture-api-response-test-fixture` skill)166 167## Utility Helpers168 169The `lib/` directory contains shared utilities:170 171| File                   | Purpose                                                  |172| ---------------------- | -------------------------------------------------------- |173| `run.ts`               | Error-handling wrapper with `.env` loading               |174| `print.ts`             | Clean object printing (removes undefined values)         |175| `print-full-stream.ts` | Colored streaming output for tool calls, reasoning, text |176| `save-raw-chunks.ts`   | Save streaming chunks for test fixtures                  |177| `present-image.ts`     | Display images in terminal                               |178| `save-audio.ts`        | Save audio files to disk                                 |179 180### Using print utilities181 182```typescript183import { print } from '../lib/print';184 185// Pretty print objects without undefined values186print('Result:', result);187print('Usage:', result.usage, { depth: 2 });188```189 190### Using printFullStream191 192```typescript193import { printFullStream } from '../lib/print-full-stream';194 195const result = streamText({ ... });196await printFullStream({ result }); // Colored output for text, tool calls, reasoning197```198 199## Reusable Tools200 201The `tools/` directory contains reusable tool definitions:202 203```typescript204import { weatherTool } from '../tools/weather-tool';205 206const result = await generateText({207  model: openai('gpt-4o'),208  tools: { weather: weatherTool },209  prompt: 'What is the weather in San Francisco?',210});211```212 213## Best Practices214 2151. **Keep examples focused**: Each example should demonstrate one feature or use case216 2172. **Use descriptive prompts**: Make it clear what the example is testing218 2193. **Handle errors gracefully**: The `run()` wrapper handles this automatically220 2214. **Use realistic model IDs**: Use actual model IDs that work with the provider222 2235. **Add comments for complex logic**: Explain non-obvious code patterns224 2256. **Reuse tools when appropriate**: Use `weatherTool` or create new reusable tools in `tools/`