Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Kerang Interaktif (Terminal)
InvokeAgentRuntimeCommandShell operasi membuka sesi terminal interaktif yang persisten di dalam yang sedang berjalan AgentCore Sesi runtime berakhir WebSocket. Tidak seperti eksekusi perintah one-shot, sesi shell mempertahankan status — variabel lingkungan, direktori kerja, dan riwayat perintah yang dibawa lintas input. Ini memungkinkan debugging, inspeksi lingkungan, dan membangun pengalaman terminal dalam aplikasi Anda.
Untuk menelepon InvokeAgentRuntimeCommandShell, Anda perlu bedrock-agentcore:InvokeAgentRuntimeCommandShell izin.
Cara kerjanya
InvokeAgentRuntimeCommandShell menetapkan a WebSocket koneksi ke proses shell interaktif yang berjalan di dalam sesi agen Anda. Koneksi menggunakan frame biner untuk mengalirkan input dan output terminal di kedua arah.
Agen yang sama, sesi yang sama
InvokeAgentRuntimeCommandShell beroperasi pada runtime agen yang sama dengan InvokeAgentRuntime dan InvokeAgentRuntimeCommand. Anda tidak membuat sumber daya terpisah. Agen yang Anda kerahkan CreateAgentRuntime menerima koneksi shell pada sesi aktif apa pun.
Anda bisa lulus session_id untuk menargetkan sesi runtime tertentu. Jika dihilangkan, sesi baru dibuat untuk setiap koneksi. Untuk menggunakan koneksi ulang, Anda harus menyimpan dan menggunakan kembali keduanya session_id dan shellId.
Koneksi mendukung:
| Fitur | Deskripsi |
|---|---|
|
Keadaan persisten |
Variabel lingkungan, direktori kerja, dan riwayat perintah membawa input dalam sesi yang sama. |
|
Koneksi ulang |
Berikan hal yang sama |
|
Beberapa shell bersamaan |
Hingga 10 sesi shell aktif (terminal) per runtime. Koneksi baru ditolak saat dalam kapasitas. |
Prasyarat
-
bedrock-agentcore:InvokeAgentRuntimeCommandShellIzin IAM -
Yang valid AgentCore Titik akhir runtime ARN dengan runtime dalam keadaan READY
Agen yang dibuat setelah 5 Juni 2026 mendukung shell interaktif (terminal) secara otomatis. Jika Anda menerapkan agen sebelum tanggal ini, Anda harus menyebarkannya kembali untuk memperbarui runtime agen.
Menggunakan AgentCore CLI
Untuk petunjuk pemasangan dan penyiapan, lihat Mulailah dengan AgentCore CLI.
CLI menyediakan pengalaman terminal interaktif bawaan. Berikan Runtime ID, bukan Runtime ARN. Untuk Runtime dalam AgentCore proyek, Runtime ID adalah segmen terakhir dari Runtime arn dalam output dari agentcore status --json:
Untuk lingkungan yang dikelola oleh Harness, gunakan agentcore harness shell --id <harness-id> alih-alih ID Runtime yang dikelola. Lihat Buka cangkang Harness dengan AgentCore CLI.
agentcore runtime shell --id <runtime-id>
Tanpa --qualifier, CLI meminta Anda untuk memilih titik akhir. Untuk memilih titik akhir secara langsung:
agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --region us-west-2
Gunakan --session-id untuk membuka shell dalam sesi Runtime tertentu:
agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --session-id <runtime-session-id>
Setelah menghubungkan, CLI mencetak ID sesi Runtime, ID shell, dan perintah reconnect lengkap. Tekan Ctrl+] untuk melepaskan terminal lokal sambil menjaga shell jarak jauh tetap berjalan:
Connected Session ID: <runtime-session-id> Shell ID: <shell-id> Ctrl+D or 'exit' to close · Ctrl+] to detach To reconnect: agentcore runtime shell --id <runtime-id> --qualifier DEFAULT --session-id <runtime-session-id> --shell-id <shell-id> --region us-west-2
Jalankan perintah yang dicetak untuk menyambung kembali ke shell yang sama. Saat membuat perintah sendiri, --shell-id memerlukan --session-id:
agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --session-id <runtime-session-id> \ --shell-id <shell-id> \ --region us-west-2
Untuk Runtime yang dikonfigurasi dengan otorisasi CUSTOM_JWT, berikan juga token pembawanya:
agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --bearer-token file://token.txt
Perintah reconnect tidak pernah menyertakan token pembawa. Lulus --bearer-token lagi saat menghubungkan kembali ke CUSTOM_JWT Runtime.
Masuk exit atau tekan Ctrl+D untuk menutup shell jarak jauh secara permanen. Tekan Ctrl+] ketika Anda ingin melepaskan dan menyambung kembali nanti.
Untuk menjalankan satu perintah tanpa membuka shell, gunakan agentcore runtime exec:
agentcore runtime exec \ --id <runtime-id> \ --command "ls -la /tmp"
Untuk contoh CLI tambahan, lihat AgentCore mencicipi
Menggunakan AgentCore SDK
Instal Python SDK:
pip install bedrock-agentcore
contoh
Koneksi ulang
Pola umum adalah menggunakan shellId untuk menyambung kembali ke shell setelah pemutusan, mempertahankan semua status sesi.
import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient async def main(): client = AgentCoreRuntimeClient(region="us-west-2") runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" session_id = "my-session-0000000000000000000000" shell_id = "my-shell" shell = await client.open_shell( runtime_arn, session_id=session_id, shell_id=shell_id, ).__aenter__() print(f"connected (reconnected={shell.reconnected})") await shell.send("export GREETING='hello'\n") await asyncio.sleep(1) async with client.open_shell( runtime_arn, session_id=session_id, shell_id=shell_id, ) as shell2: print(f"reconnected (reconnected={shell2.reconnected})") assert shell2.reconnected if __name__ == "__main__": asyncio.run(main())
Auto-reconnect
SDK juga dapat terhubung kembali secara otomatis ketika WebSocket koneksi turun. Gunakan ReconnectConfig untuk mengaktifkan ini:
import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel async def on_reconnect(): print("Reconnected") async def main(): runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" shell_id = "my-persistent-shell" config = ReconnectConfig(max_retries=5, base_delay=0.5, on_reconnect=on_reconnect) client = AgentCoreRuntimeClient(region="us-west-2") async with client.open_shell(runtime_arn, shell_id=shell_id, reconnect_config=config) as shell: # If the connection drops, the SDK retries automatically await shell.send("long-running-command\n") async for frame in shell: if frame.channel == ShellChannel.STDOUT: print(frame.text, end="") asyncio.run(main())
Untuk contoh SDK tambahan, lihat AgentCore mencicipi
Kasus penggunaan umum
- Debugging interaktif
-
Buka shell untuk memeriksa lingkungan runtime agen Anda — periksa paket yang diinstal, baca file log, periksa sistem file, atau uji perintah sebelum menambahkannya ke kode agen Anda.
python --version && pip list | head -20 - Inspeksi lingkungan
-
Verifikasi variabel lingkungan, konektivitas jaringan, alat yang tersedia, dan status sistem file. Berguna saat mendiagnosis kegagalan agen atau memvalidasi konfigurasi penerapan.
env | grep AWS && curl -s http://169.254.169.254/latest/meta-data/ - Akses terminal agen pengkodean
-
Agen pengkodean AI menggunakan shell interaktif (terminal) sebagai lingkungan eksekusi mereka. Ketika agen pengkodean perlu menjalankan kode, menginstal paket, atau menjalankan pengujian, itu membuka sesi shell ke AgentCore Runtime dan mengeksekusi perintah secara langsung - dengan cara yang sama pengembang akan menggunakan terminal. Misalnya, Claude Code, Amazon Kiro, dan OpenAI Codex masing-masing terhubung ke sesi shell di mana mereka dapat menulis kode secara berulang, menjalankannya, mengamati output, dan memperbaiki kesalahan dalam satu loop. Status persisten berarti agen dapat menjalankan urutan perintah tanpa kehilangan konteks antar langkah.
# A coding agent opens a shell and iterates on code async with client.open_shell(runtime_arn, shell_id="agent-workspace") as shell: await shell.send("cd /workspace && git clone https://github.com/user/repo.git\n") await shell.send("cd repo && pip install -r requirements.txt\n") await shell.send("python -m pytest tests/ -v\n") # Agent reads test output, fixes failures, re-runs — all in the same shell - Long-running proses
-
Mulai proses yang bertahan lebih lama dari permintaan HTTP tunggal. Gunakan koneksi ulang untuk memeriksa kemajuan atau memberikan masukan tambahan dari waktu ke waktu.
nohup python train.py > /tmp/train.log 2>&1 &
Pilihan desain utama
- Sesi interaktif yang persisten
-
Setiap koneksi memetakan ke proses shell yang berumur panjang. Anda dapat mengirim beberapa perintah tanpa membangun kembali koneksi, dan status terakumulasi oleh perintah sebelumnya (variabel yang diekspor,
cdperubahan) tersedia untuk yang nanti. - Pembingkaian biner berakhir WebSocket
-
Terminal I/O dialirkan sebagai biner WebSocket bingkai. Ini mendukung urutan kontrol terminal mentah, warna, gerakan kursor, dan aplikasi layar penuh tanpa pengkodean overhead.
- Koneksi ulang dengan pemutaran ulang output
-
Saat Anda menyambung kembali menggunakan yang sama
shellId, layanan memutar ulang hingga 256 KB output terbaru. Ini memungkinkan Anda memulihkan dari gangguan jaringan tanpa kehilangan konteks. Proses shell terus berjalan selama pemutusan. - Batas sesi
-
Ketika 10 sesi shell (terminal) sudah terbuka pada runtime, koneksi baru ditolak dengan kesalahan. Anda harus menutup sesi yang sudah ada sebelum membuka yang baru.
Pertimbangan keamanan
Untuk tampilan gabungan dari semua rekomendasi keamanan Runtime, lihat Praktik terbaik keamanan untuk AgentCore Waktu pelaksanaan.
Di bawah AWS model tanggung jawab bersama, Anda bertanggung jawab atas perintah yang Anda jalankan di AgentCore Sesi runtime. AWS menyediakan infrastruktur dan isolasi yang aman di tingkat microVM. Anda bertanggung jawab atas perintah yang Anda jalankan, data yang Anda proses, dan kontrol akses yang Anda konfigurasikan.
Batas keamanan untuk sesi shell (terminal) adalah microVM. Masing-masing AgentCore Sesi runtime berjalan di microVM terisolasi dengan kernel, memori, dan filesystem sendiri. Sesi Shell tidak dapat mengakses beban kerja pelanggan lain atau keluar dari batas VM. Namun, di dalam VM Anda, perintah shell memiliki akses penuh ke sistem file kontainer dan kredenSIAL atau rahasia apa pun yang telah Anda konfigurasikan.
Audit dengan CloudWatch Log
AgentCore Runtime mengirimkan ID permintaan dan metadata koneksi ke Amazon agen Anda CloudWatch Grup log log. Anda dapat menggunakan log ini untuk memantau aktivitas koneksi shell dan memelihara jejak audit. Terminal I/O konten (stdin/stdout) dialirkan ke klien Anda dan tidak dicatat oleh layanan.
Audit dengan CloudTrail
AWS CloudTrail rekor InvokeAgentRuntimeCommandShell Panggilan API di akun Anda. Setiap catatan menyertakan metadata seperti identitas pemanggil, stempel waktu, alamat IP sumber, dan status respons. CloudTrail tidak mencatat permintaan atau payload respons. Gunakan CloudTrail untuk mengaudit siapa yang membuka sesi shell dan kapan, kemudian berkorelasi dengan CloudWatch Log menggunakan ID permintaan untuk detail koneksi.
Untuk beban kerja sensitif, pertimbangkan untuk menerapkan kontrol tambahan seperti:
-
Menggunakan kebijakan IAM untuk membatasi kepala sekolah mana yang dapat memanggil
InvokeAgentRuntimeCommandShell -
Mengkonfigurasi titik akhir VPC untuk menjaga lalu lintas dalam jaringan Anda
-
Menyiapkan CloudWatch Mencatat filter metrik dan alarm untuk mendeteksi pola koneksi yang tidak terduga
-
Meninjau CloudTrail log secara teratur untuk upaya akses yang tidak sah
Penanganan kesalahan
Saat membuat koneksi sesi shell, Anda mungkin mengalami kesalahan berikut selama WebSocket meningkatkan:
Jika CLI melaporkan Server rejected WebSocket connection: HTTP 400 dan Runtime dikelola oleh Harness, gunakan perintah Harness shell dengan Harness ID. Respons HTTP 400 lainnya dapat memiliki penyebab yang berbeda; verifikasi sumber daya dan permintaan daripada mengasumsikan setiap penolakan mengidentifikasi Harness.
- ValidationException
-
Terjadi ketika parameter permintaan tidak valid. Hal ini dapat terjadi jika ID sesi kurang dari 33 karakter, fitur tidak diaktifkan di wilayah target, atau agen tidak dalam status READY.
- AccessDeniedException
-
Terjadi ketika Anda tidak memiliki izin yang diperlukan. Pastikan kebijakan IAM Anda mencakup
bedrock-agentcore:InvokeAgentRuntimeCommandShellizin. - ResourceNotFoundException
-
Terjadi ketika runtime agen yang ditentukan tidak dapat ditemukan. Verifikasi bahwa runtime ARN sudah benar.
- RuntimeClientError (424)
-
Terjadi dalam beberapa skenario: (1) Sesi shell bersamaan maksimum (terminal) tercapai (10 terbuka) — tutup sesi yang ada dan coba lagi. (2) Format ID Shell tidak valid - harus 1-128 karakter alfanumerik, garis bawah, atau tanda hubung. (3) Runtime tidak dapat dijangkau - coba lagi setelah mundur. Parsing badan respons JSON
errorbidang untuk membedakan penyebab. - ThrottlingException
-
Terjadi saat Anda melebihi batas tarif API. Terapkan logika mundur eksponensial dan coba lagi.
- ConflictException
-
Koneksi lain mengklaim hal yang sama
shellIdsecara bersamaan. Coba lagi setelah 1 detik. Ini adalah kondisi balapan yang sempit (bukan keadaan persisten) dan segera diselesaikan saat dicoba lagi. - RetryableConflictException (409)
-
Terjadi ketika Anda membuka koneksi sesi shell saat layanan menyediakan atau menghancurkan sesi target. Pesannya adalah
Session operation in progress, please retry. Kondisi ini bersifat sementara dan dapat dicoba kembali. Jendelanya singkat dan sesi yang sudah berjalan tidak terpengaruh. Coba lagi dengan mundur eksponensial pendek. KarenaInvokeAgentRuntimeCommandShelladalah WebSocket API, AWS SDK tidak mencobanya ulang secara otomatis. Coba lagi sendiri.
Setelah terhubung, kode tutup berikut menunjukkan mengapa koneksi dihentikan:
| Kode | Arti | Tindakan Klien |
|---|---|---|
|
|
Penutupan normal - cangkang keluar dengan bersih atau terputus anggun |
Tampilan “terputus”. Penghentian normal. |
|
|
Pergi — server menyebarkan atau mematikan |
Auto-reconnect dengan disimpan |
|
|
Data tidak didukung - dikirim setelah 5 bingkai teks berturut-turut (protokol biner saja) |
JANGAN sambungkan kembali secara otomatis. Beralih ke bingkai biner. |
|
|
Penutupan abnormal - disintesis secara lokal ketika tidak ada bingkai dekat yang diterima (kematian jaringan, TCP RST) |
Auto-reconnect dengan disimpan |
|
|
Pelanggaran kebijakan - koneksi TTL kedaluwarsa (1 jam), batas kecepatan bingkai terlampaui (250 frames/sec), atau tulis buffer overflow |
Auto-reconnect untuk kedaluwarsa TTL (TTL baru saat menyambung kembali). Untuk batas tarif: mundur, lalu sambungkan kembali. |
|
|
Pesan terlalu besar — muatan bingkai melebihi 64 KB |
Kurangi ukuran bingkai (potongan menjadi <64 KB), lalu sambungkan kembali. Session masih hidup. |
|
|
Kesalahan server - kegagalan internal yang tidak terduga |
Coba lagi dengan mundur. |
|
|
Diganti — klien lain terhubung dengan yang sama |
JANGAN sambungkan kembali secara otomatis. Tampilkan “sesi terlampir dari klien lain”. |
Praktik Terbaik
Ikuti praktik terbaik ini saat menggunakan InvokeAgentRuntimeCommandShell:
-
Gunakan yang unik
shellId(seperti UUID) untuk setiap sesi logis untuk mengaktifkan koneksi ulang. SimpanshellIddi sisi klien. -
Gunakan
ReconnectConfigdi SDK untuk secara otomatis menangani gangguan jaringan sementara tanpa logika koneksi ulang manual. -
Baca bingkai keluaran segera. Jika klien tertinggal, buffer tulis server terisi dan koneksi ditutup dengan kode
1008. -
Untuk input besar (seperti menempelkan file), bagi konten menjadi potongan-potongan di bawah 64 KB per frame untuk menghindari kode tertutup
1009. -
Tetapkan batas waktu koneksi yang sesuai. Durasi koneksi maksimum adalah 1 jam - sambungkan kembali dengan yang sama
shellIduntuk melanjutkan melampaui itu. -
Tutup sesi secara eksplisit setelah selesai. Sesi terpisah dihitung terhadap batas 10 sesi.
Kuota dan Batas
| Batas | Nilai | Deskripsi |
|---|---|---|
|
Ukuran muatan bingkai maksimum |
64 KB |
Bingkai yang melebihi batas ini menghasilkan kode tertutup |
|
Laju bingkai |
250 frames/sec |
Melebihi ini memicu kode tutup |
|
Durasi koneksi maksimum |
1 jam |
Koneksi ditutup dengan kode |
|
Sesi shell bersamaan (terminal) per runtime |
10 |
Koneksi baru ditolak jika 10 sesi sudah terbuka. Tutup sesi yang ada dan coba lagi. |
|
Buffer koneksi ulang |
256 KB |
Output maksimum diputar ulang saat menghubungkan kembali ke shell. |
Untuk batas layanan lengkap, lihat Kuota untuk Amazon Bedrock AgentCore.