소개: Cloudflare Agents (새 탭에서 열림)
Cloudflare는 에이전트를 배포·관찰·개선할 수 있는 통합 관리 환경인 Cloudflare Agents를 공개했으며, 첫 기능으로 에이전트 트레이싱을 제공한다. 이 기능은 모델 호출, 도구 실행, 토큰 사용량, 승인 대기, 서브에이전트 작업과 Workers 인프라 동작을 하나의 추적으로 연결해 에이전트의 실제 동작과 비용을 파악하게 한다. 이를 통해 단순한 요청 성공 여부를 넘어 잘못된 도구 선택, 재시도 루프, 오래된 컨텍스트 전달 같은 문제를 분석하고 지속적으로 개선할 수 있다. ## 에이전트 관찰 가능성이 필요한 이유 - 에이전트는 HTTP 200을 반환하더라도 잘못된 도구를 선택하거나, 서브에이전트에 오래된 컨텍스트를 전달하거나, 토큰을 재시도 루프에서 낭비할 수 있다. - 기존 애플리케이션 텔레메트리는 API 요청이나 데이터베이스 쿼리는 보여주지만, 그 동작을 유발한 에이전트의 판단 과정은 보여주지 못한다. - 에이전트 수준의 텔레메트리는 다음 질문에 답해야 한다. - 지연 시간은 모델, 도구, 인프라 중 어디에서 발생했는가? - 승인 대기로 턴이 중단되었는가? - 어떤 모델을 호출했고 토큰을 얼마나 사용했는가? - 올바른 도구를 선택했는가? - 외부 API가 성공했는가, 타임아웃되었는가? - 어떤 서브에이전트가 작업했고 최종 응답에 어떤 영향을 주었는가? ## 에이전트 트레이싱의 범위 - 기존 Workers 트레이싱은 `fetch`, KV, D1 등 인프라 계층의 동작을 기록했다. - 새 에이전트 트레이싱은 여기에 다음과 같은 에이전트 전용 span을 추가한다. - 에이전트 호출 - 모델 호출 - 도구 실행 - 승인 이벤트 - 지원되는 서브에이전트 호출 - 모델명과 토큰 사용량 같은 정보도 메타데이터로 연결된다. - Think, Flue, AI SDK로 만든 에이전트는 Cloudflare 대시보드에서 추적을 확인하거나 OpenTelemetry 호환 대상에 내보낼 수 있다. ## 세션 리플레이로 판단 과정 확인 - Agents 대시보드의 Messages 탭에서는 특정 턴의 전체 대화를 재구성한다. - 시스템 지침 - 사용자 메시지 - 모델의 사고 과정 - 도구 호출 인자와 결과 - 최종 응답 - 이는 에이전트를 다시 실행하는 것이 아니라 기록된 데이터를 재생하는 기능이다. - 잘못된 도구 인자, 도구 선택 당시의 컨텍스트, 서브에이전트 핸드오프, 이전 턴이 이후 결과에 미친 영향을 분석할 수 있다. - Think, Flue, AI SDK에서는 `storeMessages`와 `storeTools` 설정으로 메시지 및 도구 payload 저장 여부를 제어한다. - 개인정보, 비밀값, 민감한 데이터가 포함될 수 있다면 payload 기록을 끄는 것이 권장된다. ## 실행 워터폴과 서브에이전트 추적 - Traces 탭은 각 턴의 실행 과정을 시간순 워터폴로 보여준다. - 부모 에이전트에서 서브에이전트, 모델, 도구, 데이터 저장소까지 하나의 흐름으로 연결된다. - 예시에서는 다음 작업을 한 화면에서 확인할 수 있다. - `TravelPlanner` 부모 에이전트 호출 - `itinerary_builder` 서브에이전트 호출 - `@cf/zai-org/glm-4.7-flash` 모델 호출과 토큰 사용량 - `record_itinerary_builder_execution` 도구 실행 - D1 쿼리 실행 - `record_respond_ready` 도구 실행 - KV 쓰기 - 부모 에이전트와 서브에이전트에는 에이전트 클래스, 대화, Durable Object 식별자가 연결되어 추적 간 상관관계를 파악할 수 있다. - KV, D1, Durable Object, 서비스 바인딩, `fetch` 등 Workers 리소스는 이를 호출한 에이전트 작업 아래에 중첩되어 표시된다. ## 트레이싱 활성화 방법 - 먼저 `wrangler.jsonc`에서 Workers 관찰 기능을 활성화한다. ```json { "observability": { "traces": { "enabled": true } } } ``` - 사용하는 에이전트 스택에 따라 추가 설정이 필요하다. - Think·Flue: 자체 트레이싱 통합 기능으로 에이전트, 대화, 턴, 모델, 도구 텔레메트리 전송 - AI SDK: Cloudflare의 `wrapAISDK()` 어댑터로 SDK 감싸기 - 사용자 정의 하네스: 커스텀 span API와 OpenTelemetry Generative AI 의미 규약 사용 ## OpenTelemetry 기반 확장과 외부 전송 - Cloudflare는 향후 Workers 내부에서 OpenTelemetry API를 직접 지원할 예정이다. - 표준 OpenTelemetry Generative AI span을 생성하는 프레임워크는 Cloudflare 전용 어댑터 없이 Agents 화면에서 시각화될 수 있다. - 표준 에이전트 및 대화 식별자가 포함되면 Cloudflare의 내장 통합처럼 에이전트와 세션 단위로 그룹화할 수 있다. - 추적 데이터는 Cloudflare에 종속되지 않으며, Wrangler 설정에서 OTLP 호환 제공자를 지정해 외부 관찰성 플랫폼으로 내보낼 수 있다. 에이전트 운영을 시작한다면 먼저 트레이싱을 활성화하고 메시지·도구 payload 저장 시 개인정보 노출 여부를 검토하는 것이 좋다. 이후 세션 리플레이로 판단 오류를 찾고, 워터폴 추적으로 모델·도구·인프라별 지연 시간과 비용을 분석하면 안정성과 효율을 체계적으로 개선할 수 있다.