# Announcing AI SDK 6 Beta
AI SDK 6 is in beta — while more stable than alpha, AI SDK 6 is still in
active development and APIs may still change. Pin to specific versions as
breaking changes may occur in patch releases.
## Why AI SDK 6?
AI SDK 6 is a **major version** due to the introduction of the **v3 Language Model Specification** that powers new capabilities like agents and tool approval. However, unlike AI SDK 5, **this release is not expected to have major breaking changes** for most users.
The version bump reflects improvements to the specification, not a complete redesign of the SDK. If you're using AI SDK 5, migrating to v6 should be straightforward with minimal code changes.
## Beta Version Guidance
The AI SDK 6 Beta is intended for:
- **Trying out new features** and giving us feedback on the developer experience
- **Experimenting with agents** and tool approval workflows
Your feedback during this beta phase directly shapes the final stable release. Share your experiences through [GitHub issues](https://github.com/vercel/ai/issues/new/choose).
## Installation
To install the AI SDK 6 Beta, run the following command:
```bash
npm install ai@beta @ai-sdk/openai@beta @ai-sdk/react@beta
```
APIs may still change during beta. Pin to specific versions as breaking
changes may occur in patch releases.
## What's New in AI SDK 6?
AI SDK 6 introduces several features (with more to come soon!):
### Agent Abstraction
A new unified interface for building agents with full control over execution flow, tool loops, and state management.
### Tool Execution Approval
Request user confirmation before executing tools, enabling native human-in-the-loop patterns.
### Structured Output (Stable)
Generate structured data alongside tool calling with `generateText` and `streamText` - now stable and production-ready.
### Reranking Support
Improve search relevance by reordering documents based on their relationship to a query using specialized reranking models.
### Image Editing Support
Native support for image editing (coming soon).
## Agent Abstraction
AI SDK 6 introduces a powerful new `Agent` interface that provides a standardized way to build agents.
### Default Implementation: ToolLoopAgent
The `ToolLoopAgent` class provides a default implementation out of the box:
```typescript
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
import { weatherTool } from '@/tool/weather';
export const weatherAgent = new ToolLoopAgent({
model: __MODEL__,
instructions: 'You are a helpful weather assistant.',
tools: {
weather: weatherTool,
},
});
// Use the agent
const result = await weatherAgent.generate({
prompt: 'What is the weather in San Francisco?',
});
```
The agent automatically handles the tool execution loop:
1. Calls the LLM with your prompt
2. Executes any requested tool calls
3. Adds results back to the conversation
4. Repeats until complete (default `stopWhen: stepCountIs(20)`)
### Configuring Call Options
Call options let you pass type-safe runtime inputs to dynamically configure your agents. Use them to inject retrieved documents for RAG, select models based on request complexity, customize tool behavior per request, or adjust any agent setting based on context.
Without call options, you'd need to create multiple agents or handle configuration logic outside the agent. With call options, you define a schema once and modify agent behavior at runtime:
```typescript
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
import { z } from 'zod';
const supportAgent = new ToolLoopAgent({
model: __MODEL__,
callOptionsSchema: z.object({
userId: z.string(),
accountType: z.enum(['free', 'pro', 'enterprise']),
}),
instructions: 'You are a helpful customer support agent.',
prepareCall: ({ options, ...settings }) => ({
...settings,
instructions:
settings.instructions +
`\nUser context:
- Account type: ${options.accountType}
- User ID: ${options.userId}
Adjust your response based on the user's account level.`,
}),
});
// Pass options when calling the agent
const result = await supportAgent.generate({
prompt: 'How do I upgrade my account?',
options: {
userId: 'user_123',
accountType: 'free',
},
});
```
The `options` parameter is type-safe and will error if you don't provide it or pass incorrect types.
Call options enable dynamic agent configuration for several scenarios:
- **RAG**: Fetch relevant documents and inject them into prompts at runtime
- **Dynamic model selection**: Choose faster or more capable models based on request complexity
- **Tool configuration**: Adjust tools per request
- **Provider options**: Set reasoning effort, temperature, or other provider-specific settings dynamically
Learn more in the [Configuring Call Options](/docs/agents/configuring-call-options) documentation.
### UI Integration
Agents integrate seamlessly with React and other UI frameworks:
```typescript
// Server-side API route
import { createAgentUIStreamResponse } from 'ai';
export async function POST(request: Request) {
const { messages } = await request.json();
return createAgentUIStreamResponse({
agent: weatherAgent,
messages,
});
}
```
```typescript
// Client-side with type safety
import { useChat } from '@ai-sdk/react';
import { InferAgentUIMessage } from 'ai';
import { weatherAgent } from '@/agent/weather-agent';
type WeatherAgentUIMessage = InferAgentUIMessage;
const { messages, sendMessage } = useChat();
```
### Custom Agent Implementations
In AI SDK 6, `Agent` is an interface rather than a concrete class. While `ToolLoopAgent` provides a solid default implementation for most use cases, you can implement the `Agent` interface to build custom agent architectures:
```typescript
import { Agent } from 'ai';
// Build your own multi-agent orchestrator that delegates to specialists
class Orchestrator implements Agent {
constructor(private subAgents: Record) {
/* Implementation */
}
}
const orchestrator = new Orchestrator({
subAgents: {
// your subagents
},
});
```
This approach enables you to experiment with orchestrators, memory layers, custom stop conditions, and agent patterns tailored to your specific use case.
## Tool Execution Approval
AI SDK 6 introduces a tool approval system that gives you control over when tools are executed.
Enable approval for a tool by setting `needsApproval`:
```typescript
import { tool } from 'ai';
import { z } from 'zod';
export const weatherTool = tool({
description: 'Get the weather in a location',
inputSchema: z.object({
city: z.string(),
}),
needsApproval: true, // Require user approval
execute: async ({ city }) => {
const weather = await fetchWeather(city);
return weather;
},
});
```
### Dynamic Approval
Make approval decisions based on tool input:
```typescript
export const paymentTool = tool({
description: 'Process a payment',
inputSchema: z.object({
amount: z.number(),
recipient: z.string(),
}),
// Only require approval for large transactions
needsApproval: async ({ amount }) => amount > 1000,
execute: async ({ amount, recipient }) => {
return await processPayment(amount, recipient);
},
});
```
### Client-Side Approval UI
Handle approval requests in your UI:
```tsx
export function WeatherToolView({ invocation, addToolApprovalResponse }) {
if (invocation.state === 'approval-requested') {
return (
Can I retrieve the weather for {invocation.input.city}?
);
}
if (invocation.state === 'output-available') {
return (