이 글은 Amazon Bedrock AgentCore Runtime에 배포된 개인화된 AWS 어시스턴트인 AWS Briefing Agent를 구축하며 얻은 아키텍처, 구현 및 교훈을 기록하는 시리즈의 세 번째 게시물입니다.

Part 1: Bedrock AgentCore에서 풀스택 AI 에이전트 구축
Part 2: 데이터 수집 (Data Ingestion): RSS 피드, 지식 기반 (Knowledge Base), S3 벡터 및 메타데이터 필터링
Part 3: Strands Agents + AgentCore Runtime - 완벽한 조합
Part 4: 에이전트에 메모리 (Memory) 추가하기
Part 5: API Gateway 실험
Part 6: 관찰성 (Observability) 및 평가 (Evaluations)
Part 7: 제3자 통합 (Third Party Integrations) - ID, 게이트웨이 및 Slack 알림

AWS Briefing Agent의 초기 구현은 호출될 때마다 AWS News Feed RSS 피드를 호출했습니다. Amazon Bedrock Knowledge Base를 설정한 후, 다음 단계는 에이전트 프레임워크 (Agentic Framework)를 활용할 수 있도록 코드를 리팩터링 (Refactor)하는 것이었습니다. 우리는 단 몇 줄의 코드만으로 AI 에이전트를 구축하고 실행할 수 있도록 돕는 오픈 소스 SDK인 Strands Agents SDK를 채택하기로 결정했습니다. 우리의 경우, Knowledge Base로 전환하고 Strands Agents SDK를 채택함으로써 구현 로직의 코드 줄 수를 75% 줄일 수 있었습니다.

Strands Agents SDK 사용 Strands Agents 코드의 핵심은 간단하며 아래 코드 스니펫에서 확인할 수 있습니다: from strands import Agent from strands.models import BedrockModel from strands.agent.conversation_manager import SlidingWindowConversationManager from strands_tools import retrieve from agent.tools.slack_formatter.tool import format_slack_message model = BedrockModel ( guardrail_id = GUARDRAIL_ID , guardrail_version = GUARDRAIL_VERSION , guardrail_trace = " enabled " , ) agent = Agent ( system_prompt = _load_system_prompt (), model = model , tools = [ retrieve , format_slack_message ] + gateway_tools , session_manager = session_manager , conversation_manager = SlidingWindowConversationManager ( window_size = 20 , should_truncate_results = True , per_turn = True , ), callback_handler = None , ) result = agent ( message ) 우리는 두 패키지(strands-agents 및 strands-agents-tools)와 하나의 로컬 모듈에서 여러 클래스와 함수를 가져오는 것부터 시작합니다. Agent는 에이전트 자체의 핵심 클래스이며, BedrockModel은 모델 제공자이고, SlidingWindowConversationManager는 대화 기록을 자르는 방식을 제어하며, retrieve는 Bedrock Knowledge Base에 쿼리하는 데 사용되는 사전 구축된 도구입니다. format_slack_message는 이 프로젝트 내의 로컬 사용자 정의 도구로, @tool 어노테이션으로 장식된 Python 함수입니다. 우리는 model_id를 지정하지 않고 BedrockModel()을 인스턴스화합니다. 이 시점에서 Strands는 기본 모델인 현재 Claude Sonnet on Bedrock을 사용합니다. 모델을 인스턴스화할 때 Bedrock Guardrail의 세부 정보를 포함하는 것은, 나중에 블로그 게시물에서 다룰 guardrails의 사용을 순전히 시연하기 위함입니다. 마지막으로, 핵심 구성 요소들을 연결하여 에이전트를 생성합니다.

Amazon Bedrock AgentCore Runtime에 배포하기

AgentCore Runtime Python SDK는 에이전트 함수를 HTTP 서비스로 배포할 수 있도록 돕는 경량 래퍼 (wrapper)를 제공합니다.

# bedrock_agentcore.runtime에서 런타임을 임포트합니다.
from bedrock_agentcore.runtime import BedrockAgentCoreApp

# 앱을 초기화합니다.
app = BedrockAgentCoreApp()

# 함수에 데코레이터를 적용합니다.
@app.entrypoint
def invoke ( payload : Dict [ str , Any ], context : Any = None ) -> Dict [ str , Any ]: 
    """ AgentCore Runtime을 위한 엔트리 포인트 (Entry point)입니다. """
    message = payload . get ( " prompt " , payload . get ( " message " , "" ))
    ...
    return response

BedrockAgentCoreApp은 8080 포트에서 대기하는 HTTP 서버로 사용자의 함수를 감싸며, 두 개의 엔드포인트 (endpoint)를 가집니다:

• /invocations - 에이전트 상호작용을 위한 POST 엔드포인트입니다. 고객이 JSON 형식의 페이로드 (payload)와 함께 InvokeAgentRuntime 액션을 호출할 때 실행됩니다.
• /ping - 에이전트가 정상적으로 작동하고 요청을 처리할 준비가 되었는지 확인하기 위한 상태 확인 (health check)용 GET 엔드포인트입니다.

@app.entrypoint 데코레이터는 invoke 함수를 들어오는 요청에 대한 핸들러 (handler)로 등록합니다. AgentCore Runtime이 요청을 받으면, JSON 본문을 payload로 역직렬화 (deserialise)하고, 컨텍스트 객체 (session_id, request_headers 등 포함)를 제공하며, 사용자의 함수를 호출한 뒤 반환된 딕셔너리 (dict)를 다시 HTTP 응답으로 직렬화 (serialise)합니다.

컨테이너 빌드 (Container Build) 사용하기

@aws/agentcore CLI를 사용하고 agentcore deploy를 실행할 때, CLI는 Python 소스 코드를 AgentCore Runtime에서 실행 가능한 컨테이너 이미지 (container image)로 변환해야 합니다. 이는 agentcore.json 파일의 build 필드에 의해 제어됩니다.

기본 설정은 CodeZip이며, 이 방식에서 CLI는 Python 소스 코드를 압축하여 업로드하고, AgentCore는 uv --no-build를 사용하여 의존성 (dependencies)을 해결합니다. 이 방식은 빠르지만, 모든 의존성이 미리 빌드된 휠 (wheel) 파일을 가지고 있어야 한다는 엄격한 제약 조건이 있습니다. 저희 코드에는 소스 배포판 (source distributions)만 제공하는 패키지가 포함되어 있어, Container 빌드 설정으로 전환해야 했습니다. 이 방식은 빌드를 더욱 프로덕션 환경에 적합하게 (production-ready) 만들어 주기도 합니다.

Container 빌드 유형으로 agentcore deploy를 실행하면, CLI는 CodeBuild 프로젝트, ECR 리포지토리(repository), AgentCore Runtime 리소스 및 IAM 역할(roles)을 포함하는 CloudFormation 스택을 합성(synthesis)합니다. CLI는 codeLocation 디렉토리(agent/)를 패키징하여 CodeBuild 소스 아티팩트(artefact)로서 S3에 업로드합니다. CodeBuild는 제공된 Dockerfile을 가져와 컨테이너 이미지(container image)를 빌드합니다. 아래의 CodeBuild 프로젝트에서 모든 단계를 확인할 수 있습니다: [IMG:1] 이미지가 성공적으로 빌드되면, CodeBuild는 아래와 같이 이미지에 태그를 지정하고 ECR 리포지토리로 푸시(push)합니다: [IMG:2] 스택은 Runtime 리소스가 새로운 ECR 이미지 URI를 가리키도록 업데이트합니다. AgentCore는 다음번 호출(invocation)을 위해 컨테이너를 시작할 때 ECR에서 이미지를 가져옵니다.

내장 대화 관리자 (Built-In Conversation Managers)
Strands Agents SDK에서는 사용자의 메시지와 에이전트의 응답이 모두 컨텍스트(context)에 추가됩니다. 세션 내에서 대화가 길어짐에 따라, 이는 응답 시간(response times)에 상당한 영향을 미치기 시작했습니다. 우리는 기본 SlidingWindowConversationManager를 수정했습니다: windowSize를 기본값인 40에서 20으로 줄였습니다. 이는 유지할 메시지의 최대 개수를 설정하는 것입니다. 또한 per_turn 파라미터를 false로 설정했습니다. 이는 에이전트 루프(agent loop)가 완료될 때까지 기다리는 대신, 동일한 호출(invocation) 내에서 모델 호출(model call)이 발생하기 직전에 슬라이딩 윈도우(sliding window)를 실행하도록 합니다. 이를 통해 평균 응답 시간을 약 80초에서 15초로 단축했습니다.

Amazon Bedrock Guardrails 추가
Amazon Bedrock Guardrails는 책임감 있는 생성형 AI (generative AI) 애플리케이션을 확신을 가지고 안전하게 구축하고 배포할 수 있도록 설계되었습니다. 우리는 가드레일(guardrail)이 어디에 적합하며 무엇을 제공할 수 있는지 이해하기 위해 아키텍처에 가드레일을 포함하기로 결정했습니다.

가드레일 자체는 콘텐츠 필터(성적, 폭력, 혐오, 모욕, 부적절한 행위 및 프롬프트 공격 (prompt attack)), 주제 정책(주제와 무관한 스포츠 질문 거부), 그리고 관리되는 비속어 목록 (managed profanity word list)을 포함하여 CDK로 정의되었습니다:

---------------------------------------------------------------- # Bedrock Guardrail — 에이전트를 위한 콘텐츠 안전성 # ----------------------------------------------------------------

guardrail = bedrock.CfnGuardrail(
self,
"BriefingAgentGuardrail",
name="briefing-agent-guardrail",
description="AWS Briefing Agent를 위한 콘텐츠 안전성 가드레일",
blocked_input_messaging="죄송합니다, 해당 요청을 처리할 수 없습니다. AWS 발표에 관한 질문으로 다시 말씀해 주세요.",
blocked_outputs_messaging="죄송합니다, 해당 응답을 제공할 수 없습니다. 다른 방식으로 시도해 보겠습니다.",
content_policy_config=bedrock.CfnGuardrail.ContentPolicyConfigProperty(
filters_config=[
bedrock.CfnGuardrail.ContentFilterConfigProperty(
type="SEXUAL",
input_strength="HIGH",
output_strength="HIGH",
),
bedrock.CfnGuardrail.ContentFilterConfigProperty(
type="VIOLENCE",
input_strength="HIGH",
output_strength="HIGH",
),
# HATE, INSULTS, MISCONDUCT, PROMPT_ATTACK
],
),
topic_policy_config=bedrock.CfnGuardrail.TopicPolicyConfigProperty(
topics_config=[
bedrock.CfnGuardrail.TopicConfigProperty(
name="Sports",
definition="스포츠 점수, 경기 결과, 선수 이적, 리그 순위, 일정 또는 기타 스포츠 행사에 관한 질문.",
type="DENY",
),
],
),
word_policy_config=bedrock.CfnGuardrail.WordPolicyConfigProperty(
managed_word_lists_config=[
bedrock.CfnGuardrail.ManagedWordsConfigProperty(
type="PROFANITY",
),
],
),
)

에이전트가 호출되면, 요청은 먼저 AgentCore Runtime에 도달하여 핸들러 (handler) 코드를 먼저 실행합니다. 가드레일 자체는 핸들러가 Bedrock 추론 (inference) 호출을 수행할 때만 적용됩니다.

Bedrock은 모델 추론 (inference)을 실행하기 전에 입력을 평가하고, 출력을 반환하기 전에 검사합니다. 가드레일 (guardrail)을 구현하면서 몇 가지 흥미로운 동작을 발견했습니다.

IAM 권한 격차 (IAM Permission Gap)
가드레일을 추가한 후 첫 번째 호출이 다음과 같은 오류와 함께 실패했습니다: AccessDeniedException: User is not authorized to perform: bedrock:ApplyGuardrail on resource: arn:aws:bedrock:eu-west-1.xxx. AgentCore 실행 역할 (AgentCore execution role, @aws/agentcore-cdk 컨스트럭트에 의해 자동 생성됨)에는 bedrock:InvokeModel 및 bedrock:InvokeModelWithResponseStream은 포함되어 있지만, bedrock:ApplyGuardrail은 포함되어 있지 않았습니다. 해당 컨스트럭트는 가드레일에 대해 알지 못합니다. 가드레일은 AgentCore의 기능이 아니라 Bedrock의 기능이기 때문입니다. 결국 우리는 aws iam put-role-policy CLI 명령어를 사용하여 누락된 권한을 추가해야 했습니다.

토픽 정책 (Topic policies)이 정당한 쿼리에 대해 오탐 (false-positive)을 발생시킬 수 있음
초기 토픽 정책은 "AWS 서비스, 클라우드 컴퓨팅 또는 기술과 관련이 없는 질문"을 거부하도록 설정되었습니다. 이는 시연을 용이하게 하고 사용자 입력의 관련성을 보장하기 위한 의도였습니다. 하지만 사용자가 "오늘의 주요 발표 사항은 무엇인가요"와 같은 질문을 했을 때, 분류기 (classifier)는 이를 차단된 토픽으로 결정해 버렸습니다. 결국 토픽 정책이 어떻게 작동하는지 보여주기 위해, 우리는 스포츠 관련 질문을 명시적으로 거부하도록 변경했습니다.

CDK 업데이트로 인해 가드레일 버전이 삭제될 수 있음
토픽 정책을 업데이트할 때 가드레일의 버전 설명 (version description)을 변경했습니다. CDK 스택이 가드레일 버전 리소스를 업데이트함에 따라, CloudFormation이 버전 1을 삭제하고 버전 2를 생성했습니다. 불행히도 버전 번호는 agentcore.json 파일에도 정의되어 있습니다. 이는 AgentCore Runtime 컨테이너 환경에 여전히 버전 1이 포함되어 있음을 의미했으며, 결과적으로 호출 시 다음과 같은 예외가 발생하며 실패했습니다: ValidationException: The guardrail identifier or version provided in the request does not exist.

결국 agentcore.json의 버전 번호를 업데이트하고, 에이전트 (agent)를 재배포한 뒤, 새로운 세션을 시작해야 하는 상황이었습니다.