# The xAI agentic tool loop — server-side tools, client-side functions, state, `max_turns`

**Status:** `DOCUMENTED` + `LIVE_VERIFIED` (2026-09-19, grok-4.3: Responses function_call → function_call_output via previous_response_id; server tools web_search / x_search / code_interpreter / mcp / file_search inside single requests; Chat Completions function round trip).

**Sources:** https://docs.x.ai/developers/tools/overview · https://docs.x.ai/developers/tools/advanced-usage · https://docs.x.ai/developers/tools/tool-usage-details · https://docs.x.ai/developers/tools/streaming-and-sync · https://docs.x.ai/developers/tools/function-calling
**Last verified:** 2026-09-19

## 1. Who executes what (Responses API)

| `output[]` item type | Executed by | You send back |
|---|---|---|
| `function_call` | you | `{type:"function_call_output", call_id, output}` |
| `shell_call` (tool `shell`, env local) | you | `shell_call_output {call_id, output:[{stdout, stderr, outcome}]}` |
| `web_search_call`, `custom_tool_call` (x_search sub-tools), `code_interpreter_call`, `file_search_call`, `mcp_call`, `image_generation_call`, `tool_search_call/output` | xAI (server side, inside the same request) | nothing |

Stop when a response contains no client-side calls (normally it ends with a `message`). There is **no approval step** for MCP (`require_approval` ignored).

## 2. Loop with `previous_response_id` (verified)
```python
resp = client.responses.create(model="grok-4.3", input="…", tools=tools)
while True:
    outs = [{"type":"function_call_output","call_id":i.call_id,"output":run(i)} for i in resp.output if i.type == "function_call"]
    if not outs: break
    resp = client.responses.create(model="grok-4.3", tools=tools, input=outs, previous_response_id=resp.id)
```
Server keeps reasoning, server-tool calls and their outputs. Follow-ups may use different tools/params.

## 3. Loop with encrypted state (ZDR / `store:false`)
Request `include:["reasoning.encrypted_content"]`, keep an `input_list`, `input_list.extend(resp.output)` then append your `function_call_output` items and resend everything (`store:false` allowed). Verified: replayed reasoning + message items → 200.

## 4. Turns, limits, billing
- `max_turns` bounds assistant/server-tool turns **within one request**; a client-side call ends the request, and the follow-up request gets a fresh budget. Default = server cap. Recommended 1–2 quick, 3–5 balanced, 10+ deep.
- One turn may run several tools in parallel; `parallel_tool_calls:false` limits to one call.
- Billing: only **successful** server-tool executions count (`usage.server_side_tool_usage_details.*_calls`, `num_server_side_tools_used`) — failed attempts (e.g. `file_search_call status:"failed"`) are free; tokens for every intermediate step are billed (`input_tokens` is cumulative across steps, heavily cached: 7 467 input / 704 cached on a one-search request). Prices: web_search $5/1k, x_search $5/1k (→ per-post/profile pricing from 2026-09-21), code_interpreter $5/1k, file_search $2.50/1k, attachment search $10/1k, MCP tokens only.
- Rejected-before-generation policy violations on Responses cost $0.05.

## 5. Observability
- Streaming recommended: watch `response.output_item.added` for tool items, `response.reasoning_summary_text.delta` for thinking, `response.function_call_arguments.done` for client calls.
- Citations: `output_text.annotations[]` (`url_citation`) + inline `[[N]](url)` (disable with `include:["no_inline_citations"]`); collections citations `collections://…`.
- xai-sdk: `get_tool_call_type(tool_call)` → `client_side_tool | web_search_tool | x_search_tool | code_execution_tool | collections_search_tool | mcp_tool`; `response.server_side_tool_usage` map (e.g. `{'SERVER_SIDE_TOOL_X_SEARCH': 3}`), `response.tool_calls` (all attempts incl. failed).

## 6. Chat Completions variant
Only client functions: `tools:[{type:"function", function:{…}}]` → `choices[0].message.tool_calls` (`finish_reason:"tool_calls"`) → append the assistant message + `{"role":"tool","tool_call_id":id,"content":…}` → resend full history (stateless). Server-side tools are not available there (422 / 410).

Shared runnable loop: `examples/xai/tools/function-calling/` (py/ts/sh) and `examples/xai/responses/tool_loop.py`.