SPB Git

Repository Public

function-calling.md 13.9 KB 496 lines markdown

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
Files main
Menu

Theme