Save this content to: .claude/skills/vizra-workflows/SKILL.md

# Vizra ADK Workflow Patterns

Workflows orchestrate multiple agents to accomplish complex tasks. Vizra ADK supports sequential, parallel, conditional, and loop workflows.

## Workflow Types

| Workflow | Use Case |
|----------|----------|
| Sequential | Steps that must execute in order |
| Parallel | Independent tasks that can run simultaneously |
| Conditional | Branching based on conditions or results |
| Loop | Iterating over data or repeating until condition met |

## Sequential Workflow

Execute agents in order, passing results between steps:

```php
use Vizra\VizraADK\Workflows\SequentialWorkflow;

$workflow = SequentialWorkflow::create()
    ->addStep('research', ResearchAgent::class)
    ->addStep('analyze', AnalysisAgent::class)
    ->addStep('report', ReportGeneratorAgent::class);

$result = $workflow->run([
    'topic' => 'Market trends in AI',
    'depth' => 'comprehensive'
]);
```

### Passing Data Between Steps

```php
$workflow = SequentialWorkflow::create()
    ->addStep('fetch', DataFetcherAgent::class)
    ->addStep('transform', function ($previousResult, $context) {
        // Transform data from previous step
        return TransformAgent::run($previousResult['data'])
            ->withParameters(['format' => 'json'])
            ->go();
    })
    ->addStep('store', DataStorageAgent::class);
```

## Parallel Workflow

Run multiple agents simultaneously for independent tasks:

```php
use Vizra\VizraADK\Workflows\ParallelWorkflow;

$workflow = ParallelWorkflow::create()
    ->addTask('sentiment', SentimentAnalysisAgent::class)
    ->addTask('keywords', KeywordExtractionAgent::class)
    ->addTask('summary', SummarizationAgent::class);

$results = $workflow->run([
    'text' => $documentText
]);

// Results contain output from all agents
// $results['sentiment'], $results['keywords'], $results['summary']
```

### With Timeout

```php
$workflow = ParallelWorkflow::create()
    ->addTask('fast', FastAgent::class)
    ->addTask('slow', SlowAgent::class)
    ->timeout(30); // 30 second timeout

$results = $workflow->run($input);
```

## Conditional Workflow

Branch execution based on conditions:

```php
use Vizra\VizraADK\Workflows\ConditionalWorkflow;

$workflow = ConditionalWorkflow::create()
    ->addStep('classify', ClassificationAgent::class)
    ->branch(
        condition: fn($result) => $result['category'] === 'urgent',
        then: UrgentHandlerAgent::class,
        else: StandardHandlerAgent::class
    );

$result = $workflow->run(['ticket' => $ticketContent]);
```

### Multiple Conditions

```php
$workflow = ConditionalWorkflow::create()
    ->addStep('analyze', AnalysisAgent::class)
    ->switch(
        selector: fn($result) => $result['priority'],
        cases: [
            'high' => HighPriorityAgent::class,
            'medium' => MediumPriorityAgent::class,
            'low' => LowPriorityAgent::class,
        ],
        default: StandardAgent::class
    );
```

## Loop Workflow

Iterate over data or repeat until condition:

```php
use Vizra\VizraADK\Workflows\LoopWorkflow;

// Iterate over items
$workflow = LoopWorkflow::create()
    ->forEach(
        items: fn($context) => $context['documents'],
        agent: DocumentProcessorAgent::class
    );

$results = $workflow->run([
    'documents' => $documentList
]);
```

### With Condition

```php
$workflow = LoopWorkflow::create()
    ->repeat(
        agent: RefinementAgent::class,
        until: fn($result, $iteration) =>
            $result['quality_score'] >= 0.9 || $iteration >= 5
    );
```

### Map-Reduce Pattern

```php
$workflow = LoopWorkflow::create()
    ->map(
        items: fn($ctx) => $ctx['chunks'],
        agent: ChunkProcessorAgent::class
    )
    ->reduce(
        agent: AggregatorAgent::class
    );

$result = $workflow->run([
    'chunks' => $textChunks
]);
```

## Complex Workflow Compositions

### Research Pipeline

```php
$researchPipeline = SequentialWorkflow::create()
    // Step 1: Gather information from multiple sources in parallel
    ->addStep('gather', ParallelWorkflow::create()
        ->addTask('web', WebResearchAgent::class)
        ->addTask('database', DatabaseResearchAgent::class)
        ->addTask('documents', DocumentResearchAgent::class)
    )
    // Step 2: Analyze gathered information
    ->addStep('analyze', AnalysisAgent::class)
    // Step 3: Generate report
    ->addStep('report', ReportGeneratorAgent::class);

$report = $researchPipeline->run([
    'topic' => 'Competitive analysis',
    'sources' => ['web', 'internal_docs', 'database']
]);
```

### Customer Service Escalation

```php
$customerService = ConditionalWorkflow::create()
    // Initial classification
    ->addStep('classify', TicketClassifierAgent::class)
    // Route based on complexity
    ->branch(
        condition: fn($r) => $r['complexity'] === 'simple',
        then: SequentialWorkflow::create()
            ->addStep('respond', AutoResponderAgent::class)
            ->addStep('close', TicketCloserAgent::class),
        else: ConditionalWorkflow::create()
            ->branch(
                condition: fn($r) => $r['requires_human'],
                then: HumanEscalationAgent::class,
                else: SequentialWorkflow::create()
                    ->addStep('research', IssueResearchAgent::class)
                    ->addStep('respond', DetailedResponderAgent::class)
            )
    );
```

### Data Processing Pipeline

```php
$dataPipeline = SequentialWorkflow::create()
    // Validate incoming data
    ->addStep('validate', DataValidationAgent::class)
    // Process each record
    ->addStep('process', LoopWorkflow::create()
        ->forEach(
            items: fn($ctx) => $ctx['records'],
            agent: RecordProcessorAgent::class
        )
    )
    // Aggregate results
    ->addStep('aggregate', AggregationAgent::class)
    // Generate summary
    ->addStep('summarize', SummaryAgent::class);
```

## Error Handling in Workflows

```php
$workflow = SequentialWorkflow::create()
    ->addStep('risky', RiskyAgent::class)
    ->onError(function ($error, $step, $context) {
        Log::error("Workflow failed at step: {$step}", [
            'error' => $error->getMessage()
        ]);

        // Return fallback or rethrow
        return FallbackAgent::run($context)->go();
    })
    ->addStep('continue', NextAgent::class);
```

### Retry Logic

```php
$workflow = SequentialWorkflow::create()
    ->addStep('api_call', ExternalApiAgent::class)
    ->withRetry(
        maxAttempts: 3,
        delay: 1000, // milliseconds
        backoff: 'exponential'
    );
```

## Workflow Context

Access and modify context throughout workflow:

```php
$workflow = SequentialWorkflow::create()
    ->addStep('init', function ($input, $context) {
        $context->set('started_at', now());
        return InitAgent::run($input)->go();
    })
    ->addStep('process', ProcessorAgent::class)
    ->addStep('finalize', function ($result, $context) {
        $duration = now()->diffInSeconds($context->get('started_at'));
        return FinalizeAgent::run($result)
            ->withParameters(['duration' => $duration])
            ->go();
    });
```

## Performance Optimization

### Use Parallel for Independent Tasks

```php
// Good: Independent tasks run in parallel
$workflow = ParallelWorkflow::create()
    ->addTask('email', SendEmailAgent::class)
    ->addTask('sms', SendSmsAgent::class)
    ->addTask('push', SendPushAgent::class);

// Bad: Sequential when not needed
$workflow = SequentialWorkflow::create()
    ->addStep('email', SendEmailAgent::class)
    ->addStep('sms', SendSmsAgent::class)
    ->addStep('push', SendPushAgent::class);
```

### Set Appropriate Timeouts

```php
$workflow = ParallelWorkflow::create()
    ->addTask('fast', FastAgent::class)
    ->addTask('slow', SlowAgent::class)
    ->timeout(60)
    ->onTimeout(function ($completedTasks) {
        // Handle partial results
        return $completedTasks;
    });
```

## Testing Workflows

```php
class WorkflowTest extends TestCase
{
    public function test_sequential_workflow_completes()
    {
        $workflow = SequentialWorkflow::create()
            ->addStep('first', FirstAgent::class)
            ->addStep('second', SecondAgent::class);

$result = $workflow->run(['input' => 'test']);

        $this->assertNotNull($result);
        $this->assertEquals('expected', $result['status']);
    }
}
```