Skip to content
Docs menu

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.

View .md

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.