agent-designer

# Agent Designer - Multi-Agent System Architecture A toolkit for designing, architecting, and evaluating multi-agent systems. It provides structured approaches to agent architecture patterns, tool design principles, communication strategies, and performance evaluation frameworks for building robust, scalable AI agent systems. ## Core Capabilities - **Architecture pattern selection** — single agent, supervisor, swarm, hierarchical, and pipeline patterns with use-case fit and trade-offs. - **Agent role definition** — identity, responsibilities, capabilities, interfaces, and constraints; common archetypes (coordinator, specialist, interface, monitor). - **Tool design** — schema design, error handling, idempotency requirements, and validation rules. - **Communication & orchestration** — message passing, shared state, event-driven architecture; centralized, decentralized, and hybrid orchestration. - **Guardrails & safety** — input validation, output filtering, and human-in-the-loop checkpoints. - **Evaluation frameworks** — task completion, quality, cost, and latency metrics with bottleneck analysis. - **Memory, scaling & failure handling** — short/long/shared memory, horizontal/vertical scaling, retries, fallbacks, and circuit breakers. ## When to Use - Building AI agent systems or designing multi-agent workflows. - Creating tool schemas for OpenAI function calling or Anthropic tool use. - Selecting an architecture pattern for a new system. - Evaluating agent performance from execution logs. ## Clarify First Before designing the system, confirm these inputs. If any is unknown or vague, ASK — do not assume: - [ ] **System goal & scale** — the task the agents perform and expected load (drives which architecture pattern: single, supervisor, swarm, hierarchical, or pipeline) - [ ] **Tool protocol target** — OpenAI function calling vs Anthropic tool use (sets the schema format `tool_schema_generator.py` emits) - [ ] **Optimization priority** — cost, latency, or quality (determines agent roles, model tiers, and which metrics the evaluator weights) Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact. ## Tools | Tool | Purpose | Command | |------|---------|---------| | `agent_planner.py` | Design architecture from requirements (pattern, roles, topology, Mermaid diagram, roadmap) | `python agent_planner.py requirements.json -o my_system --format both` | | `agent_evaluator.py` | Evaluate performance from execution logs (success, cost, latency, bottlenecks) | `python agent_evaluator.py execution_logs.json -o perf_report --format both --detailed` | | `tool_schema_generator.py` | Generate OpenAI/Anthropic tool schemas with validation | `python tool_schema_generator.py tools.json -o my_tools --format both --validate` | ## References Load the reference that matches the task — keep this file lean and pull detail on demand: - **[references/core-capabilities.md](references/core-capabilities.md)** — the full Core Capabilities catalog (architecture patterns, role definition, tool design, communication, guardrails, evaluation, orchestration, memory, scaling, failure handling) plus Implementation Guidelines. Read when designing any part of a system. - **[references/agent_architecture_patterns.md](references/agent_architecture_patterns.md)** — deep catalog of architecture patterns with structure diagrams, characteristics, use cases, and implementation considerations. Read when selecting or comparing patterns. - **[references/tool_design_best_practices.md](references/tool_design_best_practices.md)** — best practices for designing tools in multi-agent systems (single responsibility, idempotency, composability, schemas, error handling). Read when designing tools or schemas. - **[references/evaluation_methodology.md](references/evaluation_methodology.md)** — full evaluation methodology across performance, reliability, cost, and satisfaction dimensions. Read when planning evaluation or interpreting reports. - **[references/troubleshooting-and-tool-reference.md](references/troubleshooting-and-tool-reference.md)** — troubleshooting table, success criteria, and the complete CLI parameter reference for all three scripts. Read when a tool misbehaves or you need full command options. ## Scope & Limitations **Covers:** - Multi-agent architecture pattern selection (single agent, supervisor, swarm, hierarchical, pipeline) - Agent role definition with responsibilities, capabilities, tools, and communication interfaces - Tool schema generation in OpenAI and Anthropic formats with validation rules and error handling - Performance evaluation from execution logs including bottleneck analysis and optimization recommendations **Does NOT cover:** - Runtime agent orchestration or execution engines (see `engineering/agent-workflow-designer` for workflow execution) - LLM prompt engineering or system prompt design (see `engineering/prompt-engineer-toolkit`) - MCP server implementation or protocol details (see `engineering/mcp-server-builder`) - Self-improving agent feedback loops or autonomous learning (see `engineering/self-improving-agent`) ## Integration Points | Skill | Integration | Data Flow | |-------|-------------|-----------| | `engineering/agent-workflow-designer` | Workflow definitions consume architecture designs from Agent Designer | Agent roles and communication topology feed into workflow step definitions | | `engineering/prompt-engineer-toolkit` | System prompts are crafted per agent role defined by Agent Designer | Agent role specifications and responsibilities inform prompt structure and constraints | | `engineering/mcp-server-builder` | Tool schemas generated here map to MCP server tool implementations | `tool_schema_generator.py` output provides the schema contract that MCP servers implement | | `engineering/self-improving-agent` | Evaluation reports feed into self-improvement loops | `agent_evaluator.py` bottleneck analysis drives autonomous optimization decisions | | `engineering/observability-designer` | Monitoring architecture aligns with agent topology and communication links | Agent definitions and communication patterns define what to instrument and alert on | | `engineering/agent-protocol` | Protocol standards govern inter-agent message formats designed here | Communication topology patterns must comply with agent protocol specifications |