Building agentic workflows with SageMaker AI and Bedrock AgentCore

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

아마존 세이지메이커 AI의 Qwen 3.5 9B와 아마존 베드록 모델을 스트랜즈 다중 에이전트로 결합해 에이전트코어에 배포하고, 누락되는 토큰 관측성을 사용자 정의 오픈텔레메트리 구간으로 보완하는 구현 안내다.

📌 핵심 요약

• 이 글은 관리형 기반 모델과 비용 최적화 또는 도메인 특화 모델을 기존 에이전트 프레임워크의 대규모 재작성 없이 함께 사용하는 구조를 제시한다.
• 단일 에이전트코어 컨테이너 안에서 Claude Haiku 4.5 기반 조정 에이전트가 요청을 분류하고, Claude Sonnet 4.6 기반 예산 에이전트 또는 Qwen 3.5 9B 기반 금융 분석 에이전트로 작업을 전달한다.
• Qwen 3.5 9B는 vLLM 딥러닝 컨테이너와 ml.g6e.2xlarge 인스턴스를 사용해 세이지메이커 실시간 엔드포인트로 배포되며, 만료되는 호출 토큰은 요청마다 새로 발급되도록 구성한다.
• 에이전트코어의 기본 계측은 베드록 모델 호출의 토큰 정보를 자동 수집하지만 스트랜즈 OpenAIModel을 통한 세이지메이커 호출에는 생성형 AI 구간과 토큰 정보가 자동으로 만들어지지 않는다.
• 세이지메이커 호출을 사용자 정의 gen_ai.chat 구간으로 감싸고 스트리밍 응답에 사용량을 포함시킨 뒤 AgentResult의 누적 사용량을 기록하면 입력·출력·전체 토큰을 추적할 수 있다.

🧩 주요 포인트

1. 오픈AI 호환 엔드포인트와 에이전트를 도구로 사용하는 패턴을 결합하면 에이전트마다 적합한 모델을 선택하면서 공통 조정 구조를 유지할 수 있다.
2. 모델 호출 호환성이 관측성의 동등성을 보장하지 않으므로, 세이지메이커 경로에는 생성형 AI 구간과 토큰 속성을 직접 추가해야 비용·지연·회귀를 분석할 수 있다.
3. vLLM 사용량 청크 활성화와 요청별 새 에이전트 생성은 각각 정확한 토큰 계측과 동시 호출 안정성을 확보하는 핵심 구현 조건이다.

🧠 상세 정리

1. 문제 정의와 통합 목표

이 글이 다루는 출발점은 관리형 기반 모델과 자체 비용 최적화 모델 또는 도메인 특화 모델을 하나의 에이전트 워크플로에서 혼합할 때 생기는 통합 부담이다. 모델마다 호출 방식이 다르다는 이유로 에이전트 프레임워크를 다시 작성하면 개발과 운영의 복잡성이 커지므로, 글은 세이지메이커 AI의 오픈AI 호환 엔드포인트를 기존 스트랜즈 에이전트 구조에 연결하는 방식을 선택한다. 전체 워크플로는 아마존 베드록 에이전트코어 런타임에 배포되며, 각 전문 에이전트가 자신의 작업에 가장 적합한 모델을 사용하면서 협업하도록 구성된다. 제시된 구조의 목표는 비용 최적화, 데이터 상주 요구 대응, 모델 선택 유연성을 하나의 운영 가능한 아키텍처 안에서 확보하는 것이다. 구현 설명은 Qwen 3.5 9B 배포, 베드록 모델과의 다중 에이전트 통합, 에이전트코어 배포뿐 아니라 기본 지원에서 빠지는 세이지메이커 토큰 관측성 보완까지 포함한다.

2. 세 에이전트의 역할과 요청 흐름

아키텍처는 단일 에이전트코어 컨테이너를 중심으로 세 가지 역할의 에이전트를 연결한다. 조정 에이전트는 베드록의 Claude Haiku 4.5와 전역 리전 간 추론을 사용해 사용자 의도를 분류하고 적절한 전문 에이전트로 요청을 전달한다. 예산 에이전트는 베드록의 Claude Sonnet 4.6을 호출해 50·30·20 예산 배분을 처리하고, 파이댄틱 기반의 구조화된 결과를 생성한다. 금융 분석 에이전트는 세이지메이커 실시간 엔드포인트에 배포된 Qwen 3.5 9B를 이용해 도구 호출 기반의 주식 분석과 포트폴리오 구성을 수행한다. 스트랜즈의 에이전트를 도구로 사용하는 패턴에 따라 조정 에이전트가 두 전문 에이전트를 도구처럼 호출하며, 처리 결과는 다시 조정 에이전트를 거쳐 사용자에게 반환된다. 다만 베드록 모델의 실제 제공 여부는 AWS 리전에 따라 달라지므로 구축 전에 대상 리전의 지원 모델을 확인해야 한다.

3. 사전 요건과 Qwen 3.5 9B 배포

구축에는 세이지메이커 AI, 베드록, 에이전트코어를 사용할 수 있는 AWS 계정과 Python 3.12 이상 환경이 필요하다. 실행 역할에는 세이지메이커 엔드포인트 호출 및 전달자 토큰 발급에 필요한 sagemaker:InvokeEndpoint와 sagemaker:CallWithBearerToken 권한이 있어야 하며, Claude Haiku 4.5와 Claude Sonnet 4.6에 대한 베드록 모델 접근 권한도 필요하다. 예제는 sagemaker-core, openai, httpx, 스트랜즈의 오픈텔레메트리 확장, yfinance, pydantic, bedrock-agentcore 패키지를 사용한다. Qwen 3.5 9B는 vLLM 0.22.1, Python 3.12, CUDA 13.0 기반 딥러닝 컨테이너와 L40S 48GB 한 장을 제공하는 ml.g6e.2xlarge 인스턴스에 배포된다. 환경 변수에는 모델 식별자, 텐서 병렬 크기 1, 최대 모델 길이 32768이 지정되고, 모델 생성 후 엔드포인트 구성과 실시간 엔드포인트를 순서대로 만든다. 컨테이너 시작 상태 확인 제한 시간은 1200초로 설정되어 대형 모델을 올리는 초기화 시간을 허용한다.

4. 자동 갱신 인증과 다중 에이전트 구현

세이지메이커의 오픈AI 호환 API는 전달자 토큰을 요구하며, 이 토큰은 만료되기 때문에 장시간 실행되는 에이전트 세션에서 고정 토큰을 사용할 수 없다. 예제는 httpx.Auth 하위 클래스를 만들고 각 요청의 인증 흐름에서 sagemaker-core의 generate_token을 호출해 Authorization 헤더를 새 토큰으로 채운다. 이 인증 객체를 사용하는 비동기 HTTP 클라이언트가 AsyncOpenAI에 전달되고, 기본 주소는 대상 세이지메이커 엔드포인트의 openai/v1 경로로 지정된다. Qwen 호출은 이 클라이언트를 받은 스트랜즈 OpenAIModel로 구성하며 온도 0.7, 최대 출력 토큰 4096, 스트리밍 사용량 포함 옵션을 설정한다. 금융 분석 도구가 호출될 때마다 Qwen 모델과 분석 도구를 포함한 새 Agent 인스턴스를 생성하고, 조정 에이전트는 예산 도구와 금융 분석 도구를 등록한 Claude Haiku 4.5 모델로 구성된다. 요청별로 새 인스턴스를 만드는 방식은 단일 에이전트 객체를 공유할 때 발생할 수 있는 동시 호출 오류를 피하기 위한 조건이다.

5. 에이전트코어 런타임 배포

완성된 다중 에이전트 애플리케이션은 bedrock-agentcore-starter-toolkit의 Runtime을 이용해 에이전트코어 런타임에 배포한다. 구성 예제는 main.py를 진입점으로 지정하고 실행 역할과 컨테이너 레지스트리를 자동 생성하며, requirements.txt를 의존성 파일로 사용한다. 배포 리전은 ap-south-1, 에이전트 이름은 personal_finance_agent로 설정되어 있으며, launch 단계에서 세이지메이커 엔드포인트 이름과 리전이 환경 변수로 전달된다. 같은 단계에서 AGENT_OBSERVABILITY_ENABLED를 true로 설정해 에이전트 관측성을 활성화한다. 이 배포 방식은 조정 에이전트와 두 전문 에이전트, 베드록 호출 경로, 세이지메이커 오픈AI 호환 호출 경로를 하나의 관리형 런타임에 담는다. 전체 배포 절차는 글에서 언급한 별도의 배포 노트북에 제시되며, 본문은 런타임 구성과 환경 변수 전달에 필요한 핵심 코드에 초점을 맞춘다.

6. 기본 계측에서 발생하는 토큰 관측성 공백

에이전트코어 런타임은 오픈텔레메트리를 통해 에이전트를 자동 계측하지만 모든 모델 제공자에 동일한 수준의 정보를 기록하지는 않는다. 베드록 모델 호출은 별도 작업 없이 생성형 AI 구간과 토큰 수가 자동으로 기록되는 반면, 스트랜즈 OpenAIModel을 거쳐 세이지메이커의 오픈AI 호환 엔드포인트를 호출하면 이에 해당하는 자동 토큰 계측이 만들어지지 않는다. 그 결과 금융 분석 에이전트가 Qwen 3.5 9B를 사용한 입력·출력 토큰이 추적 화면에서 보이지 않게 된다. 이러한 공백이 남으면 해당 모델의 비용을 모니터링하거나 사용량 회귀를 발견하고, 호출 지연의 원인을 토큰 규모와 함께 분석하기 어렵다. 원인은 스트랜즈의 오픈텔레메트리 통합이 도구 호출과 에이전트 생명주기 구간은 내보내지만 OpenAIModel 제공자에 대한 gen_ai.chat 구간과 토큰 속성을 생성하지 않는 데 있다. 또한 에이전트코어의 자동 계측은 boto3를 통한 베드록 추론 호출만 생성형 AI 작업으로 자동 인식한다.

7. 사용자 정의 구간과 토큰 사용량 추출

해결 방법은 금융 분석 에이전트 호출 전체를 사용자 정의 gen_ai.chat 오픈텔레메트리 구간으로 감싸는 것이다. 구간에는 생성형 AI 시스템이 오픈AI 호환 방식이라는 정보, 요청 모델과 세이지메이커 엔드포인트 식별 정보, 작업 종류가 채팅이라는 속성을 기록한다. Qwen 에이전트 실행이 끝나면 AgentResult.metrics.accumulated_usage에서 inputTokens, outputTokens, totalTokens 값을 읽어 각각 입력·출력·전체 토큰 속성으로 설정한다. 다만 이 누적 사용량 사전은 모델 제공자가 실제 사용량 정보를 반환한 경우에만 채워진다. vLLM은 기본 스트리밍 응답에서 사용량 청크를 보내지 않으므로 OpenAIModel 매개변수에 stream_options의 include_usage를 true로 지정해야 마지막 추가 청크에서 토큰 수를 받을 수 있다. 이 옵션을 생략하면 텍스트 생성은 정상적으로 진행되더라도 누적 사용량이 0으로 남아 사용자 정의 구간에도 모든 토큰 값이 0으로 기록된다.

8. 운영 설정과 구현상 핵심 교훈

추적 정보를 실제로 확인하려면 계정 또는 리전에서 클라우드워치 트랜잭션 검색을 활성화하고, X-Ray 추적 구간 대상과 색인 규칙을 구성해야 한다. 글은 개발 중 기본 1퍼센트 표본 추출로 대부분의 추적이 누락되는 문제를 피하기 위해 원하는 표본 비율을 100퍼센트로 설정하는 예를 제시한다. 실행 환경에는 오픈텔레메트리 확장이 포함된 스트랜즈를 설치하고 관측성 환경 변수를 활성화하며, 컨테이너 명령에는 opentelemetry-instrument를 사용해야 한다. 여기에 vLLM 사용량 포함 옵션과 사용자 정의 gen_ai.chat 구간을 함께 적용하면 예시 추적처럼 입력 1391개, 출력 1432개, 전체 2823개의 토큰과 호출 시간을 기록할 수 있다. 최종 관측성 화면에서는 세이지메이커의 Qwen 호출 구간이 자동 계측된 에이전트코어 및 베드록 구간과 함께 표시되어 양쪽 모델 경로의 토큰 정보를 비교할 수 있다. 글이 정리한 핵심 조건은 베드록 호출의 자동 계측, 세이지메이커 호출의 수동 구간 생성, vLLM 스트리밍 사용량 활성화, 누적 사용량 사전 활용, 개발 중 충분한 추적 표본, 요청별 새 에이전트 생성이다.

🧾 핵심 주장 / 시사점

• 오픈AI 호환 API는 서로 다른 모델 호스팅 경로를 같은 에이전트 인터페이스에 연결해 주지만, 호출 호환성과 텔레메트리 호환성은 별개의 문제로 다뤄야 한다.
• 토큰 계측은 사용자 정의 구간만 추가해서 완성되지 않으며, 모델 서버가 스트리밍 응답에 사용량 정보를 실제로 포함하도록 설정해야 정확한 값이 전달된다.
• 전문 에이전트별 모델 선택, 요청별 인스턴스 격리, 모델 제공자별 관측성 보완을 함께 적용해야 다중 모델 에이전트 구조를 비용·성능·동시성 측면에서 운영할 수 있다.

✅ 액션 아이템

• 단일 에이전트코어 컨테이너에서 Claude Haiku 4.5 조정 에이전트의 분류 결과를 기준으로 Claude Sonnet 4.6과 Qwen 3.5 9B 금융 분석 에이전트 전달 규칙을 정한다.
• 세이지메이커에서 Qwen 3.5 9B를 vLLM 딥러닝 컨테이너와 ml.g6e.2xlarge 기반으로 배포하고 호출 토큰을 요청마다 새로 발급되도록 점검한다.
• 에이전트코어의 기본 계측이 OpenAIModel 경로에서 누락한 생성형 AI 구간을 gen_ai.chat 구간으로 감싸고 AgentResult에 입력·출력·전체 토큰을 누적 기록해 오픈텔레메트리 추적을 정합한다.

❓ 열린 질문

• 세이지메이커 경로의 OpenAIModel 호출에서 생성형 AI 구간과 토큰 속성을 어떤 이벤트 단위로 캡처해야 비용·지연·회귀 분석이 유효한가?
• Claude Haiku 4.5 기반 조정 에이전트가 Claude Sonnet 4.6 기반 예산 에이전트와 Qwen 3.5 9B 기반 금융 분석 에이전트 중 어디로 라우팅할지 어떤 분류 기준이 필요한가?
• vLLM 사용량 청크 활성화와 요청별 새 에이전트 생성이 동일하게 적용될 때 토큰 계측 정확도와 동시 호출 안정성을 동시에 확보할 수 있는 임계값은 무엇인가?