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:

agents/helper.ts
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 null without 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

  • act is 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/ without watch isn’t an agent. Use it for helpers your agents import, like room.ts above.

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.

View as Markdown