Skip to content

Add agent identity to trace entries via persisted registry #41

@anormang1992

Description

@anormang1992

Parent Issue

Sub-issue of #34 (Persist grounding traces to daily JSONL files)

Summary

Each trace entry should include a stable agent identifier so that traces from different agents are distinguishable. This requires a persisted agent registry that ensures the same agent instance receives the same ID across restarts and sessions.

Problem Statement

Issue #34 introduces trace persistence, but every trace entry is anonymous — there is no field identifying which agent produced it. In a single-agent setup this is tolerable, but it becomes a blocker for VRE Networks (multi-agent topologies sharing grounded knowledge across graphs).

If we ship trace persistence without agent identity:

  • Historical traces will lack attribution, making them useless for multi-agent analysis
  • Retrofitting agent IDs later means either backfilling or accepting a discontinuity in the trace history
  • The VRE Workstation cannot filter or group activity by agent

Getting this right before traces are persisted at scale avoids a migration problem later.

Proposed Solution

Agent Identity Model

Introduce an AgentIdentity model (or similar) that holds:

  • agent_id: a stable, unique identifier (e.g. UUID)
  • name: a human-readable label (optional, for display purposes)
  • created_at: when this agent was first registered

Persisted Registry

A lightweight registry that maps agent instances to their stable IDs:

  • Storage: file-based (e.g. ~/.vre/agents.json or similar), consistent with Persist grounding traces to daily JSONL files #34's minimal-infrastructure approach
  • Lookup: on VRE instantiation, the agent provides a registration key (e.g. name, config hash, or explicit ID) that resolves to a persisted identity
  • Idempotent: subsequent instantiations with the same key return the same agent_id
  • No graph mutation: the registry is external to the epistemic graph, like trace files

Trace Integration

Each trace entry (from #34) includes an agent_id field, populated from the registry at write time.

VRE Design Alignment

  • Inspectability: Agent attribution makes traces more inspectable — you can answer "which agent attempted this grounding?" after the fact
  • Minimal footprint: A single JSON file for the registry; no new infrastructure
  • VRE Networks prerequisite: Multi-agent knowledge sharing requires agent identity as a foundational primitive; building it into the trace layer now avoids retrofit

Spike Notes

This will likely require spiking to resolve:

  • What constitutes a stable "registration key" — agent name? Config fingerprint? Explicit user-supplied ID?
  • Whether the registry should support deregistration or is append-only
  • How identity interacts with VRE instantiation (constructor param? Separate registration call?)
  • Whether identity should be optional (backward compat) or required when tracing is enabled

Acceptance Criteria

  • AgentIdentity model exists with stable ID, optional name, and creation timestamp
  • Persisted registry stores and retrieves agent identities idempotently
  • VRE instance can be associated with an agent identity at construction or registration time
  • Trace entries from Persist grounding traces to daily JSONL files #34 include the agent_id field when identity is configured
  • Subsequent VRE instantiations with the same registration key resolve to the same agent_id
  • Registry is file-based and requires no additional infrastructure
  • Existing behavior is unaffected when no agent identity is configured

Dependencies

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions