검색

나도 에이전트 만들 수 있을까? AgentCore Harness (AgentCore 실전편)

8월 5일
3분 분량

AgentCore Harness: Hands-On with Amazon Bedrock AgentCore

Written by Minhyeok Cha

머릿말

요즘 세상, AI가 뭐든지 다해주는 시대가 와버렸습니다.

그런데 솔직히 말하면, 저는 작년까지만 해도 "에이전트 만들기"라는 말이 조금 무겁게 느껴졌습니다. AI를 사용하여 작업한다 하더라도 PoC 한 번 찍는 데 일주일이 넘어가는 느낌입니다.

그러던 중 지난 6월, Amazon Bedrock AgentCore Harness 정식 출시 소식이 나왔더라구요. "코드 없이, 콘솔 몇 번으로 에이전트가 뜬다"는 게 진짜인지 확인은 해봐야 할 것 같아서, 늦게나마 탐방해보려고 합니다.

제가 이번에 만들어본 건 AWS 빌링 문의 대응 에이전트입니다. MSP 회사 특성상 고객사로부터 "이번 달 비용이 왜 이렇게 나왔죠?"류의 문의가 꽤 자주 들어오거든요. 물론 저의 실제 업무용은 아니고, 블로그용 시나리오입니다.

이번 글에서는 AgentCore Harness가 뭔지 짚고, Gateway에 Lambda를 연결한 뒤 콘솔에서 에이전트 프로토타입을 띄우는 전 과정을 실습 순서대로 정리했습니다.

추가로 요즘 보안, 개인정보보호도 이슈인 만큼 PII 보호를 위한 Guardrail 구성까지 연결해보고자 합니다.

AgentCore Harness란?

AgentCore는 사실 하나의 단일 서비스가 아니라, Runtime(에이전트 실행 환경), Memory(기억 저장), Gateway(외부 도구 연결), Identity(인증), Observability(관찰성) 같은 여러 개별 구성요소(프리미티브)의 모음입니다. 각각은 독립적으로 사용할 수 있지만, 그만큼 "이 조각들을 어떻게 서로 연결할 것인가"라는 조립의 부담이 개발자에게 그대로 남아 있었습니다.

Harness는 바로 이 조립 과정을 대신 처리해주는 상위 레이어입니다. Runtime, Memory, Gateway, Tool 같은 프리미티브들을 개발자가 하나하나 배선하지 않아도, 모델·시스템 프롬프트·도구 목록만 선언하면 이 모든 조각이 자동으로 엮여서 동작하는 관리형 추상화 계층이라고 보면 됩니다.

Harness 이전에는

에이전트가 도구를 호출하고, 결과를 받아 다음 판단에 반영하는 추론 루프(reasoning loop)를 직접 작성
Memory를 언제 저장하고 언제 불러올지 로직 수동 연결
Gateway로 노출한 도구들을 모델이 실제로 잘 선택해서 쓰도록 프롬프트와 파싱 로직을 세심하게 조율

즉, 아이디어는 있는데 "동작하게 만드는" 배선 작업 자체가 프로토타입 하나를 만드는 데도 상당한 시간을 잡아먹는 구조였으나 Harness 적용 이후에는 모델, 시스템 프롬프트, 도구만 사용하여 어떻게 조합해서 하나의 동작하는 에이전트로 만들어낼지는 Harness가 내부적으로 처리합니다.

AWS 빌링 문의 대응 에이전트 설계

각 구성 요소가 하는 일

Inbound Auth — (본문에서는 IAM으로 사용)
담당자가 Cognito 같은 OIDC 제공자로부터 발급받은 JWT 토큰을 들고 챗봇을 호출합니다. AgentCore Runtime/Gateway에 내장된 Inbound Authorizer가 discovery URL로 공개키를 조회해 서명·발급자(issuer)·대상(audience)을 검증합니다.
Outbound Auth — (본문에서는 IAM으로 사용)
Lambda가 실행되기 직전, 사용자가 위임한 권한 범위(3LO, OAuth 인가 코드 흐름) 내에서만 데이터에 접근하도록 확인합니다. 이 게이트가 없으면 고객 A의 질문으로 고객 B의 데이터까지 조회될 위험이 있습니다.
Guardrails — PII 체크
Bedrock Guardrails가 AgentCore 정책에 연동되어, 승인된 에이전트 행동에 대한 입력을 검사합니다. 프롬프트 인젝션 시도, 유해 콘텐츠를 이 단계에서 걸러냅니다. Lambda가 실행되기 전에 막아야, 이미 실행된 조회를 되돌릴 필요가 없습니다.
Gateway — 도구 연결
Harness가 "빌링 데이터를 조회해야겠다"고 판단하면, Gateway가 Lambda 함수를 MCP(Model Context Protocol) 호환 도구로 변환해 실제 실행으로 연결합니다.
MCP / API — 실제 조회
AgentCore가 도구 호출이 필요하다고 판단하면, 화살표가 아래로 내려가 Gateway 영역으로 연결됩니다. Gateway 안에는 두 가지 도구가 등록되어 있습니다.

실습: Guardrail부터 Harness까지

이번 실습단계에서는 Bedrock Harness 중 사용하고자 하는 Gateway 및 bedrock 가드레일 - Agentcore 연결하여 사용 방식을 안내 드립니다.

1. Bedrock guardrail 세팅

먼저 AWS Console에서 Bedrock에 들어와 왼쪽 탭에서 가드레일을 선택합니다.

저같은 경우 빌링 에이전트를 만들기 위해 빌링 관련된 질문과 PII 관련 필터는 다음과 같이 기재하였습니다.

2. Agentcore Gateway용 Lambda 세팅

본 블로그에서는 billing-cost-management-mcp-server와 AWS detect_cost_anomalies용 Lambda를 사용하였습니다.

아래 사진과 같이 Gateway에 위에서 언급한 MCP 서버와 사전에 구성한 anomalies용 lambda 연결을 합니다.

3. AgentCore harness 생성

Agentcore에 bedrock 가드레일 붙이는 방법은 다음 블로그를 참고해주세요.

Implementing Guardrails on AWS Bedrock AgentCore 출처: John Walker · AWS Community Builders (dev.to) 🔗 https://dev.to/aws-builders/implementing-guardrails-on-aws-bedrock-agentcore-acj

본 블로그에서는 Bedrock Guardrail 3종 정책(주제 이탈/PII·재무정보/프롬프트 인젝션) 만드는 create_guardrail + Harness 생성 시 guardrailConfig 연결 방식을 사용했습니다.

이후 콘솔에 들어가 Harness에서 사용하고자 하는 Gateway를 연결합니다.

이후 왼쪽탭에서 하네스 플레이그라운드에 들어가 방금 만든 에이전트를 선택한 후 테스트를 진행해보겠습니다.

계정 비용을 물으니 gateway에서 세팅한 타겟 중 하나를 돌려 출력된 값을 확인할 수 있었습니다.

이번엔 가드레일의 작동 확인을 합니다.

테스트 도중 고정된 출력만 나와 확인해보니 Guardrail 생성 중 다음 내용을 수정하지 않고 생성한 것이 원인이었습니다.

만약 가드레일을 사용하실 분들은 가드레일 설정을 수정해서 해당 케이스가 차단되지 않도록 정책/필터 기준을 조정 하시면 될 것 같습니다.

마무리

처음 Agentcore가 나왔을 땐 Strands Agents SDK로 오케스트레이션 코드를 직접 짜고, 컨테이너로 패키징해서 Custom Runtime에 배포했습니다. 도구 호출, 에러 처리까지 전부 코드로 명시해야 했죠. 그런데 AgentCore Harness로 옮겨보니, 정작 우리가 짰던 오케스트레이션 코드가 필요 없어졌습니다. 모델, 시스템 프롬프트, 도구 연결 전부 콘솔 설정만으로 가능했습니다.

Harness는 에이전트를 인프라 걱정 없이 설정만으로 만드는 데 좋지만, Guardrail을 같이 엮어 사용해보니 살짝 코드작성이 필요한 부분도 있었네요.