Trợ lý trong app

@agentic-ui/widget là package tùy chọn cung cấp một trợ lý AI ngay trong app Vue: một chat widget nổi cùng bộ composable headless, đã nối sẵn vào registry và safety pipeline. Chỉ cần thả một component vào app là người dùng có trợ lý chạy chính các action của app — được validate, kiểm tra permission và duyệt trước khi thực thi.

bash

pnpm add @agentic-ui/widget

Peer: vue ^3.3 và ai ^5, cùng @agentic-ui/vue và @agentic-ui/client.

Ba cách dùng

Mức	Bạn viết	Phù hợp khi
Drop-in	`<AgentWidget api="/agent/chat" />`	Có trợ lý ngay hôm nay
Slots	`<AgentWidget>` + `#launcher` / `#header`	Giữ logic, đổi giao diện
Headless	`useAgentChat()` / `useAgentWidget()` + template riêng	Tự làm toàn bộ UI

Dù chọn cách nào, mọi hành động trợ lý thực hiện vẫn đi qua validate → permission → confirmation → execute → audit.

Drop-in

Cài plugin registry một lần:

// main.ts
import { createApp } from 'vue'
import { createAgenticUi } from '@agentic-ui/vue'
createApp(App).use(createAgenticUi()).mount('#app')

Rồi đặt widget ở bất kỳ đâu trong app:

vue

<script setup lang="ts">
import { AgentWidget } from '@agentic-ui/widget'
import '@agentic-ui/widget/styles.css' // theme mặc định (tùy chọn)
</script>

<template>
  <AgentWidget
    api="/agent/chat"
    title="Trợ lý"
    :suggestions="['Thêm một task', 'Tóm tắt trang này']"
    show-audit
  />
</template>

Bạn khai capability ở nơi khác bằng useAgentCapability (xem Tích hợp); widget hiển thị và điều khiển bất cứ thứ gì đã đăng ký. Nó cần một server proxy nhỏ như mô tả trong hướng dẫn tích hợp — key LLM không bao giờ nằm ở browser.

Layout là kiểu live-chat chuẩn: khung tin nhắn cuộn được, ô nhập ghim ở đáy. Approval nổi phía trên ô nhập chỉ khi có việc chờ duyệt, còn audit trail được ẩn sau nút activity (bật bằng show-audit). Mỗi tool call hiện thành một bước gọn, nằm trên hàng riêng, tách khỏi câu trả lời.

Slots

Giữ phần logic, thay phần giao diện:

vue

<AgentWidget api="/agent/chat">
  <template #launcher="{ toggle, unread }">
    <button class="my-fab" @click="toggle">
      Hỏi AI <span v-if="unread">{{ unread }}</span>
    </button>
  </template>
</AgentWidget>

#launcher nhận { open, unread, toggle }; #header nhận { close, title }.

Headless

useAgentChat là "bộ não" — tạo chat, đưa confirmation qua queue, gom audit event và trả về một chat log đã chuẩn hóa. Tự dựng UI trên đó:

import { useAgentChat } from '@agentic-ui/widget'

const chat = useAgentChat({ api: '/agent/chat' })
// chat.lines · chat.input · chat.busy · chat.error
// chat.send(text?) · chat.stop()
// chat.approvals · chat.approve(callId, remember?) · chat.deny(callId, reason?)
// chat.audit · chat.entries

useAgentWidget thêm trạng thái đóng/mở panel: open, unread, toggle(), show(), hide().

Components

Dùng độc lập, hoặc để <AgentWidget> ghép lại. Tất cả theme-able qua class au-*.

AgentChatPanel — khung tin nhắn + ô nhập.
AgentApprovalPanel — các confirmation đang chờ; truyền changesFor để hiển thị diff theo field thay vì input JSON thô.
AgentAuditTimeline — các phase pipeline của mỗi call.
AgentCapabilityInspector — catalog live, tìm kiếm được.

Theming

Theme mặc định chạy hoàn toàn bằng biến --au-*. Ghi đè vài biến trên :root để đổi da, hoặc bỏ styles.css và tự style các class au-*. Light và dark đều có sẵn, theo đúng theme của người xem.

css

:root {
  --au-accent: #6d5efc;
  --au-bg: #0b0b12;
  --au-surface: #141420;
}

Lịch sử hội thoại & auto-compact

Trong một session, trợ lý nhớ ngữ cảnh — chat giữ toàn bộ transcript và gửi lại mỗi lượt nên model thấy các tin nhắn trước. Session càng dài, prompt càng phình; đặt maxHistoryTokens để auto-compact phần lịch sử gửi lên model (cửa sổ trượt theo ngân sách token, giữ các lượt gần nhất). Transcript trên màn hình vẫn đầy đủ; chỉ bản gửi đi bị giới hạn.

vue

<AgentWidget api="/agent/chat" :max-history-tokens="8000" />

useAgentChat({ api: '/agent/chat', maxHistoryTokens: 8000 })

Bộ ước lượng không cần tokenizer (~chars / 4); ghi đè bằng estimateTokens. Nếu dùng transport riêng, tự nén bằng compactMessages được export.

Ranh giới

Không ship server — proxy (và key) vẫn nằm ở app của bạn.
Không bao giờ bỏ qua pipeline; approval card render chính confirmation queue của registry.
Capability do bạn khai bằng useAgentCapability.

Trợ lý trong app ​

Ba cách dùng ​

Drop-in ​

Slots ​

Headless ​

Components ​

Theming ​

Lịch sử hội thoại & auto-compact ​

Ranh giới ​