agentoath-shadowos

AgentOath ShadowOS Adapter

Trust receipts for an AI agent backend, wired in at the pipeline boundary.

This is a standalone adapter for the AgentOath trust protocol. It depends on agentoath and on nothing else -- it contains no ShadowOS code and does not import ShadowOS. It was written against a FastAPI agent backend, and the shape it assumes is a common one: an agent that calls tools, reads and writes memory, and answers over HTTP.

Quick Start

pip install agentoath-shadowos

from agentoath_shadowos import ShadowOSTrustAdapter

adapter = ShadowOSTrustAdapter.create(agent_name="MyAI Secretary")
adapter.save("agent_identity.json", password="...")

receipt = adapter.record_tool_call(
    tool="send_email",
    outcome="delivered",
    rating=9,
)

Reload a persisted identity rather than minting a new one -- a DID is derived from its key, so creating a second identity means a second agent as far as the protocol is concerned:

adapter = ShadowOSTrustAdapter.load("agent_identity.json", password="...")

The three pieces

What to record, and what not to

Receipts are public and cannot be deleted. Record the operations somebody may later need you to prove happened -- an approval, a decision, a promise made to a customer. Do not record polling, cache hits, or debug traces: it turns the Registry into a log system, which is not what it is for, and the noise is permanent.

Recording must never break the operation it describes. Do the work first, then record, and let recording fail silently:

result = do_the_actual_work()
try:
    adapter.record_tool_call(tool="send_email", outcome="delivered", rating=9)
except Exception:
    pass          # a receipt that fails is not a request that failed
return result

Privacy

The Registry rejects receipts whose metadata contains any of 28 blocked keys -- prompt, email, raw, transcript, token and similar -- and the match is on underscore-separated words, so prompt_hash and user_email are rejected too. Send a digest, or rename the field to something that is not about the content. The full list and the reasoning are in the integration guide.

License

Apache-2.0. See LICENSE and NOTICE.