View a markdown version of this page

Jalankan perintah shell di AgentCore Sesi runtime - Batu Dasar Amazon AgentCore

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

Jalankan perintah shell di AgentCore Sesi runtime

Yang InvokeAgentRuntimeCommand operasi memungkinkan Anda menjalankan perintah shell langsung di dalam yang sedang berjalan AgentCore Runtime sesi dan streaming output kembali HTTP/2. Perintah berjalan di wadah, sistem file, dan lingkungan yang sama dengan agen Anda - sesi yang sama digunakan oleh InvokeAgentRuntime . 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 menelepon InvokeAgentRuntimeCommand , Anda perlu bedrock-agentcore:InvokeAgentRuntimeCommand izin.

Cara kerjanya

InvokeAgentRuntimeCommand menjalankan perintah shell di dalam wadah aktif AgentCore Runtime session dan streaming output kembali.

Agen yang sama, sesi yang sama

InvokeAgentRuntimeCommand beroperasi pada runtime dan sesi agen yang sama seperti InvokeAgentRuntime . Anda tidak membuat sumber daya terpisah. Agen yang Anda kerahkan CreateAgentRuntime menerima pemanggilan agen dan eksekusi perintah pada sesi aktif apa pun.

catatan

Yang AgentCore Runtime MicroVM tidak menyertakan alat pengembang seperti git , 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 Berisi

contentStart

Potongan pertama

Mengonfirmasi perintah dimulai

contentDelta

Selama eksekusi

stdout and/or stderr keluaran

contentStop

Potongan terakhir

exitCode dan status ( COMPLETED atau TIMED_OUT )

Aliran keluaran secara real time. Anda melihat hasil saat mereka berlari, bukan setelah mereka selesai.

Prasyarat

  • bedrock-agentcore:InvokeAgentRuntimeCommand Izin IAM

  • Yang valid AgentCore Titik akhir runtime ARN

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
AgentCore CLI
  1. Jalankan agentcore runtime exec dengan Runtime ID. Runtime ID adalah segmen terakhir dari Runtime ARN. ID sesi harus terdiri dari 33 hingga 100 karakter:

    agentcore runtime exec \ --id <runtime-id> \ --session-id <session-id> \ --command "ls -la /workspace"

    Perintah mencetak JSON dengan sessionId, command, exitCode, status, dan output bidang. Tambah --timeout <seconds> (1 hingga 3600) untuk membatasi berapa lama perintah berjalan, dan --qualifier <endpoint> untuk menargetkan titik akhir selain DEFAULT.

Python
  1. Contoh berikut menunjukkan cara menggunakan boto3 untuk menjalankan perintah di AgentCore Sesi runtime.

    import boto3 import sys client = boto3.client('bedrock-agentcore', region_name='us-west-2') response = client.invoke_agent_runtime_command( agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent', runtimeSessionId='session-id-at-least-33-characters-long', qualifier='DEFAULT', contentType='application/json', accept='application/vnd.amazon.eventstream', body={ 'command': '/bin/bash -c "npm test"', 'timeout': 60 } ) # Process the streaming response for event in response.get('stream', []): if 'chunk' in event: chunk = event['chunk'] if 'contentStart' in chunk: print("Command execution started") if 'contentDelta' in chunk: delta = chunk['contentDelta'] if delta.get('stdout'): print(delta['stdout'], end='') if delta.get('stderr'): print(delta['stderr'], end='', file=sys.stderr) if 'contentStop' in chunk: stop = chunk['contentStop'] print(f"\nExit code: {stop.get('exitCode')}, Status: {stop.get('status')}")
Java
  1. Contoh berikut menunjukkan cara menggunakan AWS SDK untuk Java untuk menjalankan perintah di AgentCore Sesi runtime.

    import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.bedrockagentcore.BedrockAgentCoreAsyncClient; import software.amazon.awssdk.services.bedrockagentcore.model.*; import java.util.UUID; import java.util.concurrent.CompletableFuture; public class ExecuteCommandExample { public static void main(String[] args) throws Exception { String agentArn = "arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent"; String sessionId = UUID.randomUUID().toString(); BedrockAgentCoreAsyncClient client = BedrockAgentCoreAsyncClient.builder() .region(Region.US_WEST_2) .credentialsProvider(DefaultCredentialsProvider.create()) .build(); InvokeAgentRuntimeCommandRequest request = InvokeAgentRuntimeCommandRequest.builder() .agentRuntimeArn(agentArn) .runtimeSessionId(sessionId) .qualifier("DEFAULT") .contentType("application/json") .accept("application/vnd.amazon.eventstream") .body(InvokeAgentRuntimeCommandRequestBody.builder() .command("/bin/bash -c \"npm test\"") .timeout(60) .build()) .build(); InvokeAgentRuntimeCommandResponseHandler handler = InvokeAgentRuntimeCommandResponseHandler.builder() .subscriber(InvokeAgentRuntimeCommandResponseHandler.Visitor.builder() .onChunk(chunk -> { if (chunk.contentStart() != null) { System.out.println("Command execution started"); } if (chunk.contentDelta() != null) { ContentDeltaEvent delta = chunk.contentDelta(); if (delta.stdout() != null) System.out.print(delta.stdout()); if (delta.stderr() != null) System.err.print(delta.stderr()); } if (chunk.contentStop() != null) { ContentStopEvent stop = chunk.contentStop(); System.out.println("\nExit code: " + stop.exitCode() + ", Status: " + stop.statusAsString()); } }) .build()) .build(); CompletableFuture<Void> future = client.invokeAgentRuntimeCommand(request, handler); future.get(); client.close(); } }
JavaScript
  1. Contoh berikut menunjukkan cara menggunakan AWS SDK untuk JavaScript v3 untuk menjalankan perintah dalam AgentCore Sesi runtime.

    import { BedrockAgentCoreClient, InvokeAgentRuntimeCommandCommand } from "@aws-sdk/client-bedrock-agentcore"; import { randomUUID } from "crypto"; const client = new BedrockAgentCoreClient({ region: "us-west-2" }); const request = { agentRuntimeArn: "arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent", runtimeSessionId: randomUUID(), qualifier: "DEFAULT", contentType: "application/json", accept: "application/vnd.amazon.eventstream", body: { command: '/bin/bash -c "npm test"', timeout: 60, }, }; const command = new InvokeAgentRuntimeCommandCommand(request); const response = await client.send(command); // Process the event stream for await (const event of response.stream) { if (event.chunk) { const chunk = event.chunk; if (chunk.contentStart) { console.log("Command execution started"); } if (chunk.contentDelta) { if (chunk.contentDelta.stdout) process.stdout.write(chunk.contentDelta.stdout); if (chunk.contentDelta.stderr) process.stderr.write(chunk.contentDelta.stderr); } if (chunk.contentStop) { console.log(`\nExit code: ${chunk.contentStop.exitCode}, ` + `Status: ${chunk.contentStop.status}`); } } } client.destroy();

Contoh alur kerja agen pengkodean

Pola umum adalah menggunakan InvokeAgentRuntime untuk penalaran dan InvokeAgentRuntimeCommand untuk operasi deterministik dalam sesi yang sama.

Contoh End-to-end alur kerja agen 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. SEBUAH npm test yang membutuhkan waktu dua menit menghasilkan streaming 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 yang ditulis agen di /workspace/fix.py segera terlihat oleh perintah yang berjalan cat /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 Praktik terbaik keamanan untuk AgentCore Waktu pelaksanaan.

penting

Di bawah AWS model tanggung jawab bersama, Anda bertanggung jawab atas keamanan 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 eksekusi perintah adalah microVM. Masing-masing AgentCore Sesi 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 Amazon agen Anda CloudWatch Grup log log. 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 rekor InvokeAgentRuntimeCommand 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 dieksekusi.

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 CloudWatch Mencatat filter metrik 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 mencakup bedrock-agentcore:InvokeAgentRuntimeCommand izin.

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 InvokeAgentRuntimeCommand operasi menargetkan sesi yang disediakan atau dihancurkan oleh layanan. Pesannya adalah Session operation in progress, please retry. Kondisi ini bersifat sementara dan dapat dicoba kembali. Coba lagi dengan mundur eksponensial pendek alih-alih memperlakukannya sebagai terminal. Yang AWS SDK 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 di contentStop peristiwa untuk menentukan apakah perintah itu sendiri berhasil. SEBUAH status dari TIMED_OUT menunjukkan perintah melebihi batas waktu yang ditentukan.

Praktik Terbaik

Ikuti praktik terbaik ini saat menggunakan InvokeAgentRuntimeCommand operasi:

  • Gunakan InvokeAgentRuntimeCommand untuk operasi deterministik (tes, git, build) dan InvokeAgentRuntime untuk tugas penalaran. Jangan merutekan operasi deterministik melalui LLM.

  • Sertakan alat pengembang apa pun yang bergantung pada perintah Anda (seperti git , npm , atau runtime bahasa) di image wadah Anda melalui Dockerfile Anda.

  • Selalu periksa exitCode di contentStop peristiwa untuk menentukan apakah perintah berhasil.

  • Tetapkan batas waktu yang sesuai. Sebuah rangkaian pengujian mungkin membutuhkan 5 menit, sementara git push Mungkin hanya perlu 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 ).