Tool 用量详情

实时 Server-side Tool Call

流式处理 Agent 请求时，可以实时观察模型做出的每一次 Tool Call 决策；这些决策可通过 tool_calls attribute（位于 chunk object）获取：

for tool_call in chunk.tool_calls:
    print(f"\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")

注意：这里只显示 Tool Call 调用，API Response 不会返回 Server-side Tool Call Output。Agent 会在内部使用这些 output 来生成最终响应。

Server-side Tool Call 与 Tool Usage

API 为 Server-side Tool 执行提供两个相互关联但含义不同的指标：

tool_calls - 所有尝试的 Call

response.tool_calls

返回 Agent 过程中所有尝试过的 Tool Call 列表。每个 entry 包含：

• id：Tool Call 的唯一标识符

• function.name：被调用的具体 Server-side Tool 名称

• function.arguments：传给 Server-side Tool 的参数

其中包括每一次 Tool Call 尝试，即使部分尝试失败。

server_side_tool_usage - 成功的 Call（计费）

response.server_side_tool_usage

返回成功执行的 Tool 及其调用次数 map。它只统计返回有效响应的 Tool Call，并决定你的费用。

{'SERVER_SIDE_TOOL_X_SEARCH': 3, 'SERVER_SIDE_TOOL_WEB_SEARCH': 2}

Tool Call Function Name 与 Usage Category

在 xAI SDK Chat Response 中，tool_calls 中的 function name 表示被调用 Tool 的精确名称，而 server_side_tool_usage 中的 entry 提供与原始传入 tools array 的 Tool 对应的高层分类。在 Responses API 中，Web Search 活动表示为 web_search_call output item。

Tool Call 与 Usage 不一致的情况

大多数情况下，tool_calls 和 server_side_tool_usage 会显示相同的 Tool。但在以下情况下，两者可能不同：

• Tool 执行失败：模型尝试访问不存在的网页、获取已删除的 X Post，或遇到其他执行错误

• 参数无效：Tool Call 的 argument 格式错误，无法处理

• 网络或服务问题：Tool 执行 pipeline 中的临时故障

Agent 系统会妥善处理这些故障，调整执行路径，并在需要时改用其他方案继续。

计费说明：只有成功的 Tool 执行（server_side_tool_usage）会计费，失败的尝试不会产生费用。

理解 Token 用量

与标准 Chat Completion 相比，Agent 请求具有独特的 token 用量模式：

completion_tokens

表示模型的最终文本输出。由于 Agent 会在内部完成所有中间推理和 Tool 编排，该数值通常比你预期的小得多。

prompt_tokens

表示 Agent 过程中累计的 input token，覆盖所有 inference request。每个请求都包含截至当时的完整对话历史，因此会随 Agent 推进而增长。

虽然这可能导致 prompt_tokens 数值较高，但 Agent 请求能显著受益于Prompt Caching。大部分 prompt 在各步骤之间保持不变，因此可以被高效缓存。

reasoning_tokens

表示模型内部推理过程使用的 token，包括规划 Tool Call、分析结果和组织响应，但不包括最终输出 token。

cached_prompt_text_tokens

表示有多少 prompt token 直接由 cache 提供，而非重新计算。数值越高，说明 cache 利用率越高、成本越低。

prompt_image_tokens

表示 Agent 处理的视觉内容 token。它们与 text token 分开计数；如果未处理图像或视频，该值为零。

限制 Tool Call 轮次

该 max_turns 参数用于控制 Agent 在单个请求中可执行的最大 Assistant/Tool Call 轮次。

理解 Turn 与 Tool Call

重要：max_turns并不直接限制单个 Tool Call 的数量。它限制的是 Agent Loop 中的 Assistant Turn 数量。在单个 Turn 中，模型可以并行调用多个 Tool。

一个“Turn”表示 Agent 推理循环的一次迭代：

1. 模型分析当前上下文

2. 模型决定调用一个或多个 Tool（可能并行调用）

3. Tool 执行并返回结果

4. 模型处理结果

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import web_search, x_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.5",
    tools=[
        web_search(),
        x_search(),
    ],
    max_turns=3,  # Limit to 3 assistant/tool-call turns
)

chat.append(user("What is the latest news from xAI?"))
response = chat.sample()
print(response.content)

何时使用 max_turns

默认行为

如果未指定 max_turns，Server 会应用全局默认上限。当 Agent 达到上限时，会停止发起新的 Tool Call，并根据已收集的信息生成最终响应。

识别 Tool Call 类型

要判断返回的 Tool Call 是否为需要本地执行的 Client-side Tool，请按以下方式操作：

使用 xAI SDK

使用 get_tool_call_type function：

from xai_sdk.tools import get_tool_call_type

for tool_call in response.tool_calls:
    print(get_tool_call_type(tool_call))

使用 Responses API

检查 output entry 的 type 字段（response.output[].type）：