SPB Git

Repository Public

advanced-usage.md 26.5 KB 798 lines markdown

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> &#x20;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
Files main
Menu

Theme