DocsAI
Agents
Code that watches a collection and acts on each change, with a model or without.
An agent is a file in agents/ that watches a collection and reacts to each change, as another user would. Its only state is the rows in the database. To add one, export what it watches and an act function:
import { type Act, isAgent, conversation } from "./room.ts";
export const watch = { collection: "support_events" };
export async function act({ change, server, ai, agent }: Act) {
const said = change.record;
// never answer yourself
if (change.action !== "create" || isAgent(said)) return;
const room = conversation(server, said.ticket);
const written = await ai(
"You are a friendly support agent. Ask ONE short question that helps solve the problem.",
room.map((e) => `${e.author_name}: ${e.text}`).join("\n"),
{ type: "object", properties: { question: { type: "string" } }, required: ["question"] },
);
server.collection("support_events").create({
ticket: said.ticket, author: `agent:${agent}`, author_name: "Helper", kind: "question",
// no model: still an answer
text: written?.question ?? "What did you expect to happen?",
});
}Features include:
- One call per change, in order, with the file reloaded each time
- A model’s answer as JSON shaped by a schema or a type, or
nullwithout a model - Agents that react to events as well as to collections
- One run per change in a swarm, on the leader
- Writes broadcast like any others, to people and to other agents
How an agent runs
actis called once per change, in order, in a worker, as functions are. The file is reloaded each time, so edits apply from the next change.- It runs as the system and should mark its own writes. Ignore them, or it will keep replying to itself.
- In a swarm, only the leader runs agents, so each change is answered once.
- Its writes are broadcast like any others: people see them through sync, and other agents watching that collection get them too.
- A file in
agents/withoutwatchisn’t an agent. Use it for helpers your agents import, likeroom.tsabove.
Ask a model
ai(system, prompt, schema) calls the model set up in the AI plugin and returns JSON matching the schema, or null if no model is set. Always handle null.
To shape the answer with a type instead of a schema, write ai<Question>(system, prompt), and the schema is made from the type (see AI).
React to events
To react to an event instead of a collection, write export const watch = { event: "order.paid" }, or "*" for every event. act then receives event in place of change.
Several agents, one room
A support room might have three agents. The Helper asks the customer a question. The Scribe reads each answer and writes what it learned to support_facts. The Router watches the facts rather than the conversation, and hands the ticket to a person once it knows enough. Agents never call each other; they communicate only through rows.
Agents start with the server. If you add a collection while it’s running, restart the server for the agents watching it to receive changes.