AI: the language model (LLM) in server code (ai)

ai is the project's language model. In server code (*.server.ts, Server functions) it asks for an answer, an object of a type, a look at pictures, calls of your server's functions, a decision about a text, and keeps chats; in the app it has one member, ai.messagesResource(id): a chat's messages, live while the answer is written. The code names no API key and no model: the model is the project's setting on le.codes, paid from its owner's AI credits. Another provider's API is a fetch from server code, its key in env.

  • call an LLM from the server and show its answer in the app (ai.send)
  • get structured output, JSON of a type, instead of text (ai.send<T>)
  • describe a photo the user took, read a receipt or a menu (images)
  • build a chat with an AI assistant that remembers the conversation (ai.createChat, chat.send)
  • show the assistant's answer as it is being written, with a "typing…" line (ai.messagesResource)
  • let the model look up an order or run my server code: function calling, tools (ai.tool)
  • let the AI ask the user a question with answer buttons
  • let the AI search the web, or read a page by its link, and show the sources under its answer (ai.webSearch, ai.webFetch)
  • classify, moderate, route or rate a text cheaply — spam or not, which category, a score (ai.decide)
  • show why the AI did not answer: no credits, too many requests, the daily limit (AiError, RpcError.ai)
  • test an app that uses AI on my machine

Platforms: iOS, Android, the web and the web player, against a backend le.codes deployed — the editor's preview and the published app; not on desktop: desktop run reaches only a backend on your machine, a packaged desktop build none. A backend on your machine (lecodes dev, lecodes test, lecodes render, desktop run) has no model: every ai.send, ai.decide and chat.send there throws AiError("unavailable") — see Testing AI on your machine.

At a glance

TypeScript
// ask.server.ts — runs on the app backend
export async function ask(question: string) {
  if (!question.trim()) throw new ApiError(400, "Ask something first")
  const reply = await ai.send({
    system: "You are a cooking assistant. Answer in two or three short sentences, plain text.",
    text: question,
    maxTokens: 400,
  })
  return reply.text
}
TypeScript
// main.ts — the app
import { ask } from "./ask.server"

const asking = action((question: string) => ask(question))
const question = UIInput().style({ placeholder: "How long do I boil an egg?" }).named("question")
const answer = UIText("").named("answer")

UIScreen(
  question,
  UIButton(UIText(() => (asking.busy.value ? "Thinking…" : "Ask")))
    .named("ask")
    .onClick(async () => {
      const text = await asking(question.value)
      if (text !== null) answer.text = text
    }),
  answer,
  UIText(() => asking.error.value?.message ?? "").named("error"),   // why it did not answer — see Errors
).style({ gap: 12, padding: 24 }).open()

In the le.codes preview and the published app the answer appears under the button. Under lecodes dev the error line shows the refusal instead: ai.send works on a deployed backend only — the model runs on le.codes, paid by the project's owner: deploy the server to use it.

Testing AI on your machine: unavailable under lecodes dev, the answers on le.codes

Under lecodes dev and lecodes test the model does not answer: it answers only on a backend le.codes deployed — the development backend (the editor's preview, the project link on a phone) and the production one (the published app). A backend on your machine has no road to it:

  • under lecodes dev, lecodes test, lecodes render and desktop run, ai.send throws AiError("unavailable"), so does ai.decide (ai.decide works on a deployed backend only — …), and so does chat.send (A chat's answer is written on a deployed backend only — …), which leaves the chat as it was. Uncaught, the app's call fails with status 503 and ai: "unavailable". The terminal says so at the first request, and each call it refuses in one line: [server:warn] ask.server.ts#ask: AiError("unavailable") — the call is refused with 503: …;
  • everything around the model works there: ai.createChat, ai.getChat, ai.deleteChat, chat.messages() and, in the app, ai.messagesResource(id).

So test on your machine what the app does around the model — opening a chat, the error states, the retry — and the answers themselves in the le.codes preview. A flow can check the refusal:

JSON
{ "steps": [
  { "call": "ask.server.ts#ask", "args": ["hi"], "expect": { "error": { "status": 503 } } },
  { "type": "question", "text": "hi" },
  { "tap": "ask" },
  { "expect": { "node": "error", "text": "deployed backend only" } }
] }

Which model answers and who pays: Data → AI

The model is the project's setting, not the code's: Data → AI in the le.codes editor. A request names no model — ai.send({ model: … }) is refused as invalid.

  • On the Free plan the model is Haiku; a paid plan may choose Sonnet or Opus. A setting the owner's plan does not allow runs on Haiku.
  • Every request is paid from the project owner's AI credits (a team project's: the team's). With none left, a request throws AiError("credits").
  • What the project's requests may cost a day (a UTC day) is capped; Data → AI shows today's spend against that limit. Past it, a request throws AiError("budget") until the next day.

Call the LLM from the server: ai.send

To ask the language model one thing from server code — answer a question, rewrite a text, summarize a note — await ai.send in an endpoint and return what the app needs. To classify a text — yes or no, a category, a tag from a list, a rating — ask ai.decide instead: about a second, and a small fraction of a send's price.

TypeScript
await ai.send({
  system?: string,          // who the model is and how to answer
  text?: string,            // what it answers — and/or
  images?: AiImage[],       //   pictures it looks at (see Pictures) — or
  messages?: AiMessage[],   //   a conversation, in place of text and images (see A whole conversation)
  tools?: AiTools,          // functions it may call first (see Tools)
  maxTokens?: number,       // the most tokens the answer may take: 1024 when absent, 4096 at most
}): Promise<AiReply>

type AiReply = {
  text: string                               // the answer
  stop: "end" | "length" | "refusal"         // done · cut off at maxTokens · the model would not answer
  usage: { input: number, output: number }   // tokens of the request (system and pictures in it) and of the answer
  calls?: AiToolCall[]                       // the tools it called, in order; absent when none
}
  • A request is a text, images, or both — or messages, never beside them (invalid). An empty text, a key the request does not have, a maxTokens that is no whole number above 0: invalid.
  • A token is a word or a piece of one. Past maxTokens the answer stops where it is: stop is "length" and text is what was written. A maxTokens above 4096 is lowered to 4096.
  • stop: "refusal": the model would not answer; text holds what it said, maybe "".
  • Each ai.send is one paid request, counted against the caller's rate and the project's limits (The limits). The time an endpoint waits for the model does not count toward its 30 s cap.
  • ai.send streams nothing: it resolves with the whole answer. An answer the app shows as it is written is a chat.

Get an object instead of text: ai.send<T> (structured output)

To get data the model has to write — a recipe, a list of tasks, the fields of a receipt — give ai.send a type: the model answers JSON of it, the answer is checked against it, and data is a value of that type.

Classifying a text is not this. A verdict is ai.decide: yes or no (ai.yesNo), one category of a few or one tag of a list (ai.choice), several tags (an ai.yesNo each), a rating (ai.score). It answers with probabilities in about a second, for a small fraction of a typed send's price, and its options may be built at run time — the person's own tags — which a type cannot say.

TypeScript
// recipes.server.ts
export type Recipe = {
  title: string
  minutes: number
  vegetarian: boolean
  difficulty: "easy" | "medium" | "hard"
  ingredients: { name: string, amount: string }[]
  tip?: string                                    // optional: the model may leave it out
}

export async function recipeFor(dish: string): Promise<Recipe> {
  const { data } = await ai.send<Recipe>({
    system: "You write home recipes. Amounts in metric units; minutes = the whole time, preparation included.",
    text: dish,
    maxTokens: 1500,
  })
  return data                                     // a whole Recipe: the answer was checked against the type
}
TypeScript
await ai.send<T>(request): Promise<AiDataReply<T>>
type AiDataReply<T> = { data: T, stop: "end", usage: { input: number, output: number }, calls?: AiToolCall[] }

What T may hold — the JSON a model can be told to write:

  • an object at the top (wrap a list or a string in one: { items: … });
  • string, number, boolean, null, arrays, objects, literal unions ("easy" | "hard"), T | null, unions of objects; a property with ? is one the model may leave out.

What fails the compile, with the file, the line and the place in the type: Date (use a string, an ISO date), Map / Set, a class, a function, a File, any / unknown, an index signature (Record<string, …>: name the keys, or use a list of { key, value }), a tuple, a recursive type, a template-literal type, a type parameter, a property typed undefined (make it optional), a type whose schema is over 64 KB:

TypeScript
the type of a typed ai.send and of an ai.tool's arguments is the JSON the model writes — this one cannot be told to it:
  recipes.server.ts:12: ai.send<{ when: Date }>: data.when: Date is not JSON — use a string (an ISO date)
  • The type is the model's instructions: name each property for what it holds. Doc comments do not reach the model — say the rest in system.
  • It has no ranges or lengths: minutes: number may come back 0 or 900, a list empty. Check what matters (data.minutes > 0) before you store it.
  • data is always a whole T. An answer that is not throws AiError("incomplete"), its message saying why: it was cut off at maxTokens (raise maxTokens), the model would not answer, or what it wrote did not match the type.
  • Write the call as it is — ai.send<T>({ … }) on the global ai, the type argument and the request its one argument: the compile writes the type's schema into that call. Called through another name (const send = ai.send) it is an untyped call, and its reply has no data.
  • Tools may come with a typed call if each has a function; one the person answers is invalid there (Ask the person).

Send a photo to the AI: what is on it, read a receipt — images

To ask what is on a photo the user took, read a receipt or check a picture, send it in images: a File the endpoint received from the app, or a stored file read from the database.

TypeScript
// photos.server.ts
const Dish = model({ name: t.string(), photo: t.image() })
const db = defineDb({ Dish })

export async function whatIsThis(photo: File) {                     // a picture the app uploads with the call
  const reply = await ai.send({ text: "What dish is this? One short sentence.", images: [photo], maxTokens: 200 })
  return reply.text
}

export async function caloriesOf(id: number) {                      // a picture stored in the database
  const dish = await db.dish.where({ id }).first()
  if (!dish) throw new ApiError(404, "No such dish")
  const { data } = await ai.send<{ kcal: number }>({ text: `About how many kcal is this portion of ${dish.name}?`, images: [dish.photo] })
  return Math.round(data.kcal)
}
TypeScript
// main.ts — the app picks a photo and sends it with the call
import { whatIsThis } from "./photos.server"

UIScreen(
  UIButton(UIText("What is this dish?")).named("pick").onClick(async () => {
    const photo = await openFilePicker({ accept: "image/*" })
    if (photo) toast(await whatIsThis(photo))
  }),
).open()
  • An image is a parameter of type File (an upload — Stored files) or the value of a t.file() / t.image() field. Anything else, or a file that is no picture: invalid.
  • At most 5 pictures a request — with messages, 5 across all of them.
  • Each is shown to the model as a JPEG turned the way the camera meant (HEIC photos are read), at most 1568 px on its longer side. Together, as shown, they take at most 6 MB: more is invalid, send fewer.
  • With pictures, text may be left out.
  • Pictures are input: they count in usage.input.

Give the model a whole conversation: messages

To give the model a conversation instead of one text — one your server keeps, or a chat's history read for a summary — pass messages; the answer is the model's next message.

TypeScript
type AiMessage =
  | { role: "user", text?: string, images?: AiImage[] }       // a text, pictures, or both
  | { role: "assistant", text: string, calls?: AiToolCall[] } // what the model said before, the calls it made
TypeScript
// summary.server.ts — one sentence about a chat
export async function summarize(id: string) {
  const history = await (await ai.getChat(id)).messages()
  const reply = await ai.send({
    system: "You say what a conversation was about in one sentence.",
    messages: [...history.slice(-30), { role: "user", text: "What was this conversation about?" }],
    maxTokens: 200,
  })
  return reply.text
}
  • The last message is the user's. At most 60 messages, and 5 pictures among them: a chat's history with more pictures than that needs the older ones taken out first.
  • A chat's history fits as it is: a ChatMessage's other keys (id, createdAt, writing) are not given to the model. A conversation that opens with the assistant's message (it greeted first) is fine.

Chat with an AI assistant that remembers the conversation: ai.createChat, chat.send

To build a chat with an AI assistant in the app — it remembers the conversation, the platform keeps its messages, the answer shows while it is written — open a chat on the server and write to it with chat.send. The chat stays on the server: an endpoint returns its id, and the app follows its messages with ai.messagesResource(id).

TypeScript
// help.server.ts — the chat's server
defineDb({})                                // a chat keeps its messages in the project's database

const ASSISTANT = {                         // who the assistant is: a chat keeps none of it, so every send says it
  system: "You are the cafe's assistant. Answer briefly, in plain text.",
  maxTokens: 800,
}

/** The id of the chat `id` names, or of a new one when there is none (no id yet, or the chat is gone). */
export async function openHelp(id: string | null): Promise<string> {
  if (id) {
    try {
      return (await ai.getChat(id)).id
    } catch (e) {
      if (!(e instanceof ApiError)) throw e   // 404: gone, 400: no chat's id — open a new one
    }
  }
  return (await ai.createChat()).id
}

/** The person's message: resolves once the answer is stored. Refused, the chat is as it was. */
export async function say(id: string, text: string): Promise<ChatMessage> {
  const chat = await ai.getChat(id)
  return chat.send({ ...ASSISTANT, text })
}
TypeScript
// main.ts — the app
import { openHelp, say } from "./help.server"

type Opened = { id: string, messages: Resource<ChatMessage[]> }

const savedId = signal<string | null>(null).stored("help-chat")   // the device keeps the chat's id
const chat = signal<Opened | null>(null)
const list = computed((): ChatMessage[] => {
  const loaded = chat.value?.messages.value
  return loaded?.state === "ready" ? loaded.data : []
})
const last = computed(() => list.value[list.value.length - 1])
const sending = action((text: string) => say(chat.peek()!.id, text))

const Bubble = (m: ChatMessage) =>
  UIText(m.text || "…").style({
    alignSelf: m.role === "user" ? "flex-end" : "flex-start", maxWidth: "80%",
    px: 12, py: 8, borderRadius: 14, color: "white", bgColor: m.role === "user" ? "#4f7cff" : "#2a3142",
  })

const field = UIInput().style({ flexGrow: 1, placeholder: "Message" }).named("message")

const send = async () => {
  const text = field.value.trim()
  if (!text || !chat.peek() || sending.busy.peek()) return
  field.value = ""
  if ((await sending(text)) === null) field.value = text    // refused: nothing changed — the text back
}

UIScreen(
  UIScrollable(UIColumn(() => list.value.map(Bubble)).style({ gap: 8, padding: 16 })).style({ flexGrow: 1 }),
  // the assistant is answering while the last message is the one being written; no word of it yet: "typing…"
  UIText(() => (last.value?.writing && !last.value.text ? "typing…" : sending.error.value?.message ?? "")).named("status"),
  UIRow(field, UIButton(UIText("Send")).named("send").onClick(send)).style({ gap: 8, padding: 16 }),
).style({ bgColor: "#1e2230" })
  .onClose(() => chat.peek()?.messages.close())             // stop following it
  .open()

const main = async () => {
  const id = await openHelp(savedId.peek())
  savedId.value = id
  chat.value = { id, messages: ai.messagesResource(id) }    // the chat's messages, live
}
main()

The person's message appears once the server stored it, the answer under it as the model writes it, and it stays as one stored message. The server's side:

TypeScript
await ai.createChat(): AiChat         // a new chat, its row written: chat.id is safe to store
await ai.getChat(id): AiChat          // the chat id names — ApiError 400: no chat's id, 404 "No such chat"
await ai.deleteChat(id): boolean      // true: gone, its messages and pictures with it; false: there was none
await chat.send({ system?, tools?, text?, images?, maxTokens? }): ChatMessage   // the answer, once stored
await chat.messages(): ChatMessage[]  // every stored message, in order
chat.id: string                       // a UUID — what an endpoint returns to the app

type ChatMessage = {
  id: number | string          // rises with the conversation; "writing" for the answer being written
  role: "user" | "assistant"
  text: string                 // "" for pictures alone, for an answer that only called tools, and at a turn's start
  images: StoredImage[]        // the user's pictures, as stored; an answer has none
  calls?: AiToolCall[]         // an answer's calls of tools; absent when none
  createdAt: number            // when it was stored, ms since 1970
  writing: boolean             // the answer being written (in the app's list only); false for every stored message
}
  • A chat keeps its messages in the project's database, in two models of the platform that the compile adds (AiChat, AiChatMessage: not db.<model>, and no model of yours may take their names). A project that opens chats needs a defineDb(…) in a server file — defineDb({}) when it has no models. Without one its backend does not start: a chat (ai.createChat, ai.getChat, ai.deleteChat) keeps its conversation in the project's database, and this project defines none — ….

  • The three verbs answer a promise and are awaited where they are called. ai.getChat(id).id, a call as a statement or a promise kept for later fails the compile:

    TypeScript
    a chat's verb is awaited — ai.createChat, ai.getChat and ai.deleteChat answer a promise:
      help.server.ts:4: ai.getChat(…) — write `await` before it
  • They take no options (ai.createChat({ system }) throws): who the assistant is goes with each send.

Who the assistant is: said at every send

A chat stores only its messages. system, tools and maxTokens belong to each chat.send: keep them in one module constant and spread it into every send — chat.send({ ...ASSISTANT, text }). A change of the constant reaches every chat at its next answer. One send may add to it: chat.send({ ...ASSISTANT, system: ASSISTANT.system + "\nThis is the last question.", tools: { ...ASSISTANT.tools, finish }, text }) — finish a tool made in the endpoint, which sees that call's values.

One turn: chat.send waits, all or nothing

chat.send is ai.send that remembers the conversation: it stores the user's message (text, images, or both), asks the model with the chat's history and the send's tools, stores the answer and resolves with it.

  • All or nothing. When send resolves, both messages are in the chat. When it throws — an AiError, or ApiError(404) because the chat was deleted meanwhile — nothing of the turn is: the user's message and its pictures were taken back. What a tool did meanwhile stays done. To ask again, call send again.
  • No text and no images: the assistant speaks by itself — a greeting on a new chat, going on mid-chat. Only its answer is stored, and it counts as one of the day's messages. text: "" is not that: it is an empty message, refused with 400.
  • An answer cut off at maxTokens is stored as it is. A turn whose answer has neither text nor calls throws AiError("incomplete").
  • One turn per chat at a time: a send while one runs is refused with ApiError(409), An answer is being written in this chat — wait for it to end.
  • A message is at most 8000 characters and 5 pictures, else ApiError(400). A chat's pictures are Files the call received (a stored file belongs to its row and is refused); they are stored as a t.image() field's are (Pictures).
  • The model is given the chat's last 30 stored messages — the answers' calls with their results among them — and the 5 newest pictures. What is older it does not see: keep lasting facts in system or behind a tool.
  • The endpoint's call waits as long as the answer takes; that wait does not count toward its 30 s cap. An app that goes away meanwhile stops nothing: the answer is stored.
  • A deploy or a restart of the backend under a running turn takes the turn back: the call is refused (502 incomplete, The answer was not written — ask again, or 503) and the chat is as it was.

Show the AI's answer while it is being written: the chat's messages, ai.messagesResource(id)

To show a chat on a screen — its messages, and the answer as the model writes it — an endpoint returns the chat's id (chat.id, a string) and the app opens ai.messagesResource(id): a resource of the chat's messages, live, the same kind of thing a computed's .resource() is.

TypeScript
const messages = ai.messagesResource(chatId)  // Resource<ChatMessage[]> — chatId: what an endpoint returned
messages.value: Loaded<ChatMessage[]>         // loading → ready: the last 200 stored, the answer being written last · failed
messages.peek(): Loaded<ChatMessage[]>        // the same, read without following it
messages.reload()                             // follow it again: after close() (a screen's onOpen), or when it failed
messages.close()                              // stop following it (a screen's onClose)
  • The list is the server's. The user's message appears once it is stored. From the start of a turn to its end the LAST message is the answer being written — id: "writing", writing: true, its text "" at first and then growing, its calls as the tools run — and the stored answer takes its place when the turn ends. A turn that gets no answer takes the message and the answer being written out of the list again.
  • "Is the assistant answering" is the last message's writing: show "typing…" while it is true and its text is still "".
  • failed when the server refuses it: 404 No such chat (no chat has that id, or it was deleted with ai.deleteChat), 400 when the id is no UUID. Opening it never throws.
  • Each call is a subscription of its own: open it where the screen that shows the chat is built and close() it when the screen closes; reload() follows it again.
  • It only reads: there is no send. The app writes through your endpoints, and whether a message went through is that call's answer — an action's error, not the list.
  • It rides the channels' socket: after a reconnect or a deploy it shows the chat as the server has it.
  • The chat object itself never leaves the server. An endpoint that returns it, a computed whose value holds it, a channel message carrying it are refused with a 500, in words that say what to do: the answer of help.server.ts#openHelp holds a chat (result) — a chat stays on the server: return its id, chat.id, and the app follows it with ai.messagesResource(id).
  • ai is one name on both sides with each side's members: ai.messagesResource is the app's, and ai.send, ai.tool and the chat verbs are the server's. The compile refuses a member on the wrong side, with the file and the line: ai.messagesResource is the app's — on the server read a chat with ai.getChat(id), ai.send runs on the server — call an endpoint.

Keep, protect and delete a chat: its id

chat.id is what you keep to open the chat again: a t.uuid() field of the row the chat belongs to, or the device's storage (signal(null).stored(key)), handed back to an endpoint that calls ai.getChat(id).

  • The id is the right to read the chat: whoever has it may follow it (ai.messagesResource(id)). An endpoint returns it only to who may read the chat, and writes only after checking the caller — find the chat through a row of theirs instead of taking any id:
TypeScript
// chats.server.ts — each user's conversations, nobody else's
const User = model({ name: t.string().default("") })
const Conversation = model({ owner: t.one("User").onDelete("cascade"), chat: t.uuid().unique() })
const db = defineDb({ User, Conversation }).withAuth({ model: "User" })

const ASSISTANT = { system: "You are a helpful, concise assistant.", maxTokens: 1024 }

/** The caller's conversation `id` — someone else's is "not found", like one that never was. */
const mine = async (id: number) => {
  const me = await db.auth.requireUser().select({ id: true })
  const row = await db.conversation.where({ id, owner: { id: me.id } }).first()
  if (!row) throw new ApiError(404, "No such conversation")
  return row
}

/** A new conversation of the caller: our row's id, and the chat's — to its owner only. */
export async function newConversation(): Promise<{ id: number, chat: string }> {
  const me = await db.auth.requireUser().select({ id: true })
  const chat = await ai.createChat()
  const { id } = await db.conversation.insert({ owner: me, chat: chat.id })
  return { id, chat: chat.id }
}

export async function sendMessage(id: number, text: string): Promise<ChatMessage> {
  const row = await mine(id)
  return (await ai.getChat(row.chat)).send({ ...ASSISTANT, text })
}

export async function deleteConversation(id: number) {
  const row = await mine(id)
  await ai.deleteChat(row.chat)                    // false when it was gone already: no error
  await db.conversation.delete(row.id)
}
  • A chat lives until ai.deleteChat(id). One that has no message is removed by the platform a day after it was made — a chat whose only message was taken back among them. A kept id may therefore be gone: getChat rejects with 404; catch it and createChat.
  • ai.deleteChat(id) removes the chat, its messages and their pictures. It resolves false for an id that names no chat, so calling it twice is safe; an id that is no UUID is ApiError(400). A send of that chat waiting for its answer rejects with 404, and an app's ai.messagesResource(id) of it turns failed, 404 No such chat.

Let the model call your code: tools, ai.tool (function calling)

To let the model look something up or do something while it answers — find an order, check the stock, save a result — give it tools: functions of your server, each with a description and a typed parameter. The model calls them, reads what they return, and answers once it has what it needs.

TypeScript
// orders.server.ts
const Order = model({ number: t.string().unique(), status: t.string(), total: t.float() })
const db = defineDb({ Order })

const findOrder = ai.tool(
  "Find one of the cafe's orders by its number: its status and its total",
  async ({ number }: { number: string }) => {
    const order = await db.order.where({ number }).select({ status: true, total: true }).first()
    if (!order) throw new ApiError(404, `There is no order ${number}`)   // the model reads this message
    return order
  },
)

export async function askAboutOrders(question: string) {
  const reply = await ai.send({
    system: "You answer questions about the cafe's orders. Look an order up before you say anything about it.",
    text: question,
    tools: { findOrder },                        // the key is the name the model calls it by
    maxTokens: 500,
  })
  return { text: reply.text, lookedUp: reply.calls?.length ?? 0 }
}
TypeScript
ai.tool(description: string, fn: (args: A) => unknown): AiTool   // the code answers the call
ai.tool<A>(description: string): AiTool                         // the person answers it — see Ask the person
tools: { findOrder, ask }                                        // in ai.send and chat.send: the key is the tool's name
type AiToolCall = { tool: string, args: unknown, result?: unknown, error?: string }
  • The description is what the model reads to decide when to call it (10 000 characters at most).
  • The function takes ONE object of arguments, typed — or none (() => Date.now()). The model is told that type's JSON, with the rules of ai.send<T>; a parameter with no type, two parameters or a non-object fail the compile: ai.tool: a tool's function takes ONE object of arguments — ….
  • What it returns, sync or async, goes back to the model as JSON: any value, at most 16 KB as JSON (a larger result is an error the model is told).
  • A throw is the model's to hear, and it goes on: an ApiError's message as it is, any other error as The tool failed (the error itself in the server console). Arguments that do not match the type are not run; the model is told why.
  • It runs where the send was made, in the endpoint's call: request and db.auth are the caller's. A tool made inside an endpoint sees that call's values.
  • The calls of one answer run one after another. One send may ask the model 8 times and run 24 calls — past either it throws AiError("incomplete"). text is all the model wrote between its calls, usage the sum, maxTokens each model call's; the send counts once against the caller's rate.
  • reply.calls lists the calls in the order they ran, each with its result or its error.
  • What a tool did stays done when the send fails after it — in a chat too.
  • The name is the key in tools: letters, digits, _ and -, 64 at most; 16 tools a request.
  • Make a tool with ai.tool(…) on the global, in a server file: the compile writes its schema into that call. One it did not see throws ai.tool: this tool has no schema of its arguments — ….

A chat's tool calls are part of the chat

In a chat, the answer is stored with its calls — their arguments and results — and whoever follows the chat sees them; ai.messagesResource(id) shows each call while it runs (no result yet), then with its result. The model is given them again at the next turns. Return what the conversation may hold: the fields the answer needs, not a whole row.

Ask the person a question with answer buttons: a tool without a function

To let the model ask the user — a quiz, an onboarding interview, "which of these did you mean?" with buttons — give it a tool with no function: ai.tool<T>(description). Its call ends the assistant's turn, the app shows its arguments, and the person's next message is its answer.

TypeScript
// quiz.server.ts — the model asks, the person answers with a button (or types)
export type Ask = { question: string, options: string[] }

const ask = ai.tool<Ask>("Ask the user one question, with 2 to 4 short answers they can tap")   // no function: the person answers

const QUIZ = {
  system: "You run a five-question quiz about the solar system. Ask every question with the ask tool, never in your text. " +
    "After each answer say in a few words whether it was right. After the fifth, give the score and ask nothing more.",
  tools: { ask },
  maxTokens: 400,
}

export async function startQuiz(): Promise<string> {
  const chat = await ai.createChat()
  await chat.send({ ...QUIZ })                    // no text: the assistant speaks first — and asks
  return chat.id                                  // the app follows it: ai.messagesResource(id)
}

export async function answerQuiz(id: string, text: string) {
  const chat = await ai.getChat(id)
  await chat.send({ ...QUIZ, text })              // the answer to the waiting question: its result for the model
}
TypeScript
// main.ts — the app
import { answerQuiz, startQuiz, type Ask } from "./quiz.server"

type Opened = { id: string, messages: Resource<ChatMessage[]> }

const chat = signal<Opened | null>(null)
const messages = computed((): ChatMessage[] => {
  const loaded = chat.value?.messages.value
  return loaded?.state === "ready" ? loaded.data : []
})
const replying = action((text: string) => answerQuiz(chat.peek()!.id, text))

/** The question waiting for the person: a call of `ask` with neither result nor error in the last stored message. */
const waiting = computed((): Ask | null => {
  const last = messages.value[messages.value.length - 1]
  if (last?.role !== "assistant" || last.writing) return null       // while an answer is written, a call is still running
  const call = last.calls?.find((c) => c.tool === "ask" && c.result === undefined && c.error === undefined)
  return call ? (call.args as Ask) : null
})

UIScreen(
  UIColumn(() => messages.value.filter((m) => m.text).map((m) => UIText(`${m.role === "user" ? "You" : "Quiz"}: ${m.text}`))),
  UIText(() => waiting.value?.question ?? "").style({ fontSize: 20 }).named("question"),
  UIRow(() => (waiting.value && !replying.busy.value ? waiting.value.options : []).map((option, i) =>
    UIButton(UIText(option)).named(`option-${i + 1}`).onClick(() => replying(option)),
  )).style({ gap: 8, flexWrap: "wrap" }),
  UIText(() => replying.error.value?.message ?? ""),
).style({ gap: 12, padding: 24 })
  .onClose(() => chat.peek()?.messages.close())
  .open()

startQuiz().then((id) => { chat.value = { id, messages: ai.messagesResource(id) } })
  • A tool with a function: the code answers. A tool without one: the person answers. T is its arguments — an object type, with the rules of ai.send<T>: what the model fills in and the app shows. ai.tool("…") with neither a function nor a type argument, and a type argument beside a function, fail the compile.
  • When the model's answer calls it, the tools with a function called in that same answer still run, in order, and then the turn ends — the model is not asked again. chat.send resolves with the stored answer: its text (what the model wrote before the call, maybe "") and its calls, where this call has neither result nor error.
  • The next chat.send({ ...QUIZ, text }) is its answer — a tapped option and a typed one alike. The model is given that message as the call's result; in the chat it is an ordinary user message. Pictures sent with it go along; a send with no text answers it with "no message". Several such calls in one answer are all answered by that one message.
  • The send that answers carries the same tool (spread the same constant). Without it the model gets the person's message as an ordinary one, after a call with no answer.
  • In the app, the waiting question is a call with neither result nor error in the chat's LAST message, once it is stored (!writing): while an answer is being written, a call without a result is a tool still running.
  • Arguments that do not match T are an error result like any tool's, and the model goes on.
  • With ai.send the reply ends the same way (stop: "end", the call waiting in calls). Give the conversation back with the person's answer after it, and the tool again:
TypeScript
export type Pick = { question: string, options: string[] }
const pick = ai.tool<Pick>("Ask the user to choose one option")

export async function nextTurn(first: string, said: AiReply, answer: string) {
  return ai.send({
    tools: { pick },
    messages: [
      { role: "user", text: first },
      { role: "assistant", text: said.text, calls: said.calls },
      { role: "user", text: answer },                          // the waiting call's result for the model
    ],
  })
}
  • A typed ai.send<T> takes no tool without a function: its answer is data, and this call would end it with none (invalid).

Search the web and read a page: ai.webSearch(), ai.webFetch()

For what the model does not know — today's news, a price, a product page, an article the user links — give it the web tools. Anthropic runs them on its servers: no function, no description, just the tool under the name your app calls it.

TypeScript
// support.server.ts
const SUPPORT = {
  system: "You help the cafe's customers. Search the web for anything about the area; read a page when the customer sends a link.",
  tools: { findOrder, search: ai.webSearch(), page: ai.webFetch() },   // findOrder: a tool of your own, beside them
  maxTokens: 800,
}

export async function ask(id: string, text: string) {
  await (await ai.getChat(id)).send({ ...SUPPORT, text })
}

export async function quick(question: string) {
  const reply = await ai.send({ ...SUPPORT, text: question })
  return { text: reply.text, sources: reply.sources ?? [] }       // show the sources with the answer
}
TypeScript
ai.webSearch(options?: AiWebOptions): AiWebTool
ai.webFetch(options?: AiWebOptions): AiWebTool
type AiWebOptions = { maxUses?: number, allowedDomains?: string[], blockedDomains?: string[] }
type AiSource = { url: string, title: string }
  • They go in the same tools object, in ai.send and chat.send alike, beside your own tools — one of each a send. The key is your name for it; web_search and web_fetch are the model's own names for them, so a tool of yours may not use those keys.
  • Their calls are in calls like any, under your key — never a page itself:
    • a search: { tool: "search", args: { query }, result: { sources: [{ url, title }] } } — the pages it found (an empty list when nothing matched);
    • a page: { tool: "page", args: { url }, result: { url, title? } };
    • either with error instead of result when it failed — Anthropic's code: max_uses_exceeded, too_many_requests, url_not_accessible, url_not_in_prior_context, unsupported_content_type, unavailable, … The model hears it and goes on.
  • sources — on reply.sources and on a chat's stored answer — are the pages the answer's text cites, each once, in the order it first cites them; absent when it cites none (the model may search and still cite nothing: the search's result.sources says what it found). Anthropic's terms: when you show the answer to people, show its sources with it.
  • While a chat's answer is written, a web call with no result yet is the search running — show "Searching the web…". A stored answer's web calls always have a result or an error.
  • A page is read only from a link already in the conversation: the user's message, a tool's result, an earlier search's pages — never a link the model wrote itself, nor one only in system. A link you want it to read goes in the user's message: text: `${question}\n\n${url}`. Pages that need JavaScript to render are not read.
  • maxUses: how many searches (or pages) one send may make — 3 unless given, at most 5. allowedDomains or blockedDomains (not both): bare domains with an optional path, no scheme — "docs.example.com", "example.com/blog" — 20 at most. A wrong option throws at the ai.webSearch(…) / ai.webFetch(…) call: ai.webSearch: maxUses is at most 5 uses in one send, got 6.
  • What it costs the owner: a search costs about $0.01 on top of the tokens its results take; a page read costs its tokens — up to about 20 000 of a page. Both count against the project's daily limit.
  • A chat stores the answer's text, its calls and its sources — not the pages: the next turns are not given them again (and are not paid for them again). The model sees its earlier answer's text.
  • A typed ai.send<T> takes no web tool (invalid): the API cannot cite pages in a typed answer. Search in one send, then ask for the typed answer in another, the first answer's text in its text.
TypeScript
// main.ts — the answer, "Searching the web…" while a search runs, and the sources under it
const messages = ai.messagesResource(chatId)
const list = computed((): ChatMessage[] => (messages.value.state === "ready" ? messages.value.data : []))

const bubble = (m: ChatMessage) => {
  const searching = m.writing && (m.calls ?? []).some((c) => c.tool === "search" && c.result === undefined && c.error === undefined)
  return UIColumn(
    UIText(m.text),
    ...(searching ? [UIText("Searching the web…").style({ color: "#888" })] : []),
    ...(m.sources ?? []).map((s, i) => UIText(`[${i + 1}] ${s.title}`).style({ color: "#2563eb" }).onClick(() => openURL(s.url))),
  ).style({ gap: 4 })
}

UIScreen(UIColumn(() => list.value.map(bubble)).style({ gap: 12 })).style({ padding: 16 }).open()

Classify, moderate, route or rate a text with AI: ai.decide (spam, a category, sentiment, a score)

To classify a text with AI — content moderation (is this comment spam, toxic or offensive), the category or tag of a message, which team a support request is routed to, sentiment analysis, a rating on a scale — ask the platform's decision model with ai.decide. It writes no text: it answers a question of a kind with how likely each answer is, in about a second, for a small fraction of what an ai.send costs.

TypeScript
// reviews.server.ts
const Review = model({ text: t.string(), topic: t.string().default(""), hidden: t.boolean().default(false) })
const db = defineDb({ Review })

export async function addReview(text: string) {
  if (!text.trim()) throw new ApiError(400, "Write something first")
  const { spam, topic } = await ai.decide(text, {
    spam: ai.yesNo("Is this review spam or an advertisement?", {
      yes: "Advertising, links, the same text repeated",
      no: "An opinion about the cafe, even a rude one",
    }),
    topic: ai.choice("What is the review mostly about?", {
      food: null,                                    // the name says it
      service: "Staff, waiting time, delivery",
      price: null,
    }),
  })
  return db.review.insert({
    text,
    hidden: spam.probability > 0.8,                  // a threshold of your own
    topic: topic.confidence > 0.5 ? topic.choice : "",   // topic.choice: "food" | "service" | "price"
  })
}
TypeScript
// text classification: a verdict with probabilities, ~1 s, far cheaper than ai.send or a typed ai.send<T>
await ai.decide(text: string, question: AiQuestion): the question's answer
await ai.decide(text: string, questions: { name: AiQuestion, … }): { name: that question's answer, … }

ai.yesNo(question: string, criteria?: { yes?: string, no?: string })   → { probability: number }
ai.choice(question: string, options: { name: string | null, … })       → { choice: name, confidence: number, probabilities: { name: number, … } }
ai.score(question: string, levels: string[])                           → { score: number, confidence: number, probabilities: number[] }
  • Several tags of a list are a yes / no question each, in one decide — ai.decide(note, Object.fromEntries(tags.map((tag) => [tag, ai.yesNo(`Does the note fit the tag "${tag}"?`)]))) — and the tags past your threshold are the note's; one tag is an ai.choice over them.
  • One question answers its answer: const spam = await ai.decide(text, ai.yesNo("Is it spam?")), then spam.probability. Several go by name and answer under the same names — one request, one payment of the text, each question asked of the text by itself (one says nothing to another).
  • ai.yesNo → probability: how likely the answer is yes, 0 … 1. The criteria say what counts as yes and as no, where the question leaves room — either, both or none. It is how SURE the model is, not how much: "Is the customer angry?" at 0.9 is "almost certainly angry", not "very angry". A degree is an ai.score.
  • ai.choice → choice: the likeliest option's name; probabilities: each option's, by name (together about 1); confidence: how far ahead the choice is, 0 (all alike) … 1. An option is its name and a description, or null when the name says it; 1 to 255 of them.
  • ai.score → score: where the text sits on the levels — 0 is the first, fractional (1.7: between the second and the third; Math.round(score) is a level's index); probabilities: each level's, in order; confidence: how narrowly they sit around one level. The levels are described lowest first, 2 to 10 of them. One thing a score: "useful" and "polite" are two questions.
  • The answer's type comes from the call: choice is the union of the option names written there, probabilities has exactly those keys, and the answers have the names of the questions. Options built at run time (a Record<string, string | null> made from a table's rows) work the same; choice is then a string.
  • The model always answers — it has no "I do not know", and a choice always picks one of the options. Act past a threshold of your own (probability > 0.8, confidence > 0.5) and treat the rest as undecided; for "none of these", ask an ai.yesNo beside the choice ("Does it name any of these topics?").
  • Ask narrow questions: one thing each, answerable from the text alone. A judgment of several factors is several questions put together in code. What needs reasoning over steps, or words — an explanation, a summary, a reply — is an ai.send.
  • text is a string, at most 200 000 characters — an object goes as JSON.stringify(value). The model itself takes about 64 000 tokens a request and 32 000 with any one question; past that the call throws AiError("invalid"). At most 32 questions a decide; a question 10 000 characters, a criterion (what counts as yes, an option's description, a level) 2 000.
  • A wrong argument of ai.yesNo / ai.choice / ai.score throws where the question is made (ai.score: a score has 2 to 10 levels, got 1); a question may be made once, at the module's top, and asked many times.
  • Which model decides is the platform's — one for every project and plan, not the Data → AI setting: TypeSafe's Jev, and the text and the questions are sent to TypeSafe. The owner pays for the tokens of the text and the questions (the answers cost nothing), from the same AI credits and against the same daily limit as ai.send.
  • It throws the same AiError as ai.send — credits, budget, busy, unavailable (a backend on your machine among them: ai.decide works on a deployed backend only — …), invalid — and an uncaught one refuses the app's call the same way (Errors). One decide is one request of the caller's rate, however many questions it asks.
  • It takes no pictures, no system, no tools, and it is no part of a chat: decide in the endpoint, before or after the chat.send.
  • Where the decision is optional, catch the refusal and go on without it — the review is saved unsorted, the message goes to the default team. The app then works on a backend with no model too (lecodes dev, a check), where every decide is unavailable:
TypeScript
const decided = async <Q extends AiQuestion | Record<string, AiQuestion>>(text: string, question: Q): Promise<AiAnswers<Q> | null> => {
  try {
    return await ai.decide(text, question)
  } catch (e) {
    if (e instanceof AiError && e.code !== "invalid") return null   // no decision this time
    throw e
  }
}

const spam = await decided(text, ai.yesNo("Is this review spam?"))
const hidden = spam !== null && spam.probability > 0.8             // undecided: shown, as before
TypeScript
// support.server.ts — route a message before answering it
const DEPARTMENT = ai.choice("Which team handles this message?", {
  billing: "Payments, refunds, invoices",
  delivery: "Where the order is, a late or damaged order",
  other: "Anything else",
})

export async function route(message: string) {
  const team = await ai.decide(message, DEPARTMENT)        // one question: its answer
  return team.confidence > 0.6 ? team.choice : "other"
}

When the AI does not answer: out of credits, the daily limit, busy — AiError, RpcError.ai

When the model gives no answer — the owner is out of credits, the day's limit is spent, too many requests — ai.send, ai.decide and chat.send throw an AiError: its code is the reason the code can act on, its message the words. An endpoint that does not catch it refuses the app's call with the status of the code, and the app reads the code as ai.

TypeScript
class AiError extends Error { readonly code: AiErrorCode }   // server: what ai.send and chat.send throw
err.ai?: AiErrorCode                                         // app: on RpcError — and on the Failure of an action / resource
code why the app's call, uncaught
credits the project's owner has no AI credits left 402
budget the project's daily AI limit is spent (Data → AI) 402
busy too many requests: this caller's, the project's (8 at once) or the platform's — the same request can go a little later 429
unavailable no model answered: a backend on your machine, or the platform did not answer (or its web tools are turned off: a send with ai.webSearch() / ai.webFetch()) 503
incomplete no whole answer: a typed answer that is not a whole T; a chat's answer that was not written; the model still calling tools after 8 rounds or 24 calls 502
limit chat.send only: the person sent the most messages a day allows (100) 429
invalid the request is wrong — your code's mistake, the message says what 500 Internal error, no ai
  • An uncaught AiError is no crash: the call is refused in the AiError's words, its code on the app's RpcError.ai, and the server console says it in one line. invalid is a 500 like any throw, its message in the server console only.
  • A channel's hook and a computed's run that let one escape carry ai the same way (the subscription's error, a resource's failed).
  • A 429 without ai is the transport's Too many calls (The limits).
  • A chat's other refusals are ApiErrors with no ai: 400 (an empty or too long message, no chat's id), 404 (No such chat), 409 (a turn is running).

In the app, branch on ai and say it in the person's words:

TypeScript
// main.ts
import { ask } from "./ask.server"

const asking = action((question: string) => ask(question))

const said = (f: Failure): string => {
  if (f.offline) return "No connection"
  switch (f.ai) {
    case "limit": return "That's all for today — come back tomorrow"
    case "busy": return "Too many questions at once — try again in a few seconds"
    case "credits": case "budget": return "The assistant is resting until tomorrow"
    case "unavailable": case "incomplete": return "The assistant could not answer — try again"
  }
  return f.message                                       // the endpoint's ApiError
}

UIScreen(
  UIButton(UIText("Ask")).named("ask").onClick(() => asking("What is on the menu today?")),
  UIText(() => (asking.error.value ? said(asking.error.value) : "")).named("error"),
).open()

On the server, catch it where the answer is optional:

TypeScript
export async function suggestTitle(text: string): Promise<string | null> {
  try {
    const { data } = await ai.send<{ title: string }>({ system: "Name the note in 2 to 6 words.", text, maxTokens: 60 })
    return data.title
  } catch (e) {
    if (e instanceof AiError && e.code !== "invalid") return null   // no title this time: the note saves all the same
    throw e
  }
}

The limits

What a project's AI may do, and what each limit produces past it:

what limit past it
requests of one caller — a device: its session, its address before it has one one every 5 s, a burst of 5 busy
requests of server code with no call behind it (a timer, the module's load) one bucket for all of them, the same rate busy
the project's requests at once (a chat's turn among them) 8 busy
what the project's requests cost a day (UTC) the daily limit Data → AI shows budget
the owner's AI credits what is left credits
an answer's tokens, each model call's maxTokens: 1024 when absent, 4096 at most stop: "length"; typed: incomplete
text / system of a request 400 000 / 200 000 characters invalid
messages of ai.send({ messages }) 60 invalid
pictures of a request 5; each shown at 1568 px at most; 6 MB together invalid
a typed answer's schema 64 KB as JSON a compile error
tools of a request 16, the web tools among them; a description 10 000 characters invalid
one send with tools 8 model calls (a paused long turn's going on among them), 24 calls of your tools incomplete
web tools of a request one ai.webSearch(), one ai.webFetch() invalid
a web tool's uses in one send maxUses: 3 when absent, 5 at most; a domain list 20 at most, one list thrown at ai.webSearch(…) / ai.webFetch(…); past maxUses the call's error is max_uses_exceeded
a page the model reads about 20 000 tokens of it the rest is cut off
a typed ai.send<T> with a web tool not allowed invalid
a tool's result 16 KB as JSON the model is told the call failed
the text of an ai.decide 200 000 characters; about 64 000 tokens with its questions, 32 000 with any one invalid
the questions of an ai.decide 32; a choice's options 255; a score's levels 2 to 10 invalid; a maker's own limits throw where the question is made
a chat's message 8000 characters, 5 pictures ApiError 400
a chat's turns one at a time ApiError 409
messages one person sends to the project's chats 100 in 24 h limit (429), nothing stored
what the model sees of a chat the last 30 stored messages, the 5 newest pictures older ones are not given to it
what ai.messagesResource(id) lists the last 200 stored messages await chat.messages() on the server has every one
a chat with no message removed a day after it was made getChat rejects with 404
  • One send is one request of the caller however many tool rounds it takes; a chat's turn is one too, and so is an ai.decide, however many questions it asks.
  • The daily messages count the user's messages and the answers of sends with no text (the assistant speaking by itself), against the device whose call made the send. A turn that got no answer leaves nothing and is not counted; a chat.send with no call behind it (a timer) is not counted.

Inside a computed: what is a read, what is refused

A server computed runs again whenever its data changes, so it only reads. A chat inside one:

  • await ai.getChat(id) is allowed: it reads nothing the computed follows.
  • await chat.messages() is followed: a message stored later runs the computed again.
  • ai.createChat(), ai.deleteChat(id) and chat.send(…) are writes: the run fails with status 500, computed help.server.ts#helpView: AiChat.insert is a write — a computed only reads (…); write in an endpoint.
  • ai.send is no write and runs — but each run of the computed is another paid request, at every change of its data. Ask in an endpoint and store the answer in a row the computed reads.
  • A computed's value carries the chat's id, never the chat: a value that holds the chat object is refused like an endpoint's answer (a 500 saying to return chat.id).
TypeScript
export const conversationView = computed(async (id: number): Promise<{ chat: string, messages: number }> => {
  const row = await mine(id)                       // the caller's row: `mine` of chats.server.ts above
  const chat = await ai.getChat(row.chat)          // a read: allowed, not followed
  return { chat: chat.id, messages: (await chat.messages()).length }   // followed: a new message runs it again
})

Pitfalls

TypeScript
await ai.send({ model: "claude-…", text })         // ✗ invalid: which model answers is the project's setting (Data → AI)
await ai.send({ text })                            // ✓

const chat = ai.getChat(id)                        // ✗ compile error: a chat's verb is awaited
const chat = await ai.getChat(id)                  // ✓

await ai.createChat({ system: "You help." })       // ✗ throws: a chat keeps no options
await chat.send({ ...ASSISTANT, text })            // ✓ who the assistant is, at every send

await chat.send({ text: "" })                      // ✗ 400: an empty message
await chat.send({ ...ASSISTANT })                  // ✓ no text: the assistant speaks by itself

return await ai.getChat(id)                        // ✗ endpoint: 500 — a chat stays on the server
return (await ai.getChat(id)).id                   // ✓ its id; the app opens ai.messagesResource(id)

const messages = ai.messagesResource(id)           // ✗ in a *.server.ts file: compile error — the app's member
const history = await (await ai.getChat(id)).messages()   // ✓ the server reads a chat so

const reply = await ai.send({ text })              // ✗ in the app: compile error — ai.send runs on the server
const reply = await ask(text)                      // ✓ an endpoint that calls ai.send

ai.send<{ when: Date }>({ text })                  // ✗ compile error: Date is not JSON
ai.send<{ when: string }>({ text })                // ✓ an ISO date

ai.send<Report>({ text, tools: { search: ai.webSearch() } })   // ✗ invalid: a typed answer takes no web tool
const found = await ai.send({ text, tools: { search: ai.webSearch() } })
ai.send<Report>({ text: `${text}\n\nWhat was found:\n${found.text}` })   // ✓ search first, then ask typed

ai.send({ system: `Summarize ${url}`, tools: { page: ai.webFetch() } })   // ✗ the link is only in system: url_not_in_prior_context
ai.send({ system: "Summarize the page the user links.", text: url, tools: { page: ai.webFetch() } })   // ✓ in the user's message

await ai.decide(text, "Is this spam?")             // ✗ invalid: a question is made by ai.yesNo / ai.choice / ai.score
await ai.decide(text, ai.yesNo("Is this spam?"))   // ✓

if ((await ai.decide(text, ai.yesNo("Spam?"))).probability) hide()   // ✗ 0.02 is truthy: a probability, not a yes
if ((await ai.decide(text, ai.yesNo("Spam?"))).probability > 0.8) hide()   // ✓ a threshold of your own

await ai.decide(order, ai.yesNo("Is it late?"))    // ✗ invalid: the text is a string
await ai.decide(JSON.stringify(order), ai.yesNo("Is it late?"))   // ✓

ai.webSearch({ maxUses: 10 })                      // ✗ throws: at most 5 uses in one send
tools: { web_search: myTool }                      // ✗ invalid: web_search / web_fetch are the web tools' names
UIText(reply.text)                                 // ✗ an answer with sources shown without them
UIColumn(UIText(reply.text), ...(reply.sources ?? []).map((s) => UIText(s.title).onClick(() => openURL(s.url))))   // ✓

See also

  • Server functions — endpoints, action / resource, RpcError, computeds
  • Database — the rows a chat's id belongs to
  • Stored files — File parameters and t.image() fields, the pictures a request carries
  • Sign-in — db.auth, whose chats are whose
  • Keys (env) — another provider's API, its key kept out of the code