Skip to main content

agent-custody (Python)

Signed, verifiable receipts for AI agent tool calls, from Python. The key, the Cedar policy, and the Merkle log live in the agent-custody sidecar, a local process from the npm package; this client talks to it over HTTP with the standard library only.

npm install -g @agent-custody/receipts && agent-custody keygen --dir keys --name app
agent-custody serve --config sdk.json          # loopback, port 8788
pip install agent-custody
from agent_custody import Client, PolicyDeniedError

client = Client()                                # http://127.0.0.1:8788/
refund = client.wrap("stripe.refund", lambda args: stripe.refund(**args))
refund({"amount": 5000})                         # decide, run, record; raises PolicyDeniedError on deny

Adapters, each tested against the real package: agent_custody.langchain.ReceiptCallbackHandler (record-only), agent_custody.crewai.wrap_tools (enforce: each CrewAI tool becomes a CustodyTool with the same name, description, and schema whose run is decided, executed, and recorded; a denial is returned as the tool result), agent_custody.openai_agents.wrap_tools (enforce and record), agent_custody.claude_agent_sdk.claude_hook (PreToolUse deny, PostToolUse record), agent_custody.hermes (a Hermes Agent plugin: pre_tool_call block, post_tool_call record; the drop-in plugin directory is hermes-plugin), agent_custody.adk.adk_callbacks (Google ADK: before_tool_callback skips a denied tool and hands the model the receipt, after_tool_callback records; LlmAgent(..., **adk_callbacks(client)); extra adk, which installs google-adk[a2a]). Receipts are verified by the TypeScript verifier; the tests do exactly that. An ADK agent's delegations to other agents over A2A are not tool calls and pass no callback; the gateway's A2A front, agent-custody gateway --a2a, covers them, and tests/test_adk_a2a.py runs ADK's own RemoteA2aAgent through it.

The memory tools. agent_custody.memory.MemoryClient (extra memory) talks to the shared memory server from @agent-custody/state over MCP: write, read, retract, history. Writes from here are claimed, quarantined until a gateway confirms them, and reads leave quarantined facts out unless asked; that is the honest position of an agent that did not go through the gateway.

async with MemoryClient("http://127.0.0.1:8790/mcp", token=os.environ["MEMORY_DIRECT_TOKEN"]) as memory:
    await memory.write("acct:42", "plan", "pro", space="team:support", actor="py-agent")
    await memory.read(subject="acct:42", include_claimed=True)

Everything recorded is claimed: the sidecar trusts what this process reports, the same as the in-process TypeScript SDK. For enforcement the agent cannot skip, put the gateway in front of the tools instead; it is an MCP server and needs nothing from this package.

The verifier. agent_custody.verify (extra verify, which installs cryptography for Ed25519) checks a receipt bundle against the public keys you trust, with no sidecar and no network. It is written from the receipt specification, not ported from the TypeScript verifier; the financial-operation checks, which the specification does not name, follow src/verify.ts. tests/test_verify.py runs every conformance vector and compares the failing checks by name, and it holds the verifier to the TypeScript verdicts on receipts that tests/cross_language.mts issues with the TypeScript code for cases the vectors do not cover.

pip install 'agent-custody[verify]'
agent-custody-verify receipts/<id>.json --issuer-key gateway.pub --principal-key principal.pub --log log.jsonl
from agent_custody.verify import Trust, load_public_key, read_log, verify_bundle
report = verify_bundle(bundle, Trust(issuer=[load_public_key(pem)]), log=read_log("log.jsonl"))
report.ok, report.failing

It does not decrypt or restore withheld fields: a receipt under a capture rule verifies as committed, as it does in the TypeScript verifier without --capture-key-env or --disclose.

uv run --extra test pytest        # from packages/python; starts a sidecar with node from ../receipts

Metadata

Release files for agent-custody 0.16.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-custody 0.16.8
File Size Uploaded Provenance Actions
agent_custody-0.16.8.tar.gz 446.4 kB With provenance Details for agent_custody-0.16.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-custody 0.16.8
File Interpreter ABI Platform Actions
agent_custody-0.16.8-py3-none-any.whl Python 3 none any Details for agent_custody-0.16.8-py3-none-any.whl

Total release size: 481.7 kB

Release files / agent_custody-0.16.8.tar.gz

Download URL agent_custody-0.16.8.tar.gz
Size 446.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7c6f2a861632db6191839381f8fd9afc006f318741ca2fbdabd18d6333cd8a85
BLAKE2b-256 checksum
How to use checksums
894268e518de973cbd95b33bdb7ac7c5d61d15bcc7c6b9faa4e44413b333404c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / agent_custody-0.16.8-py3-none-any.whl

Download URL agent_custody-0.16.8-py3-none-any.whl
Size 35.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7fe9800921e5f2f50c7199a82c55ade5b2b59a3a40379ffa9aea77538065cd4b
BLAKE2b-256 checksum
How to use checksums
2569b0aa8a770895f723c66ea7d4c924b2b507c36f277a21399d0dc511d3550b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for agent-custody 0.16.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agent_custody-0.16.8.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.16.8 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page