AWS 기술 블로그
AgentCore CLI로 AI 에이전트 개발부터 배포까지 – Kiro CLI, Claude Code와 함께 쓰는 워크 플로우
Strands Agents나 LangGraph로 에이전트 프로토타입은 이제 몇 시간에도 구현이 가능합니다. 문제는 그다음입니다. 로컬에서 잘 돌던 코드를 Amazon Bedrock AgentCore Runtime에 올리려면 챙길 것이 많습니다. IAM 역할, 패키징, 배포 파이프라인, 로그와 트레이스 수집까지 이어집니다. 이 과정에서 개발 흐름이 자주 끊깁니다. 실제로 에이전트를 만들어 본 분들이 공통적으로 던지는 질문이 있습니다. 코드를 고칠 때마다 로컬에서 바로 확인할 방법은 없을까요? 개발부터 배포, 운영까지 터미널 하나로 이어지는 워크 플로우는 어떻게 만들까요? 개발의 상당 부분을 맡기고 있는 Kiro CLI나 Claude Code 같은 AI 코딩 에이전트와는 어떻게 결합해야 할까요?
AWS는 2026년 4월 이 간극을 메우는 AgentCore CLI를 공개했고, 2026년 10월 28일 정식 버전 1.0을 출시했습니다. 이 명령줄 도구는 npm 패키지로 설치합니다. 프로젝트 생성부터 로컬 개발, 배포, 호출, 운영까지 에이전트의 전체 수명 주기를 터미널 하나로 묶습니다. 이 글에서는 AgentCore CLI의 구조와 핵심 명령을 살펴봅니다. 이어서 실제 개발 워크 플로우에 녹여 쓰는 방법을 봅니다. 마지막으로 Kiro CLI와 Claude Code에 연결해 에이전트 개발 자체를 자동화하는 방법까지 다룹니다.
1. 정식 출시된 AgentCore CLI 1.0
기존에 AgentCore 배포 도구로 쓰이던 Bedrock AgentCore Starter Toolkit을 기억하는 분이 많을 것입니다. 이 Python 기반 도구는 레거시로 전환되었습니다. 신규 프로젝트에는 npm 기반의 AgentCore CLI가 권장됩니다. 두 도구는 agentcore라는 같은 명령 이름을 씁니다. Starter Toolkit이 설치된 환경이라면 혼선을 막기 위해 먼저 제거해야 합니다.
새 CLI의 첫 번째 특징은 2가지 실행 모드입니다. 인수 없이 agentcore만 입력하면 터미널 UI(TUI)가 열립니다. 화면 안내를 따라가면 프로젝트 생성부터 배포, 호출까지 이어집니다. 동시에 모든 명령은 플래그 기반의 비대화형(non-interactive) 모드를 지원합니다. --json 옵션을 붙이면 구조화된 JSON 출력을 반환합니다. 사람이 직접 쓸 때는 TUI가 편하고, 스크립트나 CI/CD, 뒤에서 소개할 AI 코딩 에이전트에게는 비대화형 모드가 맞습니다.
두 번째 특징은 배포 방식입니다. agentcore create는 프로젝트 안에 AWS CDK(Cloud Development Kit) 코드를 함께 생성합니다. agentcore deploy는 이 코드를 CloudFormation 스택으로 합성해 배포합니다. 에이전트 인프라는 처음부터 코드형 인프라(IaC)로 관리됩니다.
세 번째 특징은 1.0에서 재구축된 명령 체계입니다. 시작 속도가 빨라지고 명령 구조가 일관되게 정리되었습니다. 프로젝트 없이도 하네스, 런타임, 메모리, 게이트웨이 같은 리소스를 직접 다룹니다. ID나 ARN을 지정하면 기존 리소스를 바로 호출합니다. agentcore runtime shell로 배포된 에이전트 컨테이너에 대화형 셸을 열고, agentcore runtime exec로 명령 하나를 원격 실행하는 기능도 생겼습니다. AgentCore CLI는 AgentCore가 제공되는 AWS 리전에서 지원됩니다(중국 리전은 일부 기능 제약). CLI 자체에 대한 추가 요금은 없습니다.

그림 1. AgentCore CLI 수명 주기 — create, dev, deploy, invoke 4단계와 운영 명령이 로컬 컴퓨터와 AWS 클라우드로 이어지는 흐름
2. 설치와 사전 준비
AgentCore CLI 자체는 Node.js 20.12 이상에서 동작합니다. 생성되는 에이전트 코드가 Python이라면 Python 3.10 이상과 패키지 관리자 uv가 추가로 필요합니다. AWS 자격 증명은 AWS CLI 기준으로 구성해 둡니다. 배포는 AWS CDK로 진행되며, 첫 배포에서 CLI가 계정 부트스트랩까지 처리하므로 처음에만 몇 분이 더 걸립니다. Amazon Bedrock은 파운데이션 모델 액세스를 기본으로 제공하므로 별도 활성화 없이 시작합니다. 파운데이션 모델이 아닌 모델을 쓸 때만 모델 액세스 절차를 따릅니다.
설치는 npm 한 줄입니다. 이 글의 명령은 글을 고치는 시점의 최신 안정 버전인 1.1.0(2026년 11월 18일 게시) 기준으로 확인했습니다. 이미 설치했다면 agentcore update로 최신 버전으로 올립니다.
npm install -g @aws/agentcore
agentcore --version
Starter Toolkit이 남아 있다면 설치할 때 사용한 도구에 맞춰 제거합니다.
pip uninstall bedrock-agentcore-starter-toolkit # pip로 설치한 경우
pipx uninstall bedrock-agentcore-starter-toolkit # pipx로 설치한 경우
uv tool uninstall bedrock-agentcore-starter-toolkit # uv로 설치한 경우
0.x CLI로 만든 프로젝트를 옮겨올 때 처음부터 다시 만들 필요는 없습니다. 기존 프로젝트 디렉터리에서 agentcore migrate를 한 번 실행하면 버전 1 구조로 올라갑니다.
3. 프로젝트 구조 이해하기
agentcore create는 대화형 마법사와 플래그 방식을 모두 지원합니다. 주의할 점이 하나 있습니다. 플래그 방식에서 이름만 지정하면 빈 프로젝트가 만들어지고, 하네스는 이후 agentcore add harness로 추가합니다. 하네스(harness)는 에이전트 코드 없이 모델, 프롬프트, 도구, 메모리를 선언형 설정으로 묶는 관리형 방식입니다. 이 글처럼 에이전트 코드를 직접 작성하려면 --template으로 코드 기반 템플릿을 지정합니다.

그림 2. 같은 CLI의 두 경로 — add harness로 추가하는 선언형 하네스와 템플릿으로 만드는 코드 기반 프로젝트가 같은 deploy로 배포
agentcore create --name MyProject --template agent-python-strands
cd MyProject
이 템플릿은 Strands Agents와 Amazon Bedrock을 쓰는 Python 에이전트를 만듭니다. CLI는 AgentCore Memory 리소스를 함께 추가합니다. CDK와 Python 의존성 설치(npm install, uv sync), Git 초기화까지 끝냅니다. 명령이 끝나면 다음 구조의 프로젝트가 만들어집니다.
MyProject/
├── agentcore/
│ ├── agentcore.json # 프로젝트 리소스 명세
│ ├── aws-targets.json # 배포 대상 계정, 리전
│ ├── .env.local # 로컬 비밀 값 (gitignore 처리)
│ └── cdk/ # 배포용 CDK 코드
└── app/
└── agent/
├── main.py # 에이전트 진입점
├── model/ # 모델 설정 (load.py)
├── memory/ # Memory 세션 관리 (session.py)
└── pyproject.toml # Python 의존성
구조에서 CLI의 설계 방향이 드러납니다. 에이전트 로직은 app/ 아래에, 인프라와 리소스 정의는 agentcore/ 아래에 있습니다. 코드와 설정이 섞이지 않습니다.
| 파일 | 역할 |
|---|---|
agentcore/agentcore.json |
에이전트, 메모리, 게이트웨이 등 프로젝트 리소스 명세 |
agentcore/aws-targets.json |
배포 대상 AWS 계정과 리전 정의 |
agentcore/.env.local |
모델 공급자 API 키 등 로컬 비밀 값 (git 추적 제외, 배포에는 미반영) |
표 1. AgentCore 프로젝트의 구성 파일
특히 aws-targets.json의 리전이 AWS CLI 기본 리전과 다르면 배포가 엉뚱한 곳으로 향합니다. 프로젝트를 만든 직후 한 번 확인해 두는 편이 안전합니다.
프로젝트를 만들 때 고르는 핵심 선택지를 정리했습니다.
| 선택지 | 내용 |
|---|---|
--template |
코드 기반 프로젝트를 비대화형으로 생성. agent-python-strands와 컨테이너형 agent-python-strands-container, A2A와 AG-UI용 Strands, TypeScript Strands, mcp-python-fastmcp 등 |
| 대화형 마법사 | 플래그 없이 agentcore create 실행. 하네스와 코드 기반, 템플릿, 모델 공급자를 화면에서 선택 |
| 모델 공급자 | Amazon Bedrock, Anthropic, OpenAI, Gemini, LiteLLM, OpenAI 호환 엔드포인트. 마법사에서 선택하고 API 키는 .env.local에 저장 |
| 빌드 타입 | CodeZip(기본)은 Docker 없이 zip으로 패키징, Container는 AWS CodeBuild로 이미지 빌드. 템플릿으로 구분 |
| 네트워크 | PUBLIC이 기본. VPC 배치는 agentcore add runtime의 --network-config로 지정 |
표 2. 프로젝트 생성 시 핵심 선택지
몇 가지 유의점이 있습니다. 비대화형 --template 명령은 모델 공급자 플래그를 받지 않습니다. 공급자를 바꾸려면 마법사를 씁니다. TypeScript Strands 템플릿은 LiteLLM을 지원하지 않아 OpenAI 호환 엔드포인트로 대신합니다. MCP(Model Context Protocol, 모델과 외부 도구를 잇는 표준 프로토콜) 프로젝트는 mcp-python-fastmcp 템플릿으로 만듭니다. 이때는 에이전트 프레임워크 없이 도구만 노출하는 독립 도구 서버(standalone tool server)가 됩니다. A2A(Agent-to-Agent, 에이전트 간 통신 프로토콜) 프로토콜도 전용 Strands 템플릿로 지원됩니다.
4. 로컬 개발 서버로 빠르게 실험하기
배포 전 검증은 agentcore dev가 담당합니다. AgentCore Runtime 환경을 모방한 로컬 서버를 기본 8080 포트에 띄웁니다. 기본 헤드리스 모드에서는 런타임 출력을 터미널로 스트리밍합니다. --mode browser를 붙이면 브라우저에 에이전트 인스펙터가 열립니다. 채팅 형태로 바로 대화해 보고 로컬 트레이스까지 확인합니다. 코드를 수정하면 핫 리로드(hot-reload)로 즉시 반영됩니다. 포트가 겹치면 --port로 서버 포트를, --ui-port로 인스펙터 포트를 바꿉니다.
터미널 2개를 쓰는 패턴이 특히 유용합니다. 한쪽에서 서버를 띄워 두고, 다른 쪽에서 프롬프트를 반복해서 던지는 방식입니다.
# 터미널 1: 개발 서버 실행 (출력은 터미널로 스트리밍)
agentcore dev
# 터미널 2: 실행 중인 로컬 에이전트 호출
agentcore invoke --runtime agent --local --payload '{"prompt":"너는 어떤 일을 할 수 있니?"}'
MCP 프로토콜 프로젝트라면 같은 방식에 JSON-RPC 페이로드를 실어 개별 도구를 직접 호출해 봅니다.
agentcore invoke --runtime agent --local \
--payload '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add_numbers","arguments":{"a":2,"b":3}}}'
다만 로컬 환경이 배포 환경과 완전히 같지는 않습니다. 어디까지 로컬에서 검증되고 무엇이 배포 후에야 확인 가능한지 미리 알아 두면 디버깅 시간이 줄어듭니다.
| 항목 | 로컬 dev | 배포 후 |
|---|---|---|
| API 키 | agentcore/.env.local |
AgentCore Identity |
| 메모리 | 배포된 Memory ID를 환경 변수로 주입 | AgentCore Memory |
| 게이트웨이 | 배포 상태에서 읽은 환경 변수 | CDK가 주입한 환경 변수 |
| 네트워크 | localhost | 퍼블릭 엔드포인트 |
표 3. 로컬 개발 서버와 배포 환경의 차이
표에서 눈여겨볼 부분은 게이트웨이와 메모리입니다. 한 번이라도 배포한 프로젝트라면 dev 서버가 배포 상태를 읽어 AGENTCORE_GATEWAY_{이름}_URL, MEMORY_{이름}_ID 형태의 환경 변수를 로컬 프로세스에 자동 주입합니다. 덕분에 로컬 에이전트가 배포된 AgentCore Gateway의 도구와 AgentCore Memory를 그대로 쓰면서 개발할 수 있습니다. 아직 배포하지 않은 리소스는 주입되지 않고, CLI가 배포 후 dev를 재시작하라고 안내합니다.

그림 3. 로컬 dev 서버와 배포된 리소스의 관계 — 배포된 AgentCore Gateway와 Memory 정보를 환경 변수로 주입해 로컬에서도 실제 리소스로 개발
5. AWS에 배포하기
로컬 검증이 끝났다면 agentcore build로 배포 아티팩트를 만들면서 프로젝트 명세를 검증하고, 이어서 배포합니다.
agentcore build
agentcore deploy
이 명령은 agentcore.json과 aws-targets.json을 읽어 배포할 내용을 결정합니다. 빌드 타입에 따라 동작이 갈립니다. CodeZip은 에이전트 코드를 zip 아카이브로 묶어 S3에 업로드합니다. Container는 AWS CodeBuild에서 이미지를 빌드합니다. 이어서 CDK가 CloudFormation 스택을 합성합니다. IAM 역할과 AgentCore Runtime을 포함한 AWS 리소스가 만들어집니다. AgentCore Runtime은 ARM64(AWS Graviton) 기반으로 동작합니다. 아키텍처 호환은 두 빌드 타입 모두 CLI가 알아서 맞춰 주므로 개발자가 신경 쓸 일은 거의 없습니다. 배포가 끝나면 CloudWatch 로깅과 관측성 구성까지 함께 잡힙니다.

그림 4. agentcore deploy 파이프라인 — CodeZip(기본)과 Container 두 빌드 경로가 CloudFormation 스택 합성으로 합류해 IAM 역할과 AgentCore Runtime을 생성
실제 배포 전에 변경 사항을 확인하고 싶다면 프로젝트의 CDK 디렉터리에서 diff를 직접 실행합니다. agentcore build는 명세를 검증하고 아티팩트를 합성할 뿐, 배포 미리 보기가 아닙니다. agentcore deploy는 배포 전에 확인을 묻지 않으므로 바꿀 내용은 이 단계에서 확인해 둡니다.
cd agentcore/cdk && npm run cdk -- diff # 배포 전 변경 사항 확인
배포가 실패한다면 순서대로 짚어 봅니다. 먼저 aws sts get-caller-identity로 자격 증명을 확인합니다. 다음으로 agentcore build --debug로 아티팩트를 다시 만들며 디버그 로그를 봅니다. 마지막으로 agentcore deploy --debug의 상세 출력에서 실패한 리소스를 특정합니다. 첫 배포가 몇 분 더 걸리는 것은 CDK 부트스트랩 때문이니 기다리면 됩니다.
6. 배포된 에이전트 호출하기
배포가 끝나면 agentcore invoke로 바로 확인합니다.
agentcore invoke --runtime agent --payload '{"prompt":"재미있는 농담 하나 해 줘"}'
agentcore invoke --runtime agent --session-id my-session-20261120-agentcore-demo \
--payload '{"prompt":"방금 농담 설명해 줘"}'
프롬프트는 --payload에 JSON으로 감싸 전달합니다. --runtime은 런타임이 하나뿐이어도 생략할 수 없습니다. 대화 맥락을 이어 가는 --session-id는 33자 이상이어야 합니다. 1.0부터는 프로젝트 밖에서도 ARN을 지정해 기존 리소스를 바로 호출할 수 있습니다.
애플리케이션 코드에서 호출할 때는 AWS SDK의 InvokeAgentRuntime 작업을 사용합니다. 먼저 agentcore status로 배포된 AgentCore Runtime의 ARN을 확인합니다. 그다음 boto3(AWS SDK for Python)로 호출합니다. 기본 템플릿은 응답을 SSE(text/event-stream)로 스트리밍하므로, 콘텐츠 타입을 보고 분기해야 전체 응답을 안전하게 읽습니다.
import json
import uuid
import boto3
agent_arn = "<AGENT_RUNTIME_ARN>"
client = boto3.client("bedrock-agentcore")
response = client.invoke_agent_runtime(
agentRuntimeArn=agent_arn,
runtimeSessionId=str(uuid.uuid4()),
payload=json.dumps({"prompt": "재미있는 농담 하나 해 줘"}).encode(),
qualifier="DEFAULT",
)
if "text/event-stream" in response.get("contentType", ""):
for line in response["response"].iter_lines():
line = line.decode("utf-8")
if not line.startswith("data: "):
continue
event = json.loads(line[len("data: "):]).get("event", {})
delta = event.get("contentBlockDelta", {}).get("delta", {})
print(delta.get("text", ""), end="", flush=True)
print()
else:
print(json.loads(response["response"].read().decode("utf-8")))
호출하는 자격 주체에는 bedrock-agentcore:InvokeAgentRuntime 권한이 필요합니다. 에이전트에 OAuth 기반 인바운드 인증을 붙였다면 방식이 다릅니다. SigV4 대신 agentcore invoke --bearer-token <토큰>으로 토큰을 전달해 호출합니다.

그림 5. 배포된 에이전트를 호출하는 3가지 경로 — CLI와 AWS SDK는 SigV4 서명으로, OAuth 클라이언트는 Bearer 토큰으로 같은 AgentCore Runtime을 호출
7. 운영 명령과 트러블슈팅
배포 이후의 운영도 같은 터미널에서 이어집니다. agentcore status는 배포된 리소스의 상태를 대시보드로 보여 줍니다. 로그와 트레이스는 각각 전용 명령이 있습니다.
agentcore logs runtime --name agent --tail # 실시간 로그 스트리밍
agentcore logs runtime --name agent --since 2h --level error
agentcore traces runtime list --name agent --since 30m
agentcore traces runtime get <trace-id> --name agent
배포가 CloudWatch Transaction Search를 기본으로 켜므로 별도 설정 없이 로그와 트레이스를 조회합니다. 원하지 않으면 끌 수도 있습니다. 트레이스가 쌓이면 에이전트의 추론 단계별 흐름이 남아, 응답이 이상할 때 원인을 도구 호출 단위까지 좁혀 갑니다. 배포 전이라면 agentcore dev --mode browser의 인스펙터가 로컬 트레이스를 보여 주므로 같은 방식으로 디버깅합니다.
이 밖에 agentcore build는 프로젝트 명세 검증을 겸하므로 설정 오류를 배포 전에 잡아 줍니다. 로컬 8080 포트가 이미 점유되었다면 agentcore dev --port 8081처럼 포트를 바꾸면 됩니다.
리소스를 정리할 때는 순서가 중요합니다. agentcore remove all --yes는 프로젝트 명세에서 리소스 정의를 지울 뿐입니다. 이어서 agentcore deploy --yes를 실행해야 CLI가 빈 명세를 감지해 AWS 리소스를 실제로 철거합니다. 두 명령 모두 --yes 없이는 확인을 기다리며 멈춥니다.
8. add 명령으로 프로젝트 확장하기
프로토타입이 자리를 잡으면 메모리, 도구, 평가 같은 운영 요소가 필요해집니다. AgentCore CLI에서 이런 확장은 전부 agentcore add <리소스> 형태로 통일되어 있습니다. 추가한 뒤 agentcore deploy를 실행해야 AWS에 반영된다는 규칙도 같습니다. 직접 작성한 코드를 등록하는 agentcore add runtime도 여기에 속합니다. 이 명령은 app/<이름>/에 README와 선택한 프로토콜의 요구 사항을 담은 AGENTS.md를 만들어 주고, 코드는 개발자가 채웁니다. Bedrock Agents에서 넘어올 때는 --agent-id로 기존 에이전트를 AgentCore Runtime 코드로 옮깁니다.
| 리소스 | 하는 일 |
|---|---|
runtime |
직접 작성한 에이전트 코드 등록. --agent-id로 Bedrock Agents 임포트 |
memory |
SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC 전략의 대화 메모리 |
credentials |
외부 서비스용 자격 증명. api-key, oauth, payment 하위 명령으로 추가 |
gateway, gateway-target |
도구를 MCP로 노출. Lambda, MCP 서버, OpenAPI, Smithy, API Gateway 타깃 지원 |
gateway-connector |
웹 검색(web-search), Bedrock Knowledge Bases 같은 관리형 커넥터를 게이트웨이에 연결 |
evaluator, online-eval |
LLM-as-a-Judge 평가 정의와 실 트래픽 상시 평가 |
policy-engine, policy |
Cedar 기반 사전, 사후 호출 정책과 콘텐츠 필터 |
config-bundle |
시스템 프롬프트와 도구 설명의 버전 관리, A/B 테스트 변형으로 활용 |
payment-manager, payment-connector |
x402 프로토콜 기반의 호출당 결제 처리 |
harness |
에이전트 코드 없이 모델, 프롬프트, 도구, 스킬, 메모리를 선언형 설정으로 묶는 관리형 하네스(managed harness) |
표 4. agentcore add로 추가할 수 있는 주요 리소스
Knowledge Base 자체는 1.0의 CLI가 만들지 않습니다. AWS CLI의 aws bedrock-agent create-knowledge-base로 만든 뒤 gateway-connector로 게이트웨이에 연결합니다.
전부를 한 번에 도입할 필요는 없습니다. 대화 맥락 유지가 필요해지면 memory를 추가합니다. 외부 API를 도구로 붙일 때는 gateway와 gateway-target을 씁니다. 품질을 수치로 관리하고 싶어지면 evaluator와 online-eval을 얹습니다. 이렇게 필요한 시점에 하나씩 도입하는 흐름이 자연스럽습니다. 예를 들어 외부 MCP 서버를 도구로 연결하는 작업은 다음 3개 명령이면 끝납니다.
agentcore add gateway --name MyGateway
agentcore add gateway-target \
--name WeatherTools \
--endpoint https://mcp.example.com/mcp \
--gateway MyGateway
agentcore deploy
평가 영역은 평가자 정의에서 실행 명령까지 이어집니다. 1.0에서 평가 명령은 agentcore eval 아래로 묶였습니다. agentcore eval ondemand evaluate는 지정한 세션을 대상으로 온디맨드 평가를 돌립니다(--agent와 --evaluators 필수). agentcore eval batch-evaluation evaluate는 세션 전체에 평가자를 일괄 적용하고, 평가용 데이터셋은 agentcore eval dataset으로 관리합니다. agentcore eval recommendation start는 실제 세션 트레이스를 근거로 시스템 프롬프트와 도구 설명의 개선안을 생성합니다. 개선안은 config-bundle 버전으로 만들어 agentcore eval ab-test config-based run으로 트래픽을 나눠 검증합니다. 진행 중인 테스트는 agentcore eval ab-test pause, resume, stop으로 다룹니다. 이긴 쪽의 승격은 테스트를 멈춘 뒤 AWS CLI의 aws bedrock-agentcore-control create-gateway-rule로 라우팅 규칙을 바꾸는 방식이라, 이 단계만 AgentCore CLI 밖으로 나갑니다.

그림 6. 평가와 개선 사이클 — 평가자 정의부터 A/B 검증까지 eval 명령으로 잇고, 승격만 AWS CLI로 마무리
9. Kiro CLI, Claude Code와 함께 쓰기
AgentCore CLI 발표문에는 눈에 띄는 문장이 하나 있습니다. 이 CLI는 처음부터 코딩 어시스턴트가 제어하기 좋게 최적화되었습니다. 실제로 모든 명령이 비대화형으로 동작하고 --json으로 구조화된 결과를 돌려줍니다. 터미널에서 bash를 실행하는 AI 코딩 에이전트라면 AgentCore CLI 전체가 곧 도구가 됩니다. Kiro CLI와 Claude Code 모두 이 조건을 충족합니다. 결합 방법은 크게 3가지입니다.

그림 7. Kiro CLI, Claude Code와 AgentCore CLI를 결합하는 3가지 방법 — CLI 직접 실행, 스킬 설치, MCP 서버 연결
첫 번째는 코딩 에이전트가 AgentCore CLI를 직접 실행하는 방식입니다. 별도 설정 없이 프로젝트 디렉터리에서 코딩 에이전트에게 이렇게 지시한다고 해 보겠습니다.
이 프로젝트의 에이전트에 날씨 조회 도구를 추가하고,
로컬 dev 서버에서 "서울 날씨 알려줘"가 정상 응답할 때까지 수정해 줘.
지시를 받은 Kiro CLI나 Claude Code는 app/agent/main.py를 수정합니다. agentcore dev로 서버를 띄우고 agentcore invoke --runtime agent --local --payload '{"prompt":"서울 날씨 알려줘"}'로 호출해 응답을 확인합니다. 오류가 나면 agentcore logs runtime --name agent --level error --json의 구조화된 출력을 읽고 다시 코드를 고치는 루프를 스스로 반복합니다. 사람이 하던 수정-실행-확인 반복을 코딩 에이전트가 대신하는 동안, 개발자는 결과와 방향만 검토하면 됩니다. 이 루프의 품질을 높이는 방법이 있습니다. 프로젝트 루트의 CLAUDE.md(Claude Code)나 스티어링(steering) 파일(Kiro)에 프로젝트 규칙을 적어 둡니다. “테스트는 agentcore dev로, 배포 전 agentcore build 실행” 같은 식입니다. 실제로 AgentCore CLI 저장소 자체도 루트에 CLAUDE.md와 AGENTS.md를 두고 이 방식으로 개발되고 있습니다. 1.0의 agentcore add runtime이 새 런타임마다 AGENTS.md를 만들어 주는 것도 같은 맥락입니다.
두 번째는 AgentCore 스킬을 설치하는 방식입니다. 코딩 에이전트의 학습 데이터는 시간이 지나면 낡기 마련입니다. 최신 AgentCore 명령 체계와 모범 사례를 스킬 형태로 주입하면 정확도가 올라갑니다. Kiro에서는 파워(Power) 카탈로그에서 Amazon Bedrock AgentCore 파워를 원클릭으로 설치합니다. Claude Code에서는 Agent Toolkit for AWS가 제공하는 aws-agents 플러그인을 설치하면 됩니다. 이 플러그인은 Claude Code에 기본 등록된 Anthropic 공식 플러그인 마켓플레이스에 올라와 있습니다. /plugin 메뉴에서 검색해 바로 추가하면 됩니다.
세 번째는 AgentCore MCP 서버 연결입니다. AWS Labs가 공개한 Amazon Bedrock AgentCore MCP 서버는 2가지 도구 묶음을 제공합니다. 하나는 최신 AgentCore 문서를 검색하는 도구입니다. 다른 하나는 AgentCore Runtime, Memory, Gateway 같은 리소스를 API로 직접 조작하는 운영 도구입니다. Kiro는 .kiro/settings/mcp.json, Claude Code는 프로젝트 루트의 .mcp.json에 같은 형식으로 등록합니다.
{
"mcpServers": {
"bedrock-agentcore-mcp-server": {
"command": "uvx",
"args": ["awslabs.amazon-bedrock-agentcore-mcp-server@latest"],
"env": { "FASTMCP_LOG_LEVEL": "ERROR" },
"disabled": false,
"autoApprove": ["search_agentcore_docs", "fetch_agentcore_doc"]
}
}
}
문서 검색 도구 2개를 autoApprove에 넣어 두면 코딩 에이전트가 매번 승인을 묻지 않고 최신 문서를 참조합니다. 정리하면 이렇습니다. CLI 직접 실행은 개발 루프 자동화에, 스킬은 최신 지식 주입에, MCP 서버는 문서 참조와 리소스 조작에 강합니다. 셋을 함께 쓸 때 효과가 가장 큽니다.
이 조합은 CI/CD로도 자연스럽게 확장됩니다. 사람이든 코딩 에이전트든 파이프라인이든 같은 명령을 쓰기 때문입니다.
agentcore build # 명세 검증과 아티팩트 패키징
(cd agentcore/cdk && npm run cdk -- diff) # 배포 전 변경 사항 확인
agentcore deploy --json # 배포 (확인을 묻지 않고 진행)
10. 마치며
코드를 고칠 때마다 로컬에서 바로 확인하는 문제는 agentcore dev의 핫 리로드와 터미널 2개 패턴이 해결합니다. 터미널 하나로 이어지는 워크 플로우는 create, dev, deploy, invoke의 4단계 수명 주기로 만들어집니다. 여기에 status, logs, traces 같은 운영 명령이 더해져 완성됩니다. 프로젝트가 성장하면 add 명령으로 메모리부터 평가, 정책까지 같은 방식으로 확장됩니다. 모든 명령은 비대화형과 --json을 지원합니다. 이 설계 덕분에 Kiro CLI와 Claude Code 같은 AI 코딩 에이전트가 워크 플로우 전체를 대신 수행하는 개발 방식까지 열립니다. 2026년 10월의 1.0 정식 출시로 이 워크 플로우는 더 빠른 시작 속도와 일관된 명령 구조라는 안정된 기반 위에 올라섰습니다.
에이전트 개발 도구는 빠르게 진화합니다. 명령의 세부 옵션은 AgentCore CLI 레퍼런스와 Amazon Bedrock AgentCore 개발자 가이드에서 최신 내용을 확인하시기 바랍니다.
참고 자료
- Amazon Bedrock AgentCore CLI version 1.0 is now available (What’s New, 2026년 10월)
- AgentCore CLI GitHub 저장소
- Get started with Amazon Bedrock AgentCore – 개발자 가이드
- AgentCore CLI 레퍼런스 – 개발자 가이드
- Amazon Bedrock AgentCore 릴리스 노트 – 개발자 가이드
- Amazon Bedrock AgentCore adds new features to help developers build agents faster (What’s New, 2026년 4월)
- Amazon Bedrock AgentCore MCP Server 시작하기
- Agent Toolkit for AWS