AWS 在 Amazon Bedrock AgentCore 上推出 Web Search API

对于需要回答近期事件、产品发布、价格或法规等问题的 AI 智能体和应用来说，它们需要比模型训练数据更新的信息。在此之前，Amazon Bedrock AgentCore 上的 Web Search（网络搜索）通过 Amazon Bedrock AgentCore 的一项功能——AgentCore Gateway——向智能体提供这些信息。这意味着需要创建一个网关和一个网络搜索目标，然后从 MCP 客户端调用该工具。这种设置适合在多个智能体之间共享同一搜索策略的平台团队，但如果您自己的代码只需要搜索结果，这就显得多余了。

今天，我们宣布推出 Amazon Bedrock AgentCore 上的 Web Search API（网络搜索 API）。借助它，您自己的代码只需一次 API 调用即可搜索网络。它返回来自 Amazon 运营的网络索引的排序结果，每条结果都包含文本摘录，并在可用时提供页面标题、URL 和发布时间。您可以通过 AWS SDK 或 AWS 命令行界面（AWS CLI）调用它，并使用与其他 AWS 服务相同的 AWS Identity and Access Management (IAM) 凭证进行签名。无需预先创建任何资源：完成身份验证、发起调用、获取结果。您可以在应用程序、自己编写的智能体循环或数据管道中使用它。

为什么要推出独立的 API？

对于大多数智能体工作负载，AgentCore Gateway 是推荐的途径。它为智能体提供一个安全的模型上下文协议（MCP）端点，将网络搜索与您的其他工具整合在一起。它还处理入站和出站身份验证、语义工具选择以及可选的 MCP 会话。但开发者告诉我们，在某些网关并不适用的场景下，他们还需要一个更底层的集成点：

• 自定义编排框架 – 构建自己智能体循环的开发者，或使用 LangChain、LlamaIndex 等框架的开发者，希望在编排逻辑中直接将网络搜索作为工具调用，而不是通过网关路由。
• 非智能体用例 – 并非所有需要网络信息支撑的应用都是智能体。搜索驱动的仪表板、事实核查管道、内容丰富工作流和监控系统都可以从实时网络结果中受益，而无需智能体基础设施。
• 对请求生命周期更精细的控制 – 一些开发者希望自己管理重试、缓存和错误处理，而不是委托给网关。
• 为现有应用提供更简单的集成 – 已经拥有自己 API 层的应用可以直接调用 Web Search API，在不采用完整 AgentCore Gateway 技术栈的情况下添加网络信息支撑。

Web Search API 是对网关的补充。它运行在与 Alexa+、Kiro、Quick 和其他 Amazon 产品相同的搜索基础设施之上，具备相同的质量和合规保障，并以直接 API 操作的形式对外提供。

工作原理

Web Search API 是 bedrock-agentcore 数据平面上的 InvokeWebSearch 操作，该端点与其他 AgentCore 工具（例如 Amazon Bedrock AgentCore 的一项功能 AgentCore Browser）所使用的端点相同。请求使用您的标准 AWS 凭证通过 AWS Signature Version 4 (SigV4) 进行签名，因此无需管理任何 API 密钥或机密。

图 1：Web Search API 请求的流转方式

具体步骤如下：

1. 您的应用程序通过 AWS SDK 或 AWS CLI 调用 InvokeWebSearch，SDK 会使用其 AWS 凭证通过 SigV4 对请求进行签名。在虚拟私有云（VPC）中，该调用可以通过接口 VPC 终端节点进行。
2. 该 API 会与 AWS Identity and Access Management (IAM) 核查调用者是否对 AWS 托管的网络搜索工具拥有 bedrock-agentcore:InvokeWebSearch 权限。
3. 该 API 应用请求中的过滤器：要包含或排除的域名，以及发布时间范围。
4. 该 API 搜索由 Amazon 运营的网络索引。查询在 AWS 内部处理，不会发送给第三方搜索引擎。
5. 该 API 最多返回 maxResults 条按相关性排序的结果，每条结果包含一段文本摘录，并（在可用时）附带页面标题、URL 和发布时间。

调用身份需要对 AWS 托管资源拥有一项 IAM 权限。这与网关的服务角色进行网络搜索时使用的操作和资源相同，因此一条策略即可覆盖两条路径。详见 授予调用该 API 的权限。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "InvokeWebSearch",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:InvokeWebSearch",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:aws:tool/web-search.v1"
        }
    ]
}

首个搜索请求

以下示例使用 AWS SDK for Python (Boto3) 在两个可信域名中搜索 2026 年发布、位于美国西部（俄勒冈）区域 (us-west-2) 的页面：

import boto3

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

response = client.invoke_web_search(
    webSearchId="web-search.v1",
    searchQuery="multi-region EKS cluster deployment best practices",
    maxResults=10,
    filters={
        "domainFilter": {"include": ["aws.amazon.com", "kubernetes.io"]},
        "publishedDateFilter": {"publishedAfter": "2026-01-01T00:00:00Z"},
    },
)

for result in response["results"]:
    print(result.get("publishedAt"), result.get("title"), result.get("url"))

每条结果都包含一段文本摘录。当索引中存有时，会返回标题、URL 和发布日期，因此请使用 get 读取它们。下面是一次真实调用（已缩短）的一条结果：

{
    "title": "One Amazon EKS, many edges: How to choose your edge container strategy on AWS",
    "url": "https://aws.amazon.com/blogs/containers/one-amazon-eks-many-edges-how-to-choose-your-edge-container-strategy-on-aws/",
    "text": "Separate the standard from the deployment model Choosing the wrong platform isn't really the issue. ...",
    "publishedAt": "2026-09-25T15:52:00Z"
}

这就是完整的集成。如果您的代码运行在 AWS Lambda、Amazon Elastic Container Service (Amazon ECS)、Amazon Elastic Compute Cloud (Amazon EC2) 或 Amazon Elastic Kubernetes Service (Amazon EKS) 上，执行角色会自动提供凭证。只需为该角色添加相应权限，同样的代码无需任何修改即可运行。

API 主要功能

• 域名过滤 – 包含或排除特定域名，将搜索结果限定在可信来源（例如，面向 AWS 的助手只包含 aws.amazon.com 和 kubernetes.io）。每个列表最多包含 100 个域名，且根域名也会匹配其子域名。
• 日期过滤 – 使用 publishedAfter 和 publishedBefore 将结果限定在某个发布时间范围内，以 UTC 的 RFC 3339 日期时间格式给出，例如 2026-01-01T00:00:00Z。两个边界均为包含性。
• 可配置的结果数量 – 每次查询可请求 1 至 25 条结果。如果未设置 maxResults，该 API 最多返回 25 条。搜索文本 searchQuery 最长可达 200 个字符。
• 带文本摘录的结果 – 每条结果都包含一段文本摘录，并（在可用时）附带页面标题、URL 和发布时间，可直接用于模型的上下文窗口。

5 分钟内上手

以下是获得首个结果的两种方式：

方式 1：AWS CloudShell（无需本地设置）

1. 在浏览器中打开 AWS CloudShell。它使用您控制台会话的凭证。
2. 您的角色将拥有 bedrock-agentcore:InvokeWebSearch 权限，该权限来自前面的策略，或来自更宽泛的 AWS 托管策略 BedrockAgentCoreFullAccess。
3. Run:

   aws bedrock-agentcore invoke-web-search \
       --web-search-id web-search.v1 \
       --search-query "latest EKS features" \
       --max-results 5

方式 2：本地开发

1. 安装 AWS CLI，或适用于您所用语言的 AWS SDK。对于 Python，请使用 Boto3 1.43.127 或更高版本。
2. 使用前面的策略创建一个 IAM 角色。
3. 获取该角色的凭证：从您的应用程序或 AWS CLI 配置文件中代入该角色，或通过您的身份提供程序使用该角色登录。
4. 运行前面的 Python 示例，或从任何 AWS SDK 调用该 API。

无需创建任何资源，也无需管理任何 API 密钥。完成身份验证、调用、获取结果即可。

在智能体框架中使用 Web Search API

Web Search API 可自然融入主流智能体框架。LangChain 智能体可通过 langchain-aws 1.9.3 及更高版本中的 AgentCore web search 工具使用它：

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain_aws.tools import create_web_search_toolkit

toolkit, tools = create_web_search_toolkit(region="us-west-2")
model = init_chat_model("bedrock_converse:us.anthropic.claude-sonnet-5", region_name="us-west-2")
agent = create_agent(model, tools=tools, system_prompt="Cite the URL of every fact you use.")

该工具还可以包含模型无法更改的规则，例如要排除的域名、日期下限和搜索预算。它以数据形式返回结果，供你的代码进行校验。完整示例请参阅 daily dependency watch 示例。它使用 LangGraph 并行研究三个软件包生态系统，并在报告任何结果之前根据其来源检查每一条发现。

如果你希望自己封装调用，使用普通的 LangChain 工具也可以：

from langchain.tools import tool
import boto3
import json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

@tool
def web_search(query: str) -> str:
    """Search the web for current information."""
    response = client.invoke_web_search(
        webSearchId="web-search.v1",
        searchQuery=query,
        maxResults=5,
    )
    return json.dumps(response["results"], indent=2, default=str)

# Pass web_search to an agent, for example create_agent(model, tools=[web_search])

如果不使用框架，AgentCore Python SDK 中的 WebSearchClient 可封装同样的调用并返回带有已解析日期的结果。langchain-aws 1.9.3 和 AgentCore Python SDK 1.26.0 增加了对 Web Search API 的支持，因此请安装这些版本或更高版本。

内置的企业级控制

由于 Web Search API 使用标准的 IAM 身份验证，你从第一次调用起就能获得企业级控制：

• IAM 策略。按用户、组或角色授予或拒绝 bedrock-agentcore:InvokeWebSearch。使用 服务控制策略（SCP）在多个账户之间强制执行防护规则。
• AWS CloudTrail 日志。CloudTrail 将 InvokeWebSearch 请求记录为数据事件。数据事件默认不记录，因此需要在跟踪或事件数据存储中为 AWS::BedrockAgentCore::WebSearch 资源类型添加事件选择器。事件记录的是 web search 工具和 maxResults，而不是搜索文本或筛选条件。详情请参阅 Log AgentCore Web Search API calls with AWS CloudTrail。
• VPC 支持。使用 AWS PrivateLink 通过你的私有网络而非公共互联网路由 API 调用。有关设置和端点策略，请参阅本文后面的“使用 AWS PrivateLink 实现私有连接”。
• 合规性。有关涵盖 AgentCore 的合规计划列表，请参阅 Compliance validation for Amazon Bedrock AgentCore。
• 搜索留在 AWS 内。查询由 Amazon 运营的网络索引提供服务，不会发送给第三方搜索引擎。
• 可接受使用。Web Search Tool 的条款同样适用于 API 结果，包括保留并显示随每个结果附带来源引用和链接的要求。详情请参阅 Web Search API Acceptable Use documentation。

配额按账户计算。有关默认值以及如何请求提升配额，请参阅 Quotas for Amazon Bedrock AgentCore。

默认情况下，每个账户在每个区域最多可发送每秒 10 个请求，你可以请求提升配额。详情请参阅 AgentCore Web Search Service Quotas。

使用 AWS PrivateLink 实现私有连接

处理敏感数据的智能体和管道通常运行在没有互联网路由的私有子网中。借助 AWS PrivateLink，这些代码可以通过你 VPC 中的接口 VPC 端点调用 Web Search API。你的 VPC 与 API 之间的流量始终留在 AWS 网络内，并且你无需互联网网关、NAT 网关或代理即可访问它。

图 2：通过 AWS PrivateLink 调用 Web Search API

编号步骤如下：

1. 你的应用程序以 API 的标准区域名称调用 InvokeWebSearch。启用私有 DNS 后，该名称会解析为你子网中的接口端点。
2. 端点策略生效，请求通过 AWS 网络到达 API。
3. API 向 IAM 验证调用者是否具有 bedrock-agentcore:InvokeWebSearch，包括任何 aws:SourceVpce 条件。
4. API 应用请求的筛选条件，并搜索由 Amazon 运营的网络索引。
5. 结果通过端点返回到您的应用程序。

要进行设置，请在每个调用该 API 的 VPC 和区域中，为 AgentCore 数据平面服务创建一个接口端点 com.amazonaws.<Region>.bedrock-agentcore，并开启私有 DNS：

aws ec2 create-vpc-endpoint \
    --region us-west-2 \
    --vpc-id vpc-0123456789abcdef0 \
    --vpc-endpoint-type Interface \
    --service-name com.amazonaws.us-west-2.bedrock-agentcore \
    --subnet-ids subnet-0123456789abcdef0 subnet-0fedcba9876543210 \
    --security-group-ids sg-0123456789abcdef0 \
    --private-dns-enabled

开启私有 DNS 后，该 API 的标准区域名称 bedrock-agentcore.us-west-2.amazonaws.com 将解析为端点在您 VPC 内的私有 IP 地址。本文中的 Boto3 和 AWS CLI 示例无需更改即可运行，无需设置端点 URL。端点的安全组必须允许来自调用该 API 的资源的入站 HTTPS（端口 443）流量。

PrivateLink 还在 IAM 之上为您提供额外的控制手段：

1. Endpoint policies – A VPC endpoint policy applies to InvokeWebSearch requests in addition to your IAM policies, so you decide which principals can search through the endpoint. The same endpoint also carries the other AgentCore data plane APIs, such as AgentCore runtime, a capability of Amazon Bedrock AgentCore, Memory, Identity, Browser, and Code Interpreter. If workloads in the VPC call them too, add statements that allow those calls. The following policy lets only one role call the API through the endpoint:

   {
       "Effect": "Allow",
       "Principal": { "AWS": "arn:aws:iam::111122223333:role/WebSearchAppRole" },
       "Action": "bedrock-agentcore:InvokeWebSearch",
       "Resource": "arn:aws:bedrock-agentcore:us-west-2:aws:tool/web-search.v1"
   }

2. Require the private path – Add an aws:SourceVpce condition to the IAM policy that grants the permission. The role can then search only through your endpoint, and the same call from outside the VPC is denied:

   {
       "Effect": "Allow",
       "Action": "bedrock-agentcore:InvokeWebSearch",
       "Resource": "arn:aws:bedrock-agentcore:us-west-2:aws:tool/web-search.v1",
       "Condition": { "StringEquals": { "aws:SourceVpce": "vpce-0123456789abcdef0" } }
   }

3. 网络级控制 – 安全组和子网位置决定了哪些实例、容器和函数能够访问该端点。

在 Web Search API 可用的每个区域中，PrivateLink 的工作方式都相同。接口端点按标准 AWS PrivateLink 定价计费。详情请参阅 通过 AWS PrivateLink 调用 AgentCore Web Search。

在控制台中试用

在编写任何代码之前，您可以在 Amazon Bedrock AgentCore 控制台中试用 Web Search API。在导航窗格中的 Connections（连接）下，选择 Web Search。

图 3：Amazon Bedrock AgentCore 控制台中的 Web Search

1. Configure. In the Configure panel, set:
   1. Max results（最大结果数）：每个查询返回多少条结果，范围为 1–25。控制台默认为 10。
   2. Published date（发布日期）：YYYY/MM/DD 格式的日期范围。只返回在该范围内发布的结果。留空则包含任意日期的结果。
   3. 域过滤：最多 100 个要包含的域和最多 100 个要排除的域。选择 View and manage domains（查看和管理域）来编辑这些列表。
2. 测试。在 Test Web Search API（测试 Web Search API）面板中输入最多 200 个字符的查询。每个查询都会使用您的设置调用 Web Search API。该面板显示返回了多少条结果以及调用耗时多久。对于每条结果，它会显示标题、文本摘要、发布日期和来源 URL。图 4 展示了一个针对“如何设置 Amazon S3 生命周期规则？”的搜索，结果仅限于 aws.amazon.com 和 docs.aws.amazon.com。

图 4：包含指定域的测试搜索

1. Integrate. When the results look right, you have two options:
   1. 生成代码片段：获取使用相同设置调用该 API 的代码，可直接粘贴到您的智能体或应用程序中。
   2. 创建网关目标：将 Web Search 添加为 AgentCore Gateway 上的一个工具，以便智能体可以通过 MCP 调用它。

控制台会使用您自己的 IAM 身份对每次调用进行签名，因此您的角色需要 bedrock-agentcore:InvokeWebSearch 权限。

相比网关，何时使用该 API

两种路径搜索的是同一个索引。它们之间存在一些差异：网关还可以使用 JSON Web Token (JWT) 对调用方进行授权，而 API 仅使用 IAM 进行授权。在网关上，管理员可以在目标上设置域名列表，使其适用于每个请求，而调用智能体无法看到这些列表。使用 API 时，每个请求都携带自己的过滤器。字段名称也不同：API 使用 searchQuery、publishedAfter 和 publishedBefore，而网关的 MCP 工具使用 query、from 和 to。更多指南请参阅 在 API 与网关连接器之间做出选择。

定价

Web Search API 与网关连接器使用相同的用量类型计费，因此按 Web Search 每 1,000 次查询 7 美元的费率计费。由于不涉及网关，因此不会产生网关费用。详情请参阅 Amazon Bedrock AgentCore 定价。

可用性

Web Search API 在美国东部（弗吉尼亚北部）、美国东部（俄亥俄）、美国西部（俄勒冈）、欧洲（爱尔兰）、亚太地区（东京）和亚太地区（悉尼）区域可用。有关当前列表，请参阅 支持的 AWS 区域。

开始使用

使用以下资源帮助您入门。

• Web Search API 文档
• Amazon Bedrock AgentCore 上的 Web Search
• InvokeWebSearch API 参考

关于作者