Docs
Build an AI agent in TypeScript
An AI agent in Chloe is a TypeScript file listing its jobs, tools and channels. Here is one, with a model asked only where it is needed.
An agent here is not one long prompt. It is a TypeScript file listing its purpose, its jobs, the tools it may hand a model, and the chats it answers on. Each job is an async function, and asking a model is one kind of step inside it, used only where a step needs judgement.
Install
npm install @chloejs/core
npx chloe setupSetup asks for a model and writes the config, with a first agent that has only purpose: ask it to change itself, or have your coding agent make it into what you want. See Start.
The agent
agent.ts is the whole list, and a job not on it does not run. Every option is
in An agent.
// The one agent this repo ships, and the one its docs quote: a small shop's
// back office, with a job at each level of autonomy. Orders that are late (no
// model at all), the inbox sorted (one model step), buying stock (code decides,
// a model writes the line), a customer's problem looked into (one of each, in
// one job), a customer who went quiet (an agent step), a refund big enough that a
// person decides, one job that is a prompt from end to end, and a customer's
// message answered with their orders at hand.
//
// `services/` stands in for the systems a shop already has. Point those at the real
// thing and nothing in `jobs/` changes.
//
// Copy this folder, rename it, and put your own name in chloe.config.ts.
import { defineAgent, prompt } from "@chloejs/core";
import api from "./channels/api.ts";
import telegram from "./channels/telegram.ts";
import web from "./channels/web.ts";
import whatsapp from "./channels/whatsapp.ts";
import bigRefunds from "./jobs/big-refunds.ts";
import orderIssues from "./jobs/order-issues.ts";
import howItWent from "./jobs/how-it-went.ts";
import restock from "./jobs/restock.ts";
import sortMessages from "./jobs/sort-messages.ts";
import stuckOrders from "./jobs/stuck-orders.ts";
import whyTheyLeft from "./jobs/why-they-left.ts";
import { orderStatus } from "./tools/orderStatus.ts";
export default defineAgent({
id: "shop",
name: "Shop",
// Any model the gateway or the CLI can reach. A job can name a different one
// for itself, which is the point of choosing here rather than in the runtime.
model: "anthropic/claude-sonnet-5.5",
identity: "Watches the orders, the inbox, the shelves and the customers who stopped buying.",
purpose: prompt("purpose.md"),
tools: { orderStatus },
// A channel's job is named on its channel, not here: answer-whatsapp-customer
// is in channels/whatsapp.ts.
jobs: [stuckOrders, sortMessages, restock, orderIssues, whyTheyLeft, bigRefunds, howItWent],
channels: { telegram, whatsapp, api, web },
});A job with a model in the middle
Code reads the inbox, one model step says what each message is about, in a shape checked against a zod schema, and code decides which desk each goes to.
export default defineJob({
id: "sort-messages",
cron: every(15).minutes,
timezone: "America/New_York",
description: "Every message a customer wrote in is on the right desk.",
model: "anthropic/claude-haiku-4.5",
run: async (work) => {
const waiting = await work.step("read what came in", () => unread());
if (waiting.length === 0) return { sorted: 0, urgent: [], desks: {} as Record<string, number> };
const read = await work.model("work out what each one is about", {
instructions:
"You sort a shop's inbox. Judge only what the customer wants, not what should be done about it. " +
"Every message gets exactly one line back, with the id copied exactly.",
output: Sorted,
prompt: waiting.map((one) => `${one.id} (${one.at}): ${one.text}`).join("\n\n"),
});
// The rules, in code: where each one goes, and which are worth interrupting
// somebody for. The model never decides either.
const desks: Record<string, number> = {};
for (const desk of new Set(read.sorted.map((one) => DESK[one.about]))) {
const ids = read.sorted.filter((one) => DESK[one.about] === desk).map((one) => one.id);
desks[desk] = await work.step(`hand ${ids.length} to ${desk}`, () => handTo(desk, ids));
}
const urgent = read.sorted.filter((one) => one.urgency === "today" || one.wantsMoneyBack);
return { sorted: read.sorted.length, urgent: urgent.map((one) => `${one.id}: ${one.inAWord}`), desks };
},
response: (r) =>
r.sorted === 0
? "nothing came in"
: `${r.sorted} sorted into ${Object.keys(r.desks).length} desk(s)` +
(r.urgent.length ? `, ${r.urgent.length} for today: ${r.urgent.join("; ")}` : ""),
});When the model should choose the order
When what to look at next depends on the last answer, a job hands a model a goal and some tools, and keeps the limits in the file: which tools, which calls may run, how many turns and how many dollars.
export default defineJob({
id: "why-they-left",
cron: every.monday.at("09:00"),
timezone: "America/New_York",
description: "Every good customer who stopped ordering has a reason and a next step.",
run: async (work) => {
const quiet = await work.step("find who went quiet", () => goneQuiet(QUIET_DAYS));
if (quiet.length === 0) return { looked: 0, found: [] };
const past = note(work.agentId, "why-they-left", Findings);
const already = await work.step("read what was found before", () => past.read());
const found: { at: string; customer: string; why: string; next: string }[] = [];
for (const one of quiet.slice(0, AT_MOST)) {
const theirs = ({ customer }: { customer: string }) =>
customer === one.id ? "approved" : { type: "denied" as const, reason: `${one.id} is the customer being looked into, and ${customer} is not` };
const reason = await work.agent(`work out why ${one.name} stopped ordering`, {
prompt:
`${one.name}, customer ${one.id}, has been buying since ${one.since} and last ordered on ` +
`${one.lastOrder}. Work out the most likely reason they stopped, and what somebody here should do ` +
`about it. Look things up in whatever order the answers suggest, and say what you actually saw.`,
tools: {
ordersTheyPlaced: tool({
description: "Every order this customer has placed, newest first.",
inputSchema: z.object({ customer: z.string().describe("The customer's id, like c-12") }),
execute: async ({ customer }) =>
(await ordersBy(customer)).map((order) => ({
id: order.id,
placed: order.placed,
shipped: order.shipped ?? "never",
promised: order.promised,
total: money(order.total),
})),
}),
whatTheyWroteIn: tool({
description: "Messages this customer sent us, newest first.",
inputSchema: z.object({ customer: z.string().describe("The customer's id, like c-12") }),
execute: ({ customer }) => messagesFrom(customer),
}),
whatWasFoundBefore: tool({
description: "What earlier runs concluded about this customer.",
inputSchema: z.object({ customer: z.string().describe("The customer's id, like c-12") }),
execute: ({ customer }) => already.found.filter((each) => each.customer === customer).slice(-3),
}),
},
// The tools say what it may do. This says who it may do it to: the
// model writes the arguments, so a limit on them is checked when it
// asks rather than when the job is written. One customer's file is not
// a reason to open everybody's.
toolApproval: { ordersTheyPlaced: theirs, whatTheyWroteIn: theirs, whatWasFoundBefore: theirs },
output: Reason,
// Both limits, because eight turns of a large model is not a small
// number. Whichever it reaches first ends the step with an error.
stopWhen: isStepCount(8),
budget: 0.05,
});
found.push({ at: new Date().toISOString(), customer: one.id, why: reason.why, next: reason.worthACall ? `call them: ${reason.next}` : reason.next });
}
await work.step("write down what was found", () => past.write({ found: [...already.found, ...found].slice(-50) }));
return { looked: found.length, found: found.map((one) => `${one.customer}: ${one.why}`) };
},
response: (r) => (r.looked === 0 ? "nobody has gone quiet" : r.found.join(". ")),
});Which of the two to write is in Step, model, agent. A job can also stop and wait for a person to decide: see Asking a person.
Run it
npx chloe # the agents, their cron lines and their chats
npx chloe agent shop # talk to it
npx chloe agent shop sort-messages # run one job nowEvery run records each step, what it returned and what it cost, so you can see which line asked a model and what that came to.
Next: run it on a schedule, put it on Telegram, Slack, Discord, WhatsApp or email, or read the examples.