Agent Roles & Hierarchy¶

Agents are the core building blocks of a synthetic organization. Each agent has an identity (role, name, personality), a position in the hierarchy (department, seniority, 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, personality, role, model, department. Set at creation time and never mutated.
• Runtime state (mutable-via-copy) -- execution status, current task, trust level, 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"
    level: senior
    department: "engineering"
    model:
      tier: "medium"
      priority: "balanced"
      min_context: 50000
    personality:
      openness: 0.5
      conscientiousness: 0.85
      decision_making: analytical
      verbosity: balanced
    autonomy_level: semi  # override company-wide level

Agent Configuration Fields¶

Seniority Levels¶

Seniority determines an agent's authority scope, typical model tier, and position in the delegation hierarchy:

Higher-seniority agents can delegate tasks to lower-seniority agents within their authority scope. The engine enforces that agents cannot assign work to peers or superiors.

Built-in Roles¶

SynthOrg ships with 50+ built-in roles organized by department:

Custom Roles¶

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

custom_roles:
  - role: "Compliance Officer"
    system_prompt_template: |
      You are a compliance officer responsible for ensuring
      all outputs meet regulatory requirements.
    skills:
      - "regulatory_analysis"
      - "policy_review"
    authority_level: "senior"

Departments & Reporting Lines¶

Departments group agents and define budget allocation and reporting structure:

departments:
  - name: "engineering"
    budget_percent: 60
    head_role: "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_role: "Product Manager"
  - name: "executive"
    budget_percent: 20
    head_role: "CEO"
    reporting_lines:
      - subordinate: "CTO"
        supervisor: "CEO"

Hierarchy Diagram¶

A typical startup hierarchy looks like this:

graph TD
    CEO["CEO<br/><small>c_suite</small>"]
    CTO["CTO<br/><small>c_suite</small>"]
    PM["Product Manager<br/><small>senior</small>"]
    DEV1["Full-Stack Developer<br/><small>senior</small>"]
    DEV2["Full-Stack Developer<br/><small>mid</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).

Personality Configuration¶

Agent personality is injected into the LLM system prompt and influences the agent's behavior, communication style, and decision-making.

Big Five Dimensions¶

Each dimension is a float from 0.0 to 1.0:

Behavioral Traits¶

Personality Presets¶

Rather than configuring each dimension manually, use a named preset:

These are 8 of the 22 built-in presets. See the library reference for the complete preset catalog.

Provide a full personality object for fine-grained control:

agents:
  - role: "CEO"
    personality:
      openness: 0.9
      conscientiousness: 0.7
      extraversion: 0.8
      agreeableness: 0.6
      stress_response: 0.8
      decision_making: directive
      collaboration: team
      verbosity: balanced
      conflict_approach: collaborate

Model Assignment¶

Models can be assigned to agents in two ways:

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

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

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

Templates as Starting Points¶

Templates pre-populate agents, departments, and workflows. You can customize 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 customization.

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 & Trust Policies -- autonomy levels and trust strategies
• Design: Agents -- full design specification for agents
• Design: Organization -- template system and hierarchy