From bec12db6358e0ef7117dbd634b97a8d8e214ce8d Mon Sep 17 00:00:00 2001 From: Chesars Date: Tue, 10 Mar 2026 09:50:08 -0300 Subject: [PATCH 1/3] docs(responses): add tool_search & namespaces section for gpt-5.4 Add documentation for OpenAI's tool_search feature (Responses API) with SDK and Proxy examples showing namespace-based deferred tool loading. Closes #23206. --- .../docs/providers/openai/responses_api.md | 153 ++++++++++++++++++ 1 file changed, 153 insertions(+) diff --git a/docs/my-website/docs/providers/openai/responses_api.md b/docs/my-website/docs/providers/openai/responses_api.md index 7799c93ccf..afe6fcfe10 100644 --- a/docs/my-website/docs/providers/openai/responses_api.md +++ b/docs/my-website/docs/providers/openai/responses_api.md @@ -693,6 +693,159 @@ print(final_response.output) Set `parallel_tool_calls=False` to ensure zero or one tool is called per turn. [More details](https://platform.openai.com/docs/guides/function-calling#parallel-function-calling). +## Tool Search & Namespaces + +Tool search lets models dynamically load tools at runtime instead of sending every tool definition in the prompt. Group functions into **namespaces** and mark them with `defer_loading: true` — the model only loads the schemas it actually needs, saving tokens. + +Requires `gpt-5.4` or later. See [OpenAI Tool Search docs](https://developers.openai.com/api/docs/guides/tools-tool-search) for full details. + + + + +```python showLineNumbers title="Tool Search with Namespaces" +import litellm +import json + +# Define namespaces with deferred tools +tools = [ + {"type": "tool_search"}, # Enable tool search + { + "type": "namespace", + "name": "crm", + "description": "CRM tools for customer management", + "tools": [ + { + "type": "function", + "name": "get_customer", + "description": "Get customer details by ID", + "parameters": { + "type": "object", + "properties": { + "customer_id": {"type": "string"} + }, + "required": ["customer_id"], + }, + "defer_loading": True, + }, + { + "type": "function", + "name": "list_customers", + "description": "List customers with optional filters", + "parameters": { + "type": "object", + "properties": { + "status": {"type": "string", "enum": ["active", "inactive"]}, + }, + }, + "defer_loading": True, + }, + ], + }, + { + "type": "namespace", + "name": "billing", + "description": "Billing and invoicing tools", + "tools": [ + { + "type": "function", + "name": "get_invoice", + "description": "Get an invoice by ID", + "parameters": { + "type": "object", + "properties": { + "invoice_id": {"type": "string"} + }, + "required": ["invoice_id"], + }, + "defer_loading": True, + }, + ], + }, +] + +response = litellm.responses( + model="openai/gpt-5.4", + input="Look up invoice INV-2024-001 from the billing system", + tools=tools, +) + +# The response contains tool_search_call, tool_search_output, and function_call items +for item in response.output: + if isinstance(item, dict): + if item["type"] == "tool_search_call": + print(f"Searched namespaces: {item['arguments']['paths']}") + elif item["type"] == "tool_search_output": + print(f"Loaded {len(item['tools'])} tool(s)") + elif item["type"] == "function_call": + print(f"Called: {item.get('namespace', '')}.{item['name']}({item['arguments']})") + else: + if item.type == "function_call": + print(f"Called: {item.namespace}.{item.name}({item.arguments})") +``` + + + + +1. Set up config.yaml + +```yaml showLineNumbers title="OpenAI Proxy Configuration" +model_list: + - model_name: openai/gpt-5.4 + litellm_params: + model: openai/gpt-5.4 + api_key: os.environ/OPENAI_API_KEY +``` + +2. Start LiteLLM Proxy Server + +```bash title="Start LiteLLM Proxy Server" +litellm --config /path/to/config.yaml + +# RUNNING on http://0.0.0.0:4000 +``` + +3. Test it! + +```python showLineNumbers title="Tool Search via OpenAI SDK with LiteLLM Proxy" +from openai import OpenAI + +client = OpenAI( + base_url="http://localhost:4000", + api_key="your-api-key" +) + +response = client.responses.create( + model="openai/gpt-5.4", + input="Look up invoice INV-2024-001 from the billing system", + tools=[ + {"type": "tool_search"}, + { + "type": "namespace", + "name": "billing", + "description": "Billing and invoicing tools", + "tools": [ + { + "type": "function", + "name": "get_invoice", + "description": "Get an invoice by ID", + "parameters": { + "type": "object", + "properties": {"invoice_id": {"type": "string"}}, + "required": ["invoice_id"], + }, + "defer_loading": True, + }, + ], + }, + ], +) + +print(response.output) +``` + + + + ## Free-form Function Calling From 8fac04208d046ca6b432ef7229090553e9280746 Mon Sep 17 00:00:00 2001 From: Chesars Date: Tue, 10 Mar 2026 10:27:40 -0300 Subject: [PATCH 2/3] docs(responses): add tool_search bridge examples for chat completions Add examples showing tool_search with namespaces via the chat completions bridge (openai/responses/ prefix) for both SDK and proxy. --- .../docs/providers/openai/responses_api.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/docs/my-website/docs/providers/openai/responses_api.md b/docs/my-website/docs/providers/openai/responses_api.md index afe6fcfe10..a0a1eda199 100644 --- a/docs/my-website/docs/providers/openai/responses_api.md +++ b/docs/my-website/docs/providers/openai/responses_api.md @@ -846,6 +846,84 @@ print(response.output) +### Tool Search via Chat Completions Bridge + +You can also use tool search through the `/v1/chat/completions` endpoint by prefixing the model with `openai/responses/`. The request is routed through the Responses API but returns a standard chat completions response. + + + + +```python showLineNumbers title="Tool Search via Chat Completions Bridge" +import litellm + +response = litellm.completion( + model="openai/responses/gpt-5.4", + messages=[{"role": "user", "content": "Look up invoice INV-2024-001"}], + tools=[ + {"type": "tool_search"}, + { + "type": "namespace", + "name": "billing", + "description": "Billing and invoicing tools", + "tools": [ + { + "type": "function", + "name": "get_invoice", + "description": "Get an invoice by ID", + "parameters": { + "type": "object", + "properties": {"invoice_id": {"type": "string"}}, + "required": ["invoice_id"], + }, + "defer_loading": True, + }, + ], + }, + ], +) + +# Standard chat completions response +for tool_call in response.choices[0].message.tool_calls: + print(f"Called: {tool_call.function.name}({tool_call.function.arguments})") +``` + + + + +```bash showLineNumbers title="Tool Search via /v1/chat/completions" +curl http://localhost:4000/v1/chat/completions \ + -H "Authorization: Bearer $LITELLM_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "openai/responses/gpt-5.4", + "messages": [{"role": "user", "content": "Look up invoice INV-2024-001"}], + "tools": [ + {"type": "tool_search"}, + { + "type": "namespace", + "name": "billing", + "description": "Billing and invoicing tools", + "tools": [ + { + "type": "function", + "name": "get_invoice", + "description": "Get an invoice by ID", + "parameters": { + "type": "object", + "properties": {"invoice_id": {"type": "string"}}, + "required": ["invoice_id"] + }, + "defer_loading": true + } + ] + } + ] + }' +``` + + + + ## Free-form Function Calling From e7a9c1e1566d53d29acce37678c0b4e44b275935 Mon Sep 17 00:00:00 2001 From: Chesars Date: Tue, 10 Mar 2026 18:41:54 -0300 Subject: [PATCH 3/3] docs(responses): remove unused json import from tool search example --- docs/my-website/docs/providers/openai/responses_api.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/my-website/docs/providers/openai/responses_api.md b/docs/my-website/docs/providers/openai/responses_api.md index a0a1eda199..0d6b9013ac 100644 --- a/docs/my-website/docs/providers/openai/responses_api.md +++ b/docs/my-website/docs/providers/openai/responses_api.md @@ -704,7 +704,6 @@ Requires `gpt-5.4` or later. See [OpenAI Tool Search docs](https://developers.op ```python showLineNumbers title="Tool Search with Namespaces" import litellm -import json # Define namespaces with deferred tools tools = [