ai 6.0.31 → 6.0.32

package/docs/03-agents/05-configuring-call-options.mdx

@@ -0,0 +1,286 @@
+---
+title: Configuring Call Options
+description: Pass type-safe runtime inputs to dynamically configure agent behavior.
+---
+
+# Configuring Call Options
+
+Call options allow you to pass type-safe structured inputs to your agent. Use them to dynamically modify any agent setting based on the specific request.
+
+## Why Use Call Options?
+
+When you need agent behavior to change based on runtime context:
+
+- **Add dynamic context** - Inject retrieved documents, user preferences, or session data into prompts
+- **Select models dynamically** - Choose faster or more capable models based on request complexity
+- **Configure tools per request** - Pass user location to search tools or adjust tool behavior
+- **Customize provider options** - Set reasoning effort, temperature, or other provider-specific settings
+
+Without call options, you'd need to create multiple agents or handle configuration logic outside the agent.
+
+## How It Works
+
+Define call options in three steps:
+
+1. **Define the schema** - Specify what inputs you accept using `callOptionsSchema`
+2. **Configure with `prepareCall`** - Use those inputs to modify agent settings
+3. **Pass options at runtime** - Provide the options when calling `generate()` or `stream()`
+
+## Basic Example
+
+Add user context to your agent's prompt at runtime:
+
+```ts
+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.`,
+  }),
+});
+
+// Call the agent with specific user context
+const result = await supportAgent.generate({
+  prompt: 'How do I upgrade my account?',
+  options: {
+    userId: 'user_123',
+    accountType: 'free',
+  },
+});
+```
+
+The `options` parameter is now required and type-checked. If you don't provide it or pass incorrect types, TypeScript will error.
+
+## Modifying Agent Settings
+
+Use `prepareCall` to modify any agent setting. Return only the settings you want to change.
+
+### Dynamic Model Selection
+
+Choose models based on request characteristics:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__, // Default model
+  callOptionsSchema: z.object({
+    complexity: z.enum(['simple', 'complex']),
+  }),
+  prepareCall: ({ options, ...settings }) => ({
+    ...settings,
+    model:
+      options.complexity === 'simple' ? 'openai/gpt-4o-mini' : 'openai/o1-mini',
+  }),
+});
+
+// Use faster model for simple queries
+await agent.generate({
+  prompt: 'What is 2+2?',
+  options: { complexity: 'simple' },
+});
+
+// Use more capable model for complex reasoning
+await agent.generate({
+  prompt: 'Explain quantum entanglement',
+  options: { complexity: 'complex' },
+});
+```
+
+### Dynamic Tool Configuration
+
+Configure tools based on runtime context:
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const newsAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  callOptionsSchema: z.object({
+    userCity: z.string().optional(),
+    userRegion: z.string().optional(),
+  }),
+  tools: {
+    web_search: openai.tools.webSearch(),
+  },
+  prepareCall: ({ options, ...settings }) => ({
+    ...settings,
+    tools: {
+      web_search: openai.tools.webSearch({
+        searchContextSize: 'low',
+        userLocation: {
+          type: 'approximate',
+          city: options.userCity,
+          region: options.userRegion,
+          country: 'US',
+        },
+      }),
+    },
+  }),
+});
+
+await newsAgent.generate({
+  prompt: 'What are the top local news stories?',
+  options: {
+    userCity: 'San Francisco',
+    userRegion: 'California',
+  },
+});
+```
+
+### Provider-Specific Options
+
+Configure provider settings dynamically:
+
+```ts
+import { openai, OpenAIProviderOptions } from '@ai-sdk/openai';
+import { ToolLoopAgent } from 'ai';
+import { z } from 'zod';
+
+const agent = new ToolLoopAgent({
+  model: 'openai/o3',
+  callOptionsSchema: z.object({
+    taskDifficulty: z.enum(['low', 'medium', 'high']),
+  }),
+  prepareCall: ({ options, ...settings }) => ({
+    ...settings,
+    providerOptions: {
+      openai: {
+        reasoningEffort: options.taskDifficulty,
+      } satisfies OpenAIProviderOptions,
+    },
+  }),
+});
+
+await agent.generate({
+  prompt: 'Analyze this complex scenario...',
+  options: { taskDifficulty: 'high' },
+});
+```
+
+## Advanced Patterns
+
+### Retrieval Augmented Generation (RAG)
+
+Fetch relevant context and inject it into your prompt:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const ragAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  callOptionsSchema: z.object({
+    query: z.string(),
+  }),
+  prepareCall: async ({ options, ...settings }) => {
+    // Fetch relevant documents (this can be async)
+    const documents = await vectorSearch(options.query);
+
+    return {
+      ...settings,
+      instructions: `Answer questions using the following context:
+
+${documents.map(doc => doc.content).join('\n\n')}`,
+    };
+  },
+});
+
+await ragAgent.generate({
+  prompt: 'What is our refund policy?',
+  options: { query: 'refund policy' },
+});
+```
+
+The `prepareCall` function can be async, enabling you to fetch data before configuring the agent.
+
+### Combining Multiple Modifications
+
+Modify multiple settings together:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  callOptionsSchema: z.object({
+    userRole: z.enum(['admin', 'user']),
+    urgency: z.enum(['low', 'high']),
+  }),
+  tools: {
+    readDatabase: readDatabaseTool,
+    writeDatabase: writeDatabaseTool,
+  },
+  prepareCall: ({ options, ...settings }) => ({
+    ...settings,
+    // Upgrade model for urgent requests
+    model: options.urgency === 'high' ? __MODEL__ : settings.model,
+    // Limit tools based on user role
+    activeTools:
+      options.userRole === 'admin'
+        ? ['readDatabase', 'writeDatabase']
+        : ['readDatabase'],
+    // Adjust instructions
+    instructions: `You are a ${options.userRole} assistant.
+${options.userRole === 'admin' ? 'You have full database access.' : 'You have read-only access.'}`,
+  }),
+});
+
+await agent.generate({
+  prompt: 'Update the user record',
+  options: {
+    userRole: 'admin',
+    urgency: 'high',
+  },
+});
+```
+
+## Using with createAgentUIStreamResponse
+
+Pass call options through API routes to your agent:
+
+```ts filename="app/api/chat/route.ts"
+import { createAgentUIStreamResponse } from 'ai';
+import { myAgent } from '@/ai/agents/my-agent';
+
+export async function POST(request: Request) {
+  const { messages, userId, accountType } = await request.json();
+
+  return createAgentUIStreamResponse({
+    agent: myAgent,
+    messages,
+    options: {
+      userId,
+      accountType,
+    },
+  });
+}
+```
+
+## Next Steps
+
+- Learn about [loop control](/docs/agents/loop-control) for execution management
+- Explore [workflow patterns](/docs/agents/workflows) for complex multi-step processes

package/docs/03-agents/index.mdx

@@ -0,0 +1,40 @@
+---
+title: Agents
+description: An overview of building agents with the AI SDK.
+---
+
+# Agents
+
+The following section show you how to build agents with the AI SDK - systems where large language models (LLMs) use tools in a loop to accomplish tasks.
+
+<IndexCards
+  cards={[
+    {
+      title: 'Overview',
+      description: 'Learn what agents are and why to use the Agent class.',
+      href: '/docs/agents/overview',
+    },
+    {
+      title: 'Building Agents',
+      description: 'Complete guide to creating agents with the Agent class.',
+      href: '/docs/agents/building-agents',
+    },
+    {
+      title: 'Workflow Patterns',
+      description:
+        'Structured patterns using core functions for complex workflows.',
+      href: '/docs/agents/workflows',
+    },
+    {
+      title: 'Loop Control',
+      description: 'Advanced execution control with stopWhen and prepareStep.',
+      href: '/docs/agents/loop-control',
+    },
+    {
+      title: 'Configuring Call Options',
+      description:
+        'Pass type-safe runtime inputs to dynamically configure agent behavior.',
+      href: '/docs/agents/configuring-call-options',
+    },
+  ]}
+/>

package/docs/03-ai-sdk-core/01-overview.mdx

@@ -0,0 +1,33 @@
+---
+title: Overview
+description: An overview of AI SDK Core.
+---
+
+# AI SDK Core
+
+Large Language Models (LLMs) are advanced programs that can understand, create, and engage with human language on a large scale.
+They are trained on vast amounts of written material to recognize patterns in language and predict what might come next in a given piece of text.
+
+AI SDK Core **simplifies working with LLMs by offering a standardized way of integrating them into your app** - so you can focus on building great AI applications for your users, not waste time on technical details.
+
+For example, here’s how you can generate text with various models using the AI SDK:
+
+<PreviewSwitchProviders />
+
+## AI SDK Core Functions
+
+AI SDK Core has various functions designed for [text generation](./generating-text), [structured data generation](./generating-structured-data), and [tool usage](./tools-and-tool-calling).
+These functions take a standardized approach to setting up [prompts](./prompts) and [settings](./settings), making it easier to work with different models.
+
+- [`generateText`](/docs/ai-sdk-core/generating-text): Generates text and [tool calls](./tools-and-tool-calling).
+  This function is ideal for non-interactive use cases such as automation tasks where you need to write text (e.g. drafting email or summarizing web pages) and for agents that use tools.
+- [`streamText`](/docs/ai-sdk-core/generating-text): Stream text and tool calls.
+  You can use the `streamText` function for interactive use cases such as [chat bots](/docs/ai-sdk-ui/chatbot) and [content streaming](/docs/ai-sdk-ui/completion).
+- [`generateObject`](/docs/ai-sdk-core/generating-structured-data): Generates a typed, structured object that matches a [Zod](https://zod.dev/) schema.
+  You can use this function to force the language model to return structured data, e.g. for information extraction, synthetic data generation, or classification tasks.
+- [`streamObject`](/docs/ai-sdk-core/generating-structured-data): Stream a structured object that matches a Zod schema.
+  You can use this function to [stream generated UIs](/docs/ai-sdk-ui/object-generation).
+
+## API Reference
+
+Please check out the [AI SDK Core API Reference](/docs/reference/ai-sdk-core) for more details on each function.