Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Memulai dengan Instans menggunakan AWS CLI atau SDK
<a name="runtime-instances-get-started-cli"></a>

Tutorial ini berjalan melalui hosting agen pada tipe komput ** asi Inst ** ances dengan Com AWS mand Line Interface (AWS CLI) dan SDK. Pertama-tama Anda membuat penyedia [ kapasitas ](runtime-instances-how-it-works.md#runtime-instances-capacity-provider) yang mendefinisikan infrastruktur Amazon Elastic Compute Cloud (Amazon EC2), kemudian membuat runtime agen yang menggunakannya, dan akhirnya memanggil agen.

Untuk prasyarat, lihat Mem [ ulai dengan Instans](runtime-instances-getting-started.md).

**catatan**  
Nama parameter dalam contoh ini mengikuti model bidang AgentCore kontrol. Untuk bentuk permintaan dan respons otoritatif, lihat Refer [ ensi API AgentCore Kontrol ](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html) Amazon Bedrock.

## Langkah 1: Buat penyedia kapasitas
<a name="runtime-instances-api-create-cp"></a>

Gunakan `CreateCapacityProvider` operasi untuk menentukan infrastruktur EC2 Anda. Permintaan mengambil `permissionsConfiguration` (peran IAM digunakan untuk AgentCore mengoperasikan penyedia kapasitas) dan `computeConfiguration` yang menjelaskan instans EC2 melalui template peluncuran. Contoh berikut membuat penyedia kapasitas Linux dengan tipe instance tunggal yang diizinkan dan volume EBS persisten.

**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. Contoh Python menggunakan boto3 untuk membuat penyedia kapasitas.

   ```
   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']}")
   ```

Untuk menjalankan beban kerja GPU, sertakan jenis instance GPU yang didukung. `allowedInstanceTypes` AgentCore menyediakan driver GPU pada instance, sehingga gambar kontainer standar berfungsi tanpa bundling driver. Keluarga yang didukung adalah`g4dn`, `g5``g6`,`g6e`,`gr6`,`g6f`,`gr6f`,`g7e`, dan`inf2`. Jika Anda menyertakan jenis instans akselerator dari keluarga yang tidak didukung, permintaan gagal dengan a`ValidationException`. Untuk informasi selengkapnya, lihat [ Menggunakan jenis instans GPU](runtime-instances-how-it-works.md#runtime-instances-gpu).

Jajak pendapat `GetCapacityProvider` hingga status `READY` sebelum mengaitkan penyedia kapasitas dengan runtime. Jika statusnya menjadi`CREATE_FAILED`, periksa `statusCode` dan `statusReason` untuk menentukan penyebabnya.

## Langkah 2: Buat runtime agen pada penyedia kapasitas
<a name="runtime-instances-api-create-runtime"></a>

Buat runtime agen dengan `capacityProviderConfiguration` referensi penyedia kapasitas Anda. Untuk memasang volume yang ditentukan pada penyedia kapasitas ke dalam sistem file agen, tambahkan `capacityProviderVolume` entri `filesystemConfigurations` yang mereferensikan volume berdasarkan nama. Jalur pemasangan harus berada di bawah `/mnt` dengan satu subdirektori (misalnya,`/mnt/scratch`).

Runtime agen memiliki sendiri`lifecycleConfiguration.maxLifetime`, yang default menjadi 28800 detik (8 jam). Nilai ini harus kurang dari atau sama dengan `maxLifetime` yang ditetapkan penyedia kapasitas`ec2Configuration.lifecycleConfiguration`. Penyedia kapasitas pada Langkah 1 menetapkan nilai itu menjadi 3600 detik (1 jam), sehingga default runtime 8 jam akan melebihi itu dan `CreateAgentRuntime` akan gagal dengan a`ValidationException`. Oleh karena itu, contoh berikut `maxLifetime` menetapkan runtime 1800 detik, yang berada dalam batas penyedia kapasitas.

**catatan**  
Kedua sumber daya menggunakan `lifecycleConfiguration` anggota, tetapi mereka adalah struktur yang berbeda. Versi penyedia kapasitas mengambil `idleInstanceTimeout` dan `maxLifetime` dan berlaku untuk instance. Versi runtime agen mengambil `idleRuntimeSessionTimeout` dan `maxLifetime` dan berlaku untuk sesi. Untuk informasi selengkapnya, lihat Meng [ onfigurasi pengaturan AgentCore ](runtime-lifecycle-settings.md) siklus hidup Amazon Bedrock.

Jangan lulus `networkConfiguration` saat Anda menentukan`capacityProviderConfiguration`. Runtime Instances mewarisi jaringannya dari penyedia kapasitas`ec2Configuration.vpcConfiguration`, jadi menentukan keduanya gagal dengan a`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. Contoh Python menggunakan boto3 untuk membuat runtime agen pada Instans.

   ```
   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']}")
   ```

## Langkah 3: Panggil agen
<a name="runtime-instances-api-invoke"></a>

Memanggil runtime dengan cara yang sama seperti VM-backed runtime mikro. Gunakan kembali yang sama `runtimeSessionId` di seluruh pemanggilan untuk menjaga sesi pada instance yang sama. Ini memungkinkan agen Anda mengakses data dari pemanggilan sebelumnya. Untuk menempatkan agen yang berkolaborasi bersama, gunakan agen `runtimeSessionId` yang sama di beberapa runtime yang berbagi penyedia kapasitas.

**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`Parameternya adalah gumpalan biner, dan AWS CLI mengharapkan gumpalan dikodekan base64 secara default. Meneruskan JSON mentah sebaris`--payload '{"prompt": "…​"}'`, seperti, gagal di sisi klien dengan `Invalid base64` kesalahan sebelum permintaan mencapai layanan. For `fileb://` mulir yang digunakan di sini membaca file sebagai biner terlepas dari `cli_binary_format` pengaturannya, sehingga menghindari langkah pengkodean.
Respons agen adalah gumpalan streaming yang ditulis AWS CLI ke file keluaran yang Anda beri nama sebagai argumen terakhir, dalam contoh ini. `response.json` Output standar hanya membawa `statusCode` bidang `runtimeSessionId``contentType`,, dan, jadi baca file output untuk melihat apa yang dikembalikan agen Anda.    
 AWS SDK  

1. Contoh Python menggunakan boto3 untuk memanggil runtime agen pada Instans.

   ```
   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()))
   ```

Setidaknya `runtimeSessionId` harus 33 karakter.

Pemanggilan pertama untuk sesi baru menyediakan instans EC2 di akun Anda dan meluncurkan agen, sehingga biasanya membutuhkan waktu lebih lama daripada pemanggilan selanjutnya. Pemanggilan berikutnya ke sesi yang sama menggunakan kembali instance yang sedang berjalan dan kembali lebih cepat.

AgentCore menyediakan instans ini sebagai inst [ ans terkelola Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html), yang disembunyikan dari `DescribeInstances` dan tampilan konsol EC2 Anda secara default. Pang `aws ec2 describe-instances` gilan biasa tidak mencantumkannya. Untuk melihatnya, sertakan sumber daya terkelola:

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

Untuk informasi selengkapnya tentang mengelola visibilitas instans, lihat setelan visibilitas sumber daya terkel [ ola](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html#managed-resource-visibility-settings).

## Co-locate beberapa agen pada satu instance
<a name="runtime-instances-multi-agent"></a>

Ketika dua runtime agen mereferensikan penyedia ** kapasitas ** yang sama dan Anda memanggilnya dengan ** yang sama **`runtimeSessionId`, kedua agen berjalan pada instans EC2 yang sama. Di sana, mereka dapat berbagi volume yang dikonfigurasi dalam konfigurasi sistem file mereka. Agen berkolaborasi dengan membaca dan menulis file pada volume bersama itu — setiap agen dipanggil secara independen dan sebaliknya tidak berbagi status. Misalnya, test runner dapat menulis hasil ke volume, dan penganalisis kode yang dipanggil pada sesi yang sama kemudian dapat membacanya. Untuk batas antara agen pada instance bersama, lihat Model [ keamanan dan izin untuk Instans Runtime](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",
)
```

Setiap agen berjalan dengan kredentif IAM sendiri yang berasal dari peran eksekusi runtime, sehingga Anda dapat memberikan izin berbeda kepada agen yang berkolaborasi meskipun mereka berbagi instance yang sama. Namun, karena agen pada instance yang sama tidak terisolasi satu sama lain, agen mana pun berpotensi membaca kredenSIAL agen lain. Co-locate Hanya agen yang saling dipercaya. Untuk informasi selengkapnya, lihat Model [ keamanan dan izin untuk Instans Runtime](runtime-instances-security.md).

## Bersihkan: hentikan dan hapus sesi
<a name="runtime-instances-stop-delete"></a>

**Awas**  
Untuk menghindari biaya berkelanjutan untuk instans Amazon EC2 dan volume Amazon EBS yang disediakan di akun Anda, hapus sesi dan penyedia kapasitas yang tidak lagi Anda perlukan setelah menyelesaikan tutorial ini.

Sebuah sesi dapat meng-host beberapa runtime agen pada instance yang sama, sehingga AgentCore menyediakan dua operasi yang berbeda:
+  **Menghentikan runtime agen dalam sesi ** — `StopRuntimeSession` menghentikan runtime agen tunggal dalam sesi, diidentifikasi oleh ARN runtime dan ID sesi. Runtime agen lain yang berbagi sesi dan instance yang sama tidak terpengaruh.
+  **Menghapus sesi ** — `DeleteCapacityProviderSession` menghapus seluruh sesi dan mencabut sumber daya EC2 yang dibuat di akun Anda (instans, antarmuka jaringan, dan volume EBS persisten apa pun), sehingga Anda berhenti mengeluarkan biaya infrastruktur dan penyimpanan.

Untuk menghentikan runtime agen tertentu pada sesi, panggil [ StopRuntimeSession ](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html) operasi dengan ARN runtime dan ID sesi.

**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. Contoh Python menggunakan boto3 untuk menghentikan sesi runtime.

   ```
   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",
   )
   ```

Untuk menghapus sesi dan menghapus semua sumber dayanya — termasuk volume EBS persisten — panggil `DeleteCapacityProviderSession` dengan ID penyedia kapasitas dan ID sesi. Operasi ini idempoten dan asinkron: ia segera kembali saat menghentikan AgentCore instance dan menghapus volume di latar belakang.

ID sesi adalah nilai yang Anda berikan pada pemanggilan, dan tidak ada operasi yang mencantumkan sesi pada penyedia kapasitas. Catat `runtimeSessionId` nilai-nilai yang Anda gunakan sehingga Anda dapat menghapus setiap sesi setelahnya. Jika Anda tidak lagi memilikinya, Anda dapat menemukan instance yang masih berjalan, lalu menghapus penyedia kapasitas untuk menghapus semua sesinya:

```
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. Contoh Python menggunakan boto3 untuk menghapus sesi penyedia kapasitas.

   ```
   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"])
   ```

## Menghapus penyedia kapasitas
<a name="_delete_a_capacity_provider"></a>

Ketika Anda tidak lagi membutuhkan penyedia kapasitas, hapus dengan `DeleteCapacityProvider` operasi. Menghapus penyedia kapasitas menghentikan dan menghapus semua sesi terkait dan penyimpanan persistennya, sehingga ini juga berfungsi sebagai cara untuk membersihkan sesi yang ID-nya tidak lagi Anda miliki. Anda tidak perlu menghapus sesi terlebih dahulu. Namun, Anda perlu menghapus runtime yang mereferensikan penyedia kapasitas: hapus versi terkait, titik akhir, atau runtime terlebih dahulu, atau permintaan penghapusan gagal dengan a. `ValidationException` Operasi tidak sinkron; mengidentifikasi penyedia kapasitas dengan ID-nya.

**Example**  

1. 

   ```
   aws bedrock-agentcore-control delete-capacity-provider \
     --capacity-provider-id "my_capacity_provider-a1b2c3d4e5"
   ```

1. Contoh Python menggunakan boto3 untuk menghapus penyedia kapasitas.

   ```
   import boto3
   
   client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
   
   client.delete_capacity_provider(
       capacityProviderId="my_capacity_provider-a1b2c3d4e5",
   )
   ```