工具
工具使用详情
本页涵盖工具调用的技术细节，包括如何跟踪、计费，以及如何在代理请求中理解令牌使用情况。
实时服务器端工具调用
在流式代理请求中，您可以通过 chunk 对象上的 tool_calls 属性实时观察模型做出的每个工具调用决策：
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返回成功执行的工具及其调用次数的映射。这仅表示返回有意义响应的工具调用，并决定您的计费。
{'SERVER_SIDE_TOOL_X_SEARCH': 3, 'SERVER_SIDE_TOOL_WEB_SEARCH': 2}工具调用函数名与使用类别
在 xAI SDK 聊天响应中，tool_calls 中的函数名表示所调用工具的精确名称，而 server_side_tool_usage 中的条目提供高级分类，与 tools 数组中传递的原始工具保持一致。在 Responses API 中，网页搜索活动表示为 web_search_call 输出项。
| 使用类别 | 函数名 |
|---|---|
SERVER_SIDE_TOOL_WEB_SEARCH | web_search, web_search_with_snippets, browse_page, open_page, open_page_with_find |
SERVER_SIDE_TOOL_IMAGE_SEARCH | search_images |
SERVER_SIDE_TOOL_X_SEARCH | x_user_search, x_keyword_search, x_semantic_search, x_thread_fetch |
SERVER_SIDE_TOOL_CODE_EXECUTION | code_execution |
SERVER_SIDE_TOOL_VIEW_X_VIDEO | view_x_video |
SERVER_SIDE_TOOL_VIEW_IMAGE | view_image |
SERVER_SIDE_TOOL_COLLECTIONS_SEARCH | collections_search |
SERVER_SIDE_TOOL_MCP | 如果提供了 server_label，则为 {server_label}.{tool_name}，否则为 {tool_name} |
工具调用与使用情况何时不同
在大多数情况下，tool_calls 和 server_side_tool_usage 会显示相同的工具。但是，当以下情况发生时，它们可能不同：
- 失败的工具执行：模型尝试浏览不存在的网页、获取已删除的 X 帖子，或遇到其他执行错误
- 无效参数：参数格式错误而无法处理的工具调用
- 网络或服务问题：工具执行管道中的临时故障
代理系统优雅地处理这些故障，在需要时更新其轨迹并继续使用替代方法。
计费说明：仅对成功的工具执行（server_side_tool_usage）计费。失败的尝试不收费。
理解令牌使用情况
代理请求与标准聊天完成相比具有独特的令牌使用模式：
completion_tokens
仅表示模型的最终文本输出。这通常比您预期的要小得多，因为代理在内部执行所有中间推理和工具编排。
prompt_tokens
表示代理过程中所有推理请求的累积输入令牌。每个请求包含到该点为止的完整对话历史，随着代理的推进而增长。
虽然这可能导致更高的 prompt_tokens 计数，但代理请求从提示缓存中显著受益。提示的大部分内容在步骤之间保持不变，从而实现高效缓存。
reasoning_tokens
表示模型内部推理过程使用的令牌。这包括规划工具调用、分析结果和制定响应，但不包括最终输出令牌。
cached_prompt_text_tokens
表示从缓存而非重新计算的提示令牌数量。较高的值表示更好的缓存利用率和更低成本。
prompt_image_tokens
表示代理处理的视觉内容的令牌。这些令牌与文本令牌分开计数。如果没有处理图像或视频，此值将为零。
限制工具调用轮次
max_turns 参数允许您控制在单个请求中代理可以执行的最大助手/工具调用轮次数。
理解轮次与工具调用
重要：max_turns 不直接限制单个工具调用的数量。相反，它限制了代理循环中的助手轮次数。在单个轮次中，模型可能并行调用多个工具。
"轮次"代表代理推理循环的一次迭代：
- 模型分析当前上下文
- 模型决定调用一个或多个工具（可能是并行调用）
- 工具执行并返回结果
- 模型处理结果
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 | 权衡 |
|---|---|---|
| 快速查找 | 1-2 | 最快响应，可能错过更深入的见解 |
| 平衡研究 | 3-5 | 速度和全面性的良好平衡 |
| 深入研究 | 10+ 或未设置 | 最全面，延迟更长，成本更高 |
默认行为
如果未指定 max_turns，服务器将应用全局默认上限。当代理达到限制时，它将停止进行额外的工具调用，并根据已收集的信息生成最终响应。
识别工具调用类型
要确定返回的工具调用是需要本地执行的客户端工具：
使用 xAI SDK
使用 get_tool_call_type 函数：
from xai_sdk.tools import get_tool_call_type
for tool_call in response.tool_calls:
print(get_tool_call_type(tool_call))| 工具调用类型 | 描述 |
|---|---|
"client_side_tool" | 客户端工具调用 - 需要本地执行 |
"web_search_tool" | 网页搜索工具 - 由 xAI 服务器处理 |
"x_search_tool" | X 搜索工具 - 由 xAI 服务器处理 |
"code_execution_tool" | 代码执行工具 - 由 xAI 服务器处理 |
"collections_search_tool" | 集合搜索工具 - 由 xAI 服务器处理 |
"mcp_tool" | MCP 工具 - 由 xAI 服务器处理 |
使用 Responses API
检查输出条目的 type 字段（response.output[].type）：
| 类型 | 描述 |
|---|---|
"function_call" | 客户端工具 - 需要本地执行 |
"web_search_call" | 网页搜索工具 - 由 xAI 服务器处理 |
"x_search_call" | X 搜索工具 - 由 xAI 服务器处理 |
"code_interpreter_call" | 代码执行工具 - 由 xAI 服务器处理 |
"file_search_call" | 集合搜索工具 - 由 xAI 服务器处理 |
"mcp_call" | MCP 工具 - 由 xAI 服务器处理 |