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

• ✅ You need compliance audit trails (HIPAA, SOC 2, GDPR)
• ✅ You want to debug agent behavior in production
• ✅ You need to prove who authorized specific actions
• ✅ You're building systems where accountability matters

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

• API key
• Agent Passport ID
• Delegation token (to prove authorization)
• Understanding of what actions need tracking

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

• All high-risk actions (financial transactions, data modifications)
• Human approval decisions (approve/reject with reasoning)
• Escalations (when agents defer to humans)
• Errors and failures (with context for debugging)
• Access to sensitive data (who accessed what, when)

Log Quality

• Include full context - input, output, delegation, risk level
• Use structured data - avoid free-form text logs
• Timestamp precisely - use UTC and include milliseconds
• Capture model details - which AI model, version, confidence
• Log synchronously - don't lose logs due to async failures

Performance

• Batch logging for high-frequency actions
• Use async writes where latency matters
• Set retention policies based on compliance needs
• Index by common query patterns (actor, resource, time)

Security Considerations

Common Patterns

Pattern: Auto-Logging Wrapper

function withProvenance<T>(
  agent: Agent,
  action: string,
  fn: () => Promise<T>
): Promise<T> {
  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

• Human-in-Loop - Log all human decisions
• Multi-Agent Workflow - Track workflow steps
• Delegate Access - Provenance shows delegation usage
• Audit capability grants

See Also

• Provenance Chain Deep Dive — ledger, verification, audit trails
• Provenance Core Concept
• Provenance API Reference