제가 AWS Cloud Path 시리즈를 시작했을 때, 라이브 스트리밍을 하고, 이를 게시한 뒤, 나중에 "블로그 버전으로 작성해야지"라고 스스로 다짐하지만, 밀린 업무들 때문에 결국 실행에 옮기지 못하는 패턴에 빠져 있다는 것을 깨달았습니다. 60~120분 분량의 튜토리얼은 제대로 된 기사 버전으로 만들기 위해 다시 시청하고, 초안을 작성하고, 편집하고, 형식을 맞추는 과정에서 쉽게 몇 시간으로 늘어날 수 있습니다.

저에게 이러한 마찰(friction)은 당시 제 YouTube 콘텐츠 중 아주 적은 부분만이 기사로 만들어졌음을 의미했습니다. 저는 YouTube 튜토리얼을 가져와서 제가 공유한 콘텐츠를 추출하고, 이를 구조화된 기술 기사(제목, 코드 블록, 저의 주의 사항 및 설명 포함)로 변환해 주는 파이프라인을 원했습니다. Hermes.v는 최종 초안을 필요에 따라 편집하고 개선할 수 있는 충분한 제어권을 유지하면서도, 그 파이프라인을 자동화하려는 저의 시도였습니다.

이 포스트에서는 이 프로젝트를 구축하는 과정, 그 뒤에 숨겨진 아키텍처(architecture), 그리고 엔드 투 엔드(end-to-end)로 어떻게 작동하는지에 대해 안내해 드리겠습니다. 마지막에는 여러분도 동일한 스택을 배포하고 여러분만의 콘텐츠에 맞게 조정하는 방법을 알게 될 것입니다.

Hermes.v가 하는 일

GitHub logo elizabethadegbaju / hermes.v

AWS Bedrock과 Strands Agents를 사용하여 YouTube 튜토리얼 영상을 Dev.to 기사로 변환합니다.

Hermes.v — YouTube 튜토리얼 기사 생성기

YouTube 튜토리얼 영상을 Dev.to에 게시되는 기술 기사로 변환하는 Strands Agents 기반의 자율 에이전트(autonomous agent)입니다.

작동 방식

1. 에이전트가 사용자에게 YouTube URL과 선택 사항인 제목 및 태그를 요청합니다.
2. 비디오 메타데이터를 검사하여 시각적 추출 (visual extraction)이 비용 대비 가치가 있는지 결정합니다. 코드 워크스루 (code walkthroughs) 및 데모의 경우 프레임을 추출하고, 토크 스타일 (talk-style) 비디오의 경우 추출을 건너뜁니다.
3. 오디오를 S3에 업로드하고 Amazon Transcribe를 통해 전사 (transcribe)합니다.
4. 전사된 텍스트를 청크 (chunks)로 나눕니다. 각 청크에서 구조화된 노트 (structured notes)를 추출한 다음, 이를 개요 (outline)로 압축합니다.
5. Claude가 섹션별로 기사를 작성하며, 일관성을 유지하기 위해 이전 섹션의 압축된 요약을 컨텍스트 (context)로 전달합니다.
6. 완성된 기사는 Dev.to에 초안 (draft)으로 게시됩니다.

아키텍처 (Architecture)

사용된 AWS 서비스: Bedrock (Claude Sonnet 4.6), Amazon Transcribe, S3

사전 요구 사항 (Prerequisites)

• Bedrock Claude Sonnet 4.6 모델 액세스가 활성화된 AWS 계정
• AWS CDK CLI: npm install -g…

View on GitHub

Hermes.v는 YouTube 튜토리얼 비디오를 Dev.to 초안 기사로 변환하는 Strands Agents 기반의 워크플로 (workflow)입니다. 높은 수준에서 살펴보면, 단일 입력(YouTube URL)을 받아 AWS 및 제3자 API 전반에 걸쳐 여러 단계를 오케스트레이션 (orchestrate)하여 Dev.to에 마크다운 (markdown) 기사 초안을 생성합니다.

현재의 엔드 투 엔드 (end-to-end) 흐름은 다음과 같습니다:

1. 프롬프트가 나타나면 YouTube 튜토리얼 URL(및 선택적으로 제목과 태그)을 제공합니다.
2. 에이전트는 get_video_data를 통해 yt-dlp를 사용하여 비디오 메타데이터 (metadata)를 가져옵니다.
3. extract_frames_and_audio는 비디오를 다운로드하고, 오디오를 추출하며, 시각적 문맥 (visual context)을 위해 일정 시간 간격으로 프레임 (frames)을 샘플링합니다. 오디오는 S3에 업로드되고, 프레임은 "시각적 요약 (visual summary)" 텍스트 파일로 요약됩니다.
4. generate_transcript는 오디오를 Amazon Transcribe에 전달하고, 완료될 때까지 기다린 후 전사 데이터 (transcript)를 S3에 저장합니다.
5. generate_article_draft는 _core.py에서 단계별 초안 작성 파이프라인 (pipeline)을 실행합니다: 청크 (chunked) 단위의 전사 노트 → 개요 (outline) → 섹션별 기사 순으로 진행되며, Bedrock Claude Sonnet 4.6이 핵심적인 작업 (heavy lifting)을 수행합니다.
6. publish_devto_article은 S3에서 기사 마크다운 (markdown)을 읽어 Dev.to 초안으로 게시하거나, API 키를 설정하지 않은 경우 게시를 건너뜁니다.

Hermes.v는 제 튜토리얼 콘텐츠를 변환하는 번거로운 작업 (grunt work)을 처리해주므로, 저는 기사를 처음부터 쓰는 대신 편집에 집중하고 저만의 강조점을 추가하는 데 전념할 수 있습니다.

아키텍처 개요

개념적으로 Hermes.v는 YouTube, AWS 서비스, 그리고 Dev.to를 연결하는 파이프라인 (pipeline)이며, Strands Agent가 각 단계를 조정합니다. 현재 아키텍처는 **실행 기반 (run-based)**입니다. 모든 처리 세션은 run_id와 S3에 저장된 매니페스트 (manifest)를 가지므로, 재실행 시 에이전트가 완료된 단계를 건너뛸 수 있습니다.

한눈에 보기:

• Strands Agent: 도구 호출 (tool calls)을 오케스트레이션하고, 시스템 프롬프트 (system prompt)를 유지하며, 대화 기록 (conversation history)을 관리합니다.
• AWS 서비스 (AWS services):
  • Amazon Bedrock (Claude Sonnet 4.6): 시각적 요약 (visual summarisation) 및 기사 생성용.
  • Amazon Transcribe: 오디오 전사 (audio transcription)용.
  • Amazon S3: 실행 매니페스트 (run manifests), 오디오, 전사본, 시각적 요약, 초안 캐시 (draft caches), 최종 기사 저장용.
• Dev.to API: 완성된 마크다운 (markdown)을 미발행 초안으로 수신합니다.

모든 것은 환경 변수 (environment variables)와 infra/ 아래에 정의된 AWS CDK 스택을 통해 연결됩니다.

스크립트 대신 에이전트를 사용한 이유

저의 첫 번째 버전은

환경 변수에는 AWS_REGION, BEDROCK_MODEL_ID (기본값 eu.anthropic.claude-sonnet-4-6), HERMES_S3_BUCKET, 그리고 선택 사항인 Dev.to 설정(DEVTO_API_KEY, DEVTO_ORG_ID, DEVTO_MAIN_IMAGE)이 포함됩니다.

에이전트 오케스트레이션 (Agent orchestration)

핵심 에이전트 배선(wiring)은 agent/hermes_agent.py에 구현되어 있습니다.

"""Hermes.v - Strands를 사용하는 YouTube 튜토리얼 기사 생성 에이전트."""

import logging
...

주요 포인트:

• 에이전트는 BedrockModel을 통해 Bedrock Claude Sonnet 4.6을 사용합니다.
• start_run 및 generate_article_draft를 포함한 모든 도구(tools)를 등록합니다.
• 시스템 프롬프트(system prompt)에는 워크플로우 규칙과 안전 가드레일(safety rails)이 인코딩되어 있습니다.
• run() 메서드는 대화를 시작하며, 에이전트는 먼저 handoff_to_user를 통해 사용자에게 URL/제목/태그를 요청한 다음 나머지 과정을 오케스트레이션합니다.

도구: YouTube URL에서 S3 아티팩트(artifacts)까지

모든 도구는 agent/tools.py에 위치합니다. 이 도구들은 S3 접근, 매니페스트(manifests), Bedrock 호출을 위해 _core.py의 공유 헬퍼(helpers)를 사용합니다.

실행 시작하기

각 세션은 매니페스트와 run_id를 생성하는 start_run으로 시작됩니다:

import time
from typing import Dict

...

매니페스트는 S3의 hermes/runs/<run_id>.json에 저장되며 어떤 단계가 완료되었는지 추적합니다.

비디오 메타데이터 가져오기

get_video_data는 메타데이터를 가져와 매니페스트에 저장합니다:

from typing import Any, Dict

from yt_dlp import YoutubeDL
...

에이전트는 이를 사용하여 워크플로우가 얼마나 "무거운(heavy)" 것이 적절한지 결정합니다 (예: 긴 코딩 세션 vs 짧은 공익 광고).

프레임 및 오디오 추출

이 단계에서는 오디오와 시각적 컨텍스트(context)가 캡처됩니다.

import base64
import glob
import io
...

이 도구는 원본 프레임을 에이전트에게 반환하는 대신, 요약된 시각적 아티팩트(visual artefact)를 S3에 저장하고 그 URI를 반환합니다.

스크립트(transcript) 생성

generate_transcript는 이제 스크립트를 S3에 작성하고 transcript_s3_uri를 반환합니다:

import boto3
import os
import time
...

단계별 기사 생성 파이프라인

초안 작성 파이