企业官网建设流程全解析

从 Live Search 到 Agentic Tools：@langchain/xai 集成包能力演进全解析

【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs

导读

@langchain/xai是 LangChain.js 官方的 xAI（Grok）模型集成包，为开发者提供在 LangChain 生态中原生调用 Grok 系列模型的能力。本文以该包 CHANGELOG（v1.0.0 → v1.4.13）为时间主线，结合仓库源码逐层拆解其核心能力演进：从 Completions 与 Responses 双 API 架构、结构化输出支持，到 Live Search 的引入与弃用、新一代 Agentic 服务端工具（Web Search / X Search / Code Execution / Collections Search）、流式事件与中断处理等。读完本文，你将完整掌握@langchain/xai的版本能力地图，并能正确选用ChatXAI与ChatXAIResponses完成实时搜索、结构化输出与工具调用等实战场景。

一、版本演进总览：一条清晰的能力时间线

@langchain/xai从 v1.0.0 到 v1.4.13 的演进，恰好映射了 xAI 平台本身的能力升级节奏。通过 CHANGELOG 可以梳理出以下里程碑：

其中绝大多数 Patch 版本是跟随@langchain/openai的依赖更新（如 1.4.13 更新到@langchain/openai@1.5.13），这也揭示了一个关键架构事实：@langchain/xai的 Completions 路径并非从零实现，而是复用 OpenAI 集成作为底层协议层。

二、v1.0：LangChain v1.0 兼容起点与双入口设计

v1.0.0 版本明确说明"该发布使包与 LangChain v1.0 兼容"。从 package.json 可以看到包的工程约束：

• peerDependencies要求@langchain/core: ^1.0.0；
• 唯一运行时依赖是@langchain/openai（workspace:*）；
• 构建产物同时提供 CJS 与 ESM 双格式，main指向./dist/index.cjs，module指向./dist/index.js。

入口 src/index.ts 只做了两件事：导出chat_models下的全部内容，并导出tools命名空间。也就是说，用户实际接触的 API 面由 src/chat_models/index.ts 决定——它同时导出completions.js（ChatXAI）、responses.js（ChatXAIResponses）与responses-types.js，构成典型的"双模型入口"。

安装与基础调用

npm install @langchain/xai export XAI_API_KEY="your-api-key"

import { ChatXAI } from "@langchain/xai"; const llm = new ChatXAI({ model: "grok-3-fast", temperature: 0, }); const result = await llm.invoke("Translate \"I love programming\" into French."); console.log(result);

构造函数会优先读取显式传入的apiKey，否则回退到XAI_API_KEY环境变量；两者都缺失时直接抛出错误（见 completions.ts）。默认模型为grok-3-fast，默认baseURL为https://api.x.ai/v1。

三、双 API 架构：ChatXAI（Completions）与 ChatXAIResponses（Responses）

v1.2.0（PR #9718）为包引入了 Responses API 实现，这是整个演进中最具分水岭意义的一次变更。

ChatXAI：基于 OpenAI 兼容协议

ChatXAI继承自ChatOpenAICompletions（来自@langchain/openai），因为 xAI 的 Completions API 与 OpenAI 高度兼容。源码在completionWithRetry中做了几处针对 xAI 的协议修正（completions.ts）：

• 删除 xAI 不支持的frequency_penalty、presence_penalty、logit_bias、functions参数；
• 将空content消息规范化为""；
• 从 tools 列表中过滤掉 xAI 内置工具（live_search），因为这些内置工具是通过search_parameters字段控制而非普通 function tools。

ChatXAIResponses：面向 Agentic 能力的原生实现

ChatXAIResponses（v1.2.0 引入）则直接继承BaseChatModel，通过原生fetch调用${baseURL}/responses端点（responses.ts），不经过 OpenAI 层。其默认模型为grok-3，并拥有独立的调用参数集合：

import { ChatXAIResponses } from "@langchain/xai"; const llm = new ChatXAIResponses({ model: "grok-3", temperature: 0.7, }); const result = await llm.invoke("What is the capital of France?");

ChatXAIResponses的invocationParams（responses.ts）暴露出 Responses 协议特有的能力字段：

选用建议：需要 xAI 最新 Agentic 服务端工具（Web Search、X Search、Code Execution、Collections Search）时使用ChatXAIResponses；需要与 OpenAI 工具生态深度对齐、复用bindTools+ Zod schema 的经典工作流时使用ChatXAI。两者都支持流式输出与结构化输出。

四、实时搜索能力：Live Search 的引入、使用与弃用

4.1 v1.1.0：原生 Live Search 支持

v1.1.0（PR #9537）为 xAI 提供者加入原生 Live Search 支持，允许 Grok 在回答中搜索实时信息。实现上有两条并行的使用路径，源码中均有明确注释。

路径一：searchParameters参数（Completions 路径）

const llm = new ChatXAI({ model: "grok-3-fast", searchParameters: { mode: "auto", // "auto" | "on" | "off" max_search_results: 5, from_date: "2024-01-01", // ISO 日期字符串 return_citations: true, } }); const result = await llm.invoke("What are the latest AI developments?");

路径二：内置live_search工具

const llmWithSearch = new ChatXAI({ model: "grok-3-fast", temperature: 0, }).bindTools([{ type: "live_search" }]); const result = await llmWithSearch.invoke("What happened in tech news today?");

底层实现中，invocationParams会调用mergeSearchParams将三处配置合并为最终的search_parameters负载（live_search.ts），合并优先级从低到高为：工具级配置 → 实例级默认值 → 单次调用覆盖。随后由buildSearchParametersPayload补齐默认值（mode缺省为"auto"，max_search_results缺省为 20）后发送给 API。

4.2 搜索源（sources）配置

XAISearchParameters.sources支持四种搜索源，对应 xAI 文档中的search_parameters.sources结构（live_search.ts）：

• web：country（ISO alpha-2 国家代码偏向）、allowed_websites/excluded_websites（各最多 5 条）、safe_search；
• news：country、excluded_websites、safe_search；
• x（X/Twitter）：included_x_handles/excluded_x_handles（各最多 10 条）、post_favorite_count、post_view_count；
• rss：links（RSS 源 URL，当前 API 期望单个 URL）。

若省略sources，xAI 默认启用 web、news、x 三类源。

4.3 v1.3.0：弃用与迁移

v1.3.0 在新增 Agentic 工具的同时正式弃用了 Live Search。源码中的 live_search.ts 给出了明确的迁移指引：Live Search API 将于 2025 年 12 月 15 日弃用，xaiLiveSearch()工具类型被标记为live_search_deprecated_20251215，同时xaiLiveSearch在tools命名空间中被标注@deprecated（tools/index.ts）。

// 旧（已弃用）： const searchTool = tools.xaiLiveSearch({ maxSearchResults: 5 }); // 新（推荐）： const webSearch = tools.xaiWebSearch({ allowedDomains: ["example.com"] }); const xSearch = tools.xaiXSearch({ allowedXHandles: ["elonmusk"] });

五、新一代 Agentic 服务端工具（v1.3.0）

v1.3.0（PR #9890）是能力最密集的一次 Minor 发布：新增 xAI 服务端 Agentic 工具，工具由 xAI API 在服务端直接执行，无需客户端实现工具逻辑。四个工具全部集中导出在tools命名空间（tools/index.ts），配合ChatXAIResponses使用。

5.1 xaiWebSearch：Web 搜索

在服务端搜索网页并浏览页面获取实时信息（web_search.ts）：

import { ChatXAIResponses, tools } from "@langchain/xai"; const llm = new ChatXAIResponses({ model: "grok-4-1-fast" }); const webSearch = tools.xaiWebSearch({ allowedDomains: ["wikipedia.org", "arxiv.org"], // 最多 5 个，与 excludedDomains 互斥 enableImageUnderstanding: true, // 开启图片理解，会增加 token 消耗 }); const result = await llm.invoke("What are the latest AI developments?", { tools: [webSearch], });

5.2 xaiXSearch：X（Twitter）搜索

支持 handle 过滤、日期范围与媒体理解，适合舆情监控与实时社媒检索。

5.3 xaiCodeExecution：Python 代码执行

在 xAI 服务端沙箱中执行 Python 代码，适用于数学计算、数据分析、金融建模、科学计算等场景（code_execution.ts）。其类型常量为code_interpreter，沙箱预装 NumPy、Pandas、Matplotlib、SciPy 等常用库：

const codeExecution = tools.xaiCodeExecution(); const result = await llm.invoke( "Calculate the compound interest for $10,000 at 5% annually for 10 years", { tools: [codeExecution] } );

5.4 xaiCollectionsSearch：知识库检索

检索已上传的知识库（vector store），适合 RAG 场景。v1.3.0 同时更新了XAIResponsesWebSearchTool类型以携带正确的过滤选项，并将tools支持接入ChatXAIResponses构造函数与调用选项。

// 组合使用示例：先搜索 AAPL 股价，再计算 5 年 10% 年化增长 const webSearch = tools.xaiWebSearch(); const codeExecution = tools.xaiCodeExecution(); const result = await llm.invoke( "Find the current stock price of AAPL and calculate what it would be worth with 10% annual growth over 5 years", { tools: [webSearch, codeExecution] } );

六、结构化输出：从标准 schema 到默认启用

v1.3.8（PR #10216）为 xAI 提供者实现 standard schema 结构化输出支持，v1.3.9（PR #10293）进一步启用结构化输出默认值并替换已废弃的测试模型。这使得withStructuredOutput成为开箱即用的能力：

import { z } from "zod"; const Joke = z.object({ setup: z.string().describe("The setup of the joke"), punchline: z.string().describe("The punchline to the joke"), rating: z.number().optional().describe("How funny the joke is, from 1 to 10"), }).describe("Joke to tell user."); const structuredLlm = llmForToolCalling.withStructuredOutput(Joke, { name: "Joke" }); const jokeResult = await structuredLlm.invoke("Tell me a joke about cats"); console.log(jokeResult);

结合 v1.3.5 的字符串模型名构造函数重载（PR #10080），可以写出更简洁的实例化方式：

// 重载签名：ChatXAI(model: string, fields?) const llm = new ChatXAI("grok-3-fast", { temperature: 0 });

七、流式事件：原生 streamEvents 支持（v1.4.0）

v1.4.0（PR #10924）为 completions 与 responses 两条路径都加入了原生 streamEvents 事件支持。在源码层，ChatXAI通过get streamEventProvider()返回"xai"来标记事件提供方（completions.ts）；ChatXAIResponses则实现了_streamChatModelEvents，将 xAI Responses 的流式事件（response.output_text.delta等）通过convertXAIResponsesStream转换为标准的ChatModelStreamEvent（responses.ts）。相关实现与测试位于 utils/responses_stream_events.ts 及其 测试。

普通流式输出同样得到完整支持，且 xAI 对 token 用量的处理经过了专门设计：_convertCompletionsDeltaToBaseMessageChunk会在没有finish_reason时删除中间 chunk 的usage与usage_metadata，仅在最终 chunk 写入，从而保证concat合并 chunk 时不产生 merge 警告（completions.ts）。

for await (const chunk of await llm.stream(input)) { console.log(chunk); }

八、中断处理与 ModelAbortError（v1.3.0）

v1.3.0 的两个 Patch（PR #9900）显著改善了聊天模型的中止信号处理，这在构建"可取消 + 可降级"的 Agent 系统时至关重要：

• 在@langchain/core/errors中新增ModelAbortError类：当流式调用中途被中止时，invoke()抛出携带已累积partialOutput的ModelAbortError；
• stream()被中止时抛出常规AbortError（因为 chunk 已逐段交给调用方）；
• _generate()起始处调用signal.throwIfAborted()立即响应已中止的信号；_streamResponseChunks的流式循环内检查信号并提前返回。

在ChatXAIResponses源码中可以清晰看到这两处守卫（responses.ts）。这一行为让 fallback 链在前一个 runnable 被中止时能正确推进到下一个 runnable，相关的标准测试位于@langchain/standard-tests。

九、baseURL 自定义与 LangSmith 观测（v1.3.0 / v1.0.1 / v1.3.7）

9.1 baseURL 配置（PR #9889）

ChatXAI在 v1.3.0 新增baseURL选项，用于覆盖默认的https://api.x.ai/v1端点，可对接自定义网关、代理或兼容 xAI 协议的第三方服务：

const llm = new ChatXAI({ model: "grok-3-fast", baseURL: "https://your-proxy.example.com/v1", });

该值在构造函数中直接注入 OpenAI 客户端的configuration.baseURL（completions.ts）。序列化时toJSON()会剔除openai_api_key与configuration，避免密钥泄露到序列化结果中。

9.2 模型画像与追踪元数据

• v1.0.1 引入ModelProfile与.profile属性：new ChatXAI({ model: "grok-3-fast" }).profile返回模型能力画像（token 上限、多模态、工具调用、结构化输出支持等），数据由 profiles.toml 经模型画像生成器产出为 src/profiles.ts，package.json中的typegen:profiles脚本即负责此生成流程；
• v1.3.7 起每个包在构造时通过this._addVersion("@langchain/xai", __PKG_VERSION__)将版本写入this.metadata.versions，使 LangSmith 追踪元数据中携带包版本信息；
• getLsParams会将ls_provider标记为"xai"（Responses 路径还会写入ls_model_name、ls_model_type、ls_temperature、ls_max_tokens），便于在 LangSmith 中按提供方筛选。

十、工程化与维护细节（v1.0.2 ~ v1.3.18）

除功能演进外，CHANGELOG 还记录了一批重要的工程质量变更：

• v1.0.2（PR #9416）：修复moduleResolution: "node"场景下的模块解析兼容性，保证在非 bundler 的 Node 项目中也能正确导入；
• v1.2.1（PR #9777）：正确提升 reasoning tokens——将推理模型（如 Grok 的思维链模型）产生的reasoning_content正确映射到消息的 reasoning token 通道，而不是混入普通内容 token；
• v1.3.18（PR #10556）：移除 deepseek、xai 中冗余的reasoning_content覆盖逻辑，简化实现对底层@langchain/core的推理 token 提升机制的统一依赖；同版本（PR #10872）清理了冗余的@types/uuid声明；
• 版本号策略：绝大多数 Patch 版本仅同步@langchain/openai依赖（如 1.4.13 →@langchain/openai@1.5.13），说明 Completions 路径的协议修复大多沉淀在 OpenAI 层，xAI 包保持轻量。

结语：如何按需选择能力组合

回顾整个演进脉络，@langchain/xai的能力选型可以归结为三条清晰路径：

1. 经典对话 + OpenAI 生态工具：使用ChatXAI+bindTools+ Zod schema，配合withStructuredOutput获得结构化输出；
2. 实时信息检索：旧项目可沿用searchParameters/xaiLiveSearch（注意 2025-12-15 弃用截止），新项目一律迁移到xaiWebSearch/xaiXSearch；
3. 完整 Agentic 能力：使用ChatXAIResponses组合xaiWebSearch、xaiXSearch、xaiCodeExecution、xaiCollectionsSearch四个服务端工具，配合流式事件（v1.4.0+）与中止信号处理构建可取消、可观测的 Agent 工作流。

在 xAI 平台持续迭代的背景下，建议优先跟进 Minor 版本的能力变更（尤其是 Agentic 工具与 streamEvents），并保持@langchain/openai依赖同步更新，以持续获得协议层的兼容性修复。

【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs