Agent Workflow Patterns

Purpose: Provide production-ready agent architectures, workflow patterns, and loop control strategies for building autonomous AI systems with Vercel AI SDK.

Activation Triggers:

• Building autonomous AI agents
• Implementing multi-step reasoning
• Creating agent workflows
• Tool orchestration and coordination
• Loop control and iteration management
• Multi-agent system architectures
• ReAct (Reasoning + Acting) patterns

Key Resources:

• templates/react-agent.ts - ReAct agent pattern
• templates/multi-agent-system.ts - Multiple specialized agents
• templates/workflow-orchestrator.ts - Workflow coordination
• templates/loop-control.ts - Iteration and safeguards
• templates/tool-coordinator.ts - Tool orchestration
• scripts/validate-agent.sh - Validate agent configuration
• examples/ - Production agent implementations (RAG agent, SQL agent, etc.)

Core Agent Patterns

1. ReAct Agent (Reasoning + Acting)

When to use: Complex problem-solving requiring iterative thought and action

Template: templates/react-agent.ts

Pattern:

async function reactAgent(task: string, maxIterations: number = 5) {
  const tools = { /* tool definitions */ }
  let iteration = 0

  while (iteration < maxIterations) {
    // Reasoning step
    const thought = await generateText({
      model: openai('gpt-4o')
      messages: [
        { role: 'system', content: 'Think step-by-step...' }
        { role: 'user', content: task }
      ]
    })

    // Acting step (tool calls)
    const action = await generateText({
      model: openai('gpt-4o')
      tools
      toolChoice: 'auto'
      messages: [/* ... */]
    })

    // Check if task complete
    if (isComplete(action)) break
    iteration++
  }

  return result
}

Best for: Research, analysis, complex planning

2. Multi-Agent System

When to use: Complex domains requiring specialized expertise

Template: templates/multi-agent-system.ts

Pattern:

• Coordinator agent routes tasks
• Specialist agents handle specific domains
• Result aggregation and synthesis

Best for: Multi-domain problems, parallel task execution

3. Workflow Orchestration

When to use: Pre-defined sequences of steps

Template: templates/workflow-orchestrator.ts

Pattern:

• Define workflow steps
• Execute sequentially with error handling
• State management between steps
• Conditional branching

Best for: Structured processes, pipelines

Loop Control Strategies

1. Iteration Limits

const config = {
  maxIterations: 10
  onMaxIterations: 'return-last' | 'throw-error'
}

Prevents: Infinite loops

2. Cost Limits

const config = {
  maxTokens: 10000
  onMaxTokens: 'graceful-stop'
}

Prevents: Runaway costs

3. Time Limits

const config = {
  maxDuration: 30000, // 30 seconds
  onTimeout: 'return-partial'
}

Prevents: Long-running operations

4. Quality Gates

const config = {
  stopCondition: (result) => result.confidence > 0.9
}

Ensures: Quality outputs

Tool Orchestration

Sequential Tool Execution

const tools = {
  search: tool({ /* ... */ })
  analyze: tool({ /* ... */ })
  summarize: tool({ /* ... */ })
}

// AI decides order and usage
const result = await generateText({
  model: openai('gpt-4o')
  tools
  maxToolRoundtrips: 5
})

Parallel Tool Execution

const results = await Promise.all([
  callTool('search', { query: 'topic1' })
  callTool('search', { query: 'topic2' })
  callTool('search', { query: 'topic3' })
])

Agent State Management

interface AgentState {
  conversation: Message[]
  context: Record<string, any>
  toolResults: ToolResult[]
  iteration: number
}

class StatefulAgent {
  private state: AgentState

  async execute(task: string) {
    while (!this.isComplete()) {
      await this.step()
      this.updateState()
    }
    return this.state
  }
}

Production Best Practices

1. Error Recovery

try {
  result = await agent.execute(task)
} catch (error) {
  if (error.code === 'MAX_ITERATIONS') {
    return agent.getBestSoFar()
  }
  throw error
}

2. Monitoring

agent.on('iteration', ({ count, result }) => {
  metrics.record('agent.iteration', { count })
})

3. Safeguards

• Rate limiting
• Input validation
• Output sanitization
• Cost tracking

Common Agent Architectures

1. RAG Agent

Example: examples/rag-agent.ts

Retrieves information and answers questions

2. SQL Agent

Example: examples/sql-agent.ts

Queries databases using natural language

3. Research Agent

Example: examples/research-agent.ts

Gathers and synthesizes information

4. Code Agent

Example: examples/code-agent.ts

Writes and debugs code

Resources

Templates:

• react-agent.ts - ReAct pattern implementation
• multi-agent-system.ts - Multi-agent coordination
• workflow-orchestrator.ts - Workflow execution
• loop-control.ts - Iteration safeguards
• tool-coordinator.ts - Tool orchestration

Scripts:

• validate-agent.sh - Agent config validation

Examples:

• rag-agent.ts - Complete RAG agent
• sql-agent.ts - Natural language SQL
• research-agent.ts - Information gathering
• code-agent.ts - Code generation

---

SDK Version: Vercel AI SDK 5+ Agent Frameworks: Built-in tools, MCP integration

Best Practice: Start simple (single tool), add complexity as needed