Skip to Content

*.agent.ts

Trợ lý AI trò chuyện với người dùng và làm việc bằng các công cụ của app. Việc thay đổi dữ liệu chờ người dùng duyệt. Mỗi cuộc trò chuyện được lưu lại và chạy tiếp đúng chỗ.

app/assistant/ ├── shop.agent.ts # chỉ dẫn + công cụ ├── post.ts # ask(...) — gửi tin nhắn ├── get.ts # messages(...) — đọc cuộc trò chuyện └── decide/post.ts # approve(...) / reject(...)

Vai trò

Dùng khi người dùng cần hỏi và ra lệnh bằng lời: “tồn kho mã A còn bao nhiêu”, “huỷ đơn 12 vì trùng”. Agent đọc câu hỏi, gọi công cụ bạn viết, rồi trả lời. Mỗi lần gọi mô hình và mỗi lần chạy công cụ được ghi lại, nên app khởi động lại cũng không gọi lại lần hai. Trong lúc chờ tin nhắn hay chờ duyệt thì không có gì chạy.

Export

  • default: kết quả của defineAgent({ instructions, tools, model?, maxRounds? }) từ manh/agent.
  • Mỗi công cụ có description (mô hình chọn công cụ theo câu này), input là z.object(...), run(args, { user }), approve: true nếu công cụ thay đổi dữ liệu, roles: [...] nếu chỉ vài vai được dùng, và readOnly: true nếu công cụ chỉ đọc.

Ví dụ

app/assistant/shop.agent.ts
import { defineAgent } from "manh/agent"; import { z } from "zod"; import { stockOf, cancelOrder } from "app/orders/repository"; export default defineAgent({ instructions: "Bạn là trợ lý kho. Trả lời ngắn, số liệu lấy từ công cụ.", tools: { ton_kho: { description: "Số lượng tồn của một mã hàng", input: z.object({ sku: z.string() }), run: ({ sku }, { user }) => stockOf(user, sku), }, huy_don: { description: "Huỷ một đơn hàng, cần lý do", input: z.object({ orderId: z.number().int(), reason: z.string() }), approve: true, // đổi dữ liệu → chờ người duyệt roles: ["manager"], // chỉ quản lý mới gọi được (bỏ trống = ai đăng nhập cũng gọi) run: ({ orderId, reason }, { user }) => cancelOrder(user, orderId, reason), }, }, });
app/assistant/post.ts
import { ask } from "manh/agent"; export default async (c, { user, body }) => ask("app/assistant/shop.agent.ts", "u" + user.id + "-shop", body.text, user);
app/assistant/get.ts
import { messages } from "manh/agent"; export default (c, { user }) => messages("u" + user.id + "-shop", user);

Cần biết

  • Công cụ chạy với quyền của người đang trò chuyện, nên mọi luật của app vẫn giữ nguyên. Chỉ người mở cuộc trò chuyện mới gửi tin, duyệt, từ chối hay dừng nó.
  • Công cụ có approve: true chỉ chạy sau khi người dùng bấm duyệt. Bị từ chối thì agent được báo lý do.
  • roles: [...] giới hạn công cụ theo vai (các vai trong app/auth.ts). Vai không được phép thì công cụ không đưa cho mô hình chọn, và nếu mô hình cứ gọi thì vẫn bị chặn ở máy chủ.
  • Công cụ đổi dữ liệu nên đặt approve: true; công cụ chỉ đọc thì readOnly: true. check nhắc (cảnh báo, không chặn) khi run trông như ghi dữ liệu hay gọi ra ngoài mà thiếu cả hai.
  • Mỗi người dùng có hạn mức AI riêng theo ngày (nằm trong hạn mức tháng của app), để một người không tiêu hết phần của cả app. Hết lượt thì agent trả lời “Bạn đã dùng hết lượt AI hôm nay…”, hôm sau dùng tiếp.
  • Tin nhắn gửi lúc agent đang làm được xếp hàng và trả lời lần lượt.
  • Trang chat nghe kênh agent:<threadKey> bằng useLive để tải lại tin nhắn mỗi khi agent làm xong một bước.
  • Agent chạy trên mô hình DeepSeek. Không ghi model thì dùng deepseek-flash (nhanh, gọi công cụ tốt). Ghi gpt-4o hoặc deepseek-v4-pro để dùng mô hình mạnh hơn, đắt hơn khoảng 3,5 lần. Tên mô hình khác bị từ chối kèm thông báo rõ lý do.
  • Mỗi lần gọi mô hình tính vào hạn mức AI hằng tháng của gói. Mỗi tin nhắn tối đa 8 lần gọi mô hình (đổi bằng maxRounds).
  • Gọi ask, approve, reject, stop trong post / put / patch / delete, không gọi trong get.ts.

Bước tiếp theo

  • Khối tính năng — block_add("ai-assistant") thêm sẵn file agent, trang chat và các route.
  • Quy trình (*.bpmn) — việc nghiệp vụ nhiều bước, duyệt, hẹn giờ, chạy trên cùng nền.
  • *.job.ts — một việc chậm chạy nền sau request.
Cập nhật