AG-UI: Giao thức gọn nhẹ cho Tương tác Tác nhân - Người dùng

Vì sao ứng dụng agentic cần AG-UI

Trước khi xem mã, hãy nói về lý do chúng ta cần một giao thức mới ngay từ đầu. Tất cả xuất phát từ khác biệt căn bản giữa một hàm và một tác nhân.

Giới hạn của mô hình request/response

Trong phát triển web truyền thống, tương tác mang tính giao dịch. Bạn yêu cầu hồ sơ người dùng và máy chủ gửi lại. Chỉ là một lần trao đổi.

Tác nhân, tuy nhiên, khó đoán và tốn thời gian. Khi bạn yêu cầu một tác nhân “gỡ lỗi vì sao pipeline CI đột ngột lỗi sau khi đồng đội merge,” nó không trả về một đối tượng JSON ngay. Thay vào đó, nó có thể:

1. Kéo 50 commit log gần nhất từ GitHub (Hành động).
2. Nhận ra có dependency mới được thêm mà không cập nhật lockfile (Quan sát).
3. Đối chiếu phiên bản gói đó với các CVE đã biết (Suy luận).
4. Hỏi bạn có muốn rollback lần merge hay vá tiếp (Con người trong vòng lặp).

Tôi sẽ giải thích sau trong phần “Loại sự kiện”, nhưng giờ chỉ cần biết rằng một yêu cầu HTTP tiêu chuẩn sẽ hết thời gian chờ trong khi đợi tất cả những điều này. Bạn cần cách để stream các cập nhật từng phần để người dùng không phải nhìn màn hình đứng yên.

Các nhu cầu đặc thù của tác nhân

Tác nhân cần luồng thông tin hai chiều vượt ra ngoài văn bản. Chúng cần đồng bộ Trạng thái.

Hãy hình dung một tác nhân giúp bạn viết báo cáo. Không chỉ trò chuyện; nó còn chỉnh sửa tài liệu. Cả bạn và tác nhân có thể gõ cùng lúc. AG-UI xử lý việc này bằng cách coi “tài liệu” là trạng thái dùng chung, dùng các cập nhật hiệu quả để giữ màn hình của bạn và bộ nhớ của tác nhân luôn đồng bộ mà không ghi đè công việc của nhau.

Cách tác nhân và UI giao tiếp

AG-UI thay thế mô hình Gọi thủ tục từ xa (RPC) cũ bằng mô hình Nguồn sự kiện (Event Sourcing). Thay vì đợi câu trả lời cuối, tác nhân gửi một dòng sự kiện đều đặn mô tả những gì nó đang làm.

Dòng sự kiện

Hãy coi luồng AG-UI như bảng tin thời sự cho bộ não của tác nhân. Ứng dụng khách (frontend của bạn) đăng ký vào dòng này và cập nhật UI dựa trên những gì nhận được. Cách tiếp cận này tách rời logic: frontend React của bạn không cần biết cách tác nhân suy nghĩ, chỉ cần biết cần hiển thị gì.

AG-UI tránh được khoảng chờ. Ảnh do Tác giả tạo.

Các loại sự kiện cốt lõi

Giao thức định nghĩa các loại sự kiện tiêu chuẩn bao phủ hầu hết kịch bản tương tác. Dưới đây là những loại chính bạn sẽ thấy:

1. TEXT_MESSAGE_*: Sự kiện stream văn bản được tạo theo từng phần. Thường bao gồm _START, _CONTENT (dòng token) và _END, kết hợp lại tạo hiệu ứng “đang gõ” quen thuộc.

2. TOOL_CALL: Báo hiệu tác nhân muốn làm gì đó, như kiểm tra thời tiết hoặc truy vấn cơ sở dữ liệu. Điểm mấu chốt, AG-UI có thể stream đối số của lệnh gọi công cụ, cho phép UI của bạn điền trước biểu mẫu ngay cả khi tác nhân còn “đang nói”.

3.  STATE_DELTA: “Gánh nặng” cho cộng tác. Thay vì gửi lại toàn bộ tài liệu mỗi khi một ký tự thay đổi, tác nhân gửi một “diff” nhỏ (như “thêm 'hello' tại vị trí 5”).

4. INTERRUPT: Van an toàn. Nếu tác nhân chạm vào hành động nhạy cảm (như “Xóa Cơ sở dữ liệu”), nó phát sự kiện ngắt. Luồng sẽ tạm dừng cho đến khi người dùng gửi sự kiện phê duyệt.

Đa phương thức và các bước suy nghĩ

Giao thức không chỉ giới hạn ở văn bản. Nó hỗ trợ đa phương thức, tức stream hình ảnh, âm thanh và tệp đính kèm song song với cuộc hội thoại. Nó cũng tiêu chuẩn hóa Các bước Suy nghĩ, tách biệt suy nghĩ nội bộ của tác nhân (vết suy luận) khỏi phản hồi công khai cuối cùng. Bạn có thể đã thấy mẫu tương tự khi dùng các công cụ như ChatGPT, nơi chỉ báo tiến độ hoặc bước trung gian được hiển thị riêng với câu trả lời cuối. Điều này giúp bạn quyết định hiển thị tiến độ thực thi hay chỉ kết quả cuối cho người dùng.

Các khối xây dựng của AG-UI

Giờ bạn đã hiểu luồng, hãy xem các tính năng cụ thể khiến AG-UI mạnh mẽ với nhà phát triển.

UI sinh thành

Văn bản rất tốt, nhưng đôi khi biểu đồ sẽ tốt hơn. UI sinh thành cho phép tác nhân quyết định tại thời điểm chạy rằng nó nên hiển thị một thành phần UI thay vì văn bản.

AG-UI stream sự kiện; A2UI định nghĩa thành phần. Ảnh do Tác giả tạo.

Có một điểm khác biệt dễ gây nhầm lẫn (tôi sẽ nhắc lại ở phần framework): AG-UI là cơ chế chuyển (lớp truyền tải), còn A2UI (Agent-to-User Interface) là định nghĩa UI (payload). Một tác nhân có thể dùng sự kiện TOOL_CALL của AG-UI để truyền tải payload A2UI, một cây JSON khai báo mô tả thành phần UI (như “Thẻ Giá Cổ phiếu”). Frontend của bạn nhận được và render biểu đồ thực tế.

Trạng thái dùng chung với JSON Patch

Xử lý trạng thái dùng chung rất khó. Nếu tác nhân gửi một đối tượng ngữ cảnh 5MB mỗi giây, ứng dụng của bạn sẽ ì ạch.

AG-UI giải quyết việc này với JSON Patch (RFC 6902). Như tôi đã đề cập trước về đồng bộ trạng thái, khi tác nhân thay đổi một giá trị trong bộ nhớ, nó tính phần khác biệt và gửi một sự kiện STATE_DELTA.

[
  {
    "op": "replace",
    "path": "/user/status",
    "value": "active"
  }
]Được hỗ trợ bởi

Client nhận hướng dẫn nhẹ này và áp dụng vào trạng thái cục bộ. Hiệu quả này là điều làm cho cộng tác thời gian thực với tác nhân trở nên khả thi.

AG-UI trong bức tranh giao thức

Bạn có thể đã nghe về các giao thức khác như MCP (Model Context Protocol). Điều quan trọng là biết AG-UI nằm ở đâu trong stack để bạn không dùng sai công cụ cho công việc.

Ngăn xếp agentic

Tôi thích hình dung nó như một tam giác giao tiếp:

1. MCP (Tác nhân ↔ Công cụ): Kết nối tác nhân với thế giới backend: cơ sở dữ liệu, kho GitHub và API nội bộ. Mục tiêu là lấy thông tin.
2. A2A (Tác nhân ↔ Tác nhân): Cho phép các tác nhân nói chuyện với nhau, giao phó nhiệm vụ cho tác nhân phụ.
3. AG-UI (Tác nhân ↔ Người dùng): Đây là “chặng cuối”. Nó kết nối trí tuệ của tác nhân với người dùng.

Bộ ba Giao thức kết nối các tác nhân. Ảnh do Tác giả tạo.

AG-UI không quan tâm tác nhân lấy dữ liệu như thế nào (đó là việc của MCP, như tôi đã nói ở trên); nó chỉ quan tâm cách hiển thị dữ liệu đó cho bạn.

Triển khai AG-UI

Hãy xem thực tế trông như thế nào. Lập trình viên thường tương tác với AG-UI theo ba cách: xây dựng 1) Ứng dụng agentic (kết nối frontend với tác nhân), xây dựng 2) Tích hợp (làm framework tương thích), hoặc xây dựng 3) Client (tạo frontend mới). Đa số bạn sẽ thuộc nhóm đầu.

Tôi sẽ giải thích mã ngay sau đây, nhưng trước hết, thường bạn sẽ không tự viết các trình xử lý giao thức thô. Thư viện sẽ gói gọn việc đó. Tuy nhiên, hiểu luồng là cần thiết để gỡ lỗi.

Thiết lập kênh sự kiện

Hầu hết triển khai dùng Server-Sent Events (SSE) vì đơn giản, thân thiện với tường lửa và hoàn hảo cho streaming một chiều từ server đến client. Tôi đã gợi ý trước đó, nhưng SSE là chìa khóa giúp giao thức này nhẹ hơn nhiều so với WebSocket.

Trong thiết lập điển hình (như với Microsoft Agent Framework hoặc CopilotKit), máy chủ của bạn mở một endpoint nâng cấp kết nối thành luồng.

Đăng ký sự kiện đơn giản

Đây là ví dụ khái niệm về cách một client frontend lắng nghe luồng. Lưu ý cách chúng ta xử lý các loại sự kiện khác nhau để cập nhật UI.

// Connect to the AG-UI stream
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      // Append text to the chat window
      updateChatLog(data.content);
      break;

    case 'TOOL_CALL_START':
      // Show a "Processing..." indicator or the specific tool UI
      showToolIndicator(data.tool_name);
      break;

    case 'STATE_DELTA':
      // Apply the JSON patch to our local state store
      applyPatch(localState, data.patch);
      break;

    case 'INTERRUPT':
      // Prompt the user for permission
      showApprovalModal(data.message);
      break;
  }
};Được hỗ trợ bởi

Mẫu này che đi độ phức tạp trong logic nội bộ của tác nhân. Frontend của bạn chỉ là “trình phát” cho các sự kiện mà tác nhân gửi.

Tích hợp và Hỗ trợ Hệ sinh thái

Bạn không phải tự xây tất cả. Hệ sinh thái đang trưởng thành nhanh chóng, với các nền tảng và framework lớn cùng hội tụ về các mẫu tương tác hướng sự kiện tương tự.

“Tam giác Vàng” công cụ

Microsoft mô tả một “Tam giác Vàng” cho phát triển tác nhân:

1. DevUI: Để trực quan hóa quá trình suy nghĩ của tác nhân (gỡ lỗi).
2. OpenTelemetry: Để đo lường hiệu năng và chi phí.
3. AG-UI: Để kết nối với người dùng.

Các framework được hỗ trợ

Hệ sinh thái đang mở rộng nhanh. Ngoài các bên lớn, hỗ trợ đang tăng trên diện rộng:

1. Microsoft Agent Framework: Có middleware gốc cho ASP.NET Core (Microsoft.Agents.AI.Hosting.AGUI).

2. CopilotKit: Đóng vai “Trình duyệt” cho AG-UI, cung cấp một frontend React đầy đủ biết cách render các sự kiện ngay từ đầu.

3. Hệ sinh thái Python: Các framework như LangGraph, CrewAI, Mastra, Pydantic AI, Agno, và LlamaIndex đều có thể được phơi bày như các endpoint AG-UI.

4. SDK: Mặc ddù TypeScript và Python chiếm ưu thế, SDK đang hoạt động hoặc phát triển cho Kotlin, Go, Dart, Java và Rust.

Độ tin cậy, Gỡ lỗi và Bảo mật

Mở đường liên lạc trực tiếp giữa AI và trình duyệt mang đến rủi ro. Dưới đây là cách giữ an toàn cho ứng dụng của bạn.

Máy chủ frontend tin cậy

Đừng bao giờ để client kết nối trực tiếp với runtime thô của tác nhân. Như tôi đã nhấn mạnh trong phần “Vì sao ứng dụng agentic cần AG-UI”, luôn dùng Máy chủ Frontend Tin cậy (mẫu BFF). Máy chủ này đóng vai người gác cổng. Nó thêm xác thực, giới hạn tốc độ và kiểm tra đầu vào trước khi chuyển thông điệp của người dùng tới tác nhân.

Cân nhắc bảo mật

Tiêm lệnh nhắc (prompt injection)

Người dùng độc hại có thể cố ghi đè hướng dẫn của tác nhân thông qua tấn công prompt injection. Như tôi đã đề cập trước đó, middleware của bạn nên làm sạch đầu vào.

Lệnh gọi công cụ trái phép

Chỉ vì một tác nhân có thể xóa tệp không có nghĩa là người dùng hiện tại nên được phép làm vậy. Máy chủ tin cậy của bạn phải lọc các công cụ khả dụng cho tác nhân dựa trên quyền của người dùng.

Bảo mật trạng thái

Vì trạng thái được chia sẻ qua JSON patch, hãy cảnh giác với ô nhiễm prototype. Đảm bảo thư viện patch của bạn cấm sửa các thuộc tính được bảo vệ như __proto__.

Gỡ lỗi với Dojo

Nếu tác nhân của bạn hành xử kỳ lạ, hãy dùng AG-UI Dojo. Đây là bộ kiểm thử giúp bạn trực quan hóa luồng sự kiện thô. Nó giúp bắt lỗi như JSON patch sai định dạng hoặc lệnh gọi công cụ được kích hoạt nhưng không trả về kết quả.

Kết luận

Chúng ta đã điểm qua kiến trúc, các loại sự kiện và mẫu triển khai của AG-UI.

Tôi hiểu rằng một lập trình viên đơn lẻ hay người ở công ty nhỏ khó có thể “áp dụng AG-UI” và ngay lập tức “tách rời frontend khỏi backend”. Tất cả điều này đòi hỏi quyết định kiến trúc lớn, sự đồng thuận từ nhiều nhóm và nguồn lực mà đa phần mọi người không có.

Nhưng hiểu AG-UI vẫn quan trọng ngay cả khi bạn không triển khai. Khi đánh giá framework tác nhân hoặc quyết định tự xây hay dùng nền tảng, biết “giao tiếp tác nhân - UI tốt” trông ra sao sẽ giúp bạn phán đoán tốt hơn. Bạn sẽ nhận ra khi một công cụ đang ép bạn vào các mẫu dễ vỡ.

Nếu muốn tìm hiểu sâu hơn về xây dựng các hệ thống này, hãy xem các khóa học Giới thiệu về Tác nhân AI và Xây dựng Hệ thống Agentic có thể mở rộng để nâng tầm kỹ năng.