agentralabs/agentic-contract

# AgenticContract

AI 智能体的策略引擎。

每一次操作都被检查。每一项限制都被执行。每一次违规都被记录。始终如一。

解决的问题 · 快速开始 · 工作原理 · 性能基准 · 安装 · API · 论文

## 每一个 AI 智能体都处于无治理状态。 Claude 可能超出你的 API 预算。GPT 可能绕过审批关卡。你的 copilot 可能在无人察觉的情况下违反合规规则。**每一个动作都在没有监督的情况下发生。** 当前的修复方案无效。手动策略检查会被遗忘。速率限制位于智能体无法检查的应用代码中。审批流程需要外部服务。合规义务在电子表格中跟踪。违规行为直到为时已晚才被发现。 **AgenticContract** 将策略、风险限制、审批、条件、义务和违规建模在单个二进制 `.acon` 文件中。不是“添加一个配置文件”。你的智能体拥有一个**治理引擎**——行为约束、预算执行、审批关卡和违规跟踪——全部结构化，全部可在微秒内查询。

## 解决的问题（首先阅读此部分） - **问题：** 智能体在没有策略约束的情况下运行，可以采取任何行动。 **已解决：** 类型化策略（allow/deny/require_approval/audit_only）以亚毫秒级的评估执行行为规则。 - **问题：** 没有对资源预算或速率限制的运行时感知。 **已解决：** 具有实时跟踪和阈值警报的量化风险限制。 - **问题：** 高风险操作在没有人工介入（human-in-the-loop）审批的情况下发生。 **已解决：** 具有请求/决策生命周期和审计追踪的结构化审批流程。 - **问题：** 合规义务被非正式跟踪，截止日期被错过。 **已解决：** 具有自动逾期检测的截止日期跟踪义务。 - **问题：** 策略违规未被发现且未被记录。 **已解决：** 具有预知和考古工具的严重性分类违规记录。 ``` from agentic_contract import ContractEngine engine = ContractEngine("agent.acon") # 您的智能体受管辖 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") # 会话 47 -- 数月后，相同的治理： 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 ``` 运维可靠性命令 (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 工具（22 个核心 + 16 个高级功能） ### 核心工具 | 类别 | 工具 | 描述 | |:---|:---|:---| | **Contract** | `contract_create` | 在智能体之间或智能体与用户之间创建新合约 | | | `contract_sign` | 签署合约以表示接受 | | | `contract_verify` | 验证合约的有效性和签名链 | | | `contract_list` | 列出合约，可选状态过滤 | | | `contract_get` | 通过 ID 获取特定合约 | | **Policy** | `policy_add` | 添加管理智能体行为的策略规则 | | | `policy_check` | 检查当前策略是否允许某项操作 | | | `policy_list` | 列出活动策略，可选范围过滤 | | **Risk** | `risk_limit_set` | 为资源或操作设置风险限制阈值 | | | `risk_limit_check` | 检查操作是否会超过风险限制 | | | `risk_limit_list` | 列出所有风险限制及其当前值 | | **Approval** | `approval_request` | 请求批准受控操作 | | | `approval_decide` | 批准或拒绝待处理的审批请求 | | | `approval_list` | 列出审批请求，可选状态过滤 | | **Condition** | `condition_add` | 添加条件执行规则 | | | `condition_evaluate` | 评估操作的条件是否已满足 | | **Obligation** | `obligation_add` | 添加智能体必须履行的义务 | | | `obligation_check` | 检查义务的状态 | | **Violation** | `violation_list` | 列出已记录的违规，可选严重性过滤 | | | `violation_report` | 报告合约或策略违规 | | **Context** | `contract_context_log` | 记录合约操作背后的意图和上下文 | | **Stats** | `contract_stats` | 获取合约存储的摘要统计信息 | ### 高级工具（16 个） | 工具 | 描述 | |:---|:---| | `policy_omniscience` | 分析影响智能体的所有策略 | | `risk_prophecy` | 预测风险限制违规发生前的 breaches | | `approval_telepathy` | 预测提议操作的审批路径 | | `obligation_clairvoyance` | 预测未来的义务状态和截止日期 | | `violation_precognition` | 预测计划操作的违规概率 | | `contract_crystallize` | 从意图描述生成完整合约 | | `policy_dna_extract` | 提取策略演变的基因模式 | | `trust_gradient_evaluate` | 评估智能体-操作对的信任梯度 | | `collective_contract_create` | 创建多方治理合约 | | `temporal_contract_create` | 创建具有治理级别演变的合约 | | `contract_inheritance_create` | 建立父子策略继承 | | `smart_escalation_route` | 智能地将违规路由给正确的审批人 | | `violation_archaeology_analyze` | 分析历史违规模式 | | `contract_simulation_run` | 在各种场景下模拟合约行为 | | `federated_governance_create` | 跨域创建联邦治理 | | `self_healing_contract_create` | 创建适应违规模式的合约 | 连接后，LLM 可以执行策略、跟踪预算、管理审批、监控义务和调查违规——全部由同一个 `.acon` 二进制文件支持。 ## 性能基准

| 操作 | 延迟 | 备注 | |:---|---:|:---| | 单策略评估 | **0.03 ms** | 基于哈希的范围查找 | | 风险限制检查 | **0.04 ms** | 直接比较 | | 审批请求创建 | **0.05 ms** | UUID + 插入 | | 义务逾期检查 | **0.02 ms** | 时间戳比较 | | 违规报告 | **0.04 ms** | 追加 + 分类 | | 1K 策略评估 | **0.3 ms** | 带范围过滤的线性扫描 | | 10K 策略评估 | **2.9 ms** | 完整引擎遍历 | | 保存 10K 实体 | **24 ms** | 二进制序列化 + BLAKE3 校验和 | | 加载 10K 实体 | **18 ms** | 内存映射文件读取 | | 统计计算 | **0.01 ms** | 预索引计数器 | 所有测量均在 Apple M 系列、单线程、冷缓存下进行。`.acon` 格式使用固定大小的记录和 BLAKE3 校验和——无 JSON 解析，无查询计划开销。 ## 为什么选择 AgenticContract **治理是一张图，而不是清单。** 当你追溯*为什么*操作被拒绝时，你会遵循一条链：违规 ← 策略违规 ← 风险限制超限 ← 审批从未授予。这就是图导航。简单的 allow/deny 规则永远无法重建推理。 **一个文件。真正的可移植性。** 你的整个治理状态是一个单独的 `.acon` 文件。复制它。备份它。版本控制它。没有云服务，没有 API 密钥，没有供应商锁定。 **任何 LLM，任何时间。** 今天从 Claude 开始。明天切换到 GPT。明年迁移到本地模型。相同的合约文件。治理规则随智能体移动，而不是随提供商。 **自愈。** 当策略冲突或世界条件改变时，自愈合约系统提出修正案。旧策略、新策略和修正案链都被保留以供审计。 **六种实体类型。** 不仅仅是策略。策略、风险限制、审批流程、条件、义务和违规——每种都有类型化的生命周期管理。四种策略动作，四种风险限制类型（Rate/Threshold/Budget/Count），四种违规严重程度。 ## 安装 **单行命令**（桌面配置）： ``` curl -fsSL https://agentralabs.tech/install/contract | bash ``` 安装配置： ``` # Desktop（配置 Claude Desktop、Cursor、Windsurf） curl -fsSL https://agentralabs.tech/install/contract/desktop | bash # 仅 Terminal（无 desktop 配置写入） curl -fsSL https://agentralabs.tech/install/contract/terminal | bash # 远程/服务器主机 curl -fsSL https://agentralabs.tech/install/contract/server | bash ``` ### 包管理器 ``` # npm npm install @agenticamem/contract # pip pip install agentic-contract # cargo cargo install agentic-contract-cli agentic-contract-mcp ``` ## 快速开始 ### CLI —— 用 4 个命令执行治理 ``` # 添加 deny 策略 acon policy add "No production deploys on Friday" --scope global --action deny # 设置预算限制 acon limit set "API spend" --max 100.0 --type budget # 添加带截止日期的 obligation acon obligation add "Submit compliance report" \ --description "Weekly compliance summary" \ --deadline "2026-03-07T17:00:00Z" # 检查当前治理状态 acon stats ``` ### Python SDK —— 5 行代码实现受治理智能体 ``` 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 —— 让 Claude 执行合约 ``` 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 **任何兼容 MCP 的客户端都能即时获得运行时治理访问权限。** `agentic-contract-mcp` crate 通过 [Model Context Protocol](https://modelcontextprotocol.io)（基于 stdio 的 JSON-RPC 2.0）公开完整的 ContractEngine。 ``` cargo install agentic-contract-mcp ``` ### 配置 Claude Desktop 添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`: ``` { "mcpServers": { "agentic-contract": { "command": "agentic-contract-mcp", "args": ["serve"] } } } ``` ### 配置 VS Code / Cursor 添加到 `.vscode/settings.json`: ``` { "mcp.servers": { "agentic-contract": { "command": "agentic-contract-mcp", "args": ["serve"] } } } ``` ### LLM 获得的能力 | 类别 | 数量 | 示例 | |:---|---:|:---| | **Tools** | 38 | `policy_add`, `policy_check`, `risk_limit_set`, `approval_request`, `violation_report`, `contract_crystallize` ... | | **Resources** | 4 | `acon://contract/stats`, `acon://contract/policies`, `acon://contract/violations` ... | | **Prompts** | 4 | `contract_review`, `contract_setup`, `contract_audit`, `contract_risk_assessment` | ### 服务器模式 对于云/服务器部署，设置认证令牌： ``` export AGENTIC_TOKEN="$(openssl rand -hex 32)" agentic-contract-mcp serve ``` ## 常见工作流 ### 操作前策略检查 ``` 1. policy_check("deploy to production") 2. If denied → stop, report violation 3. If require_approval → approval_request(...) 4. If allowed → proceed ``` ### 预算控制智能体 ``` 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(...) ``` ### 合规义务 ``` 1. obligation_add("Submit weekly report", deadline="2026-03-07T17:00:00Z") 2. Periodically: obligation_check() 3. On overdue → violation_report(...) ``` ## 工作原理

AgenticContract 将所有治理数据作为**类型化实体**存储在自定义二进制格式中。实体代表治理原语（策略、风险限制、审批、条件、义务、违规）。引擎在运行时评估策略、跟踪限制并记录违规。 核心运行时用 Rust 编写，以保证性能和安全性。所有状态都存在于可移植的 `.acon` 二进制文件中——没有外部数据库，没有托管服务。MCP server 通过 JSON-RPC stdio 公开完整的引擎。 **详细的治理模型：** **实体**是治理原语——六种类型： | 类型 | 含义 | 示例 | |:---|:---|:---| | **Policy** | 行为约束 | "周五禁止生产环境部署"（deny，全局范围） | | **Risk Limit** | 量化边界 | "API 支出"（budget，最大 $100，当前 $47.50） | | **Approval Rule** | 高风险操作的关卡 | "生产环境部署需要团队负责人审批" | | **Condition** | 前提条件检查 | "部署前必须通过测试"（阈值条件） | | **Obligation** | 跟踪的承诺 | "在 3 月 7 日前提交合规报告"（待处理，有截止日期） | | **Violation** | 违规记录 | "14:32 超出速率限制"（严重级别） | **策略动作**——四种类型：`allow` · `deny` · `require_approval` · `audit_only` **风险限制类型**——四种类型：`rate` · `threshold` · `budget` · `count` **违规严重程度**——四个级别：`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 +-------------------------------------+ ``` 二进制格式使用 `b"ACON"` 魔术字节、用于 O(1) 实体访问的固定大小记录以及用于完整性的 BLAKE3 校验和。无 JSON 解析开销。无外部服务。即时访问。 [完整格式规范 ->](docs/public/file-format.md)

## 部署模型 - **默认独立：** AgenticContract 可独立安装和运行。与 AgenticMemory 或其他姐妹项目的集成是可选的，绝非必需。 - **默认本地优先：** 所有治理数据都位于文件系统上的单个 `.acon` 二进制文件中。 | 区域 | 默认行为 | 控制方式 | |:---|:---|:---| | 文件位置 | `~/.agentic/contract.acon` | `ACON_PATH=/custom/path.acon` | | 服务器认证 | 服务器模式下必需 | `AGENTIC_TOKEN=` | | 传输方式 | stdio (JSON-RPC 2.0) | `agentic-contractcp serve` | | 帧大小限制 | 最大 8 MiB 消息 | `MAX_CONTENT_LENGTH_BYTES` | | JSON-RPC 版本 | 严格的 2.0 验证 | 拒绝 1.0 和无效版本 | | 策略范围 | Global、Session 或 Agent | 每个策略的范围分配 | ## 验证 | 测试套件 | 测试数 | | |:---|---:|:---| | Rust 核心引擎 | **33** | 所有 6 种实体类型的单元测试 + SDK trait 实现 | | 引擎高级压力测试 | **55** | 所有 16 种高级功能 + 大数据集 + 错误路径 | | 现有压力/边缘情况 | **14** | 边界条件、Unicode、并发 | | MCP 服务器压力测试 | **80** | 所有 38 个工具、协议合规性、传输、并发 | | 服务器压力测试 | **30** | Prompts、resources、传输边缘情况、认证 | | CLI 集成 | **41** | 所有子命令、错误参数、持久化、工作流 | | 边缘情况高级 | **29** | MCP 质量标准合规性 | | MCP 库单元测试 | **6** | 传输和 JSON-RPC 验证 | | **总计** | **288** | 全部通过 | **一篇研究论文：** - [论文 I: AgenticContract —— AI 智能体的策略引擎](paper/paper-i-policy-engine/paper.tex) ## 仓库结构 这是一个包含核心库、MCP server、CLI 和 FFI 绑定的 Cargo workspace monorepo。 ``` 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) ``` ### 运行测试 ``` # 所有工作区测试（单元 + 集成 + 压力） cargo test --workspace # 仅 Core 引擎测试 cargo test -p agentic-contract # MCP server 压力测试 cargo test -p agentic-contract-mcp --test phase1_mcp_stress # CLI 集成测试 cargo test -p agentic-contract-cli --test cli_integration # Guardrails bash scripts/check-canonical-sister.sh ``` ## 隐私与安全 - **所有合约数据保留在本地**，位于你的 `.acon` 文件中——无云端、无遥测、无网络调用 - **服务器模式需要显式认证**，通过 `AGENTIC_TOKEN` 环境变量 - **MCP 传输经过加固**，具有 Content-Length 帧和 8 MiB 消息限制 - **二进制格式包含 BLAKE3 校验和**，用于完整性验证 - **运行时无外部依赖**——引擎是自包含的 - 报告漏洞至：security@agentralabs.tech ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置和指南。所有贡献都需要： 1. `cargo fmt --all -- --check` 2. `cargo clippy --workspace --all-targets -- -D warnings` 3. `cargo test --workspace` 4. `bash scripts/check-canonical-sister.sh` ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

_{由 Agentra Labs 构建}

标签：ACL, AI代理, AI工具, API安全, JSON输出, LLM应用层, MCP服务器, Python, Rust, Streamlit, 义务跟踪, 人工智能安全, 可视化界面, 合规性, 大语言模型安全, 审批流程, 文档结构分析, 无后门, 机密管理, 治理, 知识图谱, 策略引擎, 网络安全挑战, 网络流量审计, 自动化合规, 规则执行, 访问控制, 违约检测, 逆向工具, 通知系统, 预算控制