Xây dựng và tự lưu trữ các cộng sự AI với useAgent

Cảnh báo Alpha: useAgent đang được phát triển tích cực. API và schema có thể thay đổi giữa các bản phát hành, vì vậy hãy cố định thẻ bản phát hành khi cần tính ổn định.

useAgent là gì?

useAgent là nền tảng đồng nghiệp AI mã nguồn mở để chạy các agent như Claude Code, Codex và OpenCode. Thay vì chỉ trả về câu trả lời mang tính hội thoại, các agent làm việc trong môi trường Linux cô lập và có thể cung cấp website, bản thuyết trình, bảng tính, báo cáo nghiên cứu và pull request đã được kiểm thử hoàn chỉnh.

Mỗi thread được cấp một workstation với terminal, repository, trình duyệt và desktop có thể quan sát thông qua noVNC. Các lần chạy được biểu diễn dưới dạng timeline theo mô hình event sourcing trong Postgres, giúp chúng bền vững, có thể phát lại và kiểm tra sau khi hoàn tất.

Tính năng chính

• Một giao diện cho nhiều agent: Các engine dành riêng cho từng nhà cung cấp giao tiếp thông qua một hợp đồng sự kiện chuẩn.
• Thực thi bền vững: Các lần chạy vẫn tồn tại sau khi backend khởi động lại, trong khi cơ chế khôi phục có thể thăm dò lại các phiên đang hoạt động và tiếp nhận công việc đã hoàn tất.
• Sandbox Linux cô lập: Mỗi thread được cấp một workstation riêng. Daytona và CubeSandbox triển khai hợp đồng sandbox dùng chung.
• Cổng công cụ đáng tin cậy: Thông tin xác thực được giữ trong control plane thay vì đưa vào sandbox của agent.
• Phê duyệt thủ công: Các lệnh gọi công cụ có tính phá hủy sẽ tạm dừng để chờ phê duyệt trên giao diện web hoặc Slack, sau đó tiếp tục với capability chỉ dùng một lần và được ràng buộc theo tham số.
• Skill dựa trên GitHub: Các nhóm có thể nhập tệp SKILL.md có phiên bản, đồng bộ thay đổi và xếp hạng các skill phù hợp vào các lượt làm việc của agent.
• Ngữ cảnh tổ chức: Việc truy xuất kiến thức bao gồm trích dẫn, trong khi bộ nhớ nhóm sử dụng một luồng học tập được con người xem xét.
• Artifact gốc: Nền tảng hỗ trợ các tệp DOCX, XLSX, PPTX và PDF có quản lý phiên bản cùng trình kết xuất gốc.
• Nhiều kênh tiếp nhận: Công việc có thể đến từ ứng dụng web, Slack, REST API hoặc lịch chạy.

Kiến trúc hoạt động như thế nào

useAgent tách control plane tự lưu trữ khỏi môi trường nơi agent làm việc. Các kênh tiếp nhận tạo các lần chạy thông qua cùng một quy trình chạy. Các adapter engine chuyển hoạt động dành riêng cho từng nhà cung cấp thành các sự kiện chuẩn, trong khi mỗi thread được gán một sandbox cô lập.

Ba đặc tính kiến trúc đặc biệt quan trọng:

1. Có thể thay thế engine: Việc thay đổi engine không đòi hỏi thay thế cách biểu diễn chung của thread, artifact hoặc bộ nhớ.
2. Postgres là nguồn sự thật duy nhất: Mỗi lần chạy được lưu dưới dạng nhật ký sự kiện, cho phép phát lại chính xác và kiểm tra sau khi khởi động lại.
3. Bí mật nằm ngoài sandbox: Các tích hợp được cung cấp dưới dạng công cụ có kiểu thông qua một cổng đáng tin cậy, với thông tin xác thực chỉ được lưu trong control plane.

Bố cục repository

• frontend/ chứa giao diện sản phẩm cho các phiên, skill, playbook, wiki, artifact, automation và cài đặt.
• backend/ chứa xác thực, điều phối lần chạy, adapter engine, sandbox, kiến thức, bộ nhớ, artifact và connector.
• packages/ chứa các hợp đồng sự kiện dùng chung, workpiece, định dạng artifact, trình kết xuất và các package liên quan.
• docs-site/ chứa website tài liệu.
• infra/self-host/ chứa công cụ triển khai độc lập với nhà cung cấp và cấu hình tham chiếu Terraform cho Hetzner.
• memory/ chứa dịch vụ bộ nhớ nhóm tùy chọn.

Điều kiện tiên quyết

Việc cài đặt để phát triển cục bộ yêu cầu Bun và Postgres 16 trở lên cùng tiện ích mở rộng pgvector. Các image container Postgres tiêu chuẩn không bao gồm pgvector, vì vậy hãy sử dụng image phù hợp đã bật pgvector.

Bạn cũng nên cài Docker nếu dự định khởi động container cơ sở dữ liệu được cung cấp. Chạy các bước sau từ thư mục gốc của repository useAgent.

Bước 1: Khởi động Postgres với pgvector

Nếu bạn chưa có cơ sở dữ liệu tương thích, hãy khởi động một cơ sở dữ liệu trong Docker:

docker run -d --name useagent-pg -p 5432:5432 \
  -e POSTGRES_HOST_AUTH_METHOD=trust pgvector/pgvector:pg16
export DATABASE_URL=postgres://postgres@localhost:5432/postgres

Lệnh đầu tiên mở Postgres trên cổng 5432. Lệnh thứ hai thiết lập chuỗi kết nối được ứng dụng sử dụng. Cấu hình trust thuận tiện cho việc phát triển cục bộ; môi trường production nên sử dụng thông tin xác thực cơ sở dữ liệu được bảo mật phù hợp.

Bước 2: Cài đặt các dependency của workspace

Các dependency được cài đặt độc lập trong các workspace package dùng chung, backend và frontend:

for workspace in \
  packages/agent-harness packages/artifact-workspace \
  packages/agent-client packages/artifact-formats packages/conformance \
  backend frontend; do
  (cd "$workspace" && bun install)
done

Bước 3: Khởi động backend và frontend

Mở các phiên terminal riêng và khởi động hai tiến trình phát triển:

bun run dev:backend

bun run dev:frontend

Backend cung cấp API và dịch vụ điều phối trên cổng 3201. Frontend chạy trên cổng 3400 và chuyển tiếp các yêu cầu dưới /api/* đến backend.

Mở http://localhost:3400 trong trình duyệt để truy cập giao diện. Cấu hình nhà cung cấp và sandbox có thể khác nhau, vì vậy hãy làm theo tài liệu useAgent hiện tại khi kết nối một công cụ chạy agent hoặc cấp phát môi trường thực thi cho công cụ đó.

Bước 4: Xác thực codebase

Chạy trình kiểm tra kiểu trên toàn bộ repository sau khi cài đặt hoặc trước khi gửi thay đổi:

bun run typecheck

Lệnh này bao quát mọi package trong repository và giúp phát hiện các thay đổi không tương thích giữa các hợp đồng dùng chung, backend và frontend.

Cách sử dụng cơ bản

Tạo một lượt chạy agent

1. Mở giao diện web trên cổng 3400.
2. Sử dụng trình soạn thảo agent để mô tả kết quả hoàn chỉnh bạn cần.
3. Bắt đầu lượt chạy và theo dõi dòng thời gian sự kiện trực tiếp.
4. Kiểm tra hoạt động trên terminal, trình duyệt, máy tính để bàn hoặc workspace khi agent thực hiện công việc.
5. Xem lại mọi thẻ phê duyệt trước khi cho phép thao tác công cụ mang tính phá hủy.
6. Thu thập artifact hoàn chỉnh hoặc phần công việc trong repository được phiên làm việc trả về.

Một tác vụ có thể được diễn đạt xoay quanh một sản phẩm bàn giao cụ thể, ví dụ:

Nghiên cứu chủ đề, trích dẫn các nguồn liên quan và trả về kết quả dưới dạng báo cáo có cấu trúc.

Đối với công việc phần mềm, hãy xác định rõ phần triển khai và xác minh cần thực hiện:

Triển khai thay đổi được yêu cầu trong repository, chạy các bài kiểm thử liên quan và chuẩn bị phần công việc hoàn chỉnh để xem xét.

Đây là các ví dụ về tác vụ bằng ngôn ngữ tự nhiên, không phải cú pháp lệnh đặc biệt. Các công cụ chính xác có sẵn cho một lượt chạy phụ thuộc vào engine, sandbox, nguồn kiến thức, kỹ năng và tích hợp đã cấu hình.

Làm việc qua Slack

Khi tích hợp Slack gốc được cấu hình, người dùng có thể đề cập đến agent để bắt đầu công việc. Các câu trả lời, tệp đính kèm, artifact và yêu cầu phê duyệt vẫn nằm trong chuỗi hội thoại Slack. Cách này cung cấp cùng một quy trình chạy như giao diện web, đồng thời duy trì hoạt động cộng tác trong kênh ban đầu.

Sử dụng kiến thức tổ chức và kỹ năng

Kiến thức, nội dung wiki và bộ nhớ nhóm có thể cung cấp ngữ cảnh ở phạm vi tổ chức kèm trích dẫn. Các hướng dẫn có thể tái sử dụng cũng có thể được nhập từ GitHub dưới dạng kỹ năng SKILL.md được quản lý theo phiên bản. useAgent có thể tự động đồng bộ lại các kỹ năng này và xếp hạng những kỹ năng phù hợp vào mỗi lượt.

Tự lưu trữ useAgent

useAgent có thể chạy trên bất kỳ máy chủ Linux nào, bao gồm AWS, Google Cloud, Azure, Hetzner hoặc máy chủ vật lý. Repository bao gồm các script triển khai độc lập với nhà cung cấp, cùng với một máy chủ tham chiếu Hetzner triển khai bằng Terraform chỉ với một lệnh.

Sau khi chuẩn bị máy chủ Linux và các giá trị bắt buộc, hãy gọi script triển khai từ repository:

SERVER_IP=<host-ip> PG_PASSWORD=... OPENROUTER_API_KEY=... \
  infra/self-host/deploy-app.sh /path/to/this/repo

Quy trình cấp phát kết nối đến máy đích qua SSH. Hãy xem infra/self-host/README.md để đọc hướng dẫn production đầy đủ và các chi tiết môi trường bắt buộc, thay vì xem ví dụ rút gọn này như một cấu hình bảo mật hoàn chỉnh.

Chọn runtime sandbox

• Daytona: Dịch vụ sandbox được quản lý, có thể kết hợp với máy chủ control plane trên bất kỳ đám mây nào. README mô tả đây là lựa chọn dễ bắt đầu nhất.
• CubeSandbox: Runtime tự lưu trữ dành cho các tổ chức muốn vận hành sandbox trên phần cứng của riêng mình và yêu cầu dữ liệu được lưu giữ hoàn toàn tại chỗ.

Cả hai runtime đều nằm sau cùng một hợp đồng sandbox, cho phép control plane điều phối công việc của agent mà không khiến mô hình chạy cốt lõi phụ thuộc riêng vào một nhà cung cấp sandbox.

Mẹo vận hành nâng cao

• Ghim thẻ bản phát hành: Vì dự án đang ở giai đoạn alpha, việc ghim một thẻ đã biết giúp giảm sự cố bất ngờ do API hoặc schema thay đổi.
• Bảo toàn Postgres: Nhật ký sự kiện là nguồn dữ liệu chuẩn cho các lượt chạy. Hãy sao lưu và vận hành cơ sở dữ liệu phù hợp.
• Giữ thông tin xác thực trong gateway: Không phá vỡ kiến trúc bằng cách sao chép các secret tích hợp dài hạn vào sandbox.
• Sử dụng phê duyệt có chủ đích: Duy trì các cơ chế kiểm soát có con người tham gia đối với hành động mang tính phá hủy, đặc biệt khi lượt chạy bắt đầu qua Slack hoặc lịch.
• Chọn sandbox theo yêu cầu vận hành: Daytona cung cấp quy trình được quản lý, trong khi CubeSandbox hỗ trợ thực thi tự lưu trữ và lưu giữ dữ liệu tại chỗ.
• Chạy kiểm tra kiểu nhất quán: Các hợp đồng dùng chung trải rộng trên nhiều workspace, vì vậy hãy sử dụng bun run typecheck sau các thay đổi liên package.
• Xem xét các quy trình production: Hướng dẫn triển khai đầy đủ nằm trong infra/self-host/, còn quy trình phát hành container bất biến, bổ sung, được ghi lại tại docs/operations/immutable-releases.md.
• Kiểm tra luồng request: Repository bao gồm sơ đồ tương tác tại docs/architecture/request-flow.html để nghiên cứu sâu hơn về kiến trúc.

Tích hợp và các kênh phân phối

Ngoài hỗ trợ Slack và GitHub gốc, nền tảng còn liệt kê Gmail, Linear, Notion và HubSpot thông qua các connector. OAuth được xử lý bởi một broker, còn token được niêm phong ở phía máy chủ. Các bề mặt workspace bao gồm cơ sở kiến thức, bộ nhớ nhóm, kỹ năng, playbook và các automation theo lịch.

Tích hợp GitHub hỗ trợ xác thực App, sao chép repository và quy trình pull request. Bất kể sử dụng tích hợp nào, các lệnh gọi công cụ đều đi qua gateway đáng tin cậy thay vì để lộ thông tin xác thực trực tiếp cho máy trạm của agent.

Cân nhắc về cấp phép

useAgent được phân phối theo giấy phép GNU AGPL v3.0-only. Bạn có thể sử dụng, sửa đổi và tự lưu trữ phần mềm theo các điều khoản đó. Giấy phép thương mại có sẵn cho việc nhúng độc quyền, các sản phẩm OEM hoặc white-label, phân phối mà không phải tuân theo nghĩa vụ AGPL hoặc các yêu cầu cấp phép khác.

Kết luận

useAgent kết hợp nhiều công cụ tác tử, các phiên chạy bền vững được Postgres hỗ trợ, các sandbox Linux biệt lập, ngữ cảnh tổ chức, các tích hợp bảo mật, quy trình phê duyệt và các artifact có thể chỉnh sửa trong một nền tảng có thể tự lưu trữ. Hãy bắt đầu cục bộ với Bun và pgvector, xác thực monorepo bằng trình kiểm tra kiểu của nền tảng, sau đó sử dụng quy trình tự lưu trữ được tài liệu hóa khi chuyển sang máy chủ Linux production.