Triggers

Fire a deployed agent on a schedule, from an inbound webhook, or from a queue.

A deployed agent doesn’t have to wait for a human to talk to it. Triggers fire an agent automatically and feed it an input on every run. Every fire — successful or not — lands in a unified audit log (agent_trigger_runs) so you can see exactly when, why, and with what input each agent woke up.

agntdata supports three trigger types:

Schedules

Cron-based timers. Fire an agent on a recurring schedule with a fixed input prompt.

Inbound webhooks

POST to a per-endpoint URL. agntdata stores the payload, signs the request, and dispatches the agent.

Queue

Enqueue work items and let the agent process them one by one. Coming soon.

Schedules

Schedules are stored in agent_schedules and dispatched by a pg_cron tick that runs every minute. Each row pairs a deployed agent with a 5-field cron expression, a timezone, and the user message to send on every fire.

1. Open the schedules tab

   From the dashboard sidebar, go to Schedules, or open an agent and switch to its Schedules tab.

2. Add a schedule

   Pick a name, the deployed agent, a 5-field cron expression (e.g. 0 9 * * 1-5 for weekday 09:00), and a timezone. The input text is the user message the agent will receive on every fire.

3. Enable it

   Schedules are enabled by default. Use the toggle to pause one without deleting it.

Cron format

agntdata uses the standard 5-field cron format: minute hour day-of-month month day-of-week. Seconds (6-field cron) are intentionally not supported — the dispatcher tick runs every minute, so the smallest meaningful resolution is one minute.

Expression	Meaning
*/15 * * * *	Every 15 minutes
0 9 * * 1-5	Weekdays at 09:00
0 0 1 * *	First day of the month at midnight

Timezone is configurable per-schedule (default UTC). The dispatcher uses cron-parser on the API server, so DST shifts are handled correctly.

How dispatch works

pg_cron calls a security-definer function once per minute. The function:

1. Picks up to 50 due rows (next_run_at <= now() and enabled = true), atomically clearing next_run_at so a second tick can’t double-fire.
2. POSTs each one to /system/cron-tick with a Vault-stored bearer secret.
3. The API recomputes next_run_at from the cron expression, creates an agent_session, and forwards the input text to the agent.
4. A row is written to agent_trigger_runs with trigger_type = 'schedule', the schedule id, the session id, and a status of dispatched, failed, or skipped.

Managing schedules via API

Schedules live under /dashboard/agents/:id/schedules and require a Supabase session. From an agent in the Builder, you can also use the meta-agent tools list_agent_schedules, create_agent_schedule, update_agent_schedule, and delete_agent_schedule — these write directly with no approval gate.

Inbound webhooks

Inbound webhooks turn an HTTP POST into an agent session. They’re useful for “react to this event” workflows — a Stripe payment, a form submission, a Zapier action, another agent’s outbound call.

1. Create a webhook endpoint

   From the dashboard go to Webhooks → Inbound endpoints and click Create endpoint. Optionally bind it to a deployed agent so deliveries trigger the agent automatically.

2. Copy the ingest URL

   Each endpoint gets a unique URL of the form https://api.agntdata.dev/webhooks/ingest/:hookId. Send any JSON payload to it via POST.

3. Configure signing

   Endpoints get a signing secret you can rotate at any time. When the third party supports HMAC-SHA256, set the secret on their side and agntdata will validate the X-Agntdata-Signature header.

4. Send a test payload

   The dashboard includes a Send test button that POSTs a small JSON body and shows you the resulting delivery + agent session.

What the agent receives

When a delivery comes in, agntdata:

1. Stores the raw payload in webhook_deliveries.
2. If the endpoint has a deployed_agent_id, creates an agent_session and sends the delivery JSON as the user message.
3. Writes an agent_trigger_runs row with trigger_type = 'webhook' referencing both the delivery and the new session.

The agent can also call agnt_webhooks_receive_recent at runtime to pull the tail of recent deliveries — useful for poll-style integrations where the agent needs to know what arrived since its last run.

Routing inbound traffic from other agents

A deployed agent can call its sibling via an outbound webhook (agnt_webhooks_send) pointed at an inbound endpoint on the receiving agent. Both ends are signed, so the receiving agent can verify the call came from inside the workspace.

Queue

Coming soon — see AGMX-27.

The queue trigger lets an agent process work items one at a time from a workspace-scoped FIFO queue. Producers (other agents, dashboard users, or external callers) push items; the agent wakes up, drains the queue, and processes each one in a fresh session.

Audit log

Every fire writes a row to agent_trigger_runs. The Builder meta-agent’s list_agent_trigger_runs tool reads this table, and the deployed-agent Activity tab in the dashboard renders it as a timeline.

Each row records:

Field	Meaning
trigger_type	schedule or webhook
schedule_id / webhook_delivery_id	Pointer to the source row
agent_session_id	The session the trigger created
status	dispatched, failed, or skipped
error	Populated when the dispatcher couldn’t fire (rate limit, plan limit, deleted agent, etc.)

Next steps

Sessions

How a triggered agent run is recorded and replayed.

Permissions

Keep humans in the loop for sensitive actions.

Webhooks overview

The full webhook surface — inbound, outbound, and signing.

Workspace database

Where triggered agents can read and write durable state.