Cara kerjanya Prasyarat Menggunakan AgentCore CLI Menggunakan AgentCore SDK Kasus penggunaan umum Pilihan desain utama Pertimbangan keamanan Penanganan kesalahan Praktik terbaik Kuota dan batas

Kerang Interaktif (Terminal)

InvokeAgentRuntimeCommandShellOperasi membuka sesi terminal interaktif yang persisten di dalam sesi AgentCore Runtime yang sedang berjalan. WebSocket Tidak seperti eksekusi perintah one-shot, sesi shell mempertahankan status — variabel lingkungan, direktori kerja, dan riwayat perintah membawa seluruh input. Hal ini memungkinkan debugging, inspeksi lingkungan, dan membangun pengalaman terminal dalam aplikasi Anda.

Untuk meneleponInvokeAgentRuntimeCommandShell, Anda memerlukan bedrock-agentcore:InvokeAgentRuntimeCommandShell izin.

Cara kerjanya

InvokeAgentRuntimeCommandShellmembuat 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

InvokeAgentRuntimeCommandShellberoperasi pada runtime agen yang sama dengan InvokeAgentRuntime danInvokeAgentRuntimeCommand. Anda tidak membuat sumber daya terpisah. Agen yang Anda gunakan CreateAgentRuntime menerima koneksi shell pada sesi aktif apa pun.

catatan

Anda dapat meneruskan a 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 masukan dalam sesi yang sama.
Rekoneksi	Berikan hal yang sama `session_id` dan `shellId` untuk menyambung kembali ke shell yang sama setelah terputus. Layanan memutar ulang hingga 256 KB output buffer.
Beberapa cangkang bersamaan	Hingga 10 sesi shell aktif (terminal) per runtime. Koneksi baru ditolak saat dalam kapasitas.

Prasyarat

bedrock-agentcore:InvokeAgentRuntimeCommandShellIzin IAM
ARN titik akhir AgentCore Runtime yang valid dengan runtime dalam status READY

catatan

Agen yang dibuat setelah 5 Juni 2026 mendukung shell interaktif (terminal) secara otomatis. Jika Anda menggunakan agen Anda sebelum tanggal ini, Anda harus menerapkannya kembali untuk memperbarui runtime agen.

Menggunakan AgentCore CLI

Untuk petunjuk instalasi dan penyiapan, lihat Memulai AgentCore Runtime menggunakan CLI.

CLI memberikan pengalaman terminal bawaan dengan. agentcore exec


agentcore exec --it

Untuk terhubung ke runtime tertentu:


agentcore exec --it --runtime <runtime-arn> --region us-west-2

Tekan Ctrl+] untuk melepaskan dari cangkang tanpa menutupnya. CLI mencetak perintah sambung kembali:


agentcore exec --it \
  --runtime <arn> \
  --region <region> \
  --session-id <uuid> \
  --shell-id <id>

Untuk perintah satu tembakan, hilangkan--it:


agentcore exec "ls -la /tmp"

Untuk output yang dapat dibaca mesin, gunakan mode JSON:


agentcore exec --json "echo hello"
# Output: {"success":true,"exitCode":0,"stdout":"hello\n","stderr":""}

Untuk contoh CLI tambahan, lihat AgentCore sampel di. GitHub

Menggunakan AgentCore SDK

Instal Python SDK:


pip install bedrock-agentcore

contoh

SigV4 (default)

Contoh berikut menunjukkan cara membuka sesi shell menggunakan AWS kredensyal default.


import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ShellChannel

async def main():
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    client = AgentCoreRuntimeClient(region="us-west-2")

    async with client.open_shell(runtime_arn) as shell:
        print(f"Connected. Shell ID: {shell.shell_id}")

        # Send a command
        await shell.send("echo Hello from AgentCore Shell\n")

        # Read output frames
        async for frame in shell:
            if frame.channel == ShellChannel.STDOUT:
                print(frame.text, end="")
                if "Hello from AgentCore Shell" in frame.text:
                    break

asyncio.run(main())

Pre-signed URL

Contoh berikut menunjukkan cara membuka sesi shell menggunakan URL yang telah ditandatangani sebelumnya.


import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, PresignedAuth, ShellChannel

async def main():
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    client = AgentCoreRuntimeClient(region="us-west-2")

    async with client.open_shell(runtime_arn, auth=PresignedAuth(expires=120)) as shell:
        await shell.send("whoami\n")

        async for frame in shell:
            if frame.channel == ShellChannel.STDOUT:
                print(frame.text, end="")
                break

asyncio.run(main())

OAuth

Contoh berikut menunjukkan cara membuka sesi shell menggunakan token pembawa OAuth.


import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, OAuthAuth, ShellChannel

async def main():
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    bearer_token = "your_oauth_token_here"
    client = AgentCoreRuntimeClient(region="us-west-2")

    async with client.open_shell(runtime_arn, auth=OAuthAuth(bearer_token=bearer_token)) as shell:
        await shell.send("echo oauth-connected\n")

        async for frame in shell:
            if frame.channel == ShellChannel.STDOUT:
                print(frame.text, end="")
                if "oauth-connected" in frame.text:
                    break

asyncio.run(main())

Rekoneksi

Pola yang umum digunakan shellId untuk menyambung kembali ke shell setelah terputus, 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 saat WebSocket koneksi turun. Gunakan ReconnectConfig untuk mengaktifkan ini:


import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel

async def on_reconnect(reconnected: bool):
    print(f"Reconnected: {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 sampel di GitHub.

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 tes, ia 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 di antara langkah-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 hidup lebih lama dari satu permintaan HTTP. 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 yang diakumulasikan oleh perintah sebelumnya (variabel yang diekspor, cd perubahan) tersedia untuk yang lebih baru.
Pembingkaian biner berakhir WebSocket: Terminal I/O dialirkan sebagai WebSocket frame biner. Ini mendukung urutan kontrol terminal mentah, warna, gerakan kursor, dan aplikasi layar penuh tanpa pengkodean overhead.
Koneksi ulang dengan replay output: Saat Anda menyambung kembali menggunakan yang samashellId, layanan memutar ulang hingga 256 KB output terbaru. Ini memungkinkan Anda pulih dari gangguan jaringan tanpa kehilangan konteks. Proses shell terus berjalan selama pemutusan.
Batas sesi: Ketika 10 sesi shell (terminal) sudah terbuka saat runtime, koneksi baru ditolak dengan kesalahan. Anda harus menutup sesi yang ada sebelum membuka yang baru.

Pertimbangan keamanan

Tip

Untuk tampilan gabungan dari semua rekomendasi keamanan Runtime, lihat Praktik terbaik keamanan untuk AgentCore Runtime.

penting

Di bawah model tanggung jawab AWS bersama, Anda bertanggung jawab atas perintah yang Anda jalankan dalam sesi AgentCore Runtime Anda. 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. Setiap sesi AgentCore Runtime berjalan dalam microVM terisolasi dengan kernel, memori, dan filesystem sendiri. Sesi Shell tidak dapat mengakses beban kerja pelanggan lain atau lolos dari batas VM. Namun, dalam VM Anda, perintah shell memiliki akses penuh ke sistem file kontainer dan kredensyal atau rahasia apa pun yang telah Anda konfigurasikan.

Audit dengan CloudWatch Log

AgentCore Runtime mengirimkan ID permintaan dan metadata koneksi ke grup CloudWatch log Amazon Logs agen Anda. Anda dapat menggunakan log ini untuk memantau aktivitas koneksi shell dan mempertahankan jejak audit. I/O Konten terminal (stdin/stdout) dialirkan ke klien Anda dan tidak dicatat oleh layanan.

Audit dengan CloudTrail

AWS CloudTrail merekam panggilan InvokeAgentRuntimeCommandShell API di akun Anda. Setiap catatan mencakup metadata seperti identitas pemanggil, stempel waktu, alamat IP sumber, dan status respons. CloudTrail tidak mencatat permintaan atau muatan respons. Gunakan CloudTrail untuk mengaudit siapa yang membuka sesi shell dan kapan, lalu berkorelasi dengan CloudWatch Log menggunakan ID permintaan untuk detail koneksi.

Untuk beban kerja yang sensitif, pertimbangkan untuk menerapkan kontrol tambahan seperti:

Menggunakan kebijakan IAM untuk membatasi prinsipal mana yang dapat memanggil InvokeAgentRuntimeCommandShell
Mengkonfigurasi titik akhir VPC untuk menjaga lalu lintas dalam jaringan Anda
Menyiapkan filter metrik CloudWatch Log 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 pemutakhiran:

ValidationException: Terjadi ketika parameter permintaan tidak valid. 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 bahwa kebijakan IAM Anda mencakup bedrock-agentcore:InvokeAgentRuntimeCommandShell izin.
ResourceNotFoundException: Terjadi ketika runtime agen yang ditentukan tidak dapat ditemukan. Verifikasi bahwa ARN runtime 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 backoff. Mengurai error bidang JSON badan respons untuk membedakan penyebab.
ThrottlingException: Terjadi ketika Anda melebihi batas tarif API. Menerapkan backoff eksponensial dan coba lagi logika.
ConflictException: Koneksi lain mengklaim hal yang sama shellId secara bersamaan. Coba lagi setelah 1 detik. Ini adalah kondisi balapan yang sempit (bukan keadaan persisten) dan segera diselesaikan dengan mencoba lagi.

Setelah terhubung, kode tutup berikut menunjukkan mengapa koneksi dihentikan:

Kode	Arti	Tindakan Klien
`1000`	Penutupan normal - cangkang keluar dengan bersih atau terputus dengan anggun	Tampilan “terputus”. Pengakhiran normal.
`1001`	Pergi - server menyebarkan atau mematikan	Auto-reconnect dengan disimpan`shellId`.
`1003`	Data yang tidak didukung - dikirim setelah 5 frame teks berturut-turut (protokol biner saja)	JANGAN sambungkan kembali secara otomatis. Beralih ke frame biner.
`1006`	Penutupan abnormal - disintesis secara lokal ketika tidak ada bingkai tutup yang diterima (kematian jaringan, TCP RST)	Auto-reconnect dengan disimpan`shellId`.
`1008`	Pelanggaran kebijakan — koneksi TTL kedaluwarsa (1 jam), batas frame rate terlampaui (250 frames/sec), atau write buffer overflow	Auto-reconnect untuk kedaluwarsa TTL (TTL baru saat menyambung kembali). Untuk batas tarif: mundur, lalu sambungkan kembali.
`1009`	Pesan terlalu besar — payload frame melebihi 64 KB	Kurangi ukuran bingkai (potongan menjadi <64 KB), lalu sambungkan kembali. Sesi masih hidup.
`1011`	Kesalahan server - kegagalan internal yang tidak terduga	Coba lagi dengan backoff.
`4000`	Diganti - klien lain yang terhubung dengan yang sama `shellId`	JANGAN sambungkan kembali secara otomatis. Tampilkan “sesi terlampir dari klien lain”.

Praktik terbaik

Ikuti praktik terbaik ini saat menggunakanInvokeAgentRuntimeCommandShell:

Gunakan unik shellId (seperti UUID) untuk setiap sesi logis untuk mengaktifkan koneksi ulang. Simpan shellId di sisi klien.
Gunakan ReconnectConfig dalam SDK untuk secara otomatis menangani interupsi jaringan transien tanpa logika rekoneksi manual.
Baca bingkai keluaran segera. Jika klien tertinggal, buffer tulis server terisi dan koneksi ditutup dengan kode. 1008
Untuk input besar (seperti menempelkan file), pisahkan konten menjadi potongan-potongan di bawah 64 KB per frame untuk menghindari kode penutupan. 1009
Tetapkan batas waktu koneksi yang sesuai. Durasi koneksi maksimum adalah 1 jam - sambungkan kembali dengan yang sama shellId untuk melanjutkan lebih dari itu.
Tutup sesi secara eksplisit setelah selesai. Sesi terpisah dihitung menuju batas 10 sesi.

Kuota dan batas

Kuota	Nilai	Deskripsi
Ukuran payload frame maksimum	64 KB	Bingkai yang melebihi batas ini menghasilkan kode `1009` tutup.
Laju bingkai	250 frames/sec	Melebihi ini memicu kode tutup. `1008`
Durasi koneksi maksimum	1 jam	Koneksi ditutup dengan kode`1008`. Sambungkan kembali menggunakan yang sama `shellId` untuk melanjutkan.
Sesi shell bersamaan (terminal) per runtime	10	Koneksi baru ditolak jika 10 sesi sudah terbuka. Tutup sesi yang ada dan coba lagi.
Penyangga penyambungan ulang	256 KB	Output maksimum diputar ulang saat menyambung kembali ke shell.

Untuk batas layanan lengkap, lihat Kuota untuk Amazon Bedrock AgentCore.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Jalankan perintah shell

Amati agen