@fondation-io/ai 7.0.0-beta.45

package/docs/03-agents/04-loop-control.mdx

@@ -0,0 +1,394 @@
+---
+title: Loop Control
+description: Control agent execution with built-in loop management using stopWhen and prepareStep
+---
+
+# Loop Control
+
+You can control both the execution flow and the settings at each step of the agent loop. The loop continues until:
+
+- A finish reasoning other than tool-calls is returned, or
+- A tool that is invoked does not have an execute function, or
+- A tool call needs approval, or
+- A stop condition is met
+
+The AI SDK provides built-in loop control through two parameters: `stopWhen` for defining stopping conditions and `prepareStep` for modifying settings (model, tools, messages, and more) between steps.
+
+## Stop Conditions
+
+The `stopWhen` parameter controls when to stop execution when there are tool results in the last step. By default, agents stop after 20 steps using `stepCountIs(20)`.
+
+When you provide `stopWhen`, the agent continues executing after tool calls until a stopping condition is met. When the condition is an array, execution stops when any of the conditions are met.
+
+### Use Built-in Conditions
+
+The AI SDK provides several built-in stopping conditions:
+
+```ts
+import { ToolLoopAgent, stepCountIs } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    // your tools
+  },
+  stopWhen: stepCountIs(20), // Default state: stop after 20 steps maximum
+});
+
+const result = await agent.generate({
+  prompt: 'Analyze this dataset and create a summary report',
+});
+```
+
+### Combine Multiple Conditions
+
+Combine multiple stopping conditions. The loop stops when it meets any condition:
+
+```ts
+import { ToolLoopAgent, stepCountIs, hasToolCall } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    // your tools
+  },
+  stopWhen: [
+    stepCountIs(20), // Maximum 20 steps
+    hasToolCall('someTool'), // Stop after calling 'someTool'
+  ],
+});
+
+const result = await agent.generate({
+  prompt: 'Research and analyze the topic',
+});
+```
+
+### Create Custom Conditions
+
+Build custom stopping conditions for specific requirements:
+
+```ts
+import { ToolLoopAgent, StopCondition, ToolSet } from 'ai';
+__PROVIDER_IMPORT__;
+
+const tools = {
+  // your tools
+} satisfies ToolSet;
+
+const hasAnswer: StopCondition<typeof tools> = ({ steps }) => {
+  // Stop when the model generates text containing "ANSWER:"
+  return steps.some(step => step.text?.includes('ANSWER:')) ?? false;
+};
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools,
+  stopWhen: hasAnswer,
+});
+
+const result = await agent.generate({
+  prompt: 'Find the answer and respond with "ANSWER: [your answer]"',
+});
+```
+
+Custom conditions receive step information across all steps:
+
+```ts
+const budgetExceeded: StopCondition<typeof tools> = ({ steps }) => {
+  const totalUsage = steps.reduce(
+    (acc, step) => ({
+      inputTokens: acc.inputTokens + (step.usage?.inputTokens ?? 0),
+      outputTokens: acc.outputTokens + (step.usage?.outputTokens ?? 0),
+    }),
+    { inputTokens: 0, outputTokens: 0 },
+  );
+
+  const costEstimate =
+    (totalUsage.inputTokens * 0.01 + totalUsage.outputTokens * 0.03) / 1000;
+  return costEstimate > 0.5; // Stop if cost exceeds $0.50
+};
+```
+
+## Prepare Step
+
+The `prepareStep` callback runs before each step in the loop and defaults to the initial settings if you don't return any changes. Use it to modify settings, manage context, or implement dynamic behavior based on execution history.
+
+### Dynamic Model Selection
+
+Switch models based on step requirements:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: 'openai/gpt-4o-mini', // Default model
+  tools: {
+    // your tools
+  },
+  prepareStep: async ({ stepNumber, messages }) => {
+    // Use a stronger model for complex reasoning after initial steps
+    if (stepNumber > 2 && messages.length > 10) {
+      return {
+        model: __MODEL__,
+      };
+    }
+    // Continue with default settings
+    return {};
+  },
+});
+
+const result = await agent.generate({
+  prompt: '...',
+});
+```
+
+### Context Management
+
+Manage growing conversation history in long-running loops:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    // your tools
+  },
+  prepareStep: async ({ messages }) => {
+    // Keep only recent messages to stay within context limits
+    if (messages.length > 20) {
+      return {
+        messages: [
+          messages[0], // Keep system instructions
+          ...messages.slice(-10), // Keep last 10 messages
+        ],
+      };
+    }
+    return {};
+  },
+});
+
+const result = await agent.generate({
+  prompt: '...',
+});
+```
+
+### Tool Selection
+
+Control which tools are available at each step:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    search: searchTool,
+    analyze: analyzeTool,
+    summarize: summarizeTool,
+  },
+  prepareStep: async ({ stepNumber, steps }) => {
+    // Search phase (steps 0-2)
+    if (stepNumber <= 2) {
+      return {
+        activeTools: ['search'],
+        toolChoice: 'required',
+      };
+    }
+
+    // Analysis phase (steps 3-5)
+    if (stepNumber <= 5) {
+      return {
+        activeTools: ['analyze'],
+      };
+    }
+
+    // Summary phase (step 6+)
+    return {
+      activeTools: ['summarize'],
+      toolChoice: 'required',
+    };
+  },
+});
+
+const result = await agent.generate({
+  prompt: '...',
+});
+```
+
+You can also force a specific tool to be used:
+
+```ts
+prepareStep: async ({ stepNumber }) => {
+  if (stepNumber === 0) {
+    // Force the search tool to be used first
+    return {
+      toolChoice: { type: 'tool', toolName: 'search' },
+    };
+  }
+
+  if (stepNumber === 5) {
+    // Force the summarize tool after analysis
+    return {
+      toolChoice: { type: 'tool', toolName: 'summarize' },
+    };
+  }
+
+  return {};
+};
+```
+
+### Message Modification
+
+Transform messages before sending them to the model:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    // your tools
+  },
+  prepareStep: async ({ messages, stepNumber }) => {
+    // Summarize tool results to reduce token usage
+    const processedMessages = messages.map(msg => {
+      if (msg.role === 'tool' && msg.content.length > 1000) {
+        return {
+          ...msg,
+          content: summarizeToolResult(msg.content),
+        };
+      }
+      return msg;
+    });
+
+    return { messages: processedMessages };
+  },
+});
+
+const result = await agent.generate({
+  prompt: '...',
+});
+```
+
+## Access Step Information
+
+Both `stopWhen` and `prepareStep` receive detailed information about the current execution:
+
+```ts
+prepareStep: async ({
+  model, // Current model configuration
+  stepNumber, // Current step number (0-indexed)
+  steps, // All previous steps with their results
+  messages, // Messages to be sent to the model
+}) => {
+  // Access previous tool calls and results
+  const previousToolCalls = steps.flatMap(step => step.toolCalls);
+  const previousResults = steps.flatMap(step => step.toolResults);
+
+  // Make decisions based on execution history
+  if (previousToolCalls.some(call => call.toolName === 'dataAnalysis')) {
+    return {
+      toolChoice: { type: 'tool', toolName: 'reportGenerator' },
+    };
+  }
+
+  return {};
+},
+```
+
+## Forced Tool Calling
+
+You can force the agent to always use tools by combining `toolChoice: 'required'` with a `done` tool that has no `execute` function. This pattern ensures the agent uses tools for every step and stops only when it explicitly signals completion.
+
+```ts
+import { ToolLoopAgent, tool } from 'ai';
+import { z } from 'zod';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    search: searchTool,
+    analyze: analyzeTool,
+    done: tool({
+      description: 'Signal that you have finished your work',
+      inputSchema: z.object({
+        answer: z.string().describe('The final answer'),
+      }),
+      // No execute function - stops the agent when called
+    }),
+  },
+  toolChoice: 'required', // Force tool calls at every step
+});
+
+const result = await agent.generate({
+  prompt: 'Research and analyze this topic, then provide your answer.',
+});
+
+// extract answer from done tool call
+const toolCall = result.staticToolCalls[0]; // tool call from final step
+if (toolCall?.toolName === 'done') {
+  console.log(toolCall.input.answer);
+}
+```
+
+Key aspects of this pattern:
+
+- **`toolChoice: 'required'`**: Forces the model to call a tool at every step instead of generating text directly. This ensures the agent follows a structured workflow.
+- **`done` tool without `execute`**: A tool that has no `execute` function acts as a termination signal. When the agent calls this tool, the loop stops because there's no function to execute.
+- **Accessing results**: The final answer is available in `result.staticToolCalls`, which contains tool calls that weren't executed.
+
+This pattern is useful when you want the agent to always use specific tools for operations (like code execution or data retrieval) rather than attempting to answer directly.
+
+## Manual Loop Control
+
+For scenarios requiring complete control over the agent loop, you can use AI SDK Core functions (`generateText` and `streamText`) to implement your own loop management instead of using `stopWhen` and `prepareStep`. This approach provides maximum flexibility for complex workflows.
+
+### Implementing a Manual Loop
+
+Build your own agent loop when you need full control over execution:
+
+```ts
+import { generateText, ModelMessage } from 'ai';
+__PROVIDER_IMPORT__;
+
+const messages: ModelMessage[] = [{ role: 'user', content: '...' }];
+
+let step = 0;
+const maxSteps = 10;
+
+while (step < maxSteps) {
+  const result = await generateText({
+    model: __MODEL__,
+    messages,
+    tools: {
+      // your tools here
+    },
+  });
+
+  messages.push(...result.response.messages);
+
+  if (result.text) {
+    break; // Stop when model generates text
+  }
+
+  step++;
+}
+```
+
+This manual approach gives you complete control over:
+
+- Message history management
+- Step-by-step decision making
+- Custom stopping conditions
+- Dynamic tool and model selection
+- Error handling and recovery
+
+[Learn more about manual agent loops in the cookbook](/cookbook/node/manual-agent-loop).

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 { OpenAILanguageModelResponsesOptions } 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 OpenAILanguageModelResponsesOptions,
+    },
+  }),
+});
+
+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