第 1 步：创建容量提供商步骤 2：在容量提供器上创建代理运行时步骤 3：调用代理 Co-locate 一个实例上的多个代理清理：停止和删除会话删除容量提供商

使用开始使用实例 AWS CLI 或 SDK

本教程介绍如何使用 AWS 命令行界面 (AWS CLI) 和 SDK 在实例计算类型上托管代理。您首先创建一个定义亚马逊弹性计算云 (Amazon EC2) 基础设施的容量提供商，然后创建使用该基础设施的代理运行时，最后调用该代理。

有关先决条件，请参阅实例入门。

注意

这些示例中的参数名称遵循 AgentCore 控制平面模型。有关权威请求和响应形式，请参阅亚马逊基岩 AgentCore 控制 API 参考。

第 1 步：创建容量提供商

使用CreateCapacityProvider操作来定义您的 EC2 基础设施。该请求采 AgentCore 用permissionsConfiguration（IAM 角色用于运营容量提供商）和通过启动模板描述 EC2 实例的 a。computeConfiguration以下示例创建了一个具有单一允许实例类型和永久性 EBS 卷的 Linux 容量提供商。

例

AWS CLI


aws bedrock-agentcore-control create-capacity-provider \
  --name "my_capacity_provider" \
  --permissions-configuration '{
    "capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
  }' \
  --compute-configuration '{
    "ec2Configuration": {
      "launchTemplateSource": {
        "launchParameters": {
          "operatingSystem": "LINUX_X86_64",
          "instanceRequirements": {
            "allowedInstanceTypes": ["m5.large"]
          }
        }
      },
      "vpcConfiguration": {
        "subnets": ["subnet-0123456789abcdef0"],
        "securityGroups": ["sg-0123456789abcdef0"]
      },
      "lifecycleConfiguration": {
        "maxLifetime": 3600
      },
      "volumes": [
        { "ebsConfiguration": { "name": "scratch", "sizeGiB": 50, "volumeType": "gp3" } }
      ]
    }
  }'

AWS SDK

使用 boto3 创建容量提供器的 Python 示例。


import boto3

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

response = client.create_capacity_provider(
    name="my_capacity_provider",
    permissionsConfiguration={
        "capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
    },
    computeConfiguration={
        "ec2Configuration": {
            "launchTemplateSource": {
                "launchParameters": {
                    "operatingSystem": "LINUX_X86_64",
                    "instanceRequirements": {
                        "allowedInstanceTypes": ["m5.large"],
                    },
                }
            },
            "vpcConfiguration": {
                "subnets": ["subnet-0123456789abcdef0"],
                "securityGroups": ["sg-0123456789abcdef0"],
            },
            "lifecycleConfiguration": {
                "maxLifetime": 3600,
            },
            "volumes": [
                {"ebsConfiguration": {"name": "scratch", "sizeGiB": 50, "volumeType": "gp3"}}
            ],
        }
    },
)

print(f"Capacity provider ARN: {response['capacityProviderArn']}")

要运行 GPU 工作负载，请在中添加支持的 GPU 实例类型allowedInstanceTypes。 AgentCore 在实例上配置 GPU 驱动程序，因此标准容器映像无需捆绑驱动程序即可运行。支持的家庭是g4dn、g5、g6g6e、gr6、g6f、gr6fg7e、和inf2。如果您包括来自不受支持的系列的加速器实例类型，则请求将失败并显示。ValidationException有关更多信息，请参阅使用 GPU 实例类型。

在将容量提供器与运行时关联READY之前，先轮询GetCapacityProvider直到状态变为正常。如果状态变成CREATE_FAILED，请检查statusCodestatusReason并确定原因。

步骤 2：在容量提供器上创建代理运行时

使用引用您的容量提供商的capacityProviderConfiguration创建代理运行时。要将容量提供器上定义的卷装入到代理的文件系统中，请在其中添加一个按名称引用filesystemConfigurations该卷的capacityProviderVolume条目。装载路径必须/mnt位于下方有一个子目录（例如，/mnt/scratch）。

代理运行时有自己的运行时间lifecycleConfiguration.maxLifetime，默认为 28800 秒（8 小时）。该值必须小于或等于容量提供者设置的值ec2Configuration.lifecycleConfiguration。maxLifetime步骤 1 中的容量提供者将该值设置为 3600 秒（1 小时），因此 8 小时的运行时默认值将超过该值，并且CreateAgentRuntime会出现故障。ValidationException因此，以下示例将运行时间maxLifetime设置为 1800 秒，这在容量提供商的限制范围内。

注意

两种资源都使用一个lifecycleConfiguration成员，但它们是不同的结构。容量提供者的版本采用idleInstanceTimeoutmaxLifetime和应用于实例。代理运行时的版本采用idleRuntimeSessionTimeoutmaxLifetime并应用于会话。有关更多信息，请参阅配置 Amazon Bedrock AgentCore 生命周期设置。

指定networkConfiguration时不要通过capacityProviderConfiguration。实例运行时从容量提供商那里继承其网络ec2Configuration.vpcConfiguration，因此如果指定两者，则失败。ValidationException

例

AWS CLI


aws bedrock-agentcore-control create-agent-runtime \
  --agent-runtime-name "my_instances_agent" \
  --role-arn "arn:aws:iam::111122223333:role/AgentRuntimeRole" \
  --agent-runtime-artifact '{
    "containerConfiguration": {
      "containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
    }
  }' \
  --capacity-provider-configuration '{
    "capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5"
  }' \
  --lifecycle-configuration '{
    "idleRuntimeSessionTimeout": 300,
    "maxLifetime": 1800
  }' \
  --filesystem-configurations '[
    {
      "capacityProviderVolume": { "volumeName": "scratch", "mountPath": "/mnt/scratch" }
    }
  ]'

AWS SDK

使用 boto3 在实例上创建代理运行时的 Python 示例。


import boto3

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

response = client.create_agent_runtime(
    agentRuntimeName="my_instances_agent",
    roleArn="arn:aws:iam::111122223333:role/AgentRuntimeRole",
    agentRuntimeArtifact={
        "containerConfiguration": {
            "containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
        }
    },
    capacityProviderConfiguration={
        "capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5",
    },
    lifecycleConfiguration={
        "idleRuntimeSessionTimeout": 300,
        "maxLifetime": 1800,
    },
    filesystemConfigurations=[
        {
            "capacityProviderVolume": {"volumeName": "scratch", "mountPath": "/mnt/scratch"}
        }
    ],
)

print(f"Agent runtime ARN: {response['agentRuntimeArn']}")

步骤 3：调用代理

调用运行时的方式与微型VM-backed 运行时相同。在runtimeSessionId各次调用中重复使用相同的内容，以使会话保持在同一个实例上。这使您的代理可以访问先前调用的数据。要将协作代理放在同一位置，请在共享容量提供商的runtimeSessionId多个运行时中使用相同的代理。

例

在本示例response.json中，代理的响应是一个流式传输 blob， AWS CLI 将其写入您命名为最后一个参数的输出文件中。标准输出仅带有runtimeSessionIdcontentType、和statusCode字段，因此请阅读输出文件以查看代理返回的内容。

AWS SDK

使用 boto3 在实例上调用代理运行时的 Python 示例。


import boto3
import json

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

response = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
    runtimeSessionId="project-xyz-0000000000000000000000000000",  # 33+ chars; reuse to keep the session
    payload=json.dumps({"prompt": "Analyze the sales data and summarize the key trends."}).encode(),
    qualifier="DEFAULT",
)

print("Agent response:", json.loads(response["response"].read()))

runtimeSessionId必须至少为 33 个字符。

首次调用新会话会在您的账户中预置 EC2 实例并启动代理，因此通常比以后的调用花费更长的时间。对同一会话的后续调用会重用正在运行的实例，并且返回速度要快得多。

AgentCore 将这些实例配置为 Amazon EC2 托管实例，默认情况下，这些实例对您的 EC2 控制台视图处于隐藏状态。DescribeInstances普通aws ec2 describe-instances通话并不能列出它们。要查看它们，请包括托管资源：


aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id"

有关管理实例可见性的更多信息，请参阅托管资源可见性设置。

Co-locate 一个实例上的多个代理

当两个代理运行时引用同一个容量提供商，而您使用相同的容量提供商调用它们时 runtimeSessionId，两个代理将在同一 EC2 实例上运行。在那里，他们可以共享在文件系统配置中配置的卷。代理通过在该共享卷上读取和写入文件来进行协作，每个代理均独立调用，否则不会共享状态。例如，测试运行器可以将结果写入卷，然后在同一会话中调用的代码分析器可以读取这些结果。有关共享实例上代理之间的边界，请参阅运行时实例的安全模型和权限。


import boto3
import json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")
session_id = "collab-session-000000000000000000000"

# Agent A — created on capacity provider "my_capacity_provider"
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test-runner-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Run the test suite for project ABC"}).encode(),
    qualifier="DEFAULT",
)

# Agent B — a different runtime that shares the SAME capacity provider and session ID,
# so it runs on the same instance as Agent A and can read the files Agent A wrote to the shared volume.
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/code-analyzer-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Analyze the code for project ABC"}).encode(),
    qualifier="DEFAULT",
)

每个代理都使用其自己的 IAM 证书运行，这些证书源自其运行时的执行角色，因此，尽管协作代理共享同一个实例，但您可以向他们授予不同的权限。但是，由于同一实例上的代理彼此之间并不隔离，因此任何代理都有可能读取其他代理的凭证。 Co-locate 只有相互信任的代理。有关更多信息，请参阅运行时实例的安全模型和权限。

清理：停止和删除会话

警告

为避免在您的账户中预置的 Amazon EC2 实例和 Amazon EBS 卷持续收费，请在完成本教程后删除不再需要的会话和容量提供商。

一个会话可以在同一个实例上托管多个代理运行时，因此 AgentCore 提供了两种不同的操作：

在会话中停止代理运行时 — StopRuntimeSession 停止会话中的单个代理运行时，由运行时 ARN 和会话 ID 标识。共享相同会话和实例的其他代理运行时不受影响。
删除会话 — DeleteCapacityProviderSession 删除整个会话并取消预置在您的账户中创建的 EC2 资源（实例、网络接口和任何永久性 EBS 卷），这样您就不会产生基础设施和存储成本。

要停止会话中的特定代理运行时，请使用运行时 ARN 和会话 ID 调用该StopRuntimeSession操作。

例

要删除会话并取消调配其所有资源（包括任何永久性 EBS 卷），请使用容量提供商 ID 和会话 ID DeleteCapacityProviderSession 进行调用。该操作是等导和异步的：它立即返回，同时 AgentCore 终止实例并在后台删除卷。

会话 ID 是您在调用时提供的值，没有任何操作可以在容量提供器上列出会话。记录您使用的runtimeSessionId值，以便以后可以删除每个会话。如果您不再拥有它们，则可以找到仍在运行的实例，然后删除容量提供商以取消其所有会话的配置：


aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id" \
  --query 'Reservations[].Instances[?State.Name!=`terminated`].[InstanceId,State.Name]'

例

删除容量提供商

当您不再需要容量提供器时，请通过DeleteCapacityProvider操作将其删除。删除容量提供商会停止并删除其所有关联会话及其永久存储，因此它也可以作为清理已没有 ID 的会话的一种方式。您无需先删除会话。但是，您确实需要删除引用容量提供者的运行时：先删除关联的版本、终端节点或运行时，否则删除请求将失败并显示。ValidationException该操作是异步的；通过容量提供者的 ID 来识别容量提供者。

例

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

使用控制台

开始直接部署代码