Multi-Agent Workflow
Multi-Agent Workflow
Orchestrate multiple specialized AI agents to tackle complex, multi-step workflows.
Single agents are powerful, but complex tasks often require multiple specialists working together. This pattern shows you how to coordinate multiple AI agents in a workflow, with human oversight at critical decision points.
When to Use This
- ✅ Task requires multiple specialized skills (research + writing + review)
- ✅ You need parallel processing for speed
- ✅ Steps have dependencies (output of one feeds into another)
- ✅ You want human checkpoints at critical junctures
Architecture
┌─────────────────────────────────────────────────────┐
│ Workflow Orchestrator │
│ (HumanOS coordinates all agents) │
└────────────────────┬────────────────────────────────┘
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│Agent 1 │ │Agent 2 │ │Agent 3 │
│Research│ │ Write │ │ Review │
└───┬────┘ └───┬────┘ └───┬────┘
│ │ │
└───────────┼───────────┘
│
▼
┌──────────────────────┐
│ Human Checkpoint │
│ (approve/reject) │
└──────────┬───────────┘
│
▼
Final Output
Prerequisites
- API key
- Multiple agent Passports (one per role)
- Delegations for each agent
- Understanding of workflow dependencies
Implementation
Define a Multi-Agent Workflow
Create a workflow with multiple agents working in sequence:
TypeScript:
```typescript
import { HumanClient } from '@human/sdk';
const client = new HumanClient({
apiKey: process.env.HUMAN_API_KEY,
});
// Define workflow with multiple agents
const workflow = await client.humanos.createWorkflow({
name: 'content_creation_pipeline',
description: 'Research, write, and review content',
steps: [
{
stepId: 'research',
agent: 'agent_researcher_001',
task: 'research_topic',
input: {
topic: '${workflow.input.topic}',
depth: 'comprehensive',
},
capabilities: ['web_research', 'data_analysis'],
timeout: 300, // 5 minutes
},
{
stepId: 'outline',
agent: 'agent_writer_001',
task: 'create_outline',
input: {
research: '${steps.research.output}',
format: 'blog_post',
},
capabilities: ['content_planning'],
dependsOn: ['research'], // Wait for research to complete
timeout: 120,
},
{
stepId: 'write',
agent: 'agent_writer_001',
task: 'write_content',
input: {
outline: '${steps.outline.output}',
tone: 'professional',
length: 1500,
},
capabilities: ['content_writing'],
dependsOn: ['outline'],
timeout: 300,
},
{
stepId: 'human_review',
type: 'human_approval',
assignTo: '${workflow.creator}', // Route to workflow creator
input: {
content: '${steps.write.output}',
prompt: 'Please review the draft content and approve or request changes',
},
timeout: 86400, // 24 hours for human review
},
{
stepId: 'final_polish',
agent: 'agent_editor_001',
task: 'polish_content',
input: {
draft: '${steps.write.output}',
feedback: '${steps.human_review.feedback}',
},
capabilities: ['editing', 'proofreading'],
dependsOn: ['human_review'],
condition: '${steps.human_review.approved === true}',
timeout: 180,
},
],
onError: 'escalate_to_human',
provenance: true, // Log all actions
});
console.log(`Workflow created: ${workflow.workflowId}`);
```
Python:
```python
from human_sdk import HumanClient
client = HumanClient(api_key=os.environ["HUMAN_API_KEY"])
# Define workflow with multiple agents
workflow = client.humanos.create_workflow(
name="content_creation_pipeline",
description="Research, write, and review content",
steps=[
{
"step_id": "research",
"agent": "agent_researcher_001",
"task": "research_topic",
"input": {
"topic": "${workflow.input.topic}",
"depth": "comprehensive",
},
"capabilities": ["web_research", "data_analysis"],
"timeout": 300, # 5 minutes
},
{
"step_id": "outline",
"agent": "agent_writer_001",
"task": "create_outline",
"input": {
"research": "${steps.research.output}",
"format": "blog_post",
},
"capabilities": ["content_planning"],
"depends_on": ["research"], # Wait for research to complete
"timeout": 120,
},
{
"step_id": "write",
"agent": "agent_writer_001",
"task": "write_content",
"input": {
"outline": "${steps.outline.output}",
"tone": "professional",
"length": 1500,
},
"capabilities": ["content_writing"],
"depends_on": ["outline"],
"timeout": 300,
},
{
"step_id": "human_review",
"type": "human_approval",
"assign_to": "${workflow.creator}", # Route to workflow creator
"input": {
"content": "${steps.write.output}",
"prompt": "Please review the draft content and approve or request changes",
},
"timeout": 86400, # 24 hours for human review
},
{
"step_id": "final_polish",
"agent": "agent_editor_001",
"task": "polish_content",
"input": {
"draft": "${steps.write.output}",
"feedback": "${steps.human_review.feedback}",
},
"capabilities": ["editing", "proofreading"],
"depends_on": ["human_review"],
"condition": "${steps.human_review.approved === true}",
"timeout": 180,
},
],
on_error="escalate_to_human",
provenance=True # Log all actions
)
print(f"Workflow created: {workflow.workflow_id}")
```
Go:
```go
import "github.com/human/sdk-go"
client := human.NewClient(os.Getenv("HUMAN_API_KEY"))
// Define workflow with multiple agents
workflow, err := client.HumanOS.CreateWorkflow(&human.WorkflowDefinition{
Name: "content_creation_pipeline",
Description: "Research, write, and review content",
Steps: []human.WorkflowStep{
{
StepID: "research",
Agent: "agent_researcher_001",
Task: "research_topic",
Input: map[string]interface{}{
"topic": "${workflow.input.topic}",
"depth": "comprehensive",
},
Capabilities: []string{"web_research", "data_analysis"},
Timeout: 300, // 5 minutes
},
{
StepID: "outline",
Agent: "agent_writer_001",
Task: "create_outline",
Input: map[string]interface{}{
"research": "${steps.research.output}",
"format": "blog_post",
},
Capabilities: []string{"content_planning"},
DependsOn: []string{"research"}, // Wait for research to complete
Timeout: 120,
},
{
StepID: "write",
Agent: "agent_writer_001",
Task: "write_content",
Input: map[string]interface{}{
"outline": "${steps.outline.output}",
"tone": "professional",
"length": 1500,
},
Capabilities: []string{"content_writing"},
DependsOn: []string{"outline"},
Timeout: 300,
},
{
StepID: "human_review",
Type: "human_approval",
AssignTo: "${workflow.creator}", // Route to workflow creator
Input: map[string]interface{}{
"content": "${steps.write.output}",
"prompt": "Please review the draft content and approve or request changes",
},
Timeout: 86400, // 24 hours for human review
},
{
StepID: "final_polish",
Agent: "agent_editor_001",
Task: "polish_content",
Input: map[string]interface{}{
"draft": "${steps.write.output}",
"feedback": "${steps.human_review.feedback}",
},
Capabilities: []string{"editing", "proofreading"},
DependsOn: []string{"human_review"},
Condition: "${steps.human_review.approved === true}",
Timeout: 180,
},
},
OnError: "escalate_to_human",
Provenance: true, // Log all actions
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Workflow created: %s\n", workflow.WorkflowID)
```
REST API:
```bash
curl -X POST https://api.human.ai/v1/humanos/workflows \\
-H "Authorization: Bearer $HUMAN_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"name": "content_creation_pipeline",
"description": "Research, write, and review content",
"steps": [
{
"stepId": "research",
"agent": "agent_researcher_001",
"task": "research_topic",
"input": { "topic": "${workflow.input.topic}", "depth": "comprehensive" },
"capabilities": ["web_research", "data_analysis"],
"timeout": 300
},
{
"stepId": "outline",
"agent": "agent_writer_001",
"task": "create_outline",
"input": { "research": "${steps.research.output}", "format": "blog_post" },
"capabilities": ["content_planning"],
"dependsOn": ["research"],
"timeout": 120
},
{
"stepId": "write",
"agent": "agent_writer_001",
"task": "write_content",
"input": { "outline": "${steps.outline.output}", "tone": "professional", "length": 1500 },
"capabilities": ["content_writing"],
"dependsOn": ["outline"],
"timeout": 300
},
{
"stepId": "human_review",
"type": "human_approval",
"assignTo": "${workflow.creator}",
"input": {
"content": "${steps.write.output}",
"prompt": "Please review the draft content and approve or request changes"
},
"timeout": 86400
},
{
"stepId": "final_polish",
"agent": "agent_editor_001",
"task": "polish_content",
"input": { "draft": "${steps.write.output}", "feedback": "${steps.human_review.feedback}" },
"capabilities": ["editing", "proofreading"],
"dependsOn": ["human_review"],
"condition": "${steps.human_review.approved === true}",
"timeout": 180
}
],
"onError": "escalate_to_human",
"provenance": true
}'
```
Execute Multi-Agent Workflow
Start a workflow execution with input:
TypeScript:
```typescript
// Execute the workflow
const execution = await client.humanos.executeWorkflow({
workflowId: workflow.workflowId,
input: {
topic: 'The Future of Human-AI Collaboration',
targetAudience: 'tech leaders',
},
});
console.log(`Execution started: ${execution.executionId}`);
console.log(`Status: ${execution.status}`);
// Monitor execution
const result = await client.humanos.waitForWorkflow(execution.executionId);
console.log(`Workflow completed in ${result.duration}ms`);
console.log(`Final output:`, result.output);
```
Python:
```python
# Execute the workflow
execution = client.humanos.execute_workflow(
workflow_id=workflow.workflow_id,
input={
"topic": "The Future of Human-AI Collaboration",
"target_audience": "tech leaders",
}
)
print(f"Execution started: {execution.execution_id}")
print(f"Status: {execution.status}")
# Monitor execution
result = client.humanos.wait_for_workflow(execution.execution_id)
print(f"Workflow completed in {result.duration}ms")
print(f"Final output: {result.output}")
```
Go:
```go
// Execute the workflow
execution, err := client.HumanOS.ExecuteWorkflow(&human.WorkflowExecution{
WorkflowID: workflow.WorkflowID,
Input: map[string]interface{}{
"topic": "The Future of Human-AI Collaboration",
"target_audience": "tech leaders",
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Execution started: %s\n", execution.ExecutionID)
fmt.Printf("Status: %s\n", execution.Status)
// Monitor execution
result, err := client.HumanOS.WaitForWorkflow(execution.ExecutionID)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Workflow completed in %dms\n", result.Duration)
fmt.Printf("Final output: %v\n", result.Output)
```
REST API:
```bash
# Execute workflow
curl -X POST https://api.human.ai/v1/humanos/workflows/{workflow_id}/execute \\
-H "Authorization: Bearer $HUMAN_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"input": {
"topic": "The Future of Human-AI Collaboration",
"targetAudience": "tech leaders"
}
}'
# Monitor execution
curl https://api.human.ai/v1/humanos/executions/{execution_id} \\
-H "Authorization: Bearer $HUMAN_API_KEY"
```
Use Cases
file-text:Content Creation|Research → Outline → Write → Review → Publish pipeline
briefcase:Document Processing|Extract → Classify → Analyze → Summarize → Route
shield:Security Analysis|Scan → Detect Threats → Assess Risk → Generate Report
database:Data Pipeline|Collect → Clean → Transform → Analyze → Visualize
Best Practices
Workflow Design
- Keep steps atomic - each step should have a single, clear responsibility
- Define clear inputs/outputs - avoid implicit dependencies
- Set appropriate timeouts - balance urgency with task complexity
- Include human checkpoints at high-risk decision points
- Handle errors gracefully - define fallback strategies
Agent Coordination
- Use capability-based routing - assign steps to agents with verified skills
- Minimize data transfer - pass references, not full documents, between steps
- Enable parallel execution where possible (no dependencies)
- Log all interactions for debugging and audit trails
Performance
- Cache intermediate results - avoid re-running expensive steps
- Set step timeouts to prevent hanging workflows
- Monitor execution metrics - identify bottlenecks
- Scale agents independently based on step load
Security Considerations
do:Validate agent credentials before workflow execution
do:Log all workflow steps for audit trails
do:Set maximum execution time limits
do:Verify agent capabilities match step requirements
dont:Allow agents to modify workflow definitions mid-execution
dont:Pass sensitive data without encryption between steps
dont:Skip human approval for high-risk actions
dont:Allow infinite loops or recursion in workflows
Related Patterns
- Simple Orchestration - Single-agent workflows
- Human-in-Loop - Adding human checkpoints
- Provenance Tracking - Audit workflow executions