agent-ui

Tổng quan

agent-ui là gì?

agent-ui là một Agent component “batteries-included” dành cho React và Next.js do ui.inference.sh cung cấp. Thay vì phải tự xây UI chat AI từ con số 0, bạn chỉ cần cài đặt một Agent UI dựng sẵn kèm theo một API proxy route đơn giản được cung cấp bởi @inferencesh/sdk.

Component này gói sẵn những phần cốt lõi mà bạn thường cần cho các AI assistant hiện đại:

• Giao diện chat/agent có thể nhúng trực tiếp
• Wiring runtime tới inference backend thông qua proxy route
• Hỗ trợ streaming response
• Chỗ trống để tích hợp tools, approvals và các luồng agent nâng cao hơn (thông qua thiết lập phía ui.inference.sh)

Nếu bạn muốn triển khai AI assistant, SaaS copilot hoặc agentic UI bên trong ứng dụng Next.js, agent-ui mang lại một điểm xuất phát sẵn sàng cho production với lượng boilerplate tối thiểu.

agent-ui dành cho ai?

agent-ui được thiết kế cho:

• Frontend developer muốn có một UI agent/chat hoàn thiện trong ứng dụng React hoặc Next.js mà không phải thiết kế component từ đầu.
• Nhóm sản phẩm đang tích hợp AI copilot hoặc assistant vào dashboard hiện có, sản phẩm SaaS hoặc công cụ nội bộ.
• Kỹ sư thiên về API thích cấu hình proxy route và biến môi trường hơn là tự viết logic request phía client.

Bạn sẽ dùng kỹ năng này thoải mái nhất nếu bạn đã:

• Dùng Next.js (App Router) hoặc stack React tương tự
• Quen thuộc với environment variables và API key
• Biết cách cấu hình routes và components trong codebase TypeScript/React

agent-ui giải quyết vấn đề gì?

agent-ui giúp bạn tránh các điểm ma sát thường gặp khi triển khai tính năng AI:

• Không cần tự làm chat UI – bỏ qua việc dựng danh sách tin nhắn, ô nhập liệu, và trạng thái loading từ đầu.
• Không cần “fetch glue” tự chế – proxy route được xử lý qua @inferencesh/sdk, giúp bạn không phải lặp lại logic streaming và xử lý lỗi.
• Cấu hình dễ hơn – chỉ cần truyền một object agentConfig (model ref, description, system prompt) thay vì phải luồn lách config thủ công qua UI.

Điều này khiến agent-ui rất phù hợp khi bạn muốn chuyển nhanh từ “chúng ta có API key” sang “chúng ta có một agent UI hoạt động được”.

Khi nào agent-ui là lựa chọn phù hợp?

agent-ui phù hợp khi:

• Bạn đang xây một ứng dụng Next.js (đặc biệt là với cấu trúc thư mục app/).
• Bạn muốn một agent UI dựng sẵn trông hiện đại, xây theo phong cách hệ sinh thái shadcn.
• Bạn thoải mái với việc cấu hình một inference proxy route và biến môi trường.

Có thể không phù hợp nếu:

• Bạn không dùng React/Next.js cho frontend.
• Bạn cần một chat UI thiết kế hoàn toàn custom, với pattern tương tác khác hẳn giao diện agent thông thường.
• Bạn không thể expose hoặc quản lý INFERENCE_API_KEY trong môi trường của mình.

Cách sử dụng

1. Cài kỹ năng trong agent workspace của bạn

Để thêm kỹ năng agent-ui vào một workspace tương thích Agent Skills, hãy cài thông qua skills CLI:

npx skills add https://github.com/inferen-sh/skills --skill agent-ui

Lệnh này lấy metadata của skill agent-ui từ repository inferen-sh/skills. Sau khi cài xong, mở SKILL.md trong thư mục ui/agent-ui để xem hướng dẫn upstream.

2. Cài component agent-ui vào project Next.js

Bên trong ứng dụng Next.js thực tế của bạn (nơi bạn muốn render UI), cài Agent component từ ui.inference.sh bằng lệnh theo phong cách shadcn được skill gợi ý:

# Cài agent component
npx shadcn@latest add https://ui.inference.sh/r/agent.json

# Thêm SDK cho proxy route
npm install @inferencesh/sdk

Hai bước này sẽ:

• Kéo về block Agent UI (React component và wiring UI liên quan) từ ui.inference.sh.
• Cài @inferencesh/sdk, SDK mà bạn sẽ dùng để tạo inference proxy route trong ứng dụng Next.js.

Bạn có thể chạy các lệnh này trong bất kỳ project Next.js (App Router) hiện có nào. Hãy đảm bảo bạn đã có Node.js, npm (hoặc trình quản lý package khác) và môi trường dev hoạt động trước khi chạy.

3. Cấu hình API proxy route trong Next.js

agent-ui kỳ vọng frontend của bạn giao tiếp với một backend proxy route thay vì gọi dịch vụ inference trực tiếp từ trình duyệt. Tài liệu skill cung cấp một route Next.js tối thiểu dựa trên @inferencesh/sdk:

// app/api/inference/proxy/route.ts
import { route } from '@inferencesh/sdk/proxy/nextjs';
export const { GET, POST, PUT } = route;

Ghi chú triển khai:

• Đặt file này tại app/api/inference/proxy/route.ts trong project Next.js dùng App Router.
• Helper route từ @inferencesh/sdk/proxy/nextjs expose sẵn các HTTP handler (GET, POST, PUT), vì vậy bạn không cần tự viết routing logic.
• Endpoint này sẽ trở thành proxyUrl mà bạn truyền vào Agent component.

Nếu bạn dùng cấu trúc thư mục khác, hãy giữ đường dẫn nhất quán và cập nhật proxyUrl tương ứng.

4. Thiết lập biến môi trường INFERENCE_API_KEY

Tiếp theo, cấu hình inference API key trong môi trường local của bạn. Hướng dẫn skill tham chiếu tới biến INFERENCE_API_KEY:

# .env.local
INFERENCE_API_KEY=inf_...

Các bước:

1. Tạo hoặc mở .env.local ở thư mục gốc project Next.js.
2. Thay inf_... bằng API key thực tế của bạn.
3. Khởi động lại dev server để Next.js nhận thay đổi trong .env.local.

Hãy đảm bảo bạn giữ key này bí mật và không commit .env.local lên version control.

5. Render Agent component trong một page

Khi component và proxy route đã sẵn sàng, bạn có thể render Agent UI trong bất kỳ page nào của Next.js. Skill cung cấp một ví dụ ngắn gọn:

import { Agent } from "@/registry/blocks/agent/agent";

export default function Page() {
  return (
    <Agent
      proxyUrl="/api/inference/proxy"
      agentConfig={{
        core_app: { ref: 'openrouter/claude-haiku-45@0fkg6xwb' },
        description: 'a helpful ai assistant',
        system_prompt: 'you are helpful.',
      }}
    />
  );
}

Các phần quan trọng cần hiểu:

• proxyUrl: Trỏ tới API proxy route mà bạn đã tạo (/api/inference/proxy). Đây là cách Agent UI gửi và nhận tin nhắn.
• agentConfig: Object cấu hình agent bên dưới, bao gồm:
  • core_app.ref: Tham chiếu tới model hoặc app dùng phía backend.
  • description: Mô tả dễ hiểu dành cho người dùng về assistant.
  • system_prompt: System prompt ngắn giúp định hình hành vi.

Bạn có thể nhân bản hoặc chỉnh sửa file page này tại app/agent/page.tsx hoặc bất kỳ route hiện có nào trong ứng dụng.

6. Tuỳ biến và mở rộng agent-ui

SKILL.md của skill đề cập tới các tính năng như tools, approvals và widgets (thông qua ui.inference.sh). Để tận dụng các khả năng này, bạn có thể theo từng bước:

• Điều chỉnh agentConfig với model ref, description và system prompt khác nhau.
• Khám phá các file block Agent đã cài trong @/registry/blocks/agent/agent để xem cách UI được xây dựng và những props nào được hỗ trợ.
• Tích hợp Agent UI vào các luồng cụ thể trong ứng dụng (ví dụ: support dashboard, onboarding copilot, hay assistant cho vận hành nội bộ).

Vì agent-ui được cung cấp dưới dạng một React component, bạn có thể bọc nó trong layouts, modals, tabs, hoặc dùng hệ thống điều hướng và xác thực riêng của mình xung quanh component này.

7. Các file nên xem sau khi cài đặt

Sau khi cài kỹ năng agent-ui trong workspace hỗ trợ skills, file chính bạn nên mở là:

• ui/agent-ui/SKILL.md – hướng dẫn quick-start và chi tiết cấu hình từ upstream.

Từ đó, bạn có thể ánh xạ các hướng dẫn vào project Next.js thực tế và tinh chỉnh cho phù hợp với model và ràng buộc backend của riêng bạn.

Câu hỏi thường gặp (FAQ)

agent-ui có bắt buộc dùng Next.js hay có thể dùng với React thuần?

Phần walkthrough cài đặt skill và ví dụ proxy route được viết riêng cho Next.js với convention route app/api và @inferencesh/sdk/proxy/nextjs. Dù UI bản chất là React, đường triển khai được tài liệu hoá và hỗ trợ trong skill này là dành cho Next.js với kiểu API route App Router.

Nếu bạn dùng React thuần hoặc framework khác, bạn sẽ cần tự dựng lại hành vi proxy và tự thích nghi ví dụ; đường tích hợp này không được mô tả chi tiết trong skill.

agent-ui khác gì so với tự xây một chat UI?

Với agent-ui, bạn:

• Cài một Agent component dựng sẵn từ ui.inference.sh.
• Kết nối tới inference backend thông qua một proxy route duy nhất và một environment variable.

Bạn không phải:

• Thiết kế và code danh sách tin nhắn, vùng nhập liệu cùng các trạng thái streaming.
• Tự viết các lệnh fetch để gửi và nhận tin nhắn.

Bạn vẫn giữ quyền kiểm soát cấu hình thông qua agentConfig, nên có thể thay đổi model ref, description và system prompt mà không phải đụng tới phần nội bộ UI.

@inferencesh/sdk đóng vai trò gì trong thiết lập này?

@inferencesh/sdk là nền tảng cho server-side proxy route:

import { route } from '@inferencesh/sdk/proxy/nextjs';
export const { GET, POST, PUT } = route;

Khi dùng helper này, bạn:

• Expose một endpoint duy nhất (/api/inference/proxy trong ví dụ) để Agent UI giao tiếp.
• Uỷ thác chi tiết protocol và xử lý HTTP method (GET, POST, PUT) cho SDK thay vì tự code.

Điều này giúp việc bảo trì và chỉnh sửa tích hợp inference dễ dàng hơn mà không phải viết lại UI.

Tôi thay đổi model hoặc hành vi của agent như thế nào?

Bạn cập nhật agentConfig truyền vào Agent component. Ví dụ:

<Agent
  proxyUrl="/api/inference/proxy"
  agentConfig={{
    core_app: { ref: 'openrouter/claude-haiku-45@0fkg6xwb' },
    description: 'a helpful ai assistant',
    system_prompt: 'you are helpful.',
  }}
/>

Để thay đổi hành vi, bạn có thể:

• Đổi core_app.ref sang model hoặc app được hỗ trợ khác.
• Cập nhật description để phản ánh vai trò của assistant (vd: “customer support copilot”).
• Tinh chỉnh system_prompt để điều chỉnh giọng điệu và phạm vi nhiệm vụ.

Hãy tham khảo tài liệu của inference backend bạn đang dùng để biết các giá trị hợp lệ và tuỳ chọn cấu hình bổ sung.

agent-ui có phù hợp dùng cho môi trường production không?

Kỹ năng agent-ui cung cấp một Agent component React/Next.js thực thụ và một pattern proxy route được thiết kế cho ứng dụng theo chuẩn production. Tuy nhiên, mức độ sẵn sàng cho production còn phụ thuộc vào cách bạn:

• Quản lý API key và environment variables.
• Bổ sung authentication, authorization và rate limiting quanh /api/inference/proxy.
• Giám sát, log và bảo mật traffic tới inference backend.

Skill này cho bạn một nền tảng vững chắc, nhưng bạn nên bổ sung lớp bảo mật, quan sát và xử lý lỗi riêng trước khi đưa vào môi trường live.

Tôi có thể xem tài liệu upstream của agent-ui ở đâu?

Sau khi cài skill bằng:

npx skills add https://github.com/inferen-sh/skills --skill agent-ui

hãy mở:

• ui/agent-ui/SKILL.md

File này được duy trì trong repository inferen-sh/skills và chứa hướng dẫn quick start upstream (các lệnh cài đặt, snippet proxy route, cấu hình env và ví dụ sử dụng component) cho component agent-ui.