Routines
Run a Chat or Tasks agent, or one of your bots, on a schedule, when an email arrives or when a webhook is called, and keep every run with its status, cost and result.
A routine is an instruction an agent carries out without anyone asking. It belongs to an agent: a Chat channel's agent, a Tasks agent, or one of your bots, with or without a computer. It has a name, an instruction, one trigger, an optional place to post the result, and an on/off switch. Every start is a run, kept with its status until you delete the routine.
Routines of Chat and Tasks agents need the Venom Computers add-on. Find them in the channel's settings (the agent section) and on the agent's computer page (the details panel).
A bot's routines live in Venom Agents, on the bot's page, and need no Computers add-on unless the bot has a computer of its own. Only the bot's owner sees or changes them; org admins don't. The rest of this page applies to them too, with the differences in Bots: each run is a quick chat with the bot that can go on for up to 5 turns, a destructive tool waits for the owner or is approved by the bot's autonomy, and the bot's daily cap ($2 by default) applies.
Triggers
Schedule. Every day, every weekday, chosen days of the week, a day of the month, or every few weeks, at a time in a time zone. A 09:00 routine stays at 09:00 across daylight saving. If the cloud was down at the time, the routine runs once for the latest occurrence that was due and passes over the older ones; it never piles up. Turning a routine back on starts from the next occurrence. Each occurrence is claimed once, even with several cloud instances sweeping.
Email. The routine has an address, https://<cloud>/api/routines/<id>/inbound. Point your mail provider's inbound
webhook at it (Postmark, SendGrid Inbound Parse, Mailgun routes or your own forwarder, the same shapes Venom Support takes),
with the routine's secret as ?secret=…, a bearer token, or the password of HTTP Basic auth. The sender, subject, body and the
names of the attachments become the run's context. The attachments themselves are not opened. A repeat of the same Message-ID is
the same run.
Webhook. POST https://<cloud>/api/routines/<id>/hook with the secret as Authorization: Bearer <secret> or
x-venom-routine-secret, or sign the body: x-venom-signature: sha256=<hex HMAC-SHA256 of the body>. The JSON payload (up to
1 MiB) becomes the run's context. Send x-venom-delivery or Idempotency-Key to make a retry the same run.
When something happens in Venom (event, a bot's routines only). A person added or changed, an interaction logged, a
deal created or moved to another stage, an issue created or changed, a note created or changed, with filters (your own
people, a pipeline and stage, a team or issues assigned to you, a vault and folder). The bot hears only of what its owner can
see, changes wait and go to one run together, and what a bot's own run writes never starts it again. The details are in
Bots → Events. A Chat or Tasks agent's routine cannot use this trigger.
curl -X POST 'https://<cloud>/api/routines/<id>/hook' \
-H 'Authorization: Bearer vrt_…' -H 'Content-Type: application/json' -d '{"event":"deploy","ok":true}'The secret is shown once, when the routine is made or its secret is replaced (New secret; the old one stops working at once). It is stored sealed in the vault (when the deployment has a vault key; without one only the bearer forms work, as the cloud keeps just a hash). The two addresses are public and answer a wrong secret, an unknown id and a routine of the other kind the same way. They allow 60 calls a minute per routine. A routine that is off answers 409.
Where the run goes
| The agent | The run |
|---|---|
| has a computer | a computer run on its browser, with approvals and Needs you as in Agents on computers; the routine's owner decides them |
| is a Chat agent without a computer | the Chat agent answers a message the routine posts in its channel, with the owner's rights in the other products |
| is a Tasks agent without a computer | an issue created in the Tasks team you pick, delegated to the agent; the run is done when the issue is completed |
| is a bot without a computer | a quick chat with the bot as its owner, driven turn by turn by the cloud; its transcript is linked from the run |
Post the result to is the run history only (default), the agent's channel in Chat, or a new Tasks issue in a team. A bot's
routine can instead add the result to a note in its owner's own Notes vault (target note, target_ref the note's path or
empty for Bots/<bot>/<routine>), one dated section per run, and can push its owner when a run finishes (notify_done).
Runs
A run is queued, running, needs you (a person must answer an approval or take over), done, failed or skipped. The detail shows why a run was skipped or failed, the context it was given, the result, the cost, and a link to the computer.
A run is skipped, with the reason, when:
- the previous run is still going and allow overlap is off (the default);
- the agent's daily limit is reached (the same limit as its other runs, Agents on computers);
- the agent is no longer there (the channel was archived, the Tasks agent turned off), or a Chat agent is off in the channel.
A run still open after six hours is closed as failed (a bot's run: six hours with no activity, or a day waiting for its owner). Run now makes a run as the trigger would and marks it manual.
Who can change them
A channel owner or an org admin for a Chat agent, an org admin for a Tasks agent. An agent cannot schedule itself. Members who can see the channel (or any member, for a Tasks agent) can read routines and runs.
MCP tools
On the Computers MCP server (/workspace/mcp/computers, scopes computers:read and computers:write):
computers_routine_list, _get, _create, _update, _delete, _run_now, _rotate_secret, computers_routine_run_list and
computers_routine_run_get. The REST twins are under /api/workspace/routines.
A bot's routines are on the Agents MCP server instead (agents_bot_routine_*, agents_bot_run_*, scopes agents:read and
agents:write), with REST twins under /api/workspace/agents/routines; see Bots.