六大工具调用合约验证引擎架构拆解

┌──────────────┐     ┌──────────────────┐     ┌───────────────┐
│  Tool Schema │────▶│  Constrained     │────▶│  Guaranteed   │
│  (JSON Schema│     │  Decoding        │     │  JSON Output  │
│   strict: true)    │  (token-level)   │     │  (100% valid) │
└──────────────┘     └──────────────────┘     └───────────────┘

from openai import OpenAI
client = OpenAI()

# strict模式：模型侧强制Schema合规
tools = [{
    "type": "function",
    "function": {
        "name": "transfer_money",
        "strict": True,  # 关键：启用token级约束
        "parameters": {
            "type": "object",
            "properties": {
                "amount": {"type": "number"},
                "recipient": {"type": "string"},
                "currency": {"type": "string", "enum": ["USD","EUR","CNY","JPY"]}
            },
            "required": ["amount", "recipient", "currency"],
            "additionalProperties": False  # strict模式必须
        }
    }
}]

response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "转账500美元给Alice"}],
    tools=tools
)
# 输出保证符合Schema，但amount可以为负数！

graph TD
    A["Python函数签名<br/>+ 类型标注"] -->|"自动生成"| B["JSON Schema"]
    B -->|"发送给"| C["LLM (GPT/Claude/Gemini)"]
    C -->|"返回JSON"| D["Pydantic Validator"]
    D -->|"类型校验"| E{"校验通过?"}
    E -->|"是"| F["类型安全的Python对象"]
    E -->|"否"| G["ValidationError<br/>+ 自动重试/回退"]
    G -->|"反馈给LLM"| C
    F --> H["执行工具函数"]

from pydantic_ai import Agent, RunContext
from pydantic import Field, validator
from typing import Annotated

agent = Agent('openai:gpt-5.2')

@agent.tool
def transfer_money(
    ctx: RunContext[str],
    amount: Annotated[float, Field(gt=0, description="转账金额，必须为正数")],
    recipient: Annotated[str, Field(min_length=1, max_length=50)],
    currency: Annotated[str, Field(pattern=r"^[A-Z]{3}$")] = "USD"
) -> str:
    """执行转账操作。金额必须为正数，货币为3字母代码。"""
    # Pydantic自动校验：amount>0, recipient长度, currency正则
    return f"成功转账{amount} {currency}给{recipient}"

# 如果LLM生成 amount=-500，Pydantic抛出ValidationError
# 框架自动将错误反馈给模型，触发重试
result = agent.run_sync("转500美元给Alice")

Hoare三元组: {P} tool_call(args) {Q}
P = 前置条件（调用前必须满足的状态）
Q = 后置条件（调用后必须保证的状态）

示例：
P: account.balance >= amount ∧ amount > 0
Q: account.balance' = account.balance - amount

如果P不满足 → 阻止调用，返回给LLM重新规划
如果P满足但Q不成立 → 标记异常，触发补偿

# ToolGate风格的前置/后置条件定义（概念示例）
from toolgate import Tool, Precondition, Postcondition

class TransferTool(Tool):
    name = "transfer_money"
    parameters = {
        "amount": {"type": "number"},
        "recipient": {"type": "string"},
        "currency": {"type": "string"}
    }

    @Precondition
    def check_balance(self, ctx, args):
        """前置条件：账户余额充足且金额为正"""
        return ctx.account_balance >= args.amount and args.amount > 0

    @Postcondition
    def verify_transfer(self, ctx, args, result):
        """后置条件：余额正确扣减"""
        expected = ctx.prev_balance - args.amount
        return ctx.account_balance == expected

# 如果LLM尝试调用 amount=-500
# → 前置条件检查失败（amount > 0 不满足）
# → 调用被阻止，返回"金额必须为正数"给LLM
# → LLM重新生成正确的调用

graph LR
    A["Zod Schema<br/>z.object({...})"] -->|"z.toJsonSchema()"| B["JSON Schema"]
    B -->|"发送给LLM"| C["GPT-5.2 / Claude-4"]
    C -->|"返回参数JSON"| D["schema.parse(json)"]
    D -->|"结构校验"| E{"refine()校验"}
    E -->|"通过"| F["安全执行"]
    E -->|"失败"| G["ZodError → 反馈LLM"]

import { z } from 'zod';
import { generateText, tool } from 'ai';

// Zod v4: 类型安全的工具Schema定义
const transferSchema = z.object({
  amount: z.number().positive("金额必须为正数"),
  recipient: z.string().min(1).max(50),
  currency: z.string().regex(/^[A-Z]{3}$/)
}).refine(
  (data) => data.amount <= 1000000,
  { message: "单笔转账上限100万" }
);

// Vercel AI SDK: Zod直接绑定到tool
const result = await generateText({
  model: openai('gpt-5.2'),
  tools: {
    transfer: tool({
      description: '执行转账操作',
      parameters: transferSchema,  // Zod schema直接传入
      execute: async ({ amount, recipient, currency }) => {
        // TypeScript自动推断参数类型！
        return `成功转账${amount} ${currency}给${recipient}`;
      }
    })
  },
  prompt: '转账500美元给Alice'
});
// 如果amount为负数 → Zod校验失败 → 自动反馈给LLM重试

MCP工具定义（协议规范片段）:
{
  "name": "transfer_money",
  "description": "执行转账",
  "inputSchema": {
    "type": "object",
    "properties": {
      "amount": {"type": "number", "minimum": 0.01},
      "recipient": {"type": "string"},
      "currency": {"type": "string", "enum": ["USD","EUR","CNY","JPY"]}
    },
    "required": ["amount", "recipient"]
  }
}

tools/call请求 → Schema校验 → 执行/拒绝

验证覆盖率金字塔：

         ┌──────────────┐
         │  逻辑安全     │  ← ToolGate (Hoare逻辑)
         │  (可证明)     │     覆盖率：~5% (极少部署)
         ├──────────────┤
         │  语义校验     │  ← Pydantic/Zod refine
         │  (业务规则)   │     覆盖率：~30% (增长中)
         ├──────────────┤
         │  结构合规     │  ← OpenAI Strict / MCP Schema
         │  (JSON Schema)│     覆盖率：~100% (主流)
         └──────────────┘

graph TD
    subgraph "第一层：模型侧约束"
        A["OpenAI Structured Outputs<br/>strict=true<br/>100% Schema合规"]
    end

    subgraph "第二层：框架侧校验"
        B["PydanticAI / Zod v4<br/>类型校验 + 业务规则<br/>~98% 语义合规"]
    end

    subgraph "第三层：协议侧校验"
        C["MCP Schema Validation<br/>跨服务一致性<br/>防御传输层变异"]
    end

    subgraph "第四层：执行前验证"
        D["ToolGate Pre-condition<br/>余额/权限/状态检查<br/>拦截最后一公里"]
    end

    subgraph "第五层：执行后验证"
        E["Post-condition + 补偿<br/>结果一致性验证<br/>异常自动回滚"]
    end

    F["LLM生成工具调用"] --> A
    A -->|"Schema通过"| B
    A -->|"Schema失败"| F
    B -->|"校验通过"| C
    B -->|"校验失败<br/>+ 反馈"| F
    C --> D
    D -->|"前置条件满足"| G["执行工具"]
    D -->|"前置条件不满足<br/>+ 反馈"| F
    G --> E
    E -->|"后置条件成立"| H["返回结果"]
    E -->|"后置条件异常"| I["触发补偿事务"]