本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 CLI 或 SDK AWS 開始使用執行個體
<a name="runtime-instances-get-started-cli"></a>

本教學課程會逐步解說如何使用 AWS 命令列界面 (AWS CLI) 和 SDK 在**執行個體**運算類型上託管 代理程式。 SDKs 您首先建立一個[容量提供者](runtime-instances-how-it-works.md#runtime-instances-capacity-provider)來定義 Amazon Elastic Compute Cloud (Amazon EC2) 基礎設施，然後建立一個使用該基礎設施的代理程式執行期，最後叫用代理程式。

如需先決條件，請參閱[開始使用執行個體](runtime-instances-getting-started.md)。

**注意**  
這些範例中的參數名稱遵循 AgentCore 控制平面模型。如需授權請求和回應形狀，請參閱 [Amazon Bedrock AgentCore Control API 參考](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html)。

## 步驟 1：建立容量提供者
<a name="runtime-instances-api-create-cp"></a>

使用 `CreateCapacityProvider`操作來定義 EC2 基礎設施。請求需要 `permissionsConfiguration`(AgentCore 用來操作容量提供者的 IAM 角色）`computeConfiguration`，以及透過啟動範本描述 EC2 執行個體的 。下列範例會建立具有單一允許執行個體類型和持久性 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)。

`GetCapacityProvider` 輪詢直到狀態為 狀態`READY`，再將容量提供者與執行時間建立關聯。如果狀態變成 `CREATE_FAILED`，請檢查 `statusCode`和 `statusReason`以判斷原因。

## 步驟 2：在容量提供者上建立代理程式執行時間
<a name="runtime-instances-api-create-runtime"></a>

使用參考容量提供者`capacityProviderConfiguration`的 建立代理程式執行期。若要將容量提供者上定義的磁碟區掛載至代理程式的檔案系統，請將 `capacityProviderVolume`項目新增至`filesystemConfigurations`以名稱參考磁碟區的項目。掛載路徑必須`/mnt`位於具有單一子目錄的 下 （例如，`/mnt/scratch`)。

代理程式執行期有自己的 `lifecycleConfiguration.maxLifetime`，預設為 28800 秒 (8 小時）。此值必須小於或等於容量提供者`maxLifetime`在 中設定的 `ec2Configuration.lifecycleConfiguration`。步驟 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：叫用代理程式
<a name="runtime-instances-api-invoke"></a>

叫用執行時間的方式與microVM支援的執行時間相同。在叫用`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，CLI AWS 預設預期 Blob 為 base64 編碼。將原始 JSON 內嵌，例如 `--payload '{"prompt": "…​"}'`，在請求到達服務之前，用戶端失敗並`Invalid base64`發生錯誤。無論`cli_binary_format`設定為何，此處使用的`fileb://`表單都會將檔案讀取為二進位檔案，以避免編碼步驟。
代理程式的回應是串流 Blob，CLI AWS 會寫入您命名為最後一個引數的輸出檔案，在此範例中為 `response.json`。標準輸出僅攜帶 `runtimeSessionId`、 `contentType`和 `statusCode` 欄位，因此請讀取輸出檔案以查看代理程式傳回的內容。    
 AWS 開發套件  

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)，這些執行個體預設會隱藏在 `DescribeInstances`和您的 EC2 主控台檢視中。純`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)。

## 在一個執行個體上共置多個客服人員
<a name="runtime-instances-multi-agent"></a>

當兩個代理程式執行時間參考**相同的**容量提供者，而您使用**相同的** 叫用它們時`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 登入資料執行，因此您可以授予協同合作代理程式不同的許可，即使他們共用相同的執行個體。不過，由於相同執行個體上的代理程式不會彼此隔離，因此任何代理程式都可能讀取另一個代理程式的登入資料。僅共置互信的客服人員。如需詳細資訊，請參閱[執行期執行個體的安全模型和許可](runtime-instances-security.md)。

## 清除：停止並刪除工作階段
<a name="runtime-instances-stop-delete"></a>

**警告**  
為了避免您帳戶中佈建的 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 磁碟區，`DeleteCapacityProviderSession`請使用容量提供者 ID 和工作階段 ID 呼叫 。操作是等冪和非同步的：它會在 AgentCore 終止執行個體並在背景刪除磁碟區時立即傳回。

工作階段 IDs是您在調用時提供的值，沒有列出容量提供者上工作階段的操作。保留您使用`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"])
   ```

## 刪除容量提供者
<a name="_delete_a_capacity_provider"></a>

當您不再需要容量提供者時，請使用 `DeleteCapacityProvider`操作將其刪除。刪除容量提供者會停止並刪除所有相關聯的工作階段及其持久性儲存體，因此它也可以做為清除您不再擁有 IDs之工作階段的一種方式。您不需要先刪除工作階段。不過，您需要移除參考容量提供者的執行時間：先刪除相關聯的版本、端點或執行時間，否則刪除請求會因 而失敗`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",
   )
   ```