ai 6.0.31 → 6.0.32

package/docs/03-agents/03-workflows.mdx

@@ -0,0 +1,370 @@
+---
+title: Workflow Patterns
+description: Learn workflow patterns for building reliable agents with the AI SDK.
+---
+
+# Workflow Patterns
+
+Combine the building blocks from the [overview](/docs/agents/overview) with these patterns to add structure and reliability to your agents:
+
+- [Sequential Processing](#sequential-processing-chains) - Steps executed in order
+- [Parallel Processing](#parallel-processing) - Independent tasks run simultaneously
+- [Evaluation/Feedback Loops](#evaluator-optimizer) - Results checked and improved iteratively
+- [Orchestration](#orchestrator-worker) - Coordinating multiple components
+- [Routing](#routing) - Directing work based on context
+
+## Choose Your Approach
+
+Consider these key factors:
+
+- **Flexibility vs Control** - How much freedom does the LLM need vs how tightly you must constrain its actions?
+- **Error Tolerance** - What are the consequences of mistakes in your use case?
+- **Cost Considerations** - More complex systems typically mean more LLM calls and higher costs
+- **Maintenance** - Simpler architectures are easier to debug and modify
+
+**Start with the simplest approach that meets your needs**. Add complexity only when required by:
+
+1. Breaking down tasks into clear steps
+2. Adding tools for specific capabilities
+3. Implementing feedback loops for quality control
+4. Introducing multiple agents for complex workflows
+
+Let's look at examples of these patterns in action.
+
+## Patterns with Examples
+
+These patterns, adapted from [Anthropic's guide on building effective agents](https://www.anthropic.com/research/building-effective-agents), serve as building blocks you can combine to create comprehensive workflows. Each pattern addresses specific aspects of task execution. Combine them thoughtfully to build reliable solutions for complex problems.
+
+## Sequential Processing (Chains)
+
+The simplest workflow pattern executes steps in a predefined order. Each step's output becomes input for the next step, creating a clear chain of operations. Use this pattern for tasks with well-defined sequences, like content generation pipelines or data transformation processes.
+
+```ts
+import { generateText, generateObject } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+async function generateMarketingCopy(input: string) {
+  const model = __MODEL__;
+
+  // First step: Generate marketing copy
+  const { text: copy } = await generateText({
+    model,
+    prompt: `Write persuasive marketing copy for: ${input}. Focus on benefits and emotional appeal.`,
+  });
+
+  // Perform quality check on copy
+  const { object: qualityMetrics } = await generateObject({
+    model,
+    schema: z.object({
+      hasCallToAction: z.boolean(),
+      emotionalAppeal: z.number().min(1).max(10),
+      clarity: z.number().min(1).max(10),
+    }),
+    prompt: `Evaluate this marketing copy for:
+    1. Presence of call to action (true/false)
+    2. Emotional appeal (1-10)
+    3. Clarity (1-10)
+
+    Copy to evaluate: ${copy}`,
+  });
+
+  // If quality check fails, regenerate with more specific instructions
+  if (
+    !qualityMetrics.hasCallToAction ||
+    qualityMetrics.emotionalAppeal < 7 ||
+    qualityMetrics.clarity < 7
+  ) {
+    const { text: improvedCopy } = await generateText({
+      model,
+      prompt: `Rewrite this marketing copy with:
+      ${!qualityMetrics.hasCallToAction ? '- A clear call to action' : ''}
+      ${qualityMetrics.emotionalAppeal < 7 ? '- Stronger emotional appeal' : ''}
+      ${qualityMetrics.clarity < 7 ? '- Improved clarity and directness' : ''}
+
+      Original copy: ${copy}`,
+    });
+    return { copy: improvedCopy, qualityMetrics };
+  }
+
+  return { copy, qualityMetrics };
+}
+```
+
+## Routing
+
+This pattern lets the model decide which path to take through a workflow based on context and intermediate results. The model acts as an intelligent router, directing the flow of execution between different branches of your workflow. Use this when handling varied inputs that require different processing approaches. In the example below, the first LLM call's results determine the second call's model size and system prompt.
+
+```ts
+import { generateObject, generateText } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+async function handleCustomerQuery(query: string) {
+  const model = __MODEL__;
+
+  // First step: Classify the query type
+  const { object: classification } = await generateObject({
+    model,
+    schema: z.object({
+      reasoning: z.string(),
+      type: z.enum(['general', 'refund', 'technical']),
+      complexity: z.enum(['simple', 'complex']),
+    }),
+    prompt: `Classify this customer query:
+    ${query}
+
+    Determine:
+    1. Query type (general, refund, or technical)
+    2. Complexity (simple or complex)
+    3. Brief reasoning for classification`,
+  });
+
+  // Route based on classification
+  // Set model and system prompt based on query type and complexity
+  const { text: response } = await generateText({
+    model:
+      classification.complexity === 'simple'
+        ? 'openai/gpt-4o-mini'
+        : 'openai/o4-mini',
+    system: {
+      general:
+        'You are an expert customer service agent handling general inquiries.',
+      refund:
+        'You are a customer service agent specializing in refund requests. Follow company policy and collect necessary information.',
+      technical:
+        'You are a technical support specialist with deep product knowledge. Focus on clear step-by-step troubleshooting.',
+    }[classification.type],
+    prompt: query,
+  });
+
+  return { response, classification };
+}
+```
+
+## Parallel Processing
+
+Break down tasks into independent subtasks that execute simultaneously. This pattern uses parallel execution to improve efficiency while maintaining the benefits of structured workflows. For example, analyze multiple documents or process different aspects of a single input concurrently (like code review).
+
+```ts
+import { generateText, generateObject } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+// Example: Parallel code review with multiple specialized reviewers
+async function parallelCodeReview(code: string) {
+  const model = __MODEL__;
+
+  // Run parallel reviews
+  const [securityReview, performanceReview, maintainabilityReview] =
+    await Promise.all([
+      generateObject({
+        model,
+        system:
+          'You are an expert in code security. Focus on identifying security vulnerabilities, injection risks, and authentication issues.',
+        schema: z.object({
+          vulnerabilities: z.array(z.string()),
+          riskLevel: z.enum(['low', 'medium', 'high']),
+          suggestions: z.array(z.string()),
+        }),
+        prompt: `Review this code:
+      ${code}`,
+      }),
+
+      generateObject({
+        model,
+        system:
+          'You are an expert in code performance. Focus on identifying performance bottlenecks, memory leaks, and optimization opportunities.',
+        schema: z.object({
+          issues: z.array(z.string()),
+          impact: z.enum(['low', 'medium', 'high']),
+          optimizations: z.array(z.string()),
+        }),
+        prompt: `Review this code:
+      ${code}`,
+      }),
+
+      generateObject({
+        model,
+        system:
+          'You are an expert in code quality. Focus on code structure, readability, and adherence to best practices.',
+        schema: z.object({
+          concerns: z.array(z.string()),
+          qualityScore: z.number().min(1).max(10),
+          recommendations: z.array(z.string()),
+        }),
+        prompt: `Review this code:
+      ${code}`,
+      }),
+    ]);
+
+  const reviews = [
+    { ...securityReview.object, type: 'security' },
+    { ...performanceReview.object, type: 'performance' },
+    { ...maintainabilityReview.object, type: 'maintainability' },
+  ];
+
+  // Aggregate results using another model instance
+  const { text: summary } = await generateText({
+    model,
+    system: 'You are a technical lead summarizing multiple code reviews.',
+    prompt: `Synthesize these code review results into a concise summary with key actions:
+    ${JSON.stringify(reviews, null, 2)}`,
+  });
+
+  return { reviews, summary };
+}
+```
+
+## Orchestrator-Worker
+
+A primary model (orchestrator) coordinates the execution of specialized workers. Each worker optimizes for a specific subtask, while the orchestrator maintains overall context and ensures coherent results. This pattern excels at complex tasks requiring different types of expertise or processing.
+
+```ts
+import { generateObject } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+async function implementFeature(featureRequest: string) {
+  // Orchestrator: Plan the implementation
+  const { object: implementationPlan } = await generateObject({
+    model: __MODEL__,
+    schema: z.object({
+      files: z.array(
+        z.object({
+          purpose: z.string(),
+          filePath: z.string(),
+          changeType: z.enum(['create', 'modify', 'delete']),
+        }),
+      ),
+      estimatedComplexity: z.enum(['low', 'medium', 'high']),
+    }),
+    system:
+      'You are a senior software architect planning feature implementations.',
+    prompt: `Analyze this feature request and create an implementation plan:
+    ${featureRequest}`,
+  });
+
+  // Workers: Execute the planned changes
+  const fileChanges = await Promise.all(
+    implementationPlan.files.map(async file => {
+      // Each worker is specialized for the type of change
+      const workerSystemPrompt = {
+        create:
+          'You are an expert at implementing new files following best practices and project patterns.',
+        modify:
+          'You are an expert at modifying existing code while maintaining consistency and avoiding regressions.',
+        delete:
+          'You are an expert at safely removing code while ensuring no breaking changes.',
+      }[file.changeType];
+
+      const { object: change } = await generateObject({
+        model: __MODEL__,
+        schema: z.object({
+          explanation: z.string(),
+          code: z.string(),
+        }),
+        system: workerSystemPrompt,
+        prompt: `Implement the changes for ${file.filePath} to support:
+        ${file.purpose}
+
+        Consider the overall feature context:
+        ${featureRequest}`,
+      });
+
+      return {
+        file,
+        implementation: change,
+      };
+    }),
+  );
+
+  return {
+    plan: implementationPlan,
+    changes: fileChanges,
+  };
+}
+```
+
+## Evaluator-Optimizer
+
+Add quality control to workflows with dedicated evaluation steps that assess intermediate results. Based on the evaluation, the workflow proceeds, retries with adjusted parameters, or takes corrective action. This creates robust workflows capable of self-improvement and error recovery.
+
+```ts
+import { generateText, generateObject } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+async function translateWithFeedback(text: string, targetLanguage: string) {
+  let currentTranslation = '';
+  let iterations = 0;
+  const MAX_ITERATIONS = 3;
+
+  // Initial translation
+  const { text: translation } = await generateText({
+    model: __MODEL__,
+    system: 'You are an expert literary translator.',
+    prompt: `Translate this text to ${targetLanguage}, preserving tone and cultural nuances:
+    ${text}`,
+  });
+
+  currentTranslation = translation;
+
+  // Evaluation-optimization loop
+  while (iterations < MAX_ITERATIONS) {
+    // Evaluate current translation
+    const { object: evaluation } = await generateObject({
+      model: __MODEL__,
+      schema: z.object({
+        qualityScore: z.number().min(1).max(10),
+        preservesTone: z.boolean(),
+        preservesNuance: z.boolean(),
+        culturallyAccurate: z.boolean(),
+        specificIssues: z.array(z.string()),
+        improvementSuggestions: z.array(z.string()),
+      }),
+      system: 'You are an expert in evaluating literary translations.',
+      prompt: `Evaluate this translation:
+
+      Original: ${text}
+      Translation: ${currentTranslation}
+
+      Consider:
+      1. Overall quality
+      2. Preservation of tone
+      3. Preservation of nuance
+      4. Cultural accuracy`,
+    });
+
+    // Check if quality meets threshold
+    if (
+      evaluation.qualityScore >= 8 &&
+      evaluation.preservesTone &&
+      evaluation.preservesNuance &&
+      evaluation.culturallyAccurate
+    ) {
+      break;
+    }
+
+    // Generate improved translation based on feedback
+    const { text: improvedTranslation } = await generateText({
+      model: __MODEL__,
+      system: 'You are an expert literary translator.',
+      prompt: `Improve this translation based on the following feedback:
+      ${evaluation.specificIssues.join('\n')}
+      ${evaluation.improvementSuggestions.join('\n')}
+
+      Original: ${text}
+      Current Translation: ${currentTranslation}`,
+    });
+
+    currentTranslation = improvedTranslation;
+    iterations++;
+  }
+
+  return {
+    finalTranslation: currentTranslation,
+    iterationsRequired: iterations,
+  };
+}
+```

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

@@ -0,0 +1,350 @@
+---
+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 {};
+},
+```
+
+## 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).