View a markdown version of this page

Jalankan perintah shell dalam sesi AgentCore 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 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

contentStart

Potongan pertama

Mengonfirmasi perintah dimulai

contentDelta

Selama eksekusi

stdout and/or stderrkeluaran

contentStop

Potongan terakhir

exitCodedan status (COMPLETEDatauTIMED_OUT)

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
Python
  1. Contoh berikut menunjukkan cara menggunakan boto3 untuk menjalankan perintah dalam sesi AgentCore 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 dalam sesi AgentCore 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 sesi AgentCore 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 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 test yang 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.py terlihat 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:InvokeAgentRuntimeCommand izin 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 InvokeAgentRuntimeCommand operasi 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 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 (sepertigit,npm, atau runtime bahasa) dalam image kontainer Anda melalui Dockerfile Anda.

  • Selalu exitCode periksa dalam contentStop acara untuk menentukan apakah perintah berhasil.

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