Verdra Record · SDK

Add Verdra to one agent action in under 10 lines.

Wrap any agent action with @record.capture(...). The SDK seals a four-strata Evidence Package before the action returns, signs it with your key, and writes it to your storage. Nothing leaves your environment.

Inspect a packet A signed sample Evidence Package, ready for your editor.

V0.1 schema, four strata (transaction, configuration, behavior, mandate), customer-held key, deferred RFC 3161 timestamp. Drop the file into your editor to see exactly what an Evidence Package looks like before you wire one up.

Download sample .ep.json See the verify command

1. Install

Python · verdra-recordfrom source · works today
# requires Python 3.11+
# clone the verdra repo, then:
pip install -e ./sdk/python/verdra-record
Python · verdra-recorddirect from git
# with repo credentials configured:
# repository URL provided per engagement
pip install verdra-record
Python · verdra-recordafter PyPI release
# PyPI release follows V0.1 schema freeze:
pip install verdra-record
TypeScript · @verdra/recordplanned
// a TypeScript package tracking the Python schema is planned,
// not yet published. The Python SDK is the reference today.

2. Quickstart, Python

Wrap any agent action with @record.capture(...). The SDK reads the runtime configuration at the call site, runs the four-strata capture, signs the package with your customer-held key, and writes it to your storage.

Python · LangGraph runtimequickstart.py
from verdra_record import Record
from langgraph.graph import StateGraph

# customer-held signing key + customer-controlled storage
record = Record(
    principal="Orion Treasury Corp.",
    storage="s3://orion-evidence/verdra/",
    signing_key="./orion.ed25519.priv",   # or raw 32-byte seed
    schema_version="verdra/v0.1",
)
# Production engagements wire signing through KMS (AWS KMS, GCP KMS,
# Azure Key Vault, or HSM); see /security for the integration pattern.

@record.capture(
    strata=["a", "b", "c", "d"],
    configuration={"model": "claude-sonnet-4-5", "tools": ["pay"], "spend_cap": "5000 USDC/day"},
    mandate={"delegation": "dlg_4b2e", "scope": ["pay", "ship"], "expires": "2026-12-31"},
)
def issue_payment(graph: StateGraph, mandate: dict) -> dict:
    # your existing agent logic, unchanged
    return graph.invoke(mandate)

# every call produces a signed Evidence Package in your bucket
result = issue_payment(graph, mandate={"to": "vendr-fulfill-2", "amount": "1847.20 USDC"})
# result["_verdra_package_id"] => "EP-..."  (also retrievable via the SDK return)
V0.1 → V1.0 Today (V0.1): the Python SDK is wired to your runtime during onboarding, signs with a customer-held Ed25519 key, persists to file:// or s3:// storage, and verifies offline. The schema is frozen in the public Rules; the integration surface is what gets tailored. Framework-specific adapters and RFC 3161 timestamping are forward commitments under Rules P.5; the timestamp limitation is disclosed in each package.

3. Quickstart, TypeScript

A TypeScript package is planned and not yet published. The shape below illustrates the intended surface; the Python SDK in section 2 is the reference today.

TypeScript · illustrativeplanned
import { Record } from "@verdra/record";
import { Agent, tool } from "@openai/agents";

const record = new Record({
  principal: "Orion Treasury Corp.",
  storage: "s3://orion-evidence/verdra/",
  schemaVersion: "v0.1",
});

const issuePayment = record.capture(async (mandate) => {
  const agent = new Agent({ name: "orion-procure-7" });
  return await agent.run(mandate);
});

// every call produces a signed Evidence Package in your bucket
await issuePayment({ to: "vendr-fulfill-2", amount: "1847.20 USDC" });

4. Runtime adapters

The base @record.capture(...) decorator works against any callable today, including in-house runtimes: hand the four strata in via configuration={...} and mandate={...} and the SDK signs, persists, and verifies. Framework-specific adapters are built per engagement against the same public schema, not shipped as a public catalog.

Base decoratorPY
@record.capture() The canonical V0.1 surface. Hand the four strata in via configuration={...} and mandate={...}; the SDK signs, persists, and verifies. Works against any callable, including in-house runtimes. Today
Framework adaptersper engagement
built to your runtime Idiomatic hook points for a specific runtime (for example LangGraph, or the OpenAI and Anthropic SDKs) are wired during an engagement, targeting the same public schema. They are not published as standalone packages. On contractual basis

5. Evidence Package shape

Every captured action produces an Evidence Package conforming to the public Verdra Rules schema. Top-level fields:

FieldTypeDescription
idstringContent address: EP- + first 32 hex chars (128 bits) of BLAKE3-256 over the canonical body, excluding id and signature.
schemastringSchema version pin, e.g. verdra/v0.1.
principalstringCustomer-supplied principal identifier; informational, not validated by the schema.
captured_atstringISO 8601 / RFC 3339 UTC timestamp at millisecond precision.
strata.aobjectTransaction stratum: counterparty, payload, rail, reference, timestamp.
strata.bobjectConfiguration stratum: prompt hash, tool inventory, model + version, spend caps at dispatch.
strata.cobjectBehavior stratum: self-reported decision trace by default; counterfactual re-derivation where the runtime supports it (forward-committed under Rules P.5), tool calls, latencies.
strata.dobjectMandate stratum: principal-signed delegation, scope, limits, expiry.
signed_withobjectAlgorithm + public key, bound into the signed canonical body. Tampering with either changes the recomputed id and breaks the signature. {algorithm: "ed25519", public_key: "ed25519:<hex>"}.
timestampobjectRFC 3161 timestamp token from an external authority. V0.1 records {mode: "deferred"} as a forward commitment per Rules P.5.
storageobjectCustomer-controlled storage URI. Verdra has no write path.
signatureobjectCustomer Ed25519 signature over the canonical body. {value: "<128-hex>"}; algorithm and pubkey live in signed_with so they are part of the signed bytes.

6. Verifying a package

Python · from your shellCLI verify
# anyone with the public key can verify, offline:
verdra-record verify ./EP-ed594af8f57ff7c6a5a290ea78b4ffc1.ep.json \
    --pubkey ./orion.ed25519.pub
# [OK] EP-...  schema=verdra/v0.1
#   signature_valid:        True
#   content_address_matches:True
#   timestamp_valid:        False  (RFC 3161 deferred, forward commitment per Rules P.5)
Python · verifying programmaticallyverify.py
from verdra_record import verify_package

# adjudicators, counsel, auditors, or counterparties can verify offline
# using only the public schema and the customer's pubkey.
result = verify_package(
    "./EP-ed594af8f57ff7c6a5a290ea78b4ffc1.ep.json",
    pubkey="./orion.ed25519.pub",    # raw 32 bytes, or "ed25519:<hex>" text form
)

assert result.signature_valid
assert result.content_address_matches
# result.timestamp_valid is False in V0.1 (TSA deferred); see notes:
for note in result.notes:
    print(note)

7. What the SDK does not do