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.3 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.0rc2? The breaking changes in 1.0.0rc3 are listed in MIGRATION-1.0-rc.2-to-rc.3.md.

Pythonic surface conventions apply:

  • constructor config uses signer_address
  • 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.0rc3

For development:

pip install -e ".[dev]"

Platform support

Since 1.0.0rc3 the SDK depends on did-webvh, which pulls the native aries-askar library. aries-askar ships wheels for Linux glibc (x86_64, aarch64), macOS and Windows x86_64 only, so the SDK does not install on Alpine (musl) images or Windows ARM64. Use a glibc-based image such as python:3.12-slim.

Quick Start

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

async def main():
    AgentIdentity.set_registry(InMemoryAgentRegistry())
    identity = AgentIdentity(AgentIdentityConfig(signer_address="0xYourWalletAddress"))

    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.

Features

Feature API Status
Create Agent-DID document identity.create(params) ✅
Sign messages (Ed25519) identity.sign_message(payload, key) ✅
Sign HTTP requests (Bot Auth) 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) AgentIdentity.verify_http_request_signature(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) ✅
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 ✅
EVM registry adapter EvmAgentRegistry + Web3AgentRegistryContractClient ✅
Universal resolver (HTTP/RPC/IPFS) UniversalResolverClient ✅

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
registry.* Agent registry (in-memory, EVM adapter, Web3 client)
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

If a deployment explicitly needs the deferred EVM profile, connect the SDK to a real on-chain AgentRegistry contract:

from web3 import HTTPProvider, Web3

from agent_did_sdk import AgentIdentity, EvmAgentRegistry, Web3AgentRegistryContractClient
from agent_did_sdk.registry.evm_types import EvmAgentRegistryAdapterConfig

provider = Web3(HTTPProvider("http://127.0.0.1:8545"))
contract = provider.eth.contract(address=REGISTRY_ADDRESS, abi=ABI)

registry = EvmAgentRegistry(
    EvmAgentRegistryAdapterConfig(
        contract_client=Web3AgentRegistryContractClient(contract),
        await_transaction_confirmation=True,
    )
)

AgentIdentity.set_registry(registry)

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

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 contracts
npm ci

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.0rc3

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.0rc3
File Size Uploaded Provenance Actions
agent_did_sdk-1.0.0rc3.tar.gz 86.9 kB With provenance Details for agent_did_sdk-1.0.0rc3.tar.gz

Built distribution (wheel)

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

Total release size: 149.7 kB

Release files / agent_did_sdk-1.0.0rc3.tar.gz

Download URL agent_did_sdk-1.0.0rc3.tar.gz
Size 86.9 kB
Tags Source
SHA-256 checksum
How to use checksums
779d20ce40e0655cb8f7978649d44ca6668107fcf2b470900efd0a8bfc4c421c
BLAKE2b-256 checksum
How to use checksums
a82b8c2bbe07f74bd47c72bafcb24c79fbb10da912a702ee99cb46f10b88b2d2
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 3, 2026.

Transparency log

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

Download URL agent_did_sdk-1.0.0rc3-py3-none-any.whl
Size 62.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
141b6a748dd91abfa46687d2f7e1cc2be8fd34f2189555e0ed67b7f57f540f24
BLAKE2b-256 checksum
How to use checksums
35400f2999452e0b510002527e5fda9358df34fe3eba986aa32c86a4d04e24c8
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 3, 2026.

Transparency log

Security for agent-did-sdk 1.0.0rc3

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.0rc3.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 3, 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