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

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 yang dibawa lintas input. Ini memungkinkan debugging, inspeksi lingkungan, dan membangun pengalaman terminal dalam aplikasi Anda.

Untuk menelep InvokeAgentRuntimeCommandShell on, 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.

Koneksi mendukung:

Prasyarat

Menggunakan AgentCore CLI

Untuk petunjuk instalasi dan penyiapan, lihat Mem ulai dengan AgentCore CLI.

CLI menyediakan pengalaman terminal bawaan denganagentcore exec.

agentcore exec --it

Untuk menyambung ke runtime tertentu:

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

Tek Ctrl+] an untuk melepaskan dari cangkang tanpa menutupnya. CLI mencetak perintah reconnect:

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

Untuk perintah one-shot, 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

Koneksi ulang

Pola umum adalah digunakan 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 saat WebSocket koneksi terputus. 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 contoh di GitHub.

Kasus penggunaan umum

Pilihan desain utama

Pertimbangan keamanan

Batas keamanan untuk sesi shell (terminal) adalah microVM. Setiap sesi AgentCore 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 container dan kredenSIAL 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 memelihara jejak audit. Kon I/O ten terminal (stdin/stdout) dialirkan ke klien Anda dan tidak dicatat oleh layanan.

Audit dengan CloudTrail

AWS CloudTrail merek InvokeAgentRuntimeCommandShell am 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:

Penanganan kesalahan

Saat membuat koneksi sesi shell, Anda mungkin mengalami kesalahan berikut selama pemut WebSocket akhiran:

Setelah terhubung, kode tutup berikut menunjukkan mengapa koneksi dihentikan:

Praktik terbaik

Ikuti praktik terbaik ini saat menggunakanInvokeAgentRuntimeCommandShell:

Kuota dan batas

Untuk batas layanan lengkap, lihat Ku ota untuk Amazon Bedrock AgentCore.