Amazon Bedrock과 Claude Agent SDK로 서버리스 멀티 에이전트 구현하기 - Amazon Web Services

Amazon Bedrock과 Claude Agent SDK로 서버리스 멀티 에이전트 구현하기 Kiro CLI나 Claude Code 같은 AI 코딩 에이전트를 사용하다 보면, 코드를 분석하고 수정하고 테스트까지 실행하는 이 에이전트의 동작 방식을 자신의 애플리케이션 백엔드에도 적용할 수 있으면 좋겠다고 생각해 본 적이 있을 것입니다. 하나의 에이전트에게 코드 리뷰, 테스트 작성, 리팩터링을 모두 맡기면 컨텍스트가 길어지면서 앞서 발견한 문제를 뒤에서 잊어버리게 되고, 자신이 작성한 코드를 직접 리뷰하기 때문에 객관성이 떨어집니다. Anthropic의 멀티 에이전트 연구에 따르면, Claude Opus를 리드 에이전트로 두고 Claude Sonnet 서브 에이전트를 병렬 실행한 멀티 에이전트 시스템이 단일 Opus 대비 90.2% 더 높은 성능을 보였습니다. 이 게시글에서는 Claude Agent SDK를 AWS Lambda에서 실행하여 Orchestrator-Worker 패턴의 멀티 에이전트 시스템을 구현하는 방법을 소개합니다. Amazon Bedrock 네이티브 인증을 사용하므로 별도의 API 키 관리가 필요 없습니다. 솔루션 개요 이 게시글에서 구현하는 아키텍처는 Orchestrator-Worker 패턴입니다. Orchestrator Lambda가 작업을 분할하고, 전문화된 Worker Lambda (reviewer, tester, refactorer)가 각각 독립적으로 에이전트를 실행한 뒤, Opus 모델로 결과를 취합하여 정리하는 구조입니다. [그림 1] Orchestrator-Worker 멀티 에이전트 아키텍처 왜 Amazon Bedrock인가: Claude Agent SDK는 Anthropic API를 직접 호출하는 방식도 지원하지만, AWS 환경에서는 Amazon Bedrock을 통해 모델을 호출하는 것이 운영 측면에서 이점이 있습니다. Bedrock은 IAM 기반의 네이티브 인증을 제공하므로 API 키를 발급하거나 교체할 필요가 없고, Lambda 실행 역할에 권한을 부여하는 것만으로 인증이 완료됩니다. 교차 리전 추론(cross-region inference)을 통해 가용성도 높아지며, CloudWatch와의 통합으로 토큰 사용량과 지연 시간 모니터링이 기본 제공됩니다. 왜 AWS Lambda인가: 각 Worker Lambda는 독립된 실행 환경을 가지므로, 3개의 에이전트를 동시에 실행해도 각각 15분의 타임아웃을 확보할 수 있습니다. 에이전트 실행이 없을 때는 비용이 발생하지 않으며, 동시 요청이 늘어나면 자동으로 스케일링됩니다. 컨테이너 이미지 배포를 지원하므로 Claude Agent SDK와 CLI 바이너리를 Docker 이미지 하나로 패키징하여 배포할 수 있습니다. Worker 에이전트에는 Sonnet 4.6을, 최종 종합에는 Opus 4.6을 사용합니다. Sonnet 4.6은 Opus 4.6 대비 토큰당 비용이 약 40% 저렴합니다. 코드 리뷰나 테스트 작성 작업은 Sonnet으로 충분한 품질을 얻을 수 있고, 여러 에이전트의 결과에서 상충되는 의견을 판단하고 우선순위를 정하는 종합 작업에만 Opus를 사용합니다. 단계 요약 이 게시글에서는 다음 단계를 통해 멀티 에이전트 시스템을 구현합니다. - Claude Agent SDK 소개: SDK의 핵심 API와 Bedrock 인증 설정을 소개합니다. - 에이전트 정의: Skill 기반의 전문화된 에이전트(reviewer, tester, refactorer)를 정의합니다. - Worker 구현: 각 Worker Lambda에서 Claude Agent SDK로 에이전트를 실행하는 핵심 로직을 구현합니다. - Orchestrator 구현: Worker를 병렬로 호출하고 결과를 Opus로 종합하는 Orchestrator를 구현합니다. - 배포 및 실행: Docker 이미지 빌드, Lambda 배포, 테스트 실행까지 수행합니다. 사전 준비사항 이 게시글의 구현을 따라하려면 다음이 필요합니다. - AWS 계정, Amazon Bedrock에서 Claude Opus 4.6 및 Sonnet 4.6 모델 접근 권한 활성화 - AWS CLI 설치 및 구성 완료 - Docker 설치 - us-west-2 리전 사용 (Bedrock 글로벌 추론 프로필) 단계 1: Claude Agent SDK 소개 Claude Agent SDK는 Claude의 에이전트 기능을 프로그래밍 방식으로 호출할 수 있는 Python SDK입니다. MIT 라이선스로 공개되어 있으며, pip으로 설치하면 Claude CLI 바이너리가 함께 번들됩니다. 핵심 API는 query()함수와 ClaudeAgentOptions 설정 객체입니다. from claude_agent_sdk import query, ClaudeAgentOptions options = ClaudeAgentOptions( model="global.anthropic.claude-sonnet-4-6", max_turns=10, allowed_tools=["Read", "Write", "Bash"], permission_mode="bypassPermissions", cwd="/tmp/workspace", ) async for message in query(prompt="Fix the failing test", options=options): # AssistantMessage, ToolUseMessage, ResultMessage 등이 순차로 스트리밍 print(message) query()는 async generator로, 에이전트의 사고 과정과 도구 호출, 최종 결과가 메시지 단위로 스트리밍됩니다. max_turns로 에이전트의 반복 횟수를 제한하고, allowed_tools로 사용 가능한 도구를 지정합니다. system_prompt를 넣으면 에이전트의 역할을 정의할 수 있습니다. SDK를 통해 에이전트는 파일 읽기/쓰기(Read, Write, Edit), 명령어 실행(Bash), 코드 검색(Grep, Glob) 같은 빌트인 도구를 사용할 수 있습니다. 별도의 도구 통합 없이도 에이전트가 코드베이스를 탐색하고 수정하고 테스트를 실행하는 개발 루프를 수행할 수 있습니다. 여기에 더해 system_prompt에 Skill을 정의하면 에이전트에게 도메인별 전문성을 부여할 수 있습니다. 예를 들어 보안 리뷰 체크리스트나 코딩 컨벤션 규칙을 Skill로 작성하여 에이전트가 일관된 기준으로 작업하도록 설정할 수 있습니다. Amazon Bedrock을 통해 모델을 호출하려면 환경변수 하나만 설정하면 됩니다. export CLAUDE_CODE_USE_BEDROCK=1 이 환경변수를 설정하면 SDK가 AWS 자격 증명 체인(IAM 역할, 환경변수 등)을 자동으로 사용합니다. Lambda에서 실행할 때는 Lambda 실행 역할에 Bedrock 호출 권한만 부여하면 되며, API 키를 별도로 관리할 필요가 없습니다. 단계 2: 에이전트 정의 Worker 에이전트의 역할을 정의합니다. 각 에이전트는 고유한 시스템 프롬프트와 모델 설정을 가집니다. 시스템 프롬프트에 Skill을 포함하면 에이전트가 도메인별 규칙과 체크리스트에 따라 일관되게 작업합니다. # shared/config.py MODELS = { "opus": "global.anthropic.claude-opus-4-6-v1", "sonnet": "global.anthropic.claude-sonnet-4-6", } # Skill: 보안 중심 코드 리뷰 체크리스트 REVIEWER_SKILL = """You are a senior code reviewer focused on security and reliability. ## Review checklist - SQL injection: Check all database queries use parameterized inputs - Input validation: Verify user inputs are validated and sanitized - Error handling: Ensure exceptions are caught with meaningful messages - Secrets: Flag any hardcoded credentials, API keys, or connection strings - Resource cleanup: Check that opened resources (files, connections) are properly closed ## Output format For each finding: 1. Severity (CRITICAL / HIGH / MEDIUM / LOW) 2. File and line reference 3. Description of the issue 4. Recommended fix with code example """ # Skill: 엣지 케이스 중심 테스트 작성 TESTER_SKILL = """You are a QA engineer who writes thorough unit tests. ## Test strategy - Happy path: Verify expected behavior with valid inputs - Edge cases: Empty inputs, boundary values, None/null handling - Error paths: Invalid inputs, exceptions, timeout scenarios - Concurrency: Thread safety if applicable ## Conventions - Use pytest with descriptive test names (test_should_raise_when_dividing_by_zero) - Each test function should verify one behavior - Include docstrings explaining what each test validates """ BUILTIN_AGENTS = { "reviewer": { "description": "Security-focused code reviewer", "prompt": REVIEWER_SKILL