Xikapi 接入文档

工具调用 ​

工具调用让 Grok 在需要外部数据、实时信息或业务动作时请求调用工具。模型负责判断是否需要工具、生成工具参数；你的服务端负责执行自定义工具、校验权限，并把结果返回给模型。

什么是 Tool Use ​

工具调用适合以下场景：

  • 查询订单
  • 查询数据库
  • 搜索知识库
  • 调用内部 API
  • 搜索 Web 或 X
  • 获取实时信息
  • 执行受控业务操作

工具类型 ​

Grok 工具可以分为两类：

  • 服务端工具：例如 Web Search、X Search、文件搜索等，由 xAI 服务端处理
  • 自定义函数：由你的服务端执行，例如查询订单、查询数据库、创建工单

工具定义结构 ​

自定义工具通常包含名称、描述和输入参数 schema。

json
{
  "type": "function",
  "name": "get_order_status",
  "description": "Check order shipping status",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order ID"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

工具调用流程 ​

  1. 服务端在请求中传入 tools
  2. 用户提出需要外部信息的问题
  3. Grok 返回工具调用请求
  4. 服务端读取工具名称和参数
  5. 服务端执行真实工具
  6. 服务端把工具结果返回给 Grok
  7. Grok 根据工具结果生成最终回复

模型什么时候会调用工具 ​

当用户问题需要实时数据、私有数据或系统操作时，Grok 可能选择调用工具。

json
{
  "model": "grok-4.3-latest",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "description": "Check order status",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" }
        },
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  ],
  "input": [
    { "role": "user", "content": "Check where order A1001 is now" }
  ]
}

服务端如何执行工具 ​

服务端应只执行白名单内的工具，并对参数进行校验。

javascript
const toolHandlers = {
  async get_order_status(input) {
    if (!/^[A-Z0-9-]+$/.test(input.order_id)) {
      throw new Error("Invalid order_id");
    }

    return await queryOrderStatus(input.order_id);
  },
};

如何把工具结果返回给 Grok ​

工具调用的响应形态会随 SDK 和接口形态不同而变化。无论使用哪种形态，服务端都要保留工具调用 ID，并把对应结果回填给模型。

json
{
  "model": "grok-4.3-latest",
  "input": [
    {
      "role": "user",
      "content": "Check where order A1001 is now"
    },
    {
      "type": "function_call_output",
      "call_id": "call_xxx",
      "output": "Order A1001 has arrived at the Shanghai distribution center and is expected to be delivered tomorrow."
    }
  ]
}

多工具场景 ​

多工具适合同时提供订单查询、用户资料、知识库搜索、Web Search、X Search、工单创建等能力。

设计多工具时要注意：

  • 工具名称清晰，不要语义重叠
  • 每个工具只做一类明确动作
  • 高风险动作必须二次确认
  • 工具结果尽量返回结构化数据
  • 不要把内部密钥、SQL 或敏感配置暴露给模型
  • 服务端工具可能产生额外费用，要记录工具使用量

工具调用最佳实践 ​

  • 工具执行必须在服务端
  • 所有参数都要做 schema 校验和业务校验
  • 工具调用要记录日志，便于排查
  • 写操作要增加权限控制和确认流程
  • 给工具写清楚能力边界，避免模型误用
  • 工具结果中只返回回答所需的信息