Agent Roles & Hierarchy¶

An agent is what executes a unit of work. Each has an identity (role, name), a position in the hierarchy (department, reporting line), and capabilities (model, tools, authority). This guide covers how to configure all of these.

How Agents Work¶

An agent's configuration is split into two layers:

• Config layer (frozen): identity, role, model, department. Set at creation time and never mutated.
• Runtime state (mutable-via-copy): execution status, current task, cost spent. Evolves during operation using model_copy(update=...).

This separation means you configure who an agent is in YAML, and the engine manages what the agent is doing at runtime.

Defining an Agent¶

Agents are defined in the agents list of your company configuration:

agents:
  - role: "Full-Stack Developer"
    name: "Alex"
    department: "engineering"
    model:
      priority: "balanced"
      min_context: 50000
    autonomy_level: semi  # override company-wide level

Agent Configuration Fields¶

Authority & Delegation¶

Authority is not a per-agent level. It follows from the agent's role and where that role sits in the organisation's reporting graph. Each role declares an optional reports_to (its supervisor's role name); the CEO role is the root (reports_to unset).

An agent can delegate work down its reporting chain to roles that (transitively) report to it, and cannot assign work to peers or superiors. The engine resolves "who outranks whom" from reporting depth (see HR & Agent Lifecycle), not from a seniority attribute. A role's model capability is a separate axis, driven by the work's capability demand rather than org position.

Built-in Roles¶

SynthOrg ships with 30+ built-in roles organised by department:

Red Team and Completion Reviewer judge finished work rather than performing it, so a holder of either reaches every project instead of the one team it is staffed on, and the matching completion gate selects a holder per review. They are assigned like any other role through the operator REST path covered in Agent Management; the agent MCP surface cannot grant or change a gate role, so an agent cannot appoint its own judge. Staff at least a Completion Reviewer: without one, each finished task parks awaiting a reviewer instead of being waved through. See Built-in Roles.

Custom Roles¶

Define custom roles when the built-in catalog does not cover your needs:

custom_roles:
  - name: "Compliance Officer"
    department: "operations"
    system_prompt_template: |
      You are a compliance officer responsible for ensuring
      all outputs meet regulatory requirements.
    required_skills:
      - "regulatory_analysis"
      - "policy_review"
    reports_to: "Chief Compliance Officer"

Departments & Reporting Lines¶

Departments group agents and define budget allocation and reporting structure:

departments:
  - name: "engineering"
    budget_percent: 60
    head: "CTO"
    reporting_lines:
      - subordinate: "Full-Stack Developer"
        subordinate_id: "fullstack-senior"
        supervisor: "CTO"
      - subordinate: "Full-Stack Developer"
        subordinate_id: "fullstack-mid"
        supervisor: "CTO"
  - name: "product"
    budget_percent: 20
    head: "Product Manager"
  - name: "executive"
    budget_percent: 20
    head: "CEO"
    reporting_lines:
      - subordinate: "CTO"
        supervisor: "CEO"

Hierarchy Diagram¶

A typical startup hierarchy looks like this:

graph TD
    CEO["CEO<br/><small>executive</small>"]
    CTO["CTO<br/><small>engineering</small>"]
    PM["Product Manager<br/><small>product</small>"]
    DEV1["Full-Stack Developer<br/><small>engineering</small>"]
    DEV2["Full-Stack Developer<br/><small>engineering</small>"]

    CEO --> CTO
    CEO --> PM
    CTO --> DEV1
    CTO --> DEV2

Department Fields¶

Use subordinate_id in reporting lines when you have multiple agents with the same role (matches the agent's merge_id when using templates).

How Agent Output Reads¶

How an agent writes is not configured per agent. The organisation sets one house writing style, scoped org-wide with per-role and per-department overrides, and a deterministic guardrail enforces the hard rules at the boundary where work is kept or sent. See Output Style Policy.

Model Assignment¶

Models can be assigned to agents in two ways:

agents:
  - role: "Full-Stack Developer"
    model: "medium"

agents:
  - role: "CEO"
    model:
      priority: "quality" # quality, cost, balanced, speed
      min_context: 100000

When no model is specified, the routing strategy selects one based on the agent's role and the task type.

Templates as Starting Points¶

Templates pre-populate agents, departments, and workflows. You can customise any aspect after selecting a template:

Templates support inheritance via the extends keyword (deep merge up to 10 levels) and variables with Jinja2 placeholders for customisation.

Workflow Handoffs & Escalation¶

Handoffs¶

Define automatic handoffs between departments when specific conditions are met:

workflow_handoffs:
  - from_department: "engineering"
    to_department: "product"
    trigger: "Feature implementation completed for product review"
    artifacts:
      - "pull_request"
      - "release_notes"

Escalation Paths¶

Define escalation routes for blockers or conflicts:

escalation_paths:
  - from_department: "engineering"
    to_department: "executive"
    condition: "Technical blocker requiring executive decision"
    priority_boost: 1
  - from_department: "product"
    to_department: "executive"
    condition: "Scope or priority conflict needing CEO resolution"
    priority_boost: 1

The priority_boost field increases the priority of escalated tasks (0 = no change, 1 = one level up, etc.).

See Also¶

• Company Configuration: full configuration reference
• Budget & Cost Control: per-agent budgets and cost tracking
• Security Policies: autonomy levels and tool permissions
• Design: Agents: full design specification for agents
• Design: Organisation: template system and hierarchy