From ad66067b46c074bd8629820c919b85be20ab3f77 Mon Sep 17 00:00:00 2001 From: Brandon Bennett Date: Mon, 2 Feb 2026 23:20:36 -1000 Subject: [PATCH 1/4] docs: add AgentSystems Notary integration under Governance category --- docs.json | 6 + .../governance/agentsystems-notary.mdx | 137 ++++++++++++++++++ 2 files changed, 143 insertions(+) create mode 100644 integrations/governance/agentsystems-notary.mdx 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..b4b8bf741 --- /dev/null +++ b/integrations/governance/agentsystems-notary.mdx @@ -0,0 +1,137 @@ +--- +title: AgentSystems Notary +description: Tamper-evident audit logging for Agno agents. +--- + +## Overview + +AgentSystems Notary creates cryptographically verifiable audit trails for AI systems. + +## Why + +When AI behavior is questioned — by customers, legal teams, or regulators — 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 are written to independent storage (Arweave or the AgentSystems API) 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. Match means verified. Mismatch means tampering detected. + +You control your data, but can't alter it without detection. + +**What gets logged:** +- To your storage: input prompt, response text, agent metadata, session IDs, timestamps +- To ledger: SHA-256 hash + metadata (e.g. namespace, session ID, timestamps) + +Raw data stays in your infrastructure. + +## Decentralized Hash Storage + +Hashes (not raw data) can be written to a public, append-only ledger (Arweave): + +- **No vendor lock-in**: Verify with open-source tooling, no account required +- **No crypto setup**: No wallet, no tokens — transactions are handled by the bundler +- **Independent**: Not controlled by any single vendor + +## Custodied Hash Storage + +With a [custodied plan](https://agentsystems.ai/notary), hashes are written to AgentSystems' write-once compliance storage: + +- Managed signing, verification UI, support +- Signed attestations for audits + +## Prerequisites + +```shell +pip install agentsystems-notary agno anthropic +``` + +## Example (Decentralized) + +```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 (dev/testing only — use cloud key management in production) +# Generate with: openssl genrsa -out arweave-key.pem 4096 +signer = LocalKeySignerConfig( + private_key_path=os.environ["ARWEAVE_PRIVATE_KEY_PATH"], +) + +# Arweave for decentralized hash storage +# namespace isolates logs by tenant — use an anonymous ID (written to public ledger) +arweave_storage = ArweaveHashStorage( + namespace="tenant_a1b2c3d4", + 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?") +``` + + +The `namespace` is written to the public ledger. Use an anonymous tenant identifier, not a company name. + + +## Verification + +**Decentralized (Arweave)**: Download raw payloads from your storage bucket, then verify with the open-source CLI: + +```shell +npm install -g agentsystems-verify +agentsystems-verify --logs logs.zip +``` + +The CLI re-hashes each payload and compares against the hashes stored on Arweave. + +Alternatively, the [Verify UI](https://verify.agentsystems.ai) supports both decentralized and custodied verification. + +## Configuration + +- [Raw payload storage options](https://docs.agentsystems.ai/notary/configuration/raw-payload-storage) (AWS S3, GCS, etc.) +- [Signers for Arweave](https://docs.agentsystems.ai/notary/configuration/signing) (local key, AWS KMS) +- [Hash storage options](https://docs.agentsystems.ai/notary/configuration/hash-storage) (Arweave, Custodied) + +## Resources + +- [Documentation](https://docs.agentsystems.ai/notary/) +- [GitHub](https://github.com/agentsystems/agentsystems-notary) From 482e81b37f4a4c4c0c19d20a6570c0b2be725749 Mon Sep 17 00:00:00 2001 From: Brandon Bennett Date: Mon, 2 Feb 2026 23:27:24 -1000 Subject: [PATCH 2/4] update callout --- integrations/governance/agentsystems-notary.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/integrations/governance/agentsystems-notary.mdx b/integrations/governance/agentsystems-notary.mdx index b4b8bf741..3044484e1 100644 --- a/integrations/governance/agentsystems-notary.mdx +++ b/integrations/governance/agentsystems-notary.mdx @@ -108,9 +108,9 @@ agent = Agent( agent.print_response("What is the capital of France?") ``` - + The `namespace` is written to the public ledger. Use an anonymous tenant identifier, not a company name. - + ## Verification From 483a1f7a0e614ca809c7362ae6d4cd3da1f25c85 Mon Sep 17 00:00:00 2001 From: Brandon Bennett Date: Tue, 3 Feb 2026 12:32:16 -1000 Subject: [PATCH 3/4] docs: improve agentsystems-notary integration page --- .../governance/agentsystems-notary.mdx | 176 ++++++++++-------- 1 file changed, 98 insertions(+), 78 deletions(-) diff --git a/integrations/governance/agentsystems-notary.mdx b/integrations/governance/agentsystems-notary.mdx index 3044484e1..ccbc5bb01 100644 --- a/integrations/governance/agentsystems-notary.mdx +++ b/integrations/governance/agentsystems-notary.mdx @@ -9,15 +9,15 @@ AgentSystems Notary creates cryptographically verifiable audit trails for AI sys ## Why -When AI behavior is questioned — by customers, legal teams, or regulators — 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. +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 are written to independent storage (Arweave or the AgentSystems API) at the same time. +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 storage (Arweave or the AgentSystems API) 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. Match means verified. Mismatch means tampering detected. +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. @@ -25,92 +25,112 @@ You control your data, but can't alter it without detection. - To your storage: input prompt, response text, agent metadata, session IDs, timestamps - To ledger: SHA-256 hash + metadata (e.g. namespace, session ID, timestamps) -Raw data stays in your infrastructure. +## Hash Storage Options -## Decentralized Hash Storage +Hashes (not raw data) can be written to either storage option: -Hashes (not raw data) can be written to a public, append-only ledger (Arweave): +| Storage | Best For | Features | +|---------|----------|----------| +| [Decentralized (Arweave)](https://docs.agentsystems.ai/notary/configuration/hash-storage) | No vendor lock-in | Public append-only ledger, open-source verification, no account needed | +| [Custodied](https://agentsystems.ai/notary) | Managed compliance | Write-once storage, verification UI, signed attestations for audits | -- **No vendor lock-in**: Verify with open-source tooling, no account required -- **No crypto setup**: No wallet, no tokens — transactions are handled by the bundler -- **Independent**: Not controlled by any single vendor - -## Custodied Hash Storage - -With a [custodied plan](https://agentsystems.ai/notary), hashes are written to AgentSystems' write-once compliance storage: - -- Managed signing, verification UI, support -- Signed attestations for audits + +[Custodied plans](https://agentsystems.ai/notary) offer WORM-compliant hash storage, managed signing, and signed attestations. + ## Prerequisites ```shell -pip install agentsystems-notary agno anthropic +pip install agentsystems-notary agno anthropic python-dotenv ``` ## Example (Decentralized) -```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 (dev/testing only — use cloud key management in production) -# Generate with: openssl genrsa -out arweave-key.pem 4096 -signer = LocalKeySignerConfig( - private_key_path=os.environ["ARWEAVE_PRIVATE_KEY_PATH"], -) - -# Arweave for decentralized hash storage -# namespace isolates logs by tenant — use an anonymous ID (written to public ledger) -arweave_storage = ArweaveHashStorage( - namespace="tenant_a1b2c3d4", - 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?") -``` - - -The `namespace` is written to the public ledger. Use an anonymous tenant identifier, not a company name. - + + + ```shell + openssl genrsa -out arweave-key.pem 4096 + ``` + For production, use [AWS KMS or another cloud key management service](https://docs.agentsystems.ai/notary/configuration/signing). + + + 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 + arweave_storage = ArweaveHashStorage( + namespace="tenant_a1b2c3d4", + 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?") + ``` + + + The `namespace` is written to the public ledger. Use an anonymous tenant identifier, not a company name. + + + ## Verification From b4f2c15607c6ddb11c283f470d63c542cb17e4f2 Mon Sep 17 00:00:00 2001 From: Brandon Bennett Date: Fri, 6 Feb 2026 22:36:21 -1000 Subject: [PATCH 4/4] Update verification instructions and increase clarity --- .../governance/agentsystems-notary.mdx | 52 +++++++++++-------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/integrations/governance/agentsystems-notary.mdx b/integrations/governance/agentsystems-notary.mdx index ccbc5bb01..224bf5559 100644 --- a/integrations/governance/agentsystems-notary.mdx +++ b/integrations/governance/agentsystems-notary.mdx @@ -1,11 +1,11 @@ --- title: AgentSystems Notary -description: Tamper-evident audit logging for Agno agents. +description: Cryptographically verifiable audit trails for Agno applications. --- ## Overview -AgentSystems Notary creates cryptographically verifiable audit trails for AI systems. +AgentSystems Notary creates tamper-evident audit trails for AI agent interactions. ## Why @@ -15,15 +15,15 @@ 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 storage (Arweave or the AgentSystems API) at the same time. +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: input prompt, response text, agent metadata, session IDs, timestamps -- To ledger: SHA-256 hash + metadata (e.g. namespace, session ID, timestamps) +- 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 @@ -31,11 +31,11 @@ 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) | No vendor lock-in | Public append-only ledger, open-source verification, no account needed | -| [Custodied](https://agentsystems.ai/notary) | Managed compliance | Write-once storage, verification UI, signed attestations for audits | +| [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) offer WORM-compliant hash storage, managed signing, and signed attestations. +[Custodied plans](https://agentsystems.ai/notary?utm_source=agno-docs&utm_medium=docs) offer WORM-compliant hash storage, managed signing, and signed attestations. ## Prerequisites @@ -51,7 +51,11 @@ pip install agentsystems-notary agno anthropic python-dotenv ```shell openssl genrsa -out arweave-key.pem 4096 ``` - For production, use [AWS KMS or another cloud key management service](https://docs.agentsystems.ai/notary/configuration/signing). + + 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: @@ -69,7 +73,7 @@ pip install agentsystems-notary agno anthropic python-dotenv ANTHROPIC_API_KEY=sk-ant-... ``` - + ```python import os @@ -101,8 +105,11 @@ pip install agentsystems-notary agno anthropic python-dotenv ) # 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", + namespace="tenant_a1b2c3d4", # See namespace comments above signer=signer, ) @@ -125,33 +132,32 @@ pip install agentsystems-notary agno anthropic python-dotenv agent.print_response("What is the capital of France?") ``` - - - The `namespace` is written to the public ledger. Use an anonymous tenant identifier, not a company name. - ## Verification -**Decentralized (Arweave)**: Download raw payloads from your storage bucket, then verify with the open-source CLI: +**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. +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) supports both decentralized and custodied verification. +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) (AWS S3, GCS, etc.) -- [Signers for Arweave](https://docs.agentsystems.ai/notary/configuration/signing) (local key, AWS KMS) -- [Hash storage options](https://docs.agentsystems.ai/notary/configuration/hash-storage) (Arweave, Custodied) +- [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 -- [Documentation](https://docs.agentsystems.ai/notary/) -- [GitHub](https://github.com/agentsystems/agentsystems-notary) +- [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)