Repository Public
1<!-- source: https://docs.x.ai/developers/tools/function-calling (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Tools34# Function Calling56Define custom tools that the model can invoke during a conversation. The model requests the call, you execute it locally, and return the result. This enables integration with databases, APIs, and any external system.78> [!WARNING]9>10> With streaming, the function call is returned in whole in a single chunk, not streamed across chunks.11121. Define tools with a name, description, and JSON schema for parameters132. Include tools in your request143. Model returns a `tool_call` when it needs external data154. Execute the function locally and return the result165. Model continues with your result1718## Quick Start1920```bash customLanguage="bash"21curl https://api.x.ai/v1/responses \22 -H "Content-Type: application/json" \23 -H "Authorization: Bearer $XAI_API_KEY" \24 -d '{25 "model": "grok-4.6",26 "input": [27 {"role": "user", "content": "What is the temperature in San Francisco?"}28 ],29 "tools": [30 {31 "type": "function",32 "name": "get_temperature",33 "description": "Get current temperature for a location",34 "parameters": {35 "type": "object",36 "properties": {37 "location": {"type": "string", "description": "City name"},38 "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "fahrenheit"}39 },40 "required": ["location"]41 }42 }43 ]44}'45```4647```pythonXAI48import os49import json5051from xai_sdk import Client52from xai_sdk.chat import user, tool, tool_result5354client = Client(api_key=os.getenv("XAI_API_KEY"))5556# Define tools57tools = [58 tool(59 name="get_temperature",60 description="Get current temperature for a location",61 parameters={62 "type": "object",63 "properties": {64 "location": {"type": "string", "description": "City name"},65 "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "fahrenheit"}66 },67 "required": ["location"]68 },69 ),70]7172chat = client.chat.create(73 model="grok-4.6",74 tools=tools,75)76chat.append(user("What is the temperature in San Francisco?"))77response = chat.sample()7879# Handle tool calls80if response.tool_calls:81 chat.append(response)82 for tc in response.tool_calls:83 args = json.loads(tc.function.arguments)84 # Execute your function85 result = {"location": args["location"], "temperature": 59, "unit": args.get("unit", "fahrenheit")}86 chat.append(tool_result(json.dumps(result)))8788 response = chat.sample()8990print(response.content)91```9293```pythonOpenAISDK94import os95import json96from openai import OpenAI9798client = OpenAI(99 api_key=os.getenv("XAI_API_KEY"),100 base_url="https://api.x.ai/v1",101)102103tools = [104 {105 "type": "function",106 "name": "get_temperature",107 "description": "Get current temperature for a location",108 "parameters": {109 "type": "object",110 "properties": {111 "location": {"type": "string", "description": "City name"},112 "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "fahrenheit"}113 },114 "required": ["location"]115 },116 },117]118119response = client.responses.create(120 model="grok-4.6",121 input=[{"role": "user", "content": "What is the temperature in San Francisco?"}],122 tools=tools,123)124125# Handle function calls126for item in response.output:127 if item.type == "function_call":128 args = json.loads(item.arguments)129 result = {"location": args["location"], "temperature": 59, "unit": args.get("unit", "fahrenheit")}130131 response = client.responses.create(132 model="grok-4.6",133 input=[{"type": "function_call_output", "call_id": item.call_id, "output": json.dumps(result)}],134 tools=tools,135 previous_response_id=response.id,136 )137138for item in response.output:139 if item.type == "message":140 print(item.content[0].text)141```142143```javascriptAISDK144import { xai } from '@ai-sdk/xai';145import { streamText, tool, stepCountIs } from 'ai';146import { z } from 'zod';147148const result = streamText({149 model: xai.responses('grok-4.6'),150 tools: {151 getTemperature: tool({152 description: 'Get current temperature for a location',153 inputSchema: z.object({154 location: z.string().describe('City name'),155 unit: z.enum(['celsius', 'fahrenheit']).default('fahrenheit'),156 }),157 execute: async ({ location, unit }) => ({158 location,159 temperature: unit === 'fahrenheit' ? 59 : 15,160 unit,161 }),162 }),163 },164 stopWhen: stepCountIs(5),165 prompt: 'What is the temperature in San Francisco?',166});167168for await (const chunk of result.fullStream) {169 if (chunk.type === 'text-delta') {170 process.stdout.write(chunk.text);171 }172}173```174175## Defining Tools with Pydantic176177Use Pydantic models for type-safe parameter schemas:178179```pythonXAI180from typing import Literal181from pydantic import BaseModel, Field182from xai_sdk.chat import tool183184class TemperatureRequest(BaseModel):185 location: str = Field(description="City and state, e.g. San Francisco, CA")186 unit: Literal["celsius", "fahrenheit"] = Field("fahrenheit", description="Temperature unit")187188class CeilingRequest(BaseModel):189 location: str = Field(description="City and state, e.g. San Francisco, CA")190191# Generate JSON schema from Pydantic models192tools = [193 tool(194 name="get_temperature",195 description="Get current temperature for a location",196 parameters=TemperatureRequest.model_json_schema(),197 ),198 tool(199 name="get_ceiling",200 description="Get current cloud ceiling for a location",201 parameters=CeilingRequest.model_json_schema(),202 ),203]204```205206```pythonOpenAISDK207from typing import Literal208from pydantic import BaseModel, Field209210class TemperatureRequest(BaseModel):211 location: str = Field(description="City and state, e.g. San Francisco, CA")212 unit: Literal["celsius", "fahrenheit"] = Field("fahrenheit", description="Temperature unit")213214class CeilingRequest(BaseModel):215 location: str = Field(description="City and state, e.g. San Francisco, CA")216217tools = [218 {219 "type": "function",220 "name": "get_temperature",221 "description": "Get current temperature for a location",222 "parameters": TemperatureRequest.model_json_schema(),223 },224 {225 "type": "function",226 "name": "get_ceiling",227 "description": "Get current cloud ceiling for a location",228 "parameters": CeilingRequest.model_json_schema(),229 },230]231```232233## Handling Tool Calls234235When the model wants to use your tool, execute the function and return the result:236237```pythonXAI238import json239240def get_temperature(location: str, unit: str = "fahrenheit") -> dict:241 # In production, call a real weather API242 temp = 59 if unit == "fahrenheit" else 15243 return {"location": location, "temperature": temp, "unit": unit}244245def get_ceiling(location: str) -> dict:246 return {"location": location, "ceiling": 15000, "unit": "ft"}247248tools_map = {249 "get_temperature": get_temperature,250 "get_ceiling": get_ceiling,251}252253chat.append(user("What's the weather in Denver?"))254response = chat.sample()255256# Process tool calls257if response.tool_calls:258 chat.append(response)259260 for tool_call in response.tool_calls:261 name = tool_call.function.name262 args = json.loads(tool_call.function.arguments)263264 result = tools_map[name](**args)265 chat.append(tool_result(json.dumps(result)))266267 response = chat.sample()268269print(response.content)270```271272```pythonOpenAISDK273import json274275def get_temperature(location: str, unit: str = "fahrenheit") -> dict:276 temp = 59 if unit == "fahrenheit" else 15277 return {"location": location, "temperature": temp, "unit": unit}278279tools_map = {"get_temperature": get_temperature}280281# Process function calls282for item in response.output:283 if item.type == "function_call":284 name = item.name285 args = json.loads(item.arguments)286287 if name not in tools_map:288 output = json.dumps({"error": f"Unknown function: {name}"})289 else:290 output = json.dumps(tools_map[name](**args))291292 response = client.responses.create(293 model="grok-4.6",294 input=[{"type": "function_call_output", "call_id": item.call_id, "output": output}],295 tools=tools,296 previous_response_id=response.id,297 )298299for item in response.output:300 if item.type == "message":301 print(item.content[0].text)302```303304## Combining with Built-in Tools305306Function calling works alongside built-in agentic tools. The model can use web search, then call your custom function:307308```pythonXAI309from xai_sdk.chat import tool310from xai_sdk.tools import web_search, x_search311312tools = [313 web_search(), # Built-in: runs on xAI servers314 x_search(), # Built-in: runs on xAI servers315 tool( # Custom: runs on your side316 name="save_to_database",317 description="Save research results to the database",318 parameters={319 "type": "object",320 "properties": {321 "data": {"type": "string", "description": "Data to save"}322 },323 "required": ["data"]324 },325 ),326]327328chat = client.chat.create(329 model="grok-4.6",330 tools=tools,331)332```333334```pythonOpenAISDK335tools = [336 {"type": "web_search"}, # Built-in337 {"type": "x_search"}, # Built-in338 { # Custom339 "type": "function",340 "name": "save_to_database",341 "description": "Save research results to the database",342 "parameters": {343 "type": "object",344 "properties": {345 "data": {"type": "string", "description": "Data to save"}346 },347 "required": ["data"]348 },349 },350]351```352353When mixing tools:354355* **Built-in tools** execute automatically on xAI servers356* **Custom tools** pause execution and return to you for handling357358See [Advanced Usage](/developers/tools/advanced-usage#mixing-server-side-and-client-side-tools) for complete examples with tool loops.359360## Tool Choice361362Control when the model uses tools:363364| Value | Behavior |365|-------|----------|366| `"auto"` | Model decides whether to call a tool (default) |367| `"required"` | Model must call at least one tool |368| `"none"` | Disable tool calling |369| `{"type": "function", "function": {"name": "..."}}` | Force a specific tool |370371## Parallel Function Calling372373By default, parallel function calling is enabled — the model can request multiple tool calls in a single response. Process all of them before continuing:374375```pythonWithoutSDK376# response.tool_calls may contain multiple calls377for tool_call in response.tool_calls:378 result = tools_map[tool_call.function.name](**json.loads(tool_call.function.arguments))379 # Append each result...380```381382Disable with `parallel_tool_calls: false` in your request.383384## Tool Schema Reference385386| Field | Required | Description |387|-------|----------|-------------|388| `name` | Yes | Unique identifier (max 350 tools per request) |389| `description` | Yes | What the tool does — helps the model decide when to use it |390| `parameters` | Yes | JSON Schema defining function inputs |391392### Parameter Schema393394```json395{396 "type": "object",397 "properties": {398 "location": {399 "type": "string",400 "description": "City name"401 },402 "unit": {403 "type": "string",404 "enum": ["celsius", "fahrenheit"],405 "default": "celsius"406 }407 },408 "required": ["location"]409}410```411412The root of a `parameters` schema must be an object (`"type": "object"`); nest any other types inside `properties`. A root `anyOf` or `oneOf` also works when every branch is itself an object, letting you define a tool that accepts one of several object variants:413414```json415{416 "oneOf": [417 {418 "type": "object",419 "properties": {420 "kind": { "const": "email" },421 "address": { "type": "string" }422 },423 "required": ["kind", "address"]424 },425 {426 "type": "object",427 "properties": {428 "kind": { "const": "sms" },429 "phone": { "type": "string" }430 },431 "required": ["kind", "phone"]432 }433 ]434}435```436437> [!WARNING]438>439> A tool whose `parameters` root is neither an object nor a union of objects (for example, a scalar, an array, or an `anyOf`/`oneOf` with a non-object branch) cannot be compiled into a tool-call grammar and is rejected with a `400` error that names the tool.440441## Complete Vercel AI SDK Example442443The Vercel AI SDK handles tool definition, execution, and the request/response loop automatically:444445```javascriptAISDK446import { xai } from '@ai-sdk/xai';447import { streamText, tool, stepCountIs } from 'ai';448import { z } from 'zod';449450const result = streamText({451 model: xai.responses('grok-4.6'),452 tools: {453 getCurrentTemperature: tool({454 description: 'Get current temperature for a location',455 inputSchema: z.object({456 location: z.string().describe('City and state, e.g. San Francisco, CA'),457 unit: z.enum(['celsius', 'fahrenheit']).default('fahrenheit'),458 }),459 execute: async ({ location, unit }) => ({460 location,461 temperature: unit === 'fahrenheit' ? 59 : 15,462 unit,463 }),464 }),465 getCurrentCeiling: tool({466 description: 'Get current cloud ceiling for a location',467 inputSchema: z.object({468 location: z.string().describe('City and state'),469 }),470 execute: async ({ location }) => ({471 location,472 ceiling: 15000,473 ceiling_type: 'broken',474 unit: 'ft',475 }),476 }),477 },478 stopWhen: stepCountIs(5),479 prompt: "What's the temperature and cloud ceiling in San Francisco?",480});481482for await (const chunk of result.fullStream) {483 switch (chunk.type) {484 case 'text-delta':485 process.stdout.write(chunk.text);486 break;487 case 'tool-call':488 console.log(`Tool call: ${chunk.toolName}`, chunk.input);489 break;490 case 'tool-result':491 console.log(`Tool result: ${chunk.toolName}`, chunk.output);492 break;493 }494}495```496