工具用量详情

实时服务端工具调用

流式处理智能体请求时，可以实时观察模型做出的每一次工具调用决策；这些决策可通过 tool_calls 属性（位于 chunk 对象上）获取：

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

注意：这里只显示工具调用本身，API 响应不会返回服务端工具调用的输出。智能体会在内部使用这些输出生成最终响应。

服务端工具调用与工具用量

API 为服务端工具执行提供两个相互关联但含义不同的指标：

tool_calls - 所有尝试的调用

response.tool_calls

返回智能体过程中所有尝试过的 工具调用列表。每个条目包含：

• id：工具调用的唯一标识符

• function.name：被调用的具体服务端工具名称

• function.arguments：传给服务端工具的参数

其中包括每一次工具调用尝试，即使部分尝试失败。

server_side_tool_usage - 成功调用次数

response.server_side_tool_usage

返回成功执行的工具及其调用次数映射。它只统计返回有效响应的工具调用，并决定你的费用（对于按调用计费的工具）；X Search 则按下方的条目数计费。

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

X Search 条目数

自 2026 年 9 月 21 日起，X Search 按获取的帖子和用户资料数量计费，而非按调用次数。Responses API 将这些数量报告为 usage.server_side_tool_usage_details.x_posts_fetched 和 x_users_fetched。各字段的统计范围见X Search 用量计数。

工具调用函数名与用量类别

在 xAI SDK 聊天响应中，tool_calls 中的函数名表示被调用工具的精确名称，而 server_side_tool_usage 中的条目提供与原始传入 tools 数组中的工具对应的高层分类。在 Responses API 中，Web Search 活动则表示为 web_search_call 输出项。

工具调用与用量不一致的情况

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

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

• 参数无效：工具调用的参数格式错误，无法处理

• 网络或服务问题：工具执行管道中的临时故障

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

计费说明：只有成功的工具执行（server_side_tool_usage）才会计费。失败尝试不收费。X Search 按获取的帖子和用户资料数量计费，而非按调用次数；请参阅X Search 条目数。

理解 token 用量

与标准聊天补全相比，智能体请求具有独特的 token 用量模式：

completion_tokens

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

prompt_tokens

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

虽然这可能导致 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.7",
    tools=[
        web_search(),
        x_search(),
    ],
    max_turns=3,  # Limit to 3 assistant/tool-call turns
)

chat.append(user("What is the latest news from SpaceXSI?"))
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）：