5. Triggering Agents

By now your Agent can already work through manual conversations in the Web UI. This chapter covers how to let it start working without human intervention—by time, by external event, by API call.

The concepts, boundaries, and the “why it’s split this way” behind these three trigger methods are covered in Where an Agent Gets Its Tasks. This chapter is the hands-on version, ordered from easiest to hardest:

Schedules —zero external dependencies, the simplest
External events —integrate external systems via Slack, Webhook, WeCom
API triggers —use a Service Token to let programs call the platform directly

Schedules

At the top of the Workspace, go to Automation → Schedules and create one. You need to fill in three things:

Name —used for list display and log identification (e.g. daily-report)
Schedule —a cron expression
Prompt —the instruction sent to the Agent each time it triggers

The standard five-field cron format: minute hour day month weekday.

Example	Meaning
`0 9 * * *`	Every day at 9:00
`0 9 * * 1-5`	Weekdays at 9:00
`/30 * * *`	Every 30 minutes
`0 0 1 * *`	The 1st of every month at 0:00

The time zone follows the browser by default and can be set separately.

Things to note

Each trigger is an independent Session —context is not shared. If you need to “continue from last time’s state,” have the Agent write its state to a file or put it in Memory
A minimum interval of at least 5 minutes is recommended —the platform’s scheduler has buffering, so very short intervals are not meaningful
Disabling keeps the configuration —no need to delete it to pause for a while

Schedules are best suited for: a daily system health check, hourly fetch-and-summarize of new email, weekly data roundups.

External events: Connectors + Routes

When external systems (GitLab, GitHub, Jira, Slack, WeCom, etc.) want to proactively call an Agent into action, two objects work together:

Connector —the “door” that receives events. One Connector corresponds to one external system’s ingress endpoint
Route —a rule attached under a Connector. It decides which events go to which Workspace and how they become a Prompt

The design rationale for these two objects is covered on the concepts page—here we go straight to how to configure them.

Webhook: the most universal integration

The vast majority of SaaS products support Webhooks (GitLab, GitHub, PagerDuty, Jira, various CI systems). The flow:

Step 1: Create a Webhook Connector

In the sidebar, go to Integrations → Connectors → New, and choose type Webhook. A Webhook Connector itself requires no extra credentials.

Step 2: Create a Route

In the sidebar, go to Integrations → Routes → New. Configure:

Connector —the one you just created
Endpoint Path —the URL path to listen on (e.g. /gitlab-ci), combined with the Connector to form the full receiving address
Workspace —which Workspace handles events that match
Secret —the signing key. External pushes carry the same key; the platform processes them only after verifying it. Both Plain and HMAC-SHA256 are supported (GitHub uses the latter)
Filter —filtering rules; only events that satisfy all conditions will trigger (see below)
Prompt template —the template that turns the HTTP request into a Prompt; the available variables are listed below

Variables available in the Prompt template:

Variable	Description
`{body}`	The full request body
`{body.field}`	A nested field of the request body
`{query.key}`	A URL query parameter
`{headers.name}`	A request header
`{method}`	The HTTP method
`{path}`	The request path

Leave it empty to use the raw request body directly as the Prompt.

Step 3: Configure the Webhook in the external system

Put the full URL generated by the Route into the external system’s Webhook configuration, and set the secret to match. The exact steps differ for each external system, but the URL and secret are constant.

Filter: filter first, save tokens

Filtering at the Route layer happens before a Session is created. Events that don’t match are dropped outright—no Agent is started, no tokens consumed.

Supported operators:

Operator	Description
`=`	Exact match
`≠`	Not equal
`in`	Value is in a list (comma-separated)
`exists`	Whether the field exists

For example: for CI events pushed from GitLab, you only want to handle failed jobs:

body.build_status = failed
body.tag = false
body.build_name ≠ sonarqube-check

All three rules must be satisfied to trigger; otherwise the event is dropped.

Don’t hand fixed filter conditions to the Agent to judge. Any filter condition that can be written as a rule should go in the Filter—so you don’t spin up a Session and load context every time just to “take a look and then decide not to act.” The Agent prompt should only handle complex judgments that require semantic understanding (for example, “if the same issue was already replied to last time, don’t reply again”).

Slack integration

The Slack integration flow is similar, but the credentials are a bit more involved—you first need to create an App in Slack, enable Socket Mode, and obtain two tokens:

Bot Token (xoxb-...) —from the OAuth & Permissions page
App Token (xapp-...) —from the Basic Information page, with scope connections:write

The scopes the Bot Token needs: chat:write, channels:history, channels:read, app_mentions:read.

After filling in the tokens and creating the Slack Connector, attach a Route to it—choose the channel to listen on (only channels the bot has joined are listed) and the target Workspace.

A Slack Route additionally supports multi-turn conversation within a thread: consecutive messages in the same thread reuse the same Session, with a default TTL of 24 hours. The Prompt template has more variables available than Webhook: {message}, {user}, {thread_context}, {channel}.

WeCom integration

If your team uses WeCom, you can integrate a WeCom smart bot so that @-mentioning the bot in a group directly triggers an Agent.

You need to create a smart bot (not a custom app) in the WeCom admin console, obtain its Bot ID and Secret, and fill them into the WeCom Connector.

Things to note: passive replies have a 24-hour window and are rate-limited (30 messages/minute), so this isn’t suitable for high-frequency scenarios.

API triggers: Service Token

If you want a program to call the Agent directly—from a CI pipeline, an automation script, or a small tool you wrote yourself—you can use a Service Token.

In the sidebar, go to Integrations → Service Tokens → New. The token is shown only once after creation, so save it immediately.

Afterwards, include it in the Authorization header of your HTTP requests:

Authorization: Bearer <token>

For the full list of which endpoints you can call and their URLs, see the API docs.

A quick reference

What you want to do	What to use
Run on a daily/hourly schedule	Schedules
Run when an external SaaS emits an event	Webhook Connector + Route
Trigger by @-mentioning a bot in Slack	Slack Connector + Route
Trigger by @-mentioning a bot in WeCom	WeCom Connector + Route
Call from program code	Service Token + REST API

Let Agents collaborate with each other → Guide 6: Composing Agents.