AI Agent 工具调用校验与 CI 模板
用于在执行前检查 AI Agent 工具调用的本地示例，覆盖白名单、部分路径参数与预算限制；完整 Schema 校验需要安装依赖。用于生产前仍须接入并测试真实执行器。
Python 3.10–3.12 已通过 v0.2.0 托管 CI 矩阵；这不代表客户系统集成已被验证。
本地快速上手
固定到已发布的 Starter 标签 v0.2.0。演示模式只用 Python 标准库；完整验证需另行安装依赖。示例测试均不调用付费模型 API。
# 克隆仓库并进入脚手架目录
git clone https://github.com/bartsaiconsulting/agent-production-starter.git
cd agent-production-starter
git checkout v0.2.0
python3 --version
# 零依赖演示；Schema/Pydantic/DeepEval 检查会标为跳过
python3 run_tests.py --demo
# 安装依赖后运行完整验证
python3 -m pip install -r requirements-core.txt
python3 run_tests.py --full
# 运行工具拦截示例
PYTHONPATH=. python3 examples/guard_demo.py
DETERMINISTIC ARCHITECTURE
四类本地工程检查
示例检查在工具调用前运行。真实应用须让每次调用经过检查，并另外实现运行环境隔离与业务授权。
步数硬上限与死循环哈希检测
严格限制单次会话最大工具调用步数（如 10 步），监控累计消耗 Token 与费用上限。计算工具名与参数的 SHA256 哈希值，连续 3 次相同调用即强制熔断报错。
工具白名单与已知路径参数检查
检查工具白名单和字典/列表中的已知路径字段，拒绝解析后超出声明根目录的路径（如 ../../../../etc/passwd）。不约束真实执行器、未知参数或校验后的符号链接变化。
审批令牌校验
将工具划分为 只读 (READ_ONLY)、可写 (MUTATIVE_WRITE) 与 破坏性 (DESTRUCTIVE) 权限分层。启用审批要求时，守卫拒绝令牌不在预设集合中的破坏性调用。示例不校验签名、有效期、单次使用或人员与操作绑定；应用仍需落实审批流程，并确保每次工具执行前都经过守卫校验。
强类型 JSON Schema 与无条件 WHERE 拦截
安装依赖后可用 JSON Schema 与 Pydantic 检查参数；独立辅助函数拒绝空 WHERE 参数。数据库授权和真实查询语义仍由应用负责。
如何接入现有 Agent 代码库
兼容 LangChain、CrewAI、AutoGen 或自定义 Tool Calling 循环：
from pathlib import Path
from bartsai_guard import ToolGuard, ToolPermissionLevel, CircuitBreaker
# 1. 配置边界与权限分层
guard = ToolGuard(
allowed_tools={"query_db", "write_file", "drop_table"},
tool_permissions={
"query_db": ToolPermissionLevel.READ_ONLY,
"write_file": ToolPermissionLevel.MUTATIVE_WRITE,
"drop_table": ToolPermissionLevel.DESTRUCTIVE, # 需二次人工签署凭据!
},
sandbox_root=Path("./agent_workspace").resolve(),
require_human_approval_for_destructive=True,
valid_approval_tokens={"user_session_token_xyz"}
)
breaker = CircuitBreaker(max_steps=10, max_cost_usd=0.50)
def safe_tool_executor(tool_name: str, arguments: dict, token: str = None):
# 步骤 A：步数与死循环熔断断言
breaker.record_step(tool_name, arguments, step_tokens=400, step_cost_usd=0.005)
# 步骤 B：工具白名单与已知路径参数检查
guard.inspect_and_authorize(tool_name, arguments, approval_token=token)
# 步骤 C：执行器使用已校验目标并自行实施隔离
return actual_tool_implementation(tool_name, arguments)即将把具备真实执行权限的 Agent 推向生产？
公开 Starter 代码提供可复用示例，高风险企业级 Agent 仍需结合实际部署核验跨租户隔离、权限与业务风险。了解 BartsAI 为期 1 周的独立 Launch Gate 架构审查。