작동 방식 사전 조건 명령 실행 코딩 에이전트 워크플로 예제 일반 사용 사례 주요 설계 선택 사항 보안 고려 사항 오류 처리 모범 사례

AgentCore 런타임 세션에서 셸 명령 실행

InvokeAgentRuntimeCommand 작업을 사용하면 실행 중인 AgentCore 런타임 세션 내에서 직접 셸 명령을 실행하고 HTTP/2를 통해 출력을 다시 스트리밍할 수 있습니다. 명령은 에이전트와 동일한 컨테이너, 파일 시스템 및 환경에서 실행되며에서 사용하는 것과 동일한 세션InvokeAgentRuntime입니다. 이를 통해 애플리케이션이 에이전트를 사용하여 테스트 실행, git 작업 또는 환경 설정과 같은 결정론적 작업을 위한 작업 및 명령을 추론할 수 있습니다.

InvokeAgentRuntimeCommand를 호출하려면 bedrock-agentcore:InvokeAgentRuntimeCommand 권한이 필요합니다.

작동 방식

InvokeAgentRuntimeCommand는 활성 AgentCore 런타임 세션의 컨테이너 내에서 셸 명령을 실행하고 출력을 다시 스트리밍합니다.

동일한 에이전트, 동일한 세션

InvokeAgentRuntimeCommand는 InvokeAgentRuntime와 동일한 에이전트 런타임 및 세션에서 작동합니다. 별도의 리소스는 생성하지 않습니다. 를 사용하여 배포한 에이전트는 모든 활성 세션에서 에이전트 호출과 명령 실행을 모두 CreateAgentRuntime 수락합니다.

참고

AgentCore 런타임 microVM에는 기본적으로 git , npm 또는 언어 런타임과 같은 개발자 도구가 포함되어 있지 않습니다. 명령이 의존하는 모든 도구는 컨테이너 이미지에 포함되거나(Dockerfile을 통해) 런타임에 동적으로 설치되어야 합니다.

응답은 다음 세 가지 이벤트 유형의 스트림입니다.

Event	일시	포함
`contentStart`	첫 번째 청크	명령이 시작되었는지 확인합니다.
`contentDelta`	실행 중	`stdout` 및/또는 `stderr` 출력
`contentStop`	마지막 청크	`exitCode` 및 `status` ( `COMPLETED` 또는 `TIMED_OUT` )

스트림을 실시간으로 출력합니다. 완료 후가 아니라 실행 시 결과가 표시됩니다.

사전 조건

bedrock-agentcore:InvokeAgentRuntimeCommand IAM 권한
유효한 AgentCore 런타임 엔드포인트 ARN

참고

2026년 3월 17일 이후에 생성된 에이전트는 명령 실행을 자동으로 지원합니다. 이 날짜 이전에 에이전트를 배포한 경우 에이전트 런타임을 업데이트하려면 에이전트를 다시 배포해야 합니다.

명령 실행

예

Python

다음 예제에서는 boto3를 사용하여 AgentCore 런타임 세션에서 명령을 실행하는 방법을 보여줍니다.


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

다음 예제에서는 Java용 AWS SDK를 사용하여 AgentCore 런타임 세션에서 명령을 실행하는 방법을 보여줍니다.


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

다음 예제에서는 AWS SDK for JavaScript v3를 사용하여 AgentCore 런타임 세션에서 명령을 실행하는 방법을 보여줍니다.


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();

코딩 에이전트 워크플로 예제

일반적인 패턴은 동일한 세션에서 InvokeAgentRuntime 추론 및 결정론적 작업에 InvokeAgentRuntimeCommand를 사용하는 것입니다.

End-to-end 코딩 에이전트 워크플로 예제


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"')

에이전트가 코드를 작성합니다. 플랫폼은 명령을 실행합니다. 각는 최선을 다합니다.

일반 사용 사례

테스트 제품군 실행

에이전트가 코드를 작성한 후 프로젝트의 테스트 제품군을 명령으로 실행합니다. 스트리밍 응답을 사용하면 장애를 조기에 감지하고 특정 오류 출력을 반복을 위해 에이전트에 다시 공급할 수 있습니다.


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

Git 작업

분기, 커밋 및 푸시는 결정론적 작업입니다. 에이전트가 작업을 완료한 후 명령으로 실행하여 버전 제어 로직을 LLM에서 제외합니다.


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

종속성 설치

에이전트를 호출하기 전에 환경을 부트스트랩합니다. 리포지토리 복제, 패키지 설치, 빌드 도구 설정. 이 준비는 직접 명령으로 더 빠르고 안정적으로 실행됩니다.


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

빌드 및 컴파일

단계 및 자산 생성 컴파일 - 지정된 대로 정확히 실행되어야 하는 알려진 명령으로 모든 것을 컴파일합니다.


/bin/bash -c "cd /workspace && cargo build --release"

린팅 및 검증

에이전트가 코드를 작성한 후 커밋하기 전에 코드 품질 검사를 검증 게이트로 실행합니다.


/bin/bash -c "cd /workspace && npx eslint src/ --format json"

환경 검사

에이전트 장애 디버깅에 유용한 런타임 상태, 설치된 패키지, 사용 가능한 도구를 확인합니다.


/bin/bash -c "python --version && node --version && git --version"

데이터 작업

데이터 세트를 가져오고, 결과를 업로드하고, 데이터 변환을 실행합니다. 직접 명령으로 더 빠르게 실행되는 네트워크 및 컴퓨팅 작업입니다.


/bin/bash -c "aws s3 cp s3://my-bucket/data.csv /workspace/"

주요 설계 선택 사항

원샷, 비대화형 실행: 각 명령은 새 bash 프로세스를 생성하고 완료(또는 제한 시간)까지 실행한 다음를 반환합니다. 명령 간에는 영구 셸 세션이 없습니다. 이는 에이전트 프레임워크가 명령 실행 - 명령 생성, 실행, 출력 읽기를 사용하고 다음에 수행할 작업을 결정하는 방법과 일치합니다.
HTTP/2를 통한 스트리밍 응답: 출력은 생성될 때 도착하며 완료될 때까지 버퍼링되지 않습니다. 2분이 걸리는 npm test는 결과를 실시간으로 스트리밍합니다. 애플리케이션은 처음 몇 초 동안 장애를 감지하고 전체 실행을 기다리지 않고 조기에 취소할 수 있습니다.
컨테이너 격리: 명령은 에이전트 코드와 동일한 컨테이너 내에서 실행됩니다. 동일한 파일 시스템, 환경 변수 및 설치된 패키지를 볼 수 있습니다. 에이전트/workspace/fix.py가에 작성한 파일은를 실행하는 명령에 즉시 표시됩니다cat /workspace/fix.py.
런타임에 대한 비차단: 명령 실행은 에이전트 호출을 차단하지 않습니다. 에이전트를 호출하고 동일한 세션에서 동시에 명령을 실행할 수 있습니다. 플랫폼은 동시성을 처리합니다.
명령 간 상태 비저장: 각 명령은 새로 시작됩니다. 쉘 기록 없음, 이전 명령의 환경 변수 변경 사항은 이월되지 않습니다. 상태가 필요한 경우 명령 자체에서 인코딩합니다cd /workspace && export NODE_ENV=test && npm test.

보안 고려 사항

작은 정보

모든 런타임 보안 권장 사항에 대한 통합 보기는 AgentCore 런타임의 보안 모범 사례를 참조하세요.

중요

AWS 공동 책임 모델에서는 AgentCore 런타임 세션에서 실행하는 명령의 보안을 담당합니다.는 microVM 수준에서 보안 인프라와 격리를 AWS 제공합니다. 실행하는 명령, 처리하는 데이터 및 구성하는 액세스 제어에 대한 책임은 사용자에게 있습니다.

명령 실행의 보안 경계는 microVM입니다. 각 AgentCore 런타임 세션은 자체 커널, 메모리 및 파일 시스템이 있는 격리된 microVM에서 실행됩니다. 실행하는 명령은 다른 고객의 워크로드에 액세스하거나 VM 경계를 이스케이프할 수 없습니다. 그러나 VM 내에서 명령은 컨테이너 파일 시스템과 구성한 자격 증명 또는 보안 암호에 대한 전체 액세스 권한을 가집니다.

CloudWatch Logs를 사용한 감사

AgentCore 런타임은 요청 ID와 입력 명령을 에이전트의 Amazon CloudWatch Logs 로그 그룹에 전송합니다. 이러한 로그를 사용하여 명령 활동을 모니터링하고 세션에서 실행된 명령에 대한 감사 추적을 유지할 수 있습니다. 명령 실행 출력(stdout 및 stderr)은 애플리케이션으로 다시 스트리밍되며 서비스에 의해 로깅되지 않습니다.

CloudTrail을 사용한 감사

AWS CloudTrail은 계정에 InvokeAgentRuntimeCommand API 호출을 기록합니다. 각 레코드에는 발신자 자격 증명, 타임스탬프, 소스 IP 주소 및 응답 상태와 같은 메타데이터가 포함됩니다. CloudTrail은 요청 또는 응답 페이로드를 로깅하지 않습니다. CloudTrail을 사용하여 누가 언제 명령을 실행했는지 감사한 다음 요청 ID를 사용하여 CloudWatch Logs 로그와 상호 연관시켜 어떤 명령이 실행되었는지 확인합니다.

민감한 워크로드의 경우 다음과 같은 추가 제어를 구현하는 것이 좋습니다.

IAM 정책을 사용하여 호출할 수 있는 보안 주체 제한 InvokeAgentRuntimeCommand
네트워크 내에서 트래픽을 유지하도록 VPC 엔드포인트 구성
예상치 못한 명령 패턴을 감지하기 위한 CloudWatch Logs 지표 필터 및 경보 설정
CloudTrail 로그에 무단 액세스 시도가 있는지 정기적으로 검토

오류 처리

InvokeAgentRuntimeCommand 작업을 사용할 때 다음과 같은 오류가 발생할 수 있습니다.

ValidationException: 요청 파라미터가 유효하지 않을 때 발생합니다. 에이전트 ARN, 세션 ID 및 명령의 형식이 올바른지 확인합니다. 명령은 1바이트에서 64KB 사이여야 하고, 제한 시간은 1초에서 3,600초 사이여야 하며, 세션 ID는 33자 이상이어야 합니다.
ResourceNotFoundException: 지정된 에이전트 런타임 또는 세션을 찾을 수 없을 때 발생합니다. 에이전트 ARN이 올바르고 세션이 활성 상태인지 확인합니다.
AccessDeniedException: 필요한 권한이 없을 때 발생합니다. IAM 정책에 bedrock-agentcore:InvokeAgentRuntimeCommand 권한이 포함되어 있는지 확인합니다.
ThrottlingException: 요청 속도 제한인 25TPS를 초과할 때 발생합니다. 애플리케이션에서 지수 백오프 및 재시도 로직을 구현합니다.

0이 아닌 종료 코드로 완료되는 명령은 API 오류가 아닙니다. contentStop 이벤트exitCode의를 확인하여 명령 자체가 성공했는지 확인합니다. status의는 명령이 지정된 제한 시간을 초과했음을 TIMED_OUT 나타냅니다.

모범 사례

InvokeAgentRuntimeCommand 작업을 사용할 때는 다음 모범 사례를 따르세요.

InvokeAgentRuntimeCommand 결정적 작업(테스트, git, 빌드) 및 추론 작업에 InvokeAgentRuntime를 사용합니다. LLM을 통해 결정적 작업을 라우팅하지 마세요.
Dockerfile을 통해 컨테이너 이미지에 명령이 의존하는 개발자 도구(예: git npm, 또는 언어 런타임)를 포함합니다.
항상 contentStop 이벤트exitCode의를 확인하여 명령이 성공했는지 확인합니다.
적절한 제한 시간을 설정합니다. 테스트 제품군에는 5분이 필요할 수 있지만 에는 30초만 필요할 git push 수 있습니다.
스트리밍 출력을 점진적으로 처리하여 장애를 조기에 감지합니다. 장기 실행 명령이 완료될 때까지 기다리지 않고 취소할 수 있습니다.
각 명령은 새 bash 프로세스를 시작하기 때문에 && 체인(예: cd /workspace && export NODE_ENV=test && npm test )을 사용하여 명령 자체의 상태를 인코딩합니다.
세션 IDs UUIDs를 사용하여 33자 최소 요구 사항(예: 12345678-1234-1234-1234-123456789012 )을 충족합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

쉘 실행

대화형 쉘(터미널)