LiteLLM + Amazon Bedrock AgentCore WebSearch 为 Agent 构建托管联网搜索（扩展篇）

摘要：本文是《Bedrock Claude + LiteLLM WebSearch Interception 配置指南》的扩展篇。上篇通过 LiteLLM 的 WebSearch Interception 功能 + 自部署 SearXNG，让 Bedrock Claude 获得了服务端联网搜索能力。本篇介绍另一条此后打通的路线：LiteLLM MCP 网关 + Amazon Bedrock AgentCore WebSearch（托管搜索），它在五个方面改进了上篇方案的限制与权衡，并额外支持 Claude Code 等 Agent 客户端以 MCP 工具方式接入。

01一、概述：两条路线的关系

02二、架构

03三、环境要求

04四、配置步骤

05五、调用方式（API 型消费者）

06六、Agent 客户端接入（Claude Code 等）

07七、功能支持对照

08八、结语

一、概述：两条路线的关系

上篇的 WebSearch Interception 方案通过 LiteLLM callback 拦截 Anthropic 协议中的 web_search_20250305 工具，把搜索请求转发到自部署的 SearXNG，实现”一次 API 调用内完成搜索 → 推理 → 终答”。该方案已经可用，但存在几个限制（见上篇”功能支持情况”）：

上篇方案的限制/权衡	本篇方案的改进
❌ 无结构化 Citation（靠提示词工程生成引用）	✅ 响应中原生携带每次搜索的查询词与结果明细（URL/标题/发布时间）
⚠️ Stream 被强制转为非流式	✅ 流式（SSE）正常工作
❌ `/chat/completions`（OpenAI 格式）调用 Bedrock 不触发 agentic loop（Bedrock Converse 路径限制）	✅ 主路径就是 `/chat/completions`，OpenAI SDK 直接用
Interception 覆盖 Bedrock/Azure/Vertex 等特定 provider	✅ 任意 OpenAI 兼容模型均可（含自托管 sglang / vLLM 私有模型）
文中路线为自部署 SearXNG（需自维护；也可插拔 Perplexity/Tavily 等第三方托管搜索，需其 API Key）	✅ AgentCore WebSearch 为 AWS 托管，与 IAM 权限/计费体系一体化，免运维

本篇方案的两个核心组件：

Amazon Bedrock AgentCore Gateway + WebSearch：AgentCore 提供的托管搜索能力，以标准 MCP（Model Context Protocol）端点暴露，入站认证为 AWS SigV4（IAM）。
LiteLLM MCP 网关：LiteLLM Proxy 原生支持把 MCP server 注册为受管工具源（含 AWS SigV4 认证，aws_service_name 默认即 bedrock-agentcore），并在 /chat/completions 请求携带 {"type":"mcp", "require_approval":"never"} 时，在服务端自动执行工具调用并回喂模型，直至输出终答——这正是 Anthropic 原生 web search 的 server-side tool 体验。

同时，本方案还提供上篇没有覆盖的第二种消费形态：Agent 型客户端（Claude Code、Cline 等自带工具循环的应用）可以把 LiteLLM 对外的 /mcp 端点直接注册为搜索工具—— SigV4 签名由网关代办，客户端只需一个 Bearer key。

二、架构

[图 1]

与上篇的”两层架构”（web_search_20250305 接口协议 / searxng-search 实现引擎）类比，本方案中{"type":"mcp","server_url":"litellm_proxy"} 是接口协议（模型/客户端使用，litellm_proxy 是固定哨兵值，表示”使用 proxy 自己配置的 MCP servers”），mcp_servers.agentcore_search 是实现引擎（ LiteLLM 使用）——搜索源同样可插拔，且真实 URL 与 AWS 凭证永不出网关。

三、环境要求

组件	版本/要求
LiteLLM Docker 镜像	`ghcr.io/berriai/litellm:main-stable`（需含 MCP 网关 + `aws_sigv4` 认证支持）
Amazon Bedrock AgentCore	Gateway + WebSearch（目前在海外区域提供，如 us-east-1）
调用端点	`/v1/chat/completions`（OpenAI 格式）为主；`/v1/messages`（Anthropic 格式）与 `/mcp` 同时可用
模型	任意 OpenAI 兼容后端（Bedrock 经 LiteLLM、或自托管 sglang/vLLM 私有模型均可）

部署位置不限，LiteLLM 可运行在任意能访问 AgentCore 区域端点的环境。

四、配置步骤

4.1 创建 AgentCore Gateway 与 WebSearch target

在 Bedrock AgentCore 控制台（或 CLI）创建 Gateway，入站授权选择 AWS_IAM，并为其添加 WebSearch 工具 target（详细步骤参考 AgentCore Gateway 文档）。完成后得到形如下面的 MCP 端点：

https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp

可先用 SigV4 直接验证（pip install awscurl）：

awscurl --service bedrock-agentcore --region us-east-1 -X POST "$GW_URL" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# 返回工具：web-search-tool___WebSearch（AgentCore 的 target___tool 命名）
# 参数：query（必填）、maxResults（1-25，默认 10）

4.2 最小权限 IAM 凭证

为网关创建专用 IAM user，内联策略只授权调用这一个 Gateway：

{"Version": "2012-10-17",
 "Statement": [{"Effect": "Allow",
   "Action": "bedrock-agentcore:InvokeGateway",
   "Resource": "arn:aws:bedrock-agentcore:us-east-1:<account-id>:gateway/<gateway-id>"}]}

Access Key 只写入网关服务器的 env 文件（权限 600），不进代码仓库。

4.3 配置 LiteLLM（config.yaml）

model_list:
  - model_name: my-model                 # 任意 OpenAI 兼容后端
    litellm_params:
      model: openai/my-model
      api_base: os.environ/UPSTREAM_API_BASE
      api_key: os.environ/UPSTREAM_API_KEY
      # ssl_verify: false                # 上游为自签证书（如自托管 sglang）时启用
mcp_servers:
  agentcore_search:
    url: https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp
    transport: http
    auth_type: aws_sigv4                 # LiteLLM 原生 SigV4，逐请求签名
    aws_region_name: us-east-1
    aws_service_name: bedrock-agentcore  # 默认值即此，显式写出便于阅读
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
litellm_settings:
  drop_params: true
  request_timeout: 600

对比上篇：无需 callbacks/websearch_interception_params，也没有 “api_base 只对 /v1/search 生效、handler 只读环境变量”这类隐蔽约束——MCP servers 的配置就是唯一事实源。

4.4 启动

docker run -d --name litellm-gw --restart unless-stopped --network host \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  --env-file .env \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml --port 4000
# .env 内：LITELLM_MASTER_KEY / UPSTREAM_* / AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY

验证工具已被网关发现：

curl -s http://localhost:4000/v1/mcp/tools -H "Authorization: Bearer $LITELLM_MASTER_KEY"
# → agentcore_search-web-search-tool___WebSearch

五、调用方式（API 型消费者）

5.1 一次调用完成搜索与回答

curl -s http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "messages": [{"role":"user","content":"AWS re:Invent 2026 具体是哪几天？请给出来源"}],
    "tools": [{"type":"mcp","server_url":"litellm_proxy","require_approval":"never"}]
  }'

require_approval: "never" 是服务端自动执行的开关：LiteLLM 拿到模型的 tool_calls 后自动以 SigV4 调用 AgentCore 搜索、把结果回喂模型，循环直至模型产出终答——客户端一次请求即得到完整回答。不带 type:"mcp" 工具的请求则为普通透传（tool_calls 回给客户端自行执行）。

同一端点因此天然支持三种模式：

请求形态	网关行为
无 `tools`	纯模型透传
`tools` 为普通 `type:"function"`	透传，客户端自己执行工具（传统方式）
`tools` 含 `type:"mcp"` + `require_approval:"never"`	服务端搜索循环

5.2 结构化引用：不再需要提示词工程

上篇的 Citation 只能靠提示词让模型在正文里生成 [1][2] 编号。本方案中，响应的 provider_specific_fields 原生携带完整搜索轨迹（实测返回节选）：

{
  "choices": [{
    "message": {
      "content": "AWS re:Invent 2026 的举办时间是 2026 年 11 月 30 日至 12 月 4 日……来源：https://aws.amazon.com/events/reinvent …",
      "provider_specific_fields": {
        "mcp_tool_calls": [
          {"function": {"name": "agentcore_search-web-search-tool___WebSearch",
                        "arguments": "{\"query\": \"AWS re:Invent 2026 dates\", \"maxResults\": 3}"}}
        ],
        "mcp_call_results": [
          {"tool_call_id": "…",
           "result": "{\"results\":[{\"title\":\"AWS re:Invent 2026\",\"url\":\"https://aws.amazon.com/events/reinvent/\",\"publishedDate\":\"…\",\"text\":\"Save the date November 30 - December 4, 2026 …\"}, …]}"}
        ]
      }
    }
  }]
}

客户端可以据此构建引用 UI（每次搜索的查询词、每条结果的标题/URL/发布时间/摘要全部可得），无需解析模型正文。当然，提示词内嵌引用的方式仍然兼容，可叠加使用。

5.3 Stream 正常工作

curl -sN http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H "Content-Type: application/json" \
  -d '{"model":"my-model","stream":true,
       "messages":[{"role":"user","content":"..."}],
       "tools":[{"type":"mcp","server_url":"litellm_proxy","require_approval":"never"}]}'

与上篇”stream 被强制转非流式”不同，本路径实测返回标准 SSE chunk 流。

六、Agent 客户端接入（Claude Code 等）

Agent 客户端自带工具循环，正确姿势不是服务端循环，而是把网关的两个端点分开用：

① 作为模型后端（LiteLLM 同时提供 Anthropic 格式 /v1/messages，上篇 4.2 节的 Claude Code 接法在本方案中同样成立）：

export ANTHROPIC_BASE_URL=http://<gateway-host>:4000
export ANTHROPIC_API_KEY=<litellm-key>     # 与上篇 4.2 节相同；ANTHROPIC_AUTH_TOKEN 亦可
export ANTHROPIC_MODEL=my-model
claude

② 作为搜索工具（本篇新增形态）：LiteLLM 会把它管理的 MCP servers 聚合为对外的标准 /mcp 端点，认证方式转换为 Bearer key：

claude mcp add --transport http websearch http://<gateway-host>:4000/mcp \
  --header "Authorization: Bearer <litellm-key>"

Claude Code 即获得 agentcore_search-web-search-tool___WebSearch 工具，由其自身循环驱动调用，SigV4 由网关代签，AWS 凭证不出服务端。这解决了 Agent 直连 AgentCore Gateway 的痛点——MCP 客户端通常只支持静态 header，无法完成逐请求的 SigV4 签名，经网关中转后这个问题不再存在。

七、功能支持对照

功能	上篇（Interception + SearXNG）	本篇（MCP 网关 + AgentCore）
一次调用完成搜索与回答	✅（仅 `/v1/messages`）	✅（`/chat/completions` 与 `/v1/messages`）
OpenAI 格式服务端循环	❌（Bedrock Converse 路径限制）	✅
Stream	⚠️ 强制转非流式	✅
结构化引用	❌（提示词工程）	✅ `provider_specific_fields` 原生轨迹
模型范围	Bedrock/Azure/Vertex 等	任意 OpenAI 兼容（含自托管私有模型）
搜索源	自部署 SearXNG（也可接 Perplexity/Tavily，需第三方 Key）	AWS 托管（AgentCore，IAM/计费一体化）
Agent 以 MCP 工具接入	未覆盖	✅ `/mcp` 端点 + Bearer
搜索无 API 费用	✅（SearXNG 免费）	按查询计费（见 AgentCore 定价）

两条路线并不互斥：对成本极度敏感、愿意自维护 SearXNG 的场景，上篇方案依然成立；需要托管搜索、结构化引用、流式与 Agent 生态接入的场景，推荐本篇路线。

八、结语

从上篇到本篇，服务端联网搜索的实现从”provider 特定的拦截 + 自部署搜索引擎”演进为”标准 MCP 协议 + 托管搜索服务”：协议面更通用（OpenAI/Anthropic/MCP 三种消费形态同一网关承载）、引用有了结构化数据、流式不再降级、搜索源免运维，且私有化部署的自托管模型与 Bedrock 托管模型可以在同一配置中共存。对于正在构建”带联网能力的模型 API”或希望给 Agent 工具链补充搜索能力的团队，这条路线的全部组件都是现成的，一份 config.yaml 即可完成集成。

➡️ 下一步行动：

相关产品：

Amazon Bedrock — 用于构建生成式人工智能应用程序和代理的端到端平台
Amazon Bedrock AgentCore — 加快代理投入生产的速度
Amazon IAM — 身份管理和访问权限

相关文章：

立即咨询 → 从 AI 规划到落地实施，我们的专家团队为你全程护航。

*前述特定亚马逊云科技生成式人工智能相关的服务目前在亚马逊云科技海外区域可用。亚马逊云科技中国区域相关云服务由西云数据和光环新网运营，具体信息以中国区域官网为准。

本篇作者

AWS 架构师中心：云端创新的引领者

探索 AWS 架构师中心，获取经实战验证的最佳实践与架构指南，助您高效构建安全、可靠的云上应用

亚马逊AWS官方博客