Agent Orchestration
Comprehensive patterns for building and coordinating AI agents -- from single-agent reasoning loops to multi-agent systems and framework selection. Coordination and multi-scenario categories have individual rule files in rules/ loaded on-demand; loop and framework tutorials live upstream (see Upstream coverage), with house defaults in references/ork-delta.md.
CC native /workflows (2.1.154): Claude Code now ships dynamic workflows — ask Claude to create a workflow and it orchestrates tens-to-hundreds of agents in the background; view runs with /workflows. This is complementary to the patterns here: use CC /workflows for large-scale, fire-and-forget background fan-out (you check back later); use the bounded foreground Agent Teams / Task-tool patterns below when ≤8 agents must coordinate within a single skill invocation via shared memory (handoff files, mesh messaging). Different scale, not a replacement.
Ask only when genuinely blocked (CC 2.1.154): CC now reserves the multiple-choice question prompt for decisions it genuinely cannot make itself, rather than asking when it already has enough context to proceed. When orchestrating agents, don't gate progress on an AskUserQuestion the lead can resolve from available context — reserve prompts for true branch points (irreversible actions, missing requirements). This complements ork's voice-friendly decision guidance.
Quick Reference
Total: 4 rules across 4 categories. Loop and framework tutorials moved to first-party sources; the rescued house defaults live in references/ork-delta.md.
Quick Start
async def react_loop(question: str, tools: dict, max_steps: int = 10) -> str:
history = REACT_PROMPT.format(tools=list(tools.keys()), question=question)
for step in range(max_steps):
response = await llm.chat([{"role": "user", "content": history}])
if "Final Answer:" in response.content:
return response.content.split("Final Answer:")[-1].strip()
if "Action:" in response.content:
action = parse_action(response.content)
result = await tools[action.name](*action.args)
history += f"\nObservation: {result}\n"
return "Max steps reached without answer"
async def multi_agent_analysis(content: str) -> dict:
agents = [("security", security_agent), ("perf", perf_agent)]
tasks = [agent(content) for _, agent in agents]
results = await asyncio.gather(*tasks, return_exceptions=True)
return await synthesize_findings(results)
Agent Loops
Patterns for autonomous LLM reasoning: ReAct (Reasoning + Acting), Plan-and-Execute with replanning, self-correction loops, and sliding-window memory management.
Key decisions: Max steps 5-15, temperature 0.3-0.7, memory window 10-20 messages.
Multi-Agent Coordination
Fan-out/fan-in parallelism, supervisor routing with dependency ordering, conflict resolution (confidence-based or LLM arbitration), result synthesis, and CC Agent Teams (mesh topology for peer messaging in CC 2.1.33+).
Key decisions: 3-8 specialists, parallelize independent agents, use Task tool (star) for simple work, Agent Teams (mesh) for cross-cutting concerns.
Alternative Frameworks
CrewAI hierarchical crews with Flows (1.8+), OpenAI Agents SDK handoffs and guardrails (0.12+), Microsoft Agent Framework (AutoGen + SK merger), GPT-5.2-Codex for long-horizon coding, and AG2 for open-source flexibility.
Key decisions: Match framework to team expertise + use case. LangGraph for state machines, CrewAI for role-based teams, OpenAI SDK for handoff workflows, MS Agent for enterprise compliance.
Multi-Scenario
Orchestrate a single skill across 3 parallel scenarios (simple/medium/complex) with progressive difficulty scaling (1x/3x/8x), milestone synchronization, and cross-scenario result aggregation.
Key decisions: Free-running with checkpoints, always 3 scenarios, 1x/3x/8x exponential scaling, 30s/90s/300s time budgets.
Upstream coverage (do not restate)
Local tutorials for these topics were retired; consult the first-party source and keep only house deltas in references/ork-delta.md.
| Topic | First-party source |
|---|
| ReAct / plan-and-execute / self-correction loop implementations | OpenAI function calling guide (https://platform.openai.com/docs/guides/function-calling); LangGraph tutorials (context7: /langchain-ai/langgraph) |
| Fan-out coordination, result-synthesis boilerplate, and the generic multi-agent design checklist | Python asyncio docs (https://docs.python.org/3/library/asyncio-task.html); Anthropic "Building effective agents" (https://www.anthropic.com/research/building-effective-agents); ork:langgraph supervisor patterns |
| CrewAI (crews, Flows, MCP tools, guardrails) | CrewAI docs (https://docs.crewai.com); context7: /crewaiinc/crewai |
| OpenAI Agents SDK (handoffs, sessions, guardrails, MCP) | https://openai.github.io/openai-agents-python/ ; context7: /openai/openai-agents-python |
| Microsoft Agent Framework / AutoGen (teams, termination, A2A) | https://learn.microsoft.com/en-us/agent-framework/ ; context7: /microsoft/autogen |
| GPT-5.2-Codex capabilities, pricing, IDE integrations | OpenAI model docs (https://platform.openai.com/docs/models) |
| Multi-scenario state machine, architecture and skill-agnostic template deep-dives | Superseded in-skill by rules/scenario-orchestrator.md and rules/scenario-routing.md |
References
references/ork-delta.md - House defaults and dated decisions rescued from retired tutorialsreferences/framework-comparison.md - Condensed framework decision matrix and use-case tablereferences/langgraph-implementation.md - LangGraph 1.2+ implementation of the multi-scenario orchestratorreferences/claude-code-instance-management.md - Running 3 parallel Claude Code instances for scenario demos
Key Decisions
| Decision | Recommendation |
|---|
| Single vs multi-agent | Single for focused tasks, multi for decomposable work |
| Max loop steps | 5-15 (prevent infinite loops) |
| Agent count | 3-8 specialists per workflow |
| Framework | Match to team expertise + use case |
| Topology | Task tool (star) for simple; Agent Teams (mesh) for complex |
| Scenario count | Always 3: simple, medium, complex |
Common Mistakes
- No step limit in agent loops (infinite loops)
- No memory management (context overflow)
- No error isolation in multi-agent (one failure crashes all)
- Note (CC 2.1.161): parallel tool calls now fail independently — a failed Bash no longer cancels siblings in the same batch. This caveat still applies at the agent-orchestration level, not to tool batches;
claude agents rows now show done/total for fanned-out work.
- Note (CC 2.1.157):
claude agents honors the agent field in settings.json for dispatched sessions; --agent <name> overrides it — pin the agent type explicitly when dispatching.
- Missing synthesis step (raw agent outputs not useful)
- Mixing frameworks in one project (complexity explosion)
- Using Agent Teams for simple sequential work (use Task tool)
- Sequential instead of parallel scenarios (defeats purpose)
Related Skills
ork:langgraph - LangGraph workflow patterns (supervisor, routing, state)function-calling - Tool definitions and executionork:task-dependency-patterns - Task management with Agent Teams workflow
Capability Details
react-loop
Keywords: react, reason, act, observe, loop, agent
Solves:
- Implement ReAct pattern
- Create reasoning loops
- Build iterative agents
plan-execute
Keywords: plan, execute, replan, multi-step, autonomous
Solves:
- Create plan then execute steps
- Implement replanning on failure
- Build goal-oriented agents
supervisor-coordination
Keywords: supervisor, route, coordinate, fan-out, fan-in, parallel
Solves:
- Route tasks to specialized agents
- Run agents in parallel
- Aggregate multi-agent results
agent-debate
Keywords: debate, conflict, resolution, arbitration, consensus
Solves:
- Resolve agent disagreements
- Implement LLM arbitration
- Handle conflicting outputs
result-synthesis
Keywords: synthesize, combine, aggregate, merge, summary
Solves:
- Combine outputs from multiple agents
- Create executive summaries
- Score confidence across findings
crewai-patterns
Keywords: crewai, crew, hierarchical, delegation, role-based, flows
Solves:
- Build role-based agent teams
- Implement hierarchical coordination
- Use Flows for event-driven orchestration
autogen-patterns
Keywords: autogen, microsoft, agent framework, teams, enterprise, a2a
Solves:
- Build enterprise agent systems
- Use AutoGen/SK merged framework
- Implement A2A protocol
framework-selection
Keywords: choose, compare, framework, decision, which, crewai, autogen, openai
Solves:
- Select appropriate framework
- Compare framework capabilities
- Match framework to requirements
scenario-orchestrator
Keywords: scenario, parallel, fan-out, difficulty, progressive, demo
Solves:
- Run skill across multiple difficulty levels
- Implement parallel scenario execution
- Aggregate cross-scenario results
scenario-routing
Keywords: route, synchronize, milestone, checkpoint, scaling
Solves:
- Route tasks by difficulty level
- Synchronize at milestones
- Scale inputs progressively
