Xây dựng quy trình tác tử AI bất đồng bộ, bền bỉ với Unreal Agent

Unreal Agent là gì?

Unreal Agent là một agent harness ưu tiên xử lý bất đồng bộ do Unreal Labs phát triển. Công cụ này cung cấp hạ tầng có thể kết hợp để tiếp nhận đầu vào, duy trì lịch sử phiên, chuẩn bị ngữ cảnh cho mô hình, điều phối các lượt gọi LLM, chuyển đổi lệnh gọi công cụ và phân phối các tác vụ bất đồng bộ bền vững.

Dự án tách biệt việc điều phối đồng bộ khỏi quá trình thực thi bất đồng bộ. Các bộ chuyển đổi công cụ xác thực yêu cầu do mô hình tạo ra và tạo ra mô tả thao tác có thể tuần tự hóa mà không thực hiện I/O. Sau đó, một trình quản lý thao tác thực thi các thao tác đã được cam kết bên ngoài event loop của bộ điều phối.

Cấu trúc kho lưu trữ

Kho lưu trữ được tổ chức thành ba khu vực chính:

• harness/: Thư viện agent harness có thể tái sử dụng.
• cmd/: Các tệp thực thi được xây dựng bằng thư viện.
• benchmarks/: Các trình chạy benchmark để đánh giá dự án.

Bắt đầu với harness/ khi tích hợp framework vào một ứng dụng khác. Xem cmd/ để tìm các điểm vào cụ thể của tệp thực thi, và sử dụng benchmarks/ khi cần kiểm tra hoặc đo lường hành vi thời gian chạy.

Các khái niệm cốt lõi

Đầu vào và Inbox

Một đầu vào là một sự kiện mang mã định danh duy nhất trên toàn cầu do bên gọi cung cấp. Mã định danh đó phải được giữ nguyên nếu sự kiện được phân phối lại.

Inbox của phiên sử dụng các mã định danh này để loại bỏ trùng lặp trong bộ nhớ đối với các đầu vào bên ngoài, điều khiển và sự cố. Tính chất idempotent này chỉ áp dụng trong phạm vi phiên và không bền vững, vì vậy bên gọi vẫn nên cung cấp các ID ổn định một cách nhất quán.

{
  "id": "globally-unique-and-stable-id",
  "type": "external-input",
  "payload": "Example request"
}

Cấu trúc này mang tính khái niệm, không phải là một kiểu API Unreal Agent được tài liệu hóa. Yêu cầu quan trọng là ID đầu vào phải ổn định và duy nhất trên toàn cầu.

Phiên

Một phiên là lịch sử được lưu trữ theo dạng chỉ ghi thêm. Các phiên có thể được tiếp tục và phân nhánh, cho phép ứng dụng tiếp tục công việc hiện có hoặc tạo nhánh từ lịch sử trước đó mà không viết lại chuỗi ban đầu.

Kho lưu trữ phiên sở hữu lịch sử chuẩn và trạng thái thao tác. Kho lưu trữ cũng ghi nguyên tử trạng thái chuyển đổi của một lệnh gọi công cụ cùng với mọi thao tác được tạo ra từ quá trình chuyển đổi đó.

Các lượt LLM

Một lượt LLM là chuỗi do bộ điều phối quản lý, bao quanh một yêu cầu logic duy nhất tới mô hình. Bộ điều phối lưu các đầu vào được chấp nhận, chuẩn bị lượt gọi, phân giải các bộ chuyển đổi công cụ, ghi lại công việc phát sinh và phân phối các thao tác đã được cam kết.

Công cụ, bộ chuyển đổi và thao tác

Một công cụ kết hợp một schema với một bộ chuyển đổi. Khi mô hình tạo ra một lệnh gọi công cụ, bộ chuyển đổi sẽ xác thực lệnh gọi đó và chuyển đổi thành một hoặc nhiều thao tác.

Bộ chuyển đổi công cụ chạy đồng bộ trên event loop của bộ điều phối. Bộ chuyển đổi không được thực hiện I/O hoặc tạm dừng event loop.

Kết quả chuyển đổi được gọi là trạng thái lệnh gọi công cụ. Kết quả này chứa либо lỗi xác thực hoặc các tham chiếu đến những thao tác đã gửi. Trạng thái này khác với trạng thái thực thi của các thao tác đó.

Một thao tác là mô tả công việc bất đồng bộ có thể tuần tự hóa và được lập phiên bản. Bộ chuyển đổi mô tả công việc; trình quản lý thao tác thực hiện công việc đó.

Các thành phần chính

• Inbox phiên: Cung cấp tính idempotent của đầu vào trong bộ nhớ, chỉ áp dụng trong phạm vi phiên.
• Bộ điều phối: Lưu các đầu vào được chấp nhận, quản lý các lượt LLM, phân giải bộ chuyển đổi công cụ và phân phối các thao tác đã cam kết.
• Kho lưu trữ phiên: Lưu lịch sử phiên chuẩn và trạng thái thao tác, hỗ trợ khôi phục và phân nhánh, đồng thời ghi nguyên tử trạng thái lệnh gọi công cụ cùng với các thao tác.
• Bộ dựng ngữ cảnh: Tập hợp đầu vào cho mô hình trong bộ nhớ và báo cáo nội dung bị bỏ qua, cắt ngắn hoặc nén. Thành phần này không thực hiện I/O và không phụ thuộc vào việc lưu trữ.
• Bộ điều hợp LLM: Gửi đầu vào đã chuẩn bị đến nhà cung cấp mô hình và trả về phản hồi hoàn tất đã được chuẩn hóa. Thành phần này phụ trách xác thực, hủy và lỗi từ nhà cung cấp.
• Registry công cụ: Sở hữu định nghĩa và bộ chuyển đổi của các công cụ Bash, ViewImage và skill-use, đồng thời cung cấp tập công cụ do host lựa chọn.
• Bộ chuyển đổi công cụ: Xác thực các lệnh gọi, tạo trạng thái và thao tác, đồng thời định dạng trạng thái đã ghi và đầu ra thao tác đã chuẩn bị cho mô hình.
• Trình quản lý thao tác: Cung cấp runtime actor cho các thao tác bền vững. Có thể thay thế triển khai cục bộ.

Cài đặt và thiết lập

README không nêu trình quản lý gói, lệnh cài đặt theo ngôn ngữ cụ thể hoặc API công khai ổn định. Vì vậy, nên bắt đầu thiết lập từ một bản checkout cục bộ của kho lưu trữ và siêu dữ liệu build, thay vì giả định một lệnh cài đặt gói.

1. Clone hoặc tải kho lưu trữ Unreal Agent.
2. Mở thư mục gốc của kho lưu trữ và kiểm tra các tệp build cùng tệp dependency để xác định toolchain được hỗ trợ.
3. Build hoặc cài đặt thư viện trong harness/ bằng công cụ đã được cấu hình cho kho lưu trữ.
4. Kiểm tra cmd/ để tìm các ví dụ tệp thực thi kết hợp những thành phần của harness.
5. Chỉ sử dụng benchmarks/ sau khi dự án cốt lõi build thành công.

cd <unreal-agent-repository>

# Kiểm tra các thư mục thư viện, tệp thực thi và benchmark.
ls harness
ls cmd
ls benchmarks

Ứng dụng host cũng cần một bộ điều hợp LLM được cấu hình cho nhà cung cấp mà ứng dụng lựa chọn. Việc xác thực, hành vi khi hủy và xử lý lỗi đặc thù của nhà cung cấp thuộc về bộ điều hợp đó.

Cách sử dụng cơ bản: Theo dõi một yêu cầu của agent

Vì README không công bố tên constructor hoặc phương thức cụ thể, cách an toàn nhất để hiểu cách sử dụng là theo dõi luồng thành phần được mô tả trong tài liệu.

1. Tạo hoặc tiếp tục một phiên. Kho lưu trữ phiên cung cấp lịch sử đã lưu và hỗ trợ khôi phục.
2. Gửi một đầu vào với ID ổn định. Sử dụng lại cùng ID khi gửi lại cùng một sự kiện logic.
3. Loại bỏ trùng lặp thông qua hộp thư đến của phiên. Hộp thư đến từ chối hoặc bỏ qua các đầu vào lặp lại trong phiên đang hoạt động, tùy theo cách triển khai.
4. Lưu đầu vào đã được chấp nhận. Bộ điều phối ghi đầu vào vào lịch sử phiên chuẩn chỉ được nối thêm.
5. Xây dựng ngữ cảnh cho mô hình. Bộ dựng ngữ cảnh tập hợp đầu vào mô hình trong bộ nhớ và báo cáo mọi nội dung đã bỏ qua, cắt ngắn hoặc cô đọng.
6. Chạy lượt LLM. Bộ chuyển đổi LLM gửi đầu vào đã chuẩn bị đến nhà cung cấp và trả về phản hồi hoàn tất đã được chuẩn hóa.
7. Giải quyết các lệnh gọi công cụ. Bộ điều phối tra cứu từng công cụ được phép thông qua registry.
8. Dịch đồng bộ. Bộ chuyển đổi được chọn xác thực lệnh gọi và tạo ra lỗi xác thực hoặc các thao tác có thể tuần tự hóa.
9. Cam kết nguyên tử. Kho lưu trữ phiên ghi trạng thái lệnh gọi công cụ và các thao tác cùng nhau.
10. Phân phối bất đồng bộ. Trình quản lý thao tác thực thi các thao tác đã cam kết và theo dõi trạng thái thực thi của chúng riêng với trạng thái dịch.
11. Định dạng kết quả cho mô hình. Bộ chuyển đổi kết hợp trạng thái lệnh gọi đã ghi với đầu ra thao tác đã chuẩn bị để tạo kết quả dành cho mô hình.

Vòng đời lệnh gọi công cụ mẫu

Đầu vào với ID ổn định
  -> loại bỏ trùng lặp trong hộp thư đến
  -> sự kiện phiên đã lưu
  -> xây dựng ngữ cảnh
  -> phản hồi LLM đã chuẩn hóa
  -> tra cứu registry công cụ
  -> xác thực và dịch đồng bộ
  -> cam kết nguyên tử trạng thái và thao tác
  -> thực thi thao tác bất đồng bộ
  -> định dạng kết quả dành cho mô hình

Nếu xác thực thất bại, bộ chuyển đổi ghi nhận lỗi xác thực thay vì tạo thao tác. Nếu xác thực thành công, trạng thái tham chiếu đến các thao tác đã gửi, trong khi trình quản lý thao tác theo dõi độc lập việc các thao tác đó đang chờ, đang chạy, đã hoàn tất hay được xử lý theo cách khác bởi phần triển khai.

Lựa chọn công cụ

Registry công cụ quản lý các định nghĩa và bộ chuyển đổi cho Bash, ViewImage và việc sử dụng skill. Máy chủ chọn những công cụ nào được cung cấp.

Chỉ cung cấp các khả năng cần thiết cho từng môi trường triển khai. README không quy định chính sách ủy quyền hoặc sandbox, vì vậy môi trường máy chủ và lớp thực thi thao tác nên xử lý các vấn đề đó.

Mở rộng Harness

Các thành phần của Unreal Agent được thiết kế để có thể kết hợp. Có thể thay thế các phần triển khai dựa trên interface, miễn là chúng duy trì các trách nhiệm và bất biến đã được tài liệu hóa.

Triển khai bộ chuyển đổi công cụ

Bộ chuyển đổi tùy chỉnh nên tuân theo trình tự sau:

1. Xác thực các đối số do mô hình tạo ra theo schema của công cụ.
2. Trả về lỗi xác thực khi yêu cầu không hợp lệ.
3. Khi hợp lệ, tạo một hoặc nhiều mô tả thao tác có thể tuần tự hóa và có phiên bản.
4. Trả về trạng thái tham chiếu đến các thao tác đã gửi.
5. Cung cấp logic định dạng để chuyển đổi trạng thái đã ghi và đầu ra thao tác đã chuẩn bị thành kết quả dành cho mô hình.

Giữ cho việc dịch mang tính xác định và nhanh chóng. Không thực hiện yêu cầu mạng, truy cập tệp, chờ tiến trình con hoặc thực hiện I/O khác bên trong bộ chuyển đổi.

Thay thế trình quản lý thao tác

Trình quản lý thao tác cục bộ có thể thay thế. Một phần mở rộng được tài liệu hóa là trình quản lý proxy tuần tự hóa các thao tác và gửi chúng đến một trình quản lý thao tác cục bộ khác đang chạy bên trong tiến trình sandbox từ xa.

Thiết kế này giúp bộ điều phối và các bộ chuyển đổi tập trung vào việc xác thực và ý định bền vững, đồng thời cho phép thực thi trong một môi trường biệt lập.

Triển khai lớp lưu trữ

Các kho lưu trữ phiên thay thế phải duy trì khả năng tuần tự hóa, quản lý phiên bản, hành vi khôi phục và mối quan hệ nguyên tử giữa trạng thái lệnh gọi công cụ với các thao tác được tạo ra.

Dự án hướng đến việc duy trì khả năng tương thích ngược cho các phiên. Nếu phiên sử dụng phiên bản không được hỗ trợ, việc tiếp tục phiên phải thất bại với lỗi rõ ràng thay vì âm thầm đọc sai dữ liệu.

Mẹo nâng cao

• Tạo ID đầu vào tại ranh giới của bên gọi. Lưu ID cùng với sự kiện khởi nguồn để các lần thử lại và gửi lại vẫn giữ nguyên danh tính.
• Không nhầm lẫn việc loại trùng trong inbox với lịch sử lâu bền. Inbox dễ mất dữ liệu và chỉ áp dụng trong phạm vi phiên, trong khi session store lưu các sự kiện chuẩn tắc một cách lâu bền.
• Giữ các bộ chuyển đổi thuần túy và đồng bộ. Chuyển các yêu cầu thành các thao tác thay vì trực tiếp thực hiện công việc.
• Định phiên bản cho mọi định dạng thao tác. Các thao tác có thể tồn tại lâu hơn tiến trình đã tạo chúng hoặc đi qua ranh giới giữa các tiến trình và sandbox.
• Bảo toàn các lần commit nguyên tử. Việc ghi nhận trạng thái gọi công cụ thành công mà không ghi kèm các thao tác có thể khiến một phiên rơi vào trạng thái không nhất quán sau sự cố.
• Theo dõi riêng việc chuyển đổi và thực thi. Một lệnh gọi hợp lệ có thể tạo ra một thao tác đã được commit nhưng chưa hoàn tất.
• Sử dụng metadata của context builder. Theo dõi những gì đã bị lược bỏ, cắt ngắn hoặc nén để có thể chẩn đoán hành vi của mô hình.
• Tập trung hóa các mối quan tâm của provider. Giữ thông tin xác thực, việc hủy và lỗi của provider bên trong bộ điều hợp LLM.
• Tạo nhánh phiên để thử nghiệm. Một nhánh có thể khám phá hướng tiếp diễn khác trong khi vẫn bảo toàn lịch sử chỉ được ghi thêm của phiên nguồn.
• Sử dụng proxy operation manager để cô lập. Các thao tác đã tuần tự hóa có thể được chuyển tiếp đến một runtime bên trong sandbox từ xa mà không cần chuyển việc chuyển đổi đồng bộ sang đó.

Các bất biến quan trọng

Các phần mở rộng nên duy trì những bảo đảm sau:

• Các mục trong session store vẫn có thể tuần tự hóa.
• Định dạng lưu trữ vẫn được định phiên bản.
• Các phiên bản phiên không được hỗ trợ phải tạo ra lỗi tiếp tục phiên rõ ràng.
• Các thao tác vẫn có thể tuần tự hóa và được định phiên bản.
• Việc xây dựng ngữ cảnh không thực hiện I/O và không nhận các phụ thuộc lưu trữ.
• Việc chuyển đổi công cụ không thực hiện I/O và không bao giờ tạm dừng event loop của coordinator.

Kết luận

Unreal Agent cung cấp nền tảng mô-đun cho các agent cần phiên lâu bền, đầu vào được loại trùng, các lượt LLM được điều phối, lệnh gọi công cụ được xác thực và công việc bất đồng bộ lâu bền. Nguyên tắc thiết kế trung tâm là ranh giới rõ ràng giữa việc chuyển đổi đồng bộ và thực thi bất đồng bộ. Hãy bắt đầu với các executable hiện có, tuân theo luồng sự kiện được tài liệu hóa, đồng thời bảo toàn tính tuần tự hóa, định phiên bản và tính nguyên tử khi thay thế hoặc mở rộng các thành phần.