From 39accb4be151bd37f5c72297973122ad6c0f571c Mon Sep 17 00:00:00 2001 From: Brandon Bennett Date: Wed, 22 Apr 2026 16:41:15 -1000 Subject: [PATCH 1/2] docs: add AgentSystems Notary integration --- docs.json | 3 +- integrations/agentsystems-notary.mdx | 112 +++++++++++++++++++++++++++ 2 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 integrations/agentsystems-notary.mdx diff --git a/docs.json b/docs.json index 41a28f7..bbbb4de 100644 --- a/docs.json +++ b/docs.json @@ -67,7 +67,8 @@ "integrations/strands", "integrations/google-adk", "integrations/crewai", - "integrations/langchain" + "integrations/langchain", + "integrations/agentsystems-notary" ] }, { diff --git a/integrations/agentsystems-notary.mdx b/integrations/agentsystems-notary.mdx new file mode 100644 index 0000000..0142be5 --- /dev/null +++ b/integrations/agentsystems-notary.mdx @@ -0,0 +1,112 @@ +--- +title: AgentSystems Notary +description: Tamper-evident audit trails for Agent Control events. +--- + +AgentSystems Notary writes every Agent Control event to independent, tamper-evident storage — so you can prove to auditors, regulators, and customers exactly which controls fired, when, and what they decided. + +## How it works + +Raw event payloads stay in your own S3 bucket. A SHA-256 hash of each event is written to the Arweave permaweb (or managed WORM storage). Auditors re-hash the raw payloads and compare them against the stored hashes — matching hashes prove integrity, mismatches expose tampering. + +## Storage options + +| Option | Best for | What you get | +|--------|----------|--------------| +| **Arweave (Decentralized)** | No vendor lock-in | Public append-only ledger, open-source verification, no account required | +| **Custodied** | Managed compliance | Write-once storage, verification UI, signed attestation PDFs | + +## Setup + +Notary integrates as a control event sink. Works with any framework Agent Control supports — LangChain, CrewAI, Google ADK, AWS Strands. + +### Prerequisites + +- A running Agent Control server with at least one agent and one control configured (see the [Quickstart](/core/quickstart)) +- An S3 bucket for raw event payloads +- A hash storage backend — either an Arweave signing key (decentralized) or an AgentSystems API key (custodied). See the [Notary docs](https://docs.agentsystems.ai/notary) for setup. + +### Install and register the sink + +```bash +pip install 'agentsystems-notary[agent-control]' +``` + +The example below uses Arweave. To use the custodied service instead, swap `ArweaveHashStorage` for `CustodiedHashStorage(api_key=..., slug=...)` — see the [Notary docs](https://docs.agentsystems.ai/notary) for the custodied setup. + +```python +import os + +from agent_control.observability import register_control_event_sink +from agentsystems_notary import ( + AgentControlNotarySink, + ArweaveHashStorage, + AwsS3StorageConfig, + LocalKeySignerConfig, + NotaryCore, + RawPayloadStorage, +) + +notary = NotaryCore( + raw_payload_storage=RawPayloadStorage( + storage=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"], + ), + ), + hash_storage=[ + ArweaveHashStorage( + namespace="my-agent-namespace", # scopes your stored data + signer=LocalKeySignerConfig( + private_key_path=os.environ["ARWEAVE_PRIVATE_KEY_PATH"], + ), + ) + ], +) + +register_control_event_sink(AgentControlNotarySink(notary)) +``` + +Once the sink is registered, every control your agents trigger is automatically notarized — no changes to your `@control()` decorators or control definitions required. + + +Agent Control's event batcher flushes sink events asynchronously. In short-lived scripts, allow a few seconds for events to flush before exiting (e.g. `await asyncio.sleep(5)`). Long-running agents don't need this. + + +## What gets notarized + +Each event becomes a canonical JSON record, hashed and pinned to your chosen hash storage. The `pre_execution_record` includes the full Agent Control event — `control_name`, `evaluator_name`, `action`, `matched`, `confidence`, `trace_id`, `span_id`, and the `condition_trace` showing exactly which pattern or rule matched: + +```json +{ + "metadata": { "session_id": "...", "sequence": 1, "timestamp": "..." }, + "input": { "selector_path": "output", "check_stage": "post" }, + "output": { "matched": true, "action": "deny" }, + "pre_execution_record": { + "control_name": "block-ssn", + "evaluator_name": "regex", + "action": "deny", + "matched": true, + "confidence": 1, + "agent_name": "my-agent", + "trace_id": "...", + "span_id": "...", + "metadata": { + "pattern": "\\b\\d{3}-\\d{2}-\\d{4}\\b", + "condition_trace": { "matched": true, "message": "Pattern found", "...": "..." } + }, + "timestamp": "..." + } +} +``` + +## Verification + +Download raw payloads from your S3 bucket, re-hash them, and compare against the stored hashes. Use the [Verify UI](https://verify.agentsystems.ai) for a one-click verification flow, or the open-source [`agentsystems-verify` CLI](https://github.com/agentsystems/agentsystems-verify) for programmatic verification. + +## Resources + +- [AgentSystems Notary on PyPI](https://pypi.org/project/agentsystems-notary/) +- [Source on GitHub](https://github.com/agentsystems/agentsystems-notary) From 3323807574b441a7f3724873b7e357ce0cae2db7 Mon Sep 17 00:00:00 2001 From: Brandon Bennett Date: Mon, 27 Apr 2026 15:48:53 -1000 Subject: [PATCH 2/2] docs: clarify event embedding in Notary record per review --- integrations/agentsystems-notary.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/integrations/agentsystems-notary.mdx b/integrations/agentsystems-notary.mdx index 0142be5..cb31921 100644 --- a/integrations/agentsystems-notary.mdx +++ b/integrations/agentsystems-notary.mdx @@ -7,7 +7,7 @@ AgentSystems Notary writes every Agent Control event to independent, tamper-evid ## How it works -Raw event payloads stay in your own S3 bucket. A SHA-256 hash of each event is written to the Arweave permaweb (or managed WORM storage). Auditors re-hash the raw payloads and compare them against the stored hashes — matching hashes prove integrity, mismatches expose tampering. +Each Agent Control event is embedded in a Notary record alongside metadata. A SHA-256 hash of the record is written to your hash storage backend — managed WORM or Arweave — and the record bytes are stored in your S3 bucket. Auditors re-hash the stored bytes and compare against the stored hash — matching hashes prove integrity, mismatches expose tampering. ## Storage options @@ -23,7 +23,7 @@ Notary integrates as a control event sink. Works with any framework Agent Contro ### Prerequisites - A running Agent Control server with at least one agent and one control configured (see the [Quickstart](/core/quickstart)) -- An S3 bucket for raw event payloads +- An S3 bucket for record storage - A hash storage backend — either an Arweave signing key (decentralized) or an AgentSystems API key (custodied). See the [Notary docs](https://docs.agentsystems.ai/notary) for setup. ### Install and register the sink @@ -32,7 +32,7 @@ Notary integrates as a control event sink. Works with any framework Agent Contro pip install 'agentsystems-notary[agent-control]' ``` -The example below uses Arweave. To use the custodied service instead, swap `ArweaveHashStorage` for `CustodiedHashStorage(api_key=..., slug=...)` — see the [Notary docs](https://docs.agentsystems.ai/notary) for the custodied setup. +This example uses Arweave; for custodied storage, swap `ArweaveHashStorage` for `CustodiedHashStorage(api_key=..., slug=...)`. See the [Notary docs](https://docs.agentsystems.ai/notary) for either setup. ```python import os @@ -77,7 +77,7 @@ Agent Control's event batcher flushes sink events asynchronously. In short-lived ## What gets notarized -Each event becomes a canonical JSON record, hashed and pinned to your chosen hash storage. The `pre_execution_record` includes the full Agent Control event — `control_name`, `evaluator_name`, `action`, `matched`, `confidence`, `trace_id`, `span_id`, and the `condition_trace` showing exactly which pattern or rule matched: +Each Agent Control event is preserved verbatim in the `pre_execution_record` field of the Notary record — `control_name`, `evaluator_name`, `action`, `matched`, `confidence`, `trace_id`, `span_id`, and the `condition_trace` showing exactly which pattern or rule matched: ```json { @@ -104,7 +104,7 @@ Each event becomes a canonical JSON record, hashed and pinned to your chosen has ## Verification -Download raw payloads from your S3 bucket, re-hash them, and compare against the stored hashes. Use the [Verify UI](https://verify.agentsystems.ai) for a one-click verification flow, or the open-source [`agentsystems-verify` CLI](https://github.com/agentsystems/agentsystems-verify) for programmatic verification. +Download the stored bytes from your S3 bucket, compute SHA-256, and compare against your stored hashes. Use the [Verify UI](https://verify.agentsystems.ai) for a one-click verification flow, or the open-source [`agentsystems-verify` CLI](https://github.com/agentsystems/agentsystems-verify) for programmatic verification. ## Resources