Cangkang interaktif (terminal)

InvokeAgentRuntimeCommandShellOperasi 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

InvokeAgentRuntimeCommandShellmembuat 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

• 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 dandash, saat ini tidak didukung.

Untuk informasi selengkapnya tentang model izin harness lengkap, lihat. Izin IAM yang diperlukan untuk penelepon

Connect melalui WebSocket API

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-Idheader 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.
shellIdparameter 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 ProtocolsRespons 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 kembali101 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

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.

STATUSBingkai 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

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. STATUSBingkai 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 dekat4000.

Kasus penggunaan umum

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

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, lihatKontrol keamanan dan akses.

Penanganan kesalahan

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

• 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

Kuota	Nilai	Deskripsi
Payload bingkai maksimum	64 KB	Frame yang lebih besar menghasilkan kode dekat1009.
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.

Topik terkait

• Lingkungan dan sistem file- Konfigurasikan lingkungan default atau wadah khusus

• Kontrol keamanan dan akses- Kontrol akses ke harness dan lingkungan pelaksanaannya

• Observabilitas dan kontrol biaya- memantau aktivitas dan biaya Harness

• Shell interaktif untuk AgentCore Runtime