openagent-oas

Python SDK for the Open Agent Specification (OAS) -- decentralized identity for autonomous entities.

openagent-oas implements the did:oas DID method, Ed25519 cryptographic lineage, document management, verifiable credential attestation, and DID resolution. It provides everything needed to create, derive, sign, verify, and resolve identities in the OAS ecosystem.

No network required. No blockchain required. No vendor lock-in.

from openagent.oas.sdk import create_hmr, derive_child, verify_chain
from openagent.oas.did import EntityKind
from openagent.oas.lineage import InMemoryProvider

# Create a Human Root identity
hmr = create_hmr("l1fe", "root", "2025-01-01T00:00:00Z")
print(hmr.document.id)  # did:oas:l1fe:hmr:root

# Derive an agent identity
agent = derive_child(
    parent_keypair=hmr.keypair,
    parent_document=hmr.document,
    namespace="l1fe",
    kind=EntityKind.AGENT,
    identifier="analyzer",
    derivation_path="agent/analyzer",
    created="2025-01-01T00:00:00Z",
)
print(agent.document.id)  # did:oas:l1fe:agent:analyzer

# Verify the lineage chain
provider = InMemoryProvider()
provider.add(hmr.document)
provider.add(agent.document)
await verify_chain(agent.document, provider)

Installation

pip install openagent-oas

Requires Python >= 3.12. Runtime dependencies: cryptography>=43.0, blake3>=1.0.

# With development dependencies
pip install openagent-oas[dev]

Package Structure

openagent.oas
  |-- did          DID parsing, validation, and EntityKind enumeration
  |-- crypto       Ed25519 keypairs, HKDF derivation, BLAKE3, lineage proofs, encoding
  |-- document     OAS document construction, signing, and conformance levels
  |-- lineage      Child entity derivation and lineage chain verification
  |-- resolve      DID resolution with in-memory, caching, and fallback resolvers
  |-- attestation  W3C Verifiable Credential signing and verification
  |-- sdk          High-level convenience API combining all modules

Type Checking

This package is PEP 561 compliant (py.typed marker included). All public APIs are fully annotated for use with mypy strict mode:

mypy --strict your_project/

---

Complete API Reference

openagent.oas.did -- DID Parsing and Validation

DID parsing, validation, and entity kind classification for the did:oas method. A did:oas DID has the form did:oas:<namespace>:<kind>:<identifier>.

from openagent.oas.did import (
    OasDid, EntityKind,
    validate_namespace, validate_identifier,
    DidError, DidParseError, InvalidNamespaceError,
    InvalidIdentifierError, UnknownEntityKindError,
)

OasDid -- frozen dataclass (namespace: str, kind: EntityKind, identifier: str)

Method / Property	Signature	Description
parse	@classmethod parse(input_str: str) -> OasDid	Parse a did:oas:... string
is_root	@property -> bool	True if kind is HMR, MHR, or ENR
__str__	() -> str	did:oas:<namespace>:<kind>:<identifier>

EntityKind -- str enum: HMR, MHR, ENR, AO, AGENT, AGENT_INSTANCE, TOOL, SKILL, WORKFLOW, MODEL, DATASET, SERVICE

Method	Signature	Description
is_root	() -> bool	True if HMR, MHR, or ENR
component_count	() -> int	Colon-separated component count
from_string	@classmethod (value: str) -> EntityKind	Parse string to EntityKind

Functions:

Function	Signature
validate_namespace	(namespace: str) -> str
validate_identifier	(identifier: str) -> str

Exceptions: DidError (base), DidParseError, InvalidNamespaceError, InvalidIdentifierError, UnknownEntityKindError

---

openagent.oas.crypto -- Cryptographic Operations

Ed25519 keypairs, HKDF-SHA256 derivation, BLAKE3 hashing, lineage proofs, JCS canonicalization, and encoding utilities.

from openagent.oas.crypto import (
    OasKeyPair, derive_child_keypair, derive_key_material,
    AgentLineageProof, blake3_hash, canonicalize,
    base58_encode, base58_decode, base64url_encode, base64url_decode,
    multibase_encode, multibase_decode,
    CryptoError, KeyGenerationError, SignatureError,
    DerivationError, ProofError, EncodingError,
)

OasKeyPair -- Ed25519 keypair. Private keys never appear in __repr__.

Method / Property	Signature	Description
generate	@classmethod () -> OasKeyPair	New keypair via CSPRNG
from_signing_key_bytes	@classmethod (key_bytes: bytes) -> OasKeyPair	Restore from 32-byte seed
sign	(message: bytes) -> bytes	64-byte Ed25519 signature
verify_with_key	@staticmethod (public_key: bytes, message: bytes, signature: bytes) -> None	Verify signature
verifying_key_bytes	@property -> bytes	32-byte public key
signing_key_bytes	@property -> bytes	32-byte private key seed
public_key_multibase	@property -> str	z + base58btc encoded public key
public_keys_equal	(other: OasKeyPair) -> bool	Constant-time comparison

AgentLineageProof -- frozen dataclass (type, parent_did, child_did, derivation_path, algorithm, public_key_multibase, signature)

Method	Signature
generate	@classmethod (*, parent_keypair: OasKeyPair, parent_did: str, child_did: str, derivation_path: str) -> AgentLineageProof
verify	() -> None
verify_with_key	(parent_public_key: bytes) -> None
to_dict	() -> dict[str, str]
from_dict	@classmethod (data: dict[str, str]) -> AgentLineageProof

Functions:

Function	Signature
derive_child_keypair	(parent: OasKeyPair, path: str) -> OasKeyPair
derive_key_material	(ikm: bytes, salt: bytes, info: str) -> bytes
blake3_hash	(data: bytes) -> bytes
canonicalize	(value: Any) -> bytes
base58_encode	(data: bytes) -> str
base58_decode	(encoded: str) -> bytes
base64url_encode	(data: bytes) -> str
base64url_decode	(encoded: str) -> bytes
multibase_encode	(data: bytes) -> str
multibase_decode	(encoded: str) -> bytes

Exceptions: CryptoError (base), KeyGenerationError, SignatureError, DerivationError, ProofError, EncodingError

---

openagent.oas.document -- Document Construction and Signing

OAS document construction via fluent builder, signing, proof generation, and conformance levels.

from openagent.oas.document import (
    OasDocument, DocumentMetadata, DocumentBuilder,
    ConformanceLevel, LifecycleStatus, VerificationMethod,
    ServiceEndpoint, LineageSection, DocumentProof,
    DocumentError, DocumentBuildError,
    DocumentValidationError, DocumentProofError,
)

OasDocument -- frozen dataclass (id, kind, conformance_level, verification_method, authentication, metadata, lineage, proof, service)

DocumentBuilder -- fluent builder

Method	Signature
__init__	(*, did: str, kind: str) -> None
conformance_level	(level: ConformanceLevel) -> DocumentBuilder
add_verification_method	(vm: VerificationMethod) -> DocumentBuilder
add_service	(service: ServiceEndpoint) -> DocumentBuilder
lineage	(section: LineageSection) -> DocumentBuilder
build_and_sign	(*, keypair: OasKeyPair, created: str) -> OasDocument

Enums: ConformanceLevel (L0, L1, L2), LifecycleStatus (NASCENT, ACTIVE, DORMANT, SUSPENDED, TERMINATED, ARCHIVED)

Data types: VerificationMethod, ServiceEndpoint, LineageSection, DocumentProof, DocumentMetadata -- all frozen dataclasses with to_dict() and from_dict() methods.

DocumentProof additional methods:

Method	Signature
verify	(document_json: dict[str, Any], public_key_bytes: bytes) -> None
create_and_sign	@classmethod (*, document_dict: dict[str, Any], keypair: OasKeyPair, verification_method_id: str, created: str) -> DocumentProof

Exceptions: DocumentError (base), DocumentBuildError, DocumentValidationError, DocumentProofError

---

openagent.oas.lineage -- Lineage Derivation and Verification

Child entity derivation and multi-hop lineage chain verification.

from openagent.oas.lineage import (
    derive_child_entity, DerivedEntity,
    verify_lineage,
    VerifyConfig, DocumentProvider, InMemoryProvider,
    LineageError, ParentMismatchError, SignatureInvalidError,
    ChainTooDeepError, ResolutionError, LineageStructuralError,
)

Functions:

Function	Signature
derive_child_entity	(*, parent_keypair: OasKeyPair, parent_document: OasDocument, namespace: str, kind: EntityKind, identifier: str, derivation_path: str, created: str) -> DerivedEntity
verify_lineage	async (document: OasDocument, provider: DocumentProvider, config: VerifyConfig | None = None) -> None

DerivedEntity -- frozen dataclass (document: OasDocument, keypair: OasKeyPair)

VerifyConfig -- frozen typed verifier options (max_generations: int = 16, verify_document_signatures: bool = True, total_timeout_seconds: float = 30.0, trust_anchors: tuple[TrustAnchor, ...] = ())

DocumentProvider -- Protocol with async def resolve(self, did: str) -> OasDocument

InMemoryProvider -- add(document), async resolve(did)

Exceptions: LineageError (base), ParentMismatchError, SignatureInvalidError, ChainTooDeepError, ResolutionError, LineageStructuralError

---

openagent.oas.resolve -- DID Resolution

Pluggable DID resolution with in-memory, caching, and fallback implementations.

from openagent.oas.resolve import (
    Resolver, InMemoryResolver, CachingResolver, FallbackResolver,
    ResolveError, DidNotFoundError, ResolverChainExhaustedError,
)

Resolver -- Protocol with async def resolve(self, did: str) -> OasDocument

InMemoryResolver -- add(document), add_many(documents), async resolve(did), contains(did), count()

CachingResolver -- __init__(inner, ttl_seconds=300), async resolve(did), invalidate(did), clear(), cache_size()

FallbackResolver -- __init__(resolvers: list[object]), async resolve(did)

Exceptions: ResolveError (base), DidNotFoundError, ResolverChainExhaustedError

---

openagent.oas.attestation -- Verifiable Credentials

W3C Verifiable Credential signing and verification for OAS entity attestation.

from openagent.oas.attestation import (
    OasCredential, CredentialSubject, AttestationType,
    sign_credential, verify_credential,
    AttestationError, CredentialBuildError,
    CredentialSignError, CredentialVerifyError,
)

OasCredential -- frozen dataclass (context, type, issuer, issuance_date, credential_subject, proof)

CredentialSubject -- frozen dataclass (id, type: AttestationType, claims)

AttestationType -- str enum: IDENTITY, CAPABILITY, COMPLIANCE, TRUST, CLASSIFICATION, PROVENANCE

Function	Signature
sign_credential	(credential: OasCredential, keypair: OasKeyPair, verification_method_id: str, created: str) -> OasCredential
verify_credential	(credential: OasCredential, public_key_bytes: bytes) -> None

Exceptions: AttestationError (base), CredentialBuildError, CredentialSignError, CredentialVerifyError

---

openagent.oas.sdk -- High-Level Convenience API

Unified entry points combining all modules.

from openagent.oas.sdk import (
    create_hmr, create_mhr, create_root_with_keypair,
    derive_child, verify_chain, CreatedIdentity, OasError,
)

Function	Signature
create_hmr	(namespace: str, identifier: str, created: str) -> CreatedIdentity
create_mhr	(namespace: str, identifier: str, created: str) -> CreatedIdentity
create_root_with_keypair	(*, namespace: str, kind: EntityKind, identifier: str, keypair: OasKeyPair, created: str) -> OasDocument
derive_child	(*, parent_keypair: OasKeyPair, parent_document: OasDocument, namespace: str, kind: EntityKind, identifier: str, derivation_path: str, created: str) -> DerivedEntity
verify_chain	async (document: OasDocument, provider: DocumentProvider, config: VerifyConfig | None = None) -> None

CreatedIdentity -- frozen dataclass (document: OasDocument, keypair: OasKeyPair)

OasError -- __init__(*, message: str, cause: Exception | None = None), unified SDK-level exception wrapping all sub-module errors.

---

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

pytest                     # Run tests
mypy --strict .            # Type checking
ruff check .               # Lint
ruff format --check .      # Format check

Cross-Language SDKs

OAS is implemented across multiple languages with full specification parity:

Language	Package	Install
Rust (reference)	oas-sdk	cargo add oas-sdk
TypeScript	@openagentid/oas-sdk	npm install @openagentid/oas-sdk
Go	github.com/openagentid/oas-go	go get github.com/openagentid/oas-go
Python	openagent-oas	pip install openagent-oas
Swift	oas-swift	SPM package dependency
Kotlin	id.openagent.oas:oas-sdk	Gradle/Maven dependency
Vanilla JS	@openagentid/oas-vanilla	Zero-dependency, browser-native

License

Copyright © 2026 L1fe Labs, Inc.

Licensed under the MIT license.