Cloudflare Workflows v2 백그라운드 에이전트 실행 설정은 먼저 “오래 걸리는 일을 단계로 쪼개고, 실패해도 어디서 멈췄는지 다시 볼 수 있게 만드는 작업”으로 이해하면 쉽습니다. 웹훅 하나가 들어올 때마다 LLM 요약, 파일 변환, 데이터 정리, Slack 알림, API 호출을 한 번에 처리하려고 하면 중간 실패를 찾기 어렵습니다. Workflows는 이런 과정을 단계별로 기록하고 다시 시도할 수 있게 설계하는 Cloudflare의 서버리스 오케스트레이션 도구이므로, 실무에서는 작은 배치 작업이나 승인 대기 작업부터 적용하는 편이 안전합니다.
핵심 요약: Workflows v2는 Workers 주변에서 실행되는 긴 작업을 단계, 상태, 재시도 기준으로 관리하는 방식입니다. 처음에는 “입력 받기 → 데이터 검증 → 외부 API 호출 → 결과 저장 → 알림” 정도의 5단계로 작게 만들고, 각 단계의 실패 기준과 재실행 가능 여부를 문서화하세요. Cloudflare 화면, 요금, 사용 한도, 기능명은 변경될 수 있으므로 실제 적용 전 공식 문서와 현재 대시보드를 다시 확인해야 합니다.
1. Workflows v2를 쓰면 좋은 업무 흐름
Workflows v2는 단순히 빠른 API 응답을 만드는 도구라기보다, 시간이 걸리는 작업을 안정적으로 이어 붙이는 도구에 가깝습니다. 예를 들어 고객이 양식을 제출하면 파일을 읽고, 텍스트를 정리하고, 내부 데이터베이스에 저장하고, 담당자에게 알림을 보내는 흐름이 있습니다. 이 작업을 하나의 함수 안에 전부 넣으면 외부 API가 잠깐 느려지거나 응답 형식이 바뀌었을 때 전체 흐름이 어디서 깨졌는지 확인하기 어렵습니다.
반대로 Workflows로 단계를 나누면 각 단계의 입력과 결과를 추적할 수 있습니다. “문서 가져오기”, “본문 추출”, “요약 만들기”, “검토 큐에 넣기”, “완료 알림”처럼 이름을 붙이면 운영자도 로그를 읽기 쉬워집니다. 특히 백그라운드 에이전트라는 말이 붙는 흐름은 사용자가 기다리는 화면 뒤에서 여러 일을 처리하는 구조이므로, 중간 상태와 실패 처리가 더 중요합니다.
2. 시작 전에 정해야 할 입력과 종료 기준
가장 먼저 정할 것은 트리거입니다. Workers의 HTTP 요청, Cron Trigger, Queue 메시지, 내부 관리자 버튼 등 어떤 사건이 Workflows 인스턴스를 시작하는지 고정해야 합니다. 같은 작업이라도 사용자가 직접 누르는 버튼과 매일 새벽 실행되는 배치 작업은 실패를 다루는 방식이 다릅니다. 버튼 작업은 즉시 안내가 필요하고, 배치 작업은 다음 실행 전에 재처리할 수 있는 기록이 필요합니다.
종료 기준도 미리 정해야 합니다. “Slack 알림을 보냈으면 완료”인지, “데이터베이스 저장까지 성공해야 완료”인지, “담당자가 검토 상태로 바꾸면 완료”인지가 다르면 단계 설계가 달라집니다. 종료 기준이 모호하면 자동화가 실제로 끝났는지, 사람이 이어서 봐야 하는지 판단하기 어렵습니다.
3. 기본 아키텍처: Workers, Workflows, 저장소
실무 구조는 대체로 세 부분입니다. 첫째, Workers가 외부 요청을 받아 인증, 필드 검증, Workflows 시작 요청을 맡습니다. 둘째, Workflows가 실제 단계 실행과 재시도, 대기, 상태 관리를 맡습니다. 셋째, D1, R2, KV, 외부 SaaS 같은 저장소나 업무 앱이 결과를 보관합니다. 이 구분을 해두면 Workers는 얇게 유지되고, 시간이 걸리는 작업은 Workflows가 담당합니다.
예를 들어 보고서 자동 생성 흐름에서는 Workers가 “새 보고서 요청”을 받고, Workflows가 자료 수집, 요약, 표 생성, 문서 저장, 알림 발송을 순서대로 실행합니다. 저장소에는 요청 ID, 요청자, 현재 단계, 마지막 오류, 결과 링크를 남깁니다. 이렇게 하면 담당자는 대시보드나 로그에서 어느 요청이 멈췄는지 바로 찾을 수 있습니다.
4. 단계 이름과 재시도 규칙을 작게 설계하기
단계 이름은 운영자가 읽을 수 있게 붙이는 것이 좋습니다. “step1”, “process”, “callApi”보다 “입력 검증”, “문서 다운로드”, “요약 생성”, “결과 저장”, “담당자 알림”처럼 업무 언어로 쓰면 나중에 오류를 설명하기 쉽습니다. 단계가 너무 크면 실패 지점이 보이지 않고, 너무 작으면 로그가 지나치게 많아집니다. 한 단계는 한 가지 외부 의존성이나 한 가지 판단 기준을 중심으로 나누는 편이 무난합니다.
재시도 규칙은 모든 단계에 똑같이 걸지 않는 것이 좋습니다. 네트워크 지연처럼 일시적인 문제는 재시도가 도움이 되지만, 입력값 누락이나 권한 오류처럼 데이터 자체가 잘못된 문제는 반복해도 해결되지 않습니다. 따라서 단계별로 “재시도 가능한 실패”와 “사람이 확인해야 하는 실패”를 나눠야 합니다.
5. 실무 체크리스트: 첫 배포 전 확인할 것
- 트리거가 하나로 고정되어 있고 테스트 요청을 재현할 수 있는가?
- 각 단계 이름이 업무 담당자도 이해할 수 있는 표현인가?
- 요청 ID, 현재 단계, 마지막 업데이트 시간이 저장되는가?
- 외부 API 호출 실패와 입력값 오류를 구분해서 처리하는가?
- 동일 요청이 두 번 들어왔을 때 중복 실행을 막거나 감지할 수 있는가?
- 실패 알림이 너무 자주 오지 않도록 묶음 또는 우선순위 기준이 있는가?
- 요금, 사용 한도, 보관 기간, 기능 제공 범위를 현재 공식 화면에서 확인했는가?
6. 예시 흐름: 문서 요약 백그라운드 에이전트
가장 이해하기 쉬운 예시는 문서 요약 요청입니다. 사용자가 폼에 문서 링크와 요청 목적을 입력하면 Workers가 요청을 받고 Workflows를 시작합니다. Workflows는 링크 접근 가능 여부를 확인하고, 문서 내용을 가져오고, 긴 텍스트를 나눠 요약하고, 결과를 저장한 뒤 담당자에게 알립니다. 사용자는 화면을 닫아도 작업은 백그라운드에서 이어지고, 담당자는 결과 링크와 상태를 나중에 확인할 수 있습니다.
| 단계 | 주요 역할 | 실패 시 처리 |
|---|---|---|
| 요청 접수 | 필수 필드와 요청 ID 생성 | 누락 필드는 즉시 반려 |
| 자료 확인 | 문서 링크 접근과 파일 형식 확인 | 접근 실패는 담당자 확인 큐로 이동 |
| 본문 처리 | 텍스트 추출과 분량 나누기 | 일시 오류만 제한 재시도 |
| 요약 생성 | 목적에 맞춘 요약 결과 만들기 | 결과가 비어 있으면 수동 검토 |
| 결과 저장 | 저장소에 상태와 링크 기록 | 저장 실패는 재시도 후 알림 |
7. 모니터링과 로그를 먼저 보는 습관
백그라운드 자동화는 성공할 때보다 실패할 때 운영 품질이 드러납니다. 배포 직후에는 기능을 더 붙이기보다 로그를 먼저 봐야 합니다. 어떤 단계에서 시간이 오래 걸리는지, 재시도가 과한지, 같은 입력 오류가 반복되는지 확인하면 다음 개선 방향이 보입니다. 가능하다면 상태값을 “queued, running, needs_review, completed, failed”처럼 단순하게 두고, 담당자가 해석하기 쉬운 오류 메시지를 함께 남깁니다.
또한 알림은 조심해서 설계해야 합니다. 모든 실패를 즉시 Slack으로 보내면 몇 번의 반복 실패만으로 채널이 시끄러워집니다. 중요한 고객 요청, 긴급 배치, 반복 실패 같은 조건만 우선 알림으로 올리고 나머지는 대시보드나 일일 요약으로 확인하는 방식이 운영에 맞습니다.
8. 보안과 권한은 최소 연결부터
Workflows가 여러 앱을 연결할수록 토큰, 웹훅 URL, 저장소 권한을 신중하게 다뤄야 합니다. 처음에는 읽기 전용에 가까운 작업이나 내부 테스트 데이터로 시작하고, 필요한 범위만 연결합니다. 운영 비밀값은 코드에 직접 넣지 말고 Cloudflare 환경 변수나 비밀 관리 방식으로 분리합니다. 로그에도 원문 전체나 민감한 식별값을 남기기보다 요청 ID와 요약 상태만 남기는 편이 안전합니다.
권한 검토는 자동화가 커질수록 더 중요합니다. 예를 들어 문서 요약 흐름이 나중에 CRM 업데이트까지 하게 되면, 잘못된 분류가 실제 업무 데이터 변경으로 이어질 수 있습니다. 초반에는 결과 저장과 알림까지만 자동화하고, 데이터 변경은 담당자 승인 뒤 실행되도록 나누는 것이 좋습니다.
9. 비용과 기능 변경 가능성 확인
Cloudflare의 대시보드 메뉴, Workflows 관련 한도, 요금 체계, 베타 또는 정식 제공 범위는 시점에 따라 바뀔 수 있습니다. 따라서 글이나 예시만 보고 바로 적용하기보다, 실제 계정의 Workers 및 Workflows 문서, 현재 플랜, 호출량, 저장소 사용량을 함께 확인해야 합니다. 특히 외부 AI API나 다른 SaaS와 연결하면 Cloudflare 외부의 과금 조건도 함께 영향을 줍니다.
운영팀이 확인할 항목은 단순합니다. 한 달 예상 실행 횟수, 한 실행당 단계 수, 외부 API 호출 횟수, 저장소 보관 기간, 실패 재시도 횟수를 표로 적어 보세요. 이 숫자가 있어야 나중에 비용이 늘었을 때 원인을 찾기 쉽습니다.
10. 처음 만드는 팀을 위한 적용 순서
처음에는 “자동화하고 싶은 전체 업무”가 아니라 “실패해도 되돌릴 수 있는 한 부분”부터 고릅니다. 예를 들어 고객 문의를 바로 처리하지 말고 문의 요약과 담당자 알림만 자동화합니다. 문서 변환도 원본을 덮어쓰지 말고 별도 결과 파일을 저장합니다. 이렇게 하면 자동화가 잘못되어도 원본 업무 흐름을 망가뜨리지 않습니다.
그다음 1주일 정도 로그를 보며 단계 이름, 오류 메시지, 알림 조건을 다듬습니다. 안정성이 확인되면 저장소 업데이트, 담당자 배정, 승인 대기 같은 다음 단계를 붙입니다. Workflows v2의 장점은 이런 단계형 확장에 있으므로, 처음부터 거대한 에이전트를 만들기보다 작은 백그라운드 작업을 여러 번 성공시키는 방식이 실무에 맞습니다.
FAQ
Q1. Workflows v2는 Workers와 무엇이 다른가요?
Workers는 요청을 빠르게 처리하는 실행 환경에 가깝고, Workflows는 여러 단계가 있는 긴 작업의 상태와 재시도 흐름을 관리하는 데 초점이 있습니다. 실제 운영에서는 Workers가 시작점을 만들고 Workflows가 백그라운드 단계를 이어가는 구조가 이해하기 쉽습니다.
Q2. AI 에이전트 작업이 아니어도 쓸 수 있나요?
쓸 수 있습니다. 파일 처리, 정기 리포트, 알림 묶음, 외부 API 동기화처럼 시간이 걸리고 중간 상태가 필요한 작업이면 AI가 없어도 Workflows 구조가 도움이 됩니다. 다만 사용량과 한도는 현재 공식 문서를 기준으로 확인해야 합니다.
Q3. 처음부터 완전 자동 처리를 해도 되나요?
처음에는 권장하지 않습니다. 요약, 분류, 알림처럼 되돌리기 쉬운 단계부터 시작하고, 운영 로그가 쌓인 뒤 데이터 변경이나 외부 발송 같은 단계를 붙이는 편이 안전합니다.
Q4. 실패한 작업은 어떻게 다시 처리해야 하나요?
요청 ID와 현재 단계를 저장해 두고, 재시도 가능한 오류와 사람이 확인해야 하는 오류를 구분해야 합니다. 같은 요청이 두 번 실행될 수 있으므로 결과 저장 단계에는 중복 감지 기준도 두는 것이 좋습니다.
Q5. 요금이나 화면이 글과 다르면 어떻게 하나요?
Cloudflare와 연결 SaaS의 기능명, 메뉴 위치, 플랜별 제공 범위는 바뀔 수 있습니다. 실제 적용 전 현재 계정의 대시보드와 공식 문서를 먼저 확인하고, 팀 내부 문서에는 확인 날짜를 남기는 것이 좋습니다.
마무리: 작은 단계형 자동화로 시작하기
Cloudflare Workflows v2는 “한 번에 끝나는 함수”보다 “여러 단계가 이어지는 업무 처리”에 잘 맞습니다. 백그라운드 에이전트 실행 흐름을 만들 때는 입력, 단계, 저장, 알림, 실패 처리를 먼저 문서화하고, 처음에는 되돌리기 쉬운 작업만 연결하세요. 이후 로그를 보며 재시도 기준과 알림 조건을 다듬으면 서버리스 업무 자동화를 더 안정적으로 운영할 수 있습니다.
