Skip to content
Gateway Guardian

Trusted Agent Registry (LLM Gateway)

Status: Active Last updated: 2026-03-09

This document defines the trusted agent registry that lives in the LLM Gateway database (guardian_gateway).

Sidecar implementers should also follow:

  • llm-gateway/docs/sidecar-agent-registration.md

1. Why this exists

Section titled “1. Why this exists”

The registry is the source of truth for:

  • enterprise agents
  • agent signing keys
  • user associations to agents

It supports:

  • sidecar first-time auto-registration
  • control-plane discovery via direct SQL reads

Current runtime mode is tenantless with DID-based request verification (keyid=did:key:...).

2. Core tables

Section titled “2. Core tables”

Tables:

  • registry_agents
    • agent_id: Canonical identity of the agent (required).
    • display_name: Human-readable name for the agent (optional).
    • status: Either active or revoked (kill-switch support; see migration 0013).
    • created_at, updated_at: Timestamps for record keeping.
  • registry_agent_keys
    • did: The agent’s signing key, must be a unique Ed25519 did:key (globally unique across all agents).
    • status: Active/revoked status.
    • kill_switch_revoked: Boolean for kill-switch status (enforced by migration and constraint).
    • agent_id: Foreign key reference to agent.
  • registry_users
    • external_subject: Unique user identifier (such as user email or SSO subject).
  • registry_agent_user_bindings
    • Associates agents and users (many-to-many).
    • Each entry binds an agent_id, user_id, and a role (role defaults to operator if not specified).
  • registry_registration_events and registry_agent_status_events
    • Append-only audit logs for registration and status changes (with actor, reason, and affected DIDs).

Migrations:

  • llm-gateway/service/migrations/0002_trusted_agent_registry.up.sql (initial)
  • llm-gateway/service/migrations/0004_single_tenant_schema.up.sql (tenantless schema)
  • llm-gateway/service/migrations/0006_registry_keys_did_only.up.sql (DID-only key records)
  • llm-gateway/service/migrations/0007_registry_keys_rename_kid_to_did.up.sql (rename key column to did)
  • llm-gateway/service/migrations/0008_registry_events_rename_kid_to_did.up.sql (rename event key column to did)
  • llm-gateway/service/migrations/0009_registry_keys_global_did_uniqueness.up.sql (global DID uniqueness across agents)
  • llm-gateway/service/migrations/0013_agent_kill_switch.up.sql (agent kill-switch status model + status event audit log)

3. Registration write rules

Section titled “3. Registration write rules”

POST /v1/agents/registrations

  • token must validate against configured registration token secret
  • agent and key are auto-activated
  • revoked agents cannot be reactivated by registration; they must be restored via control-plane kill-switch API
  • key idempotency by DID (did)
    • same active key (did:key) -> noop
    • new did:key -> insert new active key record (updated)
    • existing did owned by another agent -> registration_conflict
  • users are upserted by external_subject
  • bindings are upserted by (agent_id, user_id, role)

4. Read model for control plane

Section titled “4. Read model for control plane”

Control plane reads DB directly using views and audit tables:

  • v_registry_agents
  • v_registry_agent_keys
  • v_registry_agent_users
  • v_registry_agent_audit_link
  • gateway_audit_exchanges (windowed activity counts)

v_registry_agent_audit_link ties agent identity to audit records (gateway_audit_exchanges) by agent_id.

Control-plane GET /v1/agents is lightweight by default (no throughput aggregation).

For throughput sparklines in the console agents table, request GET /v1/agents?include=throughput. That response includes fixed 12-hour activity buckets (throughput, 24 values at 30-minute resolution, oldest first) computed from gateway_audit_exchanges.created_at, plus top-level activity_window, window_start, and window_end metadata.

5. Required joins for UI/UX

Section titled “5. Required joins for UI/UX”

Typical discovery queries can join:

  • agent details: v_registry_agents
  • key inventory: v_registry_agent_keys
  • user associations: v_registry_agent_users
  • traffic/audit timeline: gateway_audit_exchanges or v_registry_agent_audit_link

6. Operational notes

Section titled “6. Operational notes”
  • registry backend for production path is postgres
  • registration endpoint is disabled unless explicitly enabled by flag
  • all migrations are auto-applied at startup