@fondation-io/ai 7.0.0-beta.45

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

@@ -0,0 +1,386 @@
+---
+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, Output } 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 { output: qualityMetrics } = await generateText({
+    model,
+    output: Output.object({
+      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 { generateText, Output } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+async function handleCustomerQuery(query: string) {
+  const model = __MODEL__;
+
+  // First step: Classify the query type
+  const { output: classification } = await generateText({
+    model,
+    output: Output.object({
+      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, Output } 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([
+      generateText({
+        model,
+        system:
+          'You are an expert in code security. Focus on identifying security vulnerabilities, injection risks, and authentication issues.',
+        output: Output.object({
+          schema: z.object({
+            vulnerabilities: z.array(z.string()),
+            riskLevel: z.enum(['low', 'medium', 'high']),
+            suggestions: z.array(z.string()),
+          }),
+        }),
+        prompt: `Review this code:
+      ${code}`,
+      }),
+
+      generateText({
+        model,
+        system:
+          'You are an expert in code performance. Focus on identifying performance bottlenecks, memory leaks, and optimization opportunities.',
+        output: Output.object({
+          schema: z.object({
+            issues: z.array(z.string()),
+            impact: z.enum(['low', 'medium', 'high']),
+            optimizations: z.array(z.string()),
+          }),
+        }),
+        prompt: `Review this code:
+      ${code}`,
+      }),
+
+      generateText({
+        model,
+        system:
+          'You are an expert in code quality. Focus on code structure, readability, and adherence to best practices.',
+        output: Output.object({
+          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.output, type: 'security' },
+    { ...performanceReview.output, type: 'performance' },
+    { ...maintainabilityReview.output, 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 { generateText, Output } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+async function implementFeature(featureRequest: string) {
+  // Orchestrator: Plan the implementation
+  const { output: implementationPlan } = await generateText({
+    model: __MODEL__,
+    output: Output.object({
+      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 { output: change } = await generateText({
+        model: __MODEL__,
+        output: Output.object({
+          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, Output } 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 { output: evaluation } = await generateText({
+      model: __MODEL__,
+      output: Output.object({
+        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,
+  };
+}
+```