HR & Agent Lifecycle¶

This page covers the operational lifecycle of every agent in a synthetic organisation, from hiring through performance tracking, evolution, and offboarding. The HR subsystem is how SynthOrg simulates a workforce: closed-loop hiring when new skills are needed, performance-driven pruning when agents fail to deliver, and pluggable evolution for agents that need to adapt their identity.

See Agents for the identity layer (personality, skills, tool namespaces, identity versioning).

Authority: role + reporting graph¶

Authority is not a scalar rank. It derives from an agent's role and its position in the organisation's reporting graph. Each Role declares an optional reports_to (the role name of its supervisor); the CEO role sits at the root with reports_to = None.

core/authority.py computes authority from that graph:

• role_depth(role): distance from the CEO root (CEO is 0, its reports 1, and so on).
• reporting_chain(role): the ordered chain of supervisors up to the root.
• outranks(a, b) / compare_authority(a, b): whether role a is a (transitive) superior of role b, and a sign-comparison by reporting depth.

Consumers that need "who is more senior" (conflict resolution, owner selection, department-head detection) compare reporting depth via these helpers rather than reading a per-agent level. A role's model tier is a separate, independent axis driven by the work's capability demand (see Providers), not by org position.

Role Catalog¶

The role catalog is extensible; users can add custom roles via config. The built-in catalog covers common organisational roles:

Dynamic Roles¶

Users can define custom roles via config:

custom_roles:
  - name: "Blockchain Developer"
    department: "Engineering"
    skills: ["solidity", "web3", "smart-contracts"]
    system_prompt_template: "blockchain_dev.md"
    reports_to: "CTO"
    suggested_model: "large"

Hiring Process¶

The HR system manages the agent workforce dynamically:

1. HR agent (or human) identifies a skill gap or workload issue
2. HR generates candidate cards based on team needs:
   • What skills are underrepresented?
   • What role (and where in the reporting graph) is needed?
   • What personality would complement the team?
   • What model/provider fits the budget?
3. Candidate cards are presented for approval (to CEO or human)
4. Approved candidates are instantiated and onboarded
5. Onboarding includes: company context, project briefing, team introductions, learned from seniors (training mode)

Training Mode¶

Training mode is a pluggable knowledge-transfer pipeline that seeds newly hired agents with curated senior experience at onboarding time. It runs as the LEARNED_FROM_SENIORS onboarding step.

Pipeline:

1. Source selection: select senior agents as knowledge sources (pluggable: role top performers, department diversity sampling, user-curated list, or composite)
2. Extraction: extract procedural memories, semantic knowledge, and tool usage patterns from source agents in parallel
3. Curation: reduce candidates to a ranked subset (pluggable: relevance score or LLM-curated)
4. Guard chain: sanitization (mandatory, non-bypassable), volume caps (per-content-type hard limits), review gate (human approval via ApprovalStore)
5. Storage: seed approved items into the new agent's memory backend with training tags

Per-hire customisation:

• override_sources: explicit agent IDs bypassing the selector
• content_types: enable/disable specific extractors
• custom_caps: override default volume caps per content type
• skip_training: bypass the step entirely

Safe defaults: RoleTopPerformers (top 3), RelevanceScoreCuration, all guards enabled, human review required. Idempotent by plan ID.

Pruning¶

The pruning service automates performance-driven agent removal with mandatory human approval.

• PruningPolicy protocol with two implementations:
• ThresholdPruningPolicy: prunes agents with quality AND collaboration below thresholds for N+ consecutive windows (7d/30d/90d).
• TrendPruningPolicy: prunes agents with declining Theil-Sen trend across all three windows.
• PruningService runs as a periodic background task, evaluates all active agents, and creates CRITICAL-risk approval items for eligible candidates.
• On human approval, delegates to OffboardingService with FiringReason.PERFORMANCE.
• Approval deduplication prevents multiple pending approvals per agent.
• Transient offboarding failures are retried on subsequent cycles.

Module: src/synthorg/hr/pruning/ (models, policy, service).

Dynamic Scaling¶

The scaling service closes the loop between workload, budget, skill coverage, and performance signals and the existing hiring/pruning pipelines. It evaluates four pluggable strategies in parallel, filters decisions through a guard chain, and produces approved scaling actions.

Architecture¶

Orchestrated by ScalingService in hr/scaling/service.py.

Strategies¶

Each strategy supports a headless (rule-based) path and an optional agent-delegated path (agent_delegate config field). Agent delegation is protocol-stubbed but not implemented; the headless path is always used.

PerformancePruningStrategy coordinates with the evolution system: when defer_during_evolution is True (default), agents with recent evolution adaptations are skipped.

Guard Chain¶

All decisions flow through guards sequentially before execution:

1. ConflictResolver: priority-ordered resolution. Default: BudgetCap (0) > PerformancePruning (1) > SkillGap (2) > Workload (3). HOLD from BudgetCap blocks HIRE from lower-priority strategies.
2. CooldownGuard: per action-type + target cooldown (default 1 hour).
3. RateLimitGuard: global daily caps (default 3 hires, 1 prune per day).
4. ApprovalGateGuard: routes decisions through ApprovalStore as ApprovalItem entries for human approval.

Configuration¶

scaling:
  enabled: true
  workload:
    enabled: true
    hire_threshold: 0.85
    prune_threshold: 0.30
  budget_cap:
    enabled: true
    safety_margin: 0.90
    headroom_fraction: 0.60
  skill_gap:
    enabled: false
  performance_pruning:
    enabled: true
    defer_during_evolution: true
  triggers:
    batched_interval_seconds: 900
  guards:
    cooldown_seconds: 3600
    max_hires_per_day: 3
    max_prunes_per_day: 1
    approval_expiry_days: 7

Dashboard¶

The /scaling page shows:

• Signal gauges: utilisation, budget burn, declining agent count
• Strategy controls: enabled status, priority order
• Pending decisions: awaiting human approval
• Recent decisions: history with outcome and rationale

Module: src/synthorg/hr/scaling/ (models, protocols, strategies, signals, triggers, guards, context, config, factory, service).

Boot wiring and rollout¶

The pipeline is OPT-IN but ghost-wired. build_scaling_service (in hr/scaling/factory.py) assembles the ScalingService over the hiring and offboarding services, and wire_scaling (in api/lifecycle_helpers/scaling_wiring.py) constructs it at startup whenever its collaborators are present, regardless of hr.scaling_enabled. The hr.scaling_enabled switch (off by default) is enforced live at the /scaling endpoints via ensure_feature_enabled, which 503s while it is off; toggling it applies on the next request with no restart. wire_scaling also constructs the durable HiringService, attaches the per-backend hiring_requests repository, and reloads in-flight requests so an approved hire is not orphaned by a restart. Gated on a connected persistence backend plus a wired registry, performance tracker, and approval store; absent any of those the service stays unwired and the endpoints 503.

Firing / Offboarding¶

Offboarding is triggered by: budget cuts, poor performance metrics, project completion, or human decision.

1. Agent's memory is archived (not deleted)
2. Active tasks are reassigned
3. Team is notified

Performance Tracking¶

Performance data is exposed via three API sub-routes on /api/v1/agents/{agent_id} (the agent's stable id):

The framework tracks detailed per-agent metrics:

agent_metrics:
  tasks_completed: 42
  tasks_failed: 2
  average_quality_score: 8.5     # from code reviews, peer feedback
  average_cost_per_task: 0.45
  average_completion_time: "2h"
  collaboration_score: 7.8       # peer ratings
  last_review_date: "2026-02-20"

collaboration_score = weighted_average(
    delegation_success_rate,
    delegation_response_latency,
    conflict_resolution_constructiveness,
    meeting_contribution_rate,
    loop_prevention_score,
    handoff_completeness
)

Evaluation Loop¶

The closed-loop evaluation framework continuously measures agent performance and identifies improvement opportunities, built on top of the five-pillar evaluation, performance tracking, and trajectory scoring described elsewhere on this page. It captures traces, tags behaviour, enriches each turn with five-pillar evaluation, and proposes targeted fixes validated on the next run. The framework has its own design page: Evaluation Loop.

Agent Evolution¶

Agents improve over time through a pluggable evolution pipeline that closes the loop between execution outcomes, learned knowledge, and agent behaviour. The system follows the EvoSkill three-agent separation principle: the executing agent does not propose its own identity changes; a separate analyser does.

Architecture¶

The pipeline is orchestrated by EvolutionService in engine/evolution/service.py.

Pluggable Axes¶

Every bullet is a strategy behind a @runtime_checkable Protocol:

• Triggers (engine/evolution/triggers/): BatchedTrigger, InflectionTrigger, PerTaskTrigger, CompositeTrigger
• Proposers (engine/evolution/proposers/): SeparateAnalyzerProposer (EvoSkill strict), SelfReportProposer (heuristic), CompositeProposer (routes by outcome)
• Adapters (engine/evolution/adapters/): IdentityAdapter (identity mutation via version store), StrategySelectionAdapter (preference memory), PromptTemplateAdapter (prompt injection)
• Guards (engine/evolution/guards/): RateLimitGuard, ReviewGateGuard, RollbackGuard, ShadowEvaluationGuard (runs adapted agent on a probe task suite via a pluggable ShadowTaskProvider + ShadowAgentRunner and rejects when score or pass rate regresses beyond configured tolerances), ApproveAllGuard (no-op fallback used when every real guard is disabled), CompositeGuard (chains ALL)

Identity Version Store¶

engine/identity/store/ provides versioned identity storage with rollback:

• IdentityVersionStore protocol: put, get_current, get_version, list_versions, set_current (rollback)
• AppendOnlyIdentityStore: Every mutation appends a new version (full audit trail). set_current writes a new version pointing to the restored content.
• CopyOnWriteIdentityStore: Maintains a separate version pointer. set_current only updates the pointer (cheaper, but loses rollback audit trail).

Both wrap AgentRegistryService + VersioningService[AgentIdentity].

Performance Inflection Events¶

PerformanceTracker emits PerformanceInflection events via an InflectionSink protocol when a metric's trend direction changes (e.g., stable to declining). InflectionTrigger implements InflectionSink and queues events for the evolution service.

Safe Defaults¶

Configuration¶

evolution:
  enabled: true
  triggers:
    types: [batched, inflection]
    batched_interval_seconds: 86400
  proposer:
    type: composite
    model: example-small-001
    temperature: 0.3
    max_tokens: 2000
  adapters:
    identity: false
    strategy_selection: true
    prompt_template: true
  guards:
    review_gate: true
    rollback: true
    rollback_window_tasks: 20
    rollback_regression_threshold: 0.1
    rate_limit: true
    rate_limit_per_day: 3
    shadow_evaluation: null        # null disables; set a ShadowEvaluationConfig to enable
  memory:
    capture:
      type: hybrid           # failure | success | hybrid
      min_quality_score: 8.0
    pruning:
      type: ttl              # ttl | pareto | hybrid
      max_age_days: 90
    propagation:
      type: none             # none | role_scoped | department_scoped
  identity_store:
    type: append_only

Five-Pillar Evaluation Framework¶

Performance data is also evaluated through a structured five-pillar framework (InfoQ: Evaluating AI Agents):

Each pillar and its individual metrics can be independently enabled/disabled via EvaluationConfig. Disabled pillars/metrics have their weight redistributed proportionally to remaining enabled ones. All pillars ship enabled by default with recommended weights (equal 0.2 each).

The EvaluationService orchestrates scoring, delegating to a pluggable PillarScoringStrategy per pillar. The default per-pillar strategy is ConfigurablePillarScorer composed with the corresponding per-pillar MetricExtractor (one extractor per file under hr/evaluation/extractors/). The composite owns the shared "redistribute weights → weighted-average → clamp → confidence → log → PillarScore" pipeline so each extractor stays focused on the per-pillar data extraction. Human-calibrated LLM labelling uses the existing LlmCalibrationSampler infrastructure; calibration drift above a configurable threshold reduces the intelligence pillar's confidence (via the extractor's confidence_multiplier), signalling the need for more human labels.

HR Service Layer¶

MCP handlers and REST controllers never reach into HR repositories directly; every read goes through a narrow service facade so auditing, pagination, and optional-dependency degradation stay in one place per domain. The services follow the standard protocol + strategy + factory + config-discriminator pattern where interchangeable backends exist (e.g. AutonomyPolicyService, ScalingConfigService), and collapse to a single class where the behaviour is strictly orchestration (e.g. ActivityFeedService).

See Also¶

• Agents: agent identity, personality, skills, identity versioning
• Organisation: company types, departments, templates
• Budget & Cost: performance-driven downgrade, risk budget
• Design Overview: full index