AI SDK 6 Beta 新特性详解：智能体抽象、工具执行审批与结构化输出

ai-sdk-6-skills by gocallum/nextjs16-agent-skills

253 周安装量

18 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/gocallum/nextjs16-agent-skills --skill ai-sdk-6-skills

AI/机器学习开发 JavaScript 框架

🇨🇳中文介绍

链接

AI SDK 6 Beta 文档: https://v6.ai-sdk.dev/docs/announcing-ai-sdk-6-beta
Groq 提供商: https://v6.ai-sdk.dev/providers/ai-sdk-providers/groq
Vercel AI 网关: https://v6.ai-sdk.dev/providers/ai-sdk-providers/ai-gateway
AI SDK GitHub: https://github.com/vercel/ai
Groq 控制台模型: https://console.groq.com/docs/models

安装

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

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

AI SDK 6 有哪些新特性？

1. 智能体抽象 (新功能)

用于构建智能体的统一接口，可完全控制执行流程、工具循环和状态管理。

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);

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

2. 工具执行审批 (新功能)

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

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' };
  },
});

客户端审批界面：

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;
}

3. 结构化输出 + 工具调用 (稳定版)

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

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. 重新排序支持 (新功能)

通过重新排序文档来提高搜索相关性：

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...' }
// ]

预计只有最小的破坏性更改。大多数 AI SDK 5 代码只需少量修改即可工作。

智能体抽象取代了临时模式；考虑迁移到 ToolLoopAgent。
结构化输出现在可与 generateText / streamText 一起使用（需要 stopWhen）。
@ai-sdk/* 包在 Beta 期间可能会有较小的 API 调整。

Groq 提供商 (开源权重模型)

pnpm add @ai-sdk/groq

GROQ_API_KEY=your_groq_api_key

可用的开源权重模型

适用于 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 (Qwen 3)

完整列表请参见 Groq 控制台。

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);

使用 Llama (Groq) 进行结构化输出

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, // 为支持的模型启用
    },
  },
});

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

使用 Llama (Groq) 进行工具调用

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);

Groq 提供推理模型，例如 qwen/qwen3-32b 和 deepseek-r1-distill-llama-70b：

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', 或 'raw'
      reasoningEffort: 'default', // low, medium, high
    },
  },
  prompt: 'How many "r"s are in the word "strawberry"?',
});

console.log(text);

使用 Llama (Groq 多模态) 进行图像输入

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

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

console.log(text);

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

AI_GATEWAY_API_KEY=your_gateway_api_key

从 Vercel 仪表板 > AI 网关获取您的密钥。

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

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

import { createGateway } from 'ai';

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

OIDC 认证 (Vercel 部署)

部署到 Vercel 时，使用 OIDC 令牌进行自动身份验证（无需 API 密钥）：

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

本地开发环境 :

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

注意：OIDC 令牌在 12 小时后过期；使用 vercel dev 进行自动刷新，或再次手动运行 vercel env pull。

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

import { generateText } from 'ai';

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

console.log(text);

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);

模型发现 (动态)

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`);
  }
});

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

检查信用额度使用情况

import { gateway } from 'ai';

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

使用网关进行流式传输

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);
}

使用网关进行工具调用

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', // 通过网关
  prompt: 'What is the weather in SF?',
  tools: { getWeather: weatherTool },
});

console.log(text);

将您自己的提供商凭据连接到网关，以访问私有资源：

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 网关设置中配置 BYOK 凭据；配置后无需更改代码。

提供商执行工具

一些提供商提供在服务器端执行的工具（例如，OpenAI 网络搜索）。通过导入提供商，通过网关使用：

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 直接访问提供商。

提供商路由与回退

核心路由选项 :

order: 按顺序尝试提供商（回退优先级）
only: 仅限特定提供商
models: 如果主模型失败，则回退到替代模型
user: 跟踪每个最终用户的使用情况
tags: 对请求进行分类以进行分析
zeroDataRetention: 仅使用零数据保留的提供商
byok: 请求范围内的 BYOK 凭据

示例：提供商和模型回退

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 使用 openai/gpt-4o
// 2. 尝试 anthropic 使用 openai/gpt-4o
// 3. 尝试 vertex 使用 openai/gpt-5-nano
// 4. 尝试 anthropic 使用 openai/gpt-5-nano
// 等等。

示例：使用情况跟踪

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 仪表板中按用户和功能查看分析

将请求仅路由到具有零数据保留策略的提供商，以处理敏感数据：

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 时，网关仅路由到不保留您数据的提供商。如果省略或为 false，则不强制执行。

智能体的调用选项

在运行时动态配置智能体：

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',
  },
});

与 React 的 UI 集成

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>();

使用 llama-3.3-70b-versatile 以获得平衡的性能和成本。
使用 llama-3.1-8b-instant 处理低延迟、轻量级任务。
启用 parallelToolCalls: true（默认）以实现更快的多工具执行。
如果您能容忍偶尔的故障，请使用 serviceTier: 'flex' 以获得 10 倍的速率限制。

始终添加信用卡；网关按令牌付费。
使用 only / order 来控制路由和成本。
使用 user 和 tags 进行支出跟踪和调试。
对敏感数据启用 zeroDataRetention。
定期检查 gateway.getCredits() 以监控使用情况。

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

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.',
});

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

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

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

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

2026 年 1 月 20 日

🇺🇸English

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.

What's New in AI SDK 6?

1. Agent Abstraction (New)

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

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)

Request user confirmation before executing sensitive tools.

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:

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;
}

3. Structured Output + Tool Calling (Stable)

Combine tool calling with structured output generation:

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)

Improve search relevance by reordering documents:

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

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.

Groq Provider (Open Weight Models)

Setup

pnpm add @ai-sdk/groq

Environment:

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.

Basic Llama Example

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)

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)

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 offers reasoning models like qwen/qwen3-32b and deepseek-r1-distill-llama-70b:

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)

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.

Setup

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.

Authentication

API Key Authentication

Set via environment variable or directly in code:

import { createGateway } from 'ai';

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

OIDC Authentication (Vercel Deployments)

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.

# Start dev with automatic token management
vercel dev

Basic Usage

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);

Gateway Instance

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)

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',
});

Check Credit Usage

import { gateway } from 'ai';

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

Streaming with Gateway

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

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)

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

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.

Provider-Executed Tools

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

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.

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

Example: Provider & Model Fallback

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.

Example: Usage Tracking

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

Zero Data Retention

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

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.

Key Concepts

Call Options for Agents

Dynamically configure agents at runtime:

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',
  },
});

UI Integration with React

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>();

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.

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.

Agents

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)).

Common Patterns

RAG Agent

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.',
});

Multi-Provider with Fallback

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

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

Weekly Installs

233

Repository

gocallum/nextjs…t-skills

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

codex183

opencode182

gemini-cli181

github-copilot171

cursor165

claude-code135

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

109,600 周安装

AI SDK 6 Beta 新特性详解：智能体抽象、工具执行审批与结构化输出

🇨🇳中文介绍

链接

安装

AI SDK 6 有哪些新特性？

1. 智能体抽象 (新功能)

相关 Skills

2. 工具执行审批 (新功能)

3. 结构化输出 + 工具调用 (稳定版)

4. 重新排序支持 (新功能)

从 AI SDK 5 迁移

Groq 提供商 (开源权重模型)

设置

可用的开源权重模型

基础 Llama 示例

使用 Llama (Groq) 进行结构化输出

使用 Llama (Groq) 进行工具调用

推理模型 (Groq)

使用 Llama (Groq 多模态) 进行图像输入

Vercel AI 网关

概述

设置

身份验证

API 密钥认证

OIDC 认证 (Vercel 部署)

基本用法

网关实例

模型发现 (动态)

检查信用额度使用情况

使用网关进行流式传输

使用网关进行工具调用

自带密钥 (BYOK)

提供商执行工具

提供商路由与回退

示例：提供商和模型回退

示例：使用情况跟踪

零数据保留

核心概念

智能体的调用选项

与 React 的 UI 集成

最佳实践

Groq

Vercel AI 网关

智能体

常见模式

RAG 智能体

多提供商回退

成本优化选择

时间线

🇺🇸English

Links

Installation

What's New in AI SDK 6?

1. Agent Abstraction (New)

2. Tool Execution Approval (New)

3. Structured Output + Tool Calling (Stable)

4. Reranking Support (New)

Migration from AI SDK 5

Groq Provider (Open Weight Models)

Setup

Open Weight Models Available

Basic Llama Example

Structured Output with Llama (Groq)

Tool Use with Llama (Groq)

Reasoning Models (Groq)

Image Input with Llama (Groq Multi-Modal)

Vercel AI Gateway

What It Is

Setup

Authentication

API Key Authentication

OIDC Authentication (Vercel Deployments)

Basic Usage

Gateway Instance

Model Discovery (Dynamic)

Check Credit Usage

Streaming with Gateway

Tool Use with Gateway

Bring Your Own Key (BYOK)

Provider-Executed Tools