ai-sdk-6-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Installation

pnpm add ai@beta @ai-sdk/openai@beta @ai-sdk/react@beta @ai-sdk/groq@beta

Note: Pin versions during beta as breaking changes may occur in patch releases.

pnpm add ai@beta @ai-sdk/openai@beta @ai-sdk/react@beta @ai-sdk/groq@beta

注意: Beta版本期间请固定版本号，因为补丁版本中可能会出现破坏性变更。

What's New in AI SDK 6?

AI SDK 6 新功能

1. Agent Abstraction (New)

1. Agent抽象层（新增）

Unified interface for building agents with full control over execution flow, tool loops, and state management.

typescript

import { ToolLoopAgent } from 'ai';
import { tool } from 'ai';
import { z } from 'zod';

const weatherTool = tool({
  description: 'Get weather for a location',
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }) => ({ temperature: 72, condition: 'sunny' }),
});

const agent = new ToolLoopAgent({
  model: 'groq/llama-3.3-70b-versatile', // or any model
  instructions: 'You are a helpful weather assistant.',
  tools: { weather: weatherTool },
});

// Use the agent
const result = await agent.generate({
  prompt: 'What is the weather in San Francisco?',
});

console.log(result.output);

为构建Agent提供统一接口，可完全控制执行流程、工具循环和状态管理。

typescript

import { ToolLoopAgent } from 'ai';
import { tool } from 'ai';
import { z } from 'zod';

const weatherTool = tool({
  description: 'Get weather for a location',
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }) => ({ temperature: 72, condition: 'sunny' }),
});

const agent = new ToolLoopAgent({
  model: 'groq/llama-3.3-70b-versatile', // or any model
  instructions: 'You are a helpful weather assistant.',
  tools: { weather: weatherTool },
});

// Use the agent
const result = await agent.generate({
  prompt: 'What is the weather in San Francisco?',
});

console.log(result.output);

2. Tool Execution Approval (New)

2. 工具执行审批（新增）

Request user confirmation before executing sensitive tools.

typescript

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

const paymentTool = tool({
  description: 'Process a payment',
  inputSchema: z.object({
    amount: z.number(),
    recipient: z.string(),
  }),
  needsApproval: true, // Require approval
  execute: async ({ amount, recipient }) => {
    return { success: true, id: 'txn-123' };
  },
});

Client-side approval UI:

typescript

export function PaymentToolView({ invocation, addToolApprovalResponse }) {
  if (invocation.state === 'approval-requested') {
    return (
      <div>
        <p>Process payment of ${invocation.input.amount} to {invocation.input.recipient}?</p>
        <button
          onClick={() =>
            addToolApprovalResponse({
              id: invocation.approval.id,
              approved: true,
            })
          }
        >
          Approve
        </button>
        <button
          onClick={() =>
            addToolApprovalResponse({
              id: invocation.approval.id,
              approved: false,
            })
          }
        >
          Deny
        </button>
      </div>
    );
  }
  return null;
}

在执行敏感工具前请求用户确认。

typescript

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

const paymentTool = tool({
  description: 'Process a payment',
  inputSchema: z.object({
    amount: z.number(),
    recipient: z.string(),
  }),
  needsApproval: true, // Require approval
  execute: async ({ amount, recipient }) => {
    return { success: true, id: 'txn-123' };
  },
});

客户端审批UI:

typescript

export function PaymentToolView({ invocation, addToolApprovalResponse }) {
  if (invocation.state === 'approval-requested') {
    return (
      <div>
        <p>是否处理向{invocation.input.recipient}支付${invocation.input.amount}的请求？</p>
        <button
          onClick={() =>
            addToolApprovalResponse({
              id: invocation.approval.id,
              approved: true,
            })
          }
        >
          批准
        </button>
        <button
          onClick={() =>
            addToolApprovalResponse({
              id: invocation.approval.id,
              approved: false,
            })
          }
        >
          拒绝
        </button>
      </div>
    );
  }
  return null;
}

3. Structured Output + Tool Calling (Stable)

3. 结构化输出 + 工具调用（稳定版）

Combine tool calling with structured output generation:

typescript

import { ToolLoopAgent, Output } from 'ai';
import { z } from 'zod';

const agent = new ToolLoopAgent({
  model: 'groq/llama-3.3-70b-versatile',
  tools: { /* ... */ },
  output: Output.object({
    schema: z.object({
      summary: z.string(),
      temperature: z.number(),
      recommendation: z.string(),
    }),
  }),
});

const { output } = await agent.generate({
  prompt: 'What is the weather in San Francisco and what should I wear?',
});

console.log(output);
// { summary: '...', temperature: 72, recommendation: '...' }

将工具调用与结构化输出生成相结合:

typescript

import { ToolLoopAgent, Output } from 'ai';
import { z } from 'zod';

const agent = new ToolLoopAgent({
  model: 'groq/llama-3.3-70b-versatile',
  tools: { /* ... */ },
  output: Output.object({
    schema: z.object({
      summary: z.string(),
      temperature: z.number(),
      recommendation: z.string(),
    }),
  }),
});

const { output } = await agent.generate({
  prompt: 'What is the weather in San Francisco and what should I wear?',
});

console.log(output);
// { summary: '...', temperature: 72, recommendation: '...' }

4. Reranking Support (New)

4. 重排序支持（新增）

Improve search relevance by reordering documents:

typescript

import { rerank } from 'ai';
import { cohere } from '@ai-sdk/cohere';

const { ranking } = await rerank({
  model: cohere.reranking('rerank-v3.5'),
  documents: [
    'sunny day at the beach',
    'rainy afternoon in the city',
    'snowy night in the mountains',
  ],
  query: 'talk about rain',
  topN: 2,
});

console.log(ranking);
// [
//   { originalIndex: 1, score: 0.9, document: 'rainy afternoon...' },
//   { originalIndex: 0, score: 0.3, document: 'sunny day...' }
// ]

通过重新排序文档提升搜索相关性:

typescript

import { rerank } from 'ai';
import { cohere } from '@ai-sdk/cohere';

const { ranking } = await rerank({
  model: cohere.reranking('rerank-v3.5'),
  documents: [
    'sunny day at the beach',
    'rainy afternoon in the city',
    'snowy night in the mountains',
  ],
  query: 'talk about rain',
  topN: 2,
});

console.log(ranking);
// [
//   { originalIndex: 1, score: 0.9, document: 'rainy afternoon...' },
//   { originalIndex: 0, score: 0.3, document: 'sunny day...' }
// ]

Migration from AI SDK 5

从AI SDK 5迁移

Minimal breaking changes expected. Most AI SDK 5 code will work with little modification.

Key differences:

Agent abstraction replaces ad-hoc patterns; consider migrating to
```
ToolLoopAgent
```
.
Structured output now works with
```
generateText
```
/
```
streamText
```
(requires
```
stopWhen
```
).
```
@ai-sdk/*
```
packages may have minor API adjustments during beta.

预计破坏性变更极少。大多数AI SDK 5的代码只需少量修改即可正常运行。

主要差异:

Agent抽象层替代了临时模式；建议迁移至
```
ToolLoopAgent
```
。
结构化输出现在可与
```
generateText
```
/
```
streamText
```
配合使用（需要
```
stopWhen
```
参数）。
Beta版本期间
```
@ai-sdk/*
```
包的API可能会有细微调整。

Groq Provider (Open Weight Models)

Groq 提供商（开源权重模型）

Setup

设置

pnpm add @ai-sdk/groq

Environment:

env

GROQ_API_KEY=your_groq_api_key

pnpm add @ai-sdk/groq

环境变量:

env

GROQ_API_KEY=your_groq_api_key

Open Weight Models Available

可用的开源权重模型

Popular Groq models for AI SDK 6:

```
llama-3.3-70b-versatile
```
(Llama 3.3, 70B, balanced)
```
llama-3.1-8b-instant
```
(Llama 3.1, 8B, fast)
```
mixtral-8x7b-32768
```
(Mixture of Experts)
```
gemma2-9b-it
```
(Google Gemma 2)
```
qwen/qwen3-32b
```
(Qwen 3)

See Groq console for full list.

AI SDK 6支持的热门Groq模型:

```
llama-3.3-70b-versatile
```
（Llama 3.3，70B参数，平衡型）
```
llama-3.1-8b-instant
```
（Llama 3.1，8B参数，快速型）
```
mixtral-8x7b-32768
```
（混合专家模型）
```
gemma2-9b-it
```
（Google Gemma 2）
```
qwen/qwen3-32b
```
（通义千问3）

完整列表请查看Groq控制台。

Basic Llama Example

Llama基础示例

typescript

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

const { text } = await generateText({
  model: groq('llama-3.3-70b-versatile'),
  prompt: 'Write a TypeScript function to compute Fibonacci.',
});

console.log(text);

typescript

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

const { text } = await generateText({
  model: groq('llama-3.3-70b-versatile'),
  prompt: 'Write a TypeScript function to compute Fibonacci.',
});

console.log(text);

Structured Output with Llama (Groq)

Groq Llama的结构化输出

typescript

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

const result = await generateObject({
  model: groq('llama-3.3-70b-versatile'),
  schema: z.object({
    recipe: z.object({
      name: z.string(),
      ingredients: z.array(z.string()),
      instructions: z.array(z.string()),
    }),
  }),
  prompt: 'Generate a simple pasta recipe.',
  providerOptions: {
    groq: {
      structuredOutputs: true, // Enable for supported models
    },
  },
});

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

typescript

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

const result = await generateObject({
  model: groq('llama-3.3-70b-versatile'),
  schema: z.object({
    recipe: z.object({
      name: z.string(),
      ingredients: z.array(z.string()),
      instructions: z.array(z.string()),
    }),
  }),
  prompt: 'Generate a simple pasta recipe.',
  providerOptions: {
    groq: {
      structuredOutputs: true, // Enable for supported models
    },
  },
});

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

Tool Use with Llama (Groq)

Groq Llama的工具调用

typescript

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

const weatherTool = tool({
  description: 'Get weather for a city',
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }) => ({ temp: 72, condition: 'sunny' }),
});

const { text } = await generateText({
  model: groq('llama-3.3-70b-versatile'),
  prompt: 'What is the weather in NYC and LA?',
  tools: { weather: weatherTool },
});

console.log(text);

typescript

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

const weatherTool = tool({
  description: 'Get weather for a city',
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }) => ({ temp: 72, condition: 'sunny' }),
});

const { text } = await generateText({
  model: groq('llama-3.3-70b-versatile'),
  prompt: 'What is the weather in NYC and LA?',
  tools: { weather: weatherTool },
});

console.log(text);

Reasoning Models (Groq)

Groq推理模型

Groq offers reasoning models like

qwen/qwen3-32b

and

deepseek-r1-distill-llama-70b

typescript

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

const { text } = await generateText({
  model: groq('qwen/qwen3-32b'),
  providerOptions: {
    groq: {
      reasoningFormat: 'parsed', // 'parsed', 'hidden', or 'raw'
      reasoningEffort: 'default', // low, medium, high
    },
  },
  prompt: 'How many "r"s are in the word "strawberry"?',
});

console.log(text);

Groq提供如

qwen/qwen3-32b

和

deepseek-r1-distill-llama-70b

等推理模型:

typescript

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

const { text } = await generateText({
  model: groq('qwen/qwen3-32b'),
  providerOptions: {
    groq: {
      reasoningFormat: 'parsed', // 'parsed', 'hidden', or 'raw'
      reasoningEffort: 'default', // low, medium, high
    },
  },
  prompt: 'How many "r"s are in the word "strawberry"?',
});

console.log(text);

Image Input with Llama (Groq Multi-Modal)

Groq多模态Llama的图片输入

typescript

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

const { text } = await generateText({
  model: groq('meta-llama/llama-4-scout-17b-16e-instruct'), // Multi-modal model
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What is in this image?' },
        { type: 'image', image: 'https://example.com/image.jpg' },
      ],
    },
  ],
});

console.log(text);

typescript

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

const { text } = await generateText({
  model: groq('meta-llama/llama-4-scout-17b-16e-instruct'), // Multi-modal model
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What is in this image?' },
        { type: 'image', image: 'https://example.com/image.jpg' },
      ],
    },
  ],
});

console.log(text);

Vercel AI Gateway

What It Is

是什么

A unified interface to access models from 20+ providers (OpenAI, Anthropic, Google, Groq, xAI, Mistral, etc.) through a single API. Requires Vercel account and credit card.

一个统一接口，可通过单一API访问来自20+提供商（OpenAI、Anthropic、Google、Groq、xAI、Mistral等）的模型。需要Vercel账户和信用卡。

Setup

设置

env

AI_GATEWAY_API_KEY=your_gateway_api_key

Get your key from Vercel Dashboard > AI Gateway.

⚠️ Note: Credit card required for Gateway usage. You will be billed for model calls routed through the gateway.

env

AI_GATEWAY_API_KEY=your_gateway_api_key

从Vercel控制台 > AI Gateway获取密钥。

⚠️注意: 使用Gateway需要绑定信用卡。通过网关路由的模型调用会产生费用。

Authentication

认证

API Key Authentication

API密钥认证

Set via environment variable or directly in code:

typescript

import { createGateway } from 'ai';

const gateway = createGateway({
  apiKey: process.env.AI_GATEWAY_API_KEY,
});

通过环境变量或直接在代码中设置:

typescript

import { createGateway } from 'ai';

const gateway = createGateway({
  apiKey: process.env.AI_GATEWAY_API_KEY,
});

OIDC Authentication (Vercel Deployments)

OIDC认证（Vercel部署）

When deployed to Vercel, use OIDC tokens for automatic authentication (no API key needed):

Production/Preview: Automatic OIDC handling, no setup required.

Local Development:

Install & authenticate Vercel CLI:
```
vercel login
```
Pull OIDC token:
```
vercel env pull
```
Use
```
vercel dev
```
to start dev server (handles token refresh automatically)

Note: OIDC tokens expire after 12 hours; use

vercel dev

for automatic refresh, or run

vercel env pull

again manually.

bash

undefined

部署到Vercel时，使用OIDC令牌进行自动认证（无需API密钥）:

生产/预览环境: 自动处理OIDC，无需额外设置。

本地开发:

安装并认证Vercel CLI:
```
vercel login
```
拉取OIDC令牌:
```
vercel env pull
```
使用
```
vercel dev
```
启动开发服务器（自动处理令牌刷新）

注意: OIDC令牌12小时后过期；使用

vercel dev

可自动刷新，或手动重新运行

vercel env pull

。

bash

undefined

Start dev with automatic token management

启动开发服务器并自动管理令牌

vercel dev

undefined

vercel dev

undefined

Basic Usage

基础用法

typescript

import { generateText } from 'ai';

// Plain model string format: creator/model-name
const { text } = await generateText({
  model: 'openai/gpt-5',
  prompt: 'Explain quantum computing.',
});

console.log(text);

typescript

import { generateText } from 'ai';

// 纯模型字符串格式: 创作者/模型名称
const { text } = await generateText({
  model: 'openai/gpt-5',
  prompt: 'Explain quantum computing.',
});

console.log(text);

Gateway Instance

Gateway实例

typescript

import { createGateway } from 'ai';

const gateway = createGateway({
  apiKey: process.env.AI_GATEWAY_API_KEY,
});

const { text } = await generateText({
  model: gateway('anthropic/claude-sonnet-4'),
  prompt: 'Write a haiku about AI.',
});

console.log(text);

typescript

import { createGateway } from 'ai';

const gateway = createGateway({
  apiKey: process.env.AI_GATEWAY_API_KEY,
});

const { text } = await generateText({
  model: gateway('anthropic/claude-sonnet-4'),
  prompt: 'Write a haiku about AI.',
});

console.log(text);

Model Discovery (Dynamic)

模型发现（动态）

typescript

import { gateway } from 'ai';

const availableModels = await gateway.getAvailableModels();

availableModels.models.forEach((model) => {
  console.log(`${model.id}: ${model.name}`);
  if (model.pricing) {
    console.log(`  Input: $${model.pricing.input}/token`);
    console.log(`  Output: $${model.pricing.output}/token`);
  }
});

// Use first model
const { text } = await generateText({
  model: availableModels.models[0].id,
  prompt: 'Hello world',
});

typescript

import { gateway } from 'ai';

const availableModels = await gateway.getAvailableModels();

availableModels.models.forEach((model) => {
  console.log(`${model.id}: ${model.name}`);
  if (model.pricing) {
    console.log(`  输入: $${model.pricing.input}/token`);
    console.log(`  输出: $${model.pricing.output}/token`);
  }
});

// 使用第一个模型
const { text } = await generateText({
  model: availableModels.models[0].id,
  prompt: 'Hello world',
});

Check Credit Usage

查看额度使用情况

typescript

import { gateway } from 'ai';

const credits = await gateway.getCredits();
console.log(`Balance: ${credits.balance} credits`);
console.log(`Total used: ${credits.total_used} credits`);

typescript

import { gateway } from 'ai';

const credits = await gateway.getCredits();
console.log(`余额: ${credits.balance} 额度`);
console.log(`总使用量: ${credits.total_used} 额度`);

Streaming with Gateway

Gateway流式输出

typescript

import { streamText } from 'ai';

const { textStream } = await streamText({
  model: 'openai/gpt-5',
  prompt: 'Explain serverless architecture.',
});

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

typescript

import { streamText } from 'ai';

const { textStream } = await streamText({
  model: 'openai/gpt-5',
  prompt: 'Explain serverless architecture.',
});

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

Tool Use with Gateway

Gateway工具调用

typescript

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

const weatherTool = tool({
  description: 'Get weather',
  inputSchema: z.object({ location: z.string() }),
  execute: async ({ location }) => `Sunny in ${location}`,
});

const { text } = await generateText({
  model: 'xai/grok-4', // Via Gateway
  prompt: 'What is the weather in SF?',
  tools: { getWeather: weatherTool },
});

console.log(text);

typescript

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

const weatherTool = tool({
  description: 'Get weather',
  inputSchema: z.object({ location: z.string() }),
  execute: async ({ location }) => `Sunny in ${location}`,
});

const { text } = await generateText({
  model: 'xai/grok-4', // Via Gateway
  prompt: 'What is the weather in SF?',
  tools: { getWeather: weatherTool },
});

console.log(text);

Bring Your Own Key (BYOK)

自带密钥（BYOK）

Connect your own provider credentials to Gateway for private resource access:

typescript

import { generateText } from 'ai';
import type { GatewayProviderOptions } from '@ai-sdk/gateway';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4',
  prompt: 'Use my Anthropic account',
  providerOptions: {
    gateway: {
      byok: {
        anthropic: [{ apiKey: 'sk-ant-...' }],
      },
    } satisfies GatewayProviderOptions,
  },
});

Set up BYOK credentials in Vercel team's AI Gateway settings; no code changes needed after configuration.

连接您自己的提供商凭证到Gateway，以访问私有资源:

typescript

import { generateText } from 'ai';
import type { GatewayProviderOptions } from '@ai-sdk/gateway';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4',
  prompt: 'Use my Anthropic account',
  providerOptions: {
    gateway: {
      byok: {
        anthropic: [{ apiKey: 'sk-ant-...' }],
      },
    } satisfies GatewayProviderOptions,
  },
});

在Vercel团队的AI Gateway设置中配置BYOK凭证；配置完成后无需修改代码。

Provider-Executed Tools

提供商执行的工具

Some providers offer tools executed server-side (e.g., OpenAI web search). Use through Gateway by importing the provider:

typescript

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

const result = await generateText({
  model: 'openai/gpt-5-mini',
  prompt: 'What is the Vercel AI Gateway?',
  stopWhen: stepCountIs(10),
  tools: {
    web_search: openai.tools.webSearch({}),
  },
});

console.log(result.text);

Note: Tools requiring account-specific configuration (e.g., Claude Agent Skills) may need direct provider access via BYOK.

部分提供商支持在服务器端执行工具（如OpenAI网页搜索）。通过Gateway使用时需导入对应提供商:

typescript

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

const result = await generateText({
  model: 'openai/gpt-5-mini',
  prompt: 'What is the Vercel AI Gateway?',
  stopWhen: stepCountIs(10),
  tools: {
    web_search: openai.tools.webSearch({}),
  },
});

console.log(result.text);

注意: 需要账户特定配置的工具（如Claude Agent Skills）可能需要通过BYOK直接访问提供商。

Provider Routing & Fallback

提供商路由与降级

Core Routing Options:

```
order
```
: Try providers in sequence (fallback priority)
```
only
```
: Restrict to specific providers only
```
models
```
: Fallback to alternative models if primary fails
```
user
```
: Track usage per end-user
```
tags
```
: Categorize requests for analytics
```
zeroDataRetention
```
: Only use providers with zero data retention
```
byok
```
: Request-scoped BYOK credentials

核心路由选项:

```
order
```
: 按顺序尝试提供商（降级优先级）
```
only
```
: 仅限制使用特定提供商
```
models
```
: 若主模型失败，降级到备选模型
```
user
```
: 按终端用户跟踪使用情况
```
tags
```
: 为请求分类以便分析
```
zeroDataRetention
```
: 仅使用零数据保留的提供商
```
byok
```
: 请求级别的BYOK凭证

Example: Provider & Model Fallback

示例：提供商与模型降级

typescript

import { generateText } from 'ai';
import type { GatewayProviderOptions } from '@ai-sdk/gateway';

const { text } = await generateText({
  model: 'openai/gpt-4o', // Primary model
  prompt: 'Write a TypeScript haiku',
  providerOptions: {
    gateway: {
      order: ['vertex', 'anthropic'], // Try Vertex AI first, then Anthropic
      only: ['vertex', 'anthropic'], // Only allow these providers
      models: ['openai/gpt-5-nano', 'gemini-2.0-flash'], // Fallback models
      user: 'user-123',
      tags: ['code-gen', 'v2'],
    } satisfies GatewayProviderOptions,
  },
});

// Fallback sequence:
// 1. Try vertex with openai/gpt-4o
// 2. Try anthropic with openai/gpt-4o
// 3. Try vertex with openai/gpt-5-nano
// 4. Try anthropic with openai/gpt-5-nano
// etc.

typescript

import { generateText } from 'ai';
import type { GatewayProviderOptions } from '@ai-sdk/gateway';

const { text } = await generateText({
  model: 'openai/gpt-4o', // 主模型
  prompt: 'Write a TypeScript haiku',
  providerOptions: {
    gateway: {
      order: ['vertex', 'anthropic'], // 先尝试Vertex AI，再尝试Anthropic
      only: ['vertex', 'anthropic'], // 仅允许这些提供商
      models: ['openai/gpt-5-nano', 'gemini-2.0-flash'], // 备选模型
      user: 'user-123',
      tags: ['code-gen', 'v2'],
    } satisfies GatewayProviderOptions,
  },
});

// 降级顺序:
// 1. 使用Vertex AI调用openai/gpt-4o
// 2. 使用Anthropic调用openai/gpt-4o
// 3. 使用Vertex AI调用openai/gpt-5-nano
// 4. 使用Anthropic调用openai/gpt-5-nano
// 以此类推

Example: Usage Tracking

示例：使用情况跟踪

typescript

import { generateText } from 'ai';
import type { GatewayProviderOptions } from '@ai-sdk/gateway';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4',
  prompt: 'Summarize this document...',
  providerOptions: {
    gateway: {
      user: 'user-abc-123', // Track per end-user
      tags: ['document-summary', 'premium-feature'],
    } satisfies GatewayProviderOptions,
  },
});

// View analytics by user and feature in Vercel Dashboard

typescript

import { generateText } from 'ai';
import type { GatewayProviderOptions } from '@ai-sdk/gateway';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4',
  prompt: 'Summarize this document...',
  providerOptions: {
    gateway: {
      user: 'user-abc-123', // 按终端用户跟踪
      tags: ['document-summary', 'premium-feature'],
    } satisfies GatewayProviderOptions,
  },
});

// 在Vercel控制台按用户和功能查看分析数据

Zero Data Retention

零数据保留

Route requests only to providers with zero data retention policies for sensitive data:

typescript

import { generateText } from 'ai';
import type { GatewayProviderOptions } from '@ai-sdk/gateway';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4',
  prompt: 'Process sensitive document...',
  providerOptions: {
    gateway: {
      zeroDataRetention: true, // Enforce zero data retention
    } satisfies GatewayProviderOptions,
  },
});

When

zeroDataRetention: true

, Gateway only routes to providers that don't retain your data. No enforcement applied if omitted or

false

仅将请求路由到采用零数据保留政策的提供商，以处理敏感数据:

typescript

import { generateText } from 'ai';
import type { GatewayProviderOptions } from '@ai-sdk/gateway';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4',
  prompt: 'Process sensitive document...',
  providerOptions: {
    gateway: {
      zeroDataRetention: true, // 强制零数据保留
    } satisfies GatewayProviderOptions,
  },
});

当设置

zeroDataRetention: true

时，Gateway仅会路由到不保留您数据的提供商。若省略或设置为

false

，则不执行此限制。

Key Concepts

核心概念

Call Options for Agents

Agent调用选项

Dynamically configure agents at runtime:

typescript

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

const supportAgent = new ToolLoopAgent({
  model: 'groq/llama-3.3-70b-versatile',
  callOptionsSchema: z.object({
    userId: z.string(),
    accountType: z.enum(['free', 'pro', 'enterprise']),
  }),
  instructions: 'You are a support agent.',
  prepareCall: ({ options, ...settings }) => ({
    ...settings,
    instructions:
      settings.instructions +
      `\nUser: ${options.userId}, Account: ${options.accountType}`,
  }),
});

const result = await supportAgent.generate({
  prompt: 'How do I upgrade?',
  options: {
    userId: 'user-456',
    accountType: 'free',
  },
});

在运行时动态配置Agent:

typescript

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

const supportAgent = new ToolLoopAgent({
  model: 'groq/llama-3.3-70b-versatile',
  callOptionsSchema: z.object({
    userId: z.string(),
    accountType: z.enum(['free', 'pro', 'enterprise']),
  }),
  instructions: 'You are a support agent.',
  prepareCall: ({ options, ...settings }) => ({
    ...settings,
    instructions:
      settings.instructions +
      `\n用户: ${options.userId}, 账户类型: ${options.accountType}`,
  }),
});

const result = await supportAgent.generate({
  prompt: 'How do I upgrade?',
  options: {
    userId: 'user-456',
    accountType: 'free',
  },
});

UI Integration with React

与React的UI集成

typescript

import { createAgentUIStreamResponse } from 'ai';
import { useChat } from '@ai-sdk/react';
import { InferAgentUIMessage } from 'ai';

// Server-side
export async function POST(request: Request) {
  const { messages } = await request.json();
  return createAgentUIStreamResponse({
    agent: weatherAgent,
    messages,
  });
}

// Client-side
type AgentMessage = InferAgentUIMessage<typeof weatherAgent>;
const { messages, sendMessage } = useChat<AgentMessage>();

typescript

import { createAgentUIStreamResponse } from 'ai';
import { useChat } from '@ai-sdk/react';
import { InferAgentUIMessage } from 'ai';

// 服务端
export async function POST(request: Request) {
  const { messages } = await request.json();
  return createAgentUIStreamResponse({
    agent: weatherAgent,
    messages,
  });
}

// 客户端
type AgentMessage = InferAgentUIMessage<typeof weatherAgent>;
const { messages, sendMessage } = useChat<AgentMessage>();

Best Practices

最佳实践

Groq

Use
```
llama-3.3-70b-versatile
```
for balanced performance and cost.
Use
```
llama-3.1-8b-instant
```
for low-latency, lightweight tasks.
Enable
```
parallelToolCalls: true
```
(default) for faster multi-tool execution.
Use
```
serviceTier: 'flex'
```
for 10x rate limits if you can tolerate occasional failures.

对于平衡性能和成本的场景，使用
```
llama-3.3-70b-versatile
```
。
对于低延迟、轻量任务，使用
```
llama-3.1-8b-instant
```
。
启用
```
parallelToolCalls: true
```
（默认开启）以加快多工具执行速度。
如果可以容忍偶尔失败，使用
```
serviceTier: 'flex'
```
可获得10倍的速率限制。

Vercel AI Gateway

Always add credit card; gateway is pay-per-token.
Use
```
only
```
/
```
order
```
to control routing and costs.
Use
```
user
```
and
```
tags
```
for spend tracking and debugging.
Enable
```
zeroDataRetention
```
for sensitive data.
Check
```
gateway.getCredits()
```
regularly to monitor usage.

务必绑定信用卡；Gateway按token计费。
使用
```
only
```
/
```
order
```
控制路由和成本。
使用
```
user
```
和
```
tags
```
进行支出跟踪和调试。
处理敏感数据时启用
```
zeroDataRetention
```
。
定期调用
```
gateway.getCredits()
```
监控使用情况。

Agents

Agent

Use
```
ToolLoopAgent
```
as a starting point; extend only if needed.
Combine structured output with tool calling for rich responses.
Use tool approval for payment/deletion operations.
Set
```
stopWhen
```
to control loop iterations (default:
```
stepCountIs(20)
```
).

以
```
ToolLoopAgent
```
为起点；仅在需要时进行扩展。
将结构化输出与工具调用结合以生成丰富响应。
对于支付/删除操作使用工具审批。
设置
```
stopWhen
```
控制循环迭代次数（默认值:
```
stepCountIs(20)
```
）。

Common Patterns

常见模式

RAG Agent

typescript

const ragAgent = new ToolLoopAgent({
  model: 'groq/llama-3.3-70b-versatile',
  tools: {
    searchDocs: tool({
      description: 'Search documentation',
      inputSchema: z.object({ query: z.string() }),
      execute: async ({ query }) => {
        // Call vector DB (Upstash, Pinecone, etc.)
        return { docs: [/* ... */] };
      },
    }),
  },
  instructions: 'Answer questions by searching docs.',
});

typescript

const ragAgent = new ToolLoopAgent({
  model: 'groq/llama-3.3-70b-versatile',
  tools: {
    searchDocs: tool({
      description: 'Search documentation',
      inputSchema: z.object({ query: z.string() }),
      execute: async ({ query }) => {
        // 调用向量数据库（Upstash、Pinecone等）
        return { docs: [/* ... */] };
      },
    }),
  },
  instructions: 'Answer questions by searching docs.',
});

Multi-Provider with Fallback

多提供商降级

typescript

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4',
  prompt: 'Complex task requiring reasoning',
  providerOptions: {
    gateway: {
      models: ['openai/gpt-5', 'gemini-2.0-flash'],
    },
  },
});

typescript

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4',
  prompt: 'Complex task requiring reasoning',
  providerOptions: {
    gateway: {
      models: ['openai/gpt-5', 'gemini-2.0-flash'],
    },
  },
});

Cost-Optimized Selection

成本优化选型

typescript

const isSensitive = userQuery.includes('payment');
const model = isSensitive 
  ? 'anthropic/claude-sonnet-4' 
  : 'openai/gpt-5-nano';

const { text } = await generateText({
  model,
  prompt: userQuery,
});

typescript

const isSensitive = userQuery.includes('payment');
const model = isSensitive 
  ? 'anthropic/claude-sonnet-4' 
  : 'openai/gpt-5-nano';

const { text } = await generateText({
  model,
  prompt: userQuery,
});

Timeline

时间线

AI SDK 6 Beta: Available now (pin versions)
Stable Release: End of 2025

AI SDK 6 Beta: 现已可用（请固定版本号）
稳定版发布: 2025年底

ai-sdk-6-skills

Original

Translation

Links

Links

Installation

Installation

What's New in AI SDK 6?

AI SDK 6 新功能

1. Agent Abstraction (New)

1. Agent抽象层（新增）

2. Tool Execution Approval (New)

2. 工具执行审批（新增）

3. Structured Output + Tool Calling (Stable)

3. 结构化输出 + 工具调用（稳定版）

4. Reranking Support (New)

4. 重排序支持（新增）

Migration from AI SDK 5

从AI SDK 5迁移

Groq Provider (Open Weight Models)

Groq 提供商（开源权重模型）

Setup

设置

Open Weight Models Available

可用的开源权重模型

Basic Llama Example

Llama基础示例

Structured Output with Llama (Groq)

Groq Llama的结构化输出

Tool Use with Llama (Groq)

Groq Llama的工具调用

Reasoning Models (Groq)

Groq推理模型

Image Input with Llama (Groq Multi-Modal)

Groq多模态Llama的图片输入

Vercel AI Gateway

Vercel AI Gateway

What It Is

是什么

Setup

设置

Authentication

认证

API Key Authentication

API密钥认证

OIDC Authentication (Vercel Deployments)

OIDC认证（Vercel部署）

Start dev with automatic token management

启动开发服务器并自动管理令牌

Basic Usage

基础用法

Gateway Instance

Gateway实例

Model Discovery (Dynamic)

模型发现（动态）

Check Credit Usage

查看额度使用情况

Streaming with Gateway

Gateway流式输出

Tool Use with Gateway

Gateway工具调用

Bring Your Own Key (BYOK)

自带密钥（BYOK）

Provider-Executed Tools

提供商执行的工具

Provider Routing & Fallback

提供商路由与降级

Example: Provider & Model Fallback

示例：提供商与模型降级

Example: Usage Tracking

示例：使用情况跟踪

Zero Data Retention

零数据保留

Key Concepts

核心概念

Call Options for Agents

Agent调用选项

UI Integration with React

与React的UI集成

Best Practices