feat(search): add Amazon Bedrock AgentCore web search provider

[devin-ai-integration]

TLDR

Problem this solves:

• No AWS-native web search provider in LiteLLM
• Bedrock users need a third-party search key today
• Web Search on Bedrock AgentCore speaks MCP, unsupported

How it solves it:

• Adds agentcore search provider calling an AgentCore Gateway
• SigV4 for AWS_IAM gateways, bearer token for CUSTOM_JWT
• Works for /search and for websearch_interception

User Flow

Before: a developer on AWS wants Claude Code on Bedrock to search the web, but pointing the proxy at their AgentCore Gateway does nothing and every working option needs a non-AWS search key

1. They add a search tool with search_provider: agentcore pointing at their AgentCore Gateway MCP endpoint and start the proxy; boot succeeds with no warning
2. They send POST https://litellm-domain/search with {"query": "latest AI developments", "search_tool_name": "agentcore-search", "max_results": 5} and get HTTP 500 'agentcore' is not a valid SearchProviders
3. GET https://litellm-domain/search_tools/ui/available_providers lists 18 providers, every one a third-party service (Tavily, Exa, Perplexity, Brave, ...), and agentcore is absent
4. They send POST https://litellm-domain/v1/messages with a web_search tool and their Bedrock model; HTTP 200 comes back, but the web search result block is empty and the assistant apologizes about a search provider configuration error
5. In Claude Code pointed at the proxy, WebSearch errors on screen both times it runs, returning no links or content

After: the same developer points the proxy at their AgentCore Gateway and search works, with the search traffic staying inside AWS

1. They create an AgentCore Gateway with a web-search connector target and set AGENTCORE_GATEWAY_URL to its MCP endpoint
2. They add the same search tool entry with search_provider: agentcore (see litellm/proxy/example_config_yaml/agentcore_websearch_config.yaml) and no third-party key, then start the proxy
3. The same POST https://litellm-domain/search returns HTTP 200 with 5 real results carrying title, url, snippet, date
4. GET https://litellm-domain/search_tools/ui/available_providers now includes agentcore ("Web Search on Amazon Bedrock")
5. The same POST https://litellm-domain/v1/messages returns a filled web search result block (10 results) and an answer built from them; the search leg is a SigV4-signed call to their own gateway, billed by AWS
6. In Claude Code, Web Search returns real results and the answer cites them
7. Pointing api_base at a host that is not their gateway, or at a plain http:// URL, returns an error instead of sending the server's AGENTCORE_GATEWAY_TOKEN or a SigV4 signature, and a caller-supplied tool_name that is not a ___WebSearch connector tool is rejected

Relevant issues

Fixes #31819

Supersedes #34098, which this builds on

Docs live in the docs repo and are already merged: BerriAI/litellm-docs#834, plus BerriAI/litellm-docs#949 for the MCP protocol version env var

Follow-up filed while QA'ing this PR: #37538 (the search router silently drops provider-specific yaml litellm_params for every search provider; pre-existing, untouched here)

Linear ticket

Resolves LIT-5375

Pre-Submission checklist

• 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

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

Both runs hit a real AgentCore Gateway (litellm-qa-agentcore-tez4ymmxfc, us-east-1, web-search connector target, provisioned for this QA and deleted after) and real Bedrock Claude, no mocks or stubs anywhere. Shared setup, identical for both sides except the commit the proxy was booted from:

model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: bedrock/us.anthropic.claude-sonnet-5
      aws_region_name: us-east-1

search_tools:
  - search_tool_name: agentcore-search
    litellm_params:
      search_provider: agentcore
      api_base: https://litellm-qa-agentcore-tez4ymmxfc.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp
  - search_tool_name: agentcore-untrusted
    litellm_params:
      search_provider: agentcore
      api_base: https://untrusted-host.example.com/mcp
  - search_tool_name: agentcore-badtool
    litellm_params:
      search_provider: agentcore
      api_base: https://litellm-qa-agentcore-tez4ymmxfc.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp
      tool_name: my-target___ListFiles
  - search_tool_name: agentcore-plaintext
    litellm_params:
      search_provider: agentcore
      api_base: http://gw.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp

litellm_settings:
  callbacks: ["websearch_interception"]
  websearch_interception_params:
    enabled_providers: ["bedrock"]
    search_tool_name: agentcore-search

Env for both proxies: AGENTCORE_GATEWAY_URL (the real gateway), SigV4 credentials, AWS_REGION=us-east-1, and AWS_BEARER_TOKEN_BEDROCK for the Bedrock model call. Before proxy booted from the merge base on port 46526, After proxy from the PR tip on port 26793. Claude Code runs are the real TUI (v2.1.236) driven interactively under tmux with ANTHROPIC_BASE_URL pointed at the proxy

Before (2059033)

POST /search through the configured agentcore search tool

1. curl -sS -X POST http://127.0.0.1:46526/search -H 'Content-Type: application/json' -H 'Authorization: Bearer sk-qa-before-7731' -d '{"query": "latest AI developments", "search_tool_name": "agentcore-search", "max_results": 5}'

2. {"error":{"message":"litellm.APIConnectionError: 'agentcore' is not a valid SearchProviders\nTraceback (most recent call last):\n  File \".../litellm/search/main.py\", line 244, in search\n    provider=SearchProviders(search_provider),\n...ValueError: 'agentcore' is not a valid SearchProviders\n. Received Model Group=agentcore-search\nAvailable Model Group Fallbacks=None","type":null,"param":null,"code":"500"}}

   HTTP 500. The proxy had booted cleanly with all four agentcore search tools configured, so the failure only surfaces at request time

Provider discovery

1. curl -s http://127.0.0.1:46526/search_tools/ui/available_providers -H 'Authorization: Bearer sk-qa-before-7731'
2. 18 providers returned (perplexity, tavily, parallel_ai, exa_ai, brave, google_pse, dataforseo, firecrawl, fastcrw, searxng, linkup, duckduckgo, searchapi, serper, you_com, apiserpent, tinyfish, nimble), agentcore absent

/v1/messages with the Anthropic web_search tool on real Bedrock Claude

1. curl -sS -X POST http://127.0.0.1:46526/v1/messages -H 'Content-Type: application/json' -H 'Authorization: Bearer sk-qa-before-7731' -d '{"model":"claude-sonnet","max_tokens":1024,"messages":[{"role":"user","content":"Use the web_search tool to look up the latest LiteLLM release, then list the result titles you got."}],"tools":[{"type":"web_search_20250305","name":"web_search","max_uses":2}]}'
2. HTTP 200, but the web_search_tool_result block came back empty ("content":[]) and the assistant text was: The web search tool encountered an error on my end (a configuration issue with the search provider — "'agentcore' is not a valid SearchProviders") and was unable to return any results.
3. Proxy log: WebSearchInterception: Search failed for 'latest LiteLLM release': litellm.APIConnectionError: 'agentcore' is not a valid SearchProviders

Interactive Claude Code under tmux

1. Asked Claude Code (real TUI under tmux, proxy as ANTHROPIC_BASE_URL) to look up the latest LiteLLM release with web search; its WebFetch fallback was denied so the search path stayed the thing under test
2. It ran WebSearch twice, both erroring. On-screen output:

   ⏺ That search attempt returned an internal error rather than real results ...
   ⏺ The search tool itself is erroring out (backend misconfiguration, not fixable from my end).
   ⏺ Here's what happened: I ran WebSearch twice ... Both times, the tool returned
     no actual search results — instead it came back with an error saying an invalid search provider ("agentcore") was configured on the backend. No links or content were retrieved either time.
   

Credential and tool-name guards

1. Not reachable at this commit: every agentcore search tool already fails with the provider error above, so no credentialed request to a gateway can be produced at all

After (70a4f9a)

The PR tip 7744b91 differs from 70a4f9a only by a comment edit in the example config (nothing loads that file at runtime or in tests), so this run stands for the tip

POST /search through the configured agentcore search tool

1. curl -sS -X POST http://127.0.0.1:26793/search -H 'Content-Type: application/json' -H 'Authorization: Bearer sk-qa-after-9917' -d '{"query": "latest AI developments", "search_tool_name": "agentcore-search", "max_results": 5}'
2. HTTP 200 with 5 real live-web results, e.g.:

   {"title": "AI News & Artificial Intelligence", "url": "https://techcrunch.com/category/artificial-intelligence/", "date": "08:44AM, Wednesday, August 19 2026, PDT"}
   {"title": "The trends that will shape AI and tech in 2026", "url": "https://www.ibm.com/think/news/ai-tech-trends-predictions-2026", "date": "02:42PM, Friday, July 24 2026, PDT"}

   (others: openai.com announcement, aiweekly.co, a forbes.com article dated the day of the run)

Provider discovery

1. curl -s http://127.0.0.1:26793/search_tools/ui/available_providers -H 'Authorization: Bearer sk-qa-after-9917'
2. Now includes {"provider_name": "agentcore", "ui_friendly_name": "Web Search on Amazon Bedrock"}

/v1/messages with the Anthropic web_search tool on real Bedrock Claude

1. curl -sS -X POST http://127.0.0.1:26793/v1/messages -H 'Content-Type: application/json' -H 'Authorization: Bearer sk-qa-after-9917' -d '{"model":"claude-sonnet","max_tokens":1024,"messages":[{"role":"user","content":"Use the web_search tool to look up the latest LiteLLM release, then list the result titles you got."}],"tools":[{"type":"web_search_20250305","name":"web_search","max_uses":2}]}'
2. HTTP 200 with content blocks ['server_tool_use', 'web_search_tool_result', 'text']: {"name": "web_search", "input": {"query": "latest LiteLLM release"}}, then 10 real results (docs.litellm.ai/release_notes/..., github.com/BerriAI/litellm/releases, ...), then a real answer listing the titles; stop_reason: end_turn, usage 10770 in / 581 out
3. Proxy log shows the search leaving as a SigV4-signed tools/call of web-search-tool___WebSearch to the gateway

Interactive Claude Code under tmux

1. Same TUI flow as Before: typed the prompt, approved the Web Search permission prompt on screen
2. On-screen output, real results this time:

   ⏺ Web Search("LiteLLM latest stable release version 2026")
     ⎿  Did 1 search in 30s
   ⏺ Fetch(https://github.com/BerriAI/litellm/releases)
     ⎿  Received 757.4KB (200 OK)
   ⏺ The latest stable LiteLLM release is v1.97.0 (released Aug 16, 2026), per GitHub's "Latest" tag ...
   

3. Proxy log attributes that exact query to a tools/call against the real gateway; no other search backend existed in the environment

Credential and tool-name guards

1. Untrusted host: curl -sS -X POST http://127.0.0.1:26793/v1/search/agentcore-untrusted ... returned HTTP 500 with no request sent: Refusing to send SigV4-signed AgentCore requests to 'https://untrusted-host.example.com/mcp': it is neither an AgentCore gateway hostname nor the host in AGENTCORE_GATEWAY_URL. Set AGENTCORE_GATEWAY_URL to authorize a custom gateway hostname.
2. Plaintext transport: curl -sS -X POST http://127.0.0.1:26793/v1/search/agentcore-plaintext ... returned HTTP 500 with no request sent: Refusing to send AgentCore credentials over plaintext HTTP to 'http://gw.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp': a bearer token or SigV4 signature would be readable in transit. Use an https gateway URL (plain http is allowed only for localhost).
3. Tool-name guard, exercised via env var: with AGENTCORE_SEARCH_TOOL_NAME=my-target___ListFiles exported, /v1/search/agentcore-search refused with Invalid AgentCore search tool_name 'my-target___ListFiles': must end with '___WebSearch' (a web-search connector tool). Other gateway tools cannot be invoked through this provider.
4. The agentcore-badtool yaml entry did NOT trigger that guard: it returned HTTP 200 because the search router forwards only search_provider/api_key/api_base from yaml litellm_params and dropped the tool_name, so the request went out with the default tool name. That plumbing predates this PR and hits every search provider; filed as [Bug]: search router silently drops provider-specific litellm_params from yaml search_tools entries #37538, and the example config here no longer advertises yaml knobs the router drops. The guard itself stays load-bearing for the reachable paths: request-body tool_name, the env var, and SDK calls

Observations from the runs, for the reviewer:

• Provider-only /search body 500s; pre-existing validation; PR leaves alone
• Interception search failure still answers HTTP 200; pre-existing; PR leaves alone
• Unknown search_provider passes proxy boot silently; pre-existing; PR leaves alone
• Router drops extra yaml litellm_params ([Bug]: search router silently drops provider-specific litellm_params from yaml search_tools entries #37538); pre-existing; PR leaves alone
• Guard refusals surface as HTTP 500 with tracebacks; pre-existing error shape; PR leaves alone
• Gateway result dates occasionally nonsense ("April 12 2000"); upstream data; PR leaves alone

Type

🆕 New Feature

Caveats (if any)

• Admin UI search-tool form has no api_base field, so UI setup needs AGENTCORE_GATEWAY_URL
• Cost map entry is $0 per query, AWS bills the gateway directly
• tool_name and aws credential overrides work per request or via env vars, not yaml ([Bug]: search router silently drops provider-specific litellm_params from yaml search_tools entries #37538)

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

Changes

AgentCoreSearchConfig (litellm/llms/bedrock/search/transformation.py) is a BaseSearchConfig that speaks MCP instead of a bespoke REST API: transform_search_request builds a JSON-RPC tools/call body, and transform_search_response accepts both a plain JSON reply and the Streamable HTTP SSE framing, picking the event that carries result or error so a progress notification can't shadow the response.

{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "web-search-tool___WebSearch",
            "arguments": {"query": query[:200], "maxResults": max_results}}}

Results are parsed from the tool result's text blocks first, falling back to result.structuredContent (the web-search connector 1.1.0+ can return machine-readable results there while the text blocks carry prose). Requests go out with MCP-Protocol-Version: 2025-03-26, the version a gateway with a default protocolConfiguration accepts, overridable via AGENTCORE_MCP_PROTOCOL_VERSION for gateways pinning supportedVersions.

Signing needed a new optional hook, because a SigV4 signature covers the exact bytes on the wire:

class BaseSearchConfig:
    def sign_request(self, headers, optional_params, request_data, api_base, api_key=None) -> tuple[dict, bytes | None]:
        return headers, None  # default no-op

BaseLLMHTTPHandler.search / async_search call it and, when a signed body comes back, send it verbatim as data= rather than re-serializing it through json=.

Three things the gateway makes easy to get wrong, all covered by tests: a caller-supplied tool_name must end in ___WebSearch, so this provider can't be used to invoke unrelated tools on the same gateway with the proxy's credentials; server-managed credentials, both AGENTCORE_GATEWAY_TOKEN and a SigV4 signature, only go to a trusted host (a real *.gateway.bedrock-agentcore.<region>.amazonaws.com hostname or the host in AGENTCORE_GATEWAY_URL, which is how a custom or private gateway hostname gets authorized); and credentials only ride https, with plain http refused unless the host is localhost, so neither token nor signature is readable in transit. A tools/call that fails in-band, HTTP 200 with result.isError, raises instead of looking like a search with no results. The signing region comes from the gateway hostname, falling back to the AWS config chain and erroring out rather than guessing a region the gateway would reject. api_key="" is passed down to BaseAWSLLM._sign_request so the Bedrock Runtime AWS_BEARER_TOKEN_BEDROCK never leaks to an AgentCore endpoint.

Also adds agentcore/search to the cost map (AWS bills the gateway directly) and an example proxy config wiring it into websearch_interception for Bedrock Claude Code.

Search pre_call logs the headers as they were before signing, so a configured logger_fn never sees the SigV4 or bearer Authorization value; only the outbound request carries it

Link to Devin session: https://app.devin.ai/sessions/902d85f7efbc4becb45d3340ad7c6782
Requested by: @yassin-berriai

• 7744b91 passes /live-pr-risk

[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.
2 out of 4 committers have signed the CLA.

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

[greptile-apps]

Greptile Summary

The PR adds Amazon Bedrock AgentCore as an MCP-backed web-search provider, including bearer and SigV4 authentication, normalized JSON/SSE responses, provider registration, pricing metadata, configuration, and tests

• Extends the shared search handler with a typed request-signing hook and verbatim signed-body transport
• Adds trusted-destination and encrypted-transport checks for server-managed credentials
• Registers AgentCore across search provider discovery, configuration lookup, and cost metadata

Confidence Score: 5/5

The PR appears safe to merge

No blocking failure remains

Important Files Changed

Filename	Overview
litellm/llms/bedrock/search/transformation.py	Implements AgentCore MCP request transformation, authentication, destination validation, SSE/JSON parsing, and result normalization
litellm/llms/custom_httpx/llm_http_handler.py	Adds search-request signing while keeping signed headers separate from callback logging and preserving signed body bytes
litellm/llms/base_llm/search/transformation.py	Adds a fully parameterized optional signing contract to the shared search configuration
tests/test_litellm/llms/bedrock/search/test_agentcore_search_transformation.py	Covers request transformation, response formats, authentication paths, destination checks, transport enforcement, and provider registration

_{Reviews (9): Last reviewed commit: "docs(search): stop advertising yaml lite..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 96.59864% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/llms/bedrock/search/transformation.py	96.42%	5 Missing ⚠️

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing devin_ai_agentcore_search (7744b91) with litellm_internal_staging (4d100bd)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (d58b1c8) during the generation of this report, so 4d100bd was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[devin-ai-integration]

Fixed both findings in 15a6664: pre_call now logs the pre-signing headers, and sign_request carries precise annotations. @greptileai review

[yassin-berriai]

bugbot run

[mubashir1osmani]

bugbot run

[mubashir1osmani]

@greptile-apps

[devin-ai-integration]

Verified live on a local proxy against a stub MCP gateway, runs and outputs are in the description's proof section. A real gateway call is still untested.

[mateo-berri]

bugbot run

[mateo-berri]

@greptileai

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 49dca49. Configure here.}

[mateo-berri]

bugbot run

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[mateo-berri]

@greptileai

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ed84e82. Configure here.}

[mateo-berri]

bugbot run

[mateo-berri]

@greptileai

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 70a4f9a. Configure here.}

[mateo-berri]

bugbot run

[mateo-berri]

@greptileai

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 7744b91. Configure here.}

[mateo-berri]

LGTM