# 在 Amazon Bedrock 中使用服务相关角色 AgentCore
Amazon Bedrock AgentCore 使用 AWS 身份和访问管理 (IAM) Access Management 服务相关角色。服务相关角色是一种与之直接关联的 IAM 角色的独特类型。 AgentCore Service-linked 角色由预定义 AgentCore ，包括该服务代表您调用其他 AWS 服务所需的所有权限。
由于您不必手动添加必要的权限，因此与服务相关的角色可以 AgentCore 更轻松地使用。 AgentCore 定义其服务相关角色的权限，除非另有定义，否则 AgentCore 只能担任其角色。定义的权限包括信任策略和权限策略，而且权限策略不能附加到任何其他 IAM 实体。
只有在首先删除角色的相关资源后，才能删除角色。这样可以保护您的 AgentCore 资源，因为您不会无意中删除访问资源的权限。
AgentCore 使用以下服务相关角色：
+ `AWSServiceRoleForBedrockAgentCoreNetwork`-管理您的 VPC 中的网络接口
+ `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity`-管理代理运行时的工作负载身份访问令牌和 OAuth 凭证
+ `AWSServiceRoleForBedrockAgentCoreGatewayNetwork`-管理用于网关私有连接的 Amazon VPC L AgentCore attice 资源
+ `AWSServiceRoleForBedrockAgentCoreIdentity`-管理 Amazon VPC Lattice 资源，以实现与私有 AgentCore 身份提供商的身份连接
## AgentCore 服务相关角色权限
### 网络服务相关角色
AgentCore 使用名为的服务相关角色`AWSServiceRoleForBedrockAgentCoreNetwork` AgentCore 允许代表您创建和管理您的 VPC 中的网络接口。
`AWSServiceRoleForBedrockAgentCoreNetwork` 服务相关角色信任以下服务代入该角色：
+ `network.bedrock-agentcore.amazonaws.com`
角色权限策略 AgentCore 允许对指定资源完成以下操作：
您可以在上查看完整的政策[BedrockAgentCoreNetworkServiceRolePolicy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreNetworkServiceRolePolicy.html)。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowCreateEniInAnySubnet",
"Effect": "Allow",
"Action": "ec2:CreateNetworkInterface",
"Resource": "arn:aws:ec2:*:*:subnet/*"
},
{
"Sid": "AllowCreateEniWithSecurityGroups",
"Effect": "Allow",
"Action": "ec2:CreateNetworkInterface",
"Resource": "arn:aws:ec2:*:*:security-group/*"
},
{
"Sid": "AllowCreateEniWithBedrockManagedRequestTag",
"Effect": "Allow",
"Action": "ec2:CreateNetworkInterface",
"Resource": "arn:aws:ec2:*:*:network-interface/*",
"Condition": {
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AmazonBedrockAgentCoreManaged"
]
},
"StringEquals": {
"aws:RequestTag/AmazonBedrockAgentCoreManaged": "true"
}
}
},
{
"Sid": "AllowTagEniOnCreate",
"Effect": "Allow",
"Action": "ec2:CreateTags",
"Resource": "arn:aws:ec2:*:*:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowManageEniWhenBedrockManaged",
"Effect": "Allow",
"Action": [
"ec2:DeleteNetworkInterface",
"ec2:AssignPrivateIpAddresses",
"ec2:UnassignPrivateIpAddresses",
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:*:*:network-interface/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/AmazonBedrockAgentCoreManaged": "true"
}
}
},
{
"Sid": "AllowGetSecurityGroupsForVpc",
"Effect": "Allow",
"Action": [
"ec2:GetSecurityGroupsForVPC"
],
"Resource": "arn:aws:ec2:*:*:vpc/*"
},
{
"Sid": "AllowDescribeNetworkingResources",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs"
],
"Resource": "*"
}
]
}
```
### 身份服务相关角色
AgentCore 使用名为的服务相关角色`AWSServiceRoleForBedrockAgentCoreRuntimeIdentity` AgentCore 允许代表您管理工作负载身份访问令牌和 OAuth 凭证。
`AWSServiceRoleForBedrockAgentCoreRuntimeIdentity` 服务相关角色信任以下服务代入该角色：
+ `runtime-identity.bedrock-agentcore.amazonaws.com`
角色权限策略允许 AgentCore 对指定资源完成这些操作。
您可以在上查看完整的政策[BedrockAgentCoreRuntimeIdentityServiceRolePolicy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreRuntimeIdentityServiceRolePolicy.html)。
```
{
"Version": "2012-10-17",
"Statement": {
"Sid": "AllowWorkloadIdentityAccess",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetWorkloadAccessToken",
"bedrock-agentcore:GetWorkloadAccessTokenForJWT",
"bedrock-agentcore:GetWorkloadAccessTokenForUserId"
],
"Resource": [
"arn:aws:bedrock-agentcore:*:*:workload-identity-directory/default",
"arn:aws:bedrock-agentcore:*:*:workload-identity-directory/default/workload-identity/*"
]
}
}
```
有关此政策变更的信息，请参阅[AWS 托管策略的AgentCore 更新](security-iam-awsmanpol.md#security-iam-awsmanpol-updates)。
**了解身份功能**
服务相关角色用于支持运行时资源的 OAuth 身份验证和 JWT 不记名令牌功能。 AgentCore 此功能允许代理运行时安全地管理工作负载身份并代表用户访问外部 OAuth 提供程序。
**身份管理的主要优点**
+ **简化的权限管理**：无需为工作负载身份访问手动配置 IAM 策略
+ **安全令牌管理**：为 OAuth 流程提供对工作负载访问令牌的安全访问
+ **用户联**合：启用三足的 OAuth 流程，用于访问外部服务，例如谷歌云端硬盘、Microsoft Graph 等。
+ **自动配置**：需要时会自动创建 Service-linked 角色
**身份管理的工作原理**
当您使用 OAuth 身份验证或 JWT 不记名令牌调用 AgentCore 运行时时：
1. 在创建运行时期间，您可以配置 JWT 授权方设置（发现 URL、允许的客户端、允许的受众）
1. AgentCore 自动创建服务相关角色以管理工作负载身份权限
1. 运行时使用服务相关角色将 JWT 令牌交换为工作负载访问令牌
1. 您的代理代码可以使用这些令牌访问外部 OAuth 提供商和服务
1. 所有令牌管理均通过 AgentCore 身份服务安全处理
**从传统方法迁移**
适用于现有代理（在 2025 年 10 月 13 日之前创建）
+ 继续使用附加到代理执行角色的手动 IAM 策略
+ 不自动迁移-保留现有行为
适用于新代理（在 2025 年 10 月 13 日当天或之后创建）
+ 自动使用与服务相关的角色方法
+ 无需手动配置 IAM 策略
+ 简化了设置和管理
服务相关角色可确保 AgentCore 只能访问与您的代理运行时明确关联的工作负载身份资源，从而保持安全隔离和清晰的资源归因。
有关实现的详细信息，请参阅[使用入站身份验证和出站身份验证进行身份验证和授权](runtime-oauth.md)。
### 网关服务相关角色
AgentCore 使用名为`AWSServiceRoleForBedrockAgentCoreGatewayNetwork`的服务相关角色允许 AgentCore Gateway 代表您创建和管理账户中的 Amazon VPC Lattice 资源。当您使用托管私有终端节点配置网关目标时，将使用此角色，使 AgentCore 网关能够设置必要的 VPC Lattice 资源网关，以便私有连接到您的 VPC 中的资源。
`AWSServiceRoleForBedrockAgentCoreGatewayNetwork` 服务相关角色信任以下服务代入该角色：
+ `bedrock-agentcore.amazonaws.com`
角色权限策略 AgentCore 允许对指定资源完成以下操作：
您可以在上查看完整的政策[BedrockAgentCoreGatewayNetworkServiceRolePolicy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreGatewayNetworkServiceRolePolicy.html)。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowSLRActionsForLattice",
"Effect": "Allow",
"Action": [
"iam:CreateServiceLinkedRole"
],
"Resource": [
"arn:aws:iam::*:role/aws-service-role/vpc-lattice.amazonaws.com/AWSServiceRoleForVpcLattice"
],
"Condition": {
"StringEquals": {
"iam:AWSServiceName": "vpc-lattice.amazonaws.com"
}
}
},
{
"Sid": "AllowResourceGatewayCreate",
"Effect": "Allow",
"Action": [
"vpc-lattice:CreateResourceGateway",
"vpc-lattice:TagResource"
],
"Resource": [
"arn:aws:vpc-lattice:*:*:resourcegateway/*"
],
"Condition": {
"StringEquals": {
"aws:RequestTag/BedrockAgentCoreGatewayManaged": "true",
"aws:ResourceTag/BedrockAgentCoreGatewayManaged": "true"
}
}
},
{
"Sid": "AllowEC2PermissionsForResourceGatewayCreate",
"Effect": "Allow",
"Action": [
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeSecurityGroups"
],
"Resource": [
"*"
]
},
{
"Sid": "AllowResourceGatewayDelete",
"Effect": "Allow",
"Action": [
"vpc-lattice:DeleteResourceGateway",
"vpc-lattice:GetResourceGateway"
],
"Resource": [
"*"
],
"Condition": {
"StringEquals": {
"aws:ResourceTag/BedrockAgentCoreGatewayManaged": "true"
}
}
}
]
}
```
**了解网关托管莱迪思功能**
服务相关角色用于支持 AgentCore 网关目标的托管私有终端节点功能。当您创建带有托管私有终端节点的网关目标时， AgentCore 使用此角色代表您在账户中创建和管理 VPC Lattice 资源网关。这些托管资源网关可在网 AgentCore 关和您的 VPC 中的资源之间实现私有连接，而无需您手动设置 VPC Lattice 资源。
**莱迪思托管资源的主要优势**
+ **简化设置**：无需手动创建和配置VPC莱迪思资源网关
+ **Scoped-down 网络权限**：应用程序开发人员不需要在自己的 IAM 策略中拥有莱迪思的 VPC 网络权限
+ **托管生命周期**： AgentCore 管理莱迪思资源的整个生命周期，包括创建、重复使用和清理
+ **自动配置**：当您使用托管私有终端节点创建网关目标时，服务相关角色会自动创建
**莱迪思托管资源的工作原理**
使用托管私有终端节点创建网关目标时：
1. 您可以在配置中为私有终端节点指定 VPC、子网和可选安全组 `managedVpcResource`
1. AgentCore 如果服务相关角色尚不存在，则自动创建该角色
1. AgentCore 使用该角色在您的账户中创建托管 VPC Lattice 资源网关，标记为 `BedrockAgentCoreGatewayManaged`
1. AgentCore 设置必要的 VPC 莱迪思资源以启用私有连接
1. 删除网关目标时， AgentCore 会清理不再使用的莱迪思托管资源
**注意**
服务相关角色只能管理带有标签的 VPC Lattice 资源网关。`BedrockAgentCoreGatewayManaged`它无法修改或删除您自己创建和管理的资源网关。如果您为网关目标使用自我管理的莱迪思资源选项，则不需要此服务相关角色。
### 身份网络服务相关角色
AgentCore 使用名为`AWSServiceRoleForBedrockAgentCoreIdentity`的服务相关角色允许 Ident AgentCore ity 代表您创建和管理账户中的 Amazon VPC Lattice 资源。当您为私有身份提供者配置私有终端节点时，会使用此角色，从而使 AgentCore 身份能够设置必要的 VPC Lattice 资源网关，以便与您的 VPC 中的身份提供商进行私有连接。
`AWSServiceRoleForBedrockAgentCoreIdentity` 服务相关角色信任以下服务代入该角色：
+ `identity-network.bedrock-agentcore.amazonaws.com`
角色权限策略 AgentCore 允许对指定资源完成以下操作：
您可以在上查看完整的政策[AWSBedrockAgentCoreIdentityNetworkServiceRolePolicy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSBedrockAgentCoreIdentityNetworkServiceRolePolicy.html)。
```
{
"Version" : "2012-10-17",
"Statement" : [
{
"Sid" : "AllowSLRActionsForLattice",
"Effect" : "Allow",
"Action" : [
"iam:CreateServiceLinkedRole"
],
"Resource" : [
"arn:aws:iam::*:role/aws-service-role/vpc-lattice.amazonaws.com/AWSServiceRoleForVpcLattice"
],
"Condition" : {
"StringEquals" : {
"iam:AWSServiceName" : "vpc-lattice.amazonaws.com"
}
}
},
{
"Sid" : "AllowResourceGatewayCreate",
"Effect" : "Allow",
"Action" : [
"vpc-lattice:CreateResourceGateway",
"vpc-lattice:TagResource"
],
"Resource" : [
"arn:aws:vpc-lattice:*:*:resourcegateway/*"
],
"Condition" : {
"StringEquals" : {
"aws:RequestTag/BedrockAgentCoreIdentityManaged" : "true",
"aws:ResourceTag/BedrockAgentCoreIdentityManaged" : "true"
}
}
},
{
"Sid" : "AllowEC2PermissionsForResourceGatewayCreate",
"Effect" : "Allow",
"Action" : [
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeSecurityGroups"
],
"Resource" : [
"*"
]
},
{
"Sid" : "AllowResourceGatewayDelete",
"Effect" : "Allow",
"Action" : [
"vpc-lattice:DeleteResourceGateway",
"vpc-lattice:GetResourceGateway"
],
"Resource" : [
"*"
],
"Condition" : {
"StringEquals" : {
"aws:ResourceTag/BedrockAgentCoreIdentityManaged" : "true"
}
}
}
]
}
```
**了解身份网络功能**
服务相关角色用于支持 Ident AgentCore ity 的托管私有终端节点功能。当您为私有身份提供商配置私有终端节点时， AgentCore 使用此角色代表您在账户中创建和管理 VPC Lattice 资源网关。这些托管资源网关可在您的 VPC 中的 AgentCore 身份和身份提供者（例如自托管 Keycloak）或其他 OIDC-compliant 授权服务器之间实现私有连接，而无需您手动设置 VPC Lattice 资源。 PingFederate
**莱迪思托管资源如何用于身份识别**
为私有身份提供商配置私有终端节点时：
1. 您可以在配置中为私有终端节点指定 VPC、子网和可选安全组 `managedVpcResource`
1. AgentCore 如果服务相关角色尚不存在，则自动创建该角色
1. AgentCore 使用该角色在您的账户中创建托管 VPC Lattice 资源网关，标记为 `BedrockAgentCoreIdentityManaged`
1. AgentCore 设置必要的VPC Lattice资源以实现与您的身份提供商的私有连接
1. 删除私有端点配置时， AgentCore 会清理不再使用的莱迪思托管资源
**注意**
服务相关角色只能管理带有标签的 VPC Lattice 资源网关。`BedrockAgentCoreIdentityManaged`它无法修改或删除您自己创建和管理的资源网关。如果您为私有身份提供商使用自我管理的莱迪思资源选项，则不需要此服务相关角色。
有关配置私有身份提供商的更多信息，请参阅 [Connect 到您的 VPC 中的私有身份提供商](identity-private-idp.md)。
## 为创建服务相关角色 AgentCore
您无需手动创建服务相关角色。 AgentCore 需要时自动创建它们：
+ **网络服务相关角色：在**使用 VPC 配置创建 AgentCore 运行时、代码解释器或浏览器资源时创建
+ **身份服务相关角色**：在 2025 **年 10 月 13 日当天或之后创建或更新 AgentCore 运行时时创建**
+ **网关服务相关角色：在**使用托管私有终端节点 (`managedVpcResource`) 配置创建 AgentCore 网关目标时创建
+ **身份网络服务相关角色：在**您为 VPC 托管身份提供商 (`managedVpcResource`) 配置配置私有终端节点时创建
如果您删除了服务相关角色，然后需要重新创建该角色，则可以使用相同的流程在您的账户中重新创建该角色。当您创建相应的 AgentCore 资源时， AgentCore 会再次为您创建服务相关角色。
### 创建服务相关角色所需的权限
您必须配置权限，允许 IAM 实体（如用户、组或角色）创建、编辑或删除服务关联角色。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"
}
}
}
```
**对于身份服务相关角色**
```
{
"Sid": "CreateBedrockAgentCoreRuntimeIdentityServiceLinkedRolePermissions",
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity",
"Condition": {
"StringEquals": {
"iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com"
}
}
}
```
**对于网关服务相关角色**
```
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreGatewayNetwork",
"Condition": {
"StringEquals": {
"iam:AWSServiceName": "bedrock-agentcore.amazonaws.com"
}
}
}
```
**对于身份网络服务相关角色**
```
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/identity-network.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreIdentity",
"Condition": {
"StringEquals": {
"iam:AWSServiceName": "identity-network.bedrock-agentcore.amazonaws.com"
}
}
}
```
这些权限已包含在 AWS 托管策略中[BedrockAgentCoreFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html)。
## 编辑的服务相关角色 AgentCore
AgentCore 不允许您编辑`AWSServiceRoleForBedrockAgentCoreNetwork`、`AWSServiceRoleForBedrockAgentCoreRuntimeIdentity``AWSServiceRoleForBedrockAgentCoreGatewayNetwork`、或`AWSServiceRoleForBedrockAgentCoreIdentity`与服务相关的角色。创建服务关联角色后，您将无法更改角色的名称，因为可能有多种实体引用该角色。但是可以使用 IAM 编辑角色描述。有关更多信息，请参阅[编辑服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role)。
## 删除的服务相关角色 AgentCore
如果不再需要使用某个需要服务关联角色的功能或服务，我们建议您删除该角色。这样就没有未被主动监控或维护的未使用实体。但是，必须先删除使用服务相关角色的所有 AgentCore 资源，然后才能删除该角色：
+ **网络服务相关角色**：使用 VPC 配置删除所有 AgentCore 运行时、代码解释器和浏览器资源
+ **身份服务相关角色**：删除所有 AgentCore 运行时资源
+ **网关服务相关角色**：删除所有使用托管私有终端节点的 AgentCore 网关目标（`managedVpcResource`配置）
+ Ident@@ **ity Network 服务相关角色**：删除使用 VPC 托管 AgentCore 身份提供商的托管私有终端节点的所有身份资源（`managedVpcResource`配置）。这包括出站 OAuth 凭证提供程序和入站 JWT 授权方配置（在运行时或网关上 AgentCore ）。
### 清除服务相关角色
必须先确认服务相关角色没有活动会话并删除该角色使用的任何资源，然后才能使用 IAM 删除服务相关角色。
**在 IAM 控制台中检查服务相关角色是否有活动会话**
1. 登录 AWS 管理控制台并打开 IAM 控制台，网址为[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在 IAM 控制台的导航窗格中，选择**角色**，然后选择`AWSServiceRoleForBedrockAgentCoreNetwork`角色的名称（不是复选框）。
1. 在所选角色的 **Summary** 页面上，选择 **Access Advisor** 选项卡。
1. 在 **Access Advisor (访问顾问)** 选项卡上，查看服务相关角色的近期活动。
**注意**
如果您不确定 AgentCore 是否在使用服务相关角色，可以尝试删除该角色。如果服务正在使用该角色，则删除操作会失败，并且您可以查看正在使用该角色的 区域。如果该角色已被使用，则您必须等待会话结束，然后才能删除该角色。您无法撤销服务相关角色对会话的权限。
如果要移除服务相关角色，则必须先删除相应的 AgentCore 资源：
+ `AWSServiceRoleForBedrockAgentCoreNetwork`: 使用 VPC 配置删除所有 AgentCore 运行时、代码解释器和浏览器资源
+ `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity`: 删除所有 AgentCore 运行时资源
+ `AWSServiceRoleForBedrockAgentCoreGatewayNetwork`：删除所有使用托管私有终端节点的 AgentCore 网关目标。删除所有托管目标后， AgentCore 释放不再使用的托管 VPC Lattice 资源网关。
+ `AWSServiceRoleForBedrockAgentCoreIdentity`：删除使用 VPC 托管 AgentCore 身份提供商的托管私有终端节点的所有身份资源。这包括具有私有终端节点的出站 OAuth 凭证提供程序和入站 JWT 授权方配置（在 AgentCore 运行时或网关上）。`managedVpcResource`删除所有托管私有终端节点配置后， AgentCore 释放不再使用的托管 VPC Lattice 资源网关。
### 手动删除服务相关角色
使用 IAM 控制台、 AWS CLI 或 IAM API 删除服务相关角色。有关更多信息，请参阅[删除服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role)。