Cloudflare Agents SDK v0.16.1 해설: 브라우저·코드 실행 에이전트는 기능보다 실행 경계와 복구 로그를 먼저 설계해야 하는 이유

1. 한 줄 문제 정의

핵심 요약: 에이전트가 브라우저와 코드 실행 권한을 갖는 순간, 모델 성능보다 실행 경계가 더 큰 위험이 됩니다.

Cloudflare는 2026년 6월 16일 Agents SDK v0.16.1 업데이트를 통해 Browser Run, Codemode, Think sub-agent 위임, 재연결 복구 흐름을 강화했습니다. 표면적으로는 “에이전트가 웹을 보고 코드를 실행한다”는 기능 업데이트처럼 보입니다. 하지만 개발자가 실제로 배워야 할 핵심은 기능 목록이 아니라 브라우저 세션, 코드 실행 런타임, 하위 에이전트 권한, durable log를 어떤 경계로 나눌지입니다.

이 글은 Cloudflare Workers와 Agents SDK로 업무 자동화, 테스트 자동화, 운영 보조 에이전트를 만들려는 개발자를 대상으로 합니다. 범위는 SDK v0.16.1의 구조 해설과 실무 도입 순서입니다. 반대로 단순 챗봇, 정적 문서 검색, 한 번의 API 호출로 끝나는 기능은 이 구성이 과할 수 있습니다.

2. 먼저 결론

핵심 요약: v0.16.1의 핵심은 “더 많은 도구”가 아니라 도구를 오래 실행하고, 중간에 멈춰도 이어서 통제하는 구조입니다.

• 지금 도입할 만한 팀: 브라우저 확인, 외부 API 조합, 코드 실행, 장시간 작업 재개가 필요한 에이전트를 Workers 위에서 운영하려는 팀
• 아직 관찰이 나은 팀: 로그인·결제·삭제·고객 데이터 수정처럼 실패 비용이 큰 액션을 승인 UI 없이 자동화하려는 팀
• 제 추천: Browser Run과 Codemode를 바로 모두 열기보다 읽기 전용 브라우저 → 제한된 코드 실행 → 사람 승인 후 상태 변경 순서로 확장하십시오.

Cloudflare의 업데이트 방향은 명확합니다. 에이전트는 이제 단순히 텍스트를 생성하는 계층이 아니라, 웹 브라우저와 실행 환경을 다루는 작은 운영자에 가까워지고 있습니다. 그래서 성공 기준도 답변 품질에서 권한 축소, 세션 보존, 로그 재생, 비용 관측으로 이동합니다.

3. 핵심 구조 분해

핵심 요약: v0.16.1은 네 개의 실행 계층으로 보면 이해가 쉽습니다.

1. Browser Run 계층: 에이전트가 Chrome DevTools Protocol 기반 코드로 웹 페이지를 탐색하고, 스크린샷을 보고, 렌더링된 내용을 읽고, 브라우저 세션과 쿠키를 다룹니다.
2. Codemode 계층: 모델에게 수십 개의 도구 설명을 프롬프트에 밀어 넣는 대신, 하나의 codemode 도구와 typed globals, connector, durable execution log를 제공합니다.
3. Sub-agent 위임 계층: Think sub-agent에 작업을 넘길 때 client-provided tools를 함께 사용할 수 있게 하여, 상위 에이전트와 하위 에이전트의 도구 접근 범위를 설계하게 만듭니다.
4. 복구 계층: Durable Object eviction, 배포, 연결 끊김 이후에도 작업을 이어갈 수 있게 하는 재연결과 상태 복구 흐름입니다.

초보 개발자 기준으로 쉽게 말하면 Browser Run은 실제 브라우저가 있는 작업대, Codemode는 안전한 코드 실행 책상, sub-agent는 업무를 나눠 맡는 보조 작업자, durable log는 작업 일지입니다. 작업 일지가 없으면 중간에 멈췄을 때 “어디까지 했는지”를 알 수 없습니다.

4. 설계 의도 해설

핵심 요약: Cloudflare는 에이전트 도구를 프롬프트에 많이 넣는 방식에서 실행 런타임을 좁고 오래 유지하는 방식으로 이동하고 있습니다.

기존 함수 호출 방식은 작은 자동화에는 충분합니다. 하지만 브라우저를 열고, 화면을 읽고, 외부 API를 여러 번 호출하고, 코드 조각을 재사용하는 흐름에서는 프롬프트가 도구 설명으로 비대해집니다. 모델은 해야 할 일보다 “쓸 수 있는 도구 목록”에 컨텍스트를 쓰게 됩니다.

Codemode가 중요한 이유가 여기에 있습니다. Cloudflare 문서는 Codemode가 createCodemodeRuntime, connector, durable execution log를 사용한다고 설명합니다. 이는 모델이 매번 모든 도구 설명을 읽는 구조가 아니라, 필요한 기능을 런타임 안에서 발견하고 코드로 조합하는 구조에 가깝습니다. 얻는 것은 컨텍스트 절약과 재개 가능성이고, 잃는 것은 단순 함수 호출보다 더 엄격한 런타임 설계 필요성입니다.

Browser Run도 같은 방향입니다. 고정된 클릭/입력 액션 목록이 아니라 CDP 기반 코드 실행을 열어 유연성을 얻습니다. 대신 개발자는 브라우저 세션 모드, 녹화 여부, MFA 대기, 승인 후 재개 같은 운영 조건을 반드시 설계해야 합니다.

5. 근거 및 비교

핵심 요약: 이 업데이트의 비교 대상은 “다른 모델”이 아니라 브라우저 자동화와 코드 실행을 어떤 방식으로 운영할지입니다.

공식 근거도 최근 3개월 안의 자료로 확인됩니다. Cloudflare Docs는 2026년 6월 16일 v0.16.1에서 Browser Run, Codemode, client-provided tools, 복구 개선을 명시했습니다. 같은 날 GLM-5.2가 Workers AI에 추가되며 agentic coding, function calling, reasoning, 긴 컨텍스트를 강조했습니다. 2026년 6월 10일 AI Search namespace Wrangler 명령이 추가되어 에이전트가 검색 namespace를 스크립트로 관리하기 쉬워졌고, 2026년 6월 12일 AI Gateway 로그에는 user agent 필터가 추가되어 어떤 SDK나 앱에서 트래픽이 왔는지 추적하기 쉬워졌습니다.

6. 실제 동작 흐름 / 단계별 실행 방법

핵심 요약: 실전 도입은 브라우저 권한을 여는 일이 아니라 도구 위험 등급을 먼저 나누는 일부터 시작해야 합니다.

1. 도구를 세 등급으로 나눕니다.
   읽기 전용 도구, 상태 변경 도구, 외부 부작용 도구로 분리하십시오. 브라우저 화면 읽기와 폼 제출은 같은 권한이 아닙니다.
2. 브라우저 세션 모드를 정합니다.
   일회성 세션, 재사용 세션, 승인 후 persistent 세션 중 무엇을 쓸지 업무별로 정합니다. MFA가 필요한 업무는 중간 대기와 재개가 필수입니다.
3. Codemode connector를 좁게 시작합니다.
   처음부터 모든 API를 열지 말고, 조회 전용 connector와 테스트용 fixture부터 붙입니다.
4. durable execution log를 운영 로그로 취급합니다.
   성공 결과만 저장하지 말고 어떤 코드가 어떤 도구를 어떤 순서로 호출했는지 재현 가능해야 합니다.
5. AI Gateway와 user agent 추적을 연결합니다.
   에이전트 이름, SDK, 업무 단위를 user agent 또는 metadata로 구분하면 비용과 장애 원인을 추적하기 쉽습니다.

import { Agent, createBrowserTools, createCodemodeRuntime } from "agents";

export class OpsAgent extends Agent {
  async onRequest(task) {
    const browserTools = createBrowserTools({
      ctx: this.ctx,
      browser: this.env.BROWSER,
      loader: this.env.LOADER,
      session: { mode: "dynamic" }
    });

    const codemode = createCodemodeRuntime({
      ctx: this.ctx,
      connectors: [this.env.READONLY_STATUS_CONNECTOR]
    });

    return this.run(task, {
      tools: {
        browser_markdown: browserTools.browser_markdown,
        codemode
      }
    });
  }
}

위 예시는 실제 운영 코드라기보다 설계 방향을 보여주는 뼈대입니다. 핵심은 브라우저 도구를 모두 열지 않고, 읽기 전용 도구부터 제공하며, Codemode connector도 제한된 범위에서 시작한다는 점입니다.

7. 실수/함정(Pitfalls)

핵심 요약: 실패는 보통 모델이 못해서가 아니라, 브라우저와 코드 실행을 너무 넓게 열어서 생깁니다.

• 실수 1: Browser Run을 곧바로 제출형 액션에 연결
  예방: 첫 배포는 browser_markdown, 스크린샷, 링크 추출처럼 읽기 전용으로 제한합니다.
  복구: 제출·삭제·구매 액션을 feature flag로 끄고, 승인 UI가 붙을 때까지 read-only로 되돌립니다.
• 실수 2: Codemode에 과도한 connector 제공
  예방: connector를 업무 단위로 쪼개고, 쓰기 권한 API는 별도 런타임에 둡니다.
  복구: durable log에서 실제 호출된 connector를 분석해 사용하지 않는 권한을 제거합니다.
• 실수 3: sub-agent에게 상위 에이전트와 같은 권한을 넘김
  예방: Think sub-agent에는 필요한 client-provided tools만 전달합니다.
  복구: 위임 로그를 기준으로 하위 에이전트별 도구 allowlist를 다시 만듭니다.
• 실수 4: 재개 가능성을 성공 케이스로만 테스트
  예방: 배포 중단, Durable Object eviction, 네트워크 끊김을 테스트 시나리오에 넣습니다.
  복구: 중단 지점을 durable log와 checkpoint 기준으로 재현하고, idempotency key를 추가합니다.
• 실수 5: 비용과 트래픽 출처를 나중에 보려 함
  예방: AI Gateway user agent, metadata, spend limit를 초기부터 붙입니다.
  복구: 로그에 남은 SDK·앱 단위 트래픽을 기준으로 예산 규칙을 다시 나눕니다.

8. 강점과 한계

핵심 요약: Cloudflare Agents SDK의 강점은 실행 인프라 통합이고, 한계는 클라우드 런타임 설계를 피할 수 없다는 점입니다.

• 강점: Workers, Durable Objects, Browser Run, AI Gateway를 한 생태계에서 묶을 수 있어 배포와 복구 흐름이 단순해집니다.
• 강점: Browser Run의 persistent session은 로그인, MFA, 사람 승인 후 재개가 필요한 업무에 유리합니다.
• 강점: Codemode는 도구 설명을 프롬프트에 계속 넣는 방식보다 장기 자동화에 적합합니다.
• 한계: 브라우저 자동화와 코드 실행은 본질적으로 위험합니다. 권한 축소와 감사 로그 없이 운영하면 장애 범위가 커집니다.
• 한계: Cloudflare 런타임에 익숙하지 않은 팀은 Durable Object, binding, AI Gateway 설정을 함께 배워야 합니다.
• 반례: 단순 FAQ 챗봇, 고정된 E2E 테스트, 완전한 온프레미스 실행이 필요한 환경에는 더 얇은 구성이 낫습니다.

9. 더 깊게 공부할 포인트

핵심 요약: 다음 학습은 모델 성능표보다 런타임, 세션, 로그, 비용 제어에 맞춰야 합니다.

• Browser Run에서 one-time, reusable, persistent 세션을 업무별로 나누는 기준
• Codemode connector를 read-only와 write-capable로 분리하는 패턴
• Durable Object eviction 이후 재개 가능한 작업 단위를 설계하는 방법
• AI Gateway spend limit와 user agent log를 에이전트별 비용 대시보드로 묶는 방법
• AI Search namespace를 tenant별로 나누고 Wrangler --json 출력으로 자동화하는 방법

10. 참고자료

• Cloudflare Docs - Agents SDK improves browser automation, code execution, and recovery (게시일: 2026-06-16, 확인일: 2026-06-18)
• Cloudflare Docs - Introducing GLM-5.2 on Workers AI (게시일: 2026-06-16, 확인일: 2026-06-18)
• Cloudflare Docs - Manage AI Search namespaces with Wrangler CLI (게시일: 2026-06-10, 확인일: 2026-06-18)
• Cloudflare AI Gateway Docs - Changelog (2026-06-12 user agent logs, 2026-06-05 spend limits, 확인일: 2026-06-18)
• Cloudflare Blog - Cloudflare’s AI Platform: an inference layer designed for agents (관련 글 목록 및 Agents SDK/AI Gateway 방향성, 확인일: 2026-06-18)

11. 실행 체크리스트 + 작성자 관점

핵심 요약: 도입 준비가 된 팀은 “에이전트가 무엇을 할 수 있는가”보다 “어디서 멈추고 누가 승인하는가”를 답할 수 있어야 합니다.

• 브라우저 도구를 읽기 전용, 입력 가능, 제출 가능 액션으로 분리했다
• persistent session이 필요한 업무와 one-time session으로 충분한 업무를 구분했다
• Codemode connector를 업무 단위로 쪼개고, 쓰기 권한 connector는 별도 승인 조건을 둔다
• Durable Object eviction, 배포 중단, 네트워크 끊김을 재개 테스트에 포함했다
• sub-agent에 전달할 client-provided tools allowlist를 별도로 정의했다
• AI Gateway user agent 또는 metadata로 에이전트별 트래픽을 식별한다
• spend limit 또는 업무별 예산 차단 규칙을 설정했다
• 실패 시 durable log만 보고도 마지막 안전 지점을 재현할 수 있다

Definition of Done: 브라우저·코드 실행·하위 에이전트 권한이 각각 문서화되어 있고, 중단 후 재개 테스트와 비용 추적 대시보드가 통과하면 1차 도입 완료로 봅니다.

제 판단은 이렇습니다. Cloudflare Agents SDK v0.16.1은 “에이전트가 더 똑똑해졌다”보다 에이전트가 실제 시스템을 만질 때 필요한 실행 인프라가 더 구체화됐다는 신호입니다. 그래서 지금 개발자가 익혀야 할 것은 프롬프트 문구가 아니라, 권한을 작게 열고 로그를 남기며 멈춘 작업을 다시 이어가는 운영 설계입니다.