ToolGuard：让AI Agent严格遵守企业规则的确定性合规框架

在AI Agent逐步落地企业场景的今天，工具调用合规成为绕不开的难题：把业务策略塞进Prompt里靠LLM"尽力遵守"，结果总是不可靠、难追溯、难规模化。

今天给大家介绍一款来自EMNLP 2025的开源工具------ToolGuard，它能把企业策略文档自动转化为可执行的Python守卫代码，在工具调用前强制执行合规检查，从根源杜绝越权调用、参数违规等问题，让AI Agent的工具使用从"尽力合规"升级为"必然合规"。

一、为什么需要ToolGuard？传统合规方案的致命缺陷

当前AI Agent的合规管控，大多依赖"Prompt嵌入策略"的方式，这种方案在企业级场景中存在诸多不可忽视的问题：

• 非确定性：策略依赖LLM的临场理解，不同调用场景下执行结果不一致，合规性无法保证；
• 不可追溯：违规行为发生后，难以定位具体违反的策略条款，无法关联原始政策文档，审计难度大；
• 难规模化：随着业务规则增多，Prompt会愈发臃肿，策略修改、维护成本呈指数级上升；
• 无前置拦截：违规调用往往在执行后才被发现，已对系统状态造成污染，挽回成本高。

ToolGuard针对性解决这些痛点，给出了确定性、可预测、可解释 的两阶段解决方案------在工具调用前完成合规校验，不满足策略条件则直接拦截，从源头规避合规风险。

二、ToolGuard核心原理：编译时+运行时的双重保障

ToolGuard的核心逻辑的是"将模糊的业务策略，转化为可执行的代码规则"，采用「编译时生成+运行时拦截」的分离架构，全程围绕"工具级策略强制执行"展开，具体分为三个步骤：

1. 策略解析阶段（编译时） ：输入企业策略文档和工具定义，自动生成ToolGuardSpec规范文件，每个规范都绑定具体工具，包含策略名称、描述、原始策略引用、合规示例（允许调用的场景）和违规示例（需拦截的场景）；
2. 代码生成阶段（编译时） ：将ToolGuardSpec规范，转化为可直接运行的Python守卫函数，同时生成配套测试用例，确保规则可落地；
3. 运行时拦截阶段 ：AI Agent调用工具前，先执行对应的守卫函数，若违反策略则抛出PolicyViolationException异常，阻止工具调用，确保系统状态不被违规操作污染。

ToolGuard的核心优势的是"确定性"------不依赖LLM的临场判断，只要策略定义清晰，守卫代码就会严格执行，所有合规/违规行为都可追溯、可审计。

三、快速上手：5步搭建计算器合规守卫（实操案例）

下面以常见的计算器工具为例，演示如何用ToolGuard实现3条核心策略：禁止除零、禁止两数乘积为365的加法、禁止任一操作数KDI值为6.28的乘法，全程可直接复制代码实操。

1. 环境准备（必做）

ToolGuard要求Python 3.10+，安装步骤如下：

# 克隆仓库（可选，直接安装也可）
git clone https://github.com/AgentToolkit/toolguard.git
cd toolguard

# 核心安装命令
uv pip install toolguard

2. 定义工具与策略（核心步骤）

先定义需要管控的计算器工具，再编写对应的策略文档，两者需一一对应，确保策略可落地。

工具定义（tools.py）

def divide_tool(g: float, h: float) -> float:
    """除法工具：计算两个数的商"""
    return g / h

def add_tool(a: float, b: float) -> float:
    """加法工具：计算两个数的和"""
    return a + b

def multiply_tool(a: float, b: float) -> float:
    """乘法工具：计算两个数的积"""
    return a * b

def map_kdi_number(i: float) -> float:
    """KDI映射工具：将输入数映射为其KDI值（公式：3.14 * 输入）"""
    return 3.14 * i

策略文档（policy.md）

# 计算器使用合规策略
## 操作约束
1. 禁止除零操作：计算器工具不得执行除数为0的除法运算；
2. 禁止特定加法：若两个加数的乘积等于365，禁止执行加法运算（示例：5+73=78，因5×73=365，需拦截）；
3. 禁止特定乘法：若任一乘数的KDI值等于6.28（即输入i=2，3.14×2=6.28），禁止执行乘法运算。

3. 生成守卫规范（编译时第一步）

通过ToolGuard的编译时API，将策略文档和工具转化为ToolGuardSpec规范文件，需配置LLM（支持Azure OpenAI、OpenAI、Anthropic等）。

import asyncio
from pathlib import Path
from toolguard.buildtime import generate_guard_specs, LitellmModel

async def generate_guard_specifications():
    # 1. 配置LLM（以Azure OpenAI为例，可替换为OpenAI、Anthropic）
    llm = LitellmModel(
        model_name="gpt-4o",
        provider="azure",
        kw_args={
            "api_base": "你的Azure API地址",
            "api_version": "2024-08-01-preview",
            "api_key": "你的Azure API密钥"  # 实际使用时注意保密
        }
    )

    # 2. 读取策略文档
    with open("policy.md", "r", encoding="utf-8") as f:
        policy_text = f.read()

    # 3. 定义需要管控的工具
    tools = [divide_tool, add_tool, multiply_tool, map_kdi_number]

    # 4. 生成守卫规范，输出到指定目录
    specs = await generate_guard_specs(
        policy_text=policy_text,
        tools=tools,
        work_dir="output/step1",  # 规范文件输出目录
        llm=llm,
        # 可选：简化生成流程，加快速度（适合快速测试）
        options=PolicySpecOptions(spec_steps={PolicySpecStep.CREATE_POLICIES})
    )
    return specs

# 执行生成
specs = asyncio.run(generate_guard_specifications())

生成后，可在output/step1目录下查看规范文件，建议人工复核一遍，修正可能的错误示例（如误判的合规/违规场景）。

4. 生成守卫代码（编译时第二步）

将上一步生成的ToolGuardSpec规范，转化为可执行的Python守卫代码，用于运行时拦截。

from toolguard.buildtime import generate_guards_code

async def generate_guard_code():
    # 复用第一步的specs和llm，生成守卫代码
    guards = await generate_guards_code(
        tool_specs=specs,
        tools=tools,
        work_dir="output/step2",  # 守卫代码输出目录
        llm=llm,
        app_name="calculator"  # 应用名称，用于命名生成的文件
    )
    return guards

# 执行代码生成
guards = asyncio.run(generate_guard_code())

5. 运行时强制执行（核心落地步骤）

加载生成的守卫代码，在AI Agent调用工具时，自动执行合规检查，违规则拦截并抛出异常。

from toolguard.runtime import (
    load_toolguards,
    ToolFunctionsInvoker,
    PolicyViolationException
)

# 1. 加载生成的守卫代码
with load_toolguards("output/step2") as toolguard:
    # 2. 创建工具调用器（适配普通Python函数）
    invoker = ToolFunctionsInvoker([divide_tool, add_tool, multiply_tool])

    # 3. 合规调用：正常执行，无异常
    await toolguard.guard_toolcall("add_tool", {"a": 5, "b": 4}, invoker)  # 5+4=9，乘积≠365
    await toolguard.guard_toolcall("divide_tool", {"g": 10, "h": 2}, invoker)  # 10÷2=5，除数≠0

    # 4. 违规调用：抛出PolicyViolationException异常
    try:
        # 违规场景1：除零操作
        await toolguard.guard_toolcall("divide_tool", {"g": 5, "h": 0}, invoker)
    except PolicyViolationException as e:
        print(f"策略违规（除零）：{e}")

    try:
        # 违规场景2：两数乘积为365的加法（5×73=365）
        await toolguard.guard_toolcall("add_tool", {"a": 5, "b": 73}, invoker)
    except PolicyViolationException as e:
        print(f"策略违规（加法限制）：{e}")

运行后，违规调用会被精准拦截，控制台输出违规原因，便于排查和审计。

四、多场景兼容：适配主流AI Agent工具形态

ToolGuard不仅支持普通Python函数，还深度兼容企业常用的Agent工具形态，无需大幅修改代码即可集成，具体适配方式如下：

1. 类方法工具

from toolguard.runtime import ToolMethodsInvoker
from toolguard.extra.api_to_functions import api_cls_to_functions

# 定义类方法形式的工具
class CalculatorTools:
    def divide_tool(self, g: float, h: float) -> float:
        return g / h

    def add_tool(self, a: float, b: float) -> float:
        return a + b

# 转换类方法为函数（用于生成规范）
tools = api_cls_to_functions(CalculatorTools)

# 运行时使用类方法调用器
invoker = ToolMethodsInvoker(CalculatorTools())

2. LangChain工具

from langchain.tools import tool
from toolguard.runtime import LangchainToolInvoker
from toolguard.extra.langchain_to_oas import langchain_tools_to_openapi

# 定义LangChain工具
@tool
def divide_tool(g: float, h: float) -> float:
    """除法工具"""
    return g / h

tools = [divide_tool, add_tool]

# 转换为OpenAPI规范（用于生成守卫）
oas = langchain_tools_to_openapi(tools)

# 运行时使用LangChain调用器（注意：参数需包裹在"args"键中）
invoker = LangchainToolInvoker(tools)
await toolguard.guard_toolcall("divide_tool", {"args": {"g": 5, "h": 2}}, invoker)

3. OpenAPI接口工具

from toolguard.buildtime.utils.open_api import OpenAPI

# 加载OpenAPI规范文件（JSON/YAML）
oas = OpenAPI.load_from("calculator_api.json")

# 基于OpenAPI生成守卫代码
guards = await generate_guards_code(
    tool_specs=specs,
    tools=oas.model_dump(),
    work_dir="output/step2",
    llm=llm,
    app_name="calculator"
)

4. MCP服务工具

import asyncio
from fastmcp.client import Client, StreamableHttpTransport
from toolguard.extra.mcp_tools_to_oas import list_mcp_tools, mcp_tools_to_openapi

async def export_mcp_tools():
    # 连接MCP服务器
    transport = StreamableHttpTransport(url="http://127.0.0.1:8765/mcp")
    mcp_client = Client(transport)

    # 列出MCP服务器上的工具
    tools = await list_mcp_tools(mcp_client)

    # 转换为OpenAPI规范，用于生成守卫
    openapi_spec = mcp_tools_to_openapi(
        tools,
        title="My MCP Tools",
        version="1.0.0"
    )
    return openapi_spec

openapi_spec = asyncio.run(export_mcp_tools())

五、高级配置：精准控制合规逻辑（企业级优化）

针对企业复杂场景，ToolGuard提供多种高级配置，可灵活调整策略生成和执行逻辑，降低维护成本：

1. 选择性生成工具守卫

只对核心工具生成守卫，非核心工具跳过，减少冗余代码：

# 只对divide_tool、add_tool生成规范
specs = await generate_guard_specs(
    policy_text=policy_text,
    tools=tools,
    work_dir="output/step1",
    llm=llm,
    tools2guard=["divide_tool", "add_tool"]  # 指定需要管控的工具
)

# 只对divide_tool生成守卫代码
guards = await generate_guards_code(
    tool_specs=specs,
    tools=tools,
    work_dir="output/step2",
    llm=llm,
    app_name="calculator",
    tool_names=["divide_tool"]
)

2. 自定义策略生成流程

通过PolicySpecOptions控制策略生成的步骤（创建、补充、复核等），按需优化生成效率：

from toolguard.buildtime import PolicySpecOptions, PolicySpecStep

# 配置生成步骤和参数
options = PolicySpecOptions(
    spec_steps={
        PolicySpecStep.CREATE_POLICIES,  # 提取初始策略
        PolicySpecStep.ADD_POLICIES,     # 迭代优化策略
        PolicySpecStep.REVIEW_POLICIES   # 复核策略正确性
    },
    add_iterations=2,  # 优化迭代次数（默认3次）
    example_number=3    # 每个策略生成3个示例（默认由LLM决定）
)

3. 多厂商LLM适配

支持Azure OpenAI、OpenAI、Anthropic等主流LLM，可根据成本和性能灵活切换：

from toolguard.buildtime import LitellmModel

# 1. Azure OpenAI（推荐企业使用，合规性更强）
llm = LitellmModel(
    model_name="gpt-4o-2024-08-06",
    provider="azure",
    kw_args={
        "api_base": "https://your-resource.openai.azure.com",
        "api_version": "2024-08-01-preview",
        "api_key": "your-api-key"
    }
)

# 2. OpenAI
llm = LitellmModel(
    model_name="gpt-4o",
    provider="openai",
    kw_args={"api_key": "your-api-key"}
)

# 3. Anthropic（Claude系列）
llm = LitellmModel(
    model_name="claude-3-5-sonnet-20241022",
    provider="anthropic",
    kw_args={"api_key": "your-api-key"}
)

4. 错误处理与审计

捕获违规异常，实现日志记录、告警等功能，满足企业审计需求：

from toolguard.runtime import PolicyViolationException

try:
    # 尝试调用违规工具
    await toolguard.guard_toolcall("divide_tool", {"g": 5, "h": 0}, invoker)
except PolicyViolationException as e:
    # 处理合规违规：记录日志、通知管理员
    print(f"策略违规：{e}")
    # 可添加日志记录、邮件告警等逻辑
except Exception as e:
    # 处理其他异常（如工具本身错误）
    print(f"意外错误：{e}")

六、项目价值与适用场景

ToolGuard源自EMNLP 2025论文《Towards Enforcing Company Policy Adherence in Agentic Workflows》，将学术成果落地为工程化工具，核心价值是「降低企业级AI Agent的合规落地成本」，适合以下场景：

• 金融AI Agent：管控交易工具、查询工具，禁止越权操作、违规交易；
• 办公AI Agent：限制敏感文件操作、权限内工具调用，保护企业数据安全；
• 工业AI Agent：拦截危险参数、非法控制指令，避免设备损坏或安全事故；
• 客服AI Agent：遵守话术规范、数据隐私规则，杜绝违规话术或信息泄露。

七、总结与项目地址

AI Agent要走进企业核心场景，合规是底线，确定性是关键。ToolGuard的核心价值，就是把"模糊的业务策略"变成"硬编码的执行规则"，用标准化的流程（策略解析→代码生成→运行拦截），低成本实现工具级合规强制执行，解决了Prompt方案的固有缺陷。

无论是个人开发者做Agent安全加固，还是企业搭建合规Agent体系，ToolGuard都是值得加入技术栈的硬核工具。

项目地址：https://github.com/AgentToolkit/toolguard