AgenticContract
Every AI agent is ungoverned.
Claude can exceed your API budget. GPT can bypass approval gates. Your copilot can violate compliance rules without anyone noticing. Every action happens without oversight.
The current fixes don't work. Manual policy checks are forgotten. Rate limits live in application code that agents can't inspect. Approval workflows require external services. Compliance obligations get tracked in spreadsheets. Violations go undetected until it's too late.
AgenticContract models policies, risk limits, approvals, conditions, obligations, and violations in a single binary .acon file. Not "add a config file." Your agent has a governance engine -- behavior constraints, budget enforcement, approval gates, and breach tracking -- all structured, all queryable in microseconds.
Problems Solved (Read This First)
- Problem: agents operate without policy constraints and can take any action. Solved: typed policies (allow/deny/require_approval/audit_only) enforce behavior rules with sub-millisecond evaluation.
- Problem: no runtime awareness of resource budgets or rate limits. Solved: quantitative risk limits with real-time tracking and threshold alerts.
- Problem: high-stakes actions happen without human-in-the-loop approval. Solved: structured approval workflow with request/decide lifecycle and audit trail.
- Problem: compliance obligations are tracked informally and deadlines are missed. Solved: deadline-tracked obligations with automatic overdue detection.
- Problem: policy violations go undetected and unrecorded. Solved: severity-classified violation records with precognition and archaeology tools.
from agentic_contract import ContractEngine
engine = ContractEngine("agent.acon")
# Your agent is governed
engine.policy_add("No production deploys on Friday", scope="global", action="deny")
engine.risk_limit_set("API spend", max_value=100.0, limit_type="budget")
# Session 47 -- months later, same governance:
result = engine.policy_check("deploy") # Check before acting
status = engine.risk_limit_check("API spend", 5) # Check budget headroom
report = engine.stats() # Full governance overview
Operational reliability commands (CLI):
acon policy list # All active policies
acon limit list # Current limit usage
acon obligation check # Overdue obligations
acon violation list --severity critical # Critical breaches
acon stats # Full summary
MCP Tools (22 core + 16 advanced capabilities)
Core Tools
Advanced Tools (16)
Once connected, the LLM can enforce policies, track budgets, manage approvals, monitor obligations, and investigate violations -- all backed by the same .acon binary file.
Benchmarks
All measurements on Apple M-series, single-threaded, cold cache. The .acon format uses fixed-size records and BLAKE3 checksums -- no JSON parsing, no query planning overhead.
Why AgenticContract
Governance is a graph, not a checklist. When you trace why an action was denied, you follow a chain: violation ← policy breach ← risk limit exceeded ← approval never granted. That's graph navigation. Simple allow/deny rules can never reconstruct the reasoning.
One file. Truly portable. Your entire governance state is a single .acon file. Copy it. Back it up. Version control it. No cloud service, no API keys, no vendor lock-in.
Any LLM, any time. Start with Claude today. Switch to GPT tomorrow. Move to a local model next year. Same contract file. The governance rules travel with the agent, not with the provider.
Self-healing. When policies conflict or world conditions change, the self-healing contract system proposes amendments. The old policy, the new policy, and the amendment chain are all preserved for audit.
Six entity types. Not just policies. Policies, risk limits, approval workflows, conditions, obligations, and violations -- each with typed lifecycle management. Four policy actions (Allow/Deny/RequireApproval/AuditOnly), four risk limit types (Rate/Threshold/Budget/Count), four violation severities (Info/Warning/Critical/Fatal).
Install
One-liner (desktop profile):
curl -fsSL https://agentralabs.tech/install/contract | bash
Install profiles:
# Desktop (configures Claude Desktop, Cursor, Windsurf)
curl -fsSL https://agentralabs.tech/install/contract/desktop | bash
# Terminal-only (no desktop config writes)
curl -fsSL https://agentralabs.tech/install/contract/terminal | bash
# Remote/server hosts
curl -fsSL https://agentralabs.tech/install/contract/server | bash
Package Managers
# npm
npm install @agenticamem/contract
# pip
pip install agentic-contract
# cargo
cargo install agentic-contract-cli agentic-contract-mcp
Standalone guarantee: AgenticContract works independently. No other Agentra component is required.
Quickstart
CLI -- enforce governance in 4 commands
# Add a deny policy
acon policy add "No production deploys on Friday" --scope global --action deny
# Set a budget limit
acon limit set "API spend" --max 100.0 --type budget
# Add an obligation with a deadline
acon obligation add "Submit compliance report" \
--description "Weekly compliance summary" \
--deadline "2026-03-07T17:00:00Z"
# Check current governance state
acon stats
Python SDK -- governed agent in 5 lines
from agentic_contract import ContractEngine
engine = ContractEngine("agent.acon")
engine.policy_add("Rate limit API calls", scope="global", action="deny")
engine.risk_limit_set("API calls per minute", max_value=60, limit_type="rate")
print(engine.policy_check("call external API")) # Check before acting
MCP -- let Claude enforce contracts
User: "Deploy the staging build to production"
Claude: Let me check the governance policies first.
→ policy_check("deploy to production")
→ Result: RequireApproval
This action requires approval. Let me create an approval request.
→ approval_request(rule_id, "Deploy staging to production", "claude-agent")
→ Waiting for human approval...
MCP Server
Any MCP-compatible client gets instant access to runtime governance. The agentic-contract-mcp crate exposes the full ContractEngine over the Model Context Protocol (JSON-RPC 2.0 over stdio).
cargo install agentic-contract-mcp
Configure Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"agentic-contract": {
"command": "agentic-contract-mcp",
"args": ["serve"]
}
}
}
Zero-config: defaults to
~/.agentic/contract.acon. Override with"args": ["--path", "/path/to/contract.acon", "serve"].
Configure VS Code / Cursor
Add to .vscode/settings.json:
{
"mcp.servers": {
"agentic-contract": {
"command": "agentic-contract-mcp",
"args": ["serve"]
}
}
}
What the LLM gets
Server Mode
For cloud/server deployments, set an authentication token:
export AGENTIC_TOKEN="$(openssl rand -hex 32)"
agentic-contract-mcp serve
Common Workflows
Pre-Action Policy Check
1. policy_check("deploy to production")
2. If denied → stop, report violation
3. If require_approval → approval_request(...)
4. If allowed → proceed
Budget-Controlled Agent
1. risk_limit_set("API spend", max=100, type="budget")
2. Before each call: risk_limit_check("API spend", 0.05)
3. If exceeded → violation_report(...)
Compliance Obligations
1. obligation_add("Submit weekly report", deadline="2026-03-07T17:00:00Z")
2. Periodically: obligation_check()
3. On overdue → violation_report(...)
How It Works
AgenticContract stores all governance data as typed entities in a custom binary format. Entities represent governance primitives (policies, risk limits, approvals, conditions, obligations, violations). The engine evaluates policies, tracks limits, and records breaches at runtime.
The core runtime is written in Rust for performance and safety. All state lives in a portable .acon binary file -- no external databases, no managed services. The MCP server exposes the full engine over JSON-RPC stdio.
The governance model in detail:
Entities are governance primitives -- six types:
Policy actions -- four types: allow · deny · require_approval · audit_only
Risk limit types -- four types: rate · threshold · budget · count
Violation severities -- four levels: info · warning · critical · fatal
+-------------------------------------+
| HEADER 64 bytes | Magic(ACON) . version . flags . entity counts . timestamps
+-------------------------------------+
| POLICY TABLE fixed-size rows | id . label . scope . action . active . conditions . tags
+-------------------------------------+
| RISK LIMIT TABLE fixed-size rows | id . label . type . current . max . window
+-------------------------------------+
| APPROVAL TABLE fixed-size rows | rules . requests . decisions
+-------------------------------------+
| CONDITION TABLE fixed-size rows | id . label . type . expression
+-------------------------------------+
| OBLIGATION TABLE fixed-size rows | id . label . status . deadline . assignee
+-------------------------------------+
| VIOLATION TABLE fixed-size rows | id . description . severity . actor . timestamp
+-------------------------------------+
| CHECKSUM BLAKE3 | Integrity verification
+-------------------------------------+
The binary format uses b"ACON" magic bytes, fixed-size records for O(1) entity access, and BLAKE3 checksums for integrity. No JSON parsing overhead. No external services. Instant access.
Deployment Model
- Standalone by default: AgenticContract is independently installable and operable. Integration with AgenticMemory or other sisters is optional, never required.
- Local-first by default: all governance data lives in a single
.aconbinary file on your filesystem.
Validation
One research paper:
Repository Structure
This is a Cargo workspace monorepo containing the core library, MCP server, CLI, and FFI bindings.
agentic-contract/
├── Cargo.toml # Workspace root
├── crates/
│ ├── agentic-contract/ # Core library (policy engine, file format, advanced capabilities)
│ ├── agentic-contract-mcp/ # MCP server (22 core + 16 advanced tools)
│ ├── agentic-contract-cli/ # CLI binary: acon (policy/limit/approval/obligation/violation)
│ └── agentic-contract-ffi/ # FFI bindings (C header + shared library)
├── python/ # Python SDK (PyPI: agentic-contract)
├── npm/wasm/ # WebAssembly bindings
├── paper/ # Research paper (Paper I: policy engine)
├── scripts/ # Install, CI, and guardrail scripts
├── docs/ # Documentation (public pages, ecosystem kit)
└── .github/workflows/ # CI/CD (build, test, release, guardrails)
Running Tests
# All workspace tests (unit + integration + stress)
cargo test --workspace
# Core engine tests only
cargo test -p agentic-contract
# MCP server stress tests
cargo test -p agentic-contract-mcp --test phase1_mcp_stress
# CLI integration tests
cargo test -p agentic-contract-cli --test cli_integration
# Guardrails
bash scripts/check-canonical-sister.sh
Privacy and Security
- All contract data stays local in your
.aconfile -- no cloud, no telemetry, no network calls - Server mode requires explicit authentication via
AGENTIC_TOKENenvironment variable - MCP transport hardened with Content-Length framing and 8 MiB message limit
- Binary format includes BLAKE3 checksums for integrity verification
- No external dependencies at runtime -- the engine is self-contained
- Report vulnerabilities to: [email protected]
Contributing
See CONTRIBUTING.md for development setup and guidelines. All contributions require:
cargo fmt --all -- --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspacebash scripts/check-canonical-sister.sh
License
MIT -- see LICENSE.