Skip to main content
Status: accepted · ADR-32 · Filed 2026-04-30

​
Title

Agent identity is a UUID (agent_id); display name is presentation only

​
Decision

Introduce agents table with agent_id UUID primary key as the stable, immutable referent for any agent (persona). The human-readable persona name (display_name) becomes a presentation attribute on that row, not the identity. All routing layer code (channels, headers, signal_queue FKs) keys on agent_id. Verb arguments may accept display_name as user-facing convenience but resolve server-side to agent_id within the sender’s project scope. Replace today’s controller_registrations.agent_identity (string) and signal_queue.from_identity/to_identity (string) with FK columns agent_id / from_agent_id / to_agent_id. Replace X-Prism-Identity header with X-Prism-Agent-Id (the UUID).

​
Rationale

The legacy “identity = display name string” approach was usable while persona names were assumed unique-per-project and never expected to change. It breaks in three concrete future scenarios:
  1. Persona rename — agents.display_name = “Donna” → “DonnaR” must preserve identity continuity (same agent_id, history intact, signals in flight delivered correctly). With name-as-identity, rename is identity break.
  2. Cross-tenant collaboration (future) — a guest member from another tenant may have a name collision with a host project’s persona; the host needs to resolve “Donna who is in this project” stably regardless of display-name choices.
  3. Audit trail integrity — every signal_queue row needs a stable referent for “who sent this” that survives any future renames or moves; a string snapshot of the name at send-time loses connection to the identity if the persona is renamed later. A UUID PK with a separate display attribute is the standard relational shape for this. The cost is one new table + FK propagation.

​
Alternatives Considered

  1. Keep agent_identity as a string, add a separate agent_uuid for stability. Considered and rejected — half-step that forces every consumer to choose which to trust. Better to do the rename once.
  2. Make display_name the PK, with a slug/canonical form. Variation of the legacy model; same problems with rename + collisions.
  3. Use (user_id, project_id, display_name) as a composite key everywhere. Workable for routing, but every FK across the schema becomes a 3-column composite — verbose and error-prone. UUID is cleaner.

​
Status

accepted

​
References

  • SPEC-056 §Identity model
  • Memory: feedback_document_port_misses
Last modified on May 3, 2026