Agents & HR¶

Agent Identity Card¶

Every agent has a comprehensive identity. At the design level, agent data splits into two layers:

Config (immutable)

Identity, personality, skills, model preferences, tool permissions, and authority. Defined at hire time, changed only by explicit reconfiguration. Represented as frozen Pydantic models.

Runtime state (mutable-via-copy)

Current status, active task, conversation history, and execution metrics. Evolves during agent operation. Represented as Pydantic models using model_copy(update=...) for state transitions -- never mutated in place.

Personality Dimensions¶

Personality is split into two tiers:

Agent Configuration Example¶

# --- Config layer -- AgentIdentity (frozen) ---
agent:
  id: "uuid"
  name: "Sarah Chen"
  role: "Senior Backend Developer"
  department: "Engineering"
  level: "Senior"
  personality:
    traits:
      - analytical
      - detail-oriented
      - pragmatic
    communication_style: "concise and technical"
    risk_tolerance: "low"
    creativity: "medium"
    description: >
      Sarah is a methodical backend developer who prioritizes clean
      architecture and thorough testing. She pushes back on shortcuts
      and advocates for proper error handling. Prefers Pythonic solutions.
    # Big Five (OCEAN-variant) -- internal scoring (0.0-1.0)
    openness: 0.4
    conscientiousness: 0.9
    extraversion: 0.3
    agreeableness: 0.5
    stress_response: 0.75
    # Behavioral enums -- injected into system prompts
    decision_making: "analytical"
    collaboration: "independent"
    verbosity: "balanced"
    conflict_approach: "compromise"
  skills:
    primary:
      - python
      - litestar
      - postgresql
      - system-design
    secondary:
      - docker
      - redis
      - testing
  model:
    provider: "example-provider"
    model_id: "example-medium-001"
    temperature: 0.3
    max_tokens: 8192
    fallback_model: "openrouter/example-medium-001"
    model_tier: "medium"  # set by model matcher (large/medium/small/null)
  model_requirement:            # original tier/priority from template
    tier: "medium"
    priority: "balanced"
    min_context: 0
    capabilities: []
  memory:
    type: "persistent"       # persistent, project, session, none
    retention_days: null     # null = forever; also agent-level global default
    retention_overrides: []  # per-category overrides, e.g. [{category: "semantic", retention_days: 365}]
  tools:
    access_level: "standard" # sandboxed | restricted | standard | elevated | custom
    allowed:
      - file_system
      - git
      - code_execution
      - web_search
      - terminal
    denied:
      - deployment
      - database_admin
  authority:
    can_approve: ["junior_dev_tasks", "code_reviews"]
    reports_to: "engineering_lead"
    can_delegate_to: ["junior_developers"]
    budget_limit: 5.00
  autonomy_level: null       # full, semi, supervised, locked (overrides defaults)
  hiring_date: "2026-02-27"
  status: "active"           # active, on_leave, terminated

Runtime State¶

The runtime state layer (in engine/) tracks execution progress using frozen models with model_copy:

• TaskExecution wraps a Task with evolving execution state: status transitions, accumulated cost (TokenUsage), turn count, and timestamps.
• AgentContext wraps AgentIdentity + TaskExecution with a unique execution ID, conversation history, cost accumulation, turn limits, and timing.
• AgentRuntimeState provides a lightweight per-agent execution status snapshot (idle / executing / paused) for dashboard queries and graceful-shutdown discovery. Persisted via AgentStateRepository, independent of the checkpoint system.

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

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
)

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)

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.