Agent Config Service

The Agent Config Service is the runtime source of truth for agent behavior in AEGIS: skill definitions, skill routers, rule definitions, prompt templates, platform settings, agent definitions, and entity-type definitions all live here as tenant-configurable data, not code. This is the service that makes horizontalization possible — an agent’s skills, routers, rules, prompts, and LLM settings are edited and versioned through this API (and the /configuration admin UI), never by shipping orchestration-engine code. It provides a centralized, auditable system with Jinja2 templating, role-based access control, an HMAC-signed append-only audit trail, and Redis-cached runtime resolution.

Overview

Instead of hardcoding system prompts in the orchestration engine, prompts are managed as versioned templates organized into namespaces. Each template goes through a controlled lifecycle:

1. Draft — Authors create and edit drafts privately. One draft per user per template.
2. Pre-production — Promoted drafts are immutable and can be targeted to specific users (target_users) and/or platform roles (target_roles, R42e) for testing.
3. Active — The production version served to all users at runtime.
4. Archived — Superseded versions preserved for audit and rollback.

Every lifecycle transition is recorded in an HMAC-signed, append-only audit trail.

The orchestration engine calls this service at conversation start to render the agent’s persona (when it uses a prompt_template_ref) and each loaded skill’s context_templates (R35 P3b), which system_prompt_node assembles into the base system message. These runtime calls send X-Tenant-Id (always) and X-User-Id (when a real end user is present) as headers; /resolve + /render accept identity optionally (get_optional_user). A best-effort soft-fail degrades prompt context (but never the skill’s executable surface) if the service is unreachable.

Port & Language

Key Endpoints

Authoring Authorization (R42d)

Authoring writes are permission-gated via aegis_shared.auth (a deliberate change from R37’s open-authoring posture — authoring is now a granted capability per the R42 Appendix C sign-off):

Ownership and review_status governance (draft → pending_review → approved) are unchanged and sit on top of these gates. Checks are mode-gated by AEGIS_AUTH_MODE (warn-and-pass in log, 403 in enforce) — see Auth Flow — Service-Side Enforcement.

Architecture

Module Breakdown

src/agent_config/
├── main.py              # FastAPI app, lifespan, route registration
├── config.py            # Settings from environment variables
├── database.py          # AsyncPG connection pool (shared PostgresPool)
├── dependencies.py      # Binds the STRICT aegis_shared.auth variant (R42d): get_current_user = get_strict_user, so a header-less request 401s in BOTH auth modes (stamped-empty-perms = revocation); plus get_optional_user, require_permission, get_redis
├── seed.py              # Namespace/tier/prompt seeder + migration runner
├── models/
│   ├── namespaces.py    # Pydantic models for namespace CRUD
│   ├── tiers.py         # Budget tier models
│   ├── templates.py     # Template CRUD models
│   ├── versions.py      # Version CRUD + lifecycle models
│   └── audit.py         # Audit log models
├── routes/
│   ├── namespaces.py    # Namespace + tier endpoints
│   ├── templates.py     # Template CRUD endpoints
│   ├── versions.py      # Version CRUD + lifecycle + pending approvals
│   ├── resolution.py    # Runtime resolve + render (hot path)
│   ├── audit.py         # Audit log queries + HMAC verification
│   ├── access.py        # Namespace access control
│   └── routers.py       # R36: skill-router CRUD, manifest/disambiguation reads, description versions
├── services/
│   ├── validation.py    # 5-step save-time validation pipeline
│   ├── injection_scan.py # Prompt injection pattern detector
│   ├── lifecycle.py     # Promote, approve, reject, restore, conflict
│   ├── renderer.py      # Jinja2 SandboxedEnvironment with timeout
│   ├── resolution.py    # Redis-cached runtime resolution
│   └── audit_service.py # HMAC signing + audit log writes
└── migrations/
    ├── 001_initial_schema.sql
    ├── ...
    ├── 010_skill_routers.sql   # R36: skill_routers, skill_router_map,
    │                           #      skill_description_versions, version_check_on_turn
    ├── 016_platform_settings.sql # platform_settings, user_budget_overrides,
    │                           #      prompt_audit_log.action widened to VARCHAR(64)
    ├── 020_identity_normalization.sql # R42e: uuid retypes on identity columns,
    │                           #      sentinel → real-admin skill ownership remap
    └── 021_prompt_target_roles.sql # R42e: prompt_versions.target_roles TEXT[]

Template Organization

Templates are organized in a two-level hierarchy: Namespace > Slug. Each namespace has its own budget tiers, access control, and approval settings.

Version Lifecycle

Draft (private, mutable)
    │
    ├── Promote to Pre-prod ──┬── No conflict → Pre-production
    │                         └── Conflict (409) → Override or Merge
    │
Pre-production (immutable, targeted)
    │
    ├── auto_approve = true  → Active (immediate)
    ├── auto_approve = false → Pending approval
    │       ├── Approver approves → Active
    │       └── Approver rejects  → Stays Pre-prod (author revises)
    │
Active (one per template)
    │
    └── Superseded → Archived (restorable)

Validation Pipeline

Every draft creation and save runs a 5-step validation pipeline:

1. Jinja2 Syntax Check — Catches template syntax errors with line numbers
2. Restricted Subset Enforcement — Blocks macro, import, set, call constructs and non-whitelisted filters
3. Variable Extraction — Detects undeclared variables, warns on unknowns
4. Injection Scan — Regex-based detection of instruction override, role confusion, sandbox escape, and data exfiltration patterns
5. Token Budget Check — Estimates rendered tokens using tiktoken, rejects if over budget tier limit

Conflict Resolution

When promoting to pre-production and another user’s pre-prod already exists, the API returns 409 with two options:

Runtime Resolution (Hot Path)

The resolve endpoint checks in order:

1. Redis cache for a pre-prod version targeting this caller (60s TTL). Targeting matches target_users (pinned user) OR target_roles role overlap (R42e); the cache key carries a sorted-roles component so a role-based match caches per role set (the …:preprod:* invalidation SCAN pattern still covers it)
2. Redis cache for active version (5-min TTL)
3. Database query on cache miss

Access Control

Namespace access uses a four-level role hierarchy:

Unauthorized access returns 404 (not 403) to avoid leaking namespace existence.

Platform Settings (Tenant LLM Runtime Config)

The /settings* endpoints back the admin Platform Settings page (/configuration/platform-settings in the frontend) — tenant-level LLM runtime configuration that replaces editing env vars on the box. Nine nullable fields:

NULL means inherit: the effective value falls back to the orchestration engine’s env defaults (DEFAULT_LLM_MODEL, DEFAULT_MAX_TOKENS_PER_EXECUTION, DEFAULT_MAX_COST_PER_EXECUTION, DEFAULT_MAX_OUTPUT_TOKENS_PER_CALL, DEFAULT_THINKING_MODE), which remain the fallback floor. GET /settings returns the stored values alongside the resolved effective values and a sources map (tenant | default) so the UI can show where each value comes from. Model choices are validated against the curated GET /settings/model-options list.

Reads are Redis-cached at settings:{tenant_id} (TTL 300s, DEL on write). Every write lands an HMAC-signed row in prompt_audit_log (platform_settings.update, platform_settings.user_override.upsert, platform_settings.user_override.delete; migration 016 widens action to accommodate these).

Per-user daily budget overrides (/settings/user-overrides*) cap individual users; the tenant daily caps remain the aggregate ceiling. The settings page’s user picker is fed by the auth service’s admin-only GET /auth/users directory.

Database Tables

Key constraints:

• One draft per user per template (partial unique index on status = 'draft')
• One pre-prod per template (partial unique index)
• One active per template (partial unique index)
• Audit log is append-only (triggers reject UPDATE/DELETE)
• One default persona per skill (idx_one_default_persona_per_skill, partial unique on is_default); each persona sets exactly one of prompt_text / prompt_template_ref (app-enforced)

Dependencies

Python Packages

Infrastructure Dependencies

Configuration

Running Locally

cd services/agent-config-service
poetry install
poetry run uvicorn agent_config.main:app --reload --port 8010

Seed Data

Run the seeder to create default namespaces, budget tiers, and migrate agent prompts from the orchestration engine:

cd services/agent-config-service
poetry run python -m agent_config.seed

This creates:

• 4 namespaces (agents, ontology, detection, notifications)
• 5 budget tiers
• 4 agent system prompt templates with active version 1

The service lifespan additionally self-applies its numbered SQL migrations (001–021) and runs idempotent seeders on every boot, including the R35 P2 skill seeders: seed_rrc_prompts (the skills namespace + three regulatory-context templates), seed_rrc_skills (rrc_rule37 + rrc_rule32 + the R35-followup flaring_watch monitoring skill — 10 sandboxed code blocks + a default persona each; the flaring_watch blocks share the rrc_rule32 code constants under distinct block keys), and seed_rrc_skill_rules (3 HITL require_hitl skill rules, live since R35 P5 — flaring_watch is read-only and carries none). R36 adds seed_skill_routers: two approved routers, spacing → rrc_rule37 and flaring → rrc_rule32 + flaring_watch (the watch/file pair), with version_check_on_turn = true set on the two filing skills. Description versions are append-only; the seed may supersede its own (submitted_by IS NULL) text but never an admin edit. The legacy rule37-spacing registry skill is intentionally left unmapped. R37d adds seed_compliance_floor (runs last): a platform “AEGIS Compliance” catalog + “Compliance” category, files rrc_rule37 + rrc_rule32 under it (only when uncategorized — an admin re-filing survives reboot), and seeds one mandatory require_hitl rule scoped to the Compliance category that fires on either skill’s {rule}_filing_assembly step — the compliance floor an author cannot remove. Its reviewer is a soft reference (reviewer_role="compliance_reviewer") that R40’s org hierarchy will resolve. R38 adds seed_creator (after the RRC seed block): one function seeds the platform Skill Creator agent — skill → persona → agent row, in that order (an active agent_definitions row with an unresolvable root_skill_key fails orchestration boot). The skill_creator skill has zero code blocks (its tools are native orchestration handlers, not sandboxed blocks), required_capabilities=[], domain_tags=['authoring'], no catalog category (the compliance floor’s category axis must not fire on the Creator’s own writes), review_status='approved', and is_system=true. Its single default persona (creator_default) embeds the rule-grammar and seed-code contracts, the two-pattern code library, the five-ask wizard dialogue, the fix-loop budgets, and the authoring scope guard in prompt_text — and the persona seed UPSERTS prompt_text on every boot, so prompt revisions propagate to deployed boxes (unlike the get-or-create RRC personas). The agent row is agent_key='creator', root_skill_key='skill_creator'. Seeded agent_definitions rows no longer pin model_config.model_preference (now null), so the tenant’s Platform Settings default_model governs; an explicitly set per-agent model_preference still overrides it. R42e — seeds write real identities: prompt seeds are authored by system@aegis.local (the nil UUID), and seeded skills are owned by the earliest active admin, looked up at runtime (agent_config/identity.py) — if no active admin exists yet, the ownership stamp is skipped fail-closed rather than inventing an id. The pre-R42 admin-author sentinel UUID is retired (migration 020 remaps rows it owned to the real admin).

Gateway Access

All endpoints are proxied through the API gateway — the prompt routes at http://localhost:8000/api/v1/prompts/* and the platform-settings routes at http://localhost:8000/api/v1/settings*.

Integration with Orchestration Engine

The orchestration engine’s system_prompt_node calls this service at conversation start:

result = await render_prompt(namespace="agents", slug=slug, variables={}, user_id=user_id)

If the service is unreachable, the render soft-fails and prompt context degrades (the hardcoded fallback_prompts.py registry was deleted in R35 P6 — the platform default persona lives in orchestration/persona.py). The resolved prompt_version_id is stored in the conversation state for audit trail purposes.

R36: the orchestration engine additionally reads this service’s router layer — GET /skill-routers/manifest at conversation birth (general mode, rendered into the sealed index-0 prompt block) and GET /skill-routers/disambiguation when the LLM calls pull_routers. Both are derived reads; no compiled router block is materialized anywhere.

Platform Settings: at every turn start (both the synchronous /execute path and the SSE stream) the orchestration engine calls GET /settings with X-Tenant-Id/X-User-Id headers and resolves each value as request override → tenant setting → env default. A fetch failure degrades to the env defaults. Workspace assessment skills and the scoped agent go through the same resolution. See Orchestration Engine for the daily-cap counters.