流、工具与结构化输出：完整请求生命周期

Streaming 只改变交付方式

设置 stream: true 后，Responses API 用 Server-Sent Events（SSE）逐事件发送。文本增量事件是 response.output_text.delta；完成时会出现完成事件。流式不会让模型“更聪明”，它减少首段文字等待并允许 UI 展示进度。

// 真实可运行示例，见 examples/stream.ts
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  // 按空行切分 SSE frame；每帧解析 event/data，而非逐网络 chunk JSON.parse
}

网络 chunk 不等于 SSE 事件：一个事件可能跨 chunk，也可能一个 chunk 含多个事件。示例维护 buffer，以 \n\n 分帧，再解析 event: 与 data: 行。

两类工具必须画成两条路

服务端工具（Web Search、X Search、Code Execution、Collections Search）由 xAI 基础设施执行。客户端 function 只由模型提出调用；你的应用执行真正业务逻辑并回传。

INTERACTIVE FIGUREAPI 请求生命周期：模型不会替你执行客户端函数

100%

你的应用1. 发送 input + tools4. 校验并执行函数5. 回传 tool output7. 渲染 / 持久化

→←→←

xAI API / Grok2. 推理与选择工具3. 返回 function_call6. 基于结果继续推理stream: response.completed

服务端工具旁路web_search / x_search / code_executionxAI 基础设施执行，并把结果带回模型上下文

xAI 托管工具可由服务端执行；自定义 function call 会暂停，必须由你的程序校验参数、执行、回传结果，再让模型继续。

Function Calling 的最小安全循环

工具定义包含 name、description 与 JSON Schema：

const tools = [{
  type: 'function',
  name: 'lookup_source',
  description: 'Look up an allowlisted source by stable ID.',
  parameters: {
    type: 'object',
    properties: { id: { type: 'string', pattern: '^[a-z0-9-]{1,64}$' } },
    required: ['id'],
    additionalProperties: false,
  },
}];

收到 function_call 后，不要 eval(arguments)，也不要直接信任模型生成的 URL、SQL 或文件路径。安全循环需要：

JSON.parse 后用同一 schema 做运行时校验；
只从 allowlist 映射函数名；
绑定当前用户权限，设置超时与输出上限；
对副作用动作做确认、幂等与审计；
用相同 call_id 回传 function_call_output；
循环有最大轮数和总预算。

xAI 默认允许 parallel function calling。同一响应若有多个调用，应全部处理并回传，再继续模型循环；并行不代表任意调用都可安全并发，写操作仍需业务层顺序与事务规则。

Structured Outputs 约束最终答案

Function schema 约束工具输入；Structured Outputs 的 response_format 约束最终回答。两者可以组合，但不是同一机制。

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "concept_explanation",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "intuition": { "type": "string" },
          "mechanism": { "type": "array", "items": { "type": "string" } },
          "limits": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["intuition", "mechanism", "limits"],
        "additionalProperties": false
      }
    }
  }
}

xAI 文档说明在受支持 schema 特性与限制内可保证匹配。支持的是 JSON Schema 子集，不要把任意复杂约束都视为强保证；应用仍应解析和校验，再处理拒绝、超时和截断。

搜索工具与引用

{
  "model": "grok-4.5",
  "input": "查找 xAI 对 Grok-1 开放发布的原始说明，并给出日期。",
  "tools": [{
    "type": "web_search",
    "filters": { "allowed_domains": ["x.ai", "github.com"] }
  }]
}

Web Search 可限制最多 5 个允许或排除域；X Search 可限制账号和 ISO 日期范围。搜索能返回来源并生成 inline citations，但“有引用”不保证每个断言都有证据，也不保证抓取完整或排序中立。

实时检索的生产检查表：记录 query、过滤器、访问日期、来源 URL 与模型版本；为高风险事实打开原文核验；遇到冲突时输出分歧，不让模型强行合并成单一确定答案。

一次完整 agent 请求的停止条件

不要只写 while (toolCalls.length)。至少同时约束：

最大工具轮次；
墙钟时间；
token 与工具费用预算；
单工具超时、返回字节和并行度；
连续重复调用检测；
最终输出 schema；
需要人类确认的副作用类别。

本章检查点

Streaming 是传输协议，Function Calling 是客户端控制回路，server-side tools 是托管执行，Structured Outputs 是输出契约。把四者分开实现，故障与权限才有明确归属。