┌─────────────────────────────────────────────────────────┐
│           工具调用生产失败五分类                           │
│                                                         │
│  ① 选错工具 ────── 占比 12-18%                          │
│     模型选了语义相近但功能不同的工具                       │
│                                                         │
│  ② 参数类型不匹配 ── 占比 25-35% (最大头)               │
│     传了string给int字段、日期格式错误、枚举值越界          │
│                                                         │
│  ③ 缺失必填参数 ──── 占比 15-20%                        │
│     漏传required字段，尤其是嵌套对象内部                  │
│                                                         │
│  ④ 幻觉参数 ──────── 占比 8-12%                         │
│     编造了schema中不存在的参数名或值                      │
│                                                         │
│  ⑤ 工具链逻辑错误 ── 占比 15-25%                        │
│     调用顺序错误、依赖未满足、条件判断缺失                │
│                                                         │
└─────────────────────────────────────────────────────────┘

graph TB
    subgraph MCP["MCP (Anthropic主导)"]
        M1[Tool Discovery] --> M2[Schema Validation]
        M2 --> M3[Execution]
        M3 --> M4[Result Parsing]
        M1 -.-> |"动态注册"| M1
    end

    subgraph OAI["OpenAI Function Calling"]
        O1[Tool Definition] --> O2[Strict Schema]
        O2 --> O3[Parallel Calling]
        O3 --> O4[Structured Output]
        O2 -.-> |"CFG强制"| O2
    end

    subgraph GCP["Google Vertex Tool Use"]
        G1[Function Declaration] --> G2[Auto-execute]
        G2 --> G3[Grounding]
        G3 --> G4[Extensions"]
        G2 -.-> |"自动执行"| G2
    end

    style MCP fill:#e8f5e9
    style OAI fill:#e3f2fd
    style GCP fill:#fff3e0

需要100% Schema合规？ ──→ OpenAI strict模式
需要动态工具发现？ ──→ MCP
需要服务端执行？ ──→ Google Vertex（但注意安全边界）
两者都要？ ──→ 混合架构：MCP注册层 + OpenAI strict执行层

// 差：自由文本，模型需要"猜"格式
{
  "name": "search_flights",
  "parameters": {
    "date": {"type": "string", "description": "出发日期"},
    "class": {"type": "string", "description": "舱位等级"}
  }
}

// 好：枚举约束，消除歧义
{
  "name": "search_flights",
  "parameters": {
    "date": {"type": "string", "format": "date", "description": "出发日期，格式YYYY-MM-DD"},
    "class": {"type": "string", "enum": ["economy", "premium_economy", "business", "first"]}
  }
}

// 差：3层嵌套，模型容易漏传内层字段
{
  "name": "create_order",
  "parameters": {
    "shipping": {
      "address": {
        "street": {"type": "string"},
        "city": {"type": "string"},
        "zip": {"type": "string"}
      }
    }
  }
}

// 好：扁平化 + 语义化命名
{
  "name": "create_order",
  "parameters": {
    "shipping_street": {"type": "string"},
    "shipping_city": {"type": "string"},
    "shipping_zip": {"type": "string", "pattern": "^\\d{5}(-\\d{4})?$"}
  }
}

// 差：模糊描述
"description": "搜索数据库"

// 好：精确的行为契约
"description": "在用户数据库中搜索匹配条件的记录。返回最多50条结果。支持按name（模糊匹配）、email（精确匹配）、created_after（ISO 8601日期）过滤。不传filter参数时返回最近创建的10条。"

# OpenAI strict模式：100% JSON格式合规
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "查询北京到上海的航班"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "search_flights",
            "strict": True,  # CFG引擎强制
            "parameters": {
                "type": "object",
                "properties": {
                    "origin": {"type": "string", "enum": ["北京", "上海", "广州", "深圳"]},
                    "destination": {"type": "string", "enum": ["北京", "上海", "广州", "深圳"]},
                    "date": {"type": "string", "format": "date"}
                },
                "required": ["origin", "destination", "date"],
                "additionalProperties": False  # strict必须
            }
        }
    }]
)

flowchart LR
    A[LLM生成] --> B{CFG强制<br/>JSON格式}
    B -->|100%合规| C{Schema验证}
    C -->|通过| D[执行工具]
    C -->|失败| E{自动修复}
    E -->|重试1-2次| A
    E -->|无法修复| F[Fallback<br/>默认值/降级]
    B -->|非strict模式| G{JSON.parse}
    G -->|解析失败| E

    style D fill:#c8e6c9
    style F fill:#ffcdd2
    style E fill:#fff9c4

# OpenAI并行调用示例
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=messages,
    tools=tools,
    parallel_tool_calls=True  # 允许模型一次返回多个调用
)

# 并行执行所有返回的工具调用
import asyncio
results = await asyncio.gather(*[
    execute_tool(call.function.name, **json.loads(call.function.arguments))
    for call in response.choices[0].message.tool_calls
])

传统串行：Think→Call→Wait→Think→Call→Wait→Think→Call
                                         总时间 = 3×(think + call + wait)

Speculative：Think→Call1→[预测Call2并提前执行]→验证→Call3
                                         总时间 ≈ think + max(call1, call2) + call3

# 核心监控指标
metrics = {
    # 准确性指标
    "tool_selection_accuracy": 0.94,    # 选对工具的比例
    "parameter_compliance_rate": 0.91,  # 参数合规比例
    "end_to_end_success_rate": 0.87,    # 端到端成功（含重试后）

    # 延迟指标
    "tool_call_p50_ms": 320,            # 单次调用P50延迟
    "tool_call_p95_ms": 1200,           # 单次调用P95延迟
    "agent_loop_total_p95_ms": 4500,    # 完整Agent循环P95延迟

    # 成本指标
    "avg_tokens_per_tool_call": 185,    # 每次工具调用平均消耗token
    "tool_context_window_usage": 0.35,  # 工具Schema占上下文窗口比例

    # 告警阈值
    "alert_on": {
        "success_rate_drop_below": 0.90,    # 成功率跌破90%告警
        "p95_latency_above_ms": 3000,       # P95延迟超过3秒告警
        "context_usage_above": 0.60,        # 上下文占用超过60%告警
        "retry_rate_above": 0.25,           # 重试率超过25%告警
    }
}

flowchart TD
    A["Step 1: 基线测量<br/>建立工具调用成功率基线"] --> B["Step 2: Schema工程<br/>优化Top 10高频工具"]
    B --> C["Step 3: 强制层<br/>启用strict模式+后验证"]
    C --> D["Step 4: 并行化<br/>识别独立工具调用并行执行"]
    D --> E["Step 5: 观测闭环<br/>建立监控+告警+持续优化"]

    A -.->|"1-2周"| B
    B -.->|"2-3周"| C
    C -.->|"1-2周"| D
    D -.->|"持续"| E

    style A fill:#bbdefb
    style B fill:#c8e6c9
    style C fill:#fff9c4
    style D fill:#ffe0b2
    style E fill:#e1bee7