AgentOath Python SDK

The open protocol for AI agent identity, trust, and notarization.

Two layers, one package

Peer-to-peer (everything below unless marked otherwise) — identities are did:trust:agent:, receipts live with whoever holds them, and trust is a score you compute from the receipts you have received. Nothing central to trust or pay for. Run your own registry with pip install agentoath-registry if you want one.

Hosted Registry (agentoath.hosted) — a client for registry.agentoath.com, a notarisation service where you publish signed receipts about your own actions and any third party can verify them without trusting the platform. Identities are did:agentoath: and the wire format is different.

They are separate protocols. A receipt built for one is rejected by the other, by design. The same Ed25519 keypair can hold an identity in both.

Stability

The peer-to-peer layer has been in use since 0.2 and follows semantic versioning from 1.0 on: no breaking change without a major bump.

agentoath.hosted is provisional. The wire format it speaks is fixed — it is pinned to the Registry's published spec at GET /api/v1/registry, and the cross-language canonical fixtures in tests/ fail if either side drifts. What may still move is the shape of this client: argument names, helper functions, where things live. That is a deliberate exception to the guarantee above, stated here rather than implied by the version number, because the module is new and has had one real integration so far.

If you need it frozen, pin an exact version. If you build on it, the stable thing to build on is the wire format, not this client's signatures.

Installation

pip install agentoath

Quick Start

from agentoath import TrustAgent, TrustReceipt

# Create a new Agent identity
agent = TrustAgent.create(
    name="My AI Assistant",
    capabilities=["chat", "search"],
    platform="custom",
)

# Save identity to disk
agent.save("my_agent.json")

# Load identity from disk
agent = TrustAgent.load("my_agent.json")

# Sign a trust receipt after an interaction
receipt = agent.sign_receipt(
    to_agent="did:trust:agent:bbb...",
    action="collaboration",
    rating=9,
    description="Built a great report",
)

# Verify a receipt
is_valid = receipt.verify_from_signature(other_agent.public_key)

# Calculate trust score
score = agent.calculate_trust_score(receipts)
print(f"Trust Score: {score.overall}")

CLI

The SDK includes a command-line tool:

# Generate a new Agent keypair
agentoath init --name "My Agent" --capabilities "chat,search"

# Display Agent info
agentoath info

# Sign a receipt
agentoath sign-receipt --to did:trust:agent:bbb... --rating 9

# Verify a receipt
agentoath verify-receipt receipt.json --from-key-file agent_key.json

# Compute trust score
agentoath trust-score --receipts receipts.json --target-did did:trust:agent:bbb...

Registry Client

Connect to a registry you run yourself (pip install agentoath-registry). For the hosted Registry at registry.agentoath.com see Hosted Registry below — it is a different protocol and this client cannot talk to it.

from agentoath import TrustAgent
from agentoath.registry_client import RegistryClient

agent = TrustAgent.create(name="My Agent")
client = RegistryClient("http://localhost:8500")  # your own server

# Register with the Registry
resp = client.register(agent)
print(resp.data["identity_certificate"])

# Publish a receipt
receipt = agent.sign_receipt(to_agent="did:trust:agent:bbb...", rating=9)
client.publish_receipt(receipt)

# Query trust score
score = client.query_trust_score("did:trust:agent:bbb...")
print(score.data)

The client supports offline mode -- when the Registry is unreachable, it returns graceful fallback responses instead of crashing.

Hosted Registry

A client for registry.agentoath.com. Disabled by default — it sends nothing until you turn it on.

from agentoath.hosted import (
    AgentOathIdentity, AgentOathClientConfig, AgentOathRegistryClient,
    build_signed_receipt, verify_receipt_locally, sha256_json,
)

identity = AgentOathIdentity.generate()
print(identity.did)          # did:agentoath:<sha256 of the raw public key>
print(identity.private_key)  # keep this out of version control

client = AgentOathRegistryClient(AgentOathClientConfig(
    base_url="https://registry.agentoath.com",
    api_key="...",
    enabled=True,
))
client.register_identity(identity, name="my-service")

receipt = build_signed_receipt(
    identity,
    receipt_id="verdict-1234",
    action="compliance.verdict.red",
    metadata={"schema": "v1", "content_digest": sha256_json(text)},
)
client.publish_receipt(receipt)

Three rules the Registry enforces. build_signed_receipt checks all three locally, so you get a Python exception at the call site instead of an HTTP 422 somewhere else:

1. rating must be a JSON integer 0–10. Python prints 7.0 where JavaScript prints 7, so a float makes the signature unverifiable.
2. Empty optional fields must be omitted entirely, never sent as "".
3. metadata must always be present, and filled in before signing.

Receipts are public and permanent, so metadata keys are checked against a 28-key blocklist — matched per underscore-separated segment, which means prompt_hash and user_email are rejected. Use content_digest, actor_ref and similar instead. Full guide: https://agentoath.com/integrate.

API Reference

TrustAgent

TrustReceipt

RegistryClient

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=agentoath --cov-report=term-missing

Links

• Protocol website: agentoath.ai
• Hosted Registry: agentoath.com
• Integration guide: agentoath.com/integrate

License

Apache 2.0