대화형 쉘(터미널)

InvokeAgentRuntimeCommandShell 작업은 WebSocket을 통해 실행 중인 AgentCore 런타임 세션 내에서 지속적인 대화형 터미널 세션을 엽니다. 원샷 명령 실행과 달리 쉘 세션은 환경 변수, 작업 디렉터리 및 명령 기록이 입력 간에 전달되는 상태를 유지합니다. 이를 통해 애플리케이션에서 디버깅, 환경 검사 및 터미널 경험 구축이 가능합니다.

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

작동 방식

InvokeAgentRuntimeCommandShell는 에이전트의 세션 내에서 실행되는 대화형 셸 프로세스에 대한 WebSocket 연결을 설정합니다. 연결은 바이너리 프레임을 사용하여 터미널 입력 및 출력을 양방향으로 스트리밍합니다.

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

InvokeAgentRuntimeCommandShell는 InvokeAgentRuntime 및와 동일한 에이전트 런타임에서 작동합니다InvokeAgentRuntimeCommand. 별도의 리소스는 생성하지 않습니다. 로 배포한 에이전트는 모든 활성 세션에서 쉘 연결을 CreateAgentRuntime 허용합니다.

연결은 다음을 지원합니다.

사전 조건

AgentCore CLI 사용

설치 및 설정 지침은 CLI를 사용하여 AgentCore 런타임 시작하기를 참조하세요.

CLI는를 통해 내장 터미널 환경을 제공합니다agentcore exec.

agentcore exec --it

특정 런타임에 연결하려면:

agentcore exec --it --runtime <runtime-arn> --region us-west-2

쉘을 닫지 않고 쉘에서 분리Ctrl+]하려면를 누릅니다. CLI는 재연결 명령을 인쇄합니다.

agentcore exec --it \
  --runtime <arn> \
  --region <region> \
  --session-id <uuid> \
  --shell-id <id>

원샷 명령의 경우를 생략합니다--it.

agentcore exec "ls -la /tmp"

시스템 읽기 가능 출력의 경우 JSON 모드를 사용합니다.

agentcore exec --json "echo hello"
# Output: {"success":true,"exitCode":0,"stdout":"hello\n","stderr":""}

추가 CLI 예제는 GitHub의 AgentCore 샘플을 참조하세요.

AgentCore SDK 사용

Python SDK를 설치합니다.

pip install bedrock-agentcore

재연결

일반적인 패턴은를 사용하여 연결 해제 후 쉘에 shellId 다시 연결하여 모든 세션 상태를 유지하는 것입니다.

import asyncio

from bedrock_agentcore.runtime import AgentCoreRuntimeClient

async def main():
    client = AgentCoreRuntimeClient(region="us-west-2")
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    session_id = "my-session-0000000000000000000000"
    shell_id = "my-shell"

    shell = await client.open_shell(
        runtime_arn,
        session_id=session_id,
        shell_id=shell_id,
    ).__aenter__()
    print(f"connected (reconnected={shell.reconnected})")
    await shell.send("export GREETING='hello'\n")
    await asyncio.sleep(1)

    async with client.open_shell(
        runtime_arn,
        session_id=session_id,
        shell_id=shell_id,
    ) as shell2:
        print(f"reconnected (reconnected={shell2.reconnected})")
        assert shell2.reconnected


if __name__ == "__main__":
    asyncio.run(main())

자동 재연결

또한 WebSocket 연결이 끊어지면 SDK가 자동으로 다시 연결할 수 있습니다. ReconnectConfig를 사용하여 다음을 활성화합니다.

import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel

async def on_reconnect(reconnected: bool):
    print(f"Reconnected: {reconnected}")

async def main():
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    shell_id = "my-persistent-shell"
    config = ReconnectConfig(max_retries=5, base_delay=0.5, on_reconnect=on_reconnect)

    client = AgentCoreRuntimeClient(region="us-west-2")
    async with client.open_shell(runtime_arn, shell_id=shell_id, reconnect_config=config) as shell:
        # If the connection drops, the SDK retries automatically
        await shell.send("long-running-command\n")
        async for frame in shell:
            if frame.channel == ShellChannel.STDOUT:
                print(frame.text, end="")

asyncio.run(main())

추가 SDK 예제는 GitHub의 AgentCore 샘플을 참조하세요.

일반 사용 사례

주요 설계 선택 사항

보안 고려 사항

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

CloudWatch Logs를 사용한 감사

AgentCore 런타임은 요청 ID와 연결 메타데이터를 에이전트의 Amazon CloudWatch Logs 로그 그룹에 전송합니다. 이러한 로그를 사용하여 쉘 연결 활동을 모니터링하고 감사 추적을 유지할 수 있습니다. 터미널 I/O 콘텐츠(stdin/stdout)는 클라이언트로 스트리밍되며 서비스에 의해 로깅되지 않습니다.

CloudTrail을 사용한 감사

AWS CloudTrail은 계정에 InvokeAgentRuntimeCommandShell API 호출을 기록합니다. 각 레코드에는 발신자 자격 증명, 타임스탬프, 소스 IP 주소 및 응답 상태와 같은 메타데이터가 포함됩니다. CloudTrail은 요청 또는 응답 페이로드를 로깅하지 않습니다. CloudTrail을 사용하여 쉘 세션을 연 사람과 시기를 감사한 다음 연결 세부 정보에 대한 요청 ID를 사용하여 CloudWatch Logs와 상호 연관시킵니다.

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

오류 처리

쉘 세션 연결을 설정할 때 WebSocket 업그레이드 중에 다음과 같은 오류가 발생할 수 있습니다.

연결되면 다음 종료 코드는 연결이 종료된 이유를 나타냅니다.

모범 사례

사용 시 InvokeAgentRuntimeCommandShell다음 모범 사례를 따르세요.

할당량 및 제한

전체 서비스 제한은 Amazon Bedrock AgentCore 할당량을 참조하세요.