Cara kerjanya Prasyarat Jalankan perintah Contoh alur kerja agen pengkodean Kasus penggunaan umum Pilihan desain utama Pertimbangan keamanan Penanganan kesalahan Praktik terbaik

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 yang digunakan oleh. InvokeAgentRuntime Ini memungkinkan alur kerja di mana aplikasi Anda menggunakan agen untuk menalar tugas dan perintah untuk operasi deterministik seperti menjalankan pengujian, operasi git, atau pengaturan lingkungan.

Untuk meneleponInvokeAgentRuntimeCommand, 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 dengan. InvokeAgentRuntime Anda tidak membuat sumber daya terpisah. Agen yang Anda gunakan CreateAgentRuntime menerima pemanggilan agen dan eksekusi perintah pada sesi aktif apa pun.

catatan

MicroVM AgentCore Runtime tidak menyertakan alat pengembang sepertigit,npm, atau runtime bahasa secara default. Alat apa pun yang bergantung pada perintah Anda harus disertakan dalam gambar kontainer Anda (melalui Dockerfile Anda) atau diinstal secara dinamis saat runtime.

Responsnya adalah aliran dari tiga jenis acara:

Peristiwa	Saat	Contains
`contentStart`	Potongan pertama	Mengonfirmasi perintah dimulai
`contentDelta`	Selama eksekusi	`stdout` and/or `stderr`keluaran
`contentStop`	Potongan terakhir	`exitCode`dan `status` (`COMPLETED`atau`TIMED_OUT`)

Output stream secara real time. Anda melihat hasil saat mereka berjalan, 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 menggunakan agen Anda sebelum tanggal ini, Anda harus menerapkannya kembali untuk memperbarui runtime agen.

Jalankan perintah

contoh

Python

Contoh berikut menunjukkan bagaimana 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

Contoh berikut menunjukkan cara menggunakan AWS SDK for Java untuk menjalankan perintah dalam 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

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 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 kodenya. Platform menjalankan perintah. Masing-masing melakukan apa yang terbaik.

Kasus penggunaan umum

Menjalankan test suite

Setelah agen menulis kode, jalankan rangkaian pengujian proyek sebagai perintah. Respons streaming memungkinkan Anda mendeteksi kegagalan lebih awal dan memasukkan output kesalahan tertentu kembali ke agen untuk iterasi.


/bin/bash -c "cd /workspace && npm test 2>&1"

Operasi Git

Percabangan, komitmen, dan dorongan adalah operasi deterministik. Jalankan sebagai perintah setelah agen menyelesaikan pekerjaannya, menjauhkan logika kontrol versi dari LLM.


/bin/bash -c "cd /workspace && git add -A && git commit -m 'Fix issue'"

Instalasi ketergantungan

Bootstrap lingkungan sebelum menjalankan repo agent -clone, instal paket, atur perkakas build. Persiapan ini berjalan lebih cepat dan lebih andal sebagai perintah langsung.


/bin/bash -c "pip install -r requirements.txt"

Membangun dan mengkompilasi

Kompilasi langkah-langkah dan pembuatan aset -anything 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 penyelesaian (atau batas waktu), dan kembali. Tidak ada sesi shell persisten di antara perintah. Ini cocok dengan bagaimana kerangka kerja agen menggunakan eksekusi perintah -craft perintah, menjalankannya, membaca output, memutuskan apa yang harus dilakukan selanjutnya.
Respons streaming berakhir HTTP/2: Output tiba saat diproduksi, bukan buffer sampai selesai. A npm test yang membutuhkan waktu dua menit streaming menghasilkan waktu nyata. Aplikasi Anda dapat mendeteksi kegagalan dalam beberapa detik pertama dan membatalkan lebih awal daripada menunggu proses penuh.
Isolasi kontainer: Perintah dijalankan 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 langsung terlihat oleh perintah yang berjalancat /workspace/fix.py. /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 di antara perintah: Setiap perintah memulai riwayat shell -no baru, tidak ada perubahan variabel lingkungan dari perintah sebelumnya yang dibawa. Jika Anda membutuhkan status, encode 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 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 dalam 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 kredensyal 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 mempertahankan jejak audit dari perintah apa yang dijalankan dalam sesi Anda. Output eksekusi perintah (stdout dan stderr) dialirkan kembali ke aplikasi Anda dan tidak dicatat oleh layanan.

Audit dengan CloudTrail

AWS CloudTrail merekam panggilan InvokeAgentRuntimeCommand 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 perintah yang dijalankan dan kapan, kemudian berkorelasi dengan CloudWatch log Log menggunakan ID permintaan untuk melihat perintah apa yang dijalankan.

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

Menggunakan kebijakan IAM untuk membatasi prinsipal mana yang dapat memanggil InvokeAgentRuntimeCommand
Mengkonfigurasi titik akhir VPC untuk menjaga lalu lintas dalam jaringan Anda
Menyiapkan filter metrik CloudWatch Log 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 yang ditentukan tidak dapat ditemukan. Verifikasi bahwa agen ARN benar dan sesi aktif.
AccessDeniedException: Terjadi ketika Anda tidak memiliki izin yang diperlukan. Pastikan bahwa kebijakan IAM Anda mencakup bedrock-agentcore:InvokeAgentRuntimeCommand izin.
ThrottlingException: Terjadi ketika Anda melebihi batas tingkat permintaan 25 TPS. Terapkan backoff eksponensial dan coba lagi logika dalam aplikasi Anda.

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 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 gambar kontainer Anda melalui Dockerfile Anda.
Selalu periksa exitCode dalam contentStop acara untuk menentukan apakah perintah berhasil.
Tetapkan batas waktu yang sesuai. Sebuah test suite mungkin membutuhkan waktu 5 menit, sementara git push mungkin hanya membutuhkan 30 detik.
Proses streaming output secara bertahap untuk mendeteksi kegagalan lebih awal. Anda dapat membatalkan perintah yang berjalan lama daripada menunggu sampai selesai.
Encode state dalam perintah itu sendiri menggunakan && chaining (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

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

Eksekusi Shell

Kerang Interaktif (Terminal)