本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用开始使用实例 AWS CLI 或 SDK
本教程介绍如何使用 AWS 命令行界面 (AWS CLI) 和 SDK 在**实例**计算类型上托管代理。您首先创建一个定义亚马逊弹性计算云 (Amazon EC2) 基础设施的[容量提供商](runtime-instances-how-it-works.md#runtime-instances-capacity-provider)，然后创建使用该基础设施的代理运行时，最后调用该代理。
有关先决条件，请参阅实例[入门](runtime-instances-getting-started.md)。
**注意**
这些示例中的参数名称遵循 AgentCore 控制平面模型。有关权威请求和响应形式，请参阅[亚马逊基岩 AgentCore 控制 API 参考](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html)。
## 第 1 步：创建容量提供商
使用`CreateCapacityProvider`操作来定义您的 EC2 基础设施。该请求采 AgentCore 用`permissionsConfiguration`（IAM 角色用于运营容量提供商）和通过启动模板描述 EC2 实例的 a。`computeConfiguration`以下示例创建了一个具有单一允许实例类型和永久性 EBS 卷的 Linux 容量提供商。
**Example**
1.
```
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" } }
]
}
}'
```
1. 使用 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`、`g6``g6e`、`gr6`、`g6f`、`gr6f``g7e`、和`inf2`。如果您包括来自不受支持的系列的加速器实例类型，则请求将失败并显示。`ValidationException`有关更多信息，请参阅[使用 GPU 实例类型](runtime-instances-how-it-works.md#runtime-instances-gpu)。
在将容量提供器与运行时关联`READY`之前，先轮询`GetCapacityProvider`直到状态变为正常。如果状态变成`CREATE_FAILED`，请检查`statusCode``statusReason`并确定原因。
## 步骤 2：在容量提供器上创建代理运行时
使用引用您的容量提供商的`capacityProviderConfiguration`创建代理运行时。要将容量提供器上定义的卷装入到代理的文件系统中，请在其中添加一个按名称引用`filesystemConfigurations`该卷的`capacityProviderVolume`条目。装载路径必须`/mnt`位于下方有一个子目录（例如，`/mnt/scratch`）。
代理运行时有自己的运行时间`lifecycleConfiguration.maxLifetime`，默认为 28800 秒（8 小时）。该值必须小于或等于容量提供者设置的值`ec2Configuration.lifecycleConfiguration`。`maxLifetime`步骤 1 中的容量提供者将该值设置为 3600 秒（1 小时），因此 8 小时的运行时默认值将超过该值，并且`CreateAgentRuntime`会出现故障。`ValidationException`因此，以下示例将运行时间`maxLifetime`设置为 1800 秒，这在容量提供商的限制范围内。
**注意**
两种资源都使用一个`lifecycleConfiguration`成员，但它们是不同的结构。容量提供者的版本采用`idleInstanceTimeout``maxLifetime`和应用于实例。代理运行时的版本采用`idleRuntimeSessionTimeout``maxLifetime`并应用于会话。有关更多信息，请参阅[配置 Amazon Bedrock AgentCore 生命周期设置](runtime-lifecycle-settings.md)。
指定`networkConfiguration`时不要通过`capacityProviderConfiguration`。实例运行时从容量提供商那里继承其网络`ec2Configuration.vpcConfiguration`，因此如果指定两者，则失败。`ValidationException`
**Example**
1.
```
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" }
}
]'
```
1. 使用 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`多个运行时中使用相同的代理。
**Example**
1.
```
echo '{"prompt": "Analyze the sales data and summarize the key trends."}' > payload.json
aws bedrock-agentcore invoke-agent-runtime \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000" \
--qualifier "DEFAULT" \
--payload fileb://payload.json \
response.json
```
该`payload`参数是一个二进制 blob， AWS CLI 期望 blob 在默认情况下采用 base64 编码。例如，在请求到达服务之前，以`--payload '{"prompt": "…"}'`内联方式传递原始 JSON 会导致客户端失败，`Invalid base64`出现错误。无论`cli_binary_format`设置如何，此处使用的`fileb://`格式都将文件读取为二进制，因此避免了编码步骤。
在本示例`response.json`中，代理的响应是一个流式传输 blob， AWS CLI 将其写入您命名为最后一个参数的输出文件中。标准输出仅带有`runtimeSessionId``contentType`、和`statusCode`字段，因此请阅读输出文件以查看代理返回的内容。
AWS SDK
1. 使用 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 托管实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html)，默认情况下，这些实例对您的 EC2 控制台视图处于隐藏状态。`DescribeInstances`普通`aws ec2 describe-instances`通话并不能列出它们。要查看它们，请包括托管资源：
```
aws ec2 describe-instances --include-managed-resources \
--filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id"
```
有关管理实例可见性的更多信息，请参阅[托管资源可见性设置](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html#managed-resource-visibility-settings)。
## Co-locate 一个实例上的多个代理
当两个代理运行时引用**同一个**容量提供商，而您使用相同的容量提供商调用它们时 **`runtimeSessionId`，两个代理将在同一 EC2 实例上运行。**在那里，他们可以共享在文件系统配置中配置的卷。代理通过在该共享卷上读取和写入文件来进行协作，每个代理均独立调用，否则不会共享状态。例如，测试运行器可以将结果写入卷，然后在同一会话中调用的代码分析器可以读取这些结果。有关共享实例上代理之间的边界，请参阅运行时实例[的安全模型和权限](runtime-instances-security.md)。
```
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 只有相互信任的代理。有关更多信息，请参阅运行时实例[的安全模型和权限](runtime-instances-security.md)。
## 清理：停止和删除会话
**警告**
为避免在您的账户中预置的 Amazon EC2 实例和 Amazon EBS 卷持续收费，请在完成本教程后删除不再需要的会话和容量提供商。
一个会话可以在同一个实例上托管多个代理运行时，因此 AgentCore 提供了两种不同的操作：
+ **在会话中停止代理运行时 ** — `StopRuntimeSession` 停止会话中的单个代理运行时，由运行时 ARN 和会话 ID 标识。共享相同会话和实例的其他代理运行时不受影响。
+ **删除会话 ** — `DeleteCapacityProviderSession` 删除整个会话并取消预置在您的账户中创建的 EC2 资源（实例、网络接口和任何永久性 EBS 卷），这样您就不会产生基础设施和存储成本。
要停止会话中的特定代理运行时，请使用运行时 ARN 和会话 ID 调用该[StopRuntimeSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html)操作。
**Example**
1.
```
aws bedrock-agentcore stop-runtime-session \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000"
```
1. 使用 boto3 停止运行时会话的 Python 示例。
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
client.stop_runtime_session(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000",
)
```
要删除会话并取消调配其所有资源（包括任何永久性 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]'
```
**Example**
1.
```
aws bedrock-agentcore delete-capacity-provider-session \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5" \
--session-id "project-xyz-0000000000000000000000000000"
```
1. 使用 boto3 删除容量提供者会话的 Python 示例。
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.delete_capacity_provider_session(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
sessionId="project-xyz-0000000000000000000000000000",
)
print("Session status:", response["status"])
```
## 删除容量提供商
当您不再需要容量提供器时，请通过`DeleteCapacityProvider`操作将其删除。删除容量提供商会停止并删除其所有关联会话及其永久存储，因此它也可以作为清理已没有 ID 的会话的一种方式。您无需先删除会话。但是，您确实需要删除引用容量提供者的运行时：先删除关联的版本、终端节点或运行时，否则删除请求将失败并显示。`ValidationException`该操作是异步的；通过容量提供者的 ID 来识别容量提供者。
**Example**
1.
```
aws bedrock-agentcore-control delete-capacity-provider \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5"
```
1. 使用 boto3 删除容量提供者的 Python 示例。
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
client.delete_capacity_provider(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
)
```