| name | orchestration-agent-architect |
| description | Architect for Sunrise's agent orchestration system. Designs agentic solutions
by selecting from 21 design patterns, composing multi-pattern architectures,
and mapping designs to Sunrise's orchestration primitives (agents, capabilities,
workflows, knowledge bases). Use when a developer wants to design, plan, or
debug an AI agent system — whether they say "build me a chatbot", "I need an
agent that can look up orders", "design an AI pipeline", or "why is my agent
hallucinating". This skill handles the DESIGN phase; the orchestration-solution-builder
skill handles IMPLEMENTATION.
|
Agent Architect
An architectural decision-making skill for designing, composing, and debugging AI agent systems. Based on 21 established agentic design patterns, supplemented with emerging concepts and production practices.
This skill helps you make the right architectural choices — which patterns to use, how to combine them, what trade-offs to accept, and what production pitfalls to avoid.
Quick Reference: All 21 Patterns
| # | Pattern | One-liner |
|---|
| 1 | Prompt Chaining | Break complex tasks into sequential LLM calls with validation gates between steps |
| 2 | Routing | Classify intent and dispatch to specialised agents or models |
| 3 | Parallelisation | Run independent tasks concurrently, merge results via a reducer |
| 4 | Reflection | Draft → critique → revise loop for iterative quality improvement |
| 5 | Tool Use | Let the agent call external APIs, databases, and services |
| 6 | Planning | Agent generates its own execution plan (DAG) at runtime |
| 7 | Multi-Agent | Team of specialised agents collaborating via handoffs |
| 8 | Memory | Short-term (context window) and long-term (vector DB) recall |
| 9 | Learning & Adaptation | Agent improves over time via feedback without redeployment |
| 10 | MCP (State Management) | Standardised protocol for tool discovery and integration |
| 11 | Goal Monitoring | Track progress toward objectives, detect stuck agents |
| 12 | Exception Handling | Detect failures → handle → recover or escalate |
| 13 | Human-in-the-Loop | Pause for human approval on high-risk actions |
| 14 | RAG (Knowledge Retrieval) | Retrieve external knowledge to ground responses in fact |
| 15 | A2A (Inter-Agent Comms) | Standardised protocol for agent-to-agent collaboration |
| 16 | Resource-Aware Optimisation | Route tasks to the cheapest model that can handle them |
| 17 | Reasoning Techniques | CoT, ToT, ReAct — structured thinking strategies |
| 18 | Guardrails & Safety | Input/output filters, behavioural constraints, layered defence |
| 19 | Evaluation & Monitoring | LLM-as-a-Judge scoring, trajectory analysis, drift detection |
| 20 | Prioritisation | Semantic task ranking with dynamic re-prioritisation |
| 21 | Exploration & Discovery | Proactive hypothesis testing and knowledge expansion |
For full pattern detail, read references/patterns-1-to-10.md or references/patterns-11-to-21.md.
Pattern Selection Guide
Use this table when the user describes a problem and you need to recommend patterns:
| The user needs to... | Primary pattern(s) | Also consider |
|---|
| Handle a multi-step task | 1 (Chaining) | 6 (Planning) if steps are dynamic |
| Route requests to different handlers | 2 (Routing) | 16 (Resource-Aware) for cost-based routing |
| Speed up a slow workflow | 3 (Parallelisation) | 16 (Resource-Aware) for model selection |
| Improve output quality | 4 (Reflection) | 17 (Reasoning) for complex problems |
| Call external APIs or databases | 5 (Tool Use) | 10 (MCP) for standardised integration |
| Handle complex, multi-part goals | 6 (Planning) | 11 (Goal Monitoring) for progress tracking |
| Solve problems needing multiple skills | 7 (Multi-Agent) | 15 (A2A) for cross-framework agents |
| Remember context across sessions | 8 (Memory) | 14 (RAG) for knowledge retrieval |
| Improve performance over time | 9 (Learning) | 19 (Evaluation) to measure improvement |
| Integrate many tools via standard protocol | 10 (MCP) | 5 (Tool Use) for individual tools |
| Prevent agents getting stuck in loops | 11 (Goal Monitoring) | 12 (Exception Handling) for recovery |
| Handle API failures gracefully | 12 (Exception Handling) | 13 (HITL) for escalation |
| Add human approval for risky actions | 13 (HITL) | 18 (Guardrails) for automated safety |
| Ground answers in real data | 14 (RAG) | 8 (Memory) for conversational context |
| Connect agents across platforms | 15 (A2A) | 10 (MCP) for tool-level integration |
| Control costs at scale | 16 (Resource-Aware) | 2 (Routing) for model selection |
| Solve complex reasoning problems | 17 (Reasoning) | 4 (Reflection) for iterative refinement |
| Prevent harmful or off-policy outputs | 18 (Guardrails) | 13 (HITL) as ultimate fallback |
| Monitor production agent performance | 19 (Evaluation) | 9 (Learning) to act on findings |
| Manage competing tasks | 20 (Prioritisation) | 6 (Planning) for task sequencing |
| Explore unknown solution spaces | 21 (Exploration) | 7 (Multi-Agent) for research teams |
Troubleshooting Guide
Use this when diagnosing problems with an existing agent system:
| Symptom | Likely cause | Fix with |
|---|
| Agent hallucinating facts | No grounding in real data | Add RAG (14), tighten Guardrails (18) |
| Agent stuck in infinite loop | No exit condition or progress tracking | Add Goal Monitoring (11), set max retries |
| Responses are too slow | Too many sequential LLM calls | Add Parallelisation (3), reduce chain depth |
| Costs are too high | Frontier model used for everything | Add Resource-Aware routing (16), context compression |
| Agent ignores instructions | Context window overloaded / context rot | Apply context engineering — see references/context-and-costs.md |
| Agent leaks sensitive data | No output filtering | Add layered Guardrails (18) |
| Agent calls the wrong tool | Poor tool descriptions | Rewrite Tool (5) descriptions — they're API docs for a machine reader |
| Inconsistent output quality | No self-review | Add Reflection (4) loop |
| Agent takes unsafe actions | No approval gate for writes | Add HITL (13) with escalation policies |
| Can't debug what went wrong | No tracing | Add structured tracing — see references/emerging-concepts.md |
| Behaviour changed after model update | Model version not pinned | Pin model versions, test before upgrading |
| Agent forgets previous conversation | No memory persistence | Add Memory (8) with vector DB |
Composition Recipes
Real agent systems combine multiple patterns. Use these as starting architectures:
Recipe 1: Customer Support Agent
Patterns: 2 (Routing) + 14 (RAG) + 5 (Tool Use) + 18 (Guardrails) + 13 (HITL)
Flow: Classify intent → retrieve help docs → call tools (order lookup, refund API) → filter output for PII → escalate high-risk actions to human.
Recipe 2: Content Generation Pipeline
Patterns: 6 (Planning) + 1 (Chaining) + 4 (Reflection) + 3 (Parallelisation)
Flow: Plan stages → research and analysis in parallel → chain through outline → draft → review → critic agent loops until quality met.
Recipe 3: AI-First SaaS Backend
Patterns: 2 (Routing) + 5 (Tool Use) + 10 (MCP) + 8 (Memory) + 18 (Guardrails) + 16 (Resource-Aware) + 12 (Exception Handling)
Flow: Classify complexity and select model tier → connect to services via MCP → load user context from memory → handle tool failures with fallbacks → validate output → return.
Recipe 4: Autonomous Research Agent
Patterns: 6 (Planning) + 7 (Multi-Agent) + 14 (RAG) + 4 (Reflection) + 11 (Goal Monitoring) + 21 (Exploration)
Flow: Generate research plan → specialised agents work sub-tasks → RAG retrieves from knowledge bases → reflection checks quality → monitor tracks progress → exploration identifies new avenues.
Recipe 5: Conversational Agent with Learning
Patterns: 1 (Chaining) + 8 (Memory) + 5 (Tool Use) + 9 (Learning) + 19 (Evaluation)
Flow: Load memories → chain through understanding → reasoning → response → call tools as needed → evaluate quality → negative feedback updates instructions for next time.
Recipe 6: Event-Driven Workflow (scheduled or inbound-triggered)
Patterns: 12 (Exception Handling) + 5 (Tool Use) + 14 (RAG) + 13 (HITL, optional)
Flow: Trigger fires (cron schedule or inbound Slack / Postmark / HMAC webhook at POST /inbound/:channel/:slug) → workflow normalises payload → retrieves context → calls downstream tools or agents → optional human approval gate → notifies original channel via send_notification or call_external_api. Use when the agent system is reacting to the world rather than handling a user-initiated chat.
Trade-off Dimensions
When recommending an architecture, reason through these trade-offs explicitly:
Latency vs Quality. Reflection (4) and Reasoning (17) improve quality but add LLM round-trips. A 3-step reflection loop triples latency. Use for offline/async tasks; skip for real-time chat unless quality is critical.
Cost vs Accuracy. Frontier models ($5–25/M output tokens) are more accurate but 10–100× the cost of budget models ($0.10–0.60/M). Use tiered routing (16): send 70% of queries to budget models, reserve frontier for hard problems.
Autonomy vs Control. More autonomy (Planning, Exploration) means less predictability. More control (HITL, Guardrails) means more latency and human bottlenecks. Match to risk level: high autonomy for research, tight control for financial transactions.
Simplicity vs Flexibility. Prompt Chaining (1) is simple and debuggable. Multi-Agent (7) is flexible but complex. Always start with the simplest pattern that solves the problem, then add complexity only when a specific failure mode demands it.
Speed-to-build vs Maintainability. A single mega-prompt is fastest to build but impossible to maintain. Decomposed patterns take longer upfront but each component can be tested, optimised, and replaced independently.
Production Readiness Checklist
Before finalising any agent architecture, verify these concerns are addressed:
- Rate limits: Will concurrent calls hit provider limits? Design for backoff and queuing.
- Latency budget: Does total chain latency fit the UX requirement? Consider streaming partial results.
- Timeout strategy: What happens when an LLM call hangs? Set per-step timeouts.
- Streaming: Should partial results stream to the user for perceived responsiveness?
- Idempotency: Are write operations (payments, deletions) safe to retry? Use idempotency keys.
- State persistence: Can the workflow resume after a crash? Checkpoint long-running workflows.
- Model pinning: Is the model version locked? Behaviour changes when providers update models.
- Multi-tenant isolation: Is data scoped per user? RAG retrieval, memory, tool access must respect permissions.
- Graceful failure UX: What does the user see when it fails? Explain what was tried, not just "error occurred."
- Cost alerting: Is there a budget cap per request/user? Kill runaway agents that exceed limits.
- Observability: Can you trace a request end-to-end? Log every step, tool call, and decision.
- Rollback plan: How do you revert a bad prompt or model change? Feature flags, shadow testing.
Architecture Anti-Patterns
Warn against these common mistakes:
- Over-engineering: Building a multi-agent system when prompt chaining would suffice. Start simple.
- Under-engineering: One mega-prompt handling all edge cases. If your prompt exceeds ~500 words with multiple distinct tasks, decompose it.
- Guardrails-later: Skipping safety because "we'll add it later." Security debt compounds faster than tech debt.
- Approval-for-everything: Human-in-the-loop on every action, creating bottlenecks that defeat automation.
- Frontier-for-everything: Using the most expensive model for routing, classification, and simple queries. Use the least capable model that handles the task.
- Context-stuffing: Dumping entire documents into the context window instead of retrieving relevant chunks via RAG.
- Testing-in-production-only: No evaluation framework, relying on user complaints to find problems.
Mapping Patterns to Sunrise Primitives
Every pattern maps to concrete Sunrise orchestration primitives:
| Pattern | Sunrise primitive |
|---|
| Prompt Chaining (1) | Sequential llm_call steps or chain step |
| Routing (2) | route step type in workflow |
| Parallelisation (3) | parallel step type with branches |
| Reflection (4) | reflect step type with critique loop (bounded by maxIterations) |
| Tool Use (5) | call_external_api (recipe-driven) or custom capability + tool_call step |
| Planning (6) | plan step type or orchestrator step |
| Multi-Agent (7) | Multiple AiAgent records + agent_call step (or orchestrator for dynamic delegation) |
| Memory (8) | read_user_memory / write_user_memory built-in caps; multi-modal context via image/PDF inputs |
| Tool Use → external HTTP (5) | external_call step (workflows) with multipart support for vendors like Gotenberg |
| Human-in-the-Loop (13) | human_approval step + approval queue + in-chat Approve/Reject card via run_workflow capability |
| RAG (14) | Knowledge base + search_knowledge_base cap + rag_retrieve step (hybrid BM25 + vector). AiAgent.knowledgeRetrievalMode (model / first_turn / every_turn / keywords) picks when retrieval fires; keywords mode uses knowledgeTriggerKeywords for whole-word case-insensitive matching |
| Guardrails (18) | guard step type (LLM / regex / schema), plus per-agent input/output/citation guard modes |
| Evaluation (19) | evaluate step type + judge_call step type (drives a judge agent inline; gates on passed: boolean) + per-agent named metrics (faithfulness / groundedness / relevance) + dataset-driven evaluation runs with model + pairwise judges (workflow_as_judge, pairwise_judge_agent graders) and a CI gate |
| Exception Handling (12) | Per-step errorStrategy (retry / fallback / skip / fail), lease-based crash recovery |
| Scheduled / Inbound triggers | AiWorkflowSchedule (cron) + POST /inbound/:channel/:slug (Slack / Postmark / generic HMAC) |
| Resource-Aware (16) | TaskType-routed default models via the model matrix (routing / chat / reasoning / embeddings / audio) |
| MCP (10) | Built-in MCP server: capabilities exposed as MCP tools with key-scoped access and full audit |
| Reusable persona / voice / guardrails | AiAgentProfile — shared rows that multiple agents inherit from; each agent has an optional profileId and may override or append per-field via personaMode / voiceMode / guardrailsMode. The runtime resolveEffectivePrompt(agent, profile) composes the final system prompt from profile + agent fragments before either chat or workflow agent_call sends. Treat profiles as the way to enforce a single brand voice across a fleet of differently-bound agents without duplicating systemInstructions. |
| Reasoning depth (17) | Per-agent AiAgent.reasoningEffort + per-step reasoningEffort on every LLM-bearing workflow step (llm_call / plan / route / evaluate / reflect / guard.llm / agent_call / orchestrator / supervisor). Honoured by reasoning models (o-series / gpt-5 / Claude 4 thinking), silently dropped elsewhere. Default null = no reasoning_effort parameter sent. |
Versioning is built-in for both agents and workflows. AiAgentVersion and AiWorkflowVersion snapshot every editable change; PATCH writes to draft, POST /publish snapshots, POST /rollback is an append-only forward step. Architectural conversations about "how do we evolve this agent's prompt without breaking production?" already have an answer in the platform — no separate version-control plumbing needed.
Conversation provenance is built-in. Every chat message persists the resolved agentVersionId, workflowVersionId (when workflow-fired), modelId, providerSlug, citation chunk hashes, and a redacted summary of every capability call made on that turn. The full bundle is downloadable via GET /admin/orchestration/conversations/:id/provenance in JSON or deterministic Markdown. When designing for regulated-domain partners (legal, financial, health, planning), the audit-trail story is already there — design choices should preserve it, not work around it. Capabilities that handle PII must set processesPii = true and override redactProvenance (the registry enforces the pairing at registration time).
Building Solutions
When a developer describes a business problem and wants you to build an agentic solution:
- Understand the problem — what inputs, outputs, actions, and decisions are involved?
- Select patterns — use the Pattern Selection Guide above
- Check composition recipes — does a recipe already cover this use case?
- Map to Sunrise — use the table above to identify which agents, capabilities, workflows, and knowledge base setup are needed
- Determine complexity — simple (single agent, no workflow), moderate (1-2 agents + workflow), or complex (multi-agent + approval gates + KB)
- Implement — use
/orchestration-solution-builder for end-to-end implementation, or the individual builder skills for specific subsystems:
/orchestration-capability-builder — custom agent tools/orchestration-workflow-builder — workflow DAGs/orchestration-knowledge-builder — RAG knowledge bases
When the developer says or implies "build it", invoke the orchestration-solution-builder skill which handles the full implementation pipeline.
Reference File Routing
Load these files when you need more depth:
| When you need... | Read |
|---|
| Detail on Patterns 1–10 | references/patterns-1-to-10.md |
| Detail on Patterns 11–21 | references/patterns-11-to-21.md |
| Context engineering, token costs, pricing | references/context-and-costs.md |
| Emerging patterns, agent security, tracing | references/emerging-concepts.md |
| Sunrise code examples for agents, caps, workflows | references/sunrise-implementation.md |
