xai-agent-tools

用途

xAI Agent Tools API 面向需要构建具备实时数据访问与自主工具调用能力的智能体场景。它采用服务端智能体工具调用机制，由服务端管理整个推理与工具执行循环，而传统工具调用需要客户端自行处理每一次调用。

主要能力

该 API 提供以下可用工具：

x_search：搜索 Twitter/X 帖子
web_search：实时网页搜索
code_execution：Python 沙箱
document_search：搜索已上传的文档

使用方式

通过 OpenAI 兼容客户端接入，将 base_url 设为 https://api.x.ai/v1，并使用环境变量中的 XAI_API_KEY。示例代码：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

# Agent with automatic tool use
response = client.chat.completions.create(
    model="grok-4-1-fast",
    messages=[{
        "role": "user",
        "content": "Search X for Tesla news, then search the web for Tesla stock price, and calculate the sentiment score"
    }]
)
print(response.choices[0].message.content)

工具配置

X Search 工具配置示例：

x_search_config = {
    "type": "x_search",
    "x_search": {
        "enabled": True,
        "allowed_x_handles": ["elonmusk", "Tesla"],  # Max 10
        "excluded_x_handles": [],  # Cannot use with allowed
        "date_range": {
            "start": "2025-12-01",  # ISO8601
            "end": "2025-12-05"
        },
        "include_media": True  # Analyze images/videos
    }
}

Web Search 工具配置示例：

web_search_config = {
    "type": "web_search",
    "web_search": {
        "enabled": True,
        "search_depth": "comprehensive",  # or "quick"
        "include_domains": ["reuters.com", "bloomberg.com"],
        "exclude_domains": ["spam.com"]
    }
}

Code Execution 工具配置示例：

code_execution_config = {
    "type": "code_execution",
    "code_execution": {
        "enabled": True,
        "language": "python",
        "timeout": 30  # seconds
    }
}

智能体模式

资料给出了多种智能体模式示例，包括：

研究智能体（Research Agent）：同时搜索 X 与网页，综合实时社交讨论、新闻与分析，输出关键发现、情感分析与建议。
分析智能体（Analysis Agent）：使用代码执行进行数据解析、统计分析、洞察生成与可视化。
金融智能体（Financial Agent）：针对股票代码，搜索 X 上的散户情绪、影响者观点与突发新闻，搜索网页上的新闻、分析师评级与财报，并用代码执行计算情感分数、分析提及速度与生成汇总统计，输出投资报告。
多步骤智能体（Multi-Step Agent）：将目标拆解为步骤，使用相应工具逐步执行并综合结果。

工具成本管理

资料列出各工具每 1,000 次调用的成本：

工具	每 1,000 次调用成本
X Search	$5.00
Web Search	$5.00
Code Execution	$5.00
Document Search	$2.50

并给出成本优化智能体示例，通过限制工具调用次数（如 max_tool_calls）来控制成本。

错误处理与流式响应

资料提供了带完整错误处理的智能体示例（捕获异常并返回成功标志、结果、用量或错误类型），以及流式输出示例（stream=True 并逐块打印）。

对话上下文

资料给出 ConversationalAgent 类示例，通过维护 messages 列表来保留对话历史，支持添加系统提示并连续对话。

适用场景

适用于需要实时数据访问与自主工具调用的智能体构建，例如：

综合研究：结合 X 实时社交讨论与网页新闻分析
数据分析：借助 Python 沙箱进行统计分析与可视化
金融分析：结合社交情绪、新闻与代码计算生成投资报告
多步骤复杂任务：拆解目标并调用多种工具执行

限制

资料中未提供关于平台支持范围、并发限制、配额、可用区域等具体限制信息。

最佳实践

资料列出以下最佳实践：

使用 grok-4-1-fast——针对工具调用优化
指令具体——清晰指令可减少不必要的工具调用
设置限制——通过工具调用预算控制成本
处理错误——工具可能失败，需提前规划
流式输出——长响应使用流式以改善体验
缓存结果——不要重复相同的搜索

智能体模型选择

资料给出模型对比表：

模型	工具调用	速度	成本
grok-4-1-fast	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
grok-4	⭐⭐	⭐	⭐
grok-3-fast	⭐	⭐⭐⭐	⭐⭐⭐

参考

资料列出的参考包括：Agent Tools API、Tools Overview、Function Calling。

技能介绍

用途