diff --git a/docs.json b/docs.json index 8b965f986..da9880c55 100644 --- a/docs.json +++ b/docs.json @@ -2706,6 +2706,12 @@ ] } ] + }, + { + "group": "Governance", + "pages": [ + "integrations/governance/agentsystems-notary" + ] } ] }, diff --git a/integrations/governance/agentsystems-notary.mdx b/integrations/governance/agentsystems-notary.mdx new file mode 100644 index 000000000..224bf5559 --- /dev/null +++ b/integrations/governance/agentsystems-notary.mdx @@ -0,0 +1,163 @@ +--- +title: AgentSystems Notary +description: Cryptographically verifiable audit trails for Agno applications. +--- + +## Overview + +AgentSystems Notary creates tamper-evident audit trails for AI agent interactions. + +## Why + +When AI behavior is questioned by customers, auditors, regulators, insurers, etc., you need to prove what actually happened. Traditional logs don't work: you control them, so third parties have to trust you didn't modify them. + +Tamper-evident logging removes that trust requirement. + +## How It Works + +Raw LLM interactions stay in your storage. No third party sees them during normal operation. But cryptographic hashes of each interaction are written to independent, tamper-evident storage (Arweave or the AgentSystems custodied service) at the same time. + +If there's ever an audit or dispute, you provide the raw logs. The auditor re-hashes them and compares against the stored hashes. A match indicates the logs are unaltered. A mismatch indicates tampering or corruption. + +You control your data, but can't alter it without detection. + +**What gets logged:** +- To your storage: full raw LLM payload (prompts, responses, metadata, timestamps) +- To hash storage: SHA-256 hash + metadata (e.g. namespace, session ID, timestamps) + +## Hash Storage Options + +Hashes (not raw data) can be written to either storage option: + +| Storage | Best For | Features | +|---------|----------|----------| +| [Decentralized (Arweave)](https://docs.agentsystems.ai/notary/configuration/hash-storage?utm_source=agno-docs&utm_medium=docs) | No vendor lock-in | Public append-only ledger, open-source verification, no account needed | +| [Custodied](https://agentsystems.ai/notary?utm_source=agno-docs&utm_medium=docs) | Managed compliance | Write-once storage, verification UI, signed attestations for audits | + + +[Custodied plans](https://agentsystems.ai/notary?utm_source=agno-docs&utm_medium=docs) offer WORM-compliant hash storage, managed signing, and signed attestations. + + +## Prerequisites + +```shell +pip install agentsystems-notary agno anthropic python-dotenv +``` + +## Example (Decentralized) + + + + ```shell + openssl genrsa -out arweave-key.pem 4096 + ``` + + Retain this key. It is required to prove ownership of on-chain hashes during verification. + + + For production, use a [cloud key management service](https://docs.agentsystems.ai/notary/configuration/signing?utm_source=agno-docs&utm_medium=docs). + + + Create a `.env` file in your project root: + ``` + # AWS S3 for raw payload storage + ORG_AWS_S3_BUCKET_NAME=your-bucket + ORG_AWS_S3_ACCESS_KEY_ID=AKIA... + ORG_AWS_S3_SECRET_ACCESS_KEY=... + ORG_AWS_S3_REGION=us-east-1 + + # Path to signing key + ARWEAVE_PRIVATE_KEY_PATH=./arweave-key.pem + + # Anthropic + ANTHROPIC_API_KEY=sk-ant-... + ``` + + + ```python + import os + + from agentsystems_notary import ( + AgnoNotary, + ArweaveHashStorage, + AwsS3StorageConfig, + LocalKeySignerConfig, + RawPayloadStorage, + ) + from agno.agent import Agent + from agno.models.anthropic import Claude + from dotenv import load_dotenv + + load_dotenv() + + # Your S3 bucket for raw LLM payloads + s3_config = AwsS3StorageConfig( + bucket_name=os.environ["ORG_AWS_S3_BUCKET_NAME"], + aws_access_key_id=os.environ["ORG_AWS_S3_ACCESS_KEY_ID"], + aws_secret_access_key=os.environ["ORG_AWS_S3_SECRET_ACCESS_KEY"], + aws_region=os.environ["ORG_AWS_S3_REGION"], + ) + raw_payload_storage = RawPayloadStorage(storage=s3_config) + + # Local RSA key for signing + signer = LocalKeySignerConfig( + private_key_path=os.environ["ARWEAVE_PRIVATE_KEY_PATH"], + ) + + # Arweave for decentralized hash storage + # Namespace is public — written to the ledger and used to segment stored data + # Namespace should be one anonymous ID per customer, agent, or environment + # Retain a record of your namespace mappings + arweave_storage = ArweaveHashStorage( + namespace="tenant_a1b2c3d4", # See namespace comments above + signer=signer, + ) + + # Assemble notary + notary = AgnoNotary( + raw_payload_storage=raw_payload_storage, + hash_storage=[arweave_storage], + debug=True, + ) + + # Attach hooks to agent + agent = Agent( + model=Claude( + id="claude-sonnet-4-5-20250929", + api_key=os.environ["ANTHROPIC_API_KEY"], + ), + instructions="You are a helpful assistant.", + **notary.get_hooks(), + ) + + agent.print_response("What is the capital of France?") + ``` + + + +## Verification + +**Decentralized (Arweave)**: Download raw payloads from your storage bucket, zip them, and verify with the open-source CLI: + +```shell +aws s3 sync s3://your-bucket/arweave/tenant_a1b2c3d4/ ./logs +zip -r logs.zip logs +npm install -g agentsystems-verify +agentsystems-verify --logs logs.zip +``` + +The CLI re-hashes each payload and compares against the hashes stored on Arweave. See the [full verification guide](https://docs.agentsystems.ai/notary/verification/arweave?utm_source=agno-docs&utm_medium=docs) for details. + +Alternatively, the [Verify UI](https://verify.agentsystems.ai?utm_source=agno-docs&utm_medium=docs) supports both decentralized and custodied verification. + +## Configuration + +- [Raw payload storage options](https://docs.agentsystems.ai/notary/configuration/raw-payload-storage?utm_source=agno-docs&utm_medium=docs) +- [Signing configuration](https://docs.agentsystems.ai/notary/configuration/signing?utm_source=agno-docs&utm_medium=docs) +- [Hash storage options](https://docs.agentsystems.ai/notary/configuration/hash-storage?utm_source=agno-docs&utm_medium=docs) + +## Resources + +- [Website](https://agentsystems.ai/notary?utm_source=agno-docs&utm_medium=docs) +- [Documentation](https://docs.agentsystems.ai/notary/?utm_source=agno-docs&utm_medium=docs) +- [GitHub](https://github.com/agentsystems/agentsystems-notary?utm_source=agno-docs&utm_medium=docs)