Cloudflare Agents 가이드: 내구성 워크플로우와 사람 승인

InYourLeague 리서치 · 2026-08-29

Answer in brief

Cloudflare Agent에서 장기 실행, 자동 재시도, 내구성 상태 동기화, 외부 이벤트 대기 또는 사람 승인이 필요하면 AgentWorkflow를 사용합니다. 복구 경계는 단계 단위이며, 워크플로우의 step을 통하는 작업은 내구성을 갖지만 진행 상황 보고, 클라이언트 브로드캐스트, 직접 Agent RPC 호출은 재시도 후 반복될 수 있습니다.

Key facts at a glance

Failure modes and verification

FAQ

Cloudflare Agents에서 언제 AgentWorkflow를 사용해야 하나요?

전달 보장, 자동 재시도, 내구성 복구, 장기 백그라운드 처리, 외부 이벤트 대기 또는 사람 승인이 필요한 다단계 작업에 사용합니다. 공식 Workflow 가이드에서 적용 범위를 확인할 수 있습니다.

자동 재시도가 완료된 step.do() 작업도 반복하나요?

아닙니다. Cloudflare는 완료된 내구성 단계가 영구적으로 기록되며 워크플로우 재시작 후 다시 실행되지 않는다고 설명합니다. 실패한 단계는 설정 가능한 백오프에 따라 재시도될 수 있습니다.

진행 상황 보고나 Agent RPC 호출이 여러 번 실행될 수 있나요?

그렇습니다. this.reportProgress(), this.broadcastToClients(), this.agent를 통한 직접 호출은 비내구성이므로 워크플로우 재시도 과정에서 반복될 수 있습니다.

사람은 일시 중지된 워크플로우를 어떻게 승인하거나 거부하나요?

Workflow가 waitForApproval()에서 일시 중지되면 Agent가 approveWorkflow() 또는 rejectWorkflow()로 응답합니다. 공식 사람 참여형 패턴 가이드에서 이 승인 흐름을 설명합니다.

cloudflare-agents에 선택 가능한 모델 ID가 공개되어 있나요?

아닙니다. The official source does not publish a selectable model ID for this product.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-29

Extended guide

실패에 민감하거나 오래 실행되는 작업은 AgentWorkflow로 옮기고, 실시간 사용자 상호작용은 Cloudflare Agent에 유지합니다. 재시작 후에도 보존되어야 하거나, 자동으로 재시도해야 하거나, 사람의 승인을 기다려야 하는 작업은 워크플로우의 내구성 단계 안에서 실행해야 합니다.

확인 범위

이 문서는 Cloudflare 공식 문서를 기준으로 2026-08-29에 확인했습니다. agents/workflows에서 가져오는 AgentWorkflow는 Workflow와 이를 시작한 Agent 사이에 양방향 통신을 제공합니다. Cloudflare Agents는 오래 유지되는 식별자, 사용자와의 직접 상호작용, WebSocket, HTTP 스트리밍, 내장 상태 데이터베이스를 담당합니다. Workflows는 완료까지 이어지는 실행, 단계별 영속성, 자동 재시도와 복구, 외부 이벤트를 기다리는 내구성 대기를 담당합니다.

The official source does not publish a selectable model ID for this product. 즉, 공식 자료에는 이 제품에서 선택할 수 있는 모델 ID가 공개되어 있지 않습니다.

통합 방식과 복구 경계

권장 구현 순서

1. AgentWorkflow를 확장하고 run(event, step)을 구현합니다. 워크플로우 입력은 event.payload에서 읽습니다.
2. 검증, 처리, 그 밖의 재시도 민감 작업을 이름이 일관된 별도 step.do() 호출에 배치합니다. 성공한 내구성 단계는 이후 실행에서 오류가 발생하더라도 반복되지 않습니다.
3. 복구 후에도 동기화된 Agent 상태가 유지되어야 한다면 step.updateAgentState() 또는 step.mergeAgentState()를 사용합니다. 반복되어도 안전한 알림에만 this.reportProgress(), this.broadcastToClients(), 직접 Agent RPC 호출을 사용합니다.
4. 사람의 검토가 필요하면 this.waitForApproval(step, { timeout: ... })을 호출합니다. Agent는 approveWorkflow() 또는 rejectWorkflow()로 대기를 해제한 다음, 보류 중인 승인 목록과 같은 Agent 상태를 갱신할 수 있습니다.
5. 성공 결과는 step.reportComplete()로 마무리하고, 오류는 step.reportError()로 보고합니다. Agent는 워크플로우 상태 조회, 일시 중지, 재개, 종료, 재시작도 수행할 수 있으며 sendWorkflowEvent()로 이벤트를 보낼 수 있습니다.

출시 전 체크리스트

• 반복되면 안 되는 모든 작업이 내구성 step API 안에 있습니다.
• 비내구성 RPC, 진행 메시지, WebSocket 브로드캐스트는 여러 번 수신되어도 안전합니다.
• 복구가 필요한 Agent 상태 변경은 step.updateAgentState() 또는 step.mergeAgentState()를 사용합니다.
• 승인 요청에는 애플리케이션에 적합한 명시적 제한 시간이 있습니다.
• Agent에는 올바른 워크플로우 ID를 승인하거나 거부할 수 있는 권한 통제 경로가 있습니다.
• 후속 단계는 내구성 출력 또는 다시 구성할 수 있는 입력에만 의존합니다.
• 외부 이벤트 대기는 공식 문서의 영속성 한도를 고려합니다.

핵심 복구 경계

Workflow 복구가 run() 안의 모든 문장을 자동으로 내구성 작업으로 바꾸는 것은 아닙니다. 실제 내구성 경계는 step을 통해 수행되는 작업입니다. 직접 Agent RPC 호출, 진행 상황 보고, 클라이언트 브로드캐스트처럼 이 경계 밖에서 발생하는 작업은 다시 실행될 수 있습니다. 따라서 이런 효과는 반복되어도 안전하게 설계하고, 승인 동작을 정의할 때 Workflow 가이드와 사람 참여형 패턴 가이드를 함께 확인해야 합니다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.