Repository Public
1<!-- source: https://docs.x.ai/developers/tools/advanced-usage (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Tools34# Advanced Usage56In this section, we explore advanced usage patterns for agentic tool calling, including:78* **[Use Client-side Tools](#mixing-server-side-and-client-side-tools)** - Combine server-side agentic tools with your own client-side tools for specialized functionality that requires local execution.9* **[Multi-turn Conversations](#multi-turn-conversations-with-preservation-of-agentic-state)** - Maintain context across multiple turns in agentic tool-enabled conversations, allowing the model to build upon previous research and tool results for more complex, iterative problem-solving10* **[Requests with Multiple Active Tools](#tool-combinations)** - Send requests with multiple server-side tools active simultaneously, enabling comprehensive analysis with web search, X search, and code execution tools working together11* **[Image Integration](#using-images-in-the-context)** - Include images in your tool-enabled conversations for visual analysis and context-aware searches1213> [!NOTE]14>15>  Advanced tool usage patterns are not yet supported in the Vercel AI SDK. Please use the xAI SDK or OpenAI SDK for this functionality.1617## Mixing Server-Side and Client-Side Tools1819You can combine server-side agentic tools (like web search and code execution) with custom client-side tools to create powerful hybrid workflows. This approach lets you leverage the model's reasoning capabilities with server-side tools while adding specialized functionality that runs locally in your application.2021### How It Works2223The key difference when mixing server-side and client-side tools is that **server-side tools are executed automatically by xAI**, while **client-side tools require developer intervention**:24251. Define your client-side tools using [standard function calling patterns](/developers/tools/function-calling)262. Include both server-side and client-side tools in your request273. **xAI automatically executes any server-side tools** the model decides to use (web search, code execution, etc.)284. **When the model calls client-side tools, execution pauses** - xAI returns the tool calls to you instead of executing them295. **Detect and execute client-side tool calls yourself**, then append the results back to continue the conversation306. **Repeat this process** until the model generates a final response with no additional client-side tool calls3132### Understanding `max_turns` with Client-Side Tools3334When using [the `max_turns` parameter](/developers/tools/tool-usage-details#limiting-tool-call-turns) with mixed server-side and client-side tools, it's important to understand that **`max_turns` only limits the assistant/server-side tool call turns within a single request**.3536When the model decides to invoke a client-side tool, the agent execution **pauses and yields control back to your application**. This means:3738* The current request completes, and you receive the client-side tool call(s) to execute39* After you execute the client-side tool and append the result, you make a **new follow-up request**40* This follow-up request starts with a fresh `max_turns` count4142In other words, client-side tool invocations act as "checkpoints" that reset the turn counter. If you set `max_turns=5` and the agent performs 3 server-side tool calls before requesting a client-side tool, the subsequent request (after you provide the client-side tool result) will again allow up to 5 server-side tool turns.4344### Practical Example4546Given a local client-side function `get_weather` to get the weather of a specified city, the model can use this client-side tool and the web-search tool to determine the weather in the base city of the 2025 NBA champion.4748### Using the xAI SDK4950You can determine whether a tool call is a client-side tool call by using `xai_sdk.tools.get_tool_call_type` against a tool call from the `response.tool_calls` list.51For more details, check [Identifying Tool Call Types](/developers/tools/tool-usage-details#identifying-tool-call-types).52531. Import the dependencies, and define the client-side tool.5455 ```pythonXAI56 import os57 import json5859 from xai_sdk import Client60 from xai_sdk.chat import user, tool, tool_result61 from xai_sdk.tools import web_search, get_tool_call_type6263 client = Client(api_key=os.getenv("XAI_API_KEY"))6465 # Define client-side tool66 def get_weather(city: str) -> str:67 """Get the weather for a given city."""68 # In a real app, this would query your database69 return f"The weather in {city} is sunny."7071 # Tools array with both server-side and client-side tools72 tools = [73 web_search(),74 tool(75 name="get_weather",76 description="Get the weather for a given city.",77 parameters={78 "type": "object",79 "properties": {80 "city": {81 "type": "string",82 "description": "The name of the city",83 }84 },85 "required": ["city"]86 },87 ),88 ]8990 model = "grok-4.6"91 ```92932. Perform the tool loop with conversation continuation:94 * You can either use `previous_response_id` to continue the conversation from the last response.9596 ```pythonXAI97 # Create chat with both server-side and client-side tools98 chat = client.chat.create(99 model=model,100 tools=tools,101 store_messages=True,102 )103 chat.append(104 user(105 "What is the weather in the base city of the team that won the "106 "2025 NBA championship?"107 )108 )109110 while True:111 client_side_tool_calls = []112 for response, chunk in chat.stream():113 for tool_call in chunk.tool_calls:114 if get_tool_call_type(tool_call) == "client_side_tool":115 client_side_tool_calls.append(tool_call)116 else:117 print(118 f"Server-side tool call: {tool_call.function.name} "119 f"with arguments: {tool_call.function.arguments}"120 )121122 if not client_side_tool_calls:123 break124125 chat = client.chat.create(126 model=model,127 tools=tools,128 store_messages=True,129 previous_response_id=response.id,130 )131132 for tool_call in client_side_tool_calls:133 print(134 f"Client-side tool call: {tool_call.function.name} "135 f"with arguments: {tool_call.function.arguments}"136 )137 args = json.loads(tool_call.function.arguments)138 result = get_weather(args["city"])139 chat.append(tool_result(result))140141 print(f"Final response: {response.content}")142 ```143144 * Alternatively, you can use the encrypted content to continue the conversation.145146 ```pythonXAI147 # Create chat with both server-side and client-side tools148 chat = client.chat.create(149 model=model,150 tools=tools,151 use_encrypted_content=True,152 )153 chat.append(154 user(155 "What is the weather in the base city of the team that won the "156 "2025 NBA championship?"157 )158 )159160 while True:161 client_side_tool_calls = []162 for response, chunk in chat.stream():163 for tool_call in chunk.tool_calls:164 if get_tool_call_type(tool_call) == "client_side_tool":165 client_side_tool_calls.append(tool_call)166 else:167 print(168 f"Server-side tool call: {tool_call.function.name} "169 f"with arguments: {tool_call.function.arguments}"170 )171172 chat.append(response)173174 if not client_side_tool_calls:175 break176177 for tool_call in client_side_tool_calls:178 print(179 f"Client-side tool call: {tool_call.function.name} "180 f"with arguments: {tool_call.function.arguments}"181 )182 args = json.loads(tool_call.function.arguments)183 result = get_weather(args["city"])184 chat.append(tool_result(result))185186 print(f"Final response: {response.content}")187 ```188189You will see an output similar to the following:190191```192Server-side tool call: web_search with arguments: {"query":"Who won the 2025 NBA championship?","num_results":5}193Client-side tool call: get_weather with arguments: {"city":"Oklahoma City"}194Final response: The Oklahoma City Thunder won the 2025 NBA championship. The current weather in Oklahoma City is sunny.195```196197### Using the OpenAI SDK198199You can determine whether a tool call is a client-side tool call by checking the `type` field of an output entry from the `response.output` list.200For more details, see [Identifying Tool Call Types](/developers/tools/tool-usage-details#identifying-tool-call-types).2012021. Import the dependencies, and define the client-side tool.203204 ```pythonOpenAISDK205 import os206 import json207208 from openai import OpenAI209210 client = OpenAI(211 api_key=os.getenv("XAI_API_KEY"),212 base_url="https://api.x.ai/v1",213 )214215 # Define client-side tool216 def get_weather(city: str) -> str:217 """Get the weather for a given city."""218 # In a real app, this would query your database219 return f"The weather in {city} is sunny."220221 model = "grok-4.6"222 tools = [223 {224 "type": "function",225 "name": "get_weather",226 "description": "Get the weather for a given city.",227 "parameters": {228 "type": "object",229 "properties": {230 "city": {231 "type": "string",232 "description": "The name of the city",233 },234 },235 "required": ["city"],236 },237 },238 {239 "type": "web_search",240 },241 ]242 ```2432442. Perform the tool loop:245246 * You can either use `previous_response_id`.247248 ```pythonOpenAISDK249 response = client.responses.create(250 model=model,251 input=(252 "What is the weather in the base city of the team that won the "253 "2025 NBA championship?"254 ),255 tools=tools,256 )257258 while True:259 tool_outputs = []260 for item in response.output:261 if item.type == "function_call":262 print(f"Client-side tool call: {item.name} with arguments: {item.arguments}")263 args = json.loads(item.arguments)264 weather = get_weather(args["city"])265 tool_outputs.append(266 {267 "type": "function_call_output",268 "call_id": item.call_id,269 "output": weather,270 }271 )272 elif item.type in (273 "web_search_call",274 "x_search_call",275 "code_interpreter_call",276 "file_search_call",277 "mcp_call",278 ):279 # Server-side items expose type-specific fields (e.g. action),280 # not name/arguments like client-side function_call items.281 details = getattr(item, "action", None) or item.model_dump(282 exclude={"id", "type", "status"}, exclude_none=True283 )284 print(f"Server-side tool call: {item.type} {details}")285286 if not tool_outputs:287 break288289 response = client.responses.create(290 model=model,291 tools=tools,292 input=tool_outputs,293 previous_response_id=response.id,294 )295296 print("Final response:", response.output[-1].content[0].text)297 ```298299 * or using the encrypted content300301 ```pythonOpenAISDK302 input_list = [303 {304 "role": "user",305 "content": (306 "What is the weather in the base city of the team that won the "307 "2025 NBA championship?"308 ),309 }310 ]311312 response = client.responses.create(313 model=model,314 input=input_list,315 tools=tools,316 include=["reasoning.encrypted_content"],317 )318319 while True:320 input_list.extend(response.output)321 tool_outputs = []322 for item in response.output:323 if item.type == "function_call":324 print(f"Client-side tool call: {item.name} with arguments: {item.arguments}")325 args = json.loads(item.arguments)326 weather = get_weather(args["city"])327 tool_outputs.append(328 {329 "type": "function_call_output",330 "call_id": item.call_id,331 "output": weather,332 }333 )334 elif item.type in (335 "web_search_call",336 "x_search_call",337 "code_interpreter_call",338 "file_search_call",339 "mcp_call",340 ):341 # Server-side items expose type-specific fields (e.g. action),342 # not name/arguments like client-side function_call items.343 details = getattr(item, "action", None) or item.model_dump(344 exclude={"id", "type", "status"}, exclude_none=True345 )346 print(f"Server-side tool call: {item.type} {details}")347348 if not tool_outputs:349 break350351 input_list.extend(tool_outputs)352 response = client.responses.create(353 model=model,354 input=input_list,355 tools=tools,356 include=["reasoning.encrypted_content"],357 )358359 print("Final response:", response.output[-1].content[0].text)360 ```361362## Multi-turn Conversations with Preservation of Agentic State363364When using agentic tools, you may want multi-turn conversations where follow-up prompts maintain all agentic state, including the full history of reasoning, tool calls, and tool responses. The stateful API makes this possible by preserving conversation context across multiple interactions. Two options are outlined below.365366### Store the Conversation History Remotely367368You can choose to store the conversation history remotely on the xAI server, and every time you want to continue the conversation, you can pick up from the last response where you want to resume from.369370There are only 2 extra steps:3713721. Add the parameter `store_messages=True` when making the first agentic request. This tells the service to store the entire conversation history on xAI servers, including the model's reasoning, server-side tool calls, and corresponding responses.3732. Pass `previous_response_id=response.id` when creating the follow-up conversation, where `response` is the response returned by `chat.sample()` or `chat.stream()` from the conversation that you wish to continue.374375Note that the follow-up conversation does not need to use the same tools, model parameters, or any other configuration as the initial conversation—it will still be fully hydrated with the complete agentic state from the previous interaction.376377```pythonXAI378import os379380from xai_sdk import Client381from xai_sdk.chat import user382from xai_sdk.tools import web_search, x_search383client = Client(api_key=os.getenv("XAI_API_KEY"))384# First turn.385chat = client.chat.create(386 model="grok-4.6", # reasoning model387 tools=[web_search(), x_search()],388 store_messages=True,389)390chat.append(user("What is xAI?"))391print("\\n\\n##### First turn #####\\n")392for response, chunk in chat.stream():393 print(chunk.content, end="", flush=True)394print("\\n\\nUsage for first turn:", response.server_side_tool_usage)395396# Second turn.397chat = client.chat.create(398 model="grok-4.6", # reasoning model399 tools=[web_search(), x_search()],400 # pass the response id of the first turn to continue the conversation401 previous_response_id=response.id,402)403404chat.append(user("What is its latest mission?"))405print("\\n\\n##### Second turn #####\\n")406for response, chunk in chat.stream():407 print(chunk.content, end="", flush=True)408print("\\n\\nUsage for second turn:", response.server_side_tool_usage)409```410411### Append the Encrypted Agentic Tool Calling States412413There is another option for the ZDR (Zero Data Retention) users, or the users who don't want to use the above option, that is to let the xAI server also return414the encrypted reasoning and the encrypted tool output besides the final content to the client side, and those encrypted contents can be included as a part of the context415in the next turn conversation.416417Here are the extra steps you need to take for this option:4184191. Add the parameter `use_encrypted_content=True` when making the first agentic request. This tells the service to return the entire conversation history to the client side, including the model's reasoning (encrypted), server-side tool calls, and corresponding responses (encrypted).4202. Append the response to the conversation you wish to continue before making the call to `chat.sample()` or `chat.stream()`.421422```pythonXAI423import os424425from xai_sdk import Client426from xai_sdk.chat import user427from xai_sdk.tools import web_search, x_search428client = Client(api_key=os.getenv("XAI_API_KEY"))429# First turn.430chat = client.chat.create(431 model="grok-4.6", # reasoning model432 tools=[web_search(), x_search()],433 use_encrypted_content=True,434)435chat.append(user("What is xAI?"))436print("\\n\\n##### First turn #####\\n")437for response, chunk in chat.stream():438 print(chunk.content, end="", flush=True)439print("\\n\\nUsage for first turn:", response.server_side_tool_usage)440441chat.append(response)442443print("\\n\\n##### Second turn #####\\n")444chat.append(user("What is its latest mission?"))445# Second turn.446for response, chunk in chat.stream():447 print(chunk.content, end="", flush=True)448print("\\n\\nUsage for second turn:", response.server_side_tool_usage)449```450451For more details about stateful responses, please check out [this guide](/developers/model-capabilities/text/generate-text).452453## Tool Combinations454455Equipping your requests with multiple tools is straightforward—simply include the tools you want to activate in the `tools` array of your request. The model will intelligently orchestrate between them based on the task at hand.456457### Suggested Tool Combinations458459Here are some common patterns for combining tools, depending on your use case:460461| If you're trying to... | Consider activating... | Because... |462|------------------------|----------------------|------------|463| **Research & analyze data** | Web Search + Code Execution | Web search gathers information, code execution analyzes and visualizes it |464| **Aggregate news & social media** | Web Search + X Search | Get comprehensive coverage from both traditional web and social platforms |465| **Extract insights from multiple sources** | Web Search + X Search + Code Execution | Collect data from various sources then compute correlations and trends |466| **Monitor real-time discussions** | X Search + Web Search | Track social sentiment alongside authoritative information |467468```pythonXAI469from xai_sdk.tools import web_search, x_search, code_execution470471# Example tool combinations for different scenarios472research_setup = [web_search(), code_execution()]473news_setup = [web_search(), x_search()]474comprehensive_setup = [web_search(), x_search(), code_execution()]475```476477```pythonWithoutSDK478research_setup = {479 "tools": [480 {"type": "web_search"},481 {"type": "code_interpreter"}482 ]483}484485news_setup = {486 "tools": [487 {"type": "web_search"},488 {"type": "x_search"}489 ]490}491492comprehensive_setup = {493 "tools": [494 {"type": "web_search"},495 {"type": "x_search"},496 {"type": "code_interpreter"}497 ]498}499```500501### Using Tool Combinations in Different Scenarios5025031. When you want to search for news on the Internet, you can activate all search tools:504 * Web search tool505 * X search tool506507```pythonXAI508import os509510from xai_sdk import Client511from xai_sdk.chat import user512from xai_sdk.tools import web_search, x_search513514client = Client(api_key=os.getenv("XAI_API_KEY"))515chat = client.chat.create(516 model="grok-4.6", # reasoning model517 tools=[518 web_search(),519 x_search(),520 ],521 include=["verbose_streaming"],522)523524chat.append(user("what is the latest update from xAI?"))525526is_thinking = True527for response, chunk in chat.stream():528 # View the server-side tool calls as they are being made in real-time529 for tool_call in chunk.tool_calls:530 print(f"\\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")531 if response.usage.reasoning_tokens and is_thinking:532 print(f"\\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)533 if chunk.content and is_thinking:534 print("\\n\\nFinal Response:")535 is_thinking = False536 if chunk.content and not is_thinking:537 print(chunk.content, end="", flush=True)538539print("\\n\\nCitations:")540print(response.citations)541print("\\n\\nUsage:")542print(response.usage)543print(response.server_side_tool_usage)544print("\\n\\nServer Side Tool Calls:")545print(response.tool_calls)546```547548```pythonOpenAISDK549import os550from openai import OpenAI551552api_key = os.getenv("XAI_API_KEY")553client = OpenAI(554 api_key=api_key,555 base_url="https://api.x.ai/v1",556)557558response = client.responses.create(559 model="grok-4.6",560 input=[561 {562 "role": "user",563 "content": "what is the latest update from xAI?",564 },565 ],566 tools=[567 {568 "type": "web_search",569 },570 {571 "type": "x_search",572 },573 ],574)575576print(response)577```578579```pythonRequests580import os581import requests582583url = "https://api.x.ai/v1/responses"584headers = {585 "Content-Type": "application/json",586 "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"587}588payload = {589 "model": "grok-4.6",590 "input": [591 {592 "role": "user",593 "content": "what is the latest update from xAI?"594 }595 ],596 "tools": [597 {598 "type": "web_search",599 },600 {601 "type": "x_search",602 }603 ]604}605response = requests.post(url, headers=headers, json=payload)606print(response.json())607```608609```bash610curl https://api.x.ai/v1/responses \\611 -H "Content-Type: application/json" \\612 -H "Authorization: Bearer $XAI_API_KEY" \\613 -d '{614 "model": "grok-4.6",615 "input": [616 {617 "role": "user",618 "content": "What is the latest update from xAI?"619 }620 ],621 "tools": [622 {623 "type": "web_search"624 },625 {626 "type": "x_search"627 }628 ]629}'630```6316322. When you want to collect up-to-date data from the Internet and perform calculations based on the Internet data, you can choose to activate:633 * Web search tool634 * Code execution tool635636```pythonXAI637import os638639from xai_sdk import Client640from xai_sdk.chat import user641from xai_sdk.tools import web_search, code_execution642643client = Client(api_key=os.getenv("XAI_API_KEY"))644chat = client.chat.create(645 model="grok-4.6", # reasoning model646 # research_tools647 tools=[648 web_search(),649 code_execution(),650 ],651 include=["verbose_streaming"],652)653654chat.append(user("What is the average market cap of the companies with the top 5 market cap in the US stock market today?"))655656# sample or stream the response...657```658659```pythonOpenAISDK660import os661from openai import OpenAI662663api_key = os.getenv("XAI_API_KEY")664client = OpenAI(665 api_key=api_key,666 base_url="https://api.x.ai/v1",667)668669response = client.responses.create(670 model="grok-4.6",671 input=[672 {673 "role": "user",674 "content": "What is the average market cap of the companies with the top 5 market cap in the US stock market today?",675 },676 ],677 # research_tools678 tools=[679 {680 "type": "web_search",681 },682 {683 "type": "code_interpreter",684 },685 ],686)687688print(response)689```690691```pythonRequests692import os693import requests694695url = "https://api.x.ai/v1/responses"696headers = {697 "Content-Type": "application/json",698 "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"699}700payload = {701 "model": "grok-4.6",702 "input": [703 {704 "role": "user",705 "content": "What is the average market cap of the companies with the top 5 market cap in the US stock market today?"706 }707 ],708 # research_tools709 "tools": [710 {711 "type": "web_search",712 },713 {714 "type": "code_interpreter",715 },716 ]717}718response = requests.post(url, headers=headers, json=payload)719print(response.json())720```721722```bash723curl https://api.x.ai/v1/responses \\724 -H "Content-Type: application/json" \\725 -H "Authorization: Bearer $XAI_API_KEY" \\726 -d '{727 "model": "grok-4.6",728 "input": [729 {730 "role": "user",731 "content": "What is the average market cap of the companies with the top 5 market cap in the US stock market today?"732 }733 ],734 "tools": [735 {736 "type": "web_search"737 },738 {739 "type": "code_interpreter"740 }741 ]742}'743```744745## Using Images in the Context746747You can bootstrap your requests with an initial conversation context that includes images.748749In the code sample below, we pass an image into the context of the conversation before initiating an agentic request.750751```pythonXAI752import os753754from xai_sdk import Client755from xai_sdk.chat import image, user756from xai_sdk.tools import web_search, x_search757758# Create the client and define the server-side tools to use759client = Client(api_key=os.getenv("XAI_API_KEY"))760chat = client.chat.create(761 model="grok-4.6", # reasoning model762 tools=[web_search(), x_search()],763 include=["verbose_streaming"],764)765766# Add an image to the conversation767chat.append(768 user(769 "Search the internet and tell me what kind of dog is in the image below.",770 "And what is the typical lifespan of this dog breed?",771 image(772 "https://pbs.twimg.com/media/G3B7SweXsAAgv5N?format=jpg&name=900x900"773 ),774 )775)776777is_thinking = True778for response, chunk in chat.stream():779 # View the server-side tool calls as they are being made in real-time780 for tool_call in chunk.tool_calls:781 print(f"\\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")782 if response.usage.reasoning_tokens and is_thinking:783 print(f"\\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)784 if chunk.content and is_thinking:785 print("\\n\\nFinal Response:")786 is_thinking = False787 if chunk.content and not is_thinking:788 print(chunk.content, end="", flush=True)789790print("\\n\\nCitations:")791print(response.citations)792print("\\n\\nUsage:")793print(response.usage)794print(response.server_side_tool_usage)795print("\\n\\nServer Side Tool Calls:")796print(response.tool_calls)797```798