Molayo

© 2026 Molayo

Qiita헤드라인2026. 06. 06. 11:36

【AWS】AgentCore Managed Harness에서 자체 Skills를 사용할 수 있게 되었는데 말이죠...

요약

Amazon Bedrock AgentCore Managed Harness에서 사용자 정의 Agent Skills를 추가하고 검증하는 방법을 다룹니다. 도구 버전 관리의 중요성과 스킬을 microVM에 배치하거나 Docker 이미지에 포함하는 두 가지 구현 패턴을 설명합니다.

핵심 포인트

  • boto3 및 aws CLI 최신 버전 업데이트 필수
  • 스킬 로드 여부를 특정 규칙(🌙)으로 판정하는 검증 방법
  • microVM에 직접 배치하는 휘발성 방식과 Docker 이미지 내장 방식 비교
  • 운영 환경에서는 Docker 이미지에 스킬을 포함하는 방식 권장

Amazon Bedrock AgentCore Managed Harness가 있습니다. 이 Harness에 Agent Skills를 추가하여 동작시켜 보았습니다.

Harness 발표 직후에는 추가가 잘 되지 않았는데, 최근 들어 가능해진 것 같아서 시도해 보았습니다.

실행 전에 반드시 도구의 버전을 확인해 두는 것을 권장합니다. 저는 이 부분에서 막혔기 때문에....

도구최소 버전출처확인/업데이트 명령어
boto3 / botocore1.43.17 이상 (s3 소스 포함. 기본만 한다면 1.42.94)botocore CHANGELOG: 1.42.94에서 Harness API, 1.43.17에서 S3/Git 소스 추가venv에서 pip install -U "boto3>=1.43.17"
aws CLI2.34.56 이상 (control plane용. s3 소스 포함)aws-cli CHANGELOG: 2.34.35에서 Harness, 2.34.56에서 S3/Git 추가aws --version / brew upgrade awscli

또한, 업데이트 이력은 다음 리포지토리에서도 확인할 수 있으므로, 무언가 업데이트가 있을 때 정기적으로 확인하는 것을 권장합니다.

실행할 때는 python의 가상 환경에서 실행하는 것이 좋을지도 모릅니다.

가상 환경 하에서 harness 관련 API가 보이는지 확인해 둡니다.

cd /hogehoge
python3 -m venv .venv
.venv/bin/pip install -U "boto3>=1.43.23"
...

이번에 사용할 확인용 스킬인데, 알기 쉬운 것을 만들었습니다.

이번에는 이것을 사용하여 확인합니다.

---
name: commit-message
description: hogehoge 팀의 Git 커밋 메시지 규약에 따라, 1줄의 일본어 커밋 메시지를 생성한다. 커밋 메시지 작성·수정·제안을 요청받으면 반드시 이 스킬을 사용한다.
...

스킬에만 있는 규칙(앞부분에 🌙)을 심어두고, invoke의 출력에 🌙이 나오면 "스킬이 로드되었다"라고 판정합니다. 스킬이 없으면 일반적인 feat: ... 등이 됩니다.

이번 검증에서는 (Bedrock 호출 / 컨테이너 pull / 로그 / Workload Identity) 이러한 권한이 필요하므로 미리 역할을 생성해 둡니다.

공식 문서에서 명시되어 있는 패턴은 크게 두 종류가 있습니다만, 그 외에도 실현 가능한 방법은 다른 몇 가지 패턴이 더 있으므로 비교를 위해 병기해 둡니다.

그 외에도 이런 사용법을 알고 있다~ 하는 분이 계시면 꼭 알려주셨으면 좋겠습니다!

Harness의 microVM에, invoke 하기 전에 스킬 파일을 써두는 방법. InvokeAgentRuntimeCommand로 셸 명령어를 실행하여 배치합니다.

[SKILL.md] →(명령어 실행으로 쓰기)→ microVM:/app/... → Agent가 읽음 ※해당 세션의 VM에만 남음(휘발)

간편하지만, 배치한 스킬은 해당 세션의 VM에만 남기 때문에, 그때마다 다시 넣어줘야 한다는 점만 주의가 필요합니다.

스킬을 이미지에 COPY로 구워 넣고 ECR에 push 하여, Harness의 containerUri에 지정하는 방법.

[SKILL.md] → Docker 이미지에 동봉 → ECR → 각 microVM에 처음부터 내장 → Agent가 읽음

매 세션 처음부터 스킬이 들어있기 때문에, 취득도 배치도 필요 없습니다. 공식에서도 운영 환경에서는 이 방법을 권장합니다.

API 레퍼런스를 참조하면, harness 생성 시 지정 가능하다는 것을 알 수 있습니다.

skills의 각 요소(HarnessSkill)는 path / s3 / git 세 가지 선택지가 있으며, s3 / git을 지정하면 환경에 두지 않아도 Harness가 기동 시에 가져옵니다. 작성 방식은 다음과 같습니다:

// path형 (①②는 이것. 환경에 배치된 경로를 가리킴)
{ "path": "/app/.agents/skills/commit-message" }
// s3형 (s3://버킷/스킬 디렉토리를 가리킴)
...

또한, 역할(Role)에 별도로 s3:GetObject / s3:ListBucket 권한이 필요합니다.

최근 업데이트로 Runtime에서 파일 시스템을 마운트(Mount)할 수 있게 되었습니다.

내부적으로는 Runtime이 동작하고 있으므로, Harness로 생성한 에이전트에서도 스킬(Skills)을 마운트할 수 있습니다. 이를 사용하여 공유 스토리지로서 스킬을 에이전트 간에 이용할 수 있습니다.

이와 관련해서는 다음 기사에서 다루고자 합니다만, 이 구성은 NAT Gateway 등을 생성했을 때 비용이 발생하므로 검증할 때는 주의합시다.

이번에는 다음 두 가지 패턴(① 세션 시작 시 / ② 컨테이너 포함)을 실제로 실행해 본 절차를 작성하겠습니다.

그 외의 패턴은 다음 기사 이후에 작성하도록 하겠습니다...

매니지먼트 콘솔(Management Console) 등에서 미리 Harness를 생성해 두었다고 가정합니다. 원래는 매니지먼트 콘솔만으로 완결하고 싶었지만, 아무래도 매니지먼트 콘솔만으로는 스킬(Skills) 추가가 어려워 보였기에 이번에는 생략합니다. 또한, 기사 서두에서 언급한 스킬(Skills)도 생성해 둔 상태로 가정합니다.

이런 느낌으로 우선 생성되어 있다면 된 것으로 하겠습니다.

VSCode 같은 것으로 스킬(Skills)을 만들어 둔다.
$ cd ~/hogehoge/hugahuga # SKILL.md가 있는 위치
ARN="<매니지먼트 콘솔에서 만든 Harness의 ARN>"
...

실행 후, 달 모양 마크가 나타난다면 정상적으로 스킬(Skills)이 로드된 것이라 할 수 있습니다.

만약 나타나지 않는다면 무언가 에러가 발생한 것입니다.

실제로 도구를 실행하고 있는 모습은 CloudWatch를 통해서도 확인할 수 있습니다.

한 가지 아쉬운 소식입니다만, 이 적용 방법으로는 매니지먼트 콘솔에 있는 Harness 설정 화면의 스킬(Skill)란에는 표시되지 않습니다.

그도 그럴 것이, 이 방법은 세션마다 기동되는 마이크로 VM(Micro VM)에 대해 스킬을 적용하기 때문입니다.

중간에 긴 세션 ID를 지정했었죠? 바로 그런 것입니다. 매니지먼트 콘솔에 표시하고 싶다면 후술하는 방법처럼 Harness 자체에 적용하는 것이 좋습니다.

이 방법은 조금 복잡하므로 건너뛰셔도 무방하지만, 대략 다음과 같은 절차가 됩니다.

Dockerfile 작성 → ECR에 push → 이미지를 기반으로 Harness 생성 → 설정에 경로를 부여

그전에, 구성은 다음과 같은 형태라고 상정하고 있습니다.

commit-skill-agent/ ← 프로젝트 루트 (임의의 이름)
├── Dockerfile ← 스킬을 포함할 이미지 정의
└── skills/
...

Dockerfile은 이것뿐입니다. 작성 후에는 빌드하여 ECR에 푸시합시다.

FROM public.ecr.aws/docker/library/python:3.12-slim
# 스킬을 기지의 경로에 동봉 (디렉토리명 = 스킬명 commit-message)
COPY skills/commit-message/SKILL.md /app/.agents/skills/commit-message/SKILL.md

커스텀 이미지를 사용한 Harness 생성은 현재 매니지먼트 콘솔상에서는 어려워 보입니다. 따라서 AWS CLI 레퍼런스를 참조하여 작성해 보겠습니다.

# 이렇게 하면 Harness 생성 시 이미지를 적용
$ aws bedrock-agentcore-control create-harness --region us-west-2 \
--harness-name skilldemo_image \
...

네, 그래서 플레이그라운드(Playground)에서도 자체 스킬을 Harness를 통해 사용할 수 있었습니다.

물론 설정에도 적용되어 있습니다.

제 상상으로는 좀 더 가볍게 사용할 수 있게 되는 것일지도 모른다고 생각했습니다만, 조금 다를지도 모르겠습니다. (에이전트 생성은 척척 할 수 있지만)

어느 쪽인가 하면, 스킬(Skills) 같은 도구도 통째로 내포한 에이전트를 구동하거나, 커스터마이징하기 위한 기반 같은 느낌일까요...

AWS에서의 Harness는 다음 기사에서도 언급되어 있습니다만,

기능 추가는 코드를 다시 작성할 필요 없이 설정 변경만으로 가능하다고 하니, 속도와 유연성을 겸비한 기반이라는 말은 아주 틀린 말은 아닐 것 같습니다 (더 만지고 싶다면 직접 코드를 짜라는 뜻이겠지만요).

따라서, AgentCore Harness = '어쨌든 편하고 빠르게 만들 수 있고 무엇이든 할 수 있다!'라는 말은 조금 다르다는 점만 알아두셨으면 합니다.

이 글을 쓰는 내내 코에 감기약이 꽉 막혀 있는 듯한 기분이었습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0