multi-agent-orchestration
Designs and runs systems where several AI agents cooperate. Use whenever the user wants to split a task across agents, design planner and worker roles, define message contracts between agents, add a reviewer or critic loop, handle agent failures, or evaluate a multi-agent setup a
Install
npx skills add https://github.com/MehranQadirian/skills/tree/main/agent-engineering/multi-agent-orchestration
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mehranqadirian-skills@llmmart
git clone https://github.com/MehranQadirian/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mehranqadirian/skills collection as a plugin from our marketplace. Git is the plain clone.
README
multi-agent-orchestration
A Claude skill for designing and running systems where several AI agents cooperate.
What it does
- Picks a coordination pattern: orchestrator-worker, pipeline, fan-out, critic loop or debate
- Defines roles, message contracts and shared state
- Adds limits, retries and validation against injection between agents
- Evaluates the setup against a single-agent baseline
- Ships a runnable orchestrator skeleton and a dependency free contract validator
- Includes templates for contracts and role cards
Try it
Design a planner and worker setup that summarizes 50 PDFs.
Add a reviewer agent that checks the draft against criteria.
Is a multi-agent design worth it for this task?
Install
Claude.ai: zip this folder, then go to Settings > Capabilities > Skills > Upload.
Claude Code:
cp -r agent-engineering/multi-agent-orchestration ~/.claude/skills/
Structure
multi-agent-orchestration/
├── SKILL.md skill instructions for Claude
├── scripts/
│ ├── orchestrator_skeleton.py runnable orchestrator with retries, budget and trace
│ └── validate_contract.py JSON schema check for agent outputs
├── references/
│ ├── patterns.md patterns, roles, contracts, security
│ └── evaluation.md baselines, metrics, launch checklist
└── templates/
├── contract.json handoff message template
└── agent-role.md role card
Skill manifest
multi-agent-orchestration
Split a complex task across specialized agents, coordinate them through explicit contracts, and verify the combined result. Use multiple agents only when a single agent cannot do the job reliably.
multi-agent-orchestration/
├── SKILL.md
├── scripts/
│ ├── orchestrator_skeleton.py runnable orchestrator: retries, budget, timeout, trace, gap report
│ └── validate_contract.py dependency free JSON schema check for agent outputs
├── references/
│ ├── patterns.md pattern decision guide, role design, contracts, security
│ └── evaluation.md baselines, test set, metrics, trace analysis, launch checklist
└── templates/
├── contract.json handoff message with schema, limits and tools
└── agent-role.md role card to fill before writing prompts
When to use
- The task has independent parts that can run in parallel
- Different parts need different tools, prompts or permissions
- A second agent should review or challenge the first agent's output
- Context is too large for one agent
If none of these is true, use one agent. Say so to the user.
Choose a pattern
| Pattern | Description | Best for |
|---|---|---|
| Orchestrator-Worker | One planner delegates to workers and merges results | Research, code changes across files |
| Pipeline | Output of agent A feeds agent B | Extract, transform, validate |
| Fan-out / Fan-in | Many workers run in parallel, one aggregator merges | Batch analysis |
| Critic loop | Producer and reviewer iterate until criteria pass | Writing, code review |
| Debate | Agents argue positions, a judge decides | Ambiguous decisions |
Decision guide and risks per pattern: references/patterns.md.
Design steps
- Define the goal and measurable success criteria
- List roles; fill a role card (
templates/agent-role.md) per agent with one responsibility and minimal tools - Define message contracts (
templates/contract.json) - Decide shared state: what is passed, what stays private
- Add limits: max steps, max tokens, timeouts, retry policy
- Add verification: an independent check before returning results
- Log every handoff for tracing and debugging
- Evaluate against a single-agent baseline (
references/evaluation.md)
Example contract
{
"task_id": "T-104",
"role": "researcher",
"input": {"question": "Summarize the report", "files": ["report.pdf"]},
"output_schema": {
"summary": "string",
"sources": ["string"],
"confidence": "low|medium|high"
}
}
Validate any agent output:
python3 scripts/validate_contract.py schema.json output.json
The schema language is tiny: "string", "number", "boolean", "low|medium|high" for enums, ["string"] for arrays, nested objects, and a trailing ? for optional keys.
Reference orchestrator
Run the offline demo to see retries, budget and trace in action:
python3 scripts/orchestrator_skeleton.py
Core shape (see the script for the full version with locks and timeouts):
orch = Orchestrator(call_model) # call_model(role, payload) -> dict
result = orch.run("summarize the report")
# {"result": "...", "gaps": [...], "steps": 8}
Replace call_model with your real model or tool runner. Keep the schemas in SCHEMAS in sync with your prompts.
Failure handling
- Validate every agent output against its schema; retry once with the error message
- Use timeouts and a global step budget to prevent loops
- On repeated failure, return partial results with an explicit gap report
- Never let one agent's output act as instructions for another without validation (prompt injection risk)
- Separate agents that read untrusted content from agents that hold powerful tools
Evaluation
- Compare against a single-agent baseline; keep multi-agent only if it wins on quality or cost
- Track success rate, schema validity, retries, latency and token cost from
trace.jsonl - Keep a fixed test set and rerun it after every prompt or topology change
What to report back
| Field | Content |
|---|---|
| Chosen pattern | and why a single agent was not enough |
| Roles | one line each, with tools |
| Contracts | schema per handoff |
| Limits | steps, timeout, retries |
| Evaluation plan | baseline, test set size, metrics |
| Known risks | injection, cost, single points of failure |
Related skills
systematic-debugging: trace handoff logs to find which agent produced a wrong resultpdf-processing: a worker agent for document extraction and verification
Files (skills)
-
references
-
evaluation.md 2.4 KB
Loading… -
patterns.md 3.2 KB
Loading…
-
-
scripts
-
orchestrator_skeleton.py 5.3 KB
Loading… -
validate_contract.py 3.2 KB
Loading…
-
-
templates
-
agent-role.md 722 B
Loading… -
contract.json 421 B
Loading…
-
-
README.md 1.6 KB
# multi-agent-orchestration A [Claude skill](../../README.md) for designing and running systems where several AI agents cooperate. ## What it does - Picks a coordination pattern: orchestrator-worker, pipeline, fan-out, critic loop or debate - Defines roles, message contracts and shared state - Adds limits, retries and validation against injection between agents - Evaluates the setup against a single-agent baseline - Ships a runnable orchestrator skeleton and a dependency free contract validator - Includes templates for contracts and role cards ## Try it > Design a planner and worker setup that summarizes 50 PDFs. > Add a reviewer agent that checks the draft against criteria. > Is a multi-agent design worth it for this task? ## Install **Claude.ai:** zip this folder, then go to Settings > Capabilities > Skills > Upload. **Claude Code:** ```bash cp -r agent-engineering/multi-agent-orchestration ~/.claude/skills/ ``` ## Structure ``` multi-agent-orchestration/ ├── SKILL.md skill instructions for Claude ├── scripts/ │ ├── orchestrator_skeleton.py runnable orchestrator with retries, budget and trace │ └── validate_contract.py JSON schema check for agent outputs ├── references/ │ ├── patterns.md patterns, roles, contracts, security │ └── evaluation.md baselines, metrics, launch checklist └── templates/ ├── contract.json handoff message template └── agent-role.md role card ``` -
SKILL.md 5 KB
--- name: multi-agent-orchestration description: Designs and runs systems where several AI agents cooperate. Use whenever the user wants to split a task across agents, design planner and worker roles, define message contracts between agents, add a reviewer or critic loop, handle agent failures, or evaluate a multi-agent setup against a single agent, even if they only say "use multiple agents for this". Covers coordination patterns, retries, limits and evaluation. --- # multi-agent-orchestration Split a complex task across specialized agents, coordinate them through explicit contracts, and verify the combined result. Use multiple agents only when a single agent cannot do the job reliably. ``` multi-agent-orchestration/ ├── SKILL.md ├── scripts/ │ ├── orchestrator_skeleton.py runnable orchestrator: retries, budget, timeout, trace, gap report │ └── validate_contract.py dependency free JSON schema check for agent outputs ├── references/ │ ├── patterns.md pattern decision guide, role design, contracts, security │ └── evaluation.md baselines, test set, metrics, trace analysis, launch checklist └── templates/ ├── contract.json handoff message with schema, limits and tools └── agent-role.md role card to fill before writing prompts ``` ## When to use - The task has independent parts that can run in parallel - Different parts need different tools, prompts or permissions - A second agent should review or challenge the first agent's output - Context is too large for one agent If none of these is true, use one agent. Say so to the user. ## Choose a pattern | Pattern | Description | Best for | |---------|-------------|----------| | Orchestrator-Worker | One planner delegates to workers and merges results | Research, code changes across files | | Pipeline | Output of agent A feeds agent B | Extract, transform, validate | | Fan-out / Fan-in | Many workers run in parallel, one aggregator merges | Batch analysis | | Critic loop | Producer and reviewer iterate until criteria pass | Writing, code review | | Debate | Agents argue positions, a judge decides | Ambiguous decisions | Decision guide and risks per pattern: `references/patterns.md`. ## Design steps 1. Define the goal and measurable success criteria 2. List roles; fill a role card (`templates/agent-role.md`) per agent with one responsibility and minimal tools 3. Define message contracts (`templates/contract.json`) 4. Decide shared state: what is passed, what stays private 5. Add limits: max steps, max tokens, timeouts, retry policy 6. Add verification: an independent check before returning results 7. Log every handoff for tracing and debugging 8. Evaluate against a single-agent baseline (`references/evaluation.md`) ## Example contract ```json { "task_id": "T-104", "role": "researcher", "input": {"question": "Summarize the report", "files": ["report.pdf"]}, "output_schema": { "summary": "string", "sources": ["string"], "confidence": "low|medium|high" } } ``` Validate any agent output: ```bash python3 scripts/validate_contract.py schema.json output.json ``` The schema language is tiny: `"string"`, `"number"`, `"boolean"`, `"low|medium|high"` for enums, `["string"]` for arrays, nested objects, and a trailing `?` for optional keys. ## Reference orchestrator Run the offline demo to see retries, budget and trace in action: ```bash python3 scripts/orchestrator_skeleton.py ``` Core shape (see the script for the full version with locks and timeouts): ```python orch = Orchestrator(call_model) # call_model(role, payload) -> dict result = orch.run("summarize the report") # {"result": "...", "gaps": [...], "steps": 8} ``` Replace `call_model` with your real model or tool runner. Keep the schemas in `SCHEMAS` in sync with your prompts. ## Failure handling - Validate every agent output against its schema; retry once with the error message - Use timeouts and a global step budget to prevent loops - On repeated failure, return partial results with an explicit gap report - Never let one agent's output act as instructions for another without validation (prompt injection risk) - Separate agents that read untrusted content from agents that hold powerful tools ## Evaluation - Compare against a single-agent baseline; keep multi-agent only if it wins on quality or cost - Track success rate, schema validity, retries, latency and token cost from `trace.jsonl` - Keep a fixed test set and rerun it after every prompt or topology change ## What to report back | Field | Content | |-------|---------| | Chosen pattern | and why a single agent was not enough | | Roles | one line each, with tools | | Contracts | schema per handoff | | Limits | steps, timeout, retries | | Evaluation plan | baseline, test set size, metrics | | Known risks | injection, cost, single points of failure | ## Related skills - `systematic-debugging`: trace handoff logs to find which agent produced a wrong result - `pdf-processing`: a worker agent for document extraction and verification
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.