사전 조건 1단계: AgentCore CLI 설치 2단계: 에이전트 프로젝트 생성 3단계: 로컬에서 에이전트 테스트 4단계: 에이전트에 대한 관찰성 활성화 5단계: Amazon Bedrock AgentCore 런타임에 배포 6단계: 배포된 에이전트 테스트 7단계: 배포된 에이전트 호출 8단계: 정리 리소스 찾기 일반적인 문제 및 해결 방법 고급 옵션(선택 사항)

AgentCore CLI 시작하기

이 자습서에서는 AgentCore CLI를 사용하여 Amazon Bedrock AgentCore 런타임에서 Python 에이전트를 생성, 배포 및 호출하는 방법을 보여줍니다.

AgentCore CLI는 에이전트 프로젝트를 스캐폴드하고, Amazon Bedrock AgentCore 런타임에 배포하고, 호출하는 명령줄 도구입니다. CLI를 Strands 에이전트, LangChain/LangGraph, Google ADK, OpenAI 에이전트와 같은 널리 사용되는 Python 에이전트 프레임워크와 함께 사용할 수 있습니다. 이 자습서에서는 Strands 에이전트를 사용합니다.

에이전트가 사용하는 HTTP 프로토콜에 대한 자세한 내용은 HTTP 프로토콜 계약을 참조하세요.

사전 조건

시작하기 전에 다음이 있는지 확인합니다.

AWS 자격 증명이 구성된 계정입니다. AWS 자격 증명을 구성하려면 AWS CLI의 구성 및 자격 증명 파일 설정을 참조하세요.
Node.js 20 이상이 설치되었습니다. AgentCore CLI는 npm 패키지로 배포됩니다.
Python 3.10 이상이 설치되었습니다. 생성된 에이전트 코드는 Python입니다.
AWS CDK가 설치되었습니다. CLI는 AWS CDK를 사용하여 리소스를 배포합니다. 자세한 내용은 AWS CDK 시작하기를 참조하세요.
AWS 권한: AgentCore CLI를 사용하여 에이전트를 생성하고 배포하려면 적절한 권한이 있어야 합니다. 자세한 내용은 AgentCore CLI 사용을 참조하세요.
모델 액세스: Amazon Bedrock 콘솔에서 Anthropic Claude Sonnet 4.0 활성화( Bedrock을 모델 공급자로 사용하는 경우). Strands Agents에서 다른 모델을 사용하는 방법에 대한 자세한 내용은 Strands Agents SDK 설명서의 모델 공급자 섹션을 참조하세요.

1단계: AgentCore CLI 설치

AgentCore CLI를 전역적으로 설치합니다.


npm install -g @aws/agentcore

설치를 확인합니다.


agentcore --help

다음과 유사한 출력 화면이 표시되어야 합니다.


Usage: agentcore [options] [command]

Build and deploy Agentic AI applications on AgentCore

Options:
  -V, --version                output the version number
  -h, --help                   Display help

Commands:
  add [subcommand]             Add resources (agent, evaluator, online-eval,
                               memory, identity, target)
  dev|d [options]              Launch local development server with hot-reload.
  deploy|p [options]           Deploy project infrastructure to AWS via CDK.
  create [options]             Create a new AgentCore project
  evals                        View past eval run results.
  fetch                        Fetch access info for deployed resources.
  help                         Display help topics
  invoke|i [options] [prompt]  Invoke a deployed agent endpoint.
  logs|l [options]             Stream or search agent runtime logs.
  package|pkg [options]        Package agent artifacts without deploying.
  pause                        Pause an online eval config.
  remove [subcommand]          Remove resources from project config.
  resume                       Resume a paused online eval config.
  run                          Run on-demand evaluation.
  status|s [options]           Show deployed resource details and status.
  traces|t                     View and download agent traces.
  update [options]             Check for and install CLI updates
  validate [options]           Validate agentcore/ config files.

2단계: 에이전트 프로젝트 생성

agentcore create 명령을 사용하여 새 에이전트 프로젝트를 스캐폴드합니다.

예

agentcore create 명령은 다음 플래그를 허용합니다.

--name - 프로젝트 이름(영숫자, 문자로 시작, 최대 36자).
--framework - 에이전트 프레임워크입니다. 지원되는 값: Strands , LangChain_LangGraph , GoogleADK , OpenAIAgents.
--protocol - 프로토콜 모드입니다. 지원되는 값: HTTP (기본값), MCP , A2A.
--build - 빌드 유형입니다. 지원되는 값: CodeZip (기본값), Container.
--model-provider - 모델 공급자입니다. 지원되는 값: Bedrock , Anthropic , OpenAI , Gemini.
--memory - 메모리 구성. 지원되는 값: none , shortTerm , longAndShortTerm.

명령은 다음 구조의 프로젝트 디렉터리를 생성합니다.


MyAgent/
  agentcore/
    agentcore.json        # Project and agent configuration
    aws-targets.json      # AWS account and region targets
    .env.local            # Local environment variables (gitignored)
  app/
    MyAgent/
      main.py             # Agent entrypoint
      pyproject.toml      # Python dependencies
  README.md

agentcore/agentcore.json 파일에는 프로젝트 및 에이전트 구성이 포함되어 있습니다. app/MyAgent/main.py 파일에는 선택한 프레임워크를 사용하는 스타터 에이전트 코드가 포함되어 있습니다.

프로젝트에 결제 기능을 추가하려면 다음을 실행합니다.


agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00
agentcore add payment-connector --manager MyPayments --name MyConnector --provider CoinbaseCDP \
  --api-key-id <KEY_ID> --api-key-secret <KEY_SECRET> --wallet-secret <WALLET_SECRET>

이렇게 하면 에이전트AgentCorePaymentsPlugin에서가 구성되고 배포 시 결제 인프라가 프로비저닝됩니다. 전체 워크플로는 결제 빠른 시작을 참조하세요.

3단계: 로컬에서 에이전트 테스트

에 배포하기 전에 개발 서버를 사용하여 로컬에서 에이전트를 AWS테스트합니다. 먼저 프로젝트 디렉터리로 변경합니다.


cd MyAgent

API 키(OpenAI, Anthropic 또는 Gemini)가 필요한 모델 공급자를 선택한 경우 키가에 구성되어 있는지 확인합니다agentcore/.env.local.

로컬 개발 서버를 시작합니다.

예

agentcore dev 명령:

웹 브라우저에서 에이전트 검사기를 엽니다.
Python 가상 환경을 자동으로 생성하고 종속성을 설치합니다.
AgentCore 런타임 환경을 모방하는 로컬 서버를 시작합니다.
http://localhost:8080 기본적으로에서 실행됩니다(포트를 변경하는 -p 데 사용).

서버 로그를 실시간으로 보려면(비대화형 모드) --logs 플래그를 사용합니다.


agentcore dev --logs

별도의 터미널에서 로컬 에이전트를 호출합니다.


agentcore dev "Hello, tell me a joke"

프롬프트를 전달하면 실행 중인 로컬 개발 서버로 전송됩니다. --stream를 사용하여 실시간으로 스트리밍된 응답을 확인합니다.

4단계: 에이전트에 대한 관찰성 활성화

Amazon Bedrock AgentCore 관찰성을 사용하면 Amazon Bedrock AgentCore 런타임에서 호스팅하는 에이전트를 추적, 디버깅 및 모니터링할 수 있습니다. 먼저 Amazon Bedrock AgentCore 런타임 관찰성 활성화의 지침에 따라 CloudWatch 트랜잭션 검색을 활성화합니다. 에이전트를 관찰하려면 Amazon Bedrock AgentCore 에이전트의 관찰성 데이터 보기를 참조하세요.

에이전트를 배포한 후 AgentCore CLI를 사용하여 로그를 스트리밍하고 추적을 볼 수 있습니다.


# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

5단계: Amazon Bedrock AgentCore 런타임에 배포

Amazon Bedrock AgentCore 런타임에 에이전트 배포:

예

변경하지 않고 배포를 미리 보려면 --dry-run 플래그를 사용합니다.


agentcore deploy --dry-run

agentcore deploy 명령:

agentcore/agentcore.json 및 agentcore/aws-targets.json 구성을 읽습니다.
에이전트 코드를 패키징합니다(빌드 유형에 따라 CodeZip 아카이브 또는 Docker 컨테이너로).
AWS CDK를 사용하여 CloudFormation 리소스를 합성하고 배포합니다.
필요한 AWS 리소스(IAM 역할, Amazon Bedrock AgentCore 런타임 등)를 생성합니다.

리소스 수준 배포 이벤트를 보여주는 상세 정보 출력-v에를 사용합니다. -y를 사용하여 프롬프트 없이 배포를 자동 확인합니다.

배포에 실패하면 일반적인 문제가 있는지 확인합니다.

6단계: 배포된 에이전트 테스트

배포가 완료되면 배포된 에이전트를 호출합니다.

예

응답에joke가 표시되면 에이전트가 Amazon Bedrock AgentCore 런타임에서 실행 중이며 호출할 수 있습니다. 그렇지 않은 경우 일반적인 문제가 있는지 확인합니다.

7단계: 배포된 에이전트 호출

예

AgentCore CLI

프롬프트를 사용하여 배포된 에이전트를 호출합니다.
```
agentcore invoke --runtime MyAgent "Hello, what can you do?"
```
응답을 실시간으로 스트리밍합니다.
```
agentcore invoke --runtime MyAgent "Tell me a joke" --stream
```
프롬프트 agentcore invoke 없이를 실행하여 기본적으로 응답을 스트리밍하고 세션을 자동으로 유지 관리하는 대화형 채팅 TUI를 엽니다.

AWS Python SDK (Boto3)

AWS SDK InvokeAgentRuntime 작업을 사용하여 에이전트를 호출할 수도 있습니다. 배포된 에이전트의 ARN을 가져오려면 agentcore status 명령을 사용합니다.
```
agentcore status
```
다음 boto3(Python용AWS SDK) 코드를 사용하여 에이전트를 호출합니다. 에이전트 ARN을 에이전트의 ARN으로 바꿉니다. bedrock-agentcore:InvokeAgentRuntime 권한이 있는지 확인합니다. 라는 파일을 생성하고 다음 코드를 invoke_agent.py 추가합니다.
```
import json
import uuid
import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode('utf-8'))
print(json.loads(''.join(content)))
```
터미널 창을 열고 다음 명령을 사용하여 코드를 실행합니다.
```
python invoke_agent.py
```
성공하면 응답에 장난이 표시됩니다. 호출이 실패하면를 사용하여 로그를 확인하거나 Amazon CloudWatch에서 로그를 agentcore logs 확인합니다.

참고
에이전트를 OAuth와 통합하려는 경우 AWS SDK를 사용하여 InvokeAgentRuntime를 호출할 수 없습니다. 대신 InvokeAgentRuntime에 HTTPS를 요청합니다. 자세한 내용은 Authenticate and authorize with Inbound Auth and Outbound Auth를 참조하세요.

8단계: 정리

Amazon Bedrock AgentCore 런타임에서 에이전트를 호스팅하지 않으려면 배포된 AWS 리소스를 제거합니다. 먼저 로컬 구성에서 모든 리소스를 제거합니다.

예

그런 다음를 다시 배포하여 AWS 리소스를 삭제합니다.

예

remove all 명령은 agentcore/aws-targets.json 및 배포 상태를 유지하면서 agentcore/agentcore.json 구성 파일을 재설정합니다. 후속는 제거된 리소스를 deploy 감지하고 해당 AWS 리소스를 제거합니다.

리소스 찾기

배포 후 AgentCore CLI를 사용하여 리소스의 상태를 확인할 수 있습니다.

예

AWS 콘솔에서 리소스를 볼 수도 있습니다.

Resource	Location
에이전트 로그	CloudWatch → 로그 그룹 → `/aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT`
CloudFormation 스택	CloudFormation → Stacks → 프로젝트 이름 검색
[IAM Role]	IAM → 역할 → "BedrockAgentCore" 검색
S3 자산(CodeZip)	S3 → 버킷 → CDK 스테이징 버킷

일반적인 문제 및 해결 방법

AgentCore CLI를 시작할 때 발생하는 일반적인 문제 및 해결 방법. 자세한 문제 해결 정보는 Amazon Bedrock AgentCore 런타임 문제 해결을 참조하세요.

권한 거부 오류

자격 AWS 증명 및 권한을 확인합니다.

자격 AWS 증명 확인: aws sts get-caller-identity
필수 정책이 연결되어 있는지 확인합니다.
자세한 요구 사항은 호출자 권한 정책 검토

모델 액세스 거부됨

Bedrock 콘솔에서 모델 액세스를 활성화합니다.

Bedrock 콘솔에서 Anthropic Claude 4.0 활성화
올바른 AWS 리전에 있는지 확인합니다(기본적으로 us-west-2).

CDK 배포 오류

CDK 설정 및 권한을 확인합니다.

CDK AWS 계정을 부트스트래핑했는지 확인합니다. cdk bootstrap
호출자 권한에 CloudFormation 및 CDK 액세스가 포함되어 있는지 확인
상세 정보 출력agentcore deploy -v에를 사용하여 실패한 리소스를 식별합니다.

사용 중인 포트 8080(로컬만 해당)

포트 8080을 사용하는 프로세스를 찾아 중지합니다.

포트 8080을 사용하여 프로세스 목록을 가져오는 lsof -ti:8080 데 사용합니다.

kill -9 PID를 사용하여 프로세스를 중지합니다. PID를 프로세스 ID로 바꿉니다.

또는 다른 포트에서 개발 서버를 시작합니다. agentcore dev -p 3000

리전 불일치

를 사용하여 AWS 리전을 aws configure get region 확인하고의 리전이 리소스를 배포해야 하는 리전과 agentcore/aws-targets.json 일치하는지 확인합니다.

구성 검증 오류

구성 파일을 검증합니다.

agentcore validate를 사용하여 agentcore/agentcore.json 및 관련 구성 파일의 구문 또는 스키마 오류를 확인합니다.

고급 옵션(선택 사항)

를 사용하여 에이전트 프로젝트를 생성한 후 agentcore add 명령을 사용하여 확장agentcore create할 수 있습니다. 전체 CLI 참조는 AgentCore CLI 설명서를 참조하세요.

빌드 유형

프로젝트를 생성할 때 필요에 맞는 빌드 유형을 선택합니다.

CodeZip(기본값)

에이전트 코드는 zip 아카이브로 패키징되어 S3에 업로드됩니다. 이는 가장 간단한 옵션이며 Docker가 필요하지 않습니다.


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build CodeZip

컨테이너

에이전트 코드는 Docker 컨테이너 이미지로 패키징됩니다. 사용자 지정 시스템 수준 종속성 또는 특정 기본 이미지가 필요한 경우이 옵션을 사용합니다.


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build Container

프로젝트에 리소스 추가

생성 후 프로젝트에 리소스를 추가할 수 있습니다.


# Add another agent to the same project
agentcore add agent --name SecondAgent --language Python --framework Strands --model-provider Bedrock

# Add a memory store for conversational context
agentcore add memory --name MyMemory --strategies SEMANTIC

# Add an API key credential for external services
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

# Add a payment manager for x402 microtransactions
agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00

리소스를 추가한 후를 실행agentcore deploy하여에서 새 리소스를 프로비저닝합니다 AWS.

왜 ARM64인가?

Amazon Bedrock AgentCore 런타임은 ARM64(AWS Graviton)에서 실행됩니다. AgentCore CLI는 CodeZip 및 컨테이너 빌드 유형 모두에서 아키텍처 호환성을 자동으로 처리합니다. 컨테이너 빌드의 경우 Amazon Bedrock AgentCore 런타임에 배포할 때 ARM64용으로 빌드된 이미지만 작동합니다.

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

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

문서 규칙

AgentCore 런타임 시작하기

AgentCore CLI(TypeScript) 시작하기