Cloudflare hỗ trợ AI Agent tự động gỡ lỗi Workers ngay trên môi trường local

Kể từ hôm nay, wrangler dev và vite dev sẽ tự động thu thập các OpenTelemetry trace cho các lần gọi Worker cục bộ. Khi bộ công cụ của Cloudflare phát hiện một phiên làm việc của agent, nó sẽ hướng agent đó đến Local Explorer API, một API gỡ lỗi cục bộ nơi agent có thể truy vấn các trace này. Bạn không cần phải cài đặt SDK, bật tính năng tracing, cấu hình agent hay thậm chí là đề cập đến khả năng quan sát (observability) trong câu lệnh prompt.

Một câu lệnh prompt có thể đơn giản như sau:

Điều này được xây dựng dựa trên nhiều năm đầu tư vào phát triển cục bộ, từ việc giới thiệu Miniflare cho đến việc biến chế độ cục bộ (local mode) thành mặc định trong Wrangler 3. Các trace cục bộ cung cấp cho các coding agent phản hồi có cấu trúc từ chính môi trường phát triển đó trước khi mã nguồn được triển khai.

Các agent tự động khám phá Local Explorer API

Là một phần trong quy trình làm việc thông thường, một agent sẽ khởi chạy wrangler dev hoặc vite dev để chạy và kiểm thử Worker. Khi máy chủ phát triển nhận diện được một phiên làm việc của coding-agent được hỗ trợ, nó sẽ tự động in ra một gợi ý có dạng như sau:

Local Explorer là giao diện dựa trên trình duyệt và REST API dùng để xem, chỉnh sửa dữ liệu tài nguyên cục bộ và truy vấn dữ liệu quan sát trong quá trình phát triển. API root cung cấp một OpenAPI schema, vì vậy các agent có thể khám phá các endpoint khả dụng tại thời điểm chạy (runtime) mà không cần các chỉ dẫn được mã hóa cứng (hardcoded).

Các trace được thu thập tự động sẽ khả dụng thông qua một endpoint quan sát chỉ đọc (read-only) trong API đó, cùng với các log console tương ứng. Agent có thể truy vấn dữ liệu đo lường (telemetry) này, sau đó sử dụng các thao tác khác của API để kiểm tra các Worker và binding cục bộ, hoặc xem xét trạng thái trong D1, KV, R2, Durable Objects và Workflows.

Tìm lỗi và xác minh bản sửa lỗi

Hãy xem xét POST /api/orders, lệnh này truy xuất giỏ hàng đang hoạt động từ KV, lưu chi tiết thanh toán vào D1 và gửi tin nhắn đến Queue để xử lý đơn hàng. Sau khi thay đổi schema, endpoint đột ngột trả về trạng thái 500.

Nếu không có trace cục bộ

Lỗi 500 không xác định được thao tác nào đã thất bại. Agent sẽ thêm log xung quanh KV, D1 và Queue, chạy lại yêu cầu, kiểm tra đầu ra và lặp lại quy trình. Mỗi chu kỳ đều tốn thời gian và tiêu tốn token trong khi agent phải tái cấu trúc yêu cầu từ văn bản.

Với trace cục bộ

Agent tái hiện lỗi và truy vấn endpoint quan sát chỉ đọc. Trace cho thấy việc đọc KV thành công, việc chèn vào D1 thất bại với lỗi no such column: delivery_window, và Queue chưa bao giờ được gọi. Agent của bạn sử dụng Local Explorer API để truy cập cùng dữ liệu trace mà bạn sẽ thấy ở đây:

Agent sử dụng API để kiểm tra schema của D1. Nó phát hiện ra rằng migration thêm delivery_window đã tồn tại trong kho lưu trữ nhưng chưa được áp dụng cục bộ, nó tiến hành áp dụng migration, gửi lại yêu cầu và truy vấn trace mới. Vấn đề đã được giải quyết.

Chỉ trong một vòng lặp cục bộ, agent xác định được thao tác thất bại, sửa môi trường cục bộ và xác minh kết quả mà không cần triển khai (deploy) hay thêm các log tạm thời.

Khám phá trace và log trong Local Explorer

Các agent truy vấn dữ liệu đo lường cục bộ thông qua API, nhưng bạn với tư cách là con người có thể trực quan hóa cùng dữ liệu đó trong Local Explorer, giao diện dựa trên trình duyệt được tích hợp sẵn trong máy chủ phát triển cục bộ. Bên cạnh việc duyệt trạng thái binding cục bộ, bạn có thể chọn một yêu cầu để kiểm tra các span, thời gian, thuộc tính, lỗi và các log console tương ứng.

Local Explorer chạy trên cùng localhost origin với Worker của bạn, không phải trên bảng điều khiển Cloudflare. Nhấn phím e trong Wrangler hoặc truy cập /cdn-cgi/explorer trên máy chủ cục bộ để mở nó.

Cách thức hoạt động

Khi chúng tôi ra mắt Workers Tracing, chúng tôi đã tích hợp công cụ đo lường trực tiếp vào workerd, runtime mã nguồn mở cung cấp sức mạnh cho Workers. Mà không cần yêu cầu SDK hay bất kỳ thay đổi mã nguồn nào, runtime sẽ tự động thu thập các span cho:

Bất kỳ span tùy chỉnh nào do ứng dụng của bạn phát ra cũng sẽ xuất hiện cùng với các span tự động này.

Wrangler và plugin Cloudflare Vite sử dụng Miniflare để chạy Worker của bạn cục bộ trên cùng một runtime, giúp công cụ đo lường này khả dụng trong quá trình phát triển cục bộ.

Miniflare thu thập các sự kiện runtime và đầu ra console, tập hợp chúng thành các OpenTelemetry trace và log tương ứng, sau đó ghi dữ liệu đo lường vào một Durable Object dựa trên SQLite nội bộ đóng vai trò là kho lưu trữ trace cục bộ. Local Explorer API hiển thị dữ liệu đó thông qua máy chủ phát triển cục bộ, nơi các agent có thể dễ dàng truy vấn trace, log và kiểm tra trạng thái cục bộ.

Bắt đầu

Cập nhật Wrangler hoặc plugin Cloudflare Vite, tùy thuộc vào công cụ mà dự án của bạn đang sử dụng:

Sau đó, hãy yêu cầu agent của bạn gỡ lỗi cục bộ như cách bạn vẫn thường làm. Agent của bạn đã có thể viết và chạy Worker cục bộ — giờ đây nó còn có thể thấy chuyện gì đã xảy ra, sửa lỗi thất bại và xác minh kết quả trước khi bạn triển khai. Hãy xem tài liệu để tìm hiểu thêm!