Skip to Content

*.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 of defineAgent({ instructions, tools, model?, maxRounds? }) from manh/agent.
  • Each tool has a description (the model picks tools by it), an input written as z.object(...), run(args, { user }), approve: true when it changes data, roles: [...] when only some roles may use it, and readOnly: true when 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: true runs only after the user approves it. When the user rejects it, the agent is told why.
  • roles: [...] limits a tool to those app roles (the app/auth.ts roles). 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 set readOnly: true. check warns (it does not block) when a tool’s run looks 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> with useLive and reloads the messages after each step.
  • Agents run on DeepSeek. Without model they use deepseek-flash (fast, good at calling tools). Set gpt-4o or deepseek-v4-pro for 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, reject and stop from post / put / patch / delete, not from get.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