Skip to main content

Integrate VIA ID into your agent

This is the phased flow the VIA ID skill follows when an AI coding agent wires it into your project. If you're integrating by hand rather than through a coding assistant, follow the same four phases.

Phase 0 — mint (once, when the agent is built or about to ship)​

node bin/viaid.mjs init "<agent-name>"

One badge per agent, minted once. Not per run, not per deployment — the agent_id is meant to identify the agent across its lifetime.

Phase 1 — instrument (mandatory — this is the actual product)​

Wire a viaid log call into the agent's own code, right after each action worth recording.

node bin/viaid.mjs log <agent_id> "<action description>" [model_used]

This has to be a call from the agent's own runtime, not a one-time step a coding assistant performs at build time. If shelling out per action is too slow for your workload, import appendLog directly instead of shelling out:

import { appendLog, loadBadge, saveBadge } from 'viaid/src/agentid.mjs';

let badge = loadBadge(badgePath);
badge = appendLog(badge, workRoot, { action: 'called payments API', model_used: 'claude-sonnet' });
saveBadge(badgePath, badge);

Same effect, in-process, no shell overhead. Log the actions a human would want an audit trail for — not every internal model thought. Wrapping every internal function call in log is noise, not a record.

Phase 2 — present the badge (optional)​

Only relevant if your agent talks to a receiving party that might want to check it first — an org gating inbound agents, a marketplace, another team's system.

import { viaHeaders } from 'viaid/lib/attach.mjs';

const headers = viaHeaders(badgePath);
// { 'X-VIA-ID-Agent': 'via_...', 'X-VIA-ID-Verify-URL': 'https://viaid.ai/a/<code>' }

This is a pointer, not a proof — attaching the header asserts nothing by itself. The receiving party decides whether to fetch the verify URL and what to do with the result (gate, log, ignore); that decision is theirs, not this library's. Don't build retry, caching, or wrapper logic around this — it's two headers.

Phase 3 — verify before shipping, and periodically after​

node bin/viaid.mjs verify <agent_id>

Read the verdict — VALID, STALE, REVOKED, UNKNOWN, or INVALID — before describing the agent as "badged" anywhere. See Claims & terminology for the exact language to use (and avoid) when talking about what a badge means.

Rotating the agent's key​

Routine hygiene, or after a suspected compromise:

node bin/viaid.mjs rotate <agent_id> routine
node bin/viaid.mjs rotate <agent_id> compromise 2026-07-20T00:00:00.000Z   # ISO "suspected since"

agent_id never changes across a rotation — it's the hash of the agent's inception event. Only the signing key changes, via a pre-committed rotation chain. After a compromise rotation, verify flags the suspected window in scope_note so a reader knows what to discount; it does not silently discount log entries for you.

What not to do​

  • Don't fabricate a badge or a verdict. If the CLI isn't available or fails, say so plainly rather than describing the agent as badged.
  • Don't put "approved for X" claims into a badge yourself. Capability claims only count if they come from an actual evaluation (GraphSmith-backed, via viaid eval) — a self-declared capability has no verification weight.
  • Don't wrap every internal function call in log. That's noise, not a record.

If you also have GraphSmith or KnoSky installed​

viaid eval (capability evidence) and the org-side commands (scan, gate — see the CLI reference) need GRAPHSMITH_HOME / KNOSKY_HOME pointed at those projects. init, log, rotate, and verify work standalone with zero dependencies and zero network calls regardless — that's the point of the offline-first design. If evaluation isn't available, say so plainly rather than skipping the step silently.