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']);
}
}