---
title: Bots
description: Named agents with an avatar and your own standing instructions. Chat with one any time, or let it run on a schedule, an email, a webhook or when something happens in your workspace, and read what it did when you are back.
section: agents
order: 8
audience: [user, builder]
sources: [services/nodejs-cloud/lib/bots, services/nodejs-cloud/components/agents/BotsRoster.tsx, services/nodejs-cloud/components/agents/BotPage.tsx, services/nodejs-cloud/components/agents/BotAvatar.tsx, services/nodejs-cloud/components/agents/bots.ts, services/nodejs-cloud/app/api/workspace/agents/bots, "services/nodejs-cloud/app/(agents)/agents/bots", services/nodejs-cloud/migrations/0370_agent_bots.sql, services/nodejs-cloud/lib/bots/runs.ts, services/nodejs-cloud/lib/bots/routines.ts, services/nodejs-cloud/components/agents/BotRuns.tsx, services/nodejs-cloud/app/api/workspace/agents/routines, services/nodejs-cloud/app/api/cron/bot-runs, services/nodejs-cloud/migrations/0371_agent_bot_runs.sql, services/nodejs-cloud/lib/bots/events.ts, services/nodejs-cloud/lib/bots/events-pure.ts, services/nodejs-cloud/migrations/0372_agent_bot_events.sql, services/nodejs-cloud/lib/bots/templates.ts]
features: []
---

A bot is an agent you name and brief once. You give it a name, a face, and standing instructions: what it does, how you
like it done, and what it must never do. Then you chat with it whenever you need it, and it starts every chat already
knowing its job.

Each bot is yours alone. Other members of your organisation, admins included, can't open it, chat with it, change it or
run it. Your organisation's owners and admins can see that it exists in the [bot register](/docs/agents/bot-register.md): its name,
description and tile, that you own it, its autonomy, cap, servers, skills and gear, how it reaches out, its routines'
names and triggers, and how much it ran, spent and sent. They never see its instructions, its memory, its chats and runs,
or the messages it wrote.

A chat with a bot is a [quick chat](/docs/agents/quick-chat.md). The cloud runs the agent, it works only through MCP servers, it acts
as you with your own access and budgets, and anything that deletes, sends, publishes or shares waits for you to confirm.

## Make a bot

1. Open **Agents** and choose **Bots** in the sidebar, or go to `/agents/bots`.
2. Choose **New bot** (`/agents/bots/new`) and pick a starting point:

   | Template | What it does | Servers |
   |---|---|---|
   | Contacts keeper | Each night, picks who to get back to and drafts the messages (a routine at 05:30) | Notes, People |
   | People enricher | Each night, enriches your next people and notes what it was unsure about (a routine at 02:30) | Notes, People |
   | New contact filer | When you add someone, enriches, files and drafts a first hello (an event routine) | Notes, People |
   | Deal follow-up | When a deal moves stage, drafts the follow-up (an event routine) | Funnel, Notes, People |
   | Morning brief | A short brief of your day: meetings, due work, what changed | Calendar, Notes, Tasks |
   | Inbox triage | Sorts incoming messages into needs you, can wait, and no action | Comms, Notes, Tasks |
   | Research scout | Looks into a topic and writes up what it found, with sources, in a note | Notes, Studio |
   | Blank | Nothing filled in | Notes |

   A template fills in the form. The four that work on their own also show what they will schedule and may do, and
   **Make bot** makes the bot with those routines in one step, asking first and drafting only ([Bots that reach
   out](/docs/agents/bot-outreach.md)). Nothing is made until you choose **Make bot**, and you can change every field first.
3. Give it a name, one line about what it does, and its instructions. Write them as you would brief a person.
4. Choose **Make bot**. Its page opens at `/agents/bots/{id}`.

## Its face

With no effort at all, a bot gets a tile with its initials on a colour picked from its name, so every bot looks
different. On its page, under **Who it is**, you can:

- pick an emoji instead of the initials, or type any emoji under **Other**;
- pick a colour, or any colour with **+**;
- upload a picture (PNG, JPEG or WebP). The browser crops it to a square and shrinks it before it is sent, so any photo
  works. The picture is stored up to 256 KB and is served only to you.

The same tile shows on the roster, the bot's page, the sidebar and the header of every chat with the bot.

## Chat with a bot

Choose **Chat** on its card or its page. The new-chat screen opens with the bot's face and name, and your message starts
a quick chat with the bot's gear, servers and skills. The chat shows in the sidebar with the bot's avatar.

When the chat starts, the bot's name and instructions are added to the end of the agent's system prompt and kept with
the chat. Editing the bot later changes only new chats: a chat that already started keeps the instructions it started
with, so it stays consistent from the first message to the last. Deleting a bot keeps its chats, as plain quick chats,
and deletes its routines and their run history (the runs' chats stay too).

You can attach pictures, Word documents and text files to your messages, as in any quick chat: the paperclip, a pasted
screenshot, or files dropped on the chat ([Files and pictures in a chat](/docs/agents/attachments.md)). They stay private to you and
the chat. A run on its own works in a chat of its own, so it sees only the files you send in that run's chat (when you
answer it there); treat a file you attach to a run that acts without asking as you would text you paste into it.

A server you disconnected since you set up the bot, or a skill that is gone, is left out of a new chat instead of
stopping it. The same goes for a gear the cloud can no longer run: the chat (or the run's chat) uses your default gear and
says so at the top, with the reason. The bot's page shows the same reason under its **Gear** picker.

## Settings

| Setting | Default | What it does |
|---|---|---|
| Name | required | 1 to 80 characters. |
| One line | empty | Shown on its card. At most 200 characters. |
| Instructions | empty | Its persona and standing instructions, at most 16 KB. |
| Servers | Notes | The MCP servers its chats may use, from the same list as a quick chat's **Servers** picker. |
| Skills | none | Your organisation's skills its chats may use, as in a quick chat. |
| Gear | your default | The model preset its chats run on. |
| On / Off | On | Off: you can't start a new chat with it. Chats already open keep working. |
| When it works on its own | Ask me first | For runs with no one watching. **Ask me first**: it stops before anything that deletes or sends and waits for you. **Act without asking**: it may delete and send by itself, as you. A chat always asks, whatever this says. |
| Daily spending cap | $2 | The most it may spend a day on its own runs, in dollars. Your own budgets apply either way. |
| Keep a memory | On | A memory note it reads at the start of every run and chat, and updates itself (below). |
| Its own computer | Off | With Venom Computers: its routines run on a computer of its own. |

You can keep up to 50 bots.

## Bots that run by themselves

A bot can work while you are away. Give it routines on its page under **Routines**: each one is an instruction and a
trigger. Three are the same as any [routine](/docs/computers/routines.md), and the fourth is for bots only:

- **Schedule**: every day, every weekday, chosen days, a day of the month or every few weeks, at a time in your time zone.
- **Email**: an address a mail provider forwards to.
- **Webhook**: an address another service calls with the routine's secret.
- **When something happens in Venom**: a person added or changed, a deal moved, an issue created or assigned to you, a
  note written. See [Events](#events) below.

**Run now** starts a run at once. A bot's routines need no Venom Computers add-on, unless the bot has a computer of its
own (below). A bot that is off doesn't run.

### A run

Each run is a fresh quick chat with the bot, as you, with its instructions, gear, servers and skills. Its first message
is the routine's instruction, the bot's memory, and, for an email or a webhook, what arrived. That last part is fenced off
as untrusted data: the bot is told to treat it as material to work on, never as orders, and nothing in it can change the
bot's servers, skills, autonomy or instructions, which are fixed before the run starts.

A run's chat is kept out of your chat list, but it is not hidden: every run links to its transcript, which shows each
step the bot took. That transcript is the record of what it did.

A turn that runs out of steps or time goes on in another turn, up to 5 turns a run, so a long task is finished rather than
left half done. A run with no activity for six hours is closed as failed.

The **Runs** section lists each run with its status (queued, running, needs you, done, failed, skipped), what started it,
when it started, how long it took, what it cost, the first line of its result, and a link to the transcript.

### Ask first or act on its own

**When it works on its own** decides what happens when a run reaches a tool that deletes, sends or changes something hard
to undo:

- **Ask me first** (the default): the run stops and shows under **Needs you** on the bot's page, with the tool and what
  it wants to do it with. You get a push notification. **Approve** runs the tool and the run goes on; **Decline** tells the
  bot it did not run, and it finishes without it. You can also answer in the run's chat. Left unanswered for 24 hours, the
  request is declined and the run finishes with what it has.
- **Act without asking**: the run approves the tool itself and goes on. The run's steps record it as "approved by
  autonomy". After 20 such approvals in one run, it asks you for the rest.

A chat you have with the bot yourself always asks, whatever this setting says.

A run started by an **email or a webhook** asks you first even when the bot acts without asking. Whoever can get text
into that email or webhook could otherwise talk the bot into deleting or sending something with your access. If you
trust the sender, tick **Let what arrives steer the bot** on that routine (`trust_context` in the API); its runs then
follow the bot's setting like scheduled runs do. Only you can turn it on: an agent, a bot's own run included, cannot.
Scheduled runs and **Run now** always follow the bot's setting. So do runs started by [events](#events): what they are told
about is your own workspace, which the bot would read on any scheduled run too, so they need no such switch. The names
and titles in that list are still fenced as data, never as instructions.

### What it may spend

Each bot has a daily cap for its runs, in dollars, counted from midnight UTC. With no cap set, it is $2 a day. A run's
cost is what its model calls cost through your key, recorded on the run as it goes. When the cap is reached, new runs
are skipped with the reason, and a run already going stops before its next turn. At most 3 runs of one bot go at once
(waiting for you counts); more are skipped, so a burst of runs cannot overshoot the cap by much. Your own budgets apply
either way.

### Where the result goes

Every run keeps its result in the run history. A routine can also send it on:

| Result to | What happens |
|---|---|
| Run history only | Nothing else (the default). |
| A note in my vault | The result is added to a note in your own vault as a dated section (`## 2026-11-17 07:00 · Morning brief`), under `Bots/<bot>/<routine>` unless you give a path. The note is made on the first run; the oldest sections go once it passes 150 KB. |
| A Tasks issue | A new issue in a Tasks team you are in. |

You get a push notification when a run needs you or fails. Tick **Push me when a run finishes** on a routine to hear about
good finishes too.

### While you were away

The bots roster (`/agents/bots`) opens with a brief of what ran since you last dismissed it, at most three days back: per
bot, how many runs finished, failed or wait for you, and one line from each run with a link to its transcript. It is
worked out from the run history, not written by a model. **Dismiss** clears it until something new runs.

Each card on the roster shows when the bot runs next, how its last run went, and how many runs wait for you. The
**Bots** heading in the sidebar shows the same count across all your bots.

### Working now

A small blue dot pulses at the corner of a bot's avatar while it is working: on its sidebar row, its roster card (with a
**Working now** badge) and its page. Hover over it, or use a screen reader, to hear what it is doing and for how long,
such as "Working: Morning brief · 2 min". On the bot's page, **Working now** sits under its name and above its runs, with
a link to the live transcript. The dot holds still if you have reduced motion turned on.

A bot counts as working while one of its runs is queued or going, or while a chat you have with it has a turn running.
A run waiting for you is not working: it shows the amber **Needs you** dot instead. When both apply, you see both.

The dot only shows real activity. A run counts while its driver holds it, its chat's turn is running, or it moved in the
last five minutes (ten for a run on the bot's own computer, which reports each step). A run whose process crashed stops
showing once that time passes, long before it is closed as failed. A queued run that has not started within five minutes
does not count either.

The sidebar and the roster check every minute, and every 15 seconds while one of your bots is working, so the dot shows
up and clears without a reload. `agents_bot_summary_list` and `GET /api/workspace/agents/bots/summary` return the same
thing as `working` on each bot: what started it (`kind` `routine` with `routine_id` and `routine_name`, or `chat`), `since`,
the `chat_id` to open, and `count` when more than one is going; `null` when it is idle or only waiting for you.

### Reaching out and enriching

A bot can write to your people, as drafts you check, sent for you through Venom Comms, or sent from your own WhatsApp Web
or LinkedIn on its own computer, and fill in your People records,
inside limits set under **Outreach** on its page: channels, daily caps, pacing, quiet hours, a re-contact window and who it
may contact. With **Ask me first**, a run's messages wait for you together in one card under **Needs you**. See [Bots that
reach out](/docs/agents/bot-outreach.md).

## Memory

A bot can keep a memory: a note in your own vault at `Bots/<bot name>/Memory`, made the first time it is needed.
The newest 8 KB of it come with the first message of every run and every chat with the bot. It is not part of the
system prompt, so a chat's prompt stays the same from turn to turn. The bot is told where the note is and updates it
itself with the Notes tools when it learns something worth keeping.

You can read and edit the memory on the bot's page under **Memory**, or open the note in Notes. Memory is on by default;
turn it off under **Settings**. With memory on, Notes is always among the bot's servers. Memory needs Venom Notes.

## Events

A routine whose trigger is **When something happens in Venom** starts when something changes in your workspace. Pick one or
more events, grouped by product, and narrow them with filters:

| Event | What it means | Filters |
|---|---|---|
| `people.person.created` | A person is added to People | only my own people |
| `people.person.updated` | A person's name, role, company, location, tags, notes, circle, profile or sharing changes | only my own people |
| `people.interaction.created` | An interaction is logged on one of your own people | none |
| `funnel.deal.created` | A deal is created | pipeline |
| `funnel.deal.stage_changed` | A deal moves to another stage | pipeline, the stage it moved to |
| `tasks.issue.created` | An issue is created | team, assigned to me |
| `tasks.issue.updated` | An issue changes | team, assigned to me |
| `globe.note.created` | A note is created | vault, folder |
| `globe.note.updated` | A note changes | vault, folder |

People's background jobs (relationship strength, the context card, last touch times) are not changes to a person, so they
start nothing. The form also has three starting points: a new contact enriched with a note, a follow-up drafted when a deal
moves stage, and a plan for an issue assigned to you.

**What the bot hears of.** A bot acts as you, so it hears only of what you can see yourself, judged the way each product
judges it: your own people and those shared with you, the deals Funnel shows you, issues in the teams you can see (never a
private team you are not in), and notes in vaults you can read. Something you cannot see never reaches the routine, not
even as a count. Access is checked as each change is read, so once you lose access to something, its later changes stop reaching your bots.

**Batching.** Changes wait for the routine's next run instead of each starting one. A routine has one run at a time, and its
runs are at least **Minutes between runs** apart (5 by default, from 1 minute to a day). A run takes everything that waited:
its first message lists up to 25 items, each with its reference (`person:…`, `deal:…`, `issue:…`, `note:…`, which the bot
opens with `workspace_item_get`), its title, its events and what changed. The rest are counted, and the bot lists them with
`agents_bot_run_event_list`. Several changes to one item while it waits are one line ("changed: role, company (3 changes)").
At most 500 items wait per routine; past that the oldest are dropped, and the next run is told how many. So an import of
6,000 contacts is a run every few minutes with the newest 500, not 6,000 runs, and the bot's daily cap still applies.
Each run's line on the bot's page says how many changes started it; open the run to see them.

**Loops.** What a bot writes during its own run never starts that bot's routines again: every write a run makes through
Venom's tools, its result note or issue, and its memory note carries the run's mark, and the routine skips it. A change
one of your bots made can start another bot's routine, one step deeper; after two such steps it starts nothing, so two bots
cannot keep waking each other up. As a backstop, a routine whose last 5 event runs in a row were started only by changes
made while its own bot was running is turned off, with the reason on its line under **Routines**. Check its instruction
and filters, then turn it on again. A bot with its own computer calls Venom's tools with its run's own key, and those
calls carry the run's mark too, so its own writes don't start its routines either.

An event routine has no secret and no address. Like every routine, only you can make or change it; a bot's own run cannot
make itself one, nor add events to one.

## A bot with its own computer

With the Venom Computers add-on, a bot can have a computer of its own: turn on **Its own computer** under **Settings**.
Its routines then run on that computer, as computer runs, like the routines of other agents. Only you can give your bot
a computer.

**Asks on the computer.** The session on the computer asks before some steps (the first action on a site, a form that
sends something, a Venom tool that changes things), and sometimes needs a person (a login, a 2FA code, a CAPTCHA: a
takeover). Who answers:

- With **Act without asking**, ordinary approvals are answered for you, in a run started by a schedule, by hand or by an
  event (or by an email or a webhook when its routine trusts what arrives), up to 20 a run. Each one is listed in the run's
  steps as approved by autonomy. Only a plain browser step on the site the ask names, or a call to Venom's own tools, is
  answered for you. Never answered for you: a takeover, typing into a password or code field, a payment form, an upload, a
  download, a file, a shell command, another server's tool, or an ask Venom can't place. Those always wait for you.
- With **Ask me first**, every approval waits for you, as today.
- The outreach tools answer for themselves, in either setting: they hold a message for your card, or send within your
  limits, as [Bots that reach out](/docs/agents/bot-outreach.md) describes. A run made to send messages you approved in the card may
  act on WhatsApp Web and LinkedIn without asking again.

Every ask that waits for you sends a push notification.

**When nobody comes.** The session on the computer can't wait long for an answer: the daemon's `venom serve` gives up on
an ask after 10 minutes, and closes an idle session after 30. So a bot's run that needed you while you were away doesn't
sit with the browser open. The computer run finishes with what it could do, and the run is **parked**: it stays under
**Needs you** with what it needed, for up to 12 hours. **Continue** (after you did what it needed on the computer, such as
logging in) starts a fresh run on the computer that is told why the first attempt stopped and what it reported, so it
doesn't redo what is done. **Finish now** closes it with what it had. After 12 hours it finishes by itself and says so in
its result, which the brief shows. Twelve hours covers a night (a 2 a.m. login answered by 2 p.m.); past that, the run's
context is stale.

## API and MCP tools

The Agents MCP server (`/workspace/mcp/agents`) has these tools for bots: `agents_bot_list`, `agents_bot_get`,
`agents_bot_create`, `agents_bot_update` and `agents_bot_delete`. Chat with a bot with `agents_chat_create` and
`bot_id`. An `avatar_image` is a base64 PNG, JPEG or WebP of at most 256 KB; `null` removes it.

For runs: `agents_bot_routine_list`, `agents_bot_routine_get`, `agents_bot_routine_create`, `agents_bot_routine_update`,
`agents_bot_routine_delete`, `agents_bot_routine_run`, `agents_bot_secret_rotate`, `agents_bot_run_list`,
`agents_bot_run_get`, `agents_bot_run_event_list`, `agents_bot_run_decide`, `agents_bot_summary_list`, `agents_bot_brief_get`,
`agents_bot_brief_dismiss`, `agents_bot_memory_get` and `agents_bot_memory_update`.

Only a person sets up a bot's routines or answers what it asks. A quick chat acting for you, a bot's own run among them,
and any agent's run on a computer (it calls Venom with a key made for that run, which Venom recognises by the key itself,
not its name) is refused when it tries to make, change or run a routine, approve a run or an ask on a computer, or change
a bot's autonomy, cap, servers or on/off.

The console's routes are the same functions:

| Method and path | What it does |
|---|---|
| `GET /api/workspace/agents/bots` | Your bots, most recently used first |
| `POST /api/workspace/agents/bots` | Make one (`name` required) |
| `GET /api/workspace/agents/bots/{id}` | One bot, with its instructions |
| `PATCH /api/workspace/agents/bots/{id}` | Change any field |
| `DELETE /api/workspace/agents/bots/{id}` | Delete it with its routines; your chats with it stay, its runs' chats are archived |
| `GET /api/workspace/agents/bots/{id}/avatar` | Its uploaded picture, to you only |
| `POST /api/workspace/agents/chats` with `bot_id` | Start a chat with it |
| `GET`, `PUT /api/workspace/agents/bots/{id}/memory` | Its memory note; `PUT {body}` rewrites it |
| `GET /api/workspace/agents/bots/summary` | Per bot: next run, last run, runs waiting for you, today's spend and cap |
| `GET`, `DELETE /api/workspace/agents/bots/brief` | What ran since you last looked; `DELETE` dismisses it |
| `GET`, `POST /api/workspace/agents/routines` | Your bots' routines (`?bot_id=`); make one with `bot_id` |
| `GET`, `PATCH`, `DELETE /api/workspace/agents/routines/{id}` | One routine |
| `POST /api/workspace/agents/routines/{id}/run` | Run it now |
| `POST /api/workspace/agents/routines/{id}/secret` | A new secret for an email or webhook routine |
| `GET /api/workspace/agents/routines/runs` | Your bots' runs (`?bot_id=`, `routine_id`, `status`) |
| `GET /api/workspace/agents/routines/runs/{id}` | One run, with its steps and chat |
| `GET /api/workspace/agents/routines/runs/{id}/events` | Every change an event run took |
| `POST /api/workspace/agents/routines/runs/{id}/decide` | `{action: "approve" \| "decline"}` for a run that waits for you |

Someone else's bot, routine or run answers `404 not_found` on these routes, for org admins too; owners and admins list
every bot's metadata in the [bot register](/docs/agents/bot-register.md). Starting a chat with a bot that is off answers `409 bot_off`, and a 51st bot
answers `409 bot_limit`. Every change is in the audit log as `agents.bot_created`, `agents.bot_updated` or
`agents.bot_deleted`.

## Related

- [Quick chats](/docs/agents/quick-chat.md): how a bot's chats run.
- [Routines](/docs/computers/routines.md): triggers, secrets and run history, shared with Chat and Tasks agents.
- [The Agents app](/docs/agents/app.md): the sidebar, chats and notifications.
- [Chats API and MCP tools](/docs/agents/api.md): the rest of the agents tools.
