agentoath 0.2.0

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

AgentOath Python SDK

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

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 an AgentOath Registry server:

from agentoath import TrustAgent
from agentoath.registry_client import RegistryClient

agent = TrustAgent.create(name="My Agent")
client = RegistryClient("https://registry.agentoath.ai")

# 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.

API Reference

TrustAgent

Method	Description
TrustAgent.create(name, capabilities, platform)	Create a new Agent with a fresh keypair
TrustAgent.load(path, password)	Load an Agent from a key file
agent.save(path, password)	Save the Agent's identity to disk
agent.sign_receipt(to_agent, action, rating)	Sign a Trust Receipt
agent.counter_sign_receipt(receipt)	Add a counter-signature
agent.verify_receipt(receipt, from_public_key)	Verify a receipt's signature
agent.calculate_trust_score(receipts)	Compute trust score
agent.did	The Agent's DID
agent.public_key_formatted	Public key as ed25519:{base64}

TrustReceipt

Method	Description
TrustReceipt.create(from_agent_did, from_private_key, to_agent_did)	Create and sign a receipt
TrustReceipt.from_dict(data)	Create from a dictionary
receipt.counter_sign(to_private_key)	Add counter-signature
receipt.verify_from_signature(public_key)	Verify initiator's signature
receipt.verify_counter_signature(public_key)	Verify counter-signature
TrustReceipt.verify(receipt_dict, from_public_key)	Static verification

RegistryClient

Method	Description
client.register(agent)	Register an Agent
client.get_agent(did)	Look up an Agent by DID
client.get_agent_card(did)	Get Agent's public profile
client.search_agents(name, platform, capability)	Search for Agents
client.publish_receipt(receipt)	Publish a signed receipt
client.get_receipts(agent_did)	Get receipts for an Agent
client.verify_receipt(receipt, from_public_key)	Online verification
client.query_trust_score(agent_did)	Query trust score

Development

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

# Run tests
pytest

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

Links

• Website: agentoath.ai
• GitHub: github.com/AgentOath/agentoath
• Architecture: docs/architecture.md

License

Apache 2.0