Add secure Web Search to Claude Desktop with Amazon Bedrock AgentCore

通过 Amazon Bedrock AgentCore 为 Claude Desktop 添加安全网络搜索 | 人工智能

通过 Amazon Bedrock AgentCore 为 Claude Desktop 添加安全网络搜索

基于 Amazon Bedrock 的 Claude Desktop 提供了强大的 AI 协助功能，但缺少集成网络搜索功能时，响应结果将局限于模型训练知识的截止时间。当需要获取实时信息（如最新文档更新、实时价格或天气信息）时，模型无法自主获取这些信息。

Amazon Bedrock AgentCore 是一个用于构建、连接和大规模优化代理的平台，支持任意框架或模型。通过 AgentCore Gateway（Amazon Bedrock AgentCore 的一项功能），您可以将 Claude Desktop 连接到网络搜索功能，从而弥补知识截止时间的差距。网络搜索是一项完全托管的、兼容模型上下文协议（MCP）的网络搜索能力，依托 Amazon 的网络索引，覆盖数十亿文档。所有查询流量均保留在 AWS 基础设施内，无需管理外部 API 密钥，且查询不会离开您的边界。

使用 Claude Desktop 时，您可以使用托管的 MCP 服务器通过启用网络搜索目标的 AgentCore Gateway 进行连接。在本文中，我们将逐步演示如何设置此集成，并使用基于 JSON Web Token（JWT）的入站身份验证来保障通信安全。

架构

许多在 AWS 上运行的企业使用 AWS IAM Identity Center 实现对 AWS 账户的单点登录（SSO）访问。在本操作指南中，我们使用 AWS IAM Identity Center 作为 AgentCore Gateway 的身份验证来源。通过此设置，基于 Amazon Bedrock 的 Claude Desktop 可通过受信任的企业托管身份流程调用网络搜索。这种方法与现有的组织身份治理策略保持一致，无需单独凭据或第三方身份提供商。

为了将 AWS IAM Identity Center 与 AgentCore Gateway 的 JWT 身份验证进行连接，我们使用 Amazon Cognito 作为联邦层，并采用 OAuth 2.0 授权码授予流程。IAM Identity Center 通过安全断言标记语言（SAML）处理用户身份验证。Amazon Cognito 发行 JWT，AgentCore Gateway 在每次请求时验证这些令牌。整个身份验证链完全保留在 AWS 内部。

下图展示了该身份验证流程的序列图。

图 1：用户身份验证和授权序列图

先决条件

要按照本文步骤操作，您需要以下内容：

• 具有创建 AWS 身份和访问管理（IAM）角色及 Amazon Bedrock AgentCore 资源权限的 AWS 账户。

• 对 AWS Organizations 管理账户具有管理员访问权限（用于 AWS IAM Identity Center 配置）。

• 已预先配置 AWS IAM Identity Center 以实现对 AWS 账户的 SSO 访问。

• 已使用 Amazon Bedrock 作为推理提供者的 Claude Desktop。

• 已安装并配置 AWS 命令行界面（AWS CLI）v2。

• Python 3.10 或更高版本。

• 已更新到最新版本的 Boto3 SDK。

目前，Amazon Bedrock AgentCore 的网络搜索功能仅在以下 AWS 区域可用：美国东部（弗吉尼亚北部）区域（us-east-1）、欧洲（爱尔兰）区域（eu-west-1）和亚太（东京）区域（ap-northeast-1）。请确认您的网关创建在这些区域中的一个。

配置包括设置认证链（AWS IAM Identity Center 到 Amazon Cognito 到 JWT），然后将 AgentCore Gateway 集成到 Claude Desktop。以下部分将逐步指导您完成每个步骤。

步骤1：创建 Amazon Cognito 用户池

在目标 AWS 账户中创建 Amazon Cognito 用户池，该用户池将作为 AgentCore Gateway 的 OpenID Connect (OIDC) 令牌颁发者。

export AWS_REGION=<your-region>

# 创建用户池
aws cognito-idp create-user-pool \
  --pool-name "agentcore-websearch-pool" \
  --region $AWS_REGION \
  --auto-verified-attributes email \
  --schema '[{"Name":"email","Required":true,"Mutable":true,"AttributeDataType":"String"}]' \
  --username-attributes email \
  --username-configuration "CaseSensitive=false" \
  --mfa-configuration "OFF"

# 记录用户池 ID
export USER_POOL_ID=$(aws cognito-idp list-user-pools --max-results 10 \
  --region $AWS_REGION \
  --query "UserPools[?Name=='agentcore-websearch-pool'].Id" --output text)
echo "User Pool ID: $USER_POOL_ID"

# 创建域名（必须全局唯一）
aws cognito-idp create-user-pool-domain \
  --domain "<your-unique-prefix>" \
  --user-pool-id $USER_POOL_ID \
  --region $AWS_REGION

保存以下值以供后续步骤使用：

• 用户池 ID: $USER_POOL_ID
• 域名: <your-unique-prefix>.auth.<region>.amazoncognito.com
• 审众: urn:amazon:cognito:sp:<user-pool-id>
• ACS URL: https://<your-unique-prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse

步骤2：配置 IAM Identity Center SAML 应用

在 AWS Organizations 管理账户中创建一个与 Cognito 联合的 SAML 应用：

• 打开 IAM Identity Center 控制台
• 选择 应用程序 > 添加应用程序 > 我有需要配置的应用程序 > SAML 2.0 > 下一步
• 填写以下信息：显示名称：AgentCore Web Search；选择手动输入元数据值；ACS URL：https://<your-unique-prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse；审众：urn:amazon:cognito:sp:<user-pool-id>；下载 SAML 元数据 XML 文件并提交
• 应用创建后，编辑属性映射并插入以下值：主体 ${user:subject}（格式：Persistent）；邮箱 ${user:email}（格式：Basic）；分配可访问 Web Search 的用户或组

步骤3：将 SAML IdP 集成到 Cognito

返回目标账户，在 Cognito 用户池中注册 IAM Identity Center 作为 SAML 身份提供商：

# 添加 IAM Identity Center 作为 SAML IdP
METADATA=$(cat /path/to/downloaded-metadata.xml)

aws cognito-idp create-identity-provider \
  --user-pool-id $USER_POOL_ID \
  --provider-name "IAMIdentityCenterIdP" \
  --provider-type SAML \
  --provider-details "{\"MetadataFile\": $(echo "$METADATA" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')}" \
  --attribute-mapping '{"email": "email"}' \
  --region $AWS_REGION

步骤4：为 Amazon Bedrock AgentCore 创建 Cognito 应用客户端

创建带有客户端密钥的应用客户端。Claude Desktop 使用该客户端启动 OAuth 流程，通过 IAM Identity Center 认证用户并获取 AgentCore Gateway 的 JWT：

aws cognito-idp create-user-pool-client \
  --user-pool-id $USER_POOL_ID \
  --client-name "agentcore-websearch-client" \
  --generate-secret \
  --supported-identity-providers "IAMIdentityCenterIdP" \
  --callback-urls '["http://localhost:53280/callback"]' \
  --allowed-o-auth-flows code \
  --allowed-o-auth-scopes "openid" "email" "profile" \
  --allowed-o-auth-flows-user-pool-client \
  --region $AWS_REGION

注意输出中的客户端ID和客户端密钥。这些是您的应用程序客户端ID和密钥。

第5步：使用网络搜索工具配置AgentCore网关

在此步骤中，我们创建一个新的AgentCore网关，入站认证类型设置为JSON网络令牌（JWT）。为此配置，我们使用在前面步骤中创建的Cognito用户池ID和应用程序客户端ID。

运行以下Python脚本来创建网关并进行所需配置，将所有占位符替换为环境中的实际值。

import boto3
import json
import time

session = boto3.Session(region_name="your-region")
iam_client = session.client("iam")
gateway_client = session.client("bedrock-agentcore-control")

ACCOUNT_ID = "your-target-aws-account-id"
ROLE_NAME = "websearch-gateway-role"
GATEWAY_NAME = "websearch-gateway"
COGNITO_DISCOVERY_URL = "https://cognito-idp.<your-region>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration"
COGNITO_CLIENT_ID = "<cognito-application-client-id>"

# --- 第1步：创建IAM执行角色 ---
trust_policy = {
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
        "Action": "sts:AssumeRole",
        "Condition": {
            "StringEquals": {"aws:SourceAccount": ACCOUNT_ID}
        }
    }]
}

permissions_policy = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "GetGateway",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:GetGateway",
            "Resource": f"arn:aws:bedrock-agentcore:us-east-1:{ACCOUNT_ID}:gateway/*"
        },
        {
            "Sid": "GetConfigBundle",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:GetConfigurationBundleVersion",
            "Resource": f"arn:aws:bedrock-agentcore:us-east-1:{ACCOUNT_ID}:configuration-bundle/*"
        },
        {
            "Sid": "InvokeWebSearch",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:InvokeWebSearch",
            "Resource": "arn:aws:bedrock-agentcore:us-east-1:aws:tool/web-search.v1"
        }
    ]
}

try:
    iam_client.create_role(
        RoleName=ROLE_NAME,
        AssumeRolePolicyDocument=json.dumps(trust_policy),
        Description="用于网络搜索AgentCore网关的执行角色",
    )
    print(f"✓ 已创建角色 '{ROLE_NAME}'。")
except iam_client.exceptions.EntityAlreadyExistsException:
    print(f"✓ 角色 '{ROLE_NAME}' 已存在，正在复用。")

iam_client.put_role_policy(
    RoleName=ROLE_NAME,
    PolicyName="websearch-gateway-policy",
    PolicyDocument=json.dumps(permissions_policy),
)
print(f"✓ 已将内联策略附加到 '{ROLE_NAME}'。")

--- 第 2 步：创建网关 ---

response = gateway_client.create_gateway( name=GATEWAY_NAME, description="带托管 Web 搜索连接器的 AgentCore 网关", roleArn=f"arn:aws:iam::{ACCOUNT_ID}:role/{ROLE_NAME}", protocolType="MCP", protocolConfiguration={ "mcp": { "supportedVersions": ["2025-03-26"], } }, authorizerType="CUSTOM_JWT", authorizerConfiguration={ "customJWTAuthorizer": { "discoveryUrl": COGNITO_DISCOVERY_URL, "allowedClients": [COGNITO_CLIENT_ID], } }, ) gateway_id = response["gatewayId"] gateway_url = response.get("gatewayUrl") print(f"✓ 网关已创建: {gateway_id}") print(f" URL: {gateway_url}")

--- 第 3 步：等待网关变为 READY 状态 ---

print(" 正在等待网关达到 READY 状态...", end="", flush=True) for i in range(40): # 最多等待约 10 分钟 resp = gateway_client.get_gateway(gatewayIdentifier=gateway_id) status = resp.get("status") if status == "READY": print(f" READY (耗时 {(i+1)*15}s)") break elif status == "FAILED": print(f"\n✗ 网关进入 FAILED 状态。") reasons = resp.get("statusReasons", []) for r in reasons: print(f" 原因: {r}") exit(1) print(".", end="", flush=True) time.sleep(15) else: print(f"\n✗ 10 分钟内网关未达到 READY 状态 (最后状态: {status})") exit(1)

--- 第 4 步：附加托管 Web 搜索连接器目标 ---

gateway_client.create_gateway_target( gatewayIdentifier=gateway_id, name="web-search-tool", description="托管 Web 搜索连接器", targetConfiguration={ "mcp": { "connector": { "source": {"connectorId": "web-search"}, "configurations": [{"name": "WebSearch", "parameterValues": {}}], } } }, credentialProviderConfigurations=[ {"credentialProviderType": "GATEWAY_IAM_ROLE"} ], ) print("✓ 已附加 Web 搜索目标。") print() print("=" * 60) print(f" 网关 ID: {gateway_id}") print(f" 网关 URL: {gateway_url}") print(f" 认证: CUSTOM_JWT (Cognito)") print(f" 目标: web-search (托管连接器)") print("=" * 60)

现在您已拥有一个带有 Web 搜索工具的 AgentCore 网关，并使用基于 JWT 的入站授权。

### 第 6 步：配置 Claude Desktop

按照 Claude Desktop 配置文档中的步骤，访问 Claude Desktop 与 Amazon Bedrock 的配置窗口。打开后，选择“连接器和扩展”，然后选择“添加服务器”，再选择“空白”。

下图展示了包含这些选项的配置窗口。

图 2: Claude Desktop 连接器配置窗口

请输入以下信息：

- 名称: websearchtool。

- 传输方式: Streamable HTTP。

- URL: 输入第 5 步创建的 AgentCore 网关资源 URL。

- OAuth: 使用自有客户端。

- 客户端 ID: 输入第 4 步创建的应用客户端的客户端 ID。

- 客户端密钥: 输入第 4 步创建的应用客户端的客户端密钥。

- 授权服务器: 输入 ["https://<your-unique-prefix>.auth.<region>.amazoncognito.com/oauth2/authorize"] 。

- 作用域: openid。

- 回调主机: localhost 。

- 回调端口: 53280。

完成操作后，请选择“登录并测试”。这将打开浏览器以进行身份验证，并将您重定向到 AWS IAM Identity Center SSO 登录页面。输入凭据进行身份验证。如果成功，您应该会看到类似“授权完成。您可以关闭此标签页并返回 Claude”的消息。

回到 Claude Desktop 后，您应该会看到类似下图的 MCP 注册成功提示。

图 3：Claude Desktop 中成功的 MCP 服务器注册

现在，Claude Desktop 将通过 MCP 工具列表调用发现 WebSearchTool。每当模型需要从网络获取最新信息时，它会自动调用该工具。

## 测试与验证

在您首选的界面（例如聊天或协作）中，发送需要 Claude Desktop 获取最新结果的查询。您应该会看到一个工具执行批准框，表明 Claude 已成功发现 Web Search 工具。批准后，您应该会在响应中看到网络搜索结果。

图 4：Web Search 工具执行批准对话框

对话框会显示 Claude 想要运行的查询，并提供三个选项：拒绝、仅允许此次任务或仅允许一次。批准后，Web Search 结果将包含在响应中。

## 清理

如果在操作过程中创建了资源，请执行以下步骤删除它们：

删除网关目标

aws bedrock-agentcore-control delete-gateway-target --gateway-identifier <gateway-id> --target-id <target-id> --region $AWS_REGION

删除网关（仅当它是为此操作指南创建的）

aws bedrock-agentcore-control delete-gateway --gateway-identifier <gateway-id> --region $AWS_REGION

删除 IAM 策略（仅当它是为此操作指南创建的）

aws iam delete-role-policy --role-name websearch-gateway-role --policy-name websearch-gateway-policy

删除 IAM 角色（仅当它是为此操作指南创建的）

aws iam delete-role --role-name websearch-gateway-role

删除 Cognito 应用程序客户端

aws cognito-idp delete-user-pool-client --user-pool-id $USER_POOL_ID --client-id <client-id> --region $AWS_REGION

删除 Cognito 身份提供商

aws cognito-idp delete-identity-provider --user-pool-id $USER_POOL_ID --provider-name IAMIdentityCenterIdP --region $AWS_REGION

删除 Cognito 池域名

aws cognito-idp delete-user-pool-domain --user-pool-id $USER_POOL_ID --domain <your-unique-prefix> --region $AWS_REGION

删除 Cognito 池

aws cognito-idp delete-user-pool --user-pool-id $USER_POOL_ID --region $AWS_REGION

最后，在管理账户的 IAM Identity Center 控制台中，删除步骤 2 中创建的 SAML 应用程序。

## 结论

在本文中，我们介绍了如何将 AgentCore 上的 Web Search 与 Claude Desktop 集成。虽然本操作指南使用 AWS IAM Identity Center 作为身份提供商，但相同的模式也适用于任何 SAML 或 OIDC 兼容的身份提供商。您可以通过在 Amazon Cognito 中将其配置为联合源来替换现有的 IdP。这种方法在不引入第三方依赖的情况下填补了网络搜索的空白，并且所有查询都保留在您的 AWS 范围内。

要开始操作，请按照上述步骤在您自己的环境中设置集成。有关高级网关配置的信息，请参阅《AgentCore 网关开发人员指南》。如需了解有关 Web Search 的更多信息，请参阅《Web Search 文档》。

## 作者简介

'"`