Provenance & Attribution

Agent Commons records a lightweight provenance trail for agent and workflow runs by default. The trail is written asynchronously so it does not sit between the model, tools, and the user.

The Sources view is designed for everyone: it lists the websites used, the search query and provider, agent contributions, workflow decisions, and library similarity matches. The switchable Trajectory view adds timing, tokens, hashes, tool payload structure, and EAA actions for reviewers and developers.

What is recorded

• Web research: tool/provider, query, ranked canonical URLs and domains, titles, publication metadata, retrieval time, and evidence hashes.
• Workflows: workflow/version/definition hash, execution and node IDs, node type, status, timing, observable branch decisions, and parent workflow links.
• Multi-agent work: delegating and receiving agent IDs, role, architecture, handoff/context policy, and the child run's own model and tool trail.
• Library retrieval: original item/session/source, content hash, ranking, hybrid search weights, normalized score, and human-readable percentage match.
• Models and tools: provider/model, token usage, cost, duration, status, inputs/outputs commitments, and correlation spans.
• Human approvals: the requesting agent or workflow, authenticated reviewer, prompt/question IDs, available choices, approve/reject outcome, reason, response field names, timing, and a safe response commitment.
• Embeddings: content hash, model, dimensions, normalization version, computing system, and a deterministic cache key. Vectors are not placed in the report.

Private chain-of-thought is never recorded. Credential-shaped fields—including approval and permission tokens—are redacted before hashing or persistence. Approval response values remain subject to the selected capture mode; the default report uses field names and a safe commitment rather than exposing the values.

Capture policy

metadata is the default. It retains attribution facts and structural/hash descriptions without storing complete prompts or outputs. full is an explicit per-run choice and still redacts secrets and private reasoning. off disables capture for that run.

await commons.run.once({
  agentId,
  messages: [{ role: "user", content: "Research this topic" }],
  provenance: { mode: "metadata", onchain: false },
});

On-chain anchoring is a separate opt-in. Agent Commons keeps the useful report off-chain and submits only the verifiable bundle commitment when the environment and user both enable anchoring.

Shared embeddings with ProvenanceKit

Agent Commons and ProvenanceKit use a compute-once, index-where-needed contract. An embedding is reusable only when the content hash, model/version, dimensions, and normalization version all match. The receiving system may retain its own permission-scoped index, but it imports the verified vector instead of recomputing it. Missing, incompatible, or untrusted embeddings fall back to the configured local provider. This keeps both systems independently pluggable while avoiding duplicate inference.

SDK reports and export

const { data: report } = await commons.provenance.session(sessionId);
const { data: workflow } = await commons.provenance.scope(
  "workflow",
  executionId,
);
const { data: eaaBundle } = await commons.provenance.bundle(traceId);

The EAA bundle is portable ProvenanceKit data; it includes entities, resources, actions, attributions, and Agent Commons lineage extensions.

CLI

agc run --agent <agentId> --provenance metadata "Research this"
agc run --agent <agentId> --provenance full "Audit this" # explicit raw capture
agc provenance session <sessionId>
agc provenance workflow <executionId>
agc provenance bundle <traceId> > provenance.json

Use --onchain-provenance only when you intentionally want an anchor and the connected environment supports it.