agent-designer

Agent Designer — マルチエージェントシステムのアーキテクチャ

3 つの決定論的なツールを使って、マルチエージェントシステムを設計し、スキーマを生成して、評価します。スクリプトがワークフローです。プランナーが要件に基づいてスコアを算出できるときに、アーキテクチャを即興で作らないでください。

使用する場面

• 要件に基づいて新しいマルチエージェントシステムを設計するとき（パターンの選択、役割、通信）
• プレーンなツールの説明から、プロバイダー対応のツールスキーマ（Anthropic ＋ OpenAI 形式）を生成するとき
• 実行ログを評価するとき：成功率、レイテンシ分布、コスト、ボトルネック

使用しない場面： Claude Code の Workflow ツールによる自動化 → workflow-builder；シングルエージェントのワークフローのひな形 → agent-workflow-designer；実行時のマルチエージェントのファンアウト → agenthub

パターン選択表

選択肢	使用する場面	注意点
シングルエージェント	範囲が限定されたタスクが 1 つ、ツール数が約 5 未満	必要のないエージェントを追加しないでください
スーパーバイザー	中央でタスクを分解し、専門エージェントが結果を報告する	スーパーバイザーがボトルネックになります
パイプライン	引き継ぎを伴う、厳密に順序が決まった段階	順序が固定され、最も遅い段階がスループットを制限します
階層型	組織に複数の階層があり、エージェント数が約 8 を超える	階層ごとに通信のオーバーヘッドが発生します
スウォーム	並列に動く対等なエージェントで、予測可能性より耐障害性を重視する	デバッグが困難で、合意形成のルールが必要です

プランナーはこのスコアリングを決定論的に適用します。感覚で選ぶのではなく、実行してください。

ワークフロー

すべてのパスはこのスキルフォルダーからの相対パスです。各ステップの 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

architecture_design（パターン、エージェント、通信リンク）、mermaid_diagram、implementation_roadmap を含む arch.json が出力されます。architecture_design.pattern と、エージェントごとの役割一覧を確認し、Mermaid ダイアグラムをユーザーに提示してください。

2. ツールスキーマを生成する

各エージェントのツールをプレーンな JSON で記述し（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 と表示される必要があります。 無効なスキーマがあれば、次に進む前に修正してください。検証されていないスキーマをエージェントに渡してはいけません。

3. 実行ログを評価する

システムの実行後（またはドライランでは assets/sample_execution_logs.json を使用します）。

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

summary、agent_metrics、bottleneck_analysis、error_analysis、cost_breakdown、sla_compliance、optimization_recommendations を含む eval.json と、分割ファイル（eval_errors.json、eval_recommendations.json）が出力されます。

4. 検証ループ

次の条件を満たすまで、設計は完了ではありません。

1. tool_schema_generator.py --validate の無効なスキーマ数が 0 であることを確認します。
2. パイロット実行で agent_evaluator.py が 重大な問題 0 件 を報告すること（問題が見つかると、ツールには CRITICAL: N critical issues と表示されます）。N > 0 の場合は、eval_recommendations.json の最上位の項目を適用し、パイロットを再実行して、もう一度評価してください。
3. 出力を expected_outputs/ と比較し、使用しているスキーマの構造に変更がないことを確認します。

参考資料

• references/agent_architecture_patterns.md — パターンごとのトレードオフの詳細
• references/tool_design_best_practices.md — スキーマ、冪等性、エラー処理に関するルール
• references/evaluation_methodology.md — 評価ツールが実装する指標の定義