agent-orchestration

Agent 编排

构建和协调 AI Agent 的全面模式——从单 Agent 推理循环到多 Agent 系统和框架选择。协调和多场景类别各有独立的规则文件，按需从 rules/ 加载；循环和框架教程位于上游来源（参见上游覆盖（不要重复陈述）），默认实践见 references/ork-delta.md。

CC 原生 /workflows（2.1.154）： Claude Code 现在内置了动态工作流——让 Claude 创建工作流，它就会在后台协调数十到数百个 Agent；使用 /workflows 查看运行情况。这与本文中的模式相辅相成：大规模、即发即忘的后台并行分发可使用 CC /workflows（之后再回来查看）；当不超过 8 个 Agent 必须通过共享内存（交接文件、网状消息传递）在单次技能调用中协调时，可使用下文有界的前台 Agent Teams / Task 工具模式。二者适用于不同规模，并非相互替代。

仅在确实受阻时询问（CC 2.1.154）： CC 现在只在确实无法自行决策时才会使用多项选择问题提示，而不会在已有足够上下文可以继续时提问。协调 Agent 时，不要因为可以依据现有上下文自行解决的 AskUserQuestion 而阻碍进展——只有遇到真正的分支点（不可逆操作、需求缺失）时才提问。这与 ork 的语音友好型决策指导相辅相成。

快速参考

类别	规则	影响	适用场景
Agent 循环	上游	高	ReAct 推理、规划并执行、自我纠正
多 Agent 协调	2	极高	监督者路由、Agent 辩论、结果综合
替代框架	上游	高	CrewAI 团队、AutoGen 团队、框架比较
多场景	2	中	并行场景编排、难度路由

总计：4 个类别共 4 条规则。 循环和框架教程已移至第一方来源；保留的默认实践见 references/ork-delta.md。

快速开始

# ReAct agent loop
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"

# Supervisor with fan-out/fan-in
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 循环

用于自主大模型推理的模式：ReAct（推理 + 行动）、带重新规划的规划并执行、自我纠正循环，以及滑动窗口内存管理。

关键决策： 最大步数 5-15，温度 0.3-0.7，内存窗口 10-20 条消息。

多 Agent 协调

并行分发/汇总、按依赖顺序进行监督者路由、冲突解决（基于置信度或由大模型仲裁）、结果综合，以及 CC Agent Teams（CC 2.1.33+ 中用于对等消息传递的网状拓扑）。

关键决策： 设置 3-8 个专业 Agent，并行执行互不依赖的 Agent。三种模式择一使用：简单任务使用 Agent 工具（星形拓扑），跨领域问题使用 Agent Teams（网状拓扑），大型后台并行分发（之后再回来查看）使用 Workflow。

替代框架

CrewAI 层级团队与 Flows（1.8+）、OpenAI Agents SDK 交接和护栏（0.12+）、Microsoft Agent Framework（AutoGen + SK 合并版）、适用于长周期编码任务的 GPT-5.2-Codex，以及灵活开源的 AG2。

关键决策： 根据团队专长和用例选择框架。状态机使用 LangGraph，基于角色的团队使用 CrewAI，交接工作流使用 OpenAI SDK，企业合规场景使用 MS Agent。

多场景

通过渐进式难度扩展（1x/3x/8x）、里程碑同步和跨场景结果汇总，让一项技能跨 3 个并行场景（简单/中等/复杂）运行。

关键决策： 自由运行并设置检查点，始终使用 3 个场景，按 1x/3x/8x 指数扩展，时间预算为 30s/90s/300s。

上游覆盖内容（请勿重复）

以下主题的本地教程已停用；请查阅一手资料，并仅在 references/ork-delta.md 中保留项目特有的差异。

主题	一手资料
ReAct / 计划并执行 / 自我纠正循环的实现	OpenAI 函数调用指南（https://platform.openai.com/docs/guides/function-calling）；LangGraph 教程（context7: /langchain-ai/langgraph）
扇出协调、结果综合样板代码和通用多 Agent 设计检查清单	Python asyncio 文档（https://docs.python.org/3/library/asyncio-task.html）；Anthropic《构建高效 Agent》（https://www.anthropic.com/research/building-effective-agents）；`ork:langgraph` 监督器模式
CrewAI（crews、Flows、MCP 工具、护栏）	CrewAI 文档（https://docs.crewai.com）；context7: /crewaiinc/crewai
OpenAI Agents SDK（交接、会话、护栏、MCP）	https://openai.github.io/openai-agents-python/ ；context7: /openai/openai-agents-python
Microsoft Agent Framework / AutoGen（团队、终止、A2A）	https://learn.microsoft.com/en-us/agent-framework/ ；context7: /microsoft/autogen
GPT-5.2-Codex 功能、定价、IDE 集成	OpenAI 模型文档（https://platform.openai.com/docs/models）
多场景状态机、架构和与技能无关的模板深入解析	已由技能内的 rules/scenario-orchestrator.md 和 rules/scenario-routing.md 取代

参考资料

• references/ork-delta.md - 从已停用教程中保留的项目默认设置和带日期的决策
• references/framework-comparison.md - 精简的框架决策矩阵和用例表
• references/langgraph-implementation.md - 多场景编排器的 LangGraph 1.2+ 实现
• references/claude-code-instance-management.md - 运行 3 个并行 Claude Code 实例进行场景演示

关键决策

决策	建议
单 Agent 与多 Agent	专注任务用单 Agent，可拆分工作用多 Agent
最大循环步数	5-15（防止无限循环）
Agent 数量	每个工作流配备 3-8 个专业 Agent
框架	根据团队专业知识和用例选择
拓扑	简单任务用 Agent 工具（星形）；复杂任务用 Agent Teams（网状）；大型后台扇出用工作流
场景数量	始终为 3 个：简单、中等、复杂

常见错误

• Agent 循环没有步数限制（无限循环）
• 没有内存管理（上下文溢出）
• 多 Agent 中没有错误隔离（一次失败导致全部崩溃）
  • 注意（CC 2.1.161）：现在并行 工具调用 会独立失败——Bash 失败不再取消同一批次中的其他调用。此注意事项仍适用于 Agent 编排层级，而非工具批次；claude agents 行现在会显示扇出工作的 done/total。
  • 注意（CC 2.1.157）：claude agents 会对已分派的会话采用 settings.json 中的 agent 字段；--agent <name> 可覆盖该设置——分派时请明确指定 Agent 类型。
• 缺少综合步骤（Agent 原始输出没有实用价值）
• 在一个项目中混用多个框架（复杂度激增）
• 对简单的顺序工作使用 Agent Teams（应使用 Agent 工具）
• 场景按顺序执行而非并行执行（违背初衷）

相关技能

• ork:langgraph - LangGraph 工作流模式（监督器、路由、状态）
• function-calling - 工具定义和执行
• ork:task-dependency-patterns - 使用 Agent Teams 工作流进行任务管理

功能详情

react-loop

关键词： react、reason、act、observe、loop、agent 解决的问题：

• 实现 ReAct 模式
• 创建推理循环
• 构建迭代式 Agent

plan-execute

关键词： plan、execute、replan、multi-step、autonomous 解决的问题：

• 先创建计划，再执行各步骤
• 实现失败时重新规划
• 构建目标导向型 Agent

supervisor-coordination

关键词： supervisor、route、coordinate、fan-out、fan-in、parallel 解决的问题：

• 将任务路由给专门的 Agent
• 并行运行 Agent
• 汇总多个 Agent 的结果

agent-debate

关键词： debate、conflict、resolution、arbitration、consensus 解决的问题：

• 解决 Agent 之间的分歧
• 实现大模型仲裁
• 处理相互冲突的输出

result-synthesis

关键词： synthesize、combine、aggregate、merge、summary 解决的问题：

• 合并多个 Agent 的输出
• 创建执行摘要
• 对各项发现的置信度进行评分

crewai-patterns

关键词： crewai、crew、hierarchical、delegation、role-based、flows 解决的问题：

• 构建基于角色的 Agent 团队
• 实现分层协调
• 使用 Flows 实现事件驱动编排

autogen-patterns

关键词： autogen、microsoft、agent framework、teams、enterprise、a2a 解决的问题：

• 构建企业级 Agent 系统
• 使用 AutoGen/SK 合并框架
• 实现 A2A 协议

framework-selection

关键词： choose、compare、framework、decision、which、crewai、autogen、openai 解决的问题：

• 选择合适的框架
• 比较框架功能
• 根据需求匹配框架

scenario-orchestrator

关键词： scenario、parallel、fan-out、difficulty、progressive、demo 解决的问题：

• 在多个难度级别下运行技能
• 实现并行场景执行
• 汇总跨场景结果

scenario-routing

关键词： route、synchronize、milestone、checkpoint、scaling 解决的问题：

• 按难度级别路由任务
• 在里程碑处同步
• 逐步扩展输入