fix(websearch): intercept web search on the Responses API

[devin-ai-integration]

Relevant issues

Linear ticket

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review)

Screenshots / Proof of Fix

Live proxy hitting OpenAI Responses and Exa AI search with no mocks

model_list:
  - model_name: gpt-4.1
    litellm_params:
      model: openai/gpt-4.1
      api_key: os.environ/OPENAI_API_KEY
search_tools:
  - search_tool_name: "my-exa-search"
    litellm_params:
      search_provider: "exa_ai"
litellm_settings:
  callbacks: ["websearch_interception"]
  websearch_interception_params:
    enabled_providers: ["openai"]
    search_tool_name: "my-exa-search"

The same request was used before and after

curl -s -X POST http://localhost:4000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "Search the web: who won the most recent F1 world drivers championship and in what year? Give a one sentence answer.",
    "tools": [{"type": "web_search"}]
  }'

Before at 539bc30e04, OpenAI's native search passed through without LiteLLM interception

output item types: ['web_search_call', 'message']
tool_usage={'web_search': {'num_requests': 1}}
interception / Exa log matches: 0

After at aa7b480f4c, LiteLLM replaced the native tool, executed the configured Exa search, supplied its result as function_call_output, and completed the Responses turn

WebSearchInterception: Converting Responses web_search tools to LiteLLM standard
WebSearchInterception: Responses hook called! provider=openai, stream=False
WebSearchInterception: Found litellm_web_search function_call
WebSearchInterception: Executing 1 responses search(es) in parallel
POST https://api.exa.ai/search
WebSearchInterception: Built responses request patch
WebSearchInterception: No WebSearch function_call detected in responses output

output item types: ['message']
TEXT: The most recent Formula 1 World Drivers' Championship was won by Lando Norris in 2025.

Type

Bug Fix

Changes

Web search interception previously handled Chat Completions and Anthropic Messages, but /v1/responses fell through to the Anthropic response parser and silently skipped the agentic loop

This adds a Responses-specific path:

native Responses web_search tool
  -> flat litellm_web_search function tool
  -> detect response.output function_call
  -> execute configured search provider
  -> append function_call + function_call_output
  -> rerun through litellm.aresponses

Streaming requests are converted to non-streaming while the server-side loop executes and are re-wrapped afterward using the existing Responses fake-stream path

Review hardening in 7f598c6a9b limits detection to the canonical litellm_web_search function name and removes the transient _agentic_loop_api_surface marker from follow-up kwargs, with regression coverage for both cases

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

Link to Devin session: https://app.devin.ai/sessions/c3fab892d6844e46bd45d62ff941bcd8
Requested by: @krrish-berri-2

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
0 out of 2 committers have signed the CLA.

❌ devin-ai-integration[bot]
❌ krrish-berri
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codecov]

Codecov Report

❌ Patch coverage is 83.19328% with 20 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...egrations/websearch_interception/transformation.py	65.71%	12 Missing ⚠️
...llm/integrations/websearch_interception/handler.py	90.00%	7 Missing ⚠️
...tellm/integrations/websearch_interception/tools.py	88.88%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR adds web search interception support for the Responses API (/v1/responses), completing the surface coverage that previously only covered Chat Completions and Anthropic Messages. The implementation follows the existing interception pattern: convert the native tool in the pre-call deployment hook, detect the model's function_call in the post-call agentic hook, execute the configured search provider, and submit a follow-up request with function_call + function_call_output items.

• Deployment hook (_convert_responses_tools): converts native web_search / web_search_preview / versioned variants to a flat litellm_web_search function tool (Responses shape, distinct from the nested Chat Completions shape), and downgrades stream=True to stream=False with a re-wrap flag for after the loop completes.
• Agentic loop dispatch (async_build_agentic_loop_plan): routes to async_build_responses_agentic_loop_plan when _agentic_loop_api_surface == \"responses\", which gathers search results in parallel and builds the follow-up input list.
• Tests: eight mock-only unit tests covering detection, provider/tool filtering, surface-marker routing, regression guards, and exact plan output shape assertions.

Confidence Score: 5/5

The change is additive and isolated to the websearch interception integration; existing chat completion and Anthropic Messages paths are unmodified.

The new Responses API path is self-contained, correctly gated behind the _agentic_loop_api_surface marker, properly filters interception-specific keys from follow-up kwargs, and the stream re-wrap logic is tested end-to-end. No authentication paths or data-persistence paths are touched.

No files require special attention; the integration is well-tested and the most complex logic has direct unit test coverage.

Important Files Changed

Filename	Overview
litellm/integrations/websearch_interception/handler.py	Adds Responses API interception: deployment hook dispatches to _convert_responses_tools, async_build_agentic_loop_plan dispatches to async_build_responses_agentic_loop_plan, and _build_responses_request_patch correctly assembles function_call + function_call_output items for the follow-up.
litellm/integrations/websearch_interception/tools.py	Adds get_litellm_web_search_tool_responses() (flat Responses-API function tool shape) and is_web_search_tool_responses() (detects both native web_search* tools and the converted litellm_web_search function tool). Logic is correct.
litellm/integrations/websearch_interception/transformation.py	Adds _detect_from_responses_response() that parses response.output for function_call items named litellm_web_search. Correctly gated on response_format="responses" in transform_request.
litellm/llms/custom_httpx/llm_http_handler.py	Two targeted changes: hook_kwargs now carries _agentic_loop_api_surface, and the stream re-wrap gate now OR-includes _websearch_interception_converted_stream alongside the existing _code_interpreter flag.
litellm/types/integrations/custom_logger.py	Adds RESPONSES_AGENTIC_SURFACE = "responses" constant used to identify the Responses API path in the agentic loop dispatch chain.
tests/test_litellm/integrations/websearch_interception/test_websearch_responses.py	Eight focused mock-only unit tests covering hook detection, provider/tool filtering, surface-marker routing, regression guards, plan building shape assertions, and stream conversion.

_{Reviews (3): Last reviewed commit: "Merge remote-tracking branch 'origin/lit..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_websearch_responses_interception (75ccb4f) with litellm_internal_staging (b2202cb)}

[devin-ai-integration]

@greptileai please re-review the latest head and report the updated confidence score

[mateo-berri]

LGTM; thanks!