*.agent.ts
An AI assistant that chats with your users and works through the app’s own tools. Changes to data wait for the user’s approval. Every conversation is saved and picks up where it stopped.
app/assistant/
├── shop.agent.ts # instructions + tools
├── post.ts # ask(...) — send a message
├── get.ts # messages(...) — read the conversation
└── decide/post.ts # approve(...) / reject(...)Role
Use it when people want to ask and give orders in plain words: “how many units of A are left”, “cancel order 12, it’s a duplicate”. The agent reads the question, calls the tools you wrote and answers. Every model call and every tool run is recorded, so a restart never runs them a second time. Nothing runs while a conversation waits for a message or an approval.
Export
default: the result ofdefineAgent({ instructions, tools, model?, maxRounds? })frommanh/agent.- Each tool has a
description(the model picks tools by it), aninputwritten asz.object(...),run(args, { user }),approve: truewhen it changes data,roles: [...]when only some roles may use it, andreadOnly: truewhen it only reads.
Example
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: "You are the warehouse assistant. Answer briefly, with numbers from the tools.",
tools: {
stock: {
description: "Units in stock for a product code",
input: z.object({ sku: z.string() }),
run: ({ sku }, { user }) => stockOf(user, sku),
},
cancel_order: {
description: "Cancel an order, with a reason",
input: z.object({ orderId: z.number().int(), reason: z.string() }),
approve: true, // changes data → waits for approval
roles: ["manager"], // only managers may call it (omit = any signed-in user)
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);Good to know
- Tools run with the rights of the person chatting, so every rule of the app still holds. Only the person who started a conversation can write in it, approve, reject or stop it.
- A tool with
approve: trueruns only after the user approves it. When the user rejects it, the agent is told why. roles: [...]limits a tool to those app roles (theapp/auth.tsroles). A role that can’t use it is not offered the tool, and if the model calls it anyway it is refused server-side.- A tool that changes data should set
approve: true; a read-only tool should setreadOnly: true.checkwarns (it does not block) when a tool’srunlooks like it writes or calls out but has neither. - Each user has their own daily AI budget (inside the app’s monthly allowance), so one person can’t spend the whole app’s quota. When it runs out the agent answers “Bạn đã dùng hết lượt AI hôm nay…” and resumes the next day.
- Messages sent while the agent is working wait in line and are answered in order.
- The chat page listens on the channel
agent:<threadKey>withuseLiveand reloads the messages after each step. - Agents run on DeepSeek. Without
modelthey usedeepseek-flash(fast, good at calling tools). Setgpt-4oordeepseek-v4-profor the stronger model, about 3.5 times the cost. Any other model name is refused with a clear message. - Every model call counts toward the plan’s monthly AI allowance. One message makes at most 8 model calls (change it with
maxRounds). - Call
ask,approve,rejectandstopfrom post / put / patch / delete, not fromget.ts.
Next steps
- Blocks —
block_add("ai-assistant")adds the agent file, the chat page and the routes ready-made. - Processes (*.bpmn) — multi-step business work, approvals, timers, on the same engine.
- *.job.ts — one slow task in the background after a request.
Last updated