Skip to content

Commit 7d73f2b

Browse files
mark-hingstonmark-hingston
committed
docs: add agent orchestration section and code-review example
1 parent 7b5c622 commit 7d73f2b

File tree

2 files changed

+182
-0
lines changed

2 files changed

+182
-0
lines changed

‎README.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,106 @@ Steps can declare dependencies using `after`:
295295

296296
Steps at the same dependency level run in parallel.
297297

298+
## Agent Orchestration
299+
300+
One of the most powerful use cases is orchestrating multiple AI agents in a deterministic pipeline. This lets you build reliable, repeatable AI workflows where specialized agents collaborate on complex tasks.
301+
302+
### Multi-Agent Code Review
303+
304+
This example chains multiple specialized agents to review code from different perspectives, then synthesizes their findings:
305+
306+
```json
307+
{
308+
"id": "code-review",
309+
"name": "Multi-Agent Code Review",
310+
"description": "Parallel expert review with synthesis",
311+
"inputs": {
312+
"file": {
313+
"type": "string",
314+
"description": "File path to review",
315+
"required": true
316+
}
317+
},
318+
"steps": [
319+
{
320+
"id": "read_file",
321+
"type": "tool",
322+
"tool": "read",
323+
"args": { "filePath": "{{inputs.file}}" }
324+
},
325+
{
326+
"id": "security_review",
327+
"type": "agent",
328+
"system": "You are a security expert. Identify vulnerabilities, injection risks, and auth issues. Be concise.",
329+
"prompt": "Review this code for security issues:\n\n{{steps.read_file.result}}",
330+
"model": "anthropic:claude-sonnet-4-20250514",
331+
"after": ["read_file"]
332+
},
333+
{
334+
"id": "perf_review",
335+
"type": "agent",
336+
"system": "You are a performance engineer. Identify bottlenecks, memory leaks, and optimization opportunities. Be concise.",
337+
"prompt": "Review this code for performance issues:\n\n{{steps.read_file.result}}",
338+
"model": "anthropic:claude-sonnet-4-20250514",
339+
"after": ["read_file"]
340+
},
341+
{
342+
"id": "quality_review",
343+
"type": "agent",
344+
"system": "You are a senior developer. Review for readability, maintainability, and best practices. Be concise.",
345+
"prompt": "Review this code for quality issues:\n\n{{steps.read_file.result}}",
346+
"model": "anthropic:claude-sonnet-4-20250514",
347+
"after": ["read_file"]
348+
},
349+
{
350+
"id": "synthesize",
351+
"type": "agent",
352+
"system": "You are a tech lead. Synthesize code reviews into a prioritized action list grouped by severity.",
353+
"prompt": "Combine these reviews into a single report:\n\n## Security\n{{steps.security_review.response}}\n\n## Performance\n{{steps.perf_review.response}}\n\n## Quality\n{{steps.quality_review.response}}",
354+
"model": "anthropic:claude-sonnet-4-20250514",
355+
"after": ["security_review", "perf_review", "quality_review"]
356+
},
357+
{
358+
"id": "approve_fixes",
359+
"type": "suspend",
360+
"message": "Review complete:\n\n{{steps.synthesize.response}}\n\nResume to generate fixes.",
361+
"after": ["synthesize"]
362+
},
363+
{
364+
"id": "generate_fixes",
365+
"type": "agent",
366+
"system": "You are a code fixer. Output ONLY the corrected code, no explanations.",
367+
"prompt": "Fix the critical and high severity issues:\n\nOriginal:\n{{steps.read_file.result}}\n\nIssues:\n{{steps.synthesize.response}}",
368+
"model": "anthropic:claude-sonnet-4-20250514",
369+
"after": ["approve_fixes"]
370+
}
371+
]
372+
}
373+
```
374+
375+
Run it with:
376+
```
377+
/workflow run code-review file=src/api/auth.ts
378+
```
379+
380+
### Orchestration Patterns
381+
382+
| Pattern | Description | Example |
383+
|---------|-------------|---------|
384+
| **Sequential Chain** | Each agent uses the previous agent's output | Planner → Executor → Reviewer |
385+
| **Parallel Experts** | Multiple agents analyze independently, then synthesize | Security + Performance + Quality → Summary |
386+
| **Tool-Augmented** | Agents use tools to read files, search code, make API calls | Read file → Analyze → Write fix |
387+
| **Human-in-the-Loop** | `suspend` steps for approval between agent actions | Generate → Approve → Apply |
388+
| **Conditional Routing** | Use `condition` to skip agents based on results | Skip deploy agent if tests failed |
389+
390+
### Why Use Workflows for Agent Orchestration?
391+
392+
- **Deterministic**: Unlike free-form agent conversations, workflows execute the same steps every time
393+
- **Auditable**: Each step's output is captured and can be reviewed
394+
- **Resumable**: Workflows persist to disk and survive restarts
395+
- **Composable**: Build complex pipelines from simple, focused agents
396+
- **Controllable**: Human approval gates prevent unwanted actions
397+
298398
## License
299399

300400
MIT

‎examples/code-review.json‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
{
2+
"id": "code-review",
3+
"name": "Multi-Agent Code Review",
4+
"description": "Parallel expert code review with synthesis and optional auto-fix",
5+
"version": "1.0.0",
6+
"tags": ["review", "agents", "quality"],
7+
"inputs": {
8+
"file": {
9+
"type": "string",
10+
"description": "File path to review",
11+
"required": true
12+
}
13+
},
14+
"steps": [
15+
{
16+
"id": "read_file",
17+
"type": "tool",
18+
"description": "Read the source file",
19+
"tool": "read",
20+
"args": {
21+
"filePath": "{{inputs.file}}"
22+
}
23+
},
24+
{
25+
"id": "security_review",
26+
"type": "agent",
27+
"description": "Security vulnerability analysis",
28+
"system": "You are a security expert. Identify vulnerabilities, injection risks, authentication issues, and data exposure. Be concise and specific.",
29+
"prompt": "Review this code for security issues:\n\n{{steps.read_file.result}}",
30+
"model": "anthropic:claude-sonnet-4-20250514",
31+
"maxTokens": 1000,
32+
"after": ["read_file"]
33+
},
34+
{
35+
"id": "perf_review",
36+
"type": "agent",
37+
"description": "Performance analysis",
38+
"system": "You are a performance engineer. Identify bottlenecks, memory leaks, N+1 queries, and optimization opportunities. Be concise and specific.",
39+
"prompt": "Review this code for performance issues:\n\n{{steps.read_file.result}}",
40+
"model": "anthropic:claude-sonnet-4-20250514",
41+
"maxTokens": 1000,
42+
"after": ["read_file"]
43+
},
44+
{
45+
"id": "quality_review",
46+
"type": "agent",
47+
"description": "Code quality analysis",
48+
"system": "You are a senior developer. Review for readability, maintainability, error handling, and best practices. Be concise and specific.",
49+
"prompt": "Review this code for quality issues:\n\n{{steps.read_file.result}}",
50+
"model": "anthropic:claude-sonnet-4-20250514",
51+
"maxTokens": 1000,
52+
"after": ["read_file"]
53+
},
54+
{
55+
"id": "synthesize",
56+
"type": "agent",
57+
"description": "Synthesize reviews into prioritized action items",
58+
"system": "You are a tech lead. Synthesize multiple code reviews into a single prioritized action list. Group issues by severity: critical, high, medium, low. Be actionable.",
59+
"prompt": "Combine these code reviews into a prioritized report:\n\n## Security Review\n{{steps.security_review.response}}\n\n## Performance Review\n{{steps.perf_review.response}}\n\n## Quality Review\n{{steps.quality_review.response}}",
60+
"model": "anthropic:claude-sonnet-4-20250514",
61+
"maxTokens": 2000,
62+
"after": ["security_review", "perf_review", "quality_review"]
63+
},
64+
{
65+
"id": "approve_fixes",
66+
"type": "suspend",
67+
"description": "Human approval gate before generating fixes",
68+
"message": "Code review complete for {{inputs.file}}:\n\n{{steps.synthesize.response}}\n\nResume to generate auto-fix suggestions.",
69+
"after": ["synthesize"]
70+
},
71+
{
72+
"id": "generate_fixes",
73+
"type": "agent",
74+
"description": "Generate fixed code",
75+
"system": "You are a code fixer. Apply the requested fixes to the code. Output ONLY the complete corrected code with no explanations or markdown.",
76+
"prompt": "Fix the critical and high severity issues in this code:\n\nOriginal code:\n{{steps.read_file.result}}\n\nIssues to fix:\n{{steps.synthesize.response}}",
77+
"model": "anthropic:claude-sonnet-4-20250514",
78+
"maxTokens": 4000,
79+
"after": ["approve_fixes"]
80+
}
81+
]
82+
}

0 commit comments

Comments
 (0)