cloudflare-agents-sdk

3 개의 포스트

cloudflare

레이더 리서처 소개: 자연어로 인터넷 데이터를 탐색하는 AI 도구 (새 탭에서 열림)

Cloudflare Radar Researcher는 자연어 질문만으로 인터넷 트래픽 데이터를 조회하고, 실제 API 기반 차트와 설명을 제공하는 AI 도구다. 사용자는 복잡한 필터 설정이나 API 문서 학습 없이 국가별 인터넷 품질, 장애·셧다운 상황 등을 분석할 수 있다. Cloudflare는 이를 통해 초보자부터 네트워크 전문가까지 Radar의 공개 데이터를 더 빠르고 쉽게 활용하도록 하는 것을 목표로 한다. ## Radar Researcher를 만든 배경 - Cloudflare Radar는 2020년부터 전 세계 인터넷 트래픽에 대한 공개 데이터와 시각화를 제공해 왔다. - 주요 데이터에는 다음이 포함된다. - 1.1.1.1 공개 DNS 리졸버의 DNS 질의 - Cloudflare 글로벌 네트워크의 HTTP 트래픽 - Cloudflare Speed Test 기반 네트워크 품질 데이터 - 기존에는 사용자가 적절한 Radar 페이지를 찾고, 필터를 설정하고, API 문서를 읽어야 했다. - AI 도구의 발전으로 데이터셋의 구조와 전문 용어를 몰라도 자연어로 원하는 정보를 얻을 수 있게 되었다. - 기자나 연구자처럼 신속하게 데이터를 확인해야 하는 사용자는 복잡한 탐색 과정을 거치지 않고 바로 분석을 시작할 수 있다. ## 자연어 기반 데이터 질의 - Radar Researcher는 사용자의 질문을 해석해 Radar API에 필요한 데이터 요청을 자동으로 구성한다. - 답변은 단순한 텍스트가 아니라 Radar에서 제공하는 것과 같은 인터랙티브 차트와 간단한 설명으로 제공된다. - 답변의 깊이를 선택할 수 있다. - 짧고 직접적인 답변 - 여러 주제를 다루는 상세 보고서 - 답변 뒤에는 추가로 조사할 만한 후속 질문을 제안한다. - 대화 기록은 검색·고정할 수 있고, 링크로 공유할 수 있다. - 공유 링크는 30일 후 자동 만료된다. - 사용자는 텍스트 입력뿐 아니라 음성 입력이나 Radar 검색창에서도 Researcher를 실행할 수 있다. - 모델이 질문을 어떻게 해석했고, 어떤 데이터셋과 API를 사용했으며, 결과를 어떻게 분석했는지 확인할 수 있다. ## 기존 차트에서 바로 분석 시작 - Radar의 차트에 있는 **Explain with AI** 기능을 사용하면 현재 보고 있는 시각화를 대화의 출발점으로 삼을 수 있다. - 모델에는 다음 세 가지 정보가 함께 전달된다. - 차트 스크린샷: 사용자가 실제로 보는 시각적 맥락 파악 - Radar API의 원시 데이터: 숫자를 픽셀에서 추정하지 않고 정확하게 인용 - 현재 화면의 위치, 날짜 범위, 필터 등 조회 조건 - 따라서 일반적인 차트 설명이 아니라 사용자가 선택한 국가·기간·필터에 정확히 맞춘 분석을 제공한다. ## 사례: 포르투갈의 인터넷 품질 분석 - 사용자는 “포르투갈의 가정용 인터넷 품질은 어떤가?”처럼 자연어로 질문할 수 있다. - Researcher가 인터넷 품질 API를 조회하고 결과를 분석한 뒤, 수치 나열 대신 인터랙티브 차트로 답변한다. - 이후 포르투갈과 인접 국가를 비교하거나, 포르투갈에서 가장 흔한 인터넷 장애를 확인하는 식으로 후속 분석을 이어갈 수 있다. - API 호출 방식이나 파라미터를 직접 알지 않아도 국가별·주제별 비교가 가능하다. ## 사례: 이란 인터넷 셧다운 조사 - 2026년 이란에서 발생한 정부 주도 인터넷 차단 사례를 조사할 때 여러 트래픽 차트와 장애 기록을 직접 찾아 비교할 필요가 없다. - Researcher는 이란의 Cloudflare Radar 장애 이벤트와 관련 HTTP 트래픽 데이터를 함께 조회한다. - 분석 결과를 다음과 같은 타임라인으로 설명한다. - 1월 7일 HTTP 트래픽 지수가 약 0.58에서 시작 - 1월 9일까지 사실상 0으로 하락 - 1월 17일경 부분 회복 시작 - 1월 27일경 셧다운 이전 수준에 근접 - 2월 28일 시작된 두 번째 셧다운도 장애 표에 표시 - 장애 기간은 트래픽 차트 위에 직접 표시되며, 관련 장애 이벤트는 표 형태로 함께 제공된다. - 이후 주변 국가와의 트래픽 비교 같은 추가 조사도 제안한다. ## Cloudflare 개발자 플랫폼으로 구축 - Radar Researcher는 Cloudflare의 자체 개발자 플랫폼 위에서 구현되었다. - 핵심 구성은 다음과 같다. - Cloudflare Worker - Cloudflare Agents SDK - 대화별 상태를 유지하는 Durable Objects - 각 대화의 기록·제목·스트리밍 응답을 저장하는 SQLite 데이터베이스 - Workers AI 기반의 오픈 모델 - 사용자가 페이지를 떠나도 서버에서 응답 생성이 계속되고, 다시 접속하면 결과를 이어받을 수 있다. - 특정 모델이나 제공업체에 의존하지 않도록 세 가지 모델 계열을 순서대로 사용하는 fallback 체인을 구성했다. - 한 모델이 일시적으로 용량 부족 상태가 되면 다른 모델로 자동 전환해 서비스 중단 가능성을 줄인다. - 모든 AI 호출은 AI Gateway를 거친다. ## 실용적인 결론 Radar Researcher는 전문적인 데이터 탐색 과정을 자연어 인터페이스로 감싸, 기자·연구자·네트워크 운영자뿐 아니라 일반 사용자도 Cloudflare Radar의 공개 데이터를 쉽게 활용하게 해준다. 다만 AI의 해석을 그대로 받아들이기보다는 제공되는 API 데이터, 조회 조건, 분석 과정을 함께 확인하는 방식으로 사용하는 것이 적절하다.

cloudflare

MCP의 차세대 기술 (새 탭에서 열림)

지난 1년 반 동안 MCP는 에이전트와 외부 서비스를 연결하는 표준이 되었지만, 기존에는 세션과 연결 상태를 유지해야 해 원격 서버 운영이 복잡했다. 2026-07-28 사양부터 MCP는 완전한 무상태 프로토콜로 바뀌어, 서버가 세션을 저장하거나 sticky session·장기 스트림을 관리하지 않아도 된다. 그 결과 MCP 서버는 Cloudflare Workers 같은 요청 단위 인프라에서 더 저렴하고 간단하게 운영할 수 있다. ## MCP의 무상태 전환 - 기존 MCP는 `initialize`와 `initialized` 교환으로 세션을 만들고, 서버가 `Mcp-Session-Id`를 발급했다. - 이후 모든 요청은 해당 세션의 상태를 찾아야 했기 때문에 다음과 같은 운영 부담이 발생했다. - 오토스케일링 환경에서 세션 보존 - sticky session을 통한 요청 라우팅 - 배포 시 세션 drain 또는 migration - 인스턴스 장애 시 재연결 및 세션 복구 - 새 사양에서는 필수 handshake와 `Mcp-Session-Id`, 프로토콜 세션이 제거됐다. - 각 요청이 MCP 버전, 클라이언트 식별 정보, 클라이언트 capability를 직접 포함한다. - 서버 정보를 미리 확인해야 하는 경우에만 선택적으로 `server/discover`를 호출한다. - MCP 자체에 상태가 필요하지 않으므로 기존 `McpAgent` 없이도 서버를 구현할 수 있다. - 애플리케이션 자체에 상태가 필요할 때는 Durable Objects를 사용할 수 있지만, MCP 프로토콜만 제공하는 서버는 Cloudflare Workers처럼 요청 단위 인프라에서 실행할 수 있다. - Cloudflare SDK에서는 기존 `McpAgent` 대신 `createMcpHandler`로 새 무상태 사양을 지원한다. ## 장기 연결이 필요 없는 Elicitation - Elicitation은 서버가 작업을 완료하기 전에 사용자 입력이나 승인을 요청하는 기능이다. - 운영 배포 승인 - 디자인 색상 선택 - 환불 확인 - 기존에는 `elicitation/create`가 열린 스트림에 의존했다. - 이 방식은 스트림 유지, 타임아웃, 비용, 로드 밸런싱을 복잡하게 만들었다. - 새 사양은 Multi Round-Trip Requests(MRTR)를 사용한다. - 서버가 `input_required` 결과를 반환한다. - 클라이언트가 사용자 입력을 수집한다. - 클라이언트가 입력값과 함께 작업을 재시도한다. - 서버가 작업을 완료한다. - 요청 사이에 연결이나 transport session을 보존할 필요가 없다. - 기존 Elicitation 방식과 호환되지 않는 breaking change이지만, 구현과 운영은 훨씬 단순해진다. ## HTTP 인프라가 MCP 요청을 직접 이해 - 기존에는 MCP 요청의 메서드와 대상이 JSON-RPC 본문 안에만 있어, 게이트웨이가 내용을 파싱해야 했다. - 새 Streamable HTTP 요청에는 다음 헤더가 필수로 추가된다. - `Mcp-Protocol-Version` - `Mcp-Method` - `Mcp-Name` - 예를 들어 도구 호출은 `Mcp-Method: tools/call`, `Mcp-Name: search`로 표현할 수 있다. - 게이트웨이, rate limiter, WAF가 JSON 본문을 해석하지 않고도 요청 종류별 정책을 적용할 수 있다. - 도구별 metrics 수집, 메서드별 rate limit, 보안 규칙 적용도 기존 HTTP 인프라 방식으로 처리할 수 있다. ## 캐시와 도구 목록 개선 - `tools/list`, `prompts/list`, `resources/list`, `resources/read` 결과에 다음 힌트가 추가된다. - `ttlMs`: 결과를 얼마나 오래 캐시할 수 있는지 나타냄 - `cacheScope`: 캐시 적용 범위를 나타냄 - 도구 카탈로그는 결정론적으로 정렬된다. - 클라이언트가 연결이 끊겼다가 다시 연결되어도 카탈로그를 재사용하기 쉬워진다. - upstream prompt cache가 불필요하게 무효화되는 문제도 줄일 수 있다. ## 인증 체계의 변화 - 새 사양은 MCP 인증 방식의 우선순위를 정비한다. - 서버와 클라이언트 사이에 사전 관계가 있다면 사전 등록된 클라이언트를 우선 사용한다. - 동적 등록이 필요하면 Client ID Metadata Documents(CIMD)를 사용한다. - Dynamic Client Registration(DCR)은 최후의 수단으로 남지만, 신규 구현에서는 deprecated되었다. ## 실용적인 결론 새 MCP 서버는 세션 저장소나 장기 연결을 기본 전제로 설계할 필요가 없다. 단순한 도구·프롬프트·리소스 서버라면 `createMcpHandler`와 요청 단위 실행 환경을 사용하고, 애플리케이션 자체에 지속 상태나 실시간 협업이 필요할 때만 Durable Objects 같은 상태ful 인프라를 선택하는 것이 권장된다.

cloudflare

Flue를 시작으로 Cloudflare에 더 많은 에이전트 하네스 도입하기 (새 탭에서 열림)

2026년에는 AI 에이전트가 프로토타입을 넘어 실제 운영 인프라로 사용되면서, 중단 복구·보안 실행·도구 연동 같은 분산 시스템 문제가 중요해지고 있다. 글은 이를 해결하기 위해 **프레임워크(Flue)–하네스(Pi, Project Think)–런타임(Cloudflare Agents SDK)**의 3계층 구조가 필요하다고 주장한다. Flue는 선언적으로 에이전트를 정의하고, Cloudflare Agents SDK는 내구성 있는 실행·상태·스토리지·샌드박스를 제공해 프로덕션 환경의 안정성을 높인다. ## 프로덕션 에이전트를 위한 3계층 구조 - **프레임워크: Flue** - 프로젝트 구조, 규칙, 외부 서비스 통합, CLI, 개발자 경험을 제공한다. - 에이전트를 실제 업무 환경에 배치하고 관리하는 상위 계층이다. - **하네스: Pi, Project Think** - 모델의 에이전트 루프를 담당한다. - 도구 호출, 결과 확인, 컨텍스트 관리, 작업 완료까지의 반복 과정을 처리한다. - **런타임/플랫폼: Cloudflare Agents SDK** - 에이전트가 의존하는 컴퓨트, 상태 관리, 스토리지 primitives를 제공한다. - 특정 하네스에 종속되지 않고 다양한 하네스와 프레임워크가 사용할 수 있는 기반 계층이다. ## Flue의 선언적 에이전트 모델 - Flue 1.0 Beta는 Pi 하네스를 기반으로 하며, OpenClaw와 같은 하네스를 사용한다. - 에이전트가 무엇을 할지 절차적으로 스크립팅하는 대신, 에이전트가 알아야 할 내용을 선언한다. - 사용할 모델 - 필요한 스킬 - 실행 샌드박스 - 시스템 지침 - 별도의 오케스트레이션 루프를 직접 작성하지 않아도 에이전트가 주어진 작업을 자율적으로 수행한다. - 예를 들어 버그 리포트를 받아 샌드박스에서 재현하고 원인을 진단하는 에이전트를 25줄 이하로 작성할 수 있다. ## 개발자 도구와 외부 서비스 통합 - **Channels** - Slack, GitHub, Linear, Discord 등에 에이전트를 연결한다. - 이벤트 검증과 디스패치에 필요한 반복적인 보일러플레이트를 대신 처리한다. - **헤드리스 실행과 UI 연동** - 백그라운드 작업에서는 완전히 헤드리스로 실행할 수 있다. - `@flue/react`를 사용하면 에이전트 상태, 도구 실행, 실시간 메시지를 프론트엔드로 스트리밍할 수 있다. - 별도의 실시간 통신 인프라를 직접 구축할 필요를 줄인다. - **CLI 기반 생태계 확장** - `flue add channel slack` 같은 명령으로 통합 기능을 추가한다. - 생성된 Markdown blueprint를 코딩 에이전트가 읽고 수정해 기존 코드베이스에 통합할 수 있다. ## Durable Streams를 통한 장애 복구 - 에이전트 실행은 모델 응답 스트리밍, 도구 호출, 도구 결과 대기, 사용자 승인, 하위 에이전트 위임 등 여러 단계로 구성된다. - 호스트 장애, LLM API 타임아웃, 프로세스 재시작이 발생하면 메모리에 있던 실행 상태가 사라질 수 있다. - Flue는 **Durable Streams**를 사용해 실행 이력을 append-only 로그로 기록한다. - 프롬프트 - 도구 응답 - 모델 선택 - 기타 실행 이벤트 - 각 이벤트를 변경할 수 없는 원장처럼 저장하므로 프로세스가 종료되어도 다른 프로세스가 마지막 로그부터 실행을 이어갈 수 있다. - 결과적으로 에이전트가 작업 중이던 정확한 단계에서 복구되고, 사용자가 영원히 끝나지 않는 로딩 상태를 보는 문제를 줄인다. ## 다양한 환경에 배포하는 방식 - Node.js에서는 에이전트를 장시간 실행되는 프로세스로 배포할 수 있다. - VM, 컨테이너, GitHub Actions, 기존 서버 등에 배포할 수 있어 멀티클라우드 구성이 가능하다. - Cloudflare 환경에서는 각 Flue 에이전트가 하나의 **Durable Object**로 실행된다. - 에이전트별 독립적인 컴퓨트와 스토리지를 제공한다. - 필요한 에이전트 수만큼 자동 확장할 수 있다. - 서버 프로비저닝, sticky session, noisy neighbor 문제를 신경 쓰지 않아도 된다. ## Cloudflare Agents SDK의 실행 primitives - Cloudflare에 배포된 Flue는 Agents SDK의 다음 기능을 사용해 내구성 있는 실행을 구현한다. - `runFiber()`: 에이전트 실행을 중단·복구 가능한 작업 단위로 관리 - `stash()`: 실행 중인 상태를 보존 - `onFiberRecovered()`: 복구된 실행을 다시 처리 - `@cloudflare/codemode`와 `@cloudflare/shell`을 활용해 샌드박스 안에서 코드를 실행한다. - 이 코드는 Durable Workspace와 결합되어 에이전트가 지속적으로 사용할 수 있는 작업 공간을 제공한다. ## 하네스가 플랫폼에 요구하는 것 - 에이전트 턴은 단순한 단일 HTTP 요청이 아니라 수초에서 수분간 이어지는 상태ful한 실행이다. - 실행 중 다음과 같은 단계가 발생할 수 있다. - 모델 토큰 스트리밍 - 도구 호출 - 도구 결과 대기 - 사람의 승인 요청 - 하위 에이전트 위임 - 프로세스가 중단되면 스트리밍 연결, 대기 중인 도구 호출, 현재 실행 위치 등 메모리 상태가 사라진다. - 대화 기록만 디스크에 저장되어 있어도 사용자는 완료되지 않는 스피너를 보게 되므로 충분하지 않다. - 따라서 현대적인 하네스에는 실행 중간 상태를 체크포인트로 저장하고 장애 후 이어서 실행할 수 있는 **durable execution**이 필수다. - 글은 Cloudflare Agents SDK의 Fiber가 이러한 체크포인트와 복구를 위한 네이티브 메커니즘을 제공한다고 설명하기 시작하며, 이후 세부 동작은 제공된 본문에서 이어지지 않는다. 에이전트를 실제 서비스로 운영하려면 모델 호출 로직만 구현해서는 부족하다. Flue 같은 프레임워크로 개발 경험과 통합을 단순화하고, Pi 같은 하네스로 에이전트 루프를 처리하며, Durable Objects와 Durable Streams 같은 플랫폼 primitives로 상태 보존·장애 복구·안전한 코드 실행을 확보하는 구성이 실용적이다.