feat(ai-grok): use xAI Responses API#812
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughMigrates the ChangesGrok Responses API Migration
Sequence Diagram(s)sequenceDiagram
rect rgba(173, 216, 230, 0.5)
Note over Caller,xAI: Responses API path (new)
end
participant Caller
participant GrokTextAdapter
participant convertToolsToProviderFormat
participant OpenAIBaseResponsesTextAdapter
participant xAI as xAI Responses API
Caller->>GrokTextAdapter: generate(messages, options)
GrokTextAdapter->>GrokTextAdapter: validate grok-build-0.1 rejects reasoning option
GrokTextAdapter->>convertToolsToProviderFormat: options.tools
convertToolsToProviderFormat-->>GrokTextAdapter: GrokResponsesTool[]
GrokTextAdapter->>OpenAIBaseResponsesTextAdapter: super.mapOptionsToRequest(stripped options)
OpenAIBaseResponsesTextAdapter-->>GrokTextAdapter: base ResponseCreateParams
GrokTextAdapter->>GrokTextAdapter: set include=[reasoning.encrypted_content], store=false
GrokTextAdapter->>xAI: responses.create(params, stream=true)
xAI-->>GrokTextAdapter: response.created / response.output_text.delta / response.completed
GrokTextAdapter-->>Caller: AG-UI events (text, reasoning, usage)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/ai-grok/src/tools/index.ts`:
- Around line 18-67: The GrokMCPToolConfig interface is included in the
GrokServerTool union type, but xAI's Responses API documentation only supports
web_search, x_search, code_interpreter, and file_search as native tools, not
MCP. Since GrokServerTool is cast and sent directly to the xAI API, including an
unsupported tool type will cause runtime errors rather than compile-time errors.
Remove GrokMCPToolConfig from the GrokServerTool union type definition to ensure
only documented xAI-supported tool types are sent to the API.
In `@testing/panel/src/routes/api.chat.ts`:
- Line 185: The global default assignment of `model` to 'gpt-4o' at line 168
occurs before the provider-specific fallback at line 185 in the grokText
function call, making the Grok-specific default unreachable. Remove the global
default initialization of `model` at line 168 so that when data.model is not
provided, the provider-specific fallback (grok-build-0.1 for Grok, gpt-4o for
OpenAI, etc.) can be applied correctly based on which adapter is being used.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d35ccf62-5504-431e-b235-bf52a2a0ac42
📒 Files selected for processing (24)
.changeset/grok-responses-api.mddocs/adapters/grok.mdexamples/ts-react-chat/src/lib/model-selection.tsexamples/ts-react-chat/src/routes/api.structured-output.tsexamples/ts-react-chat/src/routes/api.tanchat.tsexamples/ts-react-chat/src/routes/generations.structured-output.tsxpackages/ai-code-mode/models-eval/eval-config.tspackages/ai-code-mode/models-eval/run-eval.tspackages/ai-grok/README.mdpackages/ai-grok/src/adapters/summarize.tspackages/ai-grok/src/adapters/text.tspackages/ai-grok/src/model-meta.tspackages/ai-grok/src/text/text-provider-options.tspackages/ai-grok/src/tools/index.tspackages/ai-grok/tests/grok-adapter.test.tspackages/ai-grok/tests/usage-extraction.test.tstesting/e2e/src/lib/features.tstesting/e2e/src/lib/providers.tstesting/e2e/src/routes/api.summarize.tstesting/panel/src/lib/model-selection.tstesting/panel/src/routes/api.chat.tstesting/panel/src/routes/api.structured.tstesting/panel/src/routes/api.summarize.tstesting/panel/tests/vendor-config.ts
| export interface GrokWebSearchToolConfig { | ||
| type: 'web_search' | ||
| filters?: { | ||
| allowed_domains?: Array<string> | ||
| excluded_domains?: Array<string> | ||
| } | ||
| enable_image_understanding?: boolean | ||
| enable_image_search?: boolean | ||
| } | ||
|
|
||
| export interface GrokXSearchToolConfig { | ||
| type: 'x_search' | ||
| allowed_x_handles?: Array<string> | ||
| excluded_x_handles?: Array<string> | ||
| from_date?: string | ||
| to_date?: string | ||
| enable_image_understanding?: boolean | ||
| enable_video_understanding?: boolean | ||
| } | ||
|
|
||
| export interface GrokFileSearchToolConfig { | ||
| type: 'file_search' | ||
| vector_store_ids: Array<string> | ||
| max_num_results?: number | ||
| } | ||
|
|
||
| export interface GrokMCPToolConfig { | ||
| type: 'mcp' | ||
| server_label: string | ||
| server_url: string | ||
| allowed_tools?: Array<string> | ||
| server_description?: string | ||
| authorization?: string | ||
| headers?: Record<string, string> | ||
| } | ||
|
|
||
| export type GrokServerTool = | ||
| | GrokWebSearchToolConfig | ||
| | GrokXSearchToolConfig | ||
| | GrokFileSearchToolConfig | ||
| | GrokMCPToolConfig | ||
|
|
||
| type GrokProviderToolMetadata<TKind extends GrokProviderToolKind> = Extract< | ||
| GrokServerTool, | ||
| { type: TKind } | ||
| > & { | ||
| __kind: GrokToolKindMarker<TKind> | ||
| } | ||
|
|
||
| export type GrokResponsesTool = GrokServerTool | ResponsesFunctionTool |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🔴 Critical
🧩 Analysis chain
🌐 Web query:
xAI Grok Responses API server-side tools web_search x_search file_search mcp request format
💡 Result:
The xAI API provides server-side tools—built-in capabilities managed by xAI—that the model executes automatically, alongside user-defined function calling [1][2]. These server-side tools include web_search, x_search, code_interpreter (or code_execution), and file_search (for collections search) [1][3][4][5][6]. API Request Format When using the Responses API (which is compatible with the OpenAI API format), you define these tools within the tools array in your request [1][7][8]. Example Request: curl https://api.x.ai/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $XAI_API_KEY" \ -d '{ "model": "grok-4.3", "tools": [ { "type": "web_search" }, { "type": "x_search" }, { "type": "code_interpreter" }, { "type": "file_search" } ], "input": [ { "role": "user", "content": "Analyze the latest tech trends and perform a calculation." } ] }' Key Tool Details: - Web Search (web_search): Searches the web in real-time [5]. Supports parameters like allowed_domains and enable_image_search [5]. - X Search (x_search): Searches X posts, users, and threads [6]. Supports parameters like from_date, to_date, and enable_video_understanding [6]. - Code Interpreter (code_interpreter/code_execution): Executes Python code in a sandbox [3]. - File Search (file_search/collections_search): Queries your uploaded documents [4]. Requires specifying vector_store_ids or collection_ids [4]. Server-side tools are handled entirely by xAI's infrastructure; the API processes the request, determines which tool to use, executes it, and returns the result to the model [1][2]. This differs from client-side function calling, where the model returns a tool call for your application to execute, requiring you to append the result back to the conversation [2][9]. You can combine both server-side and client-side tools in a single request [2]. Note: The term "MCP" (Model Context Protocol) is not referenced in official xAI documentation as a specific native tool type; xAI documentation distinguishes between built-in server-side tools and custom function calling [1].
Citations:
- 1: https://docs.x.ai/developers/tools/overview
- 2: https://docs.x.ai/developers/tools/advanced-usage
- 3: https://docs.x.ai/developers/tools/code-execution
- 4: https://docs.x.ai/developers/tools/collections-search
- 5: https://docs.x.ai/developers/tools/web-search
- 6: https://docs.x.ai/developers/tools/x-search
- 7: https://docs.x.ai/developers/rest-api-reference/inference/chat
- 8: https://docs.x.ai/developers/quickstart
- 9: https://dev.to/serpapi/grok-ai-api-tutorial-from-chat-to-web-search-32bo
🏁 Script executed:
# Check the adapters/text.ts file to understand how GrokServerTool is processed
cat -n packages/ai-grok/src/adapters/text.ts | sed -n '80,105p'Repository: TanStack/ai
Length of output: 1165
🏁 Script executed:
# Also check the full context of the index.ts file to understand the tool structure better
ast-grep outline packages/ai-grok/src/tools/index.tsRepository: TanStack/ai
Length of output: 1562
🏁 Script executed:
# Search for how GrokMCPToolConfig and MCP tools are used throughout the codebase
rg "GrokMCPToolConfig|mcp" packages/ai-grok/src --type ts -A 3 -B 1Repository: TanStack/ai
Length of output: 2392
🏁 Script executed:
# Check the ResponsesFunctionTool type and how it differs from GrokServerTool
rg "ResponsesFunctionTool" packages/ai-grok/src/tools/index.ts -A 5 -B 2Repository: TanStack/ai
Length of output: 864
🏁 Script executed:
# Check if there's any documentation or comments about MCP usage
rg -i "mcp" packages/ai-grok/src --type ts -B 3 -A 3 | head -80Repository: TanStack/ai
Length of output: 3008
🏁 Script executed:
# Look at how convertToolsToProviderFormat handles these different tool types
ast-grep outline packages/ai-grok/src/tools/index.ts | grep -A 20 "convertToolsToProviderFormat"Repository: TanStack/ai
Length of output: 200
🏁 Script executed:
# Get more context on convertGrokProviderToolToAdapterFormat to see how tools are actually processed
cat -n packages/ai-grok/src/tools/index.ts | sed -n '187,210p'Repository: TanStack/ai
Length of output: 1123
Remove GrokMCPToolConfig from GrokServerTool union or verify xAI Responses API support for MCP tool type.
xAI's Responses API documentation lists native server-side tools as web_search, x_search, code_interpreter, and file_search. The MCP tool type is not referenced in xAI's API documentation as a supported native tool. Since GrokMCPToolConfig (type: 'mcp') is included in the GrokServerTool union and sent verbatim to xAI's API via the cast in adapters/text.ts (Line 92), an unsupported tool type will cause a runtime API error rather than a compile-time type error. Either remove MCP from this union or confirm that xAI Responses API supports custom MCP tools. The other tool configs—field names for web_search (filters.allowed_domains, enable_image_search), x_search (from_date, to_date, enable_video_understanding), and file_search (vector_store_ids)—align with xAI's documentation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/ai-grok/src/tools/index.ts` around lines 18 - 67, The
GrokMCPToolConfig interface is included in the GrokServerTool union type, but
xAI's Responses API documentation only supports web_search, x_search,
code_interpreter, and file_search as native tools, not MCP. Since GrokServerTool
is cast and sent directly to the xAI API, including an unsupported tool type
will cause runtime errors rather than compile-time errors. Remove
GrokMCPToolConfig from the GrokServerTool union type definition to ensure only
documented xAI-supported tool types are sent to the API.
| grok: () => | ||
| createChatOptions({ | ||
| adapter: grokText((model || 'grok-3') as any), | ||
| adapter: grokText((model || 'grok-build-0.1') as any), |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Provider-specific model fallback is unreachable due earlier global default.
At Line 168, model is always initialized to 'gpt-4o', so Line 185 never falls back to 'grok-build-0.1'. This can send an OpenAI model to Grok when the request omits data.model.
Suggested fix
- const model: string = data.model || 'gpt-4o'
+ const model: string | undefined = data.model🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@testing/panel/src/routes/api.chat.ts` at line 185, The global default
assignment of `model` to 'gpt-4o' at line 168 occurs before the
provider-specific fallback at line 185 in the grokText function call, making the
Grok-specific default unreachable. Remove the global default initialization of
`model` at line 168 so that when data.model is not provided, the
provider-specific fallback (grok-build-0.1 for Grok, gpt-4o for OpenAI, etc.)
can be applied correctly based on which adapter is being used.
|
View your CI Pipeline Execution ↗ for commit 97e7190
☁️ Nx Cloud last updated this comment at |
|
View your CI Pipeline Execution ↗ for commit 97e7190
☁️ Nx Cloud last updated this comment at |
@tanstack/ai
@tanstack/ai-angular
@tanstack/ai-anthropic
@tanstack/ai-client
@tanstack/ai-code-mode
@tanstack/ai-code-mode-skills
@tanstack/ai-devtools-core
@tanstack/ai-elevenlabs
@tanstack/ai-event-client
@tanstack/ai-fal
@tanstack/ai-gemini
@tanstack/ai-grok
@tanstack/ai-groq
@tanstack/ai-isolate-cloudflare
@tanstack/ai-isolate-node
@tanstack/ai-isolate-quickjs
@tanstack/ai-mcp
@tanstack/ai-ollama
@tanstack/ai-openai
@tanstack/ai-openrouter
@tanstack/ai-preact
@tanstack/ai-react
@tanstack/ai-react-ui
@tanstack/ai-solid
@tanstack/ai-solid-ui
@tanstack/ai-svelte
@tanstack/ai-utils
@tanstack/ai-vue
@tanstack/ai-vue-ui
@tanstack/openai-base
@tanstack/preact-ai-devtools
@tanstack/react-ai-devtools
@tanstack/solid-ai-devtools
commit: |
2 participants
🎯 Changes
grok-build-0.1andgrok-4.3.grok-build-0.1andgrok-4.3.✅ Checklist
pnpm run test:pr.🚀 Release Impact
Test plan
pnpm --filter @tanstack/ai-grok test:typespnpm --filter @tanstack/ai-grok test:libpnpm --filter @tanstack/ai-grok test:eslintpnpm --filter @tanstack/ai-grok buildpnpm test:prSummary by CodeRabbit
New Features
grok-4.3andgrok-build-0.1Documentation