Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Jalankan perintah shell dalam sesi AgentCore Runtime
InvokeAgentRuntimeCommandOperasi ini memungkinkan Anda menjalankan perintah shell langsung di dalam sesi AgentCore Runtime yang sedang berjalan dan mengalirkan output kembali HTTP/2. Perintah berjalan di wadah, sistem file, dan lingkungan yang sama dengan agen Anda - sesi yang sama digunakan olehInvokeAgentRuntime. Ini memungkinkan alur kerja di mana aplikasi Anda menggunakan agen untuk tugas penalaran dan perintah untuk operasi deterministik seperti menjalankan pengujian, operasi git, atau pengaturan lingkungan.
Untuk menelep InvokeAgentRuntimeCommand on, Anda memerlukan bedrock-agentcore:InvokeAgentRuntimeCommand izin.
Cara kerjanya
InvokeAgentRuntimeCommandmenjalankan perintah shell di dalam wadah sesi AgentCore Runtime aktif dan mengalirkan output kembali.
Agen yang sama, sesi yang sama
InvokeAgentRuntimeCommandberoperasi pada runtime dan sesi agen yang sama sepertiInvokeAgentRuntime. Anda tidak membuat sumber daya terpisah. Agen yang Anda gunakan CreateAgentRuntime menerima pemanggilan agen dan eksekusi perintah pada sesi aktif apa pun.
catatan
AgentCore Runtime MicroVM tidak menyertakan alat pengembang sepertigit,npm, atau runtime bahasa secara default. Alat apa pun yang bergantung pada perintah Anda harus disertakan dalam image wadah Anda (melalui Dockerfile Anda) atau diinstal secara dinamis saat runtime.
Responsnya adalah aliran dari tiga jenis peristiwa:
| Peristiwa | Saat | Contains |
|---|---|---|
|
|
Potongan pertama |
Mengonfirmasi perintah dimulai |
|
|
Selama eksekusi |
|
|
|
Potongan terakhir |
|
Aliran keluaran secara real time. Anda melihat hasil saat mereka berlari, bukan setelah mereka selesai.
Prasyarat
-
bedrock-agentcore:InvokeAgentRuntimeCommandIzin IAM -
ARN titik akhir AgentCore Runtime yang valid
catatan
Agen yang dibuat setelah 17 Maret 2026 mendukung eksekusi perintah secara otomatis. Jika Anda menerapkan agen sebelum tanggal ini, Anda harus menyebarkannya kembali untuk memperbarui runtime agen.
Jalankan perintah
contoh
Contoh alur kerja agen pengkodean
Pola umum adalah digunakan InvokeAgentRuntime untuk penalaran dan InvokeAgentRuntimeCommand untuk operasi deterministik dalam sesi yang sama.
Contoh alur kerja agen End-to-end pengkodean
import boto3 import json client = boto3.client('bedrock-agentcore', region_name='us-west-2') AGENT_ARN = 'arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent' SESSION_ID = 'session-id-at-least-33-characters-long' def run_command(command, timeout=60): """Helper to run a command and return the exit code.""" response = client.invoke_agent_runtime_command( agentRuntimeArn=AGENT_ARN, runtimeSessionId=SESSION_ID, contentType='application/json', accept='application/vnd.amazon.eventstream', body={'command': command, 'timeout': timeout} ) for event in response.get('stream', []): if 'chunk' in event and 'contentStop' in event['chunk']: return event['chunk']['contentStop'].get('exitCode') return None # Step 1: Invoke the agent to analyze and write a fix response = client.invoke_agent_runtime( agentRuntimeArn=AGENT_ARN, runtimeSessionId=SESSION_ID, payload=json.dumps({"prompt": "Read JIRA-1234 and implement the fix in /workspace"}).encode() ) # Process agent response... # Step 2: Run tests deterministically exit_code = run_command('/bin/bash -c "cd /workspace && npm test"', timeout=300) # Step 3: If tests pass, commit and push if exit_code == 0: run_command('/bin/bash -c "cd /workspace && git checkout -b fix/JIRA-1234"') run_command('/bin/bash -c "cd /workspace && git add -A && git commit -m \'Fix JIRA-1234\'"') run_command('/bin/bash -c "cd /workspace && git push origin fix/JIRA-1234"')
Agen menulis kode. Platform menjalankan perintah. Masing-masing melakukan apa yang terbaik.
Kasus penggunaan umum
- Menjalankan rangkaian pengujian
-
Setelah agen menulis kode, jalankan rangkaian pengujian proyek sebagai perintah. Respons streaming memungkinkan Anda mendeteksi kegagalan lebih awal dan memasukkan keluaran kesalahan tertentu kembali ke agen untuk iterasi.
/bin/bash -c "cd /workspace && npm test 2>&1" - Operasi Git
-
Percabangan, komitmen, dan mendorong adalah operasi deterministik. Jalankan mereka sebagai perintah setelah agen menyelesaikan pekerjaannya, menjaga logika kontrol versi keluar dari LLM.
/bin/bash -c "cd /workspace && git add -A && git commit -m 'Fix issue'" - Instalasi ketergantungan
-
Bootstrap lingkungan sebelum memanggil repo agen -clone, instal paket, siapkan perkakas build. Persiapan ini berjalan lebih cepat dan lebih andal sebagai perintah langsung.
/bin/bash -c "pip install -r requirements.txt" - Membangun dan mengkompilasi
-
Mengkompilasi langkah-langkah dan pembuatan aset -apa pun dengan perintah yang diketahui yang harus berjalan persis seperti yang ditentukan.
/bin/bash -c "cd /workspace && cargo build --release" - Linting dan validasi
-
Jalankan pemeriksaan kualitas kode sebagai gerbang validasi setelah agen menulis kode, sebelum melakukan.
/bin/bash -c "cd /workspace && npx eslint src/ --format json" - Inspeksi lingkungan
-
Periksa status runtime, paket yang diinstal, alat yang tersedia -berguna untuk kegagalan agen debugging.
/bin/bash -c "python --version && node --version && git --version" - Operasi data
-
Ambil kumpulan data, unggah hasil, jalankan transformasi data -jaringan dan operasi komputasi yang berjalan lebih cepat sebagai perintah langsung.
/bin/bash -c "aws s3 cp s3://my-bucket/data.csv /workspace/"
Pilihan desain utama
- One-shot, eksekusi non-interaktif
-
Setiap perintah memunculkan proses bash baru, berjalan hingga selesai (atau batas waktu), dan kembali. Tidak ada sesi shell persisten antara perintah. Ini cocok dengan bagaimana kerangka kerja agen menggunakan eksekusi perintah -membuat perintah, menjalankannya, membaca output, memutuskan apa yang harus dilakukan selanjutnya.
- Respon streaming berakhir HTTP/2
-
Output tiba saat diproduksi, tidak di-buffer sampai selesai. A
npm testyang membutuhkan waktu dua menit streaming menghasilkan secara real time. Aplikasi Anda dapat mendeteksi kegagalan dalam beberapa detik pertama dan membatalkan lebih awal daripada menunggu proses penuh. - Isolasi kontainer
-
Perintah dieksekusi di dalam wadah yang sama dengan kode agen Anda. Mereka melihat sistem file yang sama, variabel lingkungan, dan paket yang diinstal. File tempat agen menulis segera
/workspace/fix.pyterlihat oleh perintah yang sedang berjalancat /workspace/fix.py. - Non-blocking ke runtime
-
Eksekusi perintah tidak memblokir pemanggilan agen. Anda dapat memanggil agen dan menjalankan perintah secara bersamaan pada sesi yang sama. Platform menangani konkurensi.
- Tanpa kewarganegaraan antar perintah
-
Setiap perintah memulai baru -tidak ada riwayat shell, tidak ada perubahan variabel lingkungan dari perintah sebelumnya yang dibawa. Jika Anda membutuhkan status, kodekan dalam perintah itu sendiri:
cd /workspace && export NODE_ENV=test && npm test.
Pertimbangan keamanan
Tip
Untuk tampilan gabungan dari semua rekomendasi keamanan Runtime, lihat Prakti k terbaik keamanan untuk AgentCore Runtime.
penting
Di bawah model tanggung jawab AWS bersama, Anda bertanggung jawab atas keamanan 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 eksekusi perintah adalah microVM. Setiap sesi AgentCore Runtime berjalan di microVM terisolasi dengan kernel, memori, dan filesystem sendiri. Perintah yang Anda jalankan tidak dapat mengakses beban kerja pelanggan lain atau lolos dari batas VM. Namun, di dalam VM Anda, perintah 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 perintah input ke grup CloudWatch log Amazon Logs agen Anda. Anda dapat menggunakan log ini untuk memantau aktivitas perintah dan memelihara jejak audit dari perintah apa yang dieksekusi dalam sesi Anda. Output eksekusi perintah (stdout dan stderr) dialirkan kembali ke aplikasi Anda dan tidak dicatat oleh layanan.
Audit dengan CloudTrail
AWS CloudTrail merek InvokeAgentRuntimeCommand 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 menjalankan perintah dan kapan, kemudian berkorelasi dengan CloudWatch log log menggunakan ID permintaan untuk melihat perintah apa yang dijalankan.
Untuk beban kerja sensitif, pertimbangkan untuk menerapkan kontrol tambahan seperti:
-
Menggunakan kebijakan IAM untuk membatasi kepala sekolah mana yang dapat memanggil
InvokeAgentRuntimeCommand -
Mengkonfigurasi titik akhir VPC untuk menjaga lalu lintas dalam jaringan Anda
-
Menyiapkan filter metrik CloudWatch Logs dan alarm untuk mendeteksi pola perintah yang tidak terduga
-
Meninjau CloudTrail log secara teratur untuk upaya akses yang tidak sah
Penanganan kesalahan
Saat menggunakan InvokeAgentRuntimeCommand operasi, Anda mungkin mengalami kesalahan berikut:
- ValidationException
-
Terjadi ketika parameter permintaan tidak valid. Periksa apakah ARN agen Anda, ID sesi, dan perintah diformat dengan benar. Perintah harus antara 1 byte dan 64 KB, batas waktu harus antara 1 dan 3600 detik, dan ID sesi harus setidaknya 33 karakter.
- ResourceNotFoundException
-
Terjadi ketika runtime atau sesi agen tertentu tidak dapat ditemukan. Verifikasi bahwa agen ARN benar dan sesi aktif.
- AccessDeniedException
-
Terjadi ketika Anda tidak memiliki izin yang diperlukan. Pastikan kebijakan IAM Anda menyertakan
bedrock-agentcore:InvokeAgentRuntimeCommandizin tersebut. - ThrottlingException
-
Terjadi ketika Anda melebihi batas tingkat permintaan 25 TPS. Terapkan logika backoff eksponensial dan coba lagi di aplikasi Anda.
- RetryableConflictException
-
Terjadi (HTTP 409) ketika
InvokeAgentRuntimeCommandoperasi menargetkan sesi yang disediakan atau dihancurkan oleh layanan. Pesannya adalahSession operation in progress, please retry. Kondisi ini bersifat sementara dan dapat dicoba kembali. Coba lagi dengan mundur eksponensial pendek alih-alih memperlakukannya sebagai terminal. SDK AWS mencoba ulang pengecualian ini secara otomatis saat percobaan ulang default diaktifkan. Jika Anda menonaktifkan percobaan ulang atau memanggil API secara langsung tanpa AWS SDK, coba lagi sendiri.
Perintah yang dilengkapi dengan kode keluar bukan nol bukanlah kesalahan API. Periksa exitCode dalam contentStop acara untuk menentukan apakah perintah itu sendiri berhasil. A status of TIMED_OUT menunjukkan perintah melebihi batas waktu yang ditentukan.
Praktik terbaik
Ikuti praktik terbaik ini saat menggunakan InvokeAgentRuntimeCommand operasi:
-
Gunakan
InvokeAgentRuntimeCommanduntuk operasi deterministik (tes, git, build) danInvokeAgentRuntimeuntuk tugas penalaran. Jangan merutekan operasi deterministik melalui LLM. -
Sertakan alat pengembang apa pun yang bergantung pada perintah Anda (seperti
git,npm, atau runtime bahasa) dalam image kontainer Anda melalui Dockerfile Anda. -
Selalu
exitCodeperiksa dalamcontentStopacara untuk menentukan apakah perintah berhasil. -
Tetapkan batas waktu yang sesuai. Sebuah rangkaian pengujian mungkin membutuhkan 5 menit, sementara
git pushmungkin hanya membutuhkan 30 detik. -
Memproses output streaming secara bertahap untuk mendeteksi kegagalan lebih awal. Anda dapat membatalkan perintah yang berjalan lama daripada menunggu sampai selesai.
-
Enkode status dalam perintah itu sendiri menggunakan
&&rantai (misalnya,cd /workspace && export NODE_ENV=test && npm test), karena setiap perintah memulai proses bash baru. -
Gunakan UUID untuk ID sesi untuk memenuhi persyaratan minimum 33 karakter (misalnya,
12345678-1234-1234-1234-123456789012).