Agents

An agent is a file in agents/ that watches a collection and acts on each change to it, the way a person at another screen would. Its memory is rows, and what it does depends only on them.

// no watch: a helper, not an agent
import { type Act, isAgent, conversation } from "./room.ts";

export const watch = { collection: "study_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.page);

  const written = await ai(
    "You are a friendly tutor. Ask ONE short open question.",
    room.map((e) => `${e.author_name}: ${e.text}`).join("\n"),
    { type: "object", properties: { question: { type: "string" } }, required: ["question"] },
  );
  server.collection("study_events").create({
    page: said.page, author: `agent:${agent}`, author_name: "Tutor", kind: "question",
    // no model: still an answer
    text: written?.question ?? "What do you already know about this?",
  });
}

• One call per change, in order, in the functions sandbox. The file is read again each time, so an edit takes effect at the next change.
• It acts as the system and says who it is in what it writes. It must ignore its own writes, or it would keep answering itself.
• ai(system, prompt, schema) asks the model set up in Settings → AI and returns JSON in the schema’s shape, or null when no model is set up. Always have an answer for that case.
• What it writes is announced like any other write. People see it through sync, and other agents watching that collection hear it.

Several agents, one room

A study room might have three agents. The Tutor asks the pupil it knows least about. The Scribe reads each answer and writes what it learnt to study_facts. The Coach watches the facts rather than the conversation, and gives a tip once a pupil has three. No agent calls another; they communicate only through the rows they write.

Agents start with the server. If a collection is added while the server is running, restart it before that collection’s agents will hear anything.