本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 为 VPC 配置亚马逊 Bedrock AgentCore 运行时和工具 您可以配置亚马逊 Bedrock AgentCore 运行时和内置工具（代码解释器和浏览器工具）以连接到您的亚马逊虚拟私有云 (VPC) 中的资源。通过配置 VPC 连接，您可以安全访问私有资源，例如您的 VPC 内的数据库、内部 API 和服务。 ## 亚马逊 Bedrock AgentCore 运行时和工具的 VPC 连接 为了使 Amazon Bedrock AgentCore Runtime 和内置工具能够安全访问您的私有 VPC 中的资源，请 AgentCore 提供 VPC 连接功能。此功能允许您的运行时和工具： + 在不暴露于互联网的情况下连接到私有资源 + 保持组织网络边界内的安全通信 + 访问企业数据存储和内部服务，同时保持安全 当您为亚马逊 Bedrock AgentCore 运行时和工具配置 VPC 连接时： + Amazon Bedrock 使用服务相关角色在您的 VPC 中创建弹性网络接口 (ENI) `AWSServiceRoleForBedrockAgentCoreNetwork` + 这些 ENI 使您的亚马逊 Bedrock AgentCore 运行时和工具能够安全地与您的 VPC 中的资源通信 + 每个 ENI 都会从您指定的子网中分配一个私有 IP 地址 + 附加到 ENI 的安全组控制您的运行时和工具可以与哪些资源通信 **注意** ENI 是使用相同子网和安全组配置的代理之间的共享资源。当您删除代理时，关联的 ENI 可能会在您的 VPC 中保留最多 8 小时，然后才会自动删除。 **注意** VPC 连接会影响来自 AgentCore 服务的入站和出站网络流量。当您在 Amazon VPC 中托管应用程序时，您可以通过将 VPC 终端节点添加到您的 AgentCore VPC 来建立与 AgentCore 运行时和 AgentCore 网关 API 的私有连接。这样可以通过 VPC PrivateLink 入站连接进行安全的 API 调用，而无需遍历互联网。 ## 先决条件 在为 VPC 访问配置亚马逊 Bedrock AgentCore 运行时和工具之前，请确保您具备： + 具有适合您的运行时和工具要求的子网的 Amazon VPC。例如，要将您的子网配置为可以访问互联网，请参阅[互联网访问注意事项](#agentcore-internet-access)。 + 子网位于您所在地区支持的可用区内。有关支持的可用区域的信息，请参阅[支持的可用区域](#agentcore-supported-azs)。 + 在您的 VPC 中为运行时和工具访问模式定义相应的安全组。例如，要将您的安全组配置为连接到 Amazon RDS，请参阅[示例：连接到 Amazon RDS 数据库](#agentcore-security-groups-example)。 + 创建和管理服务相关角色所需的 IAM 权限（已包含在 Amazon 托管策略中 [ BedrockAgentCoreFullAccess](https://docs.amazonaws.cn/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html)）。有关所需权限的信息，请参阅 [ IAM 权限](#agentcore-iam-permissions)。 + 如果您的 VPC 无法访问互联网，则需要 VPC 终端节点。例如，要配置您的 VPC 终端节点，请参阅 [ VPC 终端节点配置](#agentcore-vpc-endpoints)。 + 了解您的运行时和工具网络需求（数据库、API、Web 资源）。如果您需要使用需要互联网访问的浏览器工具，那么您的 VPC 应该可以通过 NAT 网关访问互联网。例如，请参阅[安全组注意事项](#agentcore-security-groups)。 **重要** AgentCore 使用私有 IP 地址在您的账户中创建网络接口。使用公有子网不提供互联网连接。要启用互联网接入，请将其置于私有子网中，并附有一条通往 NAT 网关的路由。 ## 支持的可用区 AgentCore 支持在每个受支持区域内的特定可用区内的 VPC 连接。在为您的 Amazon Bedrock AgentCore Runtime 和内置工具配置子网时，请确保您的子网位于您所在地区支持的可用区内。 下表显示了每个区域支持的可用区 ID： | Region | 区域代码 | 支持的可用区 | | --- | --- | --- | | 美国东部（弗吉尼亚州北部） | us-east-1 | use1-az1 use1-az2 use1-az4 | | 美国东部（俄亥俄州） | us-east-2 | use2-az1 use2-az2 use2-az3 | | 美国西部（北加利福尼亚） | us-west-1 | usw1-az1 usw1-az3 | | 美国西部（俄勒冈州） | us-west-2 | usw2-az1 usw2-az2 usw2-az3 | | 亚太地区（马来西亚） | ap-southeast-5 | apse5-az1 apse5-az2 apse5-az3 | | 亚太地区（孟买） | ap-south-1 | aps1-az1 aps1-az2 aps1-az3 | | 亚太地区（海得拉巴） | ap-south-2 | aps2-az1 aps2-az2 aps2-az3 | | 亚太地区（首尔） | ap-northeast-2 | apne2-az1 apne2-az2 apne2-az3 | | 亚太地区（新加坡） | ap-southeast-1 | apse1-az1 apse1-az2 apse1-az3 | | 亚太地区（悉尼） | ap-southeast-2 | apse2-az1 apse2-az2 apse2-az3 | | 亚太地区（泰国） | ap-southeast-7 | apse7-az1 apse7-az2 apse7-az3 | | 亚太地区（东京） | ap-northeast-1 | apne1-az1 apne1-az2 apne1-az2 apne1-az4 | | 加拿大（中部） | ca-central-1 | cac1-az1 cac1-az2 cac1-az4 | | 欧洲地区（法兰克福） | eu-central-1 | euc1-az1 euc1-az2 euc1-az3 | | 欧洲地区（爱尔兰） | eu-west-1 | euw1-az1 euw1-az2 euw1-az3 | | 欧洲地区（伦敦） | eu-west-2 | euw2-az1 euw2-az2 euw2-az3 | | 欧洲地区（米兰） | eu-south-1 | eus1-az1 eus1-az2 eus1-az3 | | 欧洲地区（巴黎） | eu-west-3 | euw3-az1 euw3-az2 euw3-az3 | | 欧洲（西班牙） | eu-south-2 | eus2-az1 eus2-az2 eus2-az3 | | 欧洲地区（斯德哥尔摩） | eu-north-1 | eun1-az1 eun1-az2 eun1-az2 eun1-az3 | | 南美洲（圣保罗） | sa-east-1 | sae1-az1 sae1-az2 sae1-az3 | | Amazon GovCloud (US-West) | us-gov-west-1 | usgw1-az1 usgw1-az2 usgw1-az3 | **重要** 子网必须位于上面列出的支持的可用区内。如果您在不支持的可用区域中指定子网，则在资源创建期间配置将失败。 要识别子网的可用区 ID，可以使用以下 CLI 命令： ``` aws ec2 describe-subnets --subnet-ids subnet-12345678 --query 'Subnets[0].AvailabilityZoneId' ``` ## IAM 权限 AgentCore 使用服务相关角色`AWSServiceRoleForBedrockAgentCoreNetwork`在您的 VPC 中创建和管理网络接口。当您首次配置 Amazon Bedrock AgentCore 运行时或 AgentCore 内置工具以使用 VPC 连接时，会自动创建此角色。 如果您需要手动创建此角色，则您的 IAM 实体需要以下权限： ``` { "Action": "iam:CreateServiceLinkedRole", "Effect": "Allow", "Resource": "arn:aws:iam::*:role/aws-service-role/network.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreNetwork", "Condition": { "StringLike": { "iam:AWSServiceName": "network.bedrock-agentcore.amazonaws.com" } } } ``` 此权限已包含在 Amazon 托管策略中[BedrockAgentCoreFullAccess](https://docs.amazonaws.cn/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html)。 ## 最佳实践 为了使用 VPC-connected 亚马逊 Bedrock AgentCore Runtime 和内置工具实现最佳性能和安全性： + **高可用性**： + 在不同的可用区中配置至少两个私有子网。有关支持的可用区域的列表，请参阅[支持的可用区域](#agentcore-supported-azs)。 + 部署支持多可用区的依赖资源（例如数据库或缓存），以避免单点故障。 + **网络性能**： + 将 Amazon Bedrock AgentCore Runtime 或内置工具子网置于与其连接的资源相同的可用区内。这降低了跨可用区延迟和数据传输成本。 + 尽可能使用 VPC 终端节点获取 Amazon 服务。终端节点提供更低的延迟、更高的可靠性，并避免为支持的服务收取 NAT 网关费用。 + **安全性**： + 创建安全组规则时应用最小权限原则。 + 启用 VPC 流日志进行审计和监控。定期查看日志以识别意外流量模式。 + **互联网接入**： + 要通过 Amazon Bedrock AgentCore Runtime 或 VPC 内的内置工具提供互联网接入，请在公有子网中配置 NAT 网关。更新私有子网的路由表以发送出站流量 (0.0.0.0/0) 到 NAT 网关。 + 我们建议使用 VPC 终端节点来提供 Amazon 服务，而不是互联网路由，以提高安全性并降低成本。 ## 为运行时和工具配置 VPC 访问权限 您可以使用 Amazon 管理控制台、C Amazon LI 或软件开发工具 Amazon 包配置 Amazon Bedrock AgentCore 运行时和内置工具的 VPC 访问权限。 ### 运行时配置 **Example** 1. 在 [ https://console.aws.amazon.com/bedrock-agentcore/home \# 处打开 AgentCore 控制台](https://console.amazonaws.cn/bedrock-agentcore/home#)。 1. 导航到该 AgentCore 部分 1. 选择或创建亚马逊 Bedrock AgentCore 运行时配置 1. 选择你的 ECR 图像 1. 在网络配置部分下，选择 ** VPC ** 1. 从下拉列表中选择您的 VPC 1. 根据您的应用程序需求选择相应的子网 1. 选择一个或多个安全组应用于 ENI 1. 保存您的配置 1. ``` aws bedrock-agentcore-control create-agent-runtime \ --agent-runtime-name "MyAgentRuntime" \ --network-configuration '{ "networkMode": "VPC", "networkModeConfig": { "subnets": ["subnet-0123456789abcdef0", "subnet-0123456789abcdef1"], "securityGroups": ["sg-0123456789abcdef0"] } }' ``` 1. ``` import boto3 client = boto3.client('bedrock-agentcore') response = client.create_runtime( runtimeName='MyAgentRuntime', networkConfiguration={ 'networkMode': 'VPC', 'networkModeConfig': { 'subnets': ['subnet-0123456789abcdef0', 'subnet-0123456789abcdef1'], 'securityGroups': ['sg-0123456789abcdef0'] } }, lifecycleConfiguration={ 'idleRuntimeSessionTimeout': 300, # 5 min, configurable 'maxLifetime': 1800 # 30 minutes, configurable }, ) ``` ### 代码解释器配置 **Example** 1. 在 [ https://console.aws.amazon.com/bedrock-agentcore/home \# 处打开 AgentCore 控制台](https://console.amazonaws.cn/bedrock-agentcore/home#)。 1. 导航到 AgentCore → Built-in 工具 → 代码解释器 1. 选择**创建代码解释器**或修改现有配置 1. 提供工具名称（可选） 1. 使用必要的权限配置执行角色 1. 在 “网络配置” 下，选择 ** VPC ** 1. 从下拉列表中选择您的 VPC 1. 选择适当的子网（建议使用 NAT 网关跨多个可用区的私有子网） 1. 为 ENI 访问控制选择安全组 1. 使用必要的权限配置执行角色 1. 保存您的配置 1. ``` aws bedrock-agentcore-control create-code-interpreter \ --region \ --name "my-code-interpreter" \ --description "My Code Interpreter with VPC mode for data analysis" \ --execution-role-arn "arn:aws:iam::123456789012:role/my-execution-role" \ --network-configuration '{ "networkMode": "VPC", "networkModeConfig": { "subnets": ["subnet-0123456789abcdef0", "subnet-0123456789abcdef1"], "securityGroups": ["sg-0123456789abcdef0"] } }' ``` 1. ``` import boto3 # Initialize the boto3 client cp_client = boto3.client( 'bedrock-agentcore-control', region_name="", endpoint_url="https://bedrock-agentcore-control..amazonaws.com" ) # Create a Code Interpreter response = cp_client.create_code_interpreter( name="myTestVpcCodeInterpreter", description="Test code sandbox for development", executionRoleArn="arn:aws:iam::123456789012:role/my-execution-role", networkConfiguration={ 'networkMode': 'VPC', 'networkModeConfig': { 'subnets': ['subnet-0123456789abcdef0', 'subnet-0123456789abcdef1'], 'securityGroups': ['sg-0123456789abcdef0'] } } ) # Print the Code Interpreter ID code_interpreter_id = response["codeInterpreterId"] print(f"Code Interpreter ID: {code_interpreter_id}") ``` ### 浏览器工具配置 **Example** 1. 在 [ https://console.aws.amazon.com/bedrock-agentcore/home \# 处打开 AgentCore 控制台](https://console.amazonaws.cn/bedrock-agentcore/home#)。 1. 在导航窗格中，选择**Built-in 工具 ** 1. 选择 “**创建浏览器” 工具 ** 1. 提供工具名称（可选）和描述（可选） 1. 设置执行角色权限 1. 在网络配置部分下，选择 ** VPC ** 模式 1. 选择您的 VPC 和子网 1. 为 Web 访问要求配置安全组 1. 设置执行角色权限 1. 保存您的配置 1. ``` aws bedrock-agentcore-control create-browser \ --region \ --name "my-browser" \ --description "My browser for web interaction" \ --network-configuration '{ "networkMode": "VPC", "networkModeConfig": { "subnets": ["subnet-0123456789abcdef0", "subnet-0123456789abcdef1"], "securityGroups": ["sg-0123456789abcdef0"] } }' \ --recording '{ "enabled": true, "s3Location": { "bucket": "my-bucket-name", "prefix": "sessionreplay" } }' \ --execution-role-arn "arn:aws:iam::123456789012:role/my-execution-role" ``` 1. ``` import boto3 # Initialize the boto3 client cp_client = boto3.client( 'bedrock-agentcore-control', region_name="", endpoint_url="https://bedrock-agentcore-control..amazonaws.com" ) # Create a Browser response = cp_client.create_browser( name="myTestVpcBrowser", description="Test browser with VPC mode for development", networkConfiguration={ 'networkMode': 'VPC', 'networkModeConfig': { 'subnets': ['subnet-0123456789abcdef0', 'subnet-0123456789abcdef1'], 'securityGroups': ['sg-0123456789abcdef0'] } }, executionRoleArn="arn:aws:iam::123456789012:role/Sessionreplay", recording={ "enabled": True, "s3Location": { "bucket": "session-record-123456789012", "prefix": "replay-data" } } ) ``` ## 安全组注意事项 安全组在连接到 VPC 时充当您的亚马逊 Bedrock AgentCore 运行时的虚拟防火墙或内置工具。它们在实例级别控制入站和出站流量。要为运行时配置安全组，请执行以下操作： + **出站规则 ** — 定义出站规则，允许您的亚马逊基岩 AgentCore 运行时连接到所需的 VPC 资源。 + **入站规则 ** — 确保目标资源的安全组允许来自与您的 Amazon Bedrock AgentCore Runtime 关联的安全组的入站连接。 + **最小权限 **-应用最小权限原则，只允许最低要求的流量。 ### 示例：连接到 Amazon RDS 数据库 当您的亚马逊 Bedrock R AgentCore untime 连接到 Amazon RDS 数据库时，请按以下方式配置安全组： **亚马逊 Bedrock AgentCore 运行时安全组 ** + **出站 **-允许通过端口 3306 (MySQL) 向 RDS 数据库安全组发送 TCP 流量。 + **入境 **-不需要。运行时仅启动出站连接。 **Amazon RDS 数据库安全组 ** + **入站 **-允许端口 3306 上来自亚马逊 Bedrock AgentCore Runtime 安全组的 TCP 流量。 + **出站 ** — 不需要。由于安全组是有状态的，因此自动允许返回流量。 ### 示例：连接到 Amazon EFS 或 Amazon S3 文件 当您在代理运行时配置自带文件系统（Amazon EFS 或 Amazon S3 文件访问点）时， AgentCore 运行时会通过 NFS 挂载文件系统。这需要在代理运行时 ENI 和文件系统装载目标之间的端口 2049 上建立 TCP 连接。 AgentCore 自动处理 TLS 加密和 IAM 身份验证。`amazon-efs-utils`挂载助手已预先安装在 microVM 运行时中——您无需在容器映像中配置或安装任何挂载软件。 #### 安全组配置 配置您的安全组以允许代理运行时和文件系统装载目标之间的 NFS 流量。 **代理运行时安全组-出站规则：** | Type | 协议 | 端口范围 | 目标位置 | 说明 | | --- | --- | --- | --- | --- | | NFS | TCP | 2049 | {{sg-mounttarget}} | 允许 NFS 访问文件系统挂载目标 | **文件系统装载目标安全组-入站规则：** | Type | 协议 | 端口范围 | 来源 | 说明 | | --- | --- | --- | --- | --- | | NFS | TCP | 2049 | {{sg-agentruntime}} | 允许运行时使用 NFS AgentCore | {{sg-mounttarget}}替换为 EFS 或 S3 文件挂载目标的安全组 ID{{sg-agentruntime}}，以及代理运行时使用的安全组 ID。 ** Amazon CLI — 向代理运行时安全组添加出站规则：** ``` aws ec2 authorize-security-group-egress \ --group-id sg-0123456789abcdef0 \ --protocol tcp \ --port 2049 \ --source-group sg-0987654321fedcba0 ``` ** Amazon CLI — 添加入站规则以挂载目标安全组：** ``` aws ec2 authorize-security-group-ingress \ --group-id sg-0987654321fedcba0 \ --protocol tcp \ --port 2049 \ --source-group sg-0123456789abcdef0 ``` **注意** 如果您对代理运行时和文件系统装载目标都使用单个安全组，请添加自引用规则，允许来自同一安全组的端口 2049 上进行入站 TCP。 ## VPC 端点配置 在 VPC 中 AgentCore 运行亚马逊 Bedrock Runtime 时，我们强烈建议配置以下 VPC 终端节点。**如果您的 VPC 无法访问互联网，则**需要这些终端节点，**即使您的 VPC 有 NAT 网关，也**强烈建议您使用，以避免 NAT 网关数据处理费用。 ### 所需的 VPC 端点 + **亚马逊 ECR 要求**： + Docker 端点：`com.amazonaws.region.ecr.dkr` + ECR API 端点：`com.amazonaws.region.ecr.api` + **亚马逊 S3 要求**： + ECR docker 层存储的网关端点：`com.amazonaws.region.s3` **重要** 对于容器代理， AgentCore 定期从 ECR 刷新您的容器镜像，ECR 将映像层存储在 Amazon S3 中。如果没有 S3 网关 VPC 终端节点，此流量会通过您的 NAT 网关进行路由，并产生数据处理费用。S3 网关 VPC 终端节点是免费的，可以免除这些费用。我们强烈建议为所有 VPC-mode 容器代理添加此终端节点，即使您的 VPC 可以通过 NAT 访问互联网。 **容器代理的最低 S3 存储桶权限 ** S3 网关终端节点使用 IAM 策略文档来限制对服务的访问。为遵循最小权限原则，将 S3 网关终端节点策略的范围仅限于 Amazon ECR 用于存储图像层的 Amazon S3 存储桶。以下政策限制了对您所在地区的 ECR 层存储桶的访问： ``` { "Statement": [ { "Sid": "AllowECRLayerAccess", "Principal": "*", "Action": [ "s3:GetObject" ], "Effect": "Allow", "Resource": ["arn:aws:s3:::prod-region-starport-layer-bucket/*"] } ] } ``` {{region}}替换为您的 Amazon 地区标识符（`us-east-2`例如，美国东部（俄亥俄州））。 **直接代码部署代理的最低 S3 存储桶权限 ** 对于使用直接代码部署（基于 zip）部署的代理，将您的代码工件 AgentCore 存储在内部服务拥有的 S3 存储桶中。将 S3 网关终端节点策略的范围仅限于您所在地区的代码工件存储桶： ``` { "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "s3:GetObject", "Resource": [ "arn:aws:s3:::acr-code-*-region-an", "arn:aws:s3:::acr-code-*-region-an/*" ], "Condition": { "StringEquals": { "aws:PrincipalServiceName": "bedrock-agentcore.amazonaws.com" } } } ] } ``` {{region}}替换为您的 Amazon 地区标识符（例如，`us-west-2`）。 **注意** AgentCore 代码工件存储桶是在[账户区域命名空间通用存储桶](https://docs.amazonaws.cn/AmazonS3/latest/userguide/gpbucketnamespaces.html#account-regional-gp-buckets)中创建的。 Amazon 只能拥有该服务使用的实际存储桶名称。该`aws:PrincipalServiceName`条件确保只有 AgentCore 服务主体才能通过此端点策略访问存储桶。 **注意** 如果您还使用[永久文件系统](runtime-filesystem-configurations.md)，请将会话存储桶 (`acr-storage-*-region-an`) 添加到此策略中。有关所需权限，[请参阅](runtime-filesystem-configurations.md#session-storage-networking)网络要求。 + **CloudWatch 要求**： + 日志端点：`com.amazonaws.region.logs` **注意** 如果不同，请务必{{region}}替换为您的特定区域。 **注意** 如果您使用[文件系统配置](runtime-filesystem-configurations.md)，请确保您的 VPC 满足[联网要求](runtime-filesystem-configurations.md#session-storage-networking)。 ### 互联网访问注意事项 当您将 Amazon Bedrock AgentCore Runtime 或内置工具连接到虚拟私有云 (VPC) 时，它默认无法访问互联网。默认情况下，这些资源只能与同一 VPC 内的资源通信。如果您的运行时或工具需要同时访问 VPC 资源和互联网，则必须相应地配置 VPC。 #### 互联网接入架构 要为您的 VPC-connected 亚马逊 Bedrock AgentCore 运行时或内置工具启用互联网接入，请使用以下组件配置您的 VPC： + **私有子网 ** — 将 Amazon Bedrock AgentCore 运行时或工具的网络接口置于私有子网中。 + **带有 NAT 网关的公有子网 ** — 在一个或多个公有子网中部署 NAT 网关，为私有资源提供出站互联网接入。 + **互联网网关 (IGW) ** — 将互联网网关连接到您的 VPC，以启用 NAT 网关和互联网之间的通信。 #### 路由配置 按如下方式更新您的子网路由表： + **私有子网路由表 **-添加默认路由 (0.0.0.0/0) 指向 NAT 网关。这允许来自运行时或工具的出站流量到达互联网。 + **公有子网路由表 **-添加默认路由 (0.0.0.0/0) 它指向互联网网关。这允许 NAT 网关与互联网通信。 **重要** 将亚马逊 Bedrock AgentCore Runtime 和内置工具连接到公共子网不提供互联网接入。始终使用带有 NAT 网关的私有子网进行互联网连接。 ## 监控和排查 要监控您的 VPC-connected 亚马逊 Bedrock AgentCore 运行时和工具并进行故障排除，请执行以下操作： ### CloudWatch 日志 为您的亚马逊 Bedrock AgentCore 运行时启用 CloudWatch 日志，以识别任何连接问题： + 检查与 VPC 连接相关的错误消息 + 连接到 VPC 资源时查找超时错误 + 监控初始化时间（VPC 连接可能会增加会话启动时间） ### 常见问题和解决方案 + **连接超时**： + 验证安全组规则是否正确 + 确保路由表配置正确 + 检查目标资源是否正在运行并接受连接 + **DNS 解析失败**： + 确保在您的 VPC 中启用 DNS 解析 + 验证您的 DHCP 选项配置是否正确 + **缺失的 ENI：** + 检查 IAM 权限以确保服务相关角色具有适当的权限 + 查找任何可能已达到的服务配额 ### 代码解释器问题 + **代码解释器在尝试调用公共端点**时调用调用超时： + 验证 VPC 是否配置了用于访问互联网的 NAT 网关 + **使用私有 VPC 终端节点调用对代码解释器的调用会引发 AccessDenied “” 错误**： + 确保在创建代码解释器期间传递的执行角色对配置 VPC 终端节点的 Amazon 服务具有正确的权限 + **使用某些私有 VPC 终端节点调用对代码解释器的调用显示 “无法找到凭证” 错误**： + 在创建代码解释器时检查是否提供了执行角色 ### 浏览器工具问题 + **Live-View/Connection Stream 无法加载网页并因连接超时**而失败： + 检查浏览器是否使用带有 NAT 网关的私有子网创建 ### 测试 VPC 连接 要验证您的 AgentCore 运行时和工具是否具有正确的 VPC 连接，您可以测试与私有资源的连接，并验证在您指定的子网中是否正确创建了网络接口。 要验证您的 AgentCore 工具是否可以访问互联网，您可以使用您的 VPC 配置配置代码解释器`executeCommand`，并使用该 `Invoke` API 尝试使用`curl`命令连接到公共 API 或网站并检查响应。如果连接超时，请检查您的 VPC 配置，尤其是您的路由表和 NAT 网关设置。 ``` # Using awscurl awscurl -X POST \ "https://bedrock-agentcore..amazonaws.com/code-interpreters//tools/invoke" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "x-amzn-code-interpreter-session-id: your-session-id" \ --service bedrock-agentcore \ --region \ -d '{ "name": "executeCommand", "arguments": { "command": "curl amazon.com" } }' ``` ### 文件系统连接问题 当文件系统挂载失败时，`InvokeAgentRuntime`API 返回 HTTP 状态 424（失败的依赖关系）。使用以下部分来诊断根本原因。 #### 文件系统挂载超时 **症状：使用文件系统配置的**代理调用在长时间延迟后失败。该错误表示装载操作已超时。 **常见原因和解决方案：** **1。缺少安全组规则 ** 验证代理运行时安全组的出站规则： ``` aws ec2 describe-security-groups \ --group-ids sg-0123456789abcdef0 \ --query 'SecurityGroups[0].IpPermissionsEgress[?ToPort==`2049`]' ``` 验证您的挂载目标安全组的入站规则： ``` aws ec2 describe-security-groups \ --group-ids sg-0987654321fedcba0 \ --query 'SecurityGroups[0].IpPermissions[?ToPort==`2049`]' ``` 如果任一查询返回空结果，请添加缺失的规则，如示[例：连接到 Amazon EFS 或 Amazon S3 文件中所示](#agentcore-security-groups-filesystem)。 **2。代理的可用区中没有装载目标 ** 代理运行时可以放置在不存在装载目标的可用区域中。验证重叠： ``` # Get agent runtime subnet AZs aws ec2 describe-subnets \ --subnet-ids subnet-0123456789abcdef0 subnet-0123456789abcdef1 \ --query 'Subnets[*].[SubnetId, AvailabilityZoneId]' --output table # Get EFS mount target AZs aws efs describe-mount-targets \ --file-system-id fs-0123456789abcdef0 \ --query 'MountTargets[*].[AvailabilityZoneId, LifeCycleState]' --output table ``` **解决方案：在代理运行时子网所在的每个可用区域中**创建挂载目标，或将代理运行时子网限制在存在装载目标的可用区域内。 **3. 路由表缺少本地路由 ** 验证与您的代理运行时子网关联的路由表包括本地 VPC 路由： ``` aws ec2 describe-route-tables \ --filters "Name=association.subnet-id,Values=subnet-0123456789abcdef0" \ --query 'RouteTables[0].Routes[?DestinationCidrBlock]' ``` #### 文件系统挂载失败，显示 “ResourceNotFound” **症状：**代理调用立即失败（未超时），引用文件系统主机名时 ResourceNotFound 出错。 **常见原因和解决方案：** **1。DNS 解析失败 ** — VPC 无法解析文件系统挂载目标主机名。 验证您的 VPC 上的 DNS 设置： ``` aws ec2 describe-vpc-attribute \ --vpc-id vpc-0123456789abcdef0 \ --attribute enableDnsSupport aws ec2 describe-vpc-attribute \ --vpc-id vpc-0123456789abcdef0 \ --attribute enableDnsHostnames ``` 两者都必须返回`true`。如果没有，请启用它们： ``` aws ec2 modify-vpc-attribute --vpc-id vpc-0123456789abcdef0 --enable-dns-support aws ec2 modify-vpc-attribute --vpc-id vpc-0123456789abcdef0 --enable-dns-hostnames ``` **2。装载目标未处于 “可用” 状态 ** — 装载目标可能仍在创建中或可能已被删除。 ``` # For EFS aws efs describe-mount-targets --file-system-id fs-0123456789abcdef0 # For S3 Files aws s3files list-mount-targets --file-system-id fs-0123456789abcdef0 ``` 确保挂载目标`LifeCycleState`是`available`。如果缺少装载目标，请在相应的子网中重新创建。 **3. 文件系统或接入点已删除 **-代理运行时配置中引用的资源已不存在。使用有效的 ARN 验证和更新代理运行时。 **注意** 在极少数情况下，由于 DNS 解析时机，S3 文件挂载可能会因暂`ResourceNotFound`时错误而失败。重试调用通常可以解决这个问题。如果错误仍然存在，请验证装载目标是否处于`Available`状态。 #### 可用区不匹配（间歇性故障） **症状：**文件系统挂载间歇性地成功——有些调用有效，而另一些调用因超时而失败。 **为什么会发生这种情况：**您的代理运行时在多个可用区域中有子网，但挂载目标仅存在于其中一些可用区中。当代理放置在没有挂载目标的可用区时，挂载会超时。 **解决方案：**要么在代理运行时子网所在的所有可用区域中创建挂载目标（推荐），要么移除位于没有装载目标的可用区域中的代理运行时子网。 ``` # List all EFS mount target AZs aws efs describe-mount-targets \ --file-system-id fs-0123456789abcdef0 \ --query 'MountTargets[*].AvailabilityZoneId' --output text # Create a mount target in a missing AZ aws efs create-mount-target \ --file-system-id fs-0123456789abcdef0 \ --subnet-id subnet-in-missing-az \ --security-groups sg-0987654321fedcba0 ``` **注意** 对于 S3 文件，`aws s3files create-mount-target`使用相同的参数。