Provenance Tracking

# Provenance Tracking

Create verifiable, immutable records of every AI action for compliance, debugging, and trust.

In a world where AI agents make consequential decisions, knowing exactly what happened, who authorized it, and why is critical. This pattern shows you how to implement comprehensive provenance tracking for all agent actions.

When to Use This

Architecture

┌─────────────────────────────────────────────────────┐
│              AI Agent Action                         │
│   (process invoice, approve transaction, etc.)      │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
          ┌──────────────────────┐
          │   Provenance Logger  │
          │   (captures context) │
          └──────────┬───────────┘
                     │
                     ▼
      ┌──────────────────────────────┐
      │   Provenance Entry           │
      │   - Who (Passport ID)        │
      │   - What (action)            │
      │   - When (timestamp)         │
      │   - Why (delegation/approval)│
      │   - Input/Output             │
      │   - Cryptographic signature  │
      └──────────┬───────────────────┘
                 │
                 ▼
    ┌────────────────────────────────┐
    │   Distributed Ledger           │
    │   (immutable, verifiable)      │
    └────────────────────────────────┘

Prerequisites

Implementation

Log Agent Actions

Record every significant action with full context:

Query Provenance History

Retrieve audit trails for compliance or debugging:

Verify Provenance

Cryptographically verify that a provenance entry is authentic and hasn't been tampered with:

Use Cases

Best Practices

What to Log

Log Quality

Performance

Security Considerations

Common Patterns

Pattern: Auto-Logging Wrapper

function withProvenance(
  agent: Agent,
  action: string,
  fn: () => Promise
): Promise {
  return client.provenance.trackAction({
    actor: agent.passportId,
    action,
    execute: async () => {
      const result = await fn();
      return result;
    },
  });
}
// Usage
const result = await withProvenance(
  invoiceAgent,
  'process_invoice',
  () => processInvoice(invoice)
);

Pattern: Provenance Chain

async function getProvenanceChain(resourceId: string) {
  const entries = await client.provenance.query({
    resource: resourceId,
    sortBy: 'timestamp',
    order: 'asc',
  });
  // Build dependency chain
  const chain = entries.map((entry, idx) => ({
    step: idx + 1,
    actor: entry.actor,
    action: entry.action,
    timestamp: entry.timestamp,
    authorized_by: entry.delegation?.grantedBy,
    verified: entry.ledgerRef !== null,
  }));
  return chain;
}

Provenance logging (alias)

/docs/patterns/humanos/provenance-logging is an alias of this page. Logging every action is the same contract: emit provenance with actor, action, delegation context, and ledger attestation — not a second API.

Related Patterns

See Also