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.5release train and RFC-001 is now treated as Stable text. Finalv1.0.0publication 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 from1.0.0rc3? The breaking changes in1.0.0rc5are listed in MIGRATION-1.0-rc.3-to-rc.5.md; from1.0.0rc2, see MIGRATION-1.0-rc.2-to-rc.3.md first.
Pythonic surface conventions apply:
- constructor config uses
controller_signer(an Ed25519AgentSigner) - 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.Zfor PyPI,workflow_dispatchfor 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
versioninpyproject.toml - run the workflow manually with
repository=testpypito validate the package on TestPyPI - publish to PyPI by pushing a tag named
sdk-python-vX.Y.Z - alternatively, run the workflow manually from
mainwithrepository=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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.