Agent Role Decomposition Prompt for Complex Domains

System designers and platform engineers use this prompt when they need to break a complex domain—such as customer support, financial operations, or healthcare administration—into a set of well-scoped, non-overlapping agent roles. The prompt produces a role hierarchy with specialization rationale, interaction contracts, and completeness checks against domain coverage requirements. Use this before writing individual agent system prompts or building orchestration logic. The ideal user has deep domain knowledge and understands the operational workflows that agents will automate; they are not looking for a generic list of AI personas but a structured decomposition that prevents duplicated work, conflicting actions, and handoff failures in production multi-agent systems.

This prompt requires several concrete inputs to produce useful output. You must supply a [DOMAIN_DESCRIPTION] that captures the full scope of work, including task types, user intents, and operational boundaries. A [DOMAIN_TAXONOMY] of existing capability areas, service categories, or team responsibilities helps the model ground its decomposition in real organizational structure rather than inventing arbitrary divisions. Include [CONSTRAINTS] such as regulatory requirements, latency budgets, tool access limits, and human-review triggers that shape where boundaries must fall. Optionally provide [EXISTING_AGENT_ROLES] if you are extending or refactoring an existing multi-agent system rather than designing from scratch. The prompt works best when the domain has at least three distinct capability areas; for simpler domains with one or two clear functions, a single-agent system prompt is more appropriate and this decomposition step adds unnecessary complexity.

Do not use this prompt for simple single-agent workflows, domains with fewer than three distinct capability areas, or situations where the task routing logic is already well-understood and stable. Avoid using it as a one-time design exercise without follow-up validation—the output is a starting point for iteration, not a final architecture. After generating the role decomposition, you must validate it against real use cases, test for boundary conflicts using the sibling Agent Role Conflict Detection Prompt, and verify coverage completeness with the Agent Role Validation Prompt Against Use Cases. If the domain involves high-risk decisions in regulated industries, add a human review step before deploying any agent roles derived from this decomposition. The next step after this prompt is to take each generated role and feed it into the Agent Role Definition Prompt Template to produce a full role contract with scope, authority, and stop conditions.

This prompt template is designed to be placed directly into your orchestration layer or prompt management system. It instructs the model to act as a system architect, analyzing a provided domain description and producing a structured decomposition of agent roles. The output includes a role hierarchy, specialization rationale, and interaction contracts, which are essential for preventing duplicated work and handoff failures in multi-agent systems. Before using this template, ensure you have a clear, written description of the domain, its core workflows, and any known constraints.

textCopy
You are a principal system architect specializing in multi-agent AI systems. Your task is to decompose a complex domain into a set of well-scoped, specialized agent roles. The goal is to maximize separation of concerns, minimize overlapping responsibilities, and define clear interaction contracts between agents.

## Domain to Decompose
[DOMAIN_DESCRIPTION]

## Constraints
- [CONSTRAINT_1, e.g., 'Agents cannot share tool access']
- [CONSTRAINT_2, e.g., 'All customer-facing actions require a human approval agent']
- [CONSTRAINT_3]

## Output Schema
Produce a JSON object with the following structure:
{
  "domain_summary": "A one-paragraph summary of the domain as understood.",
  "role_hierarchy": [
    {
      "role_id": "string",
      "role_name": "string",
      "specialization_rationale": "Why this role is distinct and necessary.",
      "owned_capabilities": ["capability_1", "capability_2"],
      "explicit_exclusions": ["task_type_to_reject"],
      "interaction_contracts": [
        {
          "interacts_with": "role_id",
          "handoff_trigger": "Condition for initiating interaction.",
          "input_schema": { "field": "type_description" },
          "output_schema": { "field": "type_description" },
          "expected_preconditions": ["state_or_condition"],
          "guaranteed_postconditions": ["state_or_condition"]
        }
      ],
      "stop_conditions": ["condition_to_halt_immediately"]
    }
  ],
  "coverage_assessment": {
    "covered_workflows": ["workflow_from_domain"],
    "uncovered_workflows": ["workflow_with_no_owner"],
    "overlap_risks": ["description_of_potential_conflict"]
  }
}

## Instructions
1. Analyze [DOMAIN_DESCRIPTION] to identify distinct areas of responsibility.
2. Create a role for each distinct area. A role should be defined by what it owns, not by a single task.
3. For every role, explicitly state what it does NOT do to prevent overlap.
4. Define interaction contracts only between roles that must communicate. A contract must specify the trigger, the data passed, and the state guarantees.
5. After defining all roles, perform a coverage assessment to identify any gaps or overlaps in the proposed architecture.
6. If the domain is high-risk ([RISK_LEVEL] is 'high'), ensure every role that takes an action has a corresponding stop condition and a clear escalation path to a human or an arbiter agent.

To adapt this prompt, replace the square-bracket placeholders with your specific context. The [DOMAIN_DESCRIPTION] should be a dense, factual description of the problem space, such as 'enterprise IT incident management from alert to resolution.' The [CONSTRAINT] placeholders are critical for grounding the decomposition in your operational reality; common constraints include security policies, data residency requirements, or existing system integrations. The [RISK_LEVEL] input ('low', 'medium', 'high') controls the strictness of stop conditions and escalation paths in the generated roles. After generating the role set, you must validate the output against your known use cases before integrating it into an orchestrator. A common failure mode is generating roles that are logically distinct but share the same underlying tool or data source, which creates a hidden coupling that the coverage assessment might miss. Always review the explicit_exclusions and owned_capabilities for each role pair to ensure true separation of concerns.

This prompt is a design-time tool, not a runtime agent. It should be integrated into a system architect's workflow—typically a CLI, internal tool, or design review pipeline—where the output is consumed by a human who makes final decisions about agent boundaries. The prompt expects a domain description and optionally existing role definitions, and it returns a structured decomposition with roles, responsibilities, interaction contracts, and coverage analysis. Because the output shapes a multi-agent architecture, treat it as a design artifact that requires review before implementation.

Wire the prompt into a tool that collects [DOMAIN_DESCRIPTION], [EXISTING_ROLES] (if any), and [COVERAGE_REQUIREMENTS]. Before calling the model, validate that the domain description is substantive—reject inputs under 200 characters or those that are purely generic. After receiving the output, run a structural validator that checks: (1) every role has a unique identifier, (2) every responsibility maps to exactly one primary role, (3) interaction contracts reference valid role IDs, and (4) the coverage matrix addresses all required domain areas. Log any validation failures and surface them to the architect with the raw output for comparison. For high-stakes domains like healthcare or finance, add a mandatory human review step that requires explicit sign-off on role boundaries before any agent implementation begins.

Model choice matters here. Use a model with strong reasoning and structured output capabilities—GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro are appropriate. Set temperature low (0.0–0.2) to reduce variance in role boundary decisions. If the output fails structural validation, do not silently retry with the same input. Instead, feed the validation errors back into a correction prompt that includes the original output and the specific failures, asking the model to repair only the invalid sections. Limit correction attempts to two retries; if validation still fails, escalate to a human with the full failure log. Store every decomposition attempt, validation result, and human decision in a versioned design log so teams can trace why agent boundaries were drawn the way they were.