agent-designer

Agent Designer — 多 Agent 系统架构

使用三个确定性工具设计、生成 schema 并评估多 Agent 系统。脚本本身就是工作流，不要在能用规划器根据需求打分的情况下凭感觉自由设计架构。

适用场景

• 根据需求设计新的多 Agent 系统（模式选择、角色、通信方式）
• 从普通工具描述生成可直接用于模型服务商的工具 schema（Anthropic 与 OpenAI 格式）
• 评估执行日志：成功率、延迟分布、成本、瓶颈

不适用场景： Claude Code Workflow 工具自动化 → workflow-builder；单 Agent 工作流脚手架 → agent-workflow-designer；运行时的多 Agent 扇出 → agenthub。

模式决策表

选择	适用时机	注意事项
单 Agent	一个有边界的任务，工具少于约 5 个	不要添加不需要的 Agent
Supervisor	中心化拆解，专家向其汇报	Supervisor 容易成为瓶颈
Pipeline	严格顺序的阶段，阶段间交接	顺序僵化；最慢的阶段限制整体吞吐
Hierarchical	多层组织结构，Agent 超过约 8 个	每一层都有通信开销
Swarm	并行对等节点，容错优先于可预测性	难以调试；需要共识规则

规划器会以确定性方式进行评分——请运行它，而不是凭感觉选择。

工作流

所有路径均相对于本 skill 文件夹。每一步输出的 JSON 都是下一步的设计输入。

1. 设计架构

编写需求 JSON（复制 assets/sample_system_requirements.json，字段包括：goal、tasks[]、constraints{max_response_time, budget_per_task, concurrent_tasks}、team_size）：

python3 agent_planner.py requirements.json --format json -o arch

输出 arch.json，包含 architecture_design（模式、Agent、通信链路）、mermaid_diagram 和 implementation_roadmap。读取 architecture_design.pattern 和各 Agent 的角色列表，并向用户展示 mermaid 图。

2. 生成工具 schema

用普通 JSON 描述每个 Agent 的工具（复制 assets/sample_tool_descriptions.json），然后执行：

python3 tool_schema_generator.py tool_descriptions.json --validate -o tools

输出 tools.json（包含 tool_schemas 和 validation_summary），以及针对特定服务商的 tools_anthropic.json / tools_openai.json。关卡：每个工具都必须输出 ✓ Valid。 在继续之前修复所有无效 schema——切勿把未经验证的 schema 交给 Agent。

3. 评估执行日志

系统运行后（或针对 assets/sample_execution_logs.json 进行试运行）：

python3 agent_evaluator.py execution_logs.json --detailed -o eval

输出 eval.json，包含 summary、agent_metrics、bottleneck_analysis、error_analysis、cost_breakdown、sla_compliance 和 optimization_recommendations，并拆分输出为 eval_errors.json 与 eval_recommendations.json。

4. 验证闭环

只有满足以下全部条件，设计才算完成：

1. tool_schema_generator.py --validate 报告 0 个无效 schema。
2. 对试点运行执行 agent_evaluator.py，报告 0 个严重问题（发现问题时工具会输出 CRITICAL: N critical issues）。如果 N > 0，应用 eval_recommendations.json 中的首要建议，重新运行试点，并再次评估。
3. 将你的输出与 expected_outputs/ 进行比对，确认你所使用的 schema 结构没有发生偏移。

参考资料

• references/agent_architecture_patterns.md — 深入讲解各模式的权衡
• references/tool_design_best_practices.md — schema、幂等性与错误处理规则
• references/evaluation_methodology.md — 评估器实现的指标定义