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

# Cangkang interaktif (terminal)
<a name="harness-command-shell"></a>

`InvokeAgentRuntimeCommandShell`Operasi membuka terminal interaktif yang persisten di dalam sesi AgentCore harness yang sedang berjalan. WebSocket API mengidentifikasi sesi harness ini dengan ID sesi runtime. Tidak seperti eksekusi perintah one-shot, shell interaktif mempertahankan variabel lingkungannya, direktori kerja, riwayat perintah, dan proses yang berjalan di seluruh input.

Gunakan shell interaktif untuk debugging, pengembangan berulang, atau proses yang berjalan lama saat Anda perlu mempertahankan status shell di seluruh perintah.

Untuk permintaan SiGv4 dan SiGv4 yang telah ditandatangani sebelumnya, penelepon memerlukan izin pada harness. `bedrock-agentcore:InvokeAgentRuntimeCommandShell` Bearer-token permintaan harus memenuhi otorisasi masuk harness sebagai gantinya.

**penting**  
Saat diluncurkan, perintah AgentCore CLI dan pembantu shell AgentCore SDK tingkat tinggi tidak mendukung target harness. Connect ke shell harness melalui `InvokeAgentRuntimeCommandShell` WebSocket API secara langsung, seperti yang ditunjukkan pada halaman ini.

## Cara kerjanya
<a name="harness-command-shell-how-it-works"></a>

 `InvokeAgentRuntimeCommandShell`membuat WebSocket koneksi ke proses shell interaktif di microVM yang menjalankan sesi harness Anda. Koneksi menggunakan frame biner untuk mengalirkan input dan output terminal di kedua arah.

Jika harness menggunakan lingkungan default, shell berjalan di lingkungan harness terkelola. Jika harness menggunakan wadah khusus, shell berjalan di wadah itu. Terminal interaktif Harness saat ini hanya mendukung Bash.

Koneksi mendukung:


| Fitur | Deskripsi | 
| --- | --- | 
| Keadaan persisten | Variabel lingkungan, direktori kerja, riwayat perintah, dan proses yang berjalan tetap ada dalam shell yang sama. | 
| Rekoneksi | Berikan ID sesi runtime yang sama dan `shellId` untuk menyambung kembali ke shell yang terpisah. Layanan memutar ulang hingga 256 KB output buffer. | 
| Beberapa cangkang bersamaan | Buka hingga 10 sesi shell aktif pada satu sesi harness. Cangkang yang terlepas tidak dihitung dalam batas ini. Setiap shell memiliki proses terminal independen dan berbagi sistem file sesi. | 

## Prasyarat
<a name="harness-command-shell-prerequisites"></a>
+ Harness di negara bagian `READY`
+ Otorisasi untuk metode otentikasi yang dipilih: `bedrock-agentcore:InvokeAgentRuntimeCommandShell` Izin IAM untuk SigV4, atau token pembawa yang diterima oleh otorisasi masuk harness
+  WebSocket Klien yang mendukung bingkai biner dan meminta header atau URL yang telah ditandatangani sebelumnya
+ Untuk wadah khusus, Bash dipasang di`/bin/bash`. Shell lain, termasuk `sh` dan`dash`, saat ini tidak didukung.

Untuk informasi selengkapnya tentang model izin harness lengkap, lihat. [Izin IAM yang diperlukan untuk penelepon](harness-security.md#harness-iam-permissions)

## Connect melalui WebSocket API
<a name="harness-command-shell-connect"></a>

Buka WebSocket koneksi ke URL berikut:

```
wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells
```

Gunakan harness ARN, bukan ARN dari Runtime yang dikelola. URL-encode harness lengkap ARN sebelum meletakkannya di jalan. Harness ARN memiliki format berikut:

```
arn:aws:bedrock-agentcore:<region>:<accountId>:harness/<harnessId>
```

Kirim nilai berikut dengan permintaan WebSocket pemutakhiran:


| Nilai | Diperlukan | Deskripsi | 
| --- | --- | --- | 
| Autentikasi | Ya | Tanda tangani permintaan dengan Signature Version 4 (SigV4), gunakan URL SiGv4 yang telah ditandatangani sebelumnya, atau kirim token pembawa yang dikonfigurasi oleh otorisasi masuk harness di header. `Authorization` Nama layanan SiGv4 adalah. `bedrock-agentcore` | 
|  `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`header atau parameter kueri | Tidak | Menargetkan sesi harness yang ada atau membuat sesi dengan ID yang disediakan. Nilai harus mengandung setidaknya 33 karakter. Jika Anda menghilangkannya, layanan akan membuat ID sesi runtime dan mengembalikannya dalam respons. | 
|  `Sec-WebSocket-Protocol`  | Tidak | Untuk koneksi SiGv4, secara opsional tawarkan `v1.command.agentcore.aws.dev` untuk mengidentifikasi protokol biner command-shell. Bearer-token koneksi menggunakan subprotokol otentikasi yang dijelaskan setelah tabel ini sebagai gantinya. | 
|  `shellId`parameter kueri | Tidak | Menyambung kembali ke shell yang ada. Gunakan dengan ID sesi runtime yang sama yang membuat shell. | 

Untuk klien browser yang tidak dapat mengatur `Authorization` header, base64url-menyandikan token pembawa dan menawarkan keduanya dan penjaga melalui. `base64UrlBearerAuthorization.<encoded-token>` `base64UrlBearerAuthorization` `Sec-WebSocket-Protocol` Jangan juga menawarkan `v1.command.agentcore.aws.dev` pada koneksi bearer-token.

`101 Switching Protocols`Respons mengembalikan ID sesi runtime dan ID shell di `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` dan `X-Amzn-Bedrock-AgentCore-Shell-Id` header. Klien yang tidak dapat membaca header respons WebSocket pemutakhiran dapat membaca ID shell dari `STATUS` bingkai pertama. Frame tidak berisi ID sesi runtime, jadi klien ini harus membuat dan mempertahankan ID sesi runtime sebelum menghubungkan. Saat Anda membuat URL yang telah ditandatangani sebelumnya, sertakan ID sesi waktu proses sebagai parameter kueri sebelum menandatangani URL.

Batas waktu WebSocket pemutakhiran hanya berlaku sampai layanan kembali`101 Switching Protocols`. Inisialisasi Shell dan wadah khusus dapat dilanjutkan setelah peningkatan. Tunggu `STATUS` frame awal sebelum memperlakukan shell sebagai siap, terapkan batas waktu aplikasi terpisah sambil menunggu, dan menangani kode tutup `1011` sebagai inisialisasi shell atau kegagalan server.

Contoh Python berikut menggunakan WebSocket klien generik dan `botocore` hanya untuk menandatangani permintaan upgrade. Itu tidak menggunakan pembantu shell AgentCore SDK.

```
pip install "boto3>=1.34" "websockets>=15"
```

```
import asyncio
import json
import urllib.parse
import uuid

import botocore.session
import websockets
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest


REGION = "us-west-2"
HARNESS_ARN = (
    "arn:aws:bedrock-agentcore:us-west-2:123456789012:"
    "harness/MyHarness-a1b2c3d4e5"
)
SESSION_ID = str(uuid.uuid4())  # 36 characters
SUBPROTOCOL = "v1.command.agentcore.aws.dev"


def signed_headers(url):
    request = AWSRequest(
        method="GET",
        url=url,
        headers={
            "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": SESSION_ID,
        },
    )
    credentials = botocore.session.Session().get_credentials()
    SigV4Auth(credentials, "bedrock-agentcore", REGION).add_auth(request)
    return dict(request.headers)


async def main():
    encoded_arn = urllib.parse.quote(HARNESS_ARN, safe="")
    host = f"bedrock-agentcore.{REGION}.amazonaws.com"
    path = f"/runtimes/{encoded_arn}/ws/shells"
    https_url = f"https://{host}{path}"
    websocket_url = f"wss://{host}{path}"

    async with websockets.connect(
        websocket_url,
        additional_headers=signed_headers(https_url),
        subprotocols=[SUBPROTOCOL],
        open_timeout=330,
    ) as websocket:
        shell_id = websocket.response.headers.get(
            "X-Amzn-Bedrock-AgentCore-Shell-Id"
        )
        print(f"Connected to shell {shell_id}")

        # Channel 0x00 carries terminal input.
        await websocket.send(b"\x00echo 'Hello from my harness'\n")
        await websocket.send(b"\x00exit\n")

        async for frame in websocket:
            if isinstance(frame, str) or not frame:
                continue

            channel, payload = frame[0], frame[1:]
            if channel == 0x01:  # PTY output (command stdout and stderr)
                print(payload.decode("utf-8", errors="replace"), end="")
            elif channel == 0x02:  # Service or platform diagnostics
                print(payload.decode("utf-8", errors="replace"), end="")
            elif channel == 0x03:  # STATUS
                status = json.loads(payload)
                shell_id = status.get("metadata", {}).get("shellId", shell_id)
                print(f"\nStatus: {status}")


asyncio.run(main())
```

## Protokol bingkai biner
<a name="harness-command-shell-protocol"></a>

Setiap pesan tingkat aplikasi adalah bingkai biner WebSocket . Byte pertama mengidentifikasi saluran, dan byte yang tersisa adalah payload.


| Saluran | Arahan | Payload | 
| --- | --- | --- | 
|  `0x00`- STDIN | Klien ke layanan | Masukan terminal mentah. | 
|  `0x01`- STDOUT | Layanan ke klien | Output PTY mentah. PTY menggabungkan perintah stdout dan stderr pada saluran ini. | 
|  `0x02`- STDERR | Layanan ke klien | Diagnostik layanan atau platform. Command stderr adalah bagian dari output `0x01` PTY. | 
|  `0x03`- STATUS | Layanan ke klien | UTF-8 JSON yang berisi metadata koneksi atau status keluar shell. | 
|  `0x04`- UBAH UKURAN | Klien ke layanan | UTF-8 JSON dalam bentuk`{"width":120,"height":40}`. Setiap dimensi harus dari 1 hingga 1.000. | 
|  `0x05`- DETAK JANTUNG | Kedua arah | Aplikasi opsional detak jantung. Layanan ini menggemakan muatan. WebSocket ping frame juga didukung. | 
|  `0xFF`- TUTUP | Kedua arah | Mengakhiri sesi shell. | 

Bingkai teks bukan bagian dari protokol. Layanan mengabaikan bingkai teks yang terisolasi dan menutup koneksi dengan kode `1003` setelah lima bingkai teks berturut-turut.

`STATUS`Bingkai pertama mengkonfirmasi koneksi dan menyertakan metadata yang mirip dengan yang berikut:

```
{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {
    "shellId": "my-shell",
    "reconnected": false
  },
  "status": "Success"
}
```

Saat shell keluar dengan status bukan nol, `STATUS` bingkai terakhir menyertakan `ExitCode` penyebab masuk. `details.causes`

## Sambungkan kembali ke shell
<a name="harness-command-shell-reconnect"></a>

Simpan ID sesi runtime dan ID shell. Untuk menyambung kembali, gunakan header ID sesi runtime yang sama dan tambahkan ID URL-encoded shell sebagai parameter kueri:

```
wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells?shellId=<shell-id>
```

Proses shell terus berjalan saat koneksi terlepas. Pada rekoneksi, layanan memutar ulang hingga 256 KB output buffer. `STATUS`Bingkai koneksi disetel `metadata.reconnected` ke `true` dan termasuk `metadata.bytesDropped` jika shell yang terlepas menghasilkan lebih banyak output daripada yang dapat dipertahankan oleh buffer replay.

Membuka koneksi lain dengan ID shell yang sama menggantikan koneksi yang ada. Klien yang diganti menerima kode dekat`4000`.

## Kasus penggunaan umum
<a name="harness-command-shell-use-cases"></a>

Debugging interaktif  
Periksa paket, file, proses, dan konfigurasi lingkungan yang diinstal di lingkungan yang sama dengan agen harness.

Validasi lingkungan kustom  
Untuk harness dengan wadah khusus, verifikasi dependensi yang diinstal dan pemasangan sistem file dari dalam wadah itu.

Akses terminal agen pengkodean  
Menyediakan lingkungan eksekusi persisten untuk agen pengkodean yang perlu membuat file, menjalankan tes, memeriksa output, dan mengulangi.

Long-running proses  
Mulai proses, lepaskan dari WebSocket, dan sambungkan kembali nanti untuk memeriksa kemajuan atau memberikan masukan.

## Pertimbangan keamanan
<a name="harness-command-shell-security"></a>

**penting**  
Principal yang dapat membuka shell Harness memiliki akses perintah interaktif ke sesi harness. Batasi `bedrock-agentcore:InvokeAgentRuntimeCommandShell` pada prinsipal tepercaya dan ARN harness tertentu.

Shell dapat mengakses data, file, dan rahasia yang disediakan pelanggan di lingkungan yang dipilih atau pada sistem file yang dipasang. Itu juga dapat terhubung ke tujuan jaringan yang dapat dicapai sesi. Lingkungan shell menggunakan allowlist dan tidak menyuntikkan kredensyal AgentCore platform atau beban kerja. Shell tetap berada di dalam microVM sesi yang terisolasi dan tidak dapat mengakses beban kerja pelanggan lain.

AgentCore mengirimkan ID permintaan dan metadata koneksi ke grup log Runtime harness di Amazon Logs. CloudWatch Layanan tidak mencatat input atau output terminal.

 AWS CloudTrail merekam panggilan `InvokeAgentRuntimeCommandShell` API, termasuk identitas pemanggil, stempel waktu, alamat IP sumber, sumber daya Runtime yang diselesaikan, dan status respons. CloudTrail tidak mencatat input atau output terminal.

Untuk panduan keamanan Harness lainnya, lihat[Kontrol keamanan dan akses](harness-security.md).

## Penanganan kesalahan
<a name="harness-command-shell-errors"></a>

 WebSocket Upgrade dapat mengembalikan kesalahan berikut:

 **ValidationException**   
Parameter permintaan tidak valid. Verifikasi bahwa ID sesi runtime berisi setidaknya 33 karakter, ID shell valid, dan fitur tersedia di Wilayah target. Gunakan ARN URL-encoded harness di jalur permintaan; penggunaan langsung ARN Runtime terkelola ditolak.

 **AccessDeniedException**   
Penelepon tidak memiliki `bedrock-agentcore:InvokeAgentRuntimeCommandShell` izin pada harness.

 **ResourceNotFoundException**   
Harness yang ditentukan tidak ada. Verifikasi bahwa URL berisi ARN URL-encoded harness.

 **ServiceQuotaExceededException (429)**   
Maksimal 10 cangkang aktif sudah terbuka. Akhiri cangkang aktif atau lepaskan, lalu coba lagi.

 **RuntimeClientError (424)**   
Runtime tidak dapat dicapai.

 **ThrottlingException**   
Permintaan melebihi batas tarif API. Coba lagi dengan backoff eksponensial.

 **RetryableConflictException (409)**   
Layanan ini menyediakan atau merobohkan sesi target. Coba lagi dengan backoff eksponensial pendek.

Setelah terhubung, kode tutup berikut menunjukkan mengapa koneksi berakhir:


| Kode | Arti | Tindakan klien | 
| --- | --- | --- | 
|  `1000`  | Cangkangnya keluar dengan bersih. | Perlakukan sebagai terminasi normal. | 
|  `1003`  | Klien mengirim lima frame teks berturut-turut ke protokol biner saja. | Beralih ke frame biner. Jangan tersambung kembali secara otomatis dengan perilaku yang sama. | 
|  `1006`  | Koneksi berakhir tanpa bingkai tertutup karena kegagalan jaringan atau gangguan layanan. | Sambungkan kembali dengan ID shell yang disimpan. | 
|  `1008`  | Durasi koneksi satu jam kedaluwarsa, frame rate melebihi 250 frame per detik, atau buffer tulis meluap. | Sambungkan kembali untuk durasi kedaluwarsa. Untuk pelanggaran tarif atau buffer, mundur sebelum menyambung kembali. | 
|  `1009`  | Payload bingkai melebihi 64 KB. | Pisahkan payload menjadi frame yang lebih kecil dari 64 KB, lalu sambungkan kembali. | 
|  `1011`  | Kegagalan server yang tidak terduga terjadi. | Coba lagi dengan backoff eksponensial. | 
|  `4000`  | Klien lain terhubung dengan ID shell yang sama. | Jangan tersambung kembali secara otomatis. Beri tahu pengguna bahwa klien lain melekat pada shell. | 

## Praktik terbaik
<a name="harness-command-shell-best-practices"></a>
+ Hasilkan dan pertahankan ID shell unik untuk setiap terminal logis.
+ Pertahankan ID sesi runtime dengan ID shell. Kedua nilai diperlukan untuk koneksi ulang.
+ Baca output segera sehingga buffer penulisan koneksi tidak terisi.
+ Pisahkan input besar menjadi bingkai biner yang lebih kecil dari 64 KB.
+ Sambungkan kembali sebelum atau sesudah batas koneksi satu jam jika shell harus tetap tersedia lebih lama.
+ Akhiri cangkang secara eksplisit ketika tidak lagi dibutuhkan. Cangkang yang terlepas tidak dihitung dalam batas 10-active-shell. Layanan ini mempertahankan paling banyak 20 entri shell aktif dan terpisah dan mengusir shell terpisah tertua bila diperlukan.
+ Gunakan batas waktu pemutakhiran minimal 330 detik saat koneksi dapat memulai sesi cold harness. Terapkan batas waktu terpisah sambil menunggu `STATUS` frame awal setelah upgrade.

## Kuota dan batas
<a name="harness-command-shell-limits"></a>


| Kuota | Nilai | Deskripsi | 
| --- | --- | --- | 
| Payload bingkai maksimum | 64 KB | Frame yang lebih besar menghasilkan kode dekat`1009`. | 
| Laju bingkai | 250 frame per detik | Melebihi batas menghasilkan kode `1008` tutup. | 
| Durasi koneksi maksimum | 1 jam | Sambungkan kembali dengan ID sesi runtime dan ID shell yang sama untuk melanjutkan. | 
| Cangkang aktif bersamaan per sesi harness | 10 | Koneksi baru ditolak ketika 10 shell aktif. Cangkang yang terlepas tidak dihitung dalam batas ini. | 
| Entri shell aktif dan terpisah yang dipertahankan | 20 | Ketika batas tercapai, layanan mengusir shell terpisah tertua sebelum membuat shell lain. | 
| Penyangga penyambungan ulang | 256 KB | Output maksimum diputar ulang setelah koneksi ulang. | 

Untuk batas layanan lengkap, lihat [Kuota untuk Amazon Bedrock AgentCore](bedrock-agentcore-limits.md).

## Topik terkait
<a name="_related_topics"></a>
+  [Lingkungan dan sistem file](harness-environment.md)- Konfigurasikan lingkungan default atau wadah khusus
+  [Kontrol keamanan dan akses](harness-security.md)- Kontrol akses ke harness dan lingkungan pelaksanaannya
+  [Observabilitas dan kontrol biaya](harness-operations.md)- memantau aktivitas dan biaya Harness
+  [Shell interaktif untuk AgentCore Runtime](runtime-get-started-command-shell.md)