*.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ủadefineAgent({ 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),inputlàz.object(...),run(args, { user }),approve: truenếu công cụ thay đổi dữ liệu,roles: [...]nếu chỉ vài vai được dùng, vàreadOnly: truenế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: truechỉ 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 trongapp/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.checknhắc (cảnh báo, không chặn) khiruntrô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ằnguseLiveđể 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
modelthì dùngdeepseek-flash(nhanh, gọi công cụ tốt). Ghigpt-4ohoặcdeepseek-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,stoptrong post / put / patch / delete, không gọi trongget.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