# GPT-5.2 Structured Output 强制模式示例
from openai import OpenAI
client = OpenAI()

tools = [{
    "type": "function",
    "function": {
        "name": "query_customer_orders",
        "description": "查询客户订单历史",
        "strict": True,  # GPT-5.2关键参数：强制严格模式
        "parameters": {
            "type": "object",
            "properties": {
                "customer_id": {
                    "type": "string",
                    "pattern": "^CUS-[A-Z0-9]{8}$"  # 正则约束
                },
                "date_range": {
                    "type": "object",
                    "properties": {
                        "start": {"type": "string", "format": "date"},
                        "end": {"type": "string", "format": "date"}
                    },
                    "required": ["start", "end"]
                }
            },
            "required": ["customer_id"]
        }
    }
}]

response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "查CUS-AB12CD34客户最近三个月的订单"}],
    tools=tools,
    tool_choice="auto"
)
# strict=True确保输出100%匹配Schema，不合规直接拒绝而非"猜"

# Gemini 3.1 Pro 跨MCP服务器工具协调示例
import google.generativeai as genai

# 同时声明来自不同MCP服务器的工具
tools = [
    # MCP Server 1: GitHub
    {"function_declarations": [{
        "name": "create_pull_request",
        "description": "在指定仓库创建Pull Request",
        "parameters": {
            "type": "OBJECT",
            "properties": {
                "repo": {"type": "STRING"},
                "title": {"type": "STRING"},
                "body": {"type": "STRING"},
                "head_branch": {"type": "STRING"},
                "base_branch": {"type": "STRING"}
            },
            "required": ["repo", "title", "head_branch", "base_branch"]
        }
    }]},
    # MCP Server 2: Slack
    {"function_declarations": [{
        "name": "send_channel_message",
        "description": "向Slack频道发送消息",
        "parameters": {
            "type": "OBJECT",
            "properties": {
                "channel": {"type": "STRING"},
                "text": {"type": "STRING"}
            },
            "required": ["channel", "text"]
        }
    }]},
    # MCP Server 3: PostgreSQL
    {"function_declarations": [{
        "name": "execute_sql_query",
        "description": "执行SQL查询并返回结果",
        "parameters": {
            "type": "OBJECT",
            "properties": {
                "query": {"type": "STRING"},
                "database": {"type": "STRING"}
            },
            "required": ["query"]
        }
    }]}
]

# Gemini在内部通过Tool Grounding Layer统一编码这些异构工具
model = genai.GenerativeModel('gemini-3.1-pro', tools=tools)
response = model.generate_content(
    "创建一个PR修复auth模块的bug，然后通知#eng频道，并查询最近7天的相关错误日志"
)
# Gemini能够正确编排三步工具链：PR → Slack通知 → SQL查询

# Claude Opus 4.6 工具自纠错示例（Anthropic SDK）
import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "execute_command",
    "description": "在终端执行shell命令",
    "input_schema": {
        "type": "object",
        "properties": {
            "command": {"type": "string"},
            "timeout": {"type": "integer", "default": 30}
        },
        "required": ["command"]
    }
}]

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=tools,
    messages=[{
        "role": "user",
        "content": "部署前端应用到生产环境"
    }]
)

# Claude的典型行为模式：
# 1. 调用 execute_command("npm run build") → 失败（缺少依赖）
# 2. 自纠错：调用 execute_command("npm install && npm run build") → 成功
# 3. 调用 execute_command("npm run deploy") → 部署成功
# 4. 调用 execute_command("curl -s https://app.example.com/health") → 验证部署
# 无需外部重试逻辑，模型内部完成错误恢复

# 生产级工具调用验证模式
import jsonschema
from tenacity import retry, stop_after_attempt, wait_exponential

class ToolCallValidator:
    def __init__(self, tool_registry):
        self.registry = tool_registry  # 工具Schema注册表

    def validate_before_execution(self, tool_name, arguments):
        """第一层：Schema验证——拦截模型输出错误"""
        schema = self.registry.get_schema(tool_name)
        jsonschema.validate(arguments, schema)  # 不合规直接抛异常

    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
    def execute_with_retry(self, tool_name, arguments):
        """第二层：执行重试——应对API瞬时故障"""
        result = self.registry.execute(tool_name, arguments)
        if result.status_code >= 500:
            raise TransientError(f"Server error: {result.status_code}")
        return result

    def validate_after_execution(self, result, expectations):
        """第三层：结果验证——捕获语义级错误"""
        if expectations.get("must_contain"):
            for key in expectations["must_contain"]:
                if key not in result.data:
                    raise SemanticError(f"Expected key '{key}' missing")

graph TB
    subgraph "2024: 单次函数调用"
        A1[用户请求] --> B1[LLM推理]
        B1 --> C1[生成函数调用]
        C1 --> D1[执行并返回]
    end

    subgraph "2025: 多工具编排"
        A2[用户请求] --> B2[Planner]
        B2 --> C2[工具选择]
        C2 --> D2[并行执行]
        D2 --> E2[结果聚合]
        E2 --> F2[下一步决策]
        F2 --> C2
    end

    subgraph "2026: Agentic工具生态"
        A3[用户请求] --> B3[Agent核心循环]
        B3 --> C3[MCP工具发现]
        C3 --> D3[Schema协商]
        D3 --> E3[工具调用+验证]
        E3 --> F3{成功?}
        F3 -->|是| G3[结果注入上下文]
        F3 -->|否| H3[自纠错+重试]
        H3 --> D3
        G3 --> I3{任务完成?}
        I3 -->|否| B3
        I3 -->|是| J3[最终响应]
    end

    style A3 fill:#e1f5fe
    style B3 fill:#fff3e0
    style C3 fill:#f3e5f5
    style J3 fill:#e8f5e9

graph TD
    START[选择工具调用模型] --> Q1{工具数量?}
    Q1 -->|<10个| Q2{任务步数?}
    Q1 -->|10-50个| Q3{需要跨系统?}
    Q1 -->|>50个| MCP_GEMINI[Gemini 3.1 Pro + MCP协议栈]

    Q2 -->|<5步| GPT_FLASH[GPT-5.2 或 Gemini 3.5 Flash]
    Q2 -->|>5步| Q4{需要自纠错?}

    Q4 -->|是| CLAUDE_OPUS[Claude Opus 4.6]
    Q4 -->|否| GPT_52[GPT-5.2]

    Q3 -->|是| GEMINI_PRO[Gemini 3.1 Pro + MCP]
    Q3 -->|否| Q5{精度vs速度?}

    Q5 -->|精度优先| GPT_52_2[GPT-5.2]
    Q5 -->|速度优先| GEMINI_FLASH[Gemini 3.5 Flash]

    style MCP_GEMINI fill:#e8f5e9
    style CLAUDE_OPUS fill:#fff3e0
    style GPT_52 fill:#e3f2fd
    style GPT_52_2 fill:#e3f2fd
    style GEMINI_PRO fill:#fce4ec
    style GEMINI_FLASH fill:#fce4ec
    style GPT_FLASH fill:#e3f2fd