-
Notifications
You must be signed in to change notification settings - Fork 1
Description
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.jsonor 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
-
AgentIdentitymodel 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_idfield 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
- Persist grounding traces to daily JSONL files #34 — trace persistence (this sub-issue adds a field to the trace schema)
Metadata
Metadata
Assignees
Labels
Projects
Status