AWS 教程：用 LangGraph 和 Amazon Bedrock AgentCore Web Search 构建每日依赖监控智能体

AI 智能体越来越多地承担依赖“今天发生了什么变化”的工作，例如安全公告、产品发布、价格和法规。模型的训练数据无法回答这些问题，因此智能体需要网络搜索。对于生产环境，团队还需要可引用的结果，以及控制哪些来源算数。他们希望搜索查询保留在自己的云环境中，因为这些查询往往会暴露内部工作内容。

Amazon Bedrock AgentCore 中的 Web Search API 现已推出。它让智能体和应用程序通过单次 API 调用获取最新的网络结果，并使用它们已有的 AWS 凭证进行签名。AWS 使用 Amazon 自营的网络索引处理每个查询，不会将其发送给第三方搜索引擎。

每条结果都包含页面标题、URL、发布日期以及与查询相关的摘录。请求可以包含或排除特定域名，并将结果限制在某个发布日期范围内。在 AWS Lambda、Amazon Elastic Container Service (Amazon ECS) 或 Amazon Bedrock AgentCore runtime 上，您的智能体使用其执行角色调用该 API。无需存储或轮换搜索 API 密钥。Web Search on Amazon Bedrock AgentCore 也可以通过 Amazon Bedrock AgentCore 的一项功能 AgentCore Gateway 使用。在那里，一个管理员来源策略即可覆盖每个智能体和 Model Context Protocol (MCP) 客户端。

对于 LangChain 开发者而言，LangChain 的 AWS 集成中的 AgentCore web search 工具现在会调用 Web Search API。一次函数调用即可为智能体提供最新且带引用的搜索结果。该工具还可以承载模型无法更改的规则，例如日期窗口、来源黑名单和搜索预算。它以数据形式返回结果，供您的代码进行校验。它适用于 LangChain 智能体、运行这些智能体的编排框架 LangGraph，以及添加了子智能体、虚拟文件系统和上下文压缩功能的 Deep Agents。

在这篇文章中，您将基于 Web Search API 为安全团队构建一个每日依赖项监控，形式为一个 LangGraph 图。每天早上，该监控会检查是否有新的内容影响团队所发布的开源软件包和容器基础镜像。它并行研究三个软件包生态系统，同时由您的代码将日期窗口、黑名单和搜索预算保持在模型控制之外。它会将每条发现与其引用的来源进行核对，并记住已经报告过的内容。然后，您将在 AgentCore runtime 上运行该监控，并通过 AgentCore Gateway 向各团队提供服务。在我们的测试中，三个分支在 36 秒内完成，而逐个执行则需要 99 秒。

解决方案概述

模型决定搜索什么并撰写发现。所有必须成立的规则，无论模型做什么，都保留在代码中：日期窗口、黑名单、搜索预算，以及对每条发现的校验。图 1 展示了从 notebook 运行监控时这些部分如何组合在一起。

图 1：使用 LangGraph 和 Web Search API 从 notebook 运行的每日依赖项监控

编号步骤如下：

一次运行会将监控清单和监控窗口输入图中，启动该图。
fan_out 为每个生态系统启动一个研究分支：npm、PyPI 和容器基础镜像。LangGraph 并行运行这三个分支。
在每个分支内部，智能体会调用 Anthropic Claude 模型（托管于 Amazon Bedrock）。该模型决定搜索什么内容，并在最后生成结构化的调查结果。
分支的搜索工具会为每个查询添加日期窗口和屏蔽列表。它使用经 AWS Signature Version 4 (SigV4) 签名的请求调用 Web Search API。第 3 步和第 4 步会重复进行，每个分支最多搜索四次，所有分支同时运行。
每个分支只保留其来源支持的、且落在时间窗口内的调查结果。当三个分支全部完成后，LangGraph 会合并它们的调查结果，并运行一次 keep_new。
keep_new 会检查 LangGraph store 并记录新的调查结果，因此不会有任何内容被重复报告。
report 会为安全团队构建带有引用来源的新调查结果表格。

前提条件

在开始之前，您需要满足以下条件：

一个 AWS 账户，工作在提供 Web Search API 的 AWS 区域。示例使用美国东部（弗吉尼亚北部）区域 (us-east-1)。有关其他区域，请参阅支持的 AWS 区域。
Python 3.10 或更高版本。
运行 notebook 的身份所需的 AWS 凭证，来自环境变量或 AWS Command Line Interface (AWS CLI) 配置文件。该身份需要第 1 步中的 AWS Identity and Access Management (IAM) 权限，以及对 Amazon Bedrock 中 Anthropic Claude 模型的访问权限。
The following Python packages: boto3 1.43.127 or later, the AgentCore Python SDK (bedrock-agentcore) 1.26.0 or later, and langchain-aws 1.9.3 or later. Install them with this pip command:
```
pip install -U "boto3>=1.43.127" "bedrock-agentcore>=1.26.0" "langchain-aws[tools]>=1.9.3" langchain langgraph
```

Web Search 和模型调用按使用量计费。详情请参阅 Amazon Bedrock AgentCore pricing。监视的一次运行最多进行 12 次搜索。

完整代码见这个 notebook。notebook 会运行每个单元格，包括设置部分。以下步骤涵盖与搜索相关的关键部分。

第 1 步：授予权限

首先，为您运行时使用的身份授予搜索权限。Web Search API 需要对一个 AWS 拥有的资源执行一个 IAM 操作，因此该语句在每个账户中都相同。（完整设置请参阅授予调用 API 的权限。）这里使用的权限与网关的服务角色用于网络搜索的权限相同：

{
  "Effect": "Allow",
  "Action": "bedrock-agentcore:InvokeWebSearch",
  "Resource": "arn:aws:bedrock-agentcore:us-east-1:aws:tool/web-search.v1"
}

第 2 步：构建一个带有固定规则的搜索工具

现在构建每个研究分支都会使用的搜索工具。监视功能不能让模型自行选择日期窗口、可信来源或搜索次数。该图还需要将返回的来源作为数据，以便稍后据此核查调查结果。langchain-aws 包中的网络搜索工具包通过其选项提供了所有这些功能：

toolkit, tools = create_web_search_toolkit(
    region="us-east-1",
    exclude_domains=BLOCKLIST,
    published_after=window_start.strftime("%Y-%m-%dT%H:%M:%SZ"),
    model_filters=False,
    max_searches=4,
    return_sources=True,
)

在没有 gateway 参数的情况下，该工具会调用 Web Search API。每次搜索都会带上屏蔽列表和日期下限，模型自己的参数只能对其进一步收窄。使用 model_filters=False 时，模型只能看到一个查询参数。该工具在四次搜索后停止，并两次返回结果：以文本形式返回给模型，以工件形式返回给图。每个分支都创建自己的工具包，因此各分支可以并行搜索。您也可以将相同的工具提供给 Deep Agents 子智能体。

第 3 步：定义调查结果 schema

搜索工具就绪后，定义每个分支返回的内容。每个分支都是一个 create_agent 智能体，使用 Pydantic schema 作为其响应格式，因此它返回的是结构化的调查结果而不是散文式文字。每条调查结果包含软件包名称、一行标题，以及来源提供的 CVE 或公告 ID（如果有的话）。它还包括来源声明的严重程度、来源是否指出该漏洞已被利用、建议的操作，以及来源 URL。完整 schema 和提示词见 notebook。

第 4 步：构建图及其证据核查

现在开始组装图。fan_out 使用 LangGraph 的 Send API 为每个生态系统发送一个分支，这样各分支可以并行运行。

在分支返回之前，代码会对每条发现运行四项检查。这些检查将发现结果与该分支自身搜索返回的内容进行比对：

被引用的 URL 来自该分支的某次搜索。
来源的标题或文本以完整单词的形式提到了该软件包。
发现结果中的任何 CVE 或公告 ID 都出现在该文本中。
来源的发布日期落在监视窗口内。工件已携带每个已解析的日期，缺失的日期视为在窗口之外。

在所有分支完成后，keep_new 将存活下来的发现与 LangGraph store 进行比对，然后由 report 构建表格。这些检查可以捕获不支持的 URL、未提及软件包的来源、虚构的 ID 以及窗口之外的来源。它们不会确认严重性、是否已被利用、受影响的版本或建议的操作。它们也无法证明问题首次披露的时间：索引标注为本周的页面可能描述的是更早的事件。对于生产环境的安全工作流，请对照权威的漏洞订阅源验证发现结果。在任何人采取行动之前，应有人先审查该发现。

第 5 步：运行监视

你已经准备好以 7 天窗口运行监视了。在我们的运行中，三个分支共执行了 12 次搜索，获取了 80 个来源。它们在 36 秒的墙上时间内完成，而各分支相加需要 99 秒。证据检查剔除了两条发现：一条的来源未提及软件包，另一条的 CVE ID 未出现在其来源中。没有来源来自被屏蔽的域名。

四项发现通过了检查，其中 keep_new 报告了两项。更早的测试运行已经报告了另外两项，因此存储将它们暂扣。图 2 展示了 LangGraph Studio（LangGraph 的可视化调试器）中的这次运行。报告的每一行都链接到其来源，这是 Web Search 可接受使用条款对任何展示给用户的输出所要求的内容。

图 2：在 LangGraph Studio 中运行依赖监视。右侧的三个研究条目是三个生态系统分支，LangGraph 让它们并行运行。报告只列出通过了证据检查且此前未被报告过的发现，每条都链接到其来源

第 6 步：再次运行监视，只查看新发现

最后，再运行一次监视，看看 store 的作用。定时监视每天运行一次，团队不应看到同一条公告两次。在我们的第二次运行中，各分支再次搜索并保留了两个发现，而 store 此前都已报告过。因此报告没有新内容，如图 3 所示。

图 3：使用相同输入的第二次运行。各分支再次搜索，但 keep_new 发现每个结果都已存在于 LangGraph store 中，因此报告没有新内容

对于定时任务，将 InMemoryStore 替换为支持精确键查询的持久化 store，例如来自 langgraph-checkpoint-aws 的 DynamoDBStore。

在现有的 LangChain 或 Deep Agents 应用中添加网络搜索

如果你已经有一个 LangChain 智能体，添加网络搜索只需几处更改。在部署前请检查以下内容：

权限：将第 1 步的声明添加到你的应用已在使用的身份或执行角色中。无需创建其他任何内容。
区域：工具包的 Region 必须提供 Web Search API，并且它可以与你的模型或应用其余部分的 Region 不同。
工具名称：该工具名为 web_search。如果你的智能体已经有同名工具，例如另一个搜索提供商，请在添加之前为该工具设置一个不同的名称。
规则与预算：每个工具包都有自己的过滤器和搜索预算。为每个需要独立规则或独立预算的智能体或分支分别创建一个工具包。
吞吐量：一个账户中的所有智能体共享该账户的 Web Search 配额，因此并行分支会累加。默认情况下，每个账户在每个区域每秒可发送 10 个请求。详情请参阅 Amazon Bedrock AgentCore 的配额。

在 Deep Agents 中，你使用 create_deep_agent 来定义智能体：模型、工具、系统提示词和子智能体。将工具包的工具传入子智能体的工具列表。将规则设置为工具包选项，因为该工具会在每次搜索时应用这些规则，无论模型要求什么。要对照来源检查搜索结果（如第 4 步所示），可以在智能体的输出上运行该检查，或将其添加为中间件。在我们的测试中，一个 Deep Agents 协调器将任务委派给一个拥有这些工具的研究子智能体，并在约一分钟内返回了带有引用来源的答案。

将其部署到 AgentCore runtime 上投入生产

当你准备好在没有笔记本环境的情况下每天运行这个监控任务时，可以将其托管在 AgentCore runtime 上。Runtime 可以运行用任何框架构建的智能体，包括 LangGraph，无需重写。它通过相同的 API 提供两种计算类型。MicroVM（默认类型）为每个会话提供独立的隔离 microVM，因此一次运行无法看到另一次运行的数据。Instances 则在你自己的账户中由 AWS 托管的 Amazon Elastic Compute Cloud (Amazon EC2) 实例上运行你的智能体。它们适合持续多天的会话、GPU 工作负载，或多个智能体共享一个实例的场景。

关于两者的限制，请参阅为智能体使用隔离会话和 Runtime Instances 与容量提供程序。笔记本旁边的 Runtime 示例将相同的图作为 Runtime 入口点承载。其策略仅授予 Runtime 执行角色第 1 步的权限，不授予更广泛的访问权限。其 README 演示了如何在任一计算类型上使用 AgentCore CLI 创建、部署和调用该项目。

图 4：托管在 AgentCore runtime 上的同一个依赖监控任务。第 2 步到第 7 步与图 1 一致，每次搜索均由 Runtime 执行角色签名。第 1 步，调用方调用 runtime，例如使用 agentcore invoke。第 8 步，runtime 返回报告

Runtime 会话状态是临时性的，因此内存存储仅在会话期间有效。每日任务需要第 6 步中的持久化存储，并按计划调用。

使用 AgentCore Gateway 将监控任务扩展到多个团队

Web Search API 和 AgentCore Gateway 上的 Web Search Tool 搜索的是同一个索引，相同的图在两者上都可以运行。选择依据是由谁来执行规则以及由谁调用搜索：

当你的应用程序自行调用搜索并执行自己的规则时（如第 1 步到第 6 步），使用 Web Search API。它只需要一个 IAM 权限。
当平台团队向多个智能体或团队提供搜索服务，并希望 AWS 对每次搜索应用统一的管理员来源策略时，使用 AgentCore Gateway。该策略位于网关目标上，对智能体是隐藏的，智能体无法将其解除。
当 Claude 等 MCP 客户端需要搜索功能，或者你希望将网络搜索与其他工具一起放在同一个 MCP 端点之后时，使用 AgentCore Gateway。

笔记本的可选步骤 7 通过网关运行该监视程序。它创建一个把阻止列表作为管理员策略携带的网页搜索目标，因此搜索客户端不再添加它。这条路线需要在两个不同主体上授予两个 IAM 权限。网关的服务角色需要对网页搜索工具的 bedrock-agentcore:InvokeWebSearch 权限。你的智能体签署凭据所用的身份需要对网关的 bedrock-agentcore:InvokeGateway 权限。图 5 展示了这一流程。

图 5：通过 AgentCore Gateway 运行同样的依赖项监视。该图与图 1 相同。在第 4 步，搜索工具通过 MCP 调用 AgentCore Gateway，并使用 SigV4 签名。在第 5 步，网页搜索目标应用管理员阻止列表并调用 AgentCore Web Search

要让每个团队拥有自己的策略，为每个团队添加一个网页搜索目标，每个目标都有自己的阻止列表。这个演练笔记本展示了该模式。有关此路线的更多信息，请参阅Web Search Tool。

清理

步骤 1–6 不会创建任何 AWS 资源。如果你仅为本文添加了步骤 1 的权限，请从附加该权限的身份中移除它。如果你运行了步骤 7，请删除目标与网关以避免持续收费。当你设置 DELETE_GATEWAY = True 时，笔记本的最后一个单元格会执行此操作。

target = gateway_client.get_gateway_target_by_name(GATEWAY_ID, "security-sources")
gateway_client.delete_gateway_target_and_wait(gatewayIdentifier=GATEWAY_ID, targetId=target["targetId"])
gateway_client.delete_gateway_and_wait(gatewayIdentifier=GATEWAY_ID)

笔记本会保留网关的服务角色，以便其他网关可以使用它。当不再需要时，请在 IAM 控制台中删除它。如果你部署到了 Runtime，请在项目文件夹中运行 agentcore remove all，然后运行 agentcore deploy -y。

结论

Amazon Bedrock AgentCore 中的 Web Search API 使用智能体已经在使用的 AWS 凭据，为 LangChain 智能体提供最新的、带引用的网页结果。依赖项监视展示了如何超越单次工具调用。将模型不可更改的规则保留在代码中，并将返回的来源作为模型上下文之外的数据保存。检查一切可检查的内容，并在用户看到的所有内容中保留引用。当更多团队需要相同的搜索时，AgentCore Gateway 会将一个策略应用于所有团队。

要开始使用，请打开该笔记本。作为参考，请参阅 LangChain 文档中的Amazon Bedrock AgentCore Web Search 集成页面以及使用 Amazon Bedrock AgentCore Web Search 搜索网络。