Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

agent-did-sdk (Python)

Python SDK for the Agent-DID Specification (RFC-001) — create, sign, resolve, verify and revoke Agent-DIDs.

Functional parity with the TypeScript SDK (@agentdid/sdk), with a dedicated Python CI pipeline and shared interoperability fixtures.

Formal parity tracking is documented in ../docs/F2-01-TS-Python-Parity-Matrix.md.

Release-candidate note: The repository is frozen for the 1.0.0-rc.5 release train and RFC-001 is now treated as Stable text. Final v1.0.0 publication still depends on the remaining gates in ../docs/RELEASE-1.0-CRITERIA.md.

Moving from 0.x? See MIGRATION-0.x-to-1.0.md. Coming from 1.0.0rc3? The breaking changes in 1.0.0rc5 are listed in MIGRATION-1.0-rc.3-to-rc.5.md; from 1.0.0rc2, see MIGRATION-1.0-rc.2-to-rc.3.md first.

Pythonic surface conventions apply:

  • constructor config uses controller_signer (an Ed25519 AgentSigner)
  • instance methods use snake_case
  • lifecycle-wide operations such as revoke/update/rotate/resolve remain class methods on AgentIdentity

Installation

pip install agent-did-sdk==1.0.0rc5

For development:

pip install -e ".[dev]"

RFC 3161 timestamp tokens (verify_timestamp_token, create_timestamp_request and the timestamp_token option of verify_signature_at_time) need the optional extra, which adds rfc3161-client (no Windows ARM64 wheel):

pip install "agent-did-sdk[timestamps]==1.0.0rc5"

The optional EVM registry adapter is a separate package, agent-did-evm, maintained in edisonduran/agent-did-evm. Up to 1.0.0rc4 it shipped here as agent_did_sdk.evm (extra [evm]).

Platform support

Platform Status
Linux glibc x86_64 and aarch64 (for example Debian, Ubuntu and the python:*-slim images) Supported
macOS arm64 Supported
Windows x86_64 Supported
Alpine Linux (musl) Does not install
Windows ARM64 Does not install

Since 1.0.0rc3 the SDK depends on did-webvh, the did:webvh v1.0 reference implementation, which requires the native aries-askar library. aries-askar publishes wheels for Linux glibc (x86_64, aarch64), macOS and Windows x86_64 only, and no source distribution, so pip install agent-did-sdk fails on Alpine and Windows ARM64. The limit comes from that upstream dependency; the SDK's own dependencies have wheels there. On containers, use a glibc-based image such as python:3.12-slim.

The CI — Python Platform Support workflow checks this table every night: it installs the SDK and runs a smoke test on each supported platform, and requires the install to fail on the other two because of aries-askar, so the table is updated as soon as that changes.

Quick Start

import asyncio
from agent_did_sdk import (
    AgentIdentity,
    AgentIdentityConfig,
    CreateAgentParams,
    InMemoryAgentRegistry,
    LocalKeySigner,
)

async def main():
    AgentIdentity.set_registry(InMemoryAgentRegistry())
    identity = AgentIdentity(AgentIdentityConfig(controller_signer=LocalKeySigner.generate()[0]))

    result = await identity.create(CreateAgentParams(
        name="MyAgent",
        core_model="gpt-4-turbo",
        system_prompt="You are a helpful assistant.",
        capabilities=["search", "code-execution"],
    ))

    print(f"Agent DID: {result.document.id}")
    print(f"Private Key: {result.agent_private_key}")

    # Sign a message
    signature = await identity.sign_message("Hello, World!", result.agent_private_key)

    # Verify
    is_valid = await AgentIdentity.verify_signature(
        result.document.id, "Hello, World!", signature
    )
    print(f"Valid: {is_valid}")

asyncio.run(main())

This quickstart validates the local signing lifecycle first. By default the SDK follows the canonical did:webvh path and bootstraps the local controller side for you; hosted publication of did.jsonl is a separate deployment concern.

Since 1.0.0rc3, did:webvh DIDs are did:webvh v1.0 DIDs: the did.jsonl log has a self-certifying SCID and every entry is signed by the controller key, through the DIF reference implementation did-webvh. CI runs the pinned DIF didwebvh-test-suite vectors against the SDK's did:webvh layer. See MIGRATION-1.0-rc.2-to-rc.3.md for the explicit profile's controller_signer and for re-issuing older DIDs.

An agent's controller does not have to be an Agent-DID document: any DID Core did:webvh document works, for example your organization's DID created with another did:webvh tool (RFC-001 §4.2.1). Pass it as CreateDidWebvhOptions.controller_did with a controller_signer whose key the controller lists under capabilityInvocation. resolve_document(did) returns such a document; resolve(did) returns Agent-DID documents only.

Features

Feature API Status
Create Agent-DID document identity.create(params) ✅
Sign messages (Ed25519) identity.sign_message(payload, key) ✅
Sign HTTP requests (RFC 9421) identity.sign_http_request(params) ✅
Verify message signatures AgentIdentity.verify_signature(did, payload, sig) ✅
Enforce key purpose binding assert_key_purpose(key_id, did_doc, purpose) ✅
Verify HTTP signatures (RFC 9421, replay protection via NonceStore; the default store is per process, pass a shared one when several instances verify) AgentIdentity.verify_http_request_signature(params) ✅
Verify HTTP signatures, with the reason of a rejection client.verify_http_request_signature_detailed(params) ✅
Resolve DID → document AgentIdentity.resolve(did) ✅
Revoke DID AgentIdentity.revoke_did(did) ✅
Update document AgentIdentity.update_did_document(did, patch) ✅
Rotate verification keys AgentIdentity.rotate_verification_method(did) (emergency=True also revokes the old keys) ✅
Retire or revoke one key client.retire_verification_method(did, key_id, emergency=...) ✅
Signed A2A Agent Cards (composition contract) sign_agent_card(card, signer, key_id), client.verify_agent_card(card), client.verify_identity_composition(params) ✅
Document history/audit AgentIdentity.get_document_history(did) + AgentIdentity.export_did_webvh_history(did) + AgentIdentity.import_did_webvh_history(log) + AgentIdentity.save_did_webvh_history_to_file(did, path) + AgentIdentity.load_did_webvh_history_from_file(path) + AgentIdentity.persist_did_webvh_history_to_source(did, ref, source) + AgentIdentity.restore_did_webvh_history_from_source(ref, source) ✅
Filesystem storage adapter FilesystemDIDDocumentSource ✅
Remote HTTP storage adapter HttpDIDDocumentSource (store_by_reference, get_did_log_by_reference, store_did_log_by_reference) ✅
Authenticated HTTP gateway adapter BearerTokenHttpDIDDocumentSource ✅
Presigned/object-storage adapter PresignedHttpDIDDocumentSource ✅
S3-compatible object-store adapter S3CompatibleDIDDocumentSource ✅
AWS SigV4 S3 adapter AwsSigV4S3DIDDocumentSource ✅
Universal resolver (HTTP/RPC/IPFS) UniversalResolverClient ✅
Agent metadata credential (VC 2.0, eddsa-jcs-2022, RFC-001 §4.4; the controller signs, verification checks issuer, binding and proof) client.issue_agent_metadata_credential(params) / client.verify_agent_metadata_credential(credential) ✅
Capabilities: delegation and HTTP invocation (RFC-001 §6.7; no per-capability revocation, keep expires short) client.create_capability(...), client.verify_capability_chain(capability, root_controllers=...), SignHttpRequestParams(capability=...), client.verify_http_capability_invocation(params) ✅
OAuth client assertion with the DID key (private_key_jwt, RFC-001 §6.8; the SDK runs no OAuth flow) create_client_assertion(...), build_client_jwks(document), build_client_metadata_document(...), client.verify_client_assertion(...) ✅

By default, verify_signature and HTTP signature verification require the signing key to be listed under assertionMethod in the DID document. Passing a key that exists only under another relationship, including keyAgreement, raises IdentityCompositionError with reason key_purpose_violation.

Modules

Module Description
core.types Pydantic models for RFC-001 (AgentDIDDocument, etc.)
core.identity AgentIdentity — main class for DID lifecycle
core.time_utils ISO-8601 ↔ Unix timestamp utilities
crypto.hash SHA-256 hashing with hash:// URI format
crypto.data_integrity eddsa-jcs-2022 Data Integrity proofs (W3C vc-di-eddsa vectors in CI)
core.agent_metadata_credential AgentMetadataCredential profile (RFC-001 §4.4)
core.capability Capabilities: form, chain and attenuation checks, Agent-DID-Capability field (RFC-001 §6.7)
core.oauth_client OAuth client assertion, JWKS and Client ID Metadata Document (RFC-001 §6.8)
registry.* Agent registry (in-memory)
resolver.* DID resolver (in-memory, filesystem source, HTTP source, bearer/authenticated HTTP source, presigned/object-storage source, S3-compatible source, AWS SigV4 S3 source, JSON-RPC source, universal)

Optional EVM Registry Integration

The core SDK has no EVM dependency. The optional adapter agent-did-evm (import agent_did_evm) is maintained with the on-chain AgentRegistry contract in edisonduran/agent-did-evm; see its README for the wiring.

See full example: examples/evm_registry_wiring.py

Production Resolver

Configure a production-grade resolver with failover and caching:

from agent_did_sdk import AgentIdentity, ProductionHttpResolverProfileConfig

AgentIdentity.use_production_resolver_from_http(
    ProductionHttpResolverProfileConfig(
        registry=evm_registry,  # optional when using the EVM compatibility profile
        cache_ttl_ms=60_000,
        ipfs_gateways=["https://gateway.pinata.cloud", "https://ipfs.io"],
        on_resolution_event=lambda event: print("Resolution:", event.stage),
    )
)

Minimal did:wba example: examples/did_wba_resolution.py

A did:webvh log imported with import_did_webvh_history is a copy, not an authority. With a resolver that fetches logs (the production resolver), the next resolution fetches the host's log at once and the longer of the two wins; if the host cannot be reached, the resolution fails closed. The imported log is used as is only when the resolver does not fetch logs (the in-memory default); then nothing tells an older copy (for example one from before a revocation) from the current log, so import logs only from a source you trust to be current.

did:webvh witnesses and RFC 3161 timestamps

Witnesses (ADR-007): create with CreateDidWebvhOptions(..., witness=DidWebvhWitnessConfig(threshold=2, witnesses=["did:key:z6Mk...", "did:key:z6Mk..."])), change with client.set_did_webvh_witnesses(did, rule_or_None), and give the client AgentDidClientOptions(collect_witness_proofs=...), an async function that returns each witness's approval (a witness signs with create_did_webvh_witness_proof). Publish client.export_did_webvh_witness_file(did) as did-witness.json before did.jsonl. The production resolver fetches it and fails closed when the approvals do not reach a threshold. Watchers are not supported.

Timestamps: verify_signature_at_time(..., stated_time=..., timestamp_token=tsr, tsa_trust_anchors=[tsa_root_pem]) verifies an RFC 3161 token over the raw signature bytes and uses genTime + accuracy as trusted time evidence; a token that does not verify gives reason="timestamp_invalid" and timestamp_rejection. create_timestamp_request(signature_bytes) builds the request; sending it to a TSA is up to you. Revocation of TSA certificates is not checked.

Testing

Canonical local workflow:

cd sdk-python
python -m pip install -e ".[dev]"
ruff check src/ tests/ scripts/
mypy --strict src/
pytest --cov=agent_did_sdk --cov-fail-under=85 -q

Repository-level convenience wrappers are also available from the repo root:

npm run python:test
npm run python:conformance

These npm commands are only monorepo shortcuts. The canonical Python commands remain the native python, pytest, ruff, and mypy commands shown above.

For end-to-end web-native publication and hosted DID history flows, see the examples under examples/ that exercise did:webvh, writable document sources, and external smoke targets.

cd sdk-python
pip install -e ".[dev]"
pytest --cov

RFC-001 Python conformance:

cd sdk-python
python scripts/conformance_rfc001.py

Operational smokes:

cd sdk-python
python scripts/rpc_resolver_smoke.py
python scripts/resolver_ha_smoke.py
python scripts/revocation_policy_smoke.py
python scripts/e2e_smoke.py

Maintainer Release to PyPI

The repository includes .github/workflows/publish-python-sdk.yml for PyPI Trusted Publishing.

Before the first release, create the agent-did-sdk project on PyPI and, optionally, TestPyPI, then register GitHub Trusted Publishers for:

  • repository: edisonduran/agent-did
  • workflow file: .github/workflows/publish-python-sdk.yml
  • workflow trigger: tag sdk-python-vX.Y.Z for PyPI, workflow_dispatch for TestPyPI or manual PyPI release

If you want GitHub environment approvals, add matching environments later and bind them in both GitHub and PyPI Trusted Publishing settings.

Release preparation:

cd sdk-python
python -m pip install -e ".[dev]"
python -m build
python -m twine check dist/*

Release flow:

  • bump version in pyproject.toml
  • run the workflow manually with repository=testpypi to validate the package on TestPyPI
  • publish to PyPI by pushing a tag named sdk-python-vX.Y.Z
  • alternatively, run the workflow manually from main with repository=pypi

License

Apache-2.0 — see root LICENSE.

Metadata

Release files for agent-did-sdk 1.0.0rc5

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-did-sdk 1.0.0rc5
File Size Uploaded Provenance Actions
agent_did_sdk-1.0.0rc5.tar.gz 240.4 kB With provenance Details for agent_did_sdk-1.0.0rc5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-did-sdk 1.0.0rc5
File Interpreter ABI Platform Actions
agent_did_sdk-1.0.0rc5-py3-none-any.whl Python 3 none any Details for agent_did_sdk-1.0.0rc5-py3-none-any.whl

Total release size: 397.5 kB

Release files / agent_did_sdk-1.0.0rc5.tar.gz

Download URL agent_did_sdk-1.0.0rc5.tar.gz
Size 240.4 kB
Tags Source
SHA-256 checksum
How to use checksums
2b6d5a68c8be29665ff50325d495e28c78ed33401fd07114f29eeace6ae52c6a
BLAKE2b-256 checksum
How to use checksums
bd56eb7e931c53f56172e65881260b555be050cc8ba5dbfc0bd12a41b7685b0d
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 16, 2026.

Transparency log

Release files / agent_did_sdk-1.0.0rc5-py3-none-any.whl

Download URL agent_did_sdk-1.0.0rc5-py3-none-any.whl
Size 157.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5d945761494f5516caefaed0cb11b8f553d489677e21727c369e0c2c23ed8c6
BLAKE2b-256 checksum
How to use checksums
8a39f71b23ae5cf3dbc2c7e7e6ce077f23a8da6a79f7a476ae37615b4c171b64
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 16, 2026.

Transparency log

Security for agent-did-sdk 1.0.0rc5

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_did_sdk-1.0.0rc5.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 16, 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
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