graph TD
    subgraph "工具调用六层适配栈"
        L1["L1 Schema定义层<br/>parameters / input_schema / function_declarations"]
        L2["L2 请求构造层<br/>tools / tool_choice / tool_config"]
        L3["L3 响应解析层<br/>tool_calls / content blocks / functionCall"]
        L4["L4 校验模式层<br/>strict / additionalProperties / 可选参数"]
        L5["L5 流式处理层<br/>delta.tool_calls / content_block_delta"]
        L6["L6 错误处理层<br/>错误码 / 重试语义 / 降级行为"]
    end

    L1 --> L2 --> L3 --> L4 --> L5 --> L6

    style L1 fill:#ff6b6b,color:#fff
    style L2 fill:#ffa502,color:#fff
    style L3 fill:#2ed573,color:#fff
    style L4 fill:#1e90ff,color:#fff
    style L5 fill:#a855f7,color:#fff
    style L6 fill:#636e72,color:#fff

tools = [{
    "type": "function",
    "function": {
        "name": "search_flights",
        "description": "Search for available flights",
        "parameters": {          # 字段名: parameters
            "type": "object",
            "properties": {
                "origin": {"type": "string", "description": "Departure city"},
                "destination": {"type": "string", "description": "Arrival city"},
                "date": {"type": "string", "format": "date"}
            },
            "required": ["origin", "destination"],
            "additionalProperties": False  # strict模式必须
        },
        "strict": True  # OpenAI特有：严格模式开关
    }
}]

tools = [{
    "name": "search_flights",
    "description": "Search for available flights",
    "input_schema": {          # 字段名: input_schema
        "type": "object",
        "properties": {
            "origin": {"type": "string", "description": "Departure city"},
            "destination": {"type": "string", "description": "Arrival city"},
            "date": {"type": "string", "format": "date"}
        },
        "required": ["origin", "destination"]
        # 无 additionalProperties 要求
        # 无 strict 开关
    }
}]

tools = [{
    "function_declarations": [{   # 外层包裹: function_declarations
        "name": "search_flights",
        "description": "Search for available flights",
        "parameters": {          # 字段名与OpenAI相同，但外层结构不同
            "type": "object",
            "properties": {
                "origin": {"type": "string", "description": "Departure city"},
                "destination": {"type": "string", "description": "Arrival city"},
                "date": {"type": "string", "format": "date"}
            },
            "required": ["origin", "destination"]
        }
    }]
}]

# 强制调用某个工具
tool_choice = {"type": "function", "function": {"name": "search_flights"}}

# 禁止调用任何工具
tool_choice = "none"

# 自动决定（默认）
tool_choice = "auto"

# 强制调用某个工具
tool_choice = {"type": "tool", "name": "search_flights"}

# 必须调用某个工具（但不指定哪个）
tool_choice = {"type": "any"}

# 自动决定
tool_choice = {"type": "auto"}

tool_config = {
    "function_calling_config": {
        "mode": "ANY",  # AUTO / ANY / NONE
        "allowed_function_names": ["search_flights"]  # 限定范围
    }
}

{
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "search_flights",
      "arguments": "{\"origin\":\"SFO\",\"destination\":\"JFK\"}"  
      // ⚠️ 字符串！需要json.loads()解析
    }
  }]
}

{
  "content": [{
    "type": "tool_use",
    "id": "toolu_abc123",
    "name": "search_flights",
    "input": {"origin": "SFO", "destination": "JFK"}  
    // ✅ 直接可用的dict
  }]
}

{
  "parts": [{
    "functionCall": {
      "name": "search_flights",
      "args": {"origin": "SFO", "destination": "JFK"}  
      // ✅ 直接可用的dict
    }
  }]
}

# OpenAI strict模式的7个前提条件
{
    "strict": True,
    "parameters": {
        "type": "object",
        "properties": {...},
        "required": [...],            # 必须：所有字段都列在required中，或全部不列
        "additionalProperties": False, # 必须：显式禁止额外属性
    }
}

# 一个含optional参数的工具定义
properties = {
    "query": {"type": "string"},
    "limit": {"type": "integer", "description": "Optional max results"}  
}
required = ["query"]  # limit是optional的

# OpenAI流式工具调用需要手动合并delta
tool_calls_accumulator = {}

for chunk in response:
    delta = chunk.choices[0].delta
    if delta.tool_calls:
        for tc_delta in delta.tool_calls:
            idx = tc_delta.index
            if idx not in tool_calls_accumulator:
                tool_calls_accumulator[idx] = {
                    "id": tc_delta.id,
                    "function": {"name": "", "arguments": ""}
                }
            # 增量追加arguments字符串
            if tc_delta.function:
                if tc_delta.function.name:
                    tool_calls_accumulator[idx]["function"]["name"] += tc_delta.function.name
                if tc_delta.function.arguments:
                    tool_calls_accumulator[idx]["function"]["arguments"] += tc_delta.function.arguments

# Anthropic用content_block_start/delta/stop三段式
current_tool = None

for event in client.messages.stream(...):
    if event.type == "content_block_start":
        if event.content_block.type == "tool_use":
            current_tool = {
                "id": event.content_block.id,
                "name": event.content_block.name,
                "input": ""
            }
    elif event.type == "content_block_delta":
        if current_tool:
            # input_json是增量JSON片段
            current_tool["input"] += event.delta.partial_json
    elif event.type == "content_block_stop":
        if current_tool:
            current_tool["input"] = json.loads(current_tool["input"])
            yield current_tool
            current_tool = None

messages.append({
    "role": "tool",
    "tool_call_id": "call_abc123",  # 必须匹配tool_calls的ID
    "content": "Error: API rate limit exceeded"
})

messages.append({
    "role": "user",
    "content": [{
        "type": "tool_result",
        "tool_use_id": "toolu_abc123",  # 必须匹配tool_use的ID
        "is_error": True,               # 显式标记为错误
        "content": "Error: API rate limit exceeded"
    }]
})

contents.append({
    "role": "function",
    "parts": [{
        "functionResponse": {
            "name": "search_flights",
            "response": {"error": "API rate limit exceeded"}
        }
    }]
})

graph LR
    subgraph "开发者代码"
        A["工具定义<br/>(单一Schema)"]
    end

    subgraph "适配层方案"
        B1["LiteLLM<br/>代理层翻译"]
        B2["MCP<br/>协议层统一"]
        B3["PipeLLM<br/>自动协议转换"]
        B4["llm-rosetta<br/>双向翻译层"]
        B5["手写适配器<br/>最大控制"]
    end

    subgraph "Provider API"
        C1["OpenAI"]
        C2["Anthropic"]
        C3["Google"]
    end

    A --> B1 --> C1
    B1 --> C2
    B1 --> C3

    A --> B2 --> C1
    B2 --> C2
    B2 --> C3

    A --> B3 --> C1
    B3 --> C2
    B3 --> C3

    A --> B4 --> C1
    B4 --> C2
    B4 --> C3

    A --> B5 --> C1
    B5 --> C2
    B5 --> C3

    style B1 fill:#2ed573,color:#fff
    style B2 fill:#1e90ff,color:#fff
    style B3 fill:#a855f7,color:#fff
    style B4 fill:#ffa502,color:#fff
    style B5 fill:#ff6b6b,color:#fff

import litellm

# 用OpenAI格式定义，LiteLLM自动翻译
response = litellm.completion(
    model="anthropic/claude-sonnet-4-6-20250514",
    messages=[{"role": "user", "content": "Find flights from SFO to JFK"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "search_flights",
            "parameters": {...}  # OpenAI格式，LiteLLM自动转为input_schema
        }
    }]
)

graph TB
    subgraph "Agent核心逻辑"
        CORE["工具注册表<br/>统一Schema定义"]
        PLAN["规划引擎<br/>决定调用哪些工具"]
        EXEC["执行引擎<br/>统一工具执行接口"]
    end

    subgraph "Provider适配插件"
        P1["OpenAI Adapter<br/>strict/arguments/string"]
        P2["Anthropic Adapter<br/>input_schema/object"]
        P3["Google Adapter<br/>function_declarations/object"]
    end

    subgraph "统一接口层"
        U1["ToolDefinition<br/>统一Schema → Provider格式"]
        U2["ToolResponse<br/>Provider格式 → 统一Response"]
        U3["ToolError<br/>Provider错误 → 统一ErrorResult"]
    end

    CORE --> U1
    PLAN --> U1
    EXEC --> U2

    U1 --> P1
    U1 --> P2
    U1 --> P3

    P1 --> U2
    P2 --> U2
    P3 --> U2

    style CORE fill:#1e90ff,color:#fff
    style U1 fill:#2ed573,color:#fff
    style U2 fill:#2ed573,color:#fff
    style U3 fill:#2ed573,color:#fff

from pydantic import BaseModel
from enum import Enum

class ToolCallResult(BaseModel):
    call_id: str
    tool_name: str
    arguments: dict  # 统一为dict，不再有string/object分裂
    raw_response: Any  # 保留原始响应用于调试

class ToolErrorType(Enum):
    RATE_LIMIT = "rate_limit"
    SCHEMA_VIOLATION = "schema_violation"
    TIMEOUT = "timeout"
    PROVIDER_ERROR = "provider_error"

class ToolErrorResult(BaseModel):
    call_id: str | None
    tool_name: str | None
    error_type: ToolErrorType
    message: str
    retryable: bool
    raw_error: Any