agent-custody

agent-custody

Chain of custody for AI agents: a signed receipt for every tool call, checkable with public keys alone. What each check proves, and against whom, is a table below.

Two producers, one receipt format, one verifier.

• The gateway is an MCP proxy between an agent and the systems it can affect: MCP servers, REST APIs described as tools, and other agents it delegates to over A2A. For every tool call, allowed or denied, it checks a delegation grant signed by the human principal and any required human approval of the exact arguments, gathers the facts the policy needs by calling upstream itself, evaluates a Cedar policy that fails closed, forwards the call only on allow, and emits a signed receipt appended to a Merkle transparency log.
• The SDK is an interceptor inside the agent's own process, hooked into the framework's tool-call callbacks: Claude Code, the Claude Agent SDK, the OpenAI Agents SDK, the Vercel AI SDK, OpenClaw, DeepSeek Harness, Hermes, Google ADK, LangChain, or any function you wrap. It reaches everything the gateway cannot see and issues the same receipts, labelled as self-reported.

Anyone holding the public keys can verify a receipt offline. The agent is not trusted. The layer around it is, and the receipt says exactly how far that trust extends, starting with who issued it. What the receipt file carries of a call is a choice per tool: a field can be withheld as a commitment or encrypted under your key, and the verifier recomputes the digests when it is shown the values.

• Reference: every function, endpoint, MCP tool, and command with its request and response
• Tutorials: runnable examples, one per aspect of the code, all executed by the test suite
• Financial operations: durable operation ids, provider idempotency keys, atomic daily budget reservations, and reconciliation receipts for uncertain outcomes
• The gateway console: an admin service for the person who runs a gateway: config, tools, receipts with a verdict each, a policy editor that replays recorded calls before it saves, grant revocation, and an audit trail
• Configuring the gateway: who may use which tools and where the tools live, a worked example with two agents, the Docker image, and agent-custody check to validate a config before it starts
• Usage guide: gateway setup, wiring into Claude Desktop, Claude Code, or your own agent loop, and the gateway as an A2A agent between agents that delegate to each other, private evidence: what the receipt file carries of each call, and searching receipts and exporting offline cases with the state package's review console
• Live Codex recovery demo: a real support agent, incorrect CRM memory, operator-reviewed compensation, and verified receipts; an opt-in live run with offline regression coverage
• Human approvals: short-lived signatures over the exact action, two-person thresholds, single-use enforcement, and offline verification
• The interceptor SDK: Claude Code hooks, the Claude Agent SDK, adapters for the OpenAI Agents SDK, Vercel AI SDK, LangChain, OpenClaw and DeepSeek Harness, a Hermes Agent plugin and Google ADK callbacks through the Python package, and wrapping tool functions in anything else
• Writing policies: how a tool call becomes a Cedar request, with tested examples, and replaying history against a proposed policy with policy simulate
• Verifying a receipt: what each check means and what a verified receipt does and does not prove
• What the evidence satisfies: the receipts, packs, and certificates mapped to SOC 2, ISO 27001, UK GDPR, the EU AI Act, FINRA, MAS, Colorado, DORA, the CSA AI Controls Matrix, the OWASP agentic guidance, and ISO/IEC 42001. Each regulation has a primary source, an "as of" date, and a list of what a receipt does not supply
• Anchoring the log on a chain: the log's checkpoints committed to Ethereum mainnet, or another EVM chain the installation picks, from a published address, what that proves and what it does not, running the anchor, and log-check against the chain
• Receipts on a pull request: the GitHub Action that verifies a directory of receipt bundles and posts one table on the pull request, the workflow file to copy, the export command that copies the receipts into the branch, and why a committed receipt publishes the call unless a capture rule withholds it
• Completeness: an auditor's read-only key lists the provider's objects and matches each to a verified receipt, so an action taken outside the gateway shows up
• Payment mandates and agent identity: the design for fitting grants and receipts to Google's AP2 mandates, Visa's Trusted Agent Protocol and Mastercard Agent Pay; not yet built
• Threat model: every party who could make a receipt false, the move, what stops it, and whether that is a property of the evidence or of the deployment; and what is not defended
• Aligning with IETF SCITT: the receipt as a SCITT signed statement, the log as a transparency service, our RFC 9162 proofs as COSE Receipts (RFC 9942), what differs and the options for each, an agent-action profile, and the steps toward the working group

Getting started

npm install @agent-custody/receipts        # or bun add, pnpm add

Published on npm as @agent-custody/receipts: compiled JavaScript with type declarations, Node 22 or later, Apache-2.0.

Record receipts from inside your own agent, no gateway needed. Generate a signing key, point a config at it, wrap the functions the agent calls:

npx @agent-custody/receipts keygen --dir keys --name app

{ "agentId": "billing-bot", "identity": { "keyFile": "keys/app.key" }, "receiptsDir": "receipts", "logFile": "log.jsonl" }

import { createSdkIssuer, loadSdkConfig, loadPublicKey, verifyBundle } from "@agent-custody/receipts";

const issuer = createSdkIssuer(loadSdkConfig("./sdk.json")); const refund = issuer.wrap("stripe.refund", async (args: { amount: number }) => stripe.refund(args)); await refund({ amount: 5000 }); // one signed receipt in receipts/, one leaf in log.jsonl

const bundle = JSON.parse(readFileSync("receipts/ .json", "utf8")); verifyBundle(bundle, { issuerKeys: [loadPublicKey("keys/app.pub")], logFile: "log.jsonl" }).ok; // true

For your own Claude Code sessions, one command does the whole setup (key, config in observe mode, starter deny policy, hooks), and agent-custody report lists the calls the policy would have denied: npm install -g @agent-custody/receipts, then agent-custody init claude-code, then see docs/sdk.md.

Framework hooks and adapters, including Claude Code, the OpenAI Agents SDK, the Vercel AI SDK, LangChain, OpenClaw, DeepSeek Harness, Hermes and Google ADK, are in docs/sdk.md. To enforce rather than record, put the gateway between the agent and its tools: npx @agent-custody/receipts gateway --config gateway.json, set up in docs/usage.md; between an agent and the agents it delegates to over A2A, --a2a serves the gateway as an A2A agent itself. The gateway is listed in the MCP Registry as io.github.svayatta/agent-custody; its entry is server.json, published after each npm release by running the mcp-registry workflow from the Actions tab (GitHub OIDC, no token).

How it fits together

The architecture guide adds the customer-side and hosted split, the data model, and sequence diagrams for onboarding, revocation, and verification.

flowchart LR

P["Principal (human or org, holds a signing key)"] A["Agent host Claude Desktop, Claude Code, LangGraph, custom loop"] S["SDK interceptor inside the agent process: hooks or wrapped tools"] G["agent-custody gateway scope check → fact lookups → Cedar policy"] U["Upstream MCP server Stripe, database, GitHub, ..."] R[("receipt bundles receipts/*.json")] L[("Merkle log local file, or a remote log run by someone else")] V["Verifier auditor, counterparty, CI job"] O["Observability OTel, Splunk, LangSmith, Arize"]

P -- "signed delegation grant" --> G A -- "MCP tools/call" --> G G -- "only on allow" --> U U -- "result" --> G G -- "result + receipt id, or denial + receipt id" --> A G -- "signed receipt (issuer: gateway)" --> R G -- "leaf hash" --> L A -. "in-process tool calls" .-> S S -- "signed receipt (issuer: sdk)" --> R S -- "leaf hash" --> L R --> V L -. "copy of the log (optional)" .-> V P -. "public key" .-> V G -. "public key" .-> V A -. "traces (unchanged)" .-> O G -. "one span per receipt, OTLP" .-> O S -. "one span per receipt, OTLP" .-> O

Three parties hold keys. The principal signs a grant saying which agent may use which tools until when. The issuer, gateway or SDK, signs every receipt and every tree head. The verifier holds only public keys and needs no access to the issuer, the agent, or the upstream system.

Two producers, one receipt

Every receipt names its issuer, and the verifier prints what that issuer kind is worth before anything else. A dashboard full of sdk rows is the reason to route the consequential calls through the gateway.

Supported hosts and frameworks

| Google ADK | sidecar + [Py