feat: xai server-side tool calling #9896

dancer · 2025-10-29T19:13:59Z

Background

xai supports server-side agentic tool calling through their responses api. this allows models to autonomously execute tools like web search, x search, and code execution on their servers without requiring client-side tool handling

https://docs.x.ai/docs/api-reference#create-new-response
https://docs.x.ai/docs/guides/tools/overview

Summary

added xai responses api with server-side tool execution
implemented 5 server-side tools: web_search, x_search, code_execution, view_image, view_x_video
added tool name mapping to handle sub-tool variants (browse_page → web_search, x_semantic_search → x_search)
added citation extraction from response annotations
added multi-turn conversation support with function_call items
created next.js example with toolloopagent for multi-step workflows

Manual Verification

tested with next.js example app using toolloopagent:

multi-step research queries with web_search and x_search working
tool sub-calls properly mapped to parent tools (no infinite loops)
citations displaying with url fallback when title missing
streaming events handling all 11+ event types correctly
99 tests passing with real api fixtures

Checklist

Tests have been added / updated (for bug fixes / features)
Documentation has been added / updated (for bug fixes / features)
A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
I have reviewed this pull request (self-review)

follow up

use lazySchema, see #9339 on all of xai

gr2m

preliminary review. Please add an example to examples/next-openai/app and test the xAI Responses API with multi-steps. We have been using that for all providers, we should probably rename the folder 😅

examples/ai-core/src/agent/xai-agent-research.ts

gr2m · 2025-10-29T20:58:04Z

packages/xai/src/responses/convert-to-xai-responses-input.ts

+              inputWarnings.push({
+                type: 'other',
+                message:
+                  'xAI Responses API does not support this content type in user messages',


I would include block.type in the message, it will make it more useful.

you didn't add block.type to message:?

packages/xai/src/responses/xai-responses-api.ts

gr2m · 2025-10-29T21:20:06Z

packages/xai/src/responses/xai-responses-api.ts

+  num_server_side_tools_used: z.number().optional(),
+});
+
+export const xaiResponsesResponseSchema = z.object({


we should use lazySchema, see #9339. You can do it in a follow up PR though and do all of xAI then.

gr2m · 2025-10-29T21:27:39Z

packages/xai/src/responses/xai-responses-api.ts

+  status: z.string(),
+});
+
+export const xaiResponsesChunkSchema = z.union([


use lazySchema, see above

packages/xai/src/responses/xai-responses-options.ts

gr2m

testing the next.js chat-xai-web-search example returns in an error for multi-turn

packages/xai/src/responses/xai-responses-language-model.ts

vercel

Additional Comments:

packages/provider/src/language-model/v3/language-model-v3-tool-result.ts (modified) (line 22):
The type definition changed result from unknown to NonNullable<unknown>, which excludes undefined. However, the XAI responses implementation sets result: undefined for server-side tool calls, causing a type incompatibility.

View Details

📝 Patch Details

diff --git a/packages/xai/src/responses/xai-responses-language-model.ts b/packages/xai/src/responses/xai-responses-language-model.ts
index 954968896..d3100793e 100644
--- a/packages/xai/src/responses/xai-responses-language-model.ts
+++ b/packages/xai/src/responses/xai-responses-language-model.ts
@@ -212,7 +212,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
           type: 'tool-result',
           toolCallId: part.id,
           toolName,
-          result: undefined,
+          result: {},
           providerExecuted: true,
         });
 
@@ -500,7 +500,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
                     type: 'tool-result',
                     toolCallId: part.id,
                     toolName,
-                    result: undefined,
+                    result: {},
                     providerExecuted: true,
                   });
                 }

Analysis

Type incompatibility between LanguageModelV3ToolResult and XAI implementation

What fails: XaiResponsesLanguageModel creates tool-result objects with result: undefined (lines 215 and 503), but the type definition LanguageModelV3ToolResult.result is NonNullable<unknown>, which excludes undefined.

How to reproduce:

npm run type-check

Result: TypeScript reports two type errors:

packages/xai/src/responses/xai-responses-language-model.ts(215,11): error TS2322: Type 'undefined' is not assignable to type '{}'.
packages/xai/src/responses/xai-responses-language-model.ts(503,21): error TS2322: Type 'undefined' is not assignable to type '{}'.

Expected: Type check should pass. The type was changed to NonNullable<unknown> in commit 26836cf ("spec update: toll result .result is unknown, but not nullable"), but the XAI implementation was not updated to comply with this constraint.

Fix: Changed result: undefined to result: {} in both locations. This satisfies the type constraint while semantically representing "no result data" for server-side tool executions where the XAI API does not return structured result data.

dancer · 2025-11-03T17:12:48Z

tested and verified fix via /chat-xai-web-search on next-openai

prompts tried:

What are the latest announcements from xAI?
Tell me more about the latest model
When was it released?

updated fixtures as well according to https://github.com/vercel/ai/blob/main/contributing/testing.md#test-fixtures

cc: @gr2m

packages/xai/src/responses/xai-responses-prepare-tools.ts

gr2m

just one nit left:
#9896 (comment)

We can merge but I'd like @nicoalbanese to review docs, even after PR is merged

…` to `NonNullable<JSONValue>` (#9931) ## Background Discovered in #9896 (review) ## Summary As far as I can tell, `result` has to be set to something that is not null or undefined. This makes the spec more precise and would have surfaced the problem of #9896 (review) immediately ## Manual Verification When the fix from this PR is applied, a type error is thrown in #9896

feat: xai server-side tool calling

90f124d

github-actions bot assigned dancer Oct 29, 2025

dancer marked this pull request as draft October 29, 2025 19:14

dancer requested a review from gr2m October 29, 2025 19:14

prettier

40819d0

vercel bot deployed to Preview October 29, 2025 19:16 View deployment

changesets + tests(pending)

836fb21

vercel bot deployed to Preview October 29, 2025 19:22 View deployment

gr2m reviewed Oct 29, 2025

View reviewed changes

fixtures + tests, e2e frontend

827bcfa

vercel bot deployed to Preview October 30, 2025 01:34 View deployment

fixes

9a87794

vercel bot deployed to Preview October 30, 2025 01:45 View deployment

prettier

8764cf9

vercel bot deployed to Preview October 30, 2025 01:47 View deployment

prettier

ecd94e1

vercel bot deployed to Preview October 30, 2025 02:38 View deployment

dancer added 2 commits October 30, 2025 02:44

documentation + vid / image search examples

cd6a81d

prettier

560906c

dancer marked this pull request as ready for review October 30, 2025 02:45

vercel bot deployed to Preview October 30, 2025 02:47 View deployment

gr2m self-assigned this Oct 30, 2025

gr2m requested changes Oct 30, 2025

View reviewed changes

packages/xai/src/responses/xai-responses-language-model.ts Outdated Show resolved Hide resolved

packages/xai/src/responses/xai-responses-language-model.ts Outdated Show resolved Hide resolved

spec update: toll result .result is unknown, but not nullable

26836cf

vercel bot deployed to Preview October 30, 2025 23:42 View deployment

gr2m mentioned this pull request Oct 30, 2025

fix(spec): LanguageModelV3ToolResult["result"] change from unknown to NonNullable<JSONValue> #9931

Merged

4 tasks

vercel bot reviewed Oct 30, 2025

View reviewed changes

Merge branch 'main' into josh/xx

bda7a7d

vercel bot deployed to Preview November 3, 2025 15:17 View deployment

provider exec

08d70e0

vercel bot deployed to Preview November 3, 2025 16:51 View deployment

multi turn

158cb12

vercel bot deployed to Preview November 3, 2025 17:06 View deployment

fixtures

d3596ec

vercel bot deployed to Preview November 3, 2025 17:14 View deployment

prettier

d795aca

vercel bot deployed to Preview November 3, 2025 17:17 View deployment

vercel bot reviewed Nov 3, 2025

View reviewed changes

packages/xai/src/responses/xai-responses-prepare-tools.ts Show resolved Hide resolved

dancer added 2 commits November 3, 2025 17:35

fix warnings on view x video and x images

beeff40

tests

f29f9c7

vercel bot deployed to Preview November 3, 2025 17:38 View deployment

gr2m approved these changes Nov 3, 2025

View reviewed changes

gr2m added ai/provider provider/xai labels Nov 3, 2025

dancer merged commit 5ad1bbe into main Nov 3, 2025
26 checks passed

dancer deleted the josh/xx branch November 3, 2025 18:11

feat: xai server-side tool calling #9896

feat: xai server-side tool calling #9896

Uh oh!

Conversation

dancer commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Summary

Manual Verification

Checklist

follow up

Uh oh!

gr2m left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gr2m Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

gr2m Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gr2m Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

gr2m Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gr2m left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vercel bot left a comment

Choose a reason for hiding this comment

Analysis

Type incompatibility between LanguageModelV3ToolResult and XAI implementation

Uh oh!

dancer commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

gr2m left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dancer commented Oct 29, 2025 •

edited

Loading

dancer commented Nov 3, 2025 •

edited

Loading

gr2m left a comment •

edited

Loading