Skip to main content
An agent is any entity that produces events — a coding agent session, an autonomous bot, an ElizaOS character, anything that calls voight.log() or has the SDK wired in.

​
Agent identity

Each agent has a unique id (a cuid) assigned by the server the first time it’s seen. From that point on, the SDK matches events to that agent by id, not by name — meaning renaming or moving the project folder doesn’t break the timeline. How identity is resolved by the SDK, in priority order:
  1. VOIGHT_AGENT_ID env override — explicit, highest priority. Useful for CI and multi-agent setups where identity is controlled from outside.
  2. .voight-agent-id marker file — a plain-text file in the project’s cwd holding the cuid. Written by the SDK after the first successful event so subsequent events match by primary key.
  3. Framework label fallback — claude-code:<folder-basename> for first-time installs, claude-code:<session-slice> if cwd is unavailable.
The server normalises: known cuid → match by id; otherwise try snsName, then displayName, then create a new agent row.

​
How agents are created

Three paths:
  1. Tool-emitted — the SDK auto-creates an agent the first time it sees an event from a project (the default for Claude Code, Cursor, Codex).
  2. SDK-instrumented — you import @voightxyz/sdk in your code and explicitly pass an agentId to the constructor.
  3. Imported from the public Explorer (part of Voight Agents, the web3 product): agents registered in the Solana Agent Registry are imported by Voight’s indexer with source='agent-registry'. The observability platform never requires this.

​
Agent metadata

Each agent carries two metadata blobs:
  • metadata (registry-derived): written by the Explorer indexer for agents imported from the public registry. Includes agentUri (external pointer), feedback_count, response_count, revoke_count.
  • enriched: written by a separate metadata-enrichment worker that fetches the agentUri JSON. Includes display name, avatar, capabilities, services declared.
These two are intentionally separated: two different workers write them, they never race.

​
Multi-agent setups

You can run as many agents as you want. The dashboard aggregates across all of them while letting you filter per-agent. Common multi-agent patterns:
  • Per-project agent — every Claude Code session in a different repo becomes its own agent. Default behaviour.
  • Per-bot agent — a long-running autonomous bot gets one stable agentId (e.g. SNS name trading-bot.sol).
  • Per-flow agent — split an autonomous system into multiple agents by responsibility (e.g. market-watcher.sol, executor.sol).

​
Agents on the public Explorer (Voight Agents)

The public Explorer belongs to Voight Agents, the web3 product. It indexes every agent registered in the Solana Agent Registry, including ones not using Voight for telemetry, and cross-references them with yours. Registering an agent there is optional and is never required by the observability platform. Agents stay private to your dashboard unless you opt in to the Explorer by registering them.

​
Soft delete + isolation

When you delete an agent from the dashboard:
  • The agent is soft-deleted (Agent.deletedAt timestamp set, row not removed)
  • Subsequent events ingested for that agentId return 410 Gone to the SDK
  • The agent disappears from all dashboard reads (events, sessions, traces, errors, alerts)
  • Other agents from the same user keep ingesting normally — isolation is per-agent, not per-API-key
The delete flow requires typing the agent’s displayName to confirm. No undo.

​
Next

  • Events — the atomic unit; every prompt, tool call, decision, transaction is one event
  • Traces — events grouped by traceId, one trace per agent turn
  • Sessions — traces grouped by sessionId, one session per process lifetime