> ## Documentation Index
> Fetch the complete documentation index at: https://agnt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CardGroup cols={3}>
  <Card title="Schedules" icon="clock">
    Cron-based timers. Fire an agent on a recurring schedule with a fixed input prompt.
  </Card>

  <Card title="Inbound webhooks" icon="webhook">
    POST to a per-endpoint URL. agntdata stores the payload, signs the request, and dispatches the agent.
  </Card>

  <Card title="Queue" icon="list-check">
    Enqueue work items and let the agent process them one by one. *Coming soon.*
  </Card>
</CardGroup>

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

<Steps>
  <Step title="Open the schedules tab">
    From the dashboard sidebar, go to **Schedules**, or open an agent and switch to its **Schedules** tab.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Enable it">
    Schedules are enabled by default. Use the toggle to pause one without deleting it.
  </Step>
</Steps>

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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](https://github.com/agntdata/agntdata).*

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

<CardGroup cols={2}>
  <Card title="Sessions" icon="messages" href="/agents/sessions">
    How a triggered agent run is recorded and replayed.
  </Card>

  <Card title="Permissions" icon="shield" href="/agents/permissions">
    Keep humans in the loop for sensitive actions.
  </Card>

  <Card title="Webhooks overview" icon="webhook" href="/webhooks/overview">
    The full webhook surface — inbound, outbound, and signing.
  </Card>

  <Card title="Workspace database" icon="database" href="/agents/workspace-database">
    Where triggered agents can read and write durable state.
  </Card>
</CardGroup>