Grok 4.6 API：从首次调用到会用工具的代理

如何在 Python 中配置 Grok 4.6 API？

开始前，您需要一个 SpaceXAI 的 API 密钥，并安装 xai-sdk。

从 console.x.ai 获取 API 密钥

要创建 Grok 4.6 API 密钥，我们前往 SpaceX AI 控制台的 API 密钥创建页面。接着，点击右上角的 Create API Key 按钮。

API 密钥创建表单很直观。我们给密钥取一个名字，便于识别其所属项目。我还建议始终为 API 密钥设置过期日期，以防密钥泄露时作为安全保障。

生成密钥后，我们将其复制并粘贴到与我们编写 Python 脚本的同一文件夹中名为 .env 的文件里。这样一来，就能在脚本中轻松加载密钥，而无需将其保存在代码文件中，避免我们在分享或上传代码到云端时不慎暴露密钥。

.env 文件应包含以下内容：

XAI_API_KEY=replace_with_the_api_key

安装 xai-sdk 并加载 SpaceXAI API 密钥

要使用 API 密钥连接 SpaceXAI，我们使用 xai-sdk 包。为避免不同项目的 Python 包相互冲突，最佳实践是为每个项目创建独立环境。我们将使用 Anaconda，通过以下命令创建：

conda create -yn grok-46 python=3.10
``` 
This creates an environment named grok-46 that we can activate using:
```bash
conda activate grok-46

激活后，我们就可以安装所需的包。目前先从以下开始：

• xai-sdk：SpaceXAI 官方包，用于向其 API 发起请求。

• python-dotenv：用于从 .env 文件中便捷加载 API 密钥的工具包。

使用以下命令进行安装：

pip install xai-sdk python-dotenv

下面演示如何在 Python 中加载 API 密钥并创建 SpaceXAI Client：

from dotenv import load_dotenv
from xai_sdk import Client

load_dotenv()

client = Client()

请注意，这段代码尚未发起请求。接下来我们将学习如何进行请求。

购买 SpaceXAI API 额度

要使用 Grok 4.6 API，我们还需要在其 API 平台购买额度。否则，API 请求将被拒绝。前往侧边栏底部的 Credits，点击 Add credits，然后添加您需要的金额。

通过 API 使用 Grok 4.6 的成本是多少？

对 Grok 4.6 的请求按 token 计费。基础价格为每百万输入 token 2 美元，每百万输出 token 6 美元。

需要注意的是，Grok 4.6 是一个推理模型。推理以自我对话的形式进行，也会消耗 token，并按输出 token 计费。稍后我们将学习如何控制模型在特定请求上的推理量。

缓存 token 便宜得多，每百万 token 仅需 0.5 美元。

正如我们将看到的，Grok 内置了三种工具，它们的计费独立于 token：网页搜索、X 搜索和代码执行。以上工具均按每 1,000 次调用 5.00 美元计价。

对于长上下文，需要注意的是，超过 200K 门槛的提示中所有 token 都按双倍费率计费。

如何完成您的第一次 Grok 4.6 API 调用？

我们在前面的代码基础上，使用 SpaceXAI 客户端向 Grok 4.6 发送请求。

要向 Grok 4.6 发送请求，我们用 client.chat.create() 初始化一个针对 grok-4.6 的会话，并用 chat.append(user()) 将提示添加到会话历史。

最后，调用 chat.sample() 会将会话发送给模型以生成响应，我们通过打印 response.content 显示结果。

from dotenv import load_dotenv
from xai_sdk import Client
from xai_sdk.chat import user

load_dotenv()

client = Client()

chat = client.chat.create(model="grok-4.6")
chat.append(user("Explain how the Transformer attention mechanism works using a simple analogy."))

response = chat.sample()
print(response.content)

以这种方式使用 Grok，我们会一次性获得完整响应，因此需要等 Grok 生成完整答案后才能收到内容。通过流式传输可以实现逐字回复。

响应流式传输

与其使用 chat.sample() 等待完整响应，我们可以使用 chat.stream() 实时接收模型输出。

# … Same code as before

chat.append(user("Explain how the Transformer attention mechanism works using a simple analogy."))

for response, chunk in chat.stream():
    print(chunk.content, end="", flush=True)

print()

该代码遍历数据流，逐步产生 chunk 对象，并在每段文本（chunk.content）到达时立即打印到控制台，带来逐 token 的流式体验。

执行这段代码时，我们会注意到模型开始产出 token 仍需一些时间。原因在于 Grok 4.6 是推理模型。默认情况下，在生成最终答案的第一个可见词之前，模型会经历一个内部的“思维链”推理阶段。

我们可以更新上述代码，同时显示模型的推理过程，如下所示：

# … Same code as before

chat.append(user("Explain how the Transformer attention mechanism works using a simple analogy."))

print("--- Reasoning ---")
is_first_content = True

for response, chunk in chat.stream():
    if chunk.reasoning_content:
        print(chunk.reasoning_content, end="", flush=True)
    if chunk.content:
        if is_first_content:
            print("\n\n--- Response ---")
            is_first_content = False
        print(chunk.content, end="", flush=True)

print()

Grok 4.6 在此流式过程中会输出两类 token：

• 模型的内部思维链 token
• 最终答案

该脚本通过检查 chunk.reasoning_content 区分两者，先流式展示 Grok 的逐步思考过程，然后在最终响应开始时打印 chunk.content。

如何在 Grok 4.6 中设置推理力度？

如上所示，与其他前沿 AI 模型一样，Grok 4.6 依赖隐藏的思维链。在输出最终答案的第一个词之前，它会生成数千个推理 token 来探索解法、复核逻辑并自我纠错。

reasoning_effort 参数允许我们控制模型在该推理过程上投入多少精力。由于我们也要为推理 token 付费，而不仅是最终答案，因此如果想降低成本，这是一个需要重点管理的参数。

Grok 3 mini 已经允许开发者调节 reasoning_effort，但Grok 4 取消了该控制。其推理始终开启且无法调节。SpaceXAI 在 Grok 4.x 系列（4.3 和 4.5）中重新引入了该控制，Grok 4.6 也支持，提供 low、medium、high（默认）和 xhigh。

要设置推理力度，我们在用 client.chat.create() 初始化会话时使用 reasoning_effort 参数。该值是一个字符串。默认值为 "high"。下面示例演示如何将其设为 "low"：

chat = client.chat.create(
    model="grok-4.6",
    reasoning_effort="low"
)

在相同提示下对比 low 与 high

我尝试了许多任务，分别使用 low 和 high 推理，例如构建一个小型游戏、创建脚本分析包含多种格式错误货币格式的工资数据、以及解逻辑谜题。

在这些情况下，模型在低或高推理下都能给出类似的解决方案。

要体现差异，我们需要一个在中途停止推理就会失败的任务。因此我选了一个有许多解的谜题。以下是我使用的提示：

Solve the following alphametic puzzle, in which each letter represents a unique digit from 0 to 9. The leading digits cannot be zero.

GROK + DATA = CAMP

Provide a list of all solutions. For each solution, show a single line with the final addition to prove it works.

在两种推理水平下，Grok 4.6 都找到了正确解。然而当设置为 low 时，其推理预算在完成任务前就耗尽了，因此返回了不完整的解。使用高推理时，Grok 4.6 找到了全部 264 个解。

对比来看，在 low 推理下，它使用了 16,422 个推理 token，而在 high 推理下使用了 56,455 个。

什么时候 xhigh 值回票价？

如果 high 设置已经能成功穷举复杂逻辑谜题和数据解析脚本，为什么还会有人为 xhigh 的巨量 token 消耗买单？

我认为对于 99% 的日常编程和数据科学任务，xhigh 都是大材小用，只会迅速烧光您的 API 预算。

不过，当您将模型从“编码助手”转为“自主代理”时，xhigh 就变得不可或缺。您实际上是在付费让模型更激进地审查自己的工作、走进死胡同、并在呈现最终输出前重写其逻辑。

我的建议是从 low 开始，只有当模型在某任务上系统性失败时再提升。确实，在某些情况下这意味着我们会为同一个问题多次付费，但大多数时候我们都能以更低的成本获得不错的解决方案。

如何向 Grok 4.6 API 发送图像？

Grok 4.6 是多模态模型，因此可以处理图像数据。

通过 URL 发送图像

向模型提供图像最简单的方式是使用 URL。我们可以将其作为用户消息的第二个参数提供：

from dotenv import load_dotenv
from xai_sdk import Client
from xai_sdk.chat import image, user

load_dotenv()
client = Client()

chat = client.chat.create(model="grok-4.6")

image_url = "https://images.pexels.com/photos/25810993/pexels-photo-25810993.jpeg"

chat.append(
    user(
        "Describe what you see in this image in detail.",
        image(image_url=image_url),
    )
)

for response, chunk in chat.stream():
    print(chunk.content, end="", flush=True)

print()

通过文件上传发送图像

很多时候我们希望使用本地图像而非 URL。可将图像加载为 base64 字符串实现。函数 encode_image() 可以帮助我们完成编码：

import base64
import mimetypes

def encode_image(image_path: str) -> str:
    mime_type, _ = mimetypes.guess_type(image_path)
    if not mime_type:
        mime_type = "image/jpeg"
    with open(image_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode("utf-8")
    return f"data:{mime_type};base64,{encoded_string}"

图像编码完成后，我们以相同方式提供给模型：

chat.append(
    user(
        "Describe what you see in this image in detail.",
        image(image_url=encode_image("image.png")),
    )
)

尽管支持图像输入，Grok 4.6 仅输出文本。若您想了解 SpaceXAI 的图像生成，推荐阅读我们的 Grok Imagine API 教程。

如何为 Grok 4.6 代理启用工具？

Grok 4.6 提供三种实用的服务端工具，并支持创建自定义工具。

调用服务端工具（网页搜索、X 搜索、代码执行）

Grok 4.6 内置三种服务端工具：

• 网页搜索：允许代理执行网页搜索以增强答案的依据。
• X 搜索：查询来自 X 平台的实时数据。
• 代码执行：在沙盒中执行代码以辅助回答问题。

这些工具运行在 SpaceXAI 的服务器上，每次工具调用独立于 token 计费。

要启用这些工具，我们需要导入并在用 client.chat.create() 实例化会话时传入：

from xai_sdk.tools import code_execution, web_search, x_search
chat = client.chat.create(
    model="grok-4.6",
    tools=[web_search(), x_search(), code_execution()],
)

在流式传输响应时，我们可以通过检查 chunk.tool_calls 标志来判断代理是否在使用工具。

下面是一段处理流式响应的代码片段，可向用户展示代理何时在调用工具：

for response, chunk in chat.stream():
    for tool_call in chunk.tool_calls:
        print(f"\n--> Agent is calling tool: {tool_call.function.name}\n", flush=True)
    if chunk.content:
        print(chunk.content, end="", flush=True)

包含服务端工具的完整示例脚本可在配套的 GitHub 仓库中找到。

实现自定义本地工具

在上述服务端工具之外，我们还可以为 Grok 4.6 代理配备自定义工具。下面看看如何实现允许代理读取和写入本地文件的工具。

实现自定义工具需要两部分：

1. 使用 SpaceXAI SDK 的官方 tool() 对象编写工具规范。

2. 工具的 Python 实现，即工具被调用时我们希望执行的代码。

一个工具规范包括：

• 要调用的 Python 函数的名称。
• 解释工具用途的描述。这非常关键，因为它决定代理何时会调用该工具。
• 函数的参数规范。

下面是一个可用于实现读取本地文件工具的函数：

def execute_read_file(file_path: str) -> str:
    print(f"\n🔒 [Permission Request] Grok wants to read local file: '{file_path}'")
    confirm = input("Allow access? [y/N]: ").strip().lower()
    if confirm not in ("y", "yes"):
        print(f"❌ Denied access to '{file_path}'")
        return f"Permission denied by user. Access to file '{file_path}' was not granted."

    if not os.path.exists(file_path):
        return f"Error: File '{file_path}' does not exist."

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            content = f.read()
        print(f"✅ Read {len(content)} characters from '{file_path}'\n")
        return content
    except Exception as e:
        return f"Error reading file '{file_path}': {e}"

出于安全考虑，我们实现了每次读取文件前都需征求用户许可的机制，以防不慎向代理提供私人数据。

以下是该函数的工具规范：

from xai_sdk.chat import tool
read_file_tool = tool(
    name="read_local_file",
    description="Reads the text contents of a local file given its relative or absolute path. Use this whenever the user asks to inspect, summarize, or analyze a local file.",
    parameters={
        "type": "object",
        "properties": {
            "file_path": {
                "type": "string",
                "description": "The path to the local file to read.",
            }
        },
        "required": ["file_path"],
    },
)

写入文件的代码类似，可在仓库中的 tools.py 文件找到。

如何使用 Grok 4.6 运行会用工具的代理循环？

本节我们将所学整合起来，构建一个 Grok 4.6 的代理式循环，使我们可以与能够通过操作本地文件执行实际工作、并通过搜索以在线数据为依据的代理进行对话。

代理的工作流程如下图所示。用户发送一个提示，随后代理在需要时使用工具进行回复。然后答案返回给用户，用户可以继续与代理互动。

代理通过使用 chat.append() 函数来追加用户提示、响应和工具结果，从而追踪整段会话。工具结果必须包装为 tool_result() 实例。

以下是完整的代理实现：

import json
from dotenv import load_dotenv
from xai_sdk import Client
from xai_sdk.chat import tool_result, user
from xai_sdk.tools import code_execution, web_search, x_search
from tools import (
    execute_read_file,
    execute_write_file,
    read_file_tool,
    write_file_tool,
)

load_dotenv()

# 1. Initialize the chat client with both server-side and client-side tools
client = Client()
chat = client.chat.create(
    model="grok-4.6",
    tools=[web_search(), x_search(), code_execution(), read_file_tool, write_file_tool],
)

# 2. Interactive chat loop
while True:
    try:
        prompt = input("> ")
    except (EOFError, KeyboardInterrupt):
        print()
        break

    if not prompt.strip():
        continue
    if prompt.strip().lower() in ("exit", "quit"):
        break

    # Append the user prompt to the conversation
    chat.append(user(prompt))

    # Agent loop: keeps running until Grok finishes (no further client tool calls)
    print("How can I help you?\n")
    while True:
        response = None
        announced_tools = set()
        started_content = False

        for response, chunk in chat.stream():
            # Announce tool calls
            if chunk.tool_calls:
                for tc in chunk.tool_calls:
                    name = getattr(tc.function, "name", "")
                    tc_id = getattr(tc, "id", None) or name
                    if tc_id and tc_id not in announced_tools:
                        announced_tools.add(tc_id)
                        display_name = name or "tool"
                        print(f"\n⚙️  [Agent Tool] Calling: {display_name}...", flush=True)

            # Stream generated content
            if chunk.content:
                if not started_content:
                    print("\nGrok > ", end="", flush=True)
                    started_content = True
                print(chunk.content, end="", flush=True)

        if response:
            chat.append(response)

        # Check if Grok triggered client-side tools
        client_tool_executed = False
        if response and response.tool_calls:
            for tool_call in response.tool_calls:
                fn_name = tool_call.function.name
                if fn_name == "read_local_file":
                    client_tool_executed = True
                    try:
                        args = json.loads(tool_call.function.arguments)
                        file_path = args.get("file_path", "")
                    except Exception:
                        file_path = tool_call.function.arguments or ""
                    
                    result = execute_read_file(file_path)
                    chat.append(tool_result(result, tool_call_id=tool_call.id))

                elif fn_name == "write_local_file":
                    client_tool_executed = True
                    try:
                        args = json.loads(tool_call.function.arguments)
                        file_path = args.get("file_path", "")
                        content = args.get("content", "")
                    except Exception:
                        file_path = ""
                        content = ""
                    
                    result = execute_write_file(file_path, content)
                    chat.append(tool_result(result, tool_call_id=tool_call.id))

        # If Grok called a client-side tool, re-enter the loop so Grok processes the tool result
        if client_tool_executed:
            continue
        
        break

    print("\n")

测试 Grok 4.6 代理进行股票投资组合分析

为测试代理，我创建了一个示例股票投资组合 CSV 文件。该文件很简单，列出了股票，特别包含购买日期和买入价格。

思路是让代理：

1. 加载该 CSV 文件。
2. 进行网络搜索，获取每只股票的当前价格。
3. 更新 CSV，新增一列当前价格。
4. 请代理基于我们的投资组合，创建一份展示各行业最新动态的报告。

下面是与代理在第 1 至 3 步的交互截图。

我们可以看到，它使用了网页搜索、代码执行以及我们创建的自定义工具来读取和写入本地文件。最终，它通过新增当前股价列更新了 CSV 文件。

由于代理在循环中运行，我们可以继续对话。接下来我让它查询这些股票的相关新闻、分析组合多样性，并创建一份 Markdown 报告。

如果您对其生成的报告感兴趣，可在GitHub 仓库中查看。

在真实任务（如分析股票投资组合）上测试代理，确实能展示 Grok 4.6 的能力。通过自行进行网络搜索、运行代码并调用本地工具，该模型能够轻松处理复杂请求。

提示缓存与 200k 定价断点

在实现多轮代理时，应确保对话被缓存，这样模型无需在每次交互时重新处理整个历史。否则成本可能会非常高。

缓存是自动进行的，但缓存条目按服务器存储，且默认情况下，请求可能被路由到不同服务器而错过缓存。为最大化缓存命中率，我们提供一个稳定的会话标识符，使得会话内的所有请求都到达同一台服务器。传递方式取决于所用 API：

• xai-sdk（gRPC）：x-grok-conv-id，在初始化客户端时作为 gRPC metadata 传入

• OpenAI Responses API：prompt_cache_key，在请求体中设置

以下代码片段展示了如何实现：

import uuid
from dotenv import load_dotenv
from xai_sdk import Client
from xai_sdk.chat import tool_result, user

load_dotenv()

# 1. Generate a unique ID for the conversation loop
conv_id = str(uuid.uuid4()) 

# 2. Pass the ID when initializing the Client
client = Client(
    metadata=(("x-grok-conv-id", conv_id),)
)

# ... [the rest of the code remains the same]

需要重点考虑的一点是，对于很长的对话，财务惩罚会尤其严重。一旦您的总提示长度达到或超过 200k token，API 将应用 2 倍乘数，对整个请求按双倍标准费率计费。

为防止多轮循环超出 200k 门槛，强烈建议实现上下文压缩。方法是在周期性地总结较早的对话轮次，或滑动上下文窗口。该策略可确保您在核心指令上持续享受便宜的缓存命中，同时避免无休止增长的上下文窗口带来的高额成本。

结语

在本教程中，我们学习了如何使用 Python 调用 SpaceXAI API 与 Grok 4.6 交互。我们掌握了如何发送文本和图像提示的基础操作，以及如何处理输出以便让用户了解模型的处理进度。

在掌握了为 AI 模型提供工具的方法后，我们将这些组合起来，构建了一个能够使用 Grok 4.6 解决真实任务（如分析股票投资组合）的 AI 代理。最后，我们了解到在未使用缓存的情况下，执行长上下文任务的成本会非常高。

作为练习，建议您在代理中实现缓存，并将输出更新为同时显示推理 token。

如果您想进一步学习如何使用 API 构建 AI 代理，推荐我们的 Working with the OpenAI API 课程。深入系统学习 AI 代理的最佳去处是 AI Agent Fundamentals 技能路径。