Agent 工程师的 LLM API 对照手册

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "你是 SRE 助手。" },
    { "role": "user", "content": "查 api-gateway 近1小时 ERROR 日志" }
  ],
  "tools": [
    {
      // OpenAI Chat Completions：外层包一层 type:function
      "type": "function",
      "function": {
        "name": "query_logs",
        "description": "查询服务错误日志。用户想了解服务错误时使用。",
        // Chat Completions 字段名：parameters
        "parameters": {
          "type": "object",
          "properties": {
            "service": { "type": "string" },
            "duration_minutes": { "type": "integer" },
            "level": {
              "type": "string",
              "enum": ["ERROR", "WARN", "INFO"]
            }
          },
          "required": ["service", "level"],
          "additionalProperties": false
        }
      }
    }
  ],
  // 字符串形式
  "tool_choice": "auto"
}

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": "你是 SRE 助手。",
  "messages": [
    { "role": "user", "content": "查 api-gateway 近1小时 ERROR 日志" }
  ],
  "tools": [
    {
      // Anthropic：直接平铺，没有外层 type:function
      "name": "query_logs",
      "description": "查询服务错误日志。用户想了解服务错误时使用。",
      // Anthropic 字段名：input_schema（不是 parameters）
      "input_schema": {
        "type": "object",
        "properties": {
          "service": { "type": "string" },
          "duration_minutes": { "type": "integer" },
          "level": {
            "type": "string",
            "enum": ["ERROR", "WARN", "INFO"]
          }
        },
        "required": ["service", "level"]
      }
    }
  ],
  // 始终是对象形式
  "tool_choice": { "type": "auto" }
}

{
  "choices": [{
    "message": {
      "role": "assistant",
      // content=null 当有工具调用时
      "content": null,
      "tool_calls": [{
        "id": "call_xyz",
        "type": "function",
        "function": {
          "name": "query_logs",
          // arguments 是字符串，需 JSON.parse
          "arguments": "{\"service\":\"api-gateway\",\"level\":\"ERROR\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

{
  "stop_reason": "tool_use",
  // content 可同时含文字和工具调用
  "content": [
    {
      "type": "text",
      "text": "我来查一下日志。"
    },
    {
      "type": "tool_use",
      "id": "toulu_xyz",
      "name": "query_logs",
      // input 已是对象，直接用
      "input": {
        "service": "api-gateway",
        "level": "ERROR"
      }
    }
  ]
}

// 模型自己决定（默认）
"tool_choice": "auto"

// 禁止调工具，只输出文字
"tool_choice": "none"

// 必须调工具，模型自选哪个
"tool_choice": "required"

// 强制调指定工具
"tool_choice": {
  "type": "function",
  "function": { "name": "query_logs" }
}

// 模型自己决定（始终是对象）
"tool_choice": { "type": "auto" }

// 禁止调工具
"tool_choice": { "type": "none" }

// 必须调工具，模型自选哪个（对应 Chat Completions required）
"tool_choice": { "type": "any" }

// 强制调指定工具
"tool_choice": {
  "type": "tool",
  "name": "query_logs"
}

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "你是 SRE 诊断助手，输出结构化报告。" },
    { "role": "user", "content": "api-gateway CPU 95%，大量 502" }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "diagnosis_report",
      // strict:true 保证字段不多不少
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "severity": {
            "type": "string",
            "enum": ["P0","P1","P2","P3"]
          },
          "root_cause": { "type": "string" },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "action":   { "type": "string" },
                "priority": { "type": "integer" },
                "need_approval": { "type": "boolean" }
              },
              "required": ["action","priority","need_approval"],
              "additionalProperties": false
            }
          },
          "confidence": { "type": "number" }
        },
        "required": ["severity","root_cause","actions","confidence"],
        "additionalProperties": false
      }
    }
  }
}

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": "你是 SRE 诊断助手，输出结构化报告。",
  "messages": [
    { "role": "user", "content": "api-gateway CPU 95%，大量 502" }
  ],
  // 定义一个"输出工具"，实际上是结构化输出的载体
  "tools": [{
    "name": "emit_diagnosis",
    "description": "输出诊断报告。分析完成后必须调用此工具。",
    "input_schema": {
      "type": "object",
      "properties": {
        "severity": {
          "type": "string",
          "enum": ["P0","P1","P2","P3"]
        },
        "root_cause": { "type": "string" },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "action":       { "type": "string" },
              "priority":     { "type": "integer" },
              "need_approval": { "type": "boolean" }
            },
            "required": ["action","priority","need_approval"]
          }
        },
        "confidence": { "type": "number" }
      },
      "required": ["severity","root_cause","actions","confidence"]
    }
  }],
  // 强制调用，模型填的参数就是结构化结果
  "tool_choice": { "type": "tool", "name": "emit_diagnosis" }
}

{
  "choices": [{
    "message": {
      "role": "assistant",
      // content 是 JSON 字符串，需 JSON.parse
      "content": "{\"severity\":\"P0\",\"root_cause\":\"连接池耗尽\",\"actions\":[{\"action\":\"限流\",\"priority\":1,\"need_approval\":false}],\"confidence\":0.87}"
    },
    "finish_reason": "stop"
  }]
}

// 取结果
const report = JSON.parse(
  response.choices[0].message.content
)

{
  "stop_reason": "tool_use",
  "content": [{
    "type": "tool_use",
    "name": "emit_diagnosis",
    // input 已是对象，直接用，无需 JSON.parse
    "input": {
      "severity": "P0",
      "root_cause": "连接池耗尽",
      "actions": [{
        "action": "限流",
        "priority": 1,
        "need_approval": false
      }],
      "confidence": 0.87
    }
  }]
}

// 取结果
const toolBlock = response.content.find(b => b.type === "tool_use")
const report    = toolBlock.input  // 直接用

# content=null，tool_calls 出现
data: {"choices":[{"delta":{"role":"assistant","content":null},"finish_reason":null}]}

# 第一片：id + name + arguments 首片（空字符串）
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_xyz","type":"function","function":{"name":"query_logs","arguments":""}}]},"finish_reason":null}]}

# arguments 逐片推送（JSON 字符串被切开）
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\"ser"}}]},"finish_reason":null}]}

data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"vice\":"}}]},"finish_reason":null}]}

data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\"api-gateway\"}"}}]},"finish_reason":null}]}

# finish_reason 出现 → 此时 arguments 已全部到达
data: {"choices":[{"index":0,"delta":{},"finish_reason":"tool_calls"}]}

data: [DONE]

# content_block_start 声明这是 tool_use block
event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_xyz","name":"query_logs","input":{}}}

# input_json_delta 逐片推送参数
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"ser"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"vice\":\"api-gateway\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"}"}}

# content_block_stop → jsonBuf 拼完，可以 parse
event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use"}}

POST https://api.openai.com/v1/chat/completions
Authorization: Bearer $OPENAI_API_KEY
Content-Type: application/json

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "你是 SRE 助手。"
    },
    {
      "role": "user",
      "content": "CPU 飙到 95%"
    }
  ]
}

POST https://api.anthropic.com/v1/messages
x-api-key: $ANTHROPIC_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  // system 是顶层字段，不在 messages 里
  "system": "你是 SRE 助手。",
  "messages": [
    {
      "role": "user",
      "content": "CPU 飙到 95%"
    }
  ]
}

{
  "model": "gpt-4o",
  "messages": [...],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "query_logs",
        "description": "查询错误日志",
        // 字段名：parameters
        "parameters": {
          "type": "object",
          "properties": {
            "service": {
              "type": "string"
            },
            "level": {
              "type": "string",
              "enum": ["ERROR", "WARN"]
            }
          },
          "required": ["service"]
        }
      }
    }
  ],
  // tool_choice 可以是字符串
  "tool_choice": "auto"
}

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": "...",
  "messages": [...],
  "tools": [
    {
      // 没有外层 type:function 包裹
      "name": "query_logs",
      "description": "查询错误日志",
      // 字段名：input_schema（不是 parameters）
      "input_schema": {
        "type": "object",
        "properties": {
          "service": {
            "type": "string"
          },
          "level": {
            "type": "string",
            "enum": ["ERROR", "WARN"]
          }
        },
        "required": ["service"]
      }
    }
  ],
  // tool_choice 始终是对象
  "tool_choice": { "type": "auto" }
}

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "你是 SRE 助手。"
    },
    {
      "role": "user",
      "content": "CPU 飙到 95%"
    },
    // ① assistant 原始输出（content=null）
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_xyz789",
        "type": "function",
        "function": {
          "name": "query_logs",
          // arguments 是字符串！
          "arguments": "{\"service\":\"api-gw\"}"
        }
      }]
    },
    // ② tool result：专属 role="tool"
    {
      "role": "tool",
      "tool_call_id": "call_xyz789",
      "content": "{\"logs\":[...]}"
    }
  ]
}

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": "你是 SRE 助手。",
  "messages": [
    {
      "role": "user",
      "content": "CPU 飙到 95%"
    },
    // ① assistant：content 是数组，含文字+工具调用
    {
      "role": "assistant",
      "content": [
        { "type": "text",
          "text": "我查一下日志。" },
        { "type": "tool_use",
          "id": "toolu_xyz789",
          "name": "query_logs",
          // input 是对象，直接用
          "input": {
            "service": "api-gw"
          }
        }
      ]
    },
    // ② tool result：用 role="user"，不是 tool
    {
      "role": "user",
      "content": [{
        "type": "tool_result",
        "tool_use_id": "toolu_xyz789",
        "content": "{\"logs\":[...]}"
      }]
    }
  ]
}

{
  "id": "chatcmpl-abc",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "建议先限流..."
    },
    // Agent Loop 判断字段
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 45
  }
}

{
  "id": "msg_abc",
  // stop_reason 在顶层
  "stop_reason": "end_turn",
  "content": [{
    "type": "text",
    "text": "建议先限流..."
  }],
  "usage": {
    // 字段名不同
    "input_tokens": 120,
    "output_tokens": 45
  }
}

{
  "choices": [{
    "message": {
      "role": "assistant",
      // content=null 当有工具调用时
      "content": null,
      "tool_calls": [{
        "id": "call_xyz789",
        "type": "function",
        "function": {
          "name": "query_logs",
          // arguments 是字符串，需 JSON.parse
          "arguments": "{\"service\":\"api-gw\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

{
  "stop_reason": "tool_use",
  // content 可同时含文字和工具调用
  "content": [
    {
      "type": "text",
      "text": "我来查一下日志。"
    },
    {
      "type": "tool_use",
      "id": "toolu_xyz789",
      "name": "query_logs",
      // input 已是对象，直接用
      "input": {
        "service": "api-gw"
      }
    }
  ]
}