agent-call-audit
A tiny, dependency-free guardrail layer for agent tool calls — with a tamper-evident audit trail.
⚠️ This is the generic, de-identified edition. It contains no vendor-specific rules, no private data and no personal identifiers. Rules ship as examples only.
Research prototype / AI-assisted development.
pip install agent-call-audit # zero deps, Python 3.9+
Verifiable-agent family
This engine is the first member of an open family that shares one fail-closed, audit-trail design language:
| Repo | Role |
|---|---|
| agent-call-audit | audit engine for agent tool calls (this repo) |
| agent-memory-ledger | verifiable memory layer |
| agent-audit-gateway | HTTP gateway around the engine |
| agent-route-grid | audited multi-agent routing |
Why
Agent frameworks are getting good at doing things (file writes, outbound messages, payments) and bad at proving what was allowed and why. This package is the missing middle: a single synchronous call that decides
allow | deny | human
for every tool call, refuses to fail open, and writes a hash-chained audit record that a third party can verify offline.
Design invariants
| # | Invariant | Where |
|---|---|---|
| 1 | Rule priority: red lines > fence limits > permission matrix; on conflict the most severe outcome wins | engine.AuditGuard._evaluate |
| 2 | Fail-closed: unknown caller / unknown capability / bad hash / stale timestamp / any internal error ⇒ deny |
engine.evaluate |
| 3 | Caller identity is bound to a credential — a caller id string is never enough | register_caller |
| 4 | Replay & retry defence: single-use nonces; idempotency keys return the cached verdict | _evaluate steps 5–6 |
| 5 | Atomic quota reservation: concurrent calls can never overshoot per-call / per-day / per-month caps | engine.QuotaBook |
| 6 | Human-in-the-loop for high risk, with a hard timeout that resolves to deny |
resolve, expire_pending |
| 7 | Privacy by default: only the request hash is persisted — payload content never is | _finalize |
| 8 | Tamper-evident trail: append-only JSONL with a SHA-256 hash chain, verifiable offline | AuditTrail.verify |
Quick start
pip install agent-call-audit # zero deps, Python 3.9+
python examples/demo.py # scripted walkthrough
python -m unittest discover -s tests -t . -v # 23 tests, no third-party deps
from audit_guard import AuditGuard, AuditRequest, RuleSet, AuditTrail, hash_payload
guard = AuditGuard(RuleSet.demo(), trail=AuditTrail("audit.jsonl"))
guard.register_caller("agent-7", "s3cret", capabilities=["data.lookup"],
max_action="read", max_data_class="internal")
verdict = guard.evaluate(AuditRequest(
caller_id="agent-7", credential="s3cret", target_capability="data.lookup",
action_type="read", data_class="public",
request_hash=hash_payload({"q": "hello"}), payload={"q": "hello"},
nonce="n-1", timestamp=1_800_000_000.0,
))
print(verdict.decision, verdict.reason_code) # allow ALLOWED
print(guard.trail.verify()) # True
Rule file
Rules are data, not code — see rules/rules.example.json (loaded via
RuleSet.from_json).
{
"red_lines": [
{"id": "DEMO-RL-001", "description": "outbound of restricted data",
"action_types": ["outbound"], "data_classes": ["restricted"]}
],
"fence": {"per_call": 500.0, "per_day": 2000.0, "per_month": 5000.0}
}
Transports
protocol.py implements only the semantic layer (audit.call,
audit.resolve, audit.pending) over stdio JSON lines. Binding it to MCP, A2A or
plain HTTP is a transport concern and deliberately left to the caller, so the same
rule engine runs locally, in a sandbox, or behind a gateway without change.
Status & non-goals
- Status: reference implementation, not a hardened product. No SLA.
- Non-goals: it does not execute the tool call, does not store payloads, does not replace your IAM, and does not decide business policy for you — you write the rules.
- Security review is the user's responsibility before any production use.
Contributing
See CONTRIBUTING.md for the ground rules (fail-closed first, no new dependencies, de-identified commits, tests green). Found a security issue? See SECURITY.md.
License
MIT — see LICENSE.
Contact
Furitong Digital Workspace (福瑞通 · 数字工作台) — automation workbench, AI-assisted delivery. Business enquiries: 2307788504@qq.com. No financial advice, no legal opinions, no crypto-related work.
Copyright (c) 2026 Furitong Digital Workspace. MIT licensed.
Metadata
Release files for agent-call-audit 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_call_audit-0.1.1.tar.gz | 14.8 kB | Without provenance | Details for agent_call_audit-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_call_audit-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agent_call_audit-0.1.1-py3-none-any.whl |
Total release size: 28.9 kB
Release files / agent_call_audit-0.1.1.tar.gz
| Download URL | agent_call_audit-0.1.1.tar.gz |
|---|---|
| Size | 14.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5d9becf704ef4a50622e1068c1ba5a1d5dfe0c59118fc6446c35044cf92174dd
|
|
BLAKE2b-256 checksum How to use checksums |
3da592d3cd658d75fd83442c8292ef2689da1ecb63b9d8c7788cc199b9e78835
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / agent_call_audit-0.1.1-py3-none-any.whl
| Download URL | agent_call_audit-0.1.1-py3-none-any.whl |
|---|---|
| Size | 14.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
630e32ed282f32f22d95b9818e4be78e50d164c39bfb96d96d85c1a2c37db8e6
|
|
BLAKE2b-256 checksum How to use checksums |
acaa4a008c2f67a6bd0f87f0db9de2ceed75791bee31fe7521e1105bf48e5daf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for agent-call-audit 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.