HR & Agent Lifecycle¶

This page covers the operational lifecycle of every agent in a synthetic organization -- from hiring through performance tracking, promotion, 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).

Seniority & Authority Levels¶

Role Catalog¶

The role catalog is extensible -- users can add custom roles via config. The built-in catalog covers common organizational 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"
    authority_level: "senior"
    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 seniority level 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 customization:

• 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: utilization, 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, config, factory, service).

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/{name}:

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 existing five-pillar evaluation, performance tracking, trajectory scoring, and training infrastructure.

Closed-Loop Architecture¶

flowchart LR
    T[Trace Capture] --> BT[Behavior Tagging]
    BT --> EE[Eval Enrichment<br/>5 Pillars]
    EE --> PI[Pattern Identification<br/>stub]
    PI --> FP[Fix Proposal<br/>stub]
    FP --> V[Validation<br/>next run]
    V -->|feedback| T

The EvalLoopCoordinator orchestrates existing services into cycles: collect metrics, enrich with five-pillar evaluation, identify failure patterns (stub), propose targeted fixes (stub), and validate via next-run trajectory scores.

Behavior Tagging¶

Each turn is tagged with one or more BehaviorTag categories for fine-grained trace analysis and eval routing:

Tags are inferred by BehaviorTaggerMiddleware (opt-in, after_model slot) via tool-name pattern matching. Stored on TurnRecord.behavior_tags.

Efficiency Ratios¶

Per-run efficiency ratios measured against IdealTrajectoryBaseline:

• Step ratio: observed steps / ideal steps (1.0 = on target)
• Tool call ratio: observed calls / ideal calls
• Latency ratio: observed time / ideal time
• Verbosity ratio: observed output tokens / ideal tokens (from SlopCodeBench)
• Structural erosion score: composite 0.0--1.0 (duplicated blocks, cyclomatic complexity delta, dead-branch ratio)
• PTE: Prefill Token Equivalents (hardware-aware cost metric, from arXiv:2604.05404)
• PTE ratio: observed PTE / ideal PTE

Baselines are human-curated and versioned -- not auto-updated from observed runs.

Quality Erosion Detection¶

New stagnation variant (StagnationReason.QUALITY_EROSION): agent keeps working but structural_erosion_score climbs past threshold (default 0.5). QualityErosionDetector implements the StagnationDetector protocol and fires corrective prompt injection or termination.

External Benchmarks¶

Pluggable ExternalBenchmark protocol for adopting external benchmark suites without modifying the framework. ExternalBenchmarkRegistry manages registration and execution.

Agent Evaluation Testing¶

Tests tagged @pytest.mark.agent_eval(category="file_operations") run separately from the default unit suite:

uv run python -m pytest tests/evals/ -n 8 --eval-timeout=300

n1_prefix_replay utility replays first N-1 turns of a recorded trace and lets the agent generate only the final turn for regression testing.

CI: evals.yml runs nightly and on run-evals label.

Promotions & Demotions¶

Agents can move between seniority levels based on performance:

• Promotion criteria: Sustained high quality scores, task complexity handled, peer feedback
• Demotion criteria: Repeated failures, quality drops, cost inefficiency
• Promotions can unlock higher tool access levels
• Model upgrades/downgrades may accompany level changes (configurable, see auto-downgrade)

Agent Evolution¶

Agents improve over time through a pluggable evolution pipeline that closes the loop between execution outcomes, learned knowledge, and agent behavior. The system follows the EvoSkill three-agent separation principle: the executing agent does not propose its own identity changes -- a separate analyzer 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 pluggable PillarScoringStrategy implementations. The efficiency pillar is computed inline from WindowMetrics. Human-calibrated LLM labeling uses the existing LlmCalibrationSampler infrastructure -- calibration drift above a configurable threshold reduces the intelligence pillar's confidence, signaling the need for more human labels.

Client Agents¶

Client agents are synthetic or real external actors that submit task requirements and review deliverables. Unlike internal agents (which execute tasks), client agents drive the organization from the outside -- generating workloads and evaluating outputs.

All client types implement ClientInterface from synthorg.client.protocols:

• AIClient -- LLM-backed persona that generates requirements and reviews deliverables autonomously.
• HumanClient -- Delegates decisions to a human via the API/dashboard.
• HybridClient -- AI drafts, human confirms.

Client behavior is configured via ClientProfile (persona, expertise domains, strictness level) and driven by pluggable strategies for requirement generation and feedback evaluation.

See Client Simulation for the full architecture.

See Also¶

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