
튜토리얼
TwelveLabs 및 Strands 에이전트와 AWS AgentCore를 활용한 엔터프라이즈 비디오 분석 에이전트 구축하기

네이선 체
본 튜토리얼에서는 AWS AgentCore 및 Strands Agent를 활용하여 비디오 검색 및 분석을 위한 Twelve Labs의 Pegasus 및 Marengo 모델을 결합하고, Slack 연동을 지원하며, CloudWatch 관측성이 적용된 크로스 플랫폼 ElectronJS 데스크톱 애플리케이션으로 배포되는 엔터프라이즈급 비디오 분석 에이전트를 구축하는 과정을 단계별로 알아봅니다.
본 튜토리얼에서는 AWS AgentCore 및 Strands Agent를 활용하여 비디오 검색 및 분석을 위한 Twelve Labs의 Pegasus 및 Marengo 모델을 결합하고, Slack 연동을 지원하며, CloudWatch 관측성이 적용된 크로스 플랫폼 ElectronJS 데스크톱 애플리케이션으로 배포되는 엔터프라이즈급 비디오 분석 에이전트를 구축하는 과정을 단계별로 알아봅니다.

목차
No headings found on page
뉴스레터 구독하기
뉴스레터 구독하기
영상 이해 분야의 최신 기술 업데이트, 튜토리얼 및 인사이트를 받아보세요.
영상 이해 분야의 최신 기술 업데이트, 튜토리얼 및 인사이트를 받아보세요.
AI로 영상을 검색하고, 분석하고, 탐색하세요.
2025. 12. 28.
15분
링크 복사하기
Introduction
Zoom을 사용한 엔지니어의 일일 스탠드업 미팅부터 리크루터의 하루 중 5번째 후보자 면접까지, 일하는 직장인이라면 매일의 업무에서 미팅이 얼마나 빈번하고 중요한지 잘 알고 있습니다. 실제로 Zoom과 같은 주요 미팅 플랫폼에 따르면, 일반 직원은 연간 평균 392시간을 미팅에 소비한다고 합니다. 엄청난 양의 미팅 비디오 아카이브, 회의록, 쉽게 잊히는 할 일 목록 등으로 인해 직원들과 기업들은 생산성이 떨어지는 사후 업무와 동영상 처리에 직면하고는 합니다.
만약 1,000시간 이상에 달하는 이 비디오 콘텐츠를 손쉽게 검색하여 정확한 순간을 찾고, 미팅 내용에 대한 개인화된 답변을 찾을 수 있는 방법이 있다면 어떨까요? 그뿐만 아니라, 이러한 인사이트를 Slack과 같이 널리 쓰이는 협업 플랫폼을 통해 기업 구성원 전체에게 즉시 공유할 수 있다면 어떨까요?
TwelveLabs가 AWS Strands Agent에 공식 통합되면서 이는 더 이상 꿈이 아닙니다. 오늘 튜토리얼에서는 AWS AgentCore, TwelveLabs, 그리고 ElectronJS를 사용하여 이 기능을 직접 구현해 보겠습니다.

Application Demo
코딩을 시작하기 전에, 우리가 만들고자 하는 애플리케이션의 데모를 빠르게 살펴보겠습니다.

개인 macOS나 Windows 기기에서 직접 구동해 보고 싶으시다면, 아래 링크에서 최신 릴리스를 다운로드하거나 소스 코드를 확인해 보세요.
최신 릴리스 다운로드: https://github.com/nathanchess/twelvelabs-agentcore-demo/releases/tag/v1.0.0
GitHub 소스 코드: https://github.com/nathanchess/twelvelabs-agentcore-demo
이제 무엇을 만들지 확인했으니 본격적으로 개발을 시작해 보겠습니다! 😊
Learning Objectives
이 튜토리얼을 통해 다음을 배울 수 있습니다:
AWS Bedrock, OpenAI, Ollama 등 AWS 생태계 내 다양한 LLM 공급자를 활용해 AWS AgentCore에 프로덕션 환경에서 바로 사용 가능한 AI 에이전트를 배포합니다.
AI 에이전트가 Strands Tools 외의 외부 서비스와 연동할 수 있도록 커스텀 도구를 빌드합니다.
미리 정의된 도구들을 사용해 Slack 및 TwelveLabs와 같은 외부 도구를 AI 에이전트에 통합합니다.
AWS 생태계와 CloudWatch 등의 서비스를 활용하여 AI 에이전트에 관측 가능성(Observability)을 추가하고, 정밀한 비용 추정 및 디버그 로그 확인을 구현합니다.
ElectronJS를 사용해 크로스 플랫폼 데스크톱 애플리케이션을 직접 컴파일합니다.
Prerequisites
Node.JS 20+ 버전: Node.js — 다운로드 Node.js®
패키지 매니저(npm)가 기본 포함되어 있습니다.
TwelveLabs API 키: 인증 | TwelveLabs
Python 3.8+ 버전: Python 다운로드 | Python.org
AWS 액세스 키: Credentials - Boto3 1.40.12 문서
Slack Bot & App 토큰: https://docs.slack.dev/authentication/tokens/
두 토큰 모두 Slack API를 통해 Slack 봇을 생성할 때 자동으로 생성됩니다.
AWS 콘솔 계정 및 AgentCore, Bedrock, CloudWatch 리소스를 생성할 수 있는 권한.
Python 및 JavaScript에 대한 중급 수준의 이해.
Building the Agent with Strands Agent
Slack 봇이나 TwelveLabs의 비디오 지능형 모델 같은 기능을 연동하기 전, AI 에이전트의 밑단에 있는 원리와 메커니즘을 먼저 이해하는 것이 중요합니다. Strands Agent 문서에 따르면 AI 에이전트는 본질적으로 오케스트레이션 레이어가 결합된 LLM입니다. 이 오케스트레이션 레이어 덕분에 LLM은 정보 탐색, 데이터베이스 쿼리, 코드 실행 등 다양한 목적에 부합하는 행동을 직접 취할 수 있습니다.
💡 이 오케스트레이션 레이어 전체 과정을 에이전트 루프(Agent Loop)라고 합니다.

그림 1: 에이전트 루프 도식 (출처: AWS Strands)
💡 도구(Tool): 추론 LLM이 입력 내용과 컨텍스트를 기반으로 특정 액션에 접근하고 실행할 수 있도록 정형화된 형태의 다이렉트 함수 호출 또는 API입니다.
위 도식을 보면, 중앙에 도구 실행(Tool Execution), 도구 선택(Tool Selection), 추론(Reasoning LLM)을 포함하는 박스가 위치하고 있습니다. 각각의 단계는 다음의 핵심적인 목적을 수행합니다:
추론(Reasoning, LLM) — 주어진 입력을 분석하여 해결에 적합한 도구가 무엇인지, 혹은 도구 호출이 필요한지 판단합니다.
도구 선택(Tool Selection) — 에이전트 설정(configuration)을 바탕으로 요청된 도구를 찾습니다.
도구 실행(Tool Execution) — 도구를 실행하고 결과를 다시 추론 LLM으로 전달하여 다음 단계의 판단을 돕습니다.
여기서 이러한 프레임워크를 직접 빌드하는 것이 얼마나 복잡할지 의문이 들 수 있습니다. 추론 LLM이 도구를 식별하는 과정, 더 나아가 필요한 시점에 도구를 호출하도록 제어하는 과정은 어떻게 구현할까요? LLM이 해석할 수 있도록 각 도구의 성격을 명확히 기술하고 의미를 부여하는 방법은 무엇일까요? 이러한 까다롭고 복잡한 상세 구현 사항들을 AWS Strands Agent는 이미 완성된 형태로 기본 제공하고 있습니다.
이 글에서 모든 세부 개념을 전부 다루기는 어렵지만, Strands Agent 소스 코드를 통해 이러한 정교한 메커니즘을 심도 있게 살펴보시는 것을 강력히 추천합니다: https://github.com/strands-agents.
이 프레임워크가 있다면 단 몇 줄의 코드만으로도 에이전트를 가볍게 생성할 수 있습니다:
from bedrock_agentcore.runtime import BedrockAgentCoreApp from strands import Agent app = BedrockAgentCoreApp() agent = Agent() @app.entrypoint def invoke(payload): """사용자 입력을 처리하고 응답을 반환합니다""" user_message = payload.get("prompt", "Hello") result = agent(user_message) return {"result": result.message} if __name__ == "__main__": app.run()
이 짧은 코드만으로도 첫 번째 AI 에이전트가 완성되었습니다! 다만 아직은 추가 도구들을 부착하지 않아 일반적인 질의응답 작업 위주의 표준 LLM처럼 동작합니다.
Adding TwelveLabs to Strands Agent
좋습니다, 이제 입력과 문맥에 맞춰 질문에 답하는 수준의 동작을 충실히 수행하는 AI 에이전트가 준비되었습니다. 하지만 테스트를 직접 해볼수록 다음과 같은 한계에 부딪히게 됩니다:
비디오 데이터를 직접 처리하기 어렵고, 문자열 외의 데이터 형식을 올바르게 활용하지 못합니다.
단순 질의응답 시나리오에만 한정됩니다.
추론 LLM의 내부 사고방식이나 결정 과정을 투명하게 모니터링하기 어려워, 프로덕션 단계 에이전트의 효과적인 디버깅에 지장이 생깁니다. (실제 운영 단계에서 블랙박스 상태가 될 수 있습니다 😲)
에이전트의 역량을 전면적으로 확장하기 위해, 이제 우리의 코드에 활력을 불어넣어 줄 도구들을 투입해야 합니다. 앞서 다룬 것처럼 도구는 LLM이 직접 실행할 수 있는 독립 함수나 엔드포인트 API 형태로 구현됩니다. Strands Agent에서는 크게 두 가지 방법으로 도구를 장착할 수 있습니다.
1 - strands_tools Python 패키지가 기본 제공하는 내장 도구 활용:

그림 2: Strands Agent Tools 공식 문서
Strands Agent는 에이전트에 바로 장착해 사용할 수 있는 20가지가 넘는 풍부한 도구들을 기본 구성 요소로 제공합니다! 간단한 터미널 셸(Shell) 파일 조작 작업부터 Slack, TwelveLabs, AWS 통합까지 매우 다양한 연계 기능을 커버합니다.
이번 프로젝트에서 우리는 대표적으로 다음 도구들을 사용할 것입니다:
TwelveLabs — 강력한 비디오 지능 모델인 Pegasus 및 새로 출시된 Marengo 3.0 모델을 기반으로 핵심 비디오 추론 성능을 더해줍니다.
Slack — 구성원들과 직접 소통할 수 있도록 사내 Slack 봇 인터페이스를 실시간으로 연결합니다.
참고: Slack Bot 및 Slack App Token 자격 증명이 미리 구성되어 있어야 합니다.
Environment — 에이전트의 상태(세션)를 원활하게 관리할 수 있도록 환경 변수를 제어하는 기본 유틸리티입니다.
이 유용한 도구들을 에이전트에 결합하는 일은 에이전트를 생성하는 것만큼이나 간단하며, 아래처럼 단 몇 줄로 해결됩니다:
from strands import Agent from strands_tools import calculator, file_read, shell # 에이전트에 도구 추가 agent = Agent( tools=[calculator, file_read, shell] ) # 에이전트가 계산기 도구를 사용해야 할 타이밍을 스스로 판단합니다 agent("What is 42 ^ 9") print("\n\n") # 줄바꿈 출력 # 에이전트가 필요에 따라 셸 및 파일 읽기 도구를 호출합니다 agent("Show me the contents of a single file in this directory")
위 코드 예시처럼, strands_tools를 통해 원하는 도구를 선언적으로 가져온 후 Agent() 생성 인자에 파라미터로 함께 주입하기만 하면 완료됩니다. 정말 간단하게 에이전트가 물리적인 액션을 취할 수 있도록 능력을 대폭 업그레이드했습니다! 내부적인 실행 루프는 시스템 뒤편에서 정교하게 조율되지만, 이제 우리의 에이전트는 상황에 따라 calculator, file_read, shell 도구를 자연스럽게 선택하고 자유자재로 다룹니다.
2 - Strands Agent 기반의 선언적 커스텀 도구 직접 빌드:
이번 애플리케이션에서는 커스텀 도구를 처음부터 직접 제작할 필요는 없지만, Strands Agent가 개별 도구의 비즈니스 로직 정의뿐 아니라 LLM이 해당 도구를 완벽히 인지하고 매칭할 수 있도록 상세 메타데이터 규격을 함께 명시할 수 있는 직관적인 데코레이터 프레임워크를 갖추고 있다는 사실을 알아두면 큰 도움이 됩니다.
from strands import tool @tool def weather_forecast(city: str, days: int = 3) -> str: """지정된 도시의 날씨 예보를 조회합니다. Args: city: 도시 명칭 days: 날씨를 예보할 기간(일 수) """ return f"Weather forecast for {city} for the next {days} days..."
위 코드 스니펫에서 보듯, 이미 구축해 둔 유틸 파이썬 함수 위에 단순히 @tool 성격의 데코레이터를 붙이는 것만으로 즉석에서 완벽한 도구를 정의할 수 있습니다. 함수 하단의 docstring은 도구 추론 단계에서 의사 결정을 진행하는 Reasoning LLM에 메타데이터로 즉각 전달되어 매핑 기준 자료로 적극 활용됩니다.
방금 다룬 두 가지 핵심 접근법을 머릿속에 담아두고, 아래처럼 연동할 도구들을 우리만의 단일 에이전트에 통합해 봅시다.
import json import os import asyncio from dotenv import load_dotenv load_dotenv() from bedrock_agentcore.runtime import BedrockAgentCoreApp from strands import Agent from strands_tools import environment from custom_tools import chat_video, search_video, get_slack_channel_ids, get_video_index, slack, fetch_video_url os.environ["BYPASS_TOOL_CONSENT"] = "true" os.environ["STRANDS_SLACK_AUTO_REPLY"] = "true" os.environ["STRANDS_SLACK_LISTEN_ONLY_TAG"] = "" def get_tools(): return [slack, environment, chat_video, search_video, get_slack_channel_ids, get_video_index, fetch_video_url] app = BedrockAgentCoreApp() agent = Agent( tools=get_tools() ) # 소켓 모드가 중복 시작되는 일을 방지하기 위해 추적 상태 부여 _socket_mode_started = False @app.entrypoint async def invoke(payload): """ Electron 앱에서만 직접 들어오는 시스템 요청을 독립적으로 처리합니다. """ global _socket_mode_started system_message = payload.get("prompt") # 에이전트가 실시간 스트림 처리를 진행합니다 (소켓 상태와 무관) stream = agent.stream_async(system_message) async for event in stream: if "data" in event: yield event['data'] if __name__ == '__main__': app.run()
위 스니펫 코드에서는 strands_tools를 활용해 다음과 같이 유기적으로 연결된 도구 목록을 설정했습니다:
TwelveLabs:
chat_video,search_videoSlack:
slack,get_slack_channel_ids
💡이 도구 세트들은 개발팀이 정교하게 조율하여 배포 중인 공식 통합 도구입니다. 완성도 높고 안정성 있는 도구가 실제 에이전트 단에서 어떻게 제작되었는지 궁금하시다면 공식 Strands Tools 저장소를 꼼꼼히 뜯어보시는 것을 권장합니다.
무엇보다 뜻깊은 부분은 이렇게 완벽히 구현된 TwelveLabs 고성능 비디오 인텔리전스 시스템 덕분에, 단 한 줄의 명시적인 설정만으로도 복잡한 원본 비디오 데이터 속에서 인사이트를 끄집어내는 최고 성능의 AI 에이전트를 프로덕션 단계에 실 배포할 수 있다는 점입니다. 상세 통합 구현 과정에 대한 구체적인 배경은 공식 기술 블로그 아티클을 참고하실 수 있습니다.
Deploying on AWS AgentCore
로컬 실행 컴퓨터에서 가동되는 검증된 AI 에이전트 시스템이 가동을 마쳤습니다. 이제 이 우수하고 직관적인 도구들을 비즈니스 유저를 비롯한 끝단 사용자분들이 다이렉트로 사용할 수 있도록 원스톱 클라우드 인프라 프로덕션에 본격 업로드해야 합니다. 정말 다행인 점은, Strands Agent 인터페이스 기술 덕분에 단 한 줄의 콘솔 명령 만으로 AWS 클라우드 생태계 실배포를 모두 해결할 수 있다는 것입니다.
# AWS 클라우드로 즉시 배포합니다
이 배포 명령 스크립트가 호출됨과 동시에 다음과 같이 프로덕션 수준의 백그라운드 구동 작업들이 빠르고 매끄럽게 처리됩니다:
개발자가 구성한 전체 프로젝트는 Docker, Finch 혹은 Podman을 통해 하나의 경량 프로덕션 이미지로 완벽히 컨테이너화된 뒤, 커스텀 비즈니스 로직과 함께 클라우드 보안 환경인 AWS Elastic Container Registry(ECR)에 안전하게 업로드됩니다.

에이전트 런칭 초기 단계에 작성한 프로젝트 고유 이름에 따라 최적화된 고유한 저장소 URI가 지정되며, AWS 콘솔의 ECR 대시보드 화면에서 그 상태를 한 눈에 모니터링할 수 있습니다.
그와 동시에 필요한 라이브러리 및 하위 의존 파일들을 빈틈없이 패키징하고, 서버 포트를 열어 외부에 API 엔드포인트를 노출해 주며, 에이전트 고유 엔트리포인트를 찾아 활성화해 주는 전용 빌드 Dockerfile 구조가 자동으로 작성 및 실행됩니다.
FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim WORKDIR /app # 단일 레이어에 모든 환경 변 통합 ENV UV_SYSTEM_PYTHON=1 \ UV_COMPILE_BYTECODE=1 \ UV_NO_PROGRESS=1 \ PYTHONUNBUFFERED=1 \ DOCKER_CONTAINER=1 \ AWS_REGION=us-east-1 \ AWS_DEFAULT_REGION=us-east-1 COPY requirements.txt requirements.txt # 요구 파일 목록 기준으로 의존성 설치 RUN uv pip install -r requirements.txt # FFmpeg 인코딩 라이브러리 설치 RUN apt-get update && \ apt-get install -y ffmpeg && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* RUN uv pip install aws-opentelemetry-distro==0.12.2 # 컨테이너 호스트 바인딩 판별용 상태 지정 ENV DOCKER_CONTAINER=1 # 보안을 위한 비-루트(non-root) 시스템 유저 생성 RUN useradd -m -u 1000 bedrock_agentcore USER bedrock_agentcore EXPOSE 9000 EXPOSE 8000 EXPOSE 8080 # 현재 소스 파일 전체 영역 동기화 복사 (.dockerignore 준수) COPY . . # 컴파일 및 프레임워크 타겟 실행 시작 CMD ["opentelemetry-instrument", "python", "-m", "agent"
이 자동 생성된 Docker 파일은 보안 ECR에 최종 등재되는 핵심 명세서 역할을 수행하며, AWS AgentCore가 우리의 AI 에이전트를 실배포할 때 필요한 의존 라이브러리, 엔트리포인트 실행 구문, 개방할 통신 포트를 정확히 인지할 수 있도록 보장합니다.
AWS AgentCore는 지정 포트를 통해 ECR 내부 컨테이너를 가동하여, 준비된 AI 에이전트를 모던한 REST API 형태로 호출 가능하게 만들어 줍니다.

이 전용 관리 콘솔을 활용해 실시간 비즈니스 로그와 함께 에이전트 빌드 릴리스 버전 히스토리, 누적 런타임 클라이언트 세션, 실시간 에러 검출 추이 등 주요 핵심 지표들을 실시간으로 파악할 수 있게 되었습니다!
💡 단순한 가상 모니터링 화면으로 보일 수 있지만, 이러한 관측 가능성(Observability)은 실제 운영 가능한 완성도 높은 프로덕션 수준의 AI 시스템을 설계하는 단계에서 가장 중요한 중추적 역할을 합니다. 이러한 투명한 가시성 축적을 통해 정밀한 클라우드 예상 과금 산출이 가능해지고 내부 처리 중 중단된 에러 구간의 원인을 일목요연하게 추적해 낼 수 있어 전체 세션을 높은 품질로 보호할 수 있습니다.
더 강력하고 직관적인 디버깅 정보 축적을 위해 AgentCore 런타임 시스템은 AWS 클라우드의 대표적인 인프라 로깅 솔루션인 CloudWatch 서비스와 실시간 연동 처리됩니다.

기본 관리 화면 뒤단에 숨겨진 CloudWatch의 상세 연동 로그는 가상 환경에서 무수히 호출되는 개별 에이전트와의 질의응답 세션들에서 발생되는 원본 시스템 출력 오류 코드나 세부 트랙 정보를 빈틈없이 수집하여 보여줍니다. 덕분에 복잡한 병목 현상이 발생하더라도 장애 지점을 정밀 분석하고 안전하게 보완해 나갈 수 있습니다.
이 과정을 완료함으로써 여러분은 Strands Agent 프레임워크 기술에 모던한 TwelveLabs 및 Slack API 인터페이스를 완벽하게 통합하고 최종 퍼블릭 배포하는 과정을 멋지게 성공시켰습니다! 🎉
Agent Technical Architecture
사용자들이 만날 실제 클라이언트 레이어 화면단을 빌드하기 이전에, 왜 우리가 백엔드 통신 아키텍처를 이와 같은 방식으로 세심하게 입체화하였는지 본질적인 구조 설계 철학을 이해해 볼 필요가 있습니다. 아래 설명된 LucidChart 다이어그램 도식을 보며, 데이터 통신 흐름이 전체 파이프라인에서 어떻게 맞물려 가는지 천천히 짚어보겠습니다.

아키텍처 구조를 한 눈에 파악할 수 있듯, Strands Agent 프레임워크는 유입되는 질문을 해석하는 강력한 백엔드의 주 출입문 역할을 깔끔하게 담당해 줍니다. 이후 내장 루프는 요청에 맞는 최선의 도구를 똑똑하게 찾아 실행 단계로 넘겨주며, 우리의 에이전트는 Slack 연동, TwelveLabs 원본 비디오 가공, 그리고 비디오 전처리를 돕는 백그라운드 단의 FFmpeg 무손실 디코더까지 3가지 핵심 무기를 적재적소에 무리 없이 골라 사용합니다.
더불어 주목할 가치가 있는 탁월한 기술 결정 요인은 바로 **AgentCore 작동 구조에 AWS EC2 스팟 인스턴스(Spot Instance) 전략을 접목했다는 점**입니다. 이 저렴한 스팟 기반 클라우드 노드는 AgentCore 연계 구동 도구의 공식 기본 하드웨어로 동작하도록 세팅되어 있습니다. 그 개발 의도는 과연 무엇일까요?
💡 **새로운 기술 지평**: 스팟 형식의 클라우드 컴퓨팅 부품 노드는 AWS 클라우드 생태계 내부 전체에서 주기적으로 쓰고 남은 가용 인프라 자원을 경매 방식으로 기민하게 할당받는 형태입니다. 이 덕분에 의무적인 대규모 가상 서버 3년 약정 등 영구적인 통신 리소스를 매초 잡아먹을 필요 없이 일할 때만 켜서 임대해 쓰는 혁신적인 비용 절감 효과를 거두게 됩니다. 단발적인 질의 프롬프트가 들어왔을 때만 효율적으로 연산을 전개하는 AgentCore 특성과 최고의 효율성 궁합을 선사합니다.
이 백엔드 내부에서는 메모리 상태 공유 기술 및 heartbeat/ack POST 패킷을 이용한 정교한 실시간 연결 관리 등, 프로덕션 단계의 섬세한 유틸 디테일 요소들이 작동하고 있지만 이번 설명글에서는 지면 관계상 더 깊게 파고들지 않고 넘어가도록 하겠습니다. 이와 관련된 다이내믹한 핵심 연출 방식과 내부 설계 사상이 한결 더 깊이 궁금하시다면 해당 서비스 제품의 공식 GitHub 원본 리포지토리를 직접 방문하여 읽어보시는 것을 강력하게 권장해 드립니다.
Building Cross-Platform Desktop Application
지금까지 우리가 수립한 스마트 에이전트 뒤편의 정교한 동적 처리 루프는 물론, Strands Agent 프레임워크 핵심 통합 모듈 덕분에 TwelveLabs 비디오 인지 성능을 현대적인 신경망 에이전트 구조에 엮어내기가 얼마나 단순하고 물 흐르듯 유기적으로 직행할 수 있는지에 대해 완전히 손에 쥐게 되셨을 것으로 깊이 기대합니다.
그러한 확신을 안고, 드디어 기기 끝단 클라이언트 화면을 밝혀줄 멋진 에이전트 데스크톱 애플리케이션 코드를 입출력 프론트엔드 단에 구현할 차례입니다. 빌드에 사용되는 주춧돌 프레임워크 도구 스택은 전 세계 크로스플랫폼의 황제인 ElectronJS와 모던한 NodeJS 환경입니다. 그러므로 이 과정에 착수하시기 전 본인의 컴퓨터 개발 환경에 해당 핵심 모듈들이 정밀 설치 완료되어 정상 가동 중인지 반드시 먼저 검증하시길 당부드립니다.
우선 컴파일을 진행하기 전 프로젝트 폴더 구조를 시각적으로 가볍게 조망해 보겠습니다.


이 아티클의 집필 미션은 화려한 프론트엔드 화면 꾸미기를 넘어 AgentCore 서버 연산과 TwelveLabs 모델 인터페이스 지능 메커니즘을 통찰 깊게 설명하는 일에 초점이 맞춰져 있으므로 웹 페이지 개발 지식 자체는 생략하겠습니다. 기본적으로 ReactJS 스타일의 익숙한 웹 기술들과 매우 닿아 있습니다. 세부적으로는 직관적으로 쪼개진 강력한 모듈화 컴포넌트(Components) 구조를 탑재하고 있으며, 모든 제어 흐름과 연동 바인딩 파이프라인 처리는 핵심 구동 파일인 main.js 안에서 탄탄히 보장됩니다.

상단의 아키텍처 다이어그램은 이 아름다운 데스크톱 컴파일 프로그램이 나머지 네트워크 인터페이스 및 전체 백엔드 시스템 중 어느 위치에 명료하게 녹아들어 안착되어 있는지 똑 부러지게 나타냅니다. 골조를 축약해 드리자면, 우리는 현대식 배포 솔루션인 GitHub Actions 파이프라인 통합 설정을 적용하여 하나의 소스 코드로 macOS 및 Windows용 빌드(전용 다운로드 탭에서 만날 수 있는 설치 버전입니다)를 모두 수월하게 컴파일해 냈습니다. 또한 하둡 및 비디오 전처리를 위해 FFmpeg 도구를 탑재하여 비디오를 다각화 프로세싱합니다. 이렇게 수렴된 유저의 질문과 정보 파싱 본체는 NodeJS 채널을 지나, 비전용 AWS AgentCore 로드밸런서 엔드포인트 게이트웨이와 매칭되어 우리의 초거대 AI 인텔리전스로 정확히 소통됩니다.
이 스마트한 결정 뒤편에 도사리고 있는 아키텍처 선택과 아키텍처 통신 설계 등, 집요하고 아름답게 정돈된 비법 소스들이 낱낱이 궁금하시다면 잘 정리된 이 기고 자료에서 시원하게 그 정답을 손에 잡아 보시길 적극 추천해 드립니다.
Conclusion
진심으로 성공적인 튜토리얼 마무리를 축하드립니다! 🎉 이번 여정을 통해 여러분은 Strands Agent 프레임워크 생태계 위에서 강력한 AWS AgentCore 서버 에이전트를 조립 및 전진 배치하는 요령은 물론, 스마트 인공지능 에이전트 구조의 중심축을 흐르는 지능형 루프의 설계 비밀을 깊게 몸소 체험하셨습니다. 무엇보다 전 세계 최정상 수준의 TwelveLabs 혁신적 멀티모달 비디오 인지 기술을 여러분의 제품에 간편하게 이식해 내는 놀랍도록 간결한 개발 경로를 완전한 여러분의 지식 자산으로 만드셨습니다.
앞서 다룬 원리와 더욱 입체적이고 다양한 구현 방식을 연구하고자 하신다면 다음 훌륭한 공식 채널 리소스를 탐색해 보실 수 있습니다:
공식 배포 GitHub 소스 리포지토리: https://github.com/nathanchess/twelvelabs-agentcore-demo
백엔드 연동 기술 아키텍처 전체 맵(LucidChart): https://lucid.app/lucidchart/40b7aa79-6da6-4bed-bd63-5f34e3955685/edit?viewport_loc=424%2C-502%2C4025%2C1778%2C0_0&invitationId=inv_ba388ce0-6ad8-4f77-9ac1-c8a4edc405db
본 애플리케이션 공식 인스톨러 배포 페이지: https://github.com/nathanchess/twelvelabs-agentcore-demo/releases/tag/v1.0.0
Strands Agent 구현 전체 공식 개발 문서: https://strandsagents.com/latest/
AWS AgentCore 상세 통합 가이드 문서: https://aws.amazon.com/bedrock/agentcore/
Introduction
Zoom을 사용한 엔지니어의 일일 스탠드업 미팅부터 리크루터의 하루 중 5번째 후보자 면접까지, 일하는 직장인이라면 매일의 업무에서 미팅이 얼마나 빈번하고 중요한지 잘 알고 있습니다. 실제로 Zoom과 같은 주요 미팅 플랫폼에 따르면, 일반 직원은 연간 평균 392시간을 미팅에 소비한다고 합니다. 엄청난 양의 미팅 비디오 아카이브, 회의록, 쉽게 잊히는 할 일 목록 등으로 인해 직원들과 기업들은 생산성이 떨어지는 사후 업무와 동영상 처리에 직면하고는 합니다.
만약 1,000시간 이상에 달하는 이 비디오 콘텐츠를 손쉽게 검색하여 정확한 순간을 찾고, 미팅 내용에 대한 개인화된 답변을 찾을 수 있는 방법이 있다면 어떨까요? 그뿐만 아니라, 이러한 인사이트를 Slack과 같이 널리 쓰이는 협업 플랫폼을 통해 기업 구성원 전체에게 즉시 공유할 수 있다면 어떨까요?
TwelveLabs가 AWS Strands Agent에 공식 통합되면서 이는 더 이상 꿈이 아닙니다. 오늘 튜토리얼에서는 AWS AgentCore, TwelveLabs, 그리고 ElectronJS를 사용하여 이 기능을 직접 구현해 보겠습니다.

Application Demo
코딩을 시작하기 전에, 우리가 만들고자 하는 애플리케이션의 데모를 빠르게 살펴보겠습니다.

개인 macOS나 Windows 기기에서 직접 구동해 보고 싶으시다면, 아래 링크에서 최신 릴리스를 다운로드하거나 소스 코드를 확인해 보세요.
최신 릴리스 다운로드: https://github.com/nathanchess/twelvelabs-agentcore-demo/releases/tag/v1.0.0
GitHub 소스 코드: https://github.com/nathanchess/twelvelabs-agentcore-demo
이제 무엇을 만들지 확인했으니 본격적으로 개발을 시작해 보겠습니다! 😊
Learning Objectives
이 튜토리얼을 통해 다음을 배울 수 있습니다:
AWS Bedrock, OpenAI, Ollama 등 AWS 생태계 내 다양한 LLM 공급자를 활용해 AWS AgentCore에 프로덕션 환경에서 바로 사용 가능한 AI 에이전트를 배포합니다.
AI 에이전트가 Strands Tools 외의 외부 서비스와 연동할 수 있도록 커스텀 도구를 빌드합니다.
미리 정의된 도구들을 사용해 Slack 및 TwelveLabs와 같은 외부 도구를 AI 에이전트에 통합합니다.
AWS 생태계와 CloudWatch 등의 서비스를 활용하여 AI 에이전트에 관측 가능성(Observability)을 추가하고, 정밀한 비용 추정 및 디버그 로그 확인을 구현합니다.
ElectronJS를 사용해 크로스 플랫폼 데스크톱 애플리케이션을 직접 컴파일합니다.
Prerequisites
Node.JS 20+ 버전: Node.js — 다운로드 Node.js®
패키지 매니저(npm)가 기본 포함되어 있습니다.
TwelveLabs API 키: 인증 | TwelveLabs
Python 3.8+ 버전: Python 다운로드 | Python.org
AWS 액세스 키: Credentials - Boto3 1.40.12 문서
Slack Bot & App 토큰: https://docs.slack.dev/authentication/tokens/
두 토큰 모두 Slack API를 통해 Slack 봇을 생성할 때 자동으로 생성됩니다.
AWS 콘솔 계정 및 AgentCore, Bedrock, CloudWatch 리소스를 생성할 수 있는 권한.
Python 및 JavaScript에 대한 중급 수준의 이해.
Building the Agent with Strands Agent
Slack 봇이나 TwelveLabs의 비디오 지능형 모델 같은 기능을 연동하기 전, AI 에이전트의 밑단에 있는 원리와 메커니즘을 먼저 이해하는 것이 중요합니다. Strands Agent 문서에 따르면 AI 에이전트는 본질적으로 오케스트레이션 레이어가 결합된 LLM입니다. 이 오케스트레이션 레이어 덕분에 LLM은 정보 탐색, 데이터베이스 쿼리, 코드 실행 등 다양한 목적에 부합하는 행동을 직접 취할 수 있습니다.
💡 이 오케스트레이션 레이어 전체 과정을 에이전트 루프(Agent Loop)라고 합니다.

그림 1: 에이전트 루프 도식 (출처: AWS Strands)
💡 도구(Tool): 추론 LLM이 입력 내용과 컨텍스트를 기반으로 특정 액션에 접근하고 실행할 수 있도록 정형화된 형태의 다이렉트 함수 호출 또는 API입니다.
위 도식을 보면, 중앙에 도구 실행(Tool Execution), 도구 선택(Tool Selection), 추론(Reasoning LLM)을 포함하는 박스가 위치하고 있습니다. 각각의 단계는 다음의 핵심적인 목적을 수행합니다:
추론(Reasoning, LLM) — 주어진 입력을 분석하여 해결에 적합한 도구가 무엇인지, 혹은 도구 호출이 필요한지 판단합니다.
도구 선택(Tool Selection) — 에이전트 설정(configuration)을 바탕으로 요청된 도구를 찾습니다.
도구 실행(Tool Execution) — 도구를 실행하고 결과를 다시 추론 LLM으로 전달하여 다음 단계의 판단을 돕습니다.
여기서 이러한 프레임워크를 직접 빌드하는 것이 얼마나 복잡할지 의문이 들 수 있습니다. 추론 LLM이 도구를 식별하는 과정, 더 나아가 필요한 시점에 도구를 호출하도록 제어하는 과정은 어떻게 구현할까요? LLM이 해석할 수 있도록 각 도구의 성격을 명확히 기술하고 의미를 부여하는 방법은 무엇일까요? 이러한 까다롭고 복잡한 상세 구현 사항들을 AWS Strands Agent는 이미 완성된 형태로 기본 제공하고 있습니다.
이 글에서 모든 세부 개념을 전부 다루기는 어렵지만, Strands Agent 소스 코드를 통해 이러한 정교한 메커니즘을 심도 있게 살펴보시는 것을 강력히 추천합니다: https://github.com/strands-agents.
이 프레임워크가 있다면 단 몇 줄의 코드만으로도 에이전트를 가볍게 생성할 수 있습니다:
from bedrock_agentcore.runtime import BedrockAgentCoreApp from strands import Agent app = BedrockAgentCoreApp() agent = Agent() @app.entrypoint def invoke(payload): """사용자 입력을 처리하고 응답을 반환합니다""" user_message = payload.get("prompt", "Hello") result = agent(user_message) return {"result": result.message} if __name__ == "__main__": app.run()
이 짧은 코드만으로도 첫 번째 AI 에이전트가 완성되었습니다! 다만 아직은 추가 도구들을 부착하지 않아 일반적인 질의응답 작업 위주의 표준 LLM처럼 동작합니다.
Adding TwelveLabs to Strands Agent
좋습니다, 이제 입력과 문맥에 맞춰 질문에 답하는 수준의 동작을 충실히 수행하는 AI 에이전트가 준비되었습니다. 하지만 테스트를 직접 해볼수록 다음과 같은 한계에 부딪히게 됩니다:
비디오 데이터를 직접 처리하기 어렵고, 문자열 외의 데이터 형식을 올바르게 활용하지 못합니다.
단순 질의응답 시나리오에만 한정됩니다.
추론 LLM의 내부 사고방식이나 결정 과정을 투명하게 모니터링하기 어려워, 프로덕션 단계 에이전트의 효과적인 디버깅에 지장이 생깁니다. (실제 운영 단계에서 블랙박스 상태가 될 수 있습니다 😲)
에이전트의 역량을 전면적으로 확장하기 위해, 이제 우리의 코드에 활력을 불어넣어 줄 도구들을 투입해야 합니다. 앞서 다룬 것처럼 도구는 LLM이 직접 실행할 수 있는 독립 함수나 엔드포인트 API 형태로 구현됩니다. Strands Agent에서는 크게 두 가지 방법으로 도구를 장착할 수 있습니다.
1 - strands_tools Python 패키지가 기본 제공하는 내장 도구 활용:

그림 2: Strands Agent Tools 공식 문서
Strands Agent는 에이전트에 바로 장착해 사용할 수 있는 20가지가 넘는 풍부한 도구들을 기본 구성 요소로 제공합니다! 간단한 터미널 셸(Shell) 파일 조작 작업부터 Slack, TwelveLabs, AWS 통합까지 매우 다양한 연계 기능을 커버합니다.
이번 프로젝트에서 우리는 대표적으로 다음 도구들을 사용할 것입니다:
TwelveLabs — 강력한 비디오 지능 모델인 Pegasus 및 새로 출시된 Marengo 3.0 모델을 기반으로 핵심 비디오 추론 성능을 더해줍니다.
Slack — 구성원들과 직접 소통할 수 있도록 사내 Slack 봇 인터페이스를 실시간으로 연결합니다.
참고: Slack Bot 및 Slack App Token 자격 증명이 미리 구성되어 있어야 합니다.
Environment — 에이전트의 상태(세션)를 원활하게 관리할 수 있도록 환경 변수를 제어하는 기본 유틸리티입니다.
이 유용한 도구들을 에이전트에 결합하는 일은 에이전트를 생성하는 것만큼이나 간단하며, 아래처럼 단 몇 줄로 해결됩니다:
from strands import Agent from strands_tools import calculator, file_read, shell # 에이전트에 도구 추가 agent = Agent( tools=[calculator, file_read, shell] ) # 에이전트가 계산기 도구를 사용해야 할 타이밍을 스스로 판단합니다 agent("What is 42 ^ 9") print("\n\n") # 줄바꿈 출력 # 에이전트가 필요에 따라 셸 및 파일 읽기 도구를 호출합니다 agent("Show me the contents of a single file in this directory")
위 코드 예시처럼, strands_tools를 통해 원하는 도구를 선언적으로 가져온 후 Agent() 생성 인자에 파라미터로 함께 주입하기만 하면 완료됩니다. 정말 간단하게 에이전트가 물리적인 액션을 취할 수 있도록 능력을 대폭 업그레이드했습니다! 내부적인 실행 루프는 시스템 뒤편에서 정교하게 조율되지만, 이제 우리의 에이전트는 상황에 따라 calculator, file_read, shell 도구를 자연스럽게 선택하고 자유자재로 다룹니다.
2 - Strands Agent 기반의 선언적 커스텀 도구 직접 빌드:
이번 애플리케이션에서는 커스텀 도구를 처음부터 직접 제작할 필요는 없지만, Strands Agent가 개별 도구의 비즈니스 로직 정의뿐 아니라 LLM이 해당 도구를 완벽히 인지하고 매칭할 수 있도록 상세 메타데이터 규격을 함께 명시할 수 있는 직관적인 데코레이터 프레임워크를 갖추고 있다는 사실을 알아두면 큰 도움이 됩니다.
from strands import tool @tool def weather_forecast(city: str, days: int = 3) -> str: """지정된 도시의 날씨 예보를 조회합니다. Args: city: 도시 명칭 days: 날씨를 예보할 기간(일 수) """ return f"Weather forecast for {city} for the next {days} days..."
위 코드 스니펫에서 보듯, 이미 구축해 둔 유틸 파이썬 함수 위에 단순히 @tool 성격의 데코레이터를 붙이는 것만으로 즉석에서 완벽한 도구를 정의할 수 있습니다. 함수 하단의 docstring은 도구 추론 단계에서 의사 결정을 진행하는 Reasoning LLM에 메타데이터로 즉각 전달되어 매핑 기준 자료로 적극 활용됩니다.
방금 다룬 두 가지 핵심 접근법을 머릿속에 담아두고, 아래처럼 연동할 도구들을 우리만의 단일 에이전트에 통합해 봅시다.
import json import os import asyncio from dotenv import load_dotenv load_dotenv() from bedrock_agentcore.runtime import BedrockAgentCoreApp from strands import Agent from strands_tools import environment from custom_tools import chat_video, search_video, get_slack_channel_ids, get_video_index, slack, fetch_video_url os.environ["BYPASS_TOOL_CONSENT"] = "true" os.environ["STRANDS_SLACK_AUTO_REPLY"] = "true" os.environ["STRANDS_SLACK_LISTEN_ONLY_TAG"] = "" def get_tools(): return [slack, environment, chat_video, search_video, get_slack_channel_ids, get_video_index, fetch_video_url] app = BedrockAgentCoreApp() agent = Agent( tools=get_tools() ) # 소켓 모드가 중복 시작되는 일을 방지하기 위해 추적 상태 부여 _socket_mode_started = False @app.entrypoint async def invoke(payload): """ Electron 앱에서만 직접 들어오는 시스템 요청을 독립적으로 처리합니다. """ global _socket_mode_started system_message = payload.get("prompt") # 에이전트가 실시간 스트림 처리를 진행합니다 (소켓 상태와 무관) stream = agent.stream_async(system_message) async for event in stream: if "data" in event: yield event['data'] if __name__ == '__main__': app.run()
위 스니펫 코드에서는 strands_tools를 활용해 다음과 같이 유기적으로 연결된 도구 목록을 설정했습니다:
TwelveLabs:
chat_video,search_videoSlack:
slack,get_slack_channel_ids
💡이 도구 세트들은 개발팀이 정교하게 조율하여 배포 중인 공식 통합 도구입니다. 완성도 높고 안정성 있는 도구가 실제 에이전트 단에서 어떻게 제작되었는지 궁금하시다면 공식 Strands Tools 저장소를 꼼꼼히 뜯어보시는 것을 권장합니다.
무엇보다 뜻깊은 부분은 이렇게 완벽히 구현된 TwelveLabs 고성능 비디오 인텔리전스 시스템 덕분에, 단 한 줄의 명시적인 설정만으로도 복잡한 원본 비디오 데이터 속에서 인사이트를 끄집어내는 최고 성능의 AI 에이전트를 프로덕션 단계에 실 배포할 수 있다는 점입니다. 상세 통합 구현 과정에 대한 구체적인 배경은 공식 기술 블로그 아티클을 참고하실 수 있습니다.
Deploying on AWS AgentCore
로컬 실행 컴퓨터에서 가동되는 검증된 AI 에이전트 시스템이 가동을 마쳤습니다. 이제 이 우수하고 직관적인 도구들을 비즈니스 유저를 비롯한 끝단 사용자분들이 다이렉트로 사용할 수 있도록 원스톱 클라우드 인프라 프로덕션에 본격 업로드해야 합니다. 정말 다행인 점은, Strands Agent 인터페이스 기술 덕분에 단 한 줄의 콘솔 명령 만으로 AWS 클라우드 생태계 실배포를 모두 해결할 수 있다는 것입니다.
# AWS 클라우드로 즉시 배포합니다
이 배포 명령 스크립트가 호출됨과 동시에 다음과 같이 프로덕션 수준의 백그라운드 구동 작업들이 빠르고 매끄럽게 처리됩니다:
개발자가 구성한 전체 프로젝트는 Docker, Finch 혹은 Podman을 통해 하나의 경량 프로덕션 이미지로 완벽히 컨테이너화된 뒤, 커스텀 비즈니스 로직과 함께 클라우드 보안 환경인 AWS Elastic Container Registry(ECR)에 안전하게 업로드됩니다.

에이전트 런칭 초기 단계에 작성한 프로젝트 고유 이름에 따라 최적화된 고유한 저장소 URI가 지정되며, AWS 콘솔의 ECR 대시보드 화면에서 그 상태를 한 눈에 모니터링할 수 있습니다.
그와 동시에 필요한 라이브러리 및 하위 의존 파일들을 빈틈없이 패키징하고, 서버 포트를 열어 외부에 API 엔드포인트를 노출해 주며, 에이전트 고유 엔트리포인트를 찾아 활성화해 주는 전용 빌드 Dockerfile 구조가 자동으로 작성 및 실행됩니다.
FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim WORKDIR /app # 단일 레이어에 모든 환경 변 통합 ENV UV_SYSTEM_PYTHON=1 \ UV_COMPILE_BYTECODE=1 \ UV_NO_PROGRESS=1 \ PYTHONUNBUFFERED=1 \ DOCKER_CONTAINER=1 \ AWS_REGION=us-east-1 \ AWS_DEFAULT_REGION=us-east-1 COPY requirements.txt requirements.txt # 요구 파일 목록 기준으로 의존성 설치 RUN uv pip install -r requirements.txt # FFmpeg 인코딩 라이브러리 설치 RUN apt-get update && \ apt-get install -y ffmpeg && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* RUN uv pip install aws-opentelemetry-distro==0.12.2 # 컨테이너 호스트 바인딩 판별용 상태 지정 ENV DOCKER_CONTAINER=1 # 보안을 위한 비-루트(non-root) 시스템 유저 생성 RUN useradd -m -u 1000 bedrock_agentcore USER bedrock_agentcore EXPOSE 9000 EXPOSE 8000 EXPOSE 8080 # 현재 소스 파일 전체 영역 동기화 복사 (.dockerignore 준수) COPY . . # 컴파일 및 프레임워크 타겟 실행 시작 CMD ["opentelemetry-instrument", "python", "-m", "agent"
이 자동 생성된 Docker 파일은 보안 ECR에 최종 등재되는 핵심 명세서 역할을 수행하며, AWS AgentCore가 우리의 AI 에이전트를 실배포할 때 필요한 의존 라이브러리, 엔트리포인트 실행 구문, 개방할 통신 포트를 정확히 인지할 수 있도록 보장합니다.
AWS AgentCore는 지정 포트를 통해 ECR 내부 컨테이너를 가동하여, 준비된 AI 에이전트를 모던한 REST API 형태로 호출 가능하게 만들어 줍니다.

이 전용 관리 콘솔을 활용해 실시간 비즈니스 로그와 함께 에이전트 빌드 릴리스 버전 히스토리, 누적 런타임 클라이언트 세션, 실시간 에러 검출 추이 등 주요 핵심 지표들을 실시간으로 파악할 수 있게 되었습니다!
💡 단순한 가상 모니터링 화면으로 보일 수 있지만, 이러한 관측 가능성(Observability)은 실제 운영 가능한 완성도 높은 프로덕션 수준의 AI 시스템을 설계하는 단계에서 가장 중요한 중추적 역할을 합니다. 이러한 투명한 가시성 축적을 통해 정밀한 클라우드 예상 과금 산출이 가능해지고 내부 처리 중 중단된 에러 구간의 원인을 일목요연하게 추적해 낼 수 있어 전체 세션을 높은 품질로 보호할 수 있습니다.
더 강력하고 직관적인 디버깅 정보 축적을 위해 AgentCore 런타임 시스템은 AWS 클라우드의 대표적인 인프라 로깅 솔루션인 CloudWatch 서비스와 실시간 연동 처리됩니다.

기본 관리 화면 뒤단에 숨겨진 CloudWatch의 상세 연동 로그는 가상 환경에서 무수히 호출되는 개별 에이전트와의 질의응답 세션들에서 발생되는 원본 시스템 출력 오류 코드나 세부 트랙 정보를 빈틈없이 수집하여 보여줍니다. 덕분에 복잡한 병목 현상이 발생하더라도 장애 지점을 정밀 분석하고 안전하게 보완해 나갈 수 있습니다.
이 과정을 완료함으로써 여러분은 Strands Agent 프레임워크 기술에 모던한 TwelveLabs 및 Slack API 인터페이스를 완벽하게 통합하고 최종 퍼블릭 배포하는 과정을 멋지게 성공시켰습니다! 🎉
Agent Technical Architecture
사용자들이 만날 실제 클라이언트 레이어 화면단을 빌드하기 이전에, 왜 우리가 백엔드 통신 아키텍처를 이와 같은 방식으로 세심하게 입체화하였는지 본질적인 구조 설계 철학을 이해해 볼 필요가 있습니다. 아래 설명된 LucidChart 다이어그램 도식을 보며, 데이터 통신 흐름이 전체 파이프라인에서 어떻게 맞물려 가는지 천천히 짚어보겠습니다.

아키텍처 구조를 한 눈에 파악할 수 있듯, Strands Agent 프레임워크는 유입되는 질문을 해석하는 강력한 백엔드의 주 출입문 역할을 깔끔하게 담당해 줍니다. 이후 내장 루프는 요청에 맞는 최선의 도구를 똑똑하게 찾아 실행 단계로 넘겨주며, 우리의 에이전트는 Slack 연동, TwelveLabs 원본 비디오 가공, 그리고 비디오 전처리를 돕는 백그라운드 단의 FFmpeg 무손실 디코더까지 3가지 핵심 무기를 적재적소에 무리 없이 골라 사용합니다.
더불어 주목할 가치가 있는 탁월한 기술 결정 요인은 바로 **AgentCore 작동 구조에 AWS EC2 스팟 인스턴스(Spot Instance) 전략을 접목했다는 점**입니다. 이 저렴한 스팟 기반 클라우드 노드는 AgentCore 연계 구동 도구의 공식 기본 하드웨어로 동작하도록 세팅되어 있습니다. 그 개발 의도는 과연 무엇일까요?
💡 **새로운 기술 지평**: 스팟 형식의 클라우드 컴퓨팅 부품 노드는 AWS 클라우드 생태계 내부 전체에서 주기적으로 쓰고 남은 가용 인프라 자원을 경매 방식으로 기민하게 할당받는 형태입니다. 이 덕분에 의무적인 대규모 가상 서버 3년 약정 등 영구적인 통신 리소스를 매초 잡아먹을 필요 없이 일할 때만 켜서 임대해 쓰는 혁신적인 비용 절감 효과를 거두게 됩니다. 단발적인 질의 프롬프트가 들어왔을 때만 효율적으로 연산을 전개하는 AgentCore 특성과 최고의 효율성 궁합을 선사합니다.
이 백엔드 내부에서는 메모리 상태 공유 기술 및 heartbeat/ack POST 패킷을 이용한 정교한 실시간 연결 관리 등, 프로덕션 단계의 섬세한 유틸 디테일 요소들이 작동하고 있지만 이번 설명글에서는 지면 관계상 더 깊게 파고들지 않고 넘어가도록 하겠습니다. 이와 관련된 다이내믹한 핵심 연출 방식과 내부 설계 사상이 한결 더 깊이 궁금하시다면 해당 서비스 제품의 공식 GitHub 원본 리포지토리를 직접 방문하여 읽어보시는 것을 강력하게 권장해 드립니다.
Building Cross-Platform Desktop Application
지금까지 우리가 수립한 스마트 에이전트 뒤편의 정교한 동적 처리 루프는 물론, Strands Agent 프레임워크 핵심 통합 모듈 덕분에 TwelveLabs 비디오 인지 성능을 현대적인 신경망 에이전트 구조에 엮어내기가 얼마나 단순하고 물 흐르듯 유기적으로 직행할 수 있는지에 대해 완전히 손에 쥐게 되셨을 것으로 깊이 기대합니다.
그러한 확신을 안고, 드디어 기기 끝단 클라이언트 화면을 밝혀줄 멋진 에이전트 데스크톱 애플리케이션 코드를 입출력 프론트엔드 단에 구현할 차례입니다. 빌드에 사용되는 주춧돌 프레임워크 도구 스택은 전 세계 크로스플랫폼의 황제인 ElectronJS와 모던한 NodeJS 환경입니다. 그러므로 이 과정에 착수하시기 전 본인의 컴퓨터 개발 환경에 해당 핵심 모듈들이 정밀 설치 완료되어 정상 가동 중인지 반드시 먼저 검증하시길 당부드립니다.
우선 컴파일을 진행하기 전 프로젝트 폴더 구조를 시각적으로 가볍게 조망해 보겠습니다.


이 아티클의 집필 미션은 화려한 프론트엔드 화면 꾸미기를 넘어 AgentCore 서버 연산과 TwelveLabs 모델 인터페이스 지능 메커니즘을 통찰 깊게 설명하는 일에 초점이 맞춰져 있으므로 웹 페이지 개발 지식 자체는 생략하겠습니다. 기본적으로 ReactJS 스타일의 익숙한 웹 기술들과 매우 닿아 있습니다. 세부적으로는 직관적으로 쪼개진 강력한 모듈화 컴포넌트(Components) 구조를 탑재하고 있으며, 모든 제어 흐름과 연동 바인딩 파이프라인 처리는 핵심 구동 파일인 main.js 안에서 탄탄히 보장됩니다.

상단의 아키텍처 다이어그램은 이 아름다운 데스크톱 컴파일 프로그램이 나머지 네트워크 인터페이스 및 전체 백엔드 시스템 중 어느 위치에 명료하게 녹아들어 안착되어 있는지 똑 부러지게 나타냅니다. 골조를 축약해 드리자면, 우리는 현대식 배포 솔루션인 GitHub Actions 파이프라인 통합 설정을 적용하여 하나의 소스 코드로 macOS 및 Windows용 빌드(전용 다운로드 탭에서 만날 수 있는 설치 버전입니다)를 모두 수월하게 컴파일해 냈습니다. 또한 하둡 및 비디오 전처리를 위해 FFmpeg 도구를 탑재하여 비디오를 다각화 프로세싱합니다. 이렇게 수렴된 유저의 질문과 정보 파싱 본체는 NodeJS 채널을 지나, 비전용 AWS AgentCore 로드밸런서 엔드포인트 게이트웨이와 매칭되어 우리의 초거대 AI 인텔리전스로 정확히 소통됩니다.
이 스마트한 결정 뒤편에 도사리고 있는 아키텍처 선택과 아키텍처 통신 설계 등, 집요하고 아름답게 정돈된 비법 소스들이 낱낱이 궁금하시다면 잘 정리된 이 기고 자료에서 시원하게 그 정답을 손에 잡아 보시길 적극 추천해 드립니다.
Conclusion
진심으로 성공적인 튜토리얼 마무리를 축하드립니다! 🎉 이번 여정을 통해 여러분은 Strands Agent 프레임워크 생태계 위에서 강력한 AWS AgentCore 서버 에이전트를 조립 및 전진 배치하는 요령은 물론, 스마트 인공지능 에이전트 구조의 중심축을 흐르는 지능형 루프의 설계 비밀을 깊게 몸소 체험하셨습니다. 무엇보다 전 세계 최정상 수준의 TwelveLabs 혁신적 멀티모달 비디오 인지 기술을 여러분의 제품에 간편하게 이식해 내는 놀랍도록 간결한 개발 경로를 완전한 여러분의 지식 자산으로 만드셨습니다.
앞서 다룬 원리와 더욱 입체적이고 다양한 구현 방식을 연구하고자 하신다면 다음 훌륭한 공식 채널 리소스를 탐색해 보실 수 있습니다:
공식 배포 GitHub 소스 리포지토리: https://github.com/nathanchess/twelvelabs-agentcore-demo
백엔드 연동 기술 아키텍처 전체 맵(LucidChart): https://lucid.app/lucidchart/40b7aa79-6da6-4bed-bd63-5f34e3955685/edit?viewport_loc=424%2C-502%2C4025%2C1778%2C0_0&invitationId=inv_ba388ce0-6ad8-4f77-9ac1-c8a4edc405db
본 애플리케이션 공식 인스톨러 배포 페이지: https://github.com/nathanchess/twelvelabs-agentcore-demo/releases/tag/v1.0.0
Strands Agent 구현 전체 공식 개발 문서: https://strandsagents.com/latest/
AWS AgentCore 상세 통합 가이드 문서: https://aws.amazon.com/bedrock/agentcore/
Introduction
Zoom을 사용한 엔지니어의 일일 스탠드업 미팅부터 리크루터의 하루 중 5번째 후보자 면접까지, 일하는 직장인이라면 매일의 업무에서 미팅이 얼마나 빈번하고 중요한지 잘 알고 있습니다. 실제로 Zoom과 같은 주요 미팅 플랫폼에 따르면, 일반 직원은 연간 평균 392시간을 미팅에 소비한다고 합니다. 엄청난 양의 미팅 비디오 아카이브, 회의록, 쉽게 잊히는 할 일 목록 등으로 인해 직원들과 기업들은 생산성이 떨어지는 사후 업무와 동영상 처리에 직면하고는 합니다.
만약 1,000시간 이상에 달하는 이 비디오 콘텐츠를 손쉽게 검색하여 정확한 순간을 찾고, 미팅 내용에 대한 개인화된 답변을 찾을 수 있는 방법이 있다면 어떨까요? 그뿐만 아니라, 이러한 인사이트를 Slack과 같이 널리 쓰이는 협업 플랫폼을 통해 기업 구성원 전체에게 즉시 공유할 수 있다면 어떨까요?
TwelveLabs가 AWS Strands Agent에 공식 통합되면서 이는 더 이상 꿈이 아닙니다. 오늘 튜토리얼에서는 AWS AgentCore, TwelveLabs, 그리고 ElectronJS를 사용하여 이 기능을 직접 구현해 보겠습니다.

Application Demo
코딩을 시작하기 전에, 우리가 만들고자 하는 애플리케이션의 데모를 빠르게 살펴보겠습니다.

개인 macOS나 Windows 기기에서 직접 구동해 보고 싶으시다면, 아래 링크에서 최신 릴리스를 다운로드하거나 소스 코드를 확인해 보세요.
최신 릴리스 다운로드: https://github.com/nathanchess/twelvelabs-agentcore-demo/releases/tag/v1.0.0
GitHub 소스 코드: https://github.com/nathanchess/twelvelabs-agentcore-demo
이제 무엇을 만들지 확인했으니 본격적으로 개발을 시작해 보겠습니다! 😊
Learning Objectives
이 튜토리얼을 통해 다음을 배울 수 있습니다:
AWS Bedrock, OpenAI, Ollama 등 AWS 생태계 내 다양한 LLM 공급자를 활용해 AWS AgentCore에 프로덕션 환경에서 바로 사용 가능한 AI 에이전트를 배포합니다.
AI 에이전트가 Strands Tools 외의 외부 서비스와 연동할 수 있도록 커스텀 도구를 빌드합니다.
미리 정의된 도구들을 사용해 Slack 및 TwelveLabs와 같은 외부 도구를 AI 에이전트에 통합합니다.
AWS 생태계와 CloudWatch 등의 서비스를 활용하여 AI 에이전트에 관측 가능성(Observability)을 추가하고, 정밀한 비용 추정 및 디버그 로그 확인을 구현합니다.
ElectronJS를 사용해 크로스 플랫폼 데스크톱 애플리케이션을 직접 컴파일합니다.
Prerequisites
Node.JS 20+ 버전: Node.js — 다운로드 Node.js®
패키지 매니저(npm)가 기본 포함되어 있습니다.
TwelveLabs API 키: 인증 | TwelveLabs
Python 3.8+ 버전: Python 다운로드 | Python.org
AWS 액세스 키: Credentials - Boto3 1.40.12 문서
Slack Bot & App 토큰: https://docs.slack.dev/authentication/tokens/
두 토큰 모두 Slack API를 통해 Slack 봇을 생성할 때 자동으로 생성됩니다.
AWS 콘솔 계정 및 AgentCore, Bedrock, CloudWatch 리소스를 생성할 수 있는 권한.
Python 및 JavaScript에 대한 중급 수준의 이해.
Building the Agent with Strands Agent
Slack 봇이나 TwelveLabs의 비디오 지능형 모델 같은 기능을 연동하기 전, AI 에이전트의 밑단에 있는 원리와 메커니즘을 먼저 이해하는 것이 중요합니다. Strands Agent 문서에 따르면 AI 에이전트는 본질적으로 오케스트레이션 레이어가 결합된 LLM입니다. 이 오케스트레이션 레이어 덕분에 LLM은 정보 탐색, 데이터베이스 쿼리, 코드 실행 등 다양한 목적에 부합하는 행동을 직접 취할 수 있습니다.
💡 이 오케스트레이션 레이어 전체 과정을 에이전트 루프(Agent Loop)라고 합니다.

그림 1: 에이전트 루프 도식 (출처: AWS Strands)
💡 도구(Tool): 추론 LLM이 입력 내용과 컨텍스트를 기반으로 특정 액션에 접근하고 실행할 수 있도록 정형화된 형태의 다이렉트 함수 호출 또는 API입니다.
위 도식을 보면, 중앙에 도구 실행(Tool Execution), 도구 선택(Tool Selection), 추론(Reasoning LLM)을 포함하는 박스가 위치하고 있습니다. 각각의 단계는 다음의 핵심적인 목적을 수행합니다:
추론(Reasoning, LLM) — 주어진 입력을 분석하여 해결에 적합한 도구가 무엇인지, 혹은 도구 호출이 필요한지 판단합니다.
도구 선택(Tool Selection) — 에이전트 설정(configuration)을 바탕으로 요청된 도구를 찾습니다.
도구 실행(Tool Execution) — 도구를 실행하고 결과를 다시 추론 LLM으로 전달하여 다음 단계의 판단을 돕습니다.
여기서 이러한 프레임워크를 직접 빌드하는 것이 얼마나 복잡할지 의문이 들 수 있습니다. 추론 LLM이 도구를 식별하는 과정, 더 나아가 필요한 시점에 도구를 호출하도록 제어하는 과정은 어떻게 구현할까요? LLM이 해석할 수 있도록 각 도구의 성격을 명확히 기술하고 의미를 부여하는 방법은 무엇일까요? 이러한 까다롭고 복잡한 상세 구현 사항들을 AWS Strands Agent는 이미 완성된 형태로 기본 제공하고 있습니다.
이 글에서 모든 세부 개념을 전부 다루기는 어렵지만, Strands Agent 소스 코드를 통해 이러한 정교한 메커니즘을 심도 있게 살펴보시는 것을 강력히 추천합니다: https://github.com/strands-agents.
이 프레임워크가 있다면 단 몇 줄의 코드만으로도 에이전트를 가볍게 생성할 수 있습니다:
from bedrock_agentcore.runtime import BedrockAgentCoreApp from strands import Agent app = BedrockAgentCoreApp() agent = Agent() @app.entrypoint def invoke(payload): """사용자 입력을 처리하고 응답을 반환합니다""" user_message = payload.get("prompt", "Hello") result = agent(user_message) return {"result": result.message} if __name__ == "__main__": app.run()
이 짧은 코드만으로도 첫 번째 AI 에이전트가 완성되었습니다! 다만 아직은 추가 도구들을 부착하지 않아 일반적인 질의응답 작업 위주의 표준 LLM처럼 동작합니다.
Adding TwelveLabs to Strands Agent
좋습니다, 이제 입력과 문맥에 맞춰 질문에 답하는 수준의 동작을 충실히 수행하는 AI 에이전트가 준비되었습니다. 하지만 테스트를 직접 해볼수록 다음과 같은 한계에 부딪히게 됩니다:
비디오 데이터를 직접 처리하기 어렵고, 문자열 외의 데이터 형식을 올바르게 활용하지 못합니다.
단순 질의응답 시나리오에만 한정됩니다.
추론 LLM의 내부 사고방식이나 결정 과정을 투명하게 모니터링하기 어려워, 프로덕션 단계 에이전트의 효과적인 디버깅에 지장이 생깁니다. (실제 운영 단계에서 블랙박스 상태가 될 수 있습니다 😲)
에이전트의 역량을 전면적으로 확장하기 위해, 이제 우리의 코드에 활력을 불어넣어 줄 도구들을 투입해야 합니다. 앞서 다룬 것처럼 도구는 LLM이 직접 실행할 수 있는 독립 함수나 엔드포인트 API 형태로 구현됩니다. Strands Agent에서는 크게 두 가지 방법으로 도구를 장착할 수 있습니다.
1 - strands_tools Python 패키지가 기본 제공하는 내장 도구 활용:

그림 2: Strands Agent Tools 공식 문서
Strands Agent는 에이전트에 바로 장착해 사용할 수 있는 20가지가 넘는 풍부한 도구들을 기본 구성 요소로 제공합니다! 간단한 터미널 셸(Shell) 파일 조작 작업부터 Slack, TwelveLabs, AWS 통합까지 매우 다양한 연계 기능을 커버합니다.
이번 프로젝트에서 우리는 대표적으로 다음 도구들을 사용할 것입니다:
TwelveLabs — 강력한 비디오 지능 모델인 Pegasus 및 새로 출시된 Marengo 3.0 모델을 기반으로 핵심 비디오 추론 성능을 더해줍니다.
Slack — 구성원들과 직접 소통할 수 있도록 사내 Slack 봇 인터페이스를 실시간으로 연결합니다.
참고: Slack Bot 및 Slack App Token 자격 증명이 미리 구성되어 있어야 합니다.
Environment — 에이전트의 상태(세션)를 원활하게 관리할 수 있도록 환경 변수를 제어하는 기본 유틸리티입니다.
이 유용한 도구들을 에이전트에 결합하는 일은 에이전트를 생성하는 것만큼이나 간단하며, 아래처럼 단 몇 줄로 해결됩니다:
from strands import Agent from strands_tools import calculator, file_read, shell # 에이전트에 도구 추가 agent = Agent( tools=[calculator, file_read, shell] ) # 에이전트가 계산기 도구를 사용해야 할 타이밍을 스스로 판단합니다 agent("What is 42 ^ 9") print("\n\n") # 줄바꿈 출력 # 에이전트가 필요에 따라 셸 및 파일 읽기 도구를 호출합니다 agent("Show me the contents of a single file in this directory")
위 코드 예시처럼, strands_tools를 통해 원하는 도구를 선언적으로 가져온 후 Agent() 생성 인자에 파라미터로 함께 주입하기만 하면 완료됩니다. 정말 간단하게 에이전트가 물리적인 액션을 취할 수 있도록 능력을 대폭 업그레이드했습니다! 내부적인 실행 루프는 시스템 뒤편에서 정교하게 조율되지만, 이제 우리의 에이전트는 상황에 따라 calculator, file_read, shell 도구를 자연스럽게 선택하고 자유자재로 다룹니다.
2 - Strands Agent 기반의 선언적 커스텀 도구 직접 빌드:
이번 애플리케이션에서는 커스텀 도구를 처음부터 직접 제작할 필요는 없지만, Strands Agent가 개별 도구의 비즈니스 로직 정의뿐 아니라 LLM이 해당 도구를 완벽히 인지하고 매칭할 수 있도록 상세 메타데이터 규격을 함께 명시할 수 있는 직관적인 데코레이터 프레임워크를 갖추고 있다는 사실을 알아두면 큰 도움이 됩니다.
from strands import tool @tool def weather_forecast(city: str, days: int = 3) -> str: """지정된 도시의 날씨 예보를 조회합니다. Args: city: 도시 명칭 days: 날씨를 예보할 기간(일 수) """ return f"Weather forecast for {city} for the next {days} days..."
위 코드 스니펫에서 보듯, 이미 구축해 둔 유틸 파이썬 함수 위에 단순히 @tool 성격의 데코레이터를 붙이는 것만으로 즉석에서 완벽한 도구를 정의할 수 있습니다. 함수 하단의 docstring은 도구 추론 단계에서 의사 결정을 진행하는 Reasoning LLM에 메타데이터로 즉각 전달되어 매핑 기준 자료로 적극 활용됩니다.
방금 다룬 두 가지 핵심 접근법을 머릿속에 담아두고, 아래처럼 연동할 도구들을 우리만의 단일 에이전트에 통합해 봅시다.
import json import os import asyncio from dotenv import load_dotenv load_dotenv() from bedrock_agentcore.runtime import BedrockAgentCoreApp from strands import Agent from strands_tools import environment from custom_tools import chat_video, search_video, get_slack_channel_ids, get_video_index, slack, fetch_video_url os.environ["BYPASS_TOOL_CONSENT"] = "true" os.environ["STRANDS_SLACK_AUTO_REPLY"] = "true" os.environ["STRANDS_SLACK_LISTEN_ONLY_TAG"] = "" def get_tools(): return [slack, environment, chat_video, search_video, get_slack_channel_ids, get_video_index, fetch_video_url] app = BedrockAgentCoreApp() agent = Agent( tools=get_tools() ) # 소켓 모드가 중복 시작되는 일을 방지하기 위해 추적 상태 부여 _socket_mode_started = False @app.entrypoint async def invoke(payload): """ Electron 앱에서만 직접 들어오는 시스템 요청을 독립적으로 처리합니다. """ global _socket_mode_started system_message = payload.get("prompt") # 에이전트가 실시간 스트림 처리를 진행합니다 (소켓 상태와 무관) stream = agent.stream_async(system_message) async for event in stream: if "data" in event: yield event['data'] if __name__ == '__main__': app.run()
위 스니펫 코드에서는 strands_tools를 활용해 다음과 같이 유기적으로 연결된 도구 목록을 설정했습니다:
TwelveLabs:
chat_video,search_videoSlack:
slack,get_slack_channel_ids
💡이 도구 세트들은 개발팀이 정교하게 조율하여 배포 중인 공식 통합 도구입니다. 완성도 높고 안정성 있는 도구가 실제 에이전트 단에서 어떻게 제작되었는지 궁금하시다면 공식 Strands Tools 저장소를 꼼꼼히 뜯어보시는 것을 권장합니다.
무엇보다 뜻깊은 부분은 이렇게 완벽히 구현된 TwelveLabs 고성능 비디오 인텔리전스 시스템 덕분에, 단 한 줄의 명시적인 설정만으로도 복잡한 원본 비디오 데이터 속에서 인사이트를 끄집어내는 최고 성능의 AI 에이전트를 프로덕션 단계에 실 배포할 수 있다는 점입니다. 상세 통합 구현 과정에 대한 구체적인 배경은 공식 기술 블로그 아티클을 참고하실 수 있습니다.
Deploying on AWS AgentCore
로컬 실행 컴퓨터에서 가동되는 검증된 AI 에이전트 시스템이 가동을 마쳤습니다. 이제 이 우수하고 직관적인 도구들을 비즈니스 유저를 비롯한 끝단 사용자분들이 다이렉트로 사용할 수 있도록 원스톱 클라우드 인프라 프로덕션에 본격 업로드해야 합니다. 정말 다행인 점은, Strands Agent 인터페이스 기술 덕분에 단 한 줄의 콘솔 명령 만으로 AWS 클라우드 생태계 실배포를 모두 해결할 수 있다는 것입니다.
# AWS 클라우드로 즉시 배포합니다
이 배포 명령 스크립트가 호출됨과 동시에 다음과 같이 프로덕션 수준의 백그라운드 구동 작업들이 빠르고 매끄럽게 처리됩니다:
개발자가 구성한 전체 프로젝트는 Docker, Finch 혹은 Podman을 통해 하나의 경량 프로덕션 이미지로 완벽히 컨테이너화된 뒤, 커스텀 비즈니스 로직과 함께 클라우드 보안 환경인 AWS Elastic Container Registry(ECR)에 안전하게 업로드됩니다.

에이전트 런칭 초기 단계에 작성한 프로젝트 고유 이름에 따라 최적화된 고유한 저장소 URI가 지정되며, AWS 콘솔의 ECR 대시보드 화면에서 그 상태를 한 눈에 모니터링할 수 있습니다.
그와 동시에 필요한 라이브러리 및 하위 의존 파일들을 빈틈없이 패키징하고, 서버 포트를 열어 외부에 API 엔드포인트를 노출해 주며, 에이전트 고유 엔트리포인트를 찾아 활성화해 주는 전용 빌드 Dockerfile 구조가 자동으로 작성 및 실행됩니다.
FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim WORKDIR /app # 단일 레이어에 모든 환경 변 통합 ENV UV_SYSTEM_PYTHON=1 \ UV_COMPILE_BYTECODE=1 \ UV_NO_PROGRESS=1 \ PYTHONUNBUFFERED=1 \ DOCKER_CONTAINER=1 \ AWS_REGION=us-east-1 \ AWS_DEFAULT_REGION=us-east-1 COPY requirements.txt requirements.txt # 요구 파일 목록 기준으로 의존성 설치 RUN uv pip install -r requirements.txt # FFmpeg 인코딩 라이브러리 설치 RUN apt-get update && \ apt-get install -y ffmpeg && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* RUN uv pip install aws-opentelemetry-distro==0.12.2 # 컨테이너 호스트 바인딩 판별용 상태 지정 ENV DOCKER_CONTAINER=1 # 보안을 위한 비-루트(non-root) 시스템 유저 생성 RUN useradd -m -u 1000 bedrock_agentcore USER bedrock_agentcore EXPOSE 9000 EXPOSE 8000 EXPOSE 8080 # 현재 소스 파일 전체 영역 동기화 복사 (.dockerignore 준수) COPY . . # 컴파일 및 프레임워크 타겟 실행 시작 CMD ["opentelemetry-instrument", "python", "-m", "agent"
이 자동 생성된 Docker 파일은 보안 ECR에 최종 등재되는 핵심 명세서 역할을 수행하며, AWS AgentCore가 우리의 AI 에이전트를 실배포할 때 필요한 의존 라이브러리, 엔트리포인트 실행 구문, 개방할 통신 포트를 정확히 인지할 수 있도록 보장합니다.
AWS AgentCore는 지정 포트를 통해 ECR 내부 컨테이너를 가동하여, 준비된 AI 에이전트를 모던한 REST API 형태로 호출 가능하게 만들어 줍니다.

이 전용 관리 콘솔을 활용해 실시간 비즈니스 로그와 함께 에이전트 빌드 릴리스 버전 히스토리, 누적 런타임 클라이언트 세션, 실시간 에러 검출 추이 등 주요 핵심 지표들을 실시간으로 파악할 수 있게 되었습니다!
💡 단순한 가상 모니터링 화면으로 보일 수 있지만, 이러한 관측 가능성(Observability)은 실제 운영 가능한 완성도 높은 프로덕션 수준의 AI 시스템을 설계하는 단계에서 가장 중요한 중추적 역할을 합니다. 이러한 투명한 가시성 축적을 통해 정밀한 클라우드 예상 과금 산출이 가능해지고 내부 처리 중 중단된 에러 구간의 원인을 일목요연하게 추적해 낼 수 있어 전체 세션을 높은 품질로 보호할 수 있습니다.
더 강력하고 직관적인 디버깅 정보 축적을 위해 AgentCore 런타임 시스템은 AWS 클라우드의 대표적인 인프라 로깅 솔루션인 CloudWatch 서비스와 실시간 연동 처리됩니다.

기본 관리 화면 뒤단에 숨겨진 CloudWatch의 상세 연동 로그는 가상 환경에서 무수히 호출되는 개별 에이전트와의 질의응답 세션들에서 발생되는 원본 시스템 출력 오류 코드나 세부 트랙 정보를 빈틈없이 수집하여 보여줍니다. 덕분에 복잡한 병목 현상이 발생하더라도 장애 지점을 정밀 분석하고 안전하게 보완해 나갈 수 있습니다.
이 과정을 완료함으로써 여러분은 Strands Agent 프레임워크 기술에 모던한 TwelveLabs 및 Slack API 인터페이스를 완벽하게 통합하고 최종 퍼블릭 배포하는 과정을 멋지게 성공시켰습니다! 🎉
Agent Technical Architecture
사용자들이 만날 실제 클라이언트 레이어 화면단을 빌드하기 이전에, 왜 우리가 백엔드 통신 아키텍처를 이와 같은 방식으로 세심하게 입체화하였는지 본질적인 구조 설계 철학을 이해해 볼 필요가 있습니다. 아래 설명된 LucidChart 다이어그램 도식을 보며, 데이터 통신 흐름이 전체 파이프라인에서 어떻게 맞물려 가는지 천천히 짚어보겠습니다.

아키텍처 구조를 한 눈에 파악할 수 있듯, Strands Agent 프레임워크는 유입되는 질문을 해석하는 강력한 백엔드의 주 출입문 역할을 깔끔하게 담당해 줍니다. 이후 내장 루프는 요청에 맞는 최선의 도구를 똑똑하게 찾아 실행 단계로 넘겨주며, 우리의 에이전트는 Slack 연동, TwelveLabs 원본 비디오 가공, 그리고 비디오 전처리를 돕는 백그라운드 단의 FFmpeg 무손실 디코더까지 3가지 핵심 무기를 적재적소에 무리 없이 골라 사용합니다.
더불어 주목할 가치가 있는 탁월한 기술 결정 요인은 바로 **AgentCore 작동 구조에 AWS EC2 스팟 인스턴스(Spot Instance) 전략을 접목했다는 점**입니다. 이 저렴한 스팟 기반 클라우드 노드는 AgentCore 연계 구동 도구의 공식 기본 하드웨어로 동작하도록 세팅되어 있습니다. 그 개발 의도는 과연 무엇일까요?
💡 **새로운 기술 지평**: 스팟 형식의 클라우드 컴퓨팅 부품 노드는 AWS 클라우드 생태계 내부 전체에서 주기적으로 쓰고 남은 가용 인프라 자원을 경매 방식으로 기민하게 할당받는 형태입니다. 이 덕분에 의무적인 대규모 가상 서버 3년 약정 등 영구적인 통신 리소스를 매초 잡아먹을 필요 없이 일할 때만 켜서 임대해 쓰는 혁신적인 비용 절감 효과를 거두게 됩니다. 단발적인 질의 프롬프트가 들어왔을 때만 효율적으로 연산을 전개하는 AgentCore 특성과 최고의 효율성 궁합을 선사합니다.
이 백엔드 내부에서는 메모리 상태 공유 기술 및 heartbeat/ack POST 패킷을 이용한 정교한 실시간 연결 관리 등, 프로덕션 단계의 섬세한 유틸 디테일 요소들이 작동하고 있지만 이번 설명글에서는 지면 관계상 더 깊게 파고들지 않고 넘어가도록 하겠습니다. 이와 관련된 다이내믹한 핵심 연출 방식과 내부 설계 사상이 한결 더 깊이 궁금하시다면 해당 서비스 제품의 공식 GitHub 원본 리포지토리를 직접 방문하여 읽어보시는 것을 강력하게 권장해 드립니다.
Building Cross-Platform Desktop Application
지금까지 우리가 수립한 스마트 에이전트 뒤편의 정교한 동적 처리 루프는 물론, Strands Agent 프레임워크 핵심 통합 모듈 덕분에 TwelveLabs 비디오 인지 성능을 현대적인 신경망 에이전트 구조에 엮어내기가 얼마나 단순하고 물 흐르듯 유기적으로 직행할 수 있는지에 대해 완전히 손에 쥐게 되셨을 것으로 깊이 기대합니다.
그러한 확신을 안고, 드디어 기기 끝단 클라이언트 화면을 밝혀줄 멋진 에이전트 데스크톱 애플리케이션 코드를 입출력 프론트엔드 단에 구현할 차례입니다. 빌드에 사용되는 주춧돌 프레임워크 도구 스택은 전 세계 크로스플랫폼의 황제인 ElectronJS와 모던한 NodeJS 환경입니다. 그러므로 이 과정에 착수하시기 전 본인의 컴퓨터 개발 환경에 해당 핵심 모듈들이 정밀 설치 완료되어 정상 가동 중인지 반드시 먼저 검증하시길 당부드립니다.
우선 컴파일을 진행하기 전 프로젝트 폴더 구조를 시각적으로 가볍게 조망해 보겠습니다.


이 아티클의 집필 미션은 화려한 프론트엔드 화면 꾸미기를 넘어 AgentCore 서버 연산과 TwelveLabs 모델 인터페이스 지능 메커니즘을 통찰 깊게 설명하는 일에 초점이 맞춰져 있으므로 웹 페이지 개발 지식 자체는 생략하겠습니다. 기본적으로 ReactJS 스타일의 익숙한 웹 기술들과 매우 닿아 있습니다. 세부적으로는 직관적으로 쪼개진 강력한 모듈화 컴포넌트(Components) 구조를 탑재하고 있으며, 모든 제어 흐름과 연동 바인딩 파이프라인 처리는 핵심 구동 파일인 main.js 안에서 탄탄히 보장됩니다.

상단의 아키텍처 다이어그램은 이 아름다운 데스크톱 컴파일 프로그램이 나머지 네트워크 인터페이스 및 전체 백엔드 시스템 중 어느 위치에 명료하게 녹아들어 안착되어 있는지 똑 부러지게 나타냅니다. 골조를 축약해 드리자면, 우리는 현대식 배포 솔루션인 GitHub Actions 파이프라인 통합 설정을 적용하여 하나의 소스 코드로 macOS 및 Windows용 빌드(전용 다운로드 탭에서 만날 수 있는 설치 버전입니다)를 모두 수월하게 컴파일해 냈습니다. 또한 하둡 및 비디오 전처리를 위해 FFmpeg 도구를 탑재하여 비디오를 다각화 프로세싱합니다. 이렇게 수렴된 유저의 질문과 정보 파싱 본체는 NodeJS 채널을 지나, 비전용 AWS AgentCore 로드밸런서 엔드포인트 게이트웨이와 매칭되어 우리의 초거대 AI 인텔리전스로 정확히 소통됩니다.
이 스마트한 결정 뒤편에 도사리고 있는 아키텍처 선택과 아키텍처 통신 설계 등, 집요하고 아름답게 정돈된 비법 소스들이 낱낱이 궁금하시다면 잘 정리된 이 기고 자료에서 시원하게 그 정답을 손에 잡아 보시길 적극 추천해 드립니다.
Conclusion
진심으로 성공적인 튜토리얼 마무리를 축하드립니다! 🎉 이번 여정을 통해 여러분은 Strands Agent 프레임워크 생태계 위에서 강력한 AWS AgentCore 서버 에이전트를 조립 및 전진 배치하는 요령은 물론, 스마트 인공지능 에이전트 구조의 중심축을 흐르는 지능형 루프의 설계 비밀을 깊게 몸소 체험하셨습니다. 무엇보다 전 세계 최정상 수준의 TwelveLabs 혁신적 멀티모달 비디오 인지 기술을 여러분의 제품에 간편하게 이식해 내는 놀랍도록 간결한 개발 경로를 완전한 여러분의 지식 자산으로 만드셨습니다.
앞서 다룬 원리와 더욱 입체적이고 다양한 구현 방식을 연구하고자 하신다면 다음 훌륭한 공식 채널 리소스를 탐색해 보실 수 있습니다:
공식 배포 GitHub 소스 리포지토리: https://github.com/nathanchess/twelvelabs-agentcore-demo
백엔드 연동 기술 아키텍처 전체 맵(LucidChart): https://lucid.app/lucidchart/40b7aa79-6da6-4bed-bd63-5f34e3955685/edit?viewport_loc=424%2C-502%2C4025%2C1778%2C0_0&invitationId=inv_ba388ce0-6ad8-4f77-9ac1-c8a4edc405db
본 애플리케이션 공식 인스톨러 배포 페이지: https://github.com/nathanchess/twelvelabs-agentcore-demo/releases/tag/v1.0.0
Strands Agent 구현 전체 공식 개발 문서: https://strandsagents.com/latest/
AWS AgentCore 상세 통합 가이드 문서: https://aws.amazon.com/bedrock/agentcore/




