Skip to content
Docs menu

Bots

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.

View .md

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: 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. 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). 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). 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, 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 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: 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.

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 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. 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.