# 一个多余参数就能毁掉 Claude 演示，先学会原生 API

> 在 Claude 和 OpenAI 上手写工具调用循环，再对比 Gemini，学会看懂框架掩盖的底层故障。

原文: https://fdetimes.net/zh/guides/claude-openai-api-tool-use-loop/

一个参数就足以毁掉一场演示。在较新的 Claude 模型上，只要把 `temperature`、`top_p` 或 `top_k` 设成非默认值，API 就会返回 400 错误。从 4.6 系列开始，预填充（prefill）也会被拒绝，所以从旧博客里复制来的代码，可能当着客户的面直接崩掉。

框架会把这些细节藏起来，但藏不了一辈子。作为前线部署工程师（FDE），你会发现客户系统往往坏在最底层：header 写错、id 对不上、某一轮对话丢了。要学会读懂这类故障，最快的办法是至少亲手调用一次原生 API。

本指南围绕一个小脚本展开，脚本里只有一个工具 `get_order_status(order_id)`，它通过模拟函数查询订单状态。你会在 Claude 和 OpenAI 上走完请求、流式输出和工具调用的完整流程，再对比 Gemini 如何处理同样的问题。你需要准备 Python、写入环境变量的 API key，以及 `anthropic` 和 `openai` 两个 SDK。

为便于阅读，下面的代码做了精简，没有错误处理和重试。模型名放在 `MODEL` 和 `OA_MODEL` 两个变量里，请按各家文档填入当前的模型名。

## 第 1 步：为什么从 curl 开始？

在让 SDK 封装请求之前，你需要先看清原始请求。Claude Messages API 接收 `POST /v1/messages`，用 `x-api-key` header 认证，还需要一个 `anthropic-version` header。在 Anthropic 的示例中，`max_tokens` 和 `messages` 数组是两个必填字段。

```bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "'"$CLAUDE_MODEL"'", "max_tokens": 512,
       "messages": [{"role": "user", "content": "你好"}]}'
```

**检查：**你应该收到一段包含回复的 JSON。接着发送第二轮，只带上新问题。模型不会记得第一轮的任何内容，因为 Messages API 是无状态的：每一轮都必须重发完整的对话历史。

所以，当客户抱怨模型“忘了”上一轮时，首先要查的就是这里。

## 第 2 步：流式输出应当逐步显示文本

用户盯着空白屏幕等上十秒，就会以为系统卡死了。在 Claude 上，设置 `"stream": true`，即可通过服务器发送事件（SSE）分段接收响应。Python SDK 自带 `text_stream` 辅助方法，不必自己解析事件。

```python
import anthropic
client = anthropic.Anthropic()
history = [{"role": "user", "content": "用 3 句话解释 SSE"}]

with client.messages.stream(model=MODEL, max_tokens=512,
                            messages=history) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

**检查：**文本应当在终端里逐步出现。如果整段文字一次性出现，就要排查你的机器和 API 之间是否有代理或网关先缓冲了响应再转发。在客户的内网环境里，这个问题值得尽早提出。

## 第 3 步：模型提出调用，你的代码执行函数

这是本指南最重要的概念。当 Claude 想使用客户端工具时，它会返回 `stop_reason: "tool_use"`，并附带一个或多个 `tool_use` 块。你的代码执行函数，再把结果放进 `tool_result` 块发回。服务端工具则不同，它们运行在 Anthropic 的基础设施上。

先写一个返回字符串的模拟函数，声明工具，再写一个调用 API 的公共函数：

```python
def get_order_status(order_id): return f"订单 {order_id}：派送中"  # 模拟数据

tools = [{"name": "get_order_status",
          "description": "根据订单 ID 查询订单状态",
          "input_schema": {"type": "object",
              "properties": {"order_id": {"type": "string"}},
              "required": ["order_id"]}}]

def ask():
    return client.messages.create(model=MODEL, max_tokens=512,
                                  tools=tools, messages=history)
```

然后把问题放进 `history`，编写循环，并限制轮数，防止无限循环：

```python
history = [{"role": "user", "content": "订单 A123 现在在哪？"}]
resp = ask()
for _ in range(5):
    if resp.stop_reason != "tool_use":
        break
    history.append({"role": "assistant", "content": resp.content})
    results = [{"type": "tool_result", "tool_use_id": b.id,
                "content": get_order_status(**b.input)}
               for b in resp.content if b.type == "tool_use"]
    history.append({"role": "user", "content": results})
    resp = ask()
```

**检查：**在 `get_order_status` 里加一行日志。如果日志出现了，且最终回答包含函数返回的“派送中”字样，说明循环可以正常工作。

还要记住，工具并不免费：API 会悄悄插入一段隐藏的系统提示词来启用工具调用，`tools` 参数以及 `tool_use` 和 `tool_result` 块都会计入 token。

## 第 4 步：OpenAI Responses 换了名字，逻辑不变

在 Responses API 上，循环是一样的，只是名字变了。函数调用位于 `output` 数组中，是一个 `type` 为 `function_call` 的条目，带有 `call_id`。你用同一个 `call_id`，以 `function_call_output` 条目返回结果。

按 OpenAI 的格式声明工具，复用第 3 步的 schema 和模拟函数：

```python
import json
from openai import OpenAI
oa = OpenAI()
oa_tools = [{"type": "function", "name": "get_order_status",
             "description": "根据订单 ID 查询订单状态",
             "parameters": tools[0]["input_schema"]}]
inputs = [{"role": "user", "content": "订单 A123 现在在哪？"}]
```

然后执行一轮函数调用，并把结果发回：

```python
resp = oa.responses.create(model=OA_MODEL, input=inputs, tools=oa_tools)
for item in resp.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        inputs.append(item)
        inputs.append({"type": "function_call_output",
                       "call_id": item.call_id,
                       "output": get_order_status(**args)})
resp = oa.responses.create(model=OA_MODEL, input=inputs, tools=oa_tools)
```

注意，这段代码只处理一轮函数调用，不同于第 3 步中带上限的循环。如果模型收到结果后还会提出新的调用，就用类似的 `for` 循环包起来，直到 `output` 中不再出现 `function_call` 条目为止。

Responses API 同样用 `stream=True` 开启流式输出，但返回的是一系列语义事件，每个事件都有自己的类型。在编写任何处理逻辑之前，先打印每个 `event.type`，看看事件流长什么样：

```python
for event in oa.responses.create(model=OA_MODEL, input=inputs,
                                 tools=oa_tools, stream=True):
    print(event.type)
```

**检查：**你会看到一串事件，每类事件都有不同的名字。找出携带新增文本的那个事件，并对照文档确认它的名字，不要靠猜。

## 第 5 步：Gemini 正在更换 API，别照抄旧代码

在 Gemini 上，陷阱在于选哪个 API。当前文档建议新项目使用 Interactions API，并把 `generateContent` 列为旧版接口，因此网上那些使用 `generateContent` 的教程可能已经过时。通过 REST 调用时，key 放在 `x-goog-api-key` header 中。

```bash
# 精简骨架：endpoint 和 body 请以 Interactions API 文档页为准
curl "$GEMINI_ENDPOINT" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "content-type: application/json" \
  -d @request.json
```

本指南没有给出现成的 Gemini 工具调用循环，因为 Interactions API 的请求结构应当直接从文档获取。原则不变：Gemini 不会自己执行函数。它提出调用，由你的应用执行函数并发回结果。

默认情况下，模型生成完毕后才会返回响应，所以必须开启流式输出才能分段接收。

**拓展练习：**按照文档，在 Interactions API 上重建 `get_order_status` 循环，用同样的订单 A123 问题，再对比 Gemini 与另外两家在提出函数调用上的差异。

## 三个 API，一张对比表

| | Claude Messages | OpenAI Responses | Gemini |
|---|---|---|---|
| 流式输出 | `stream: true`，SSE | `stream=True`，语义事件 | 开启流式输出后分段接收 |
| 工具调用信号 | `stop_reason: "tool_use"` | `output` 中的 `function_call` 条目 | 模型提出函数调用 |
| 返回结果 | `tool_result` + `tool_use_id` | `function_call_output` + `call_id` | 应用发回结果 |
| 历史 | 客户端重发全部内容 | 可在服务端保存状态 | 取决于所选 API |

**要点:** 三家服务商都只是由模型提出调用，函数由你的代码执行。所以工具调用循环出问题时，首先该查的是你自己的代码。

## 真实项目中会遇到的错误

最常见的是过时的采样配置：如果客户的设置里还留着旧模型时代的 `temperature: 0.2`，较新的 Claude 模型就会返回 400。其次是缺少 id：`tool_result` 缺了 `tool_use_id`，或 `function_call_output` 缺了 `call_id`，模型就分不清某个结果属于哪次调用。还有一种是每次请求都塞进几十个工具，然后惊讶于 token 账单飙升。

还有一个架构决策需要向客户讲清楚。Anthropic 把 Messages API 定位为面向需要精细控制的手写 Agent 循环；OpenAI 则表示，Responses API 能在多轮之间保留推理内容，这是 Chat Completions 做不到的，并且托管工具在服务端运行。

Simon Willison 也指出，Responses 可以替你在服务端管理对话状态。

作为 FDE，比较稳妥的做法是在第一次会议上问客户两个问题：对话历史允许存放在哪里？工具由谁来执行？

一家希望所有日志都留在自己系统内的银行，更适合无状态模式；而一家需要快速上线的初创公司，可能更愿意把部分状态管理交给服务端。

## 把练习变成简历上的证据

简历上写一句“有 LLM 经验”，很难证明你理解框架之下的那一层，而当框架在客户现场出故障时，你要调试的恰恰是这一层。把这个脚本推到 GitHub 上，让 Claude 和 OpenAI 两个适配器共用一个 `call_tool` 接口，再附一份 README，记录你遇到的每个 400 错误以及修复方法。

在简历上具体写明：你在 Claude Messages 和 OpenAI Responses 上手写过工具调用循环；如果完成了拓展练习，再加上 Gemini Interactions API。

阅读岗位描述时，留意“integrate with multiple model providers”或“build agent loops”这类说法。这正是你刚做完的练习，而现在你可以用具体的字段来描述它，而不只是报出框架的名字。

**本周动手试试:**

- 用 curl 带上 x-api-key 和 anthropic-version header 调用 Claude，再故意不带历史发送第二轮，观察模型如何忘掉第一轮
- 写一个模拟的 get_order_status 工具，让它在 Claude 和 OpenAI Responses 上都能跑通，再用 stream=True 打印每个 event.type
- 在 GitHub 上推送一个小仓库，包含 Claude 和 OpenAI 适配器，以及一份列出所有报错和修复方法的 README，然后在简历中附上链接

## 信源

- [Using the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)

- [Streaming messages](https://platform.claude.com/docs/en/build-with-claude/streaming)

- [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)

- [Streaming API responses](https://developers.openai.com/api/docs/guides/streaming-responses)

- [Function calling](https://developers.openai.com/api/docs/guides/function-calling)

- [Why we built the Responses API](https://developers.openai.com/blog/responses-api/)

- [OpenAI API: Responses vs. Chat Completions](https://simonwillison.net/2025/Mar/11/responses-vs-chat-completions/)

- [Function calling with the Gemini API](https://ai.google.dev/gemini-api/docs/function-calling)

- [Gemini API | Google AI for Developers](https://ai.google.dev/gemini-api/docs)

- [Text generation | Gemini API | Google AI for Developers](https://ai.google.dev/gemini-api/docs/text-generation)
