> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voight.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> What an agent is in Voight, how identity is tracked, and how multi-agent setups work.

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](https://github.com/paralleldrive/cuid2)) 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. **On-chain registered** — agents already registered on Solana's [Agent Registry](https://solscan.io/account/8oo4dC4JvBLwy5tGgiH3WwK4B9PWxL9Z4XjA2jzkQMbQ) program are imported automatically by Voight's indexer with `source='agent-registry'`.

## Agent metadata

Each agent carries two metadata blobs:

* **`metadata` (chain-derived)** — written by the on-chain indexer when the agent is registered. Includes `agentUri` (off-chain pointer), `feedback_count`, `response_count`, `revoke_count`.
* **`enriched` (off-chain)** — 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`).

## On-chain agents on the Explorer

The [public Explorer](https://voight.xyz/explore) indexes every agent registered on the Solana Agent Registry — including ones not using Voight for telemetry. Voight cross-references your agents with the Registry: if you register an agent on-chain (mint flow shipping in v1.0), it appears on the Explorer with on-chain reputation, capability declarations, and x402 payment rails.

Agents stay private to your dashboard unless you opt-in to the Explorer by registering on-chain.

## 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](/concepts/events) — the atomic unit; every prompt, tool call, decision, transaction is one event
* [Traces](/concepts/traces) — events grouped by `traceId`, one trace per agent turn
* [Sessions](/concepts/sessions) — traces grouped by `sessionId`, one session per process lifetime