# Triggers and automations

> Wake an agent on a webhook, an app event, one of NoClick's own events, a schedule (as an automation) or each message on a queue.

A **trigger** wakes an agent without anyone messaging it: a call to a URL, something happening in one of its connections, or a time on a schedule. Each time one fires, the agent takes a turn, exactly as if it had been sent a message, and reads what arrived the way a trigger wired into an agent on the canvas does. An agent with a schedule is an **automation**, and the developer console lists automations apart from your other agents.

| Trigger | Wakes the agent | Defined with |
| --- | --- | --- |
| Webhook | on each POST to a URL it's given | `noclick.OnWebhook` |
| App event | when something happens in a connection: a Slack message, a new HubSpot contact | `noclick.OnEvent` |
| NoClick event | when something happens on the platform: an operation fails, a connection breaks | `noclick.OnPlatformEvent` |
| Email | on each message to an [inbox](https://www.noclick.com/docs/guide/inboxes.md) it answers | `Inbox.create(agent=...)` |
| Call | on each call to a [phone number](https://www.noclick.com/docs/guide/phone-numbers.md) it answers | `PhoneNumber.answer_with` |
| Schedule | at the times a cron expression names | `noclick.Cron` |
| Queue | on each message put on a [queue](https://www.noclick.com/docs/guide/queues.md) | `noclick.OnQueue` |
| Approval | when a person answers a tool call your [policy](https://www.noclick.com/docs/guide/policy.md) held | your policy |

A trigger wakes the agent every time it fires. To give one conversation a single turn later, or when something finishes, set a [wake-up](https://www.noclick.com/docs/guide/agents.md#wake-it-up-later) instead.

## Wake it with a webhook

```python
fulfilment = noclick.Agent.from_name(
    "fulfilment",
    create_if_missing=True,
    instructions="You confirm new orders with the customer by email.",
    tools=["gmail.send_email_message"],
    triggers=[noclick.OnWebhook(name="orders", message="A new order arrived. Confirm it with the customer.")],
)
[orders] = fulfilment.triggers()
print(orders.url)   # POST your order JSON here
```

```ts
import { Agent, OnWebhook } from "noclick";

const fulfilment = Agent.fromName("fulfilment", {
  createIfMissing: true,
  instructions: "You confirm new orders with the customer by email.",
  tools: ["gmail.send_email_message"],
  triggers: [new OnWebhook("orders", { message: "A new order arrived. Confirm it with the customer." })],
});
const [orders] = await fulfilment.triggers();
console.log(orders.url);   // POST your order JSON here
```

Point your order system, a form tool or any service that sends webhooks at `url`. Each POST is a turn: the agent reads `message`, then the call (its method, any query parameters, and the body: JSON as JSON, anything else as text, up to 256 KB). Headers never reach the agent, so a caller's credentials stay out of its turn. The call answers `202` at once with the delivery: its `status` (`delivered`, or `pending` while the agent works on another turn), the turn's `operation_id` once it has one, and the `conversation` it runs in. The turn runs on.

Anyone with the URL can wake the agent, so keep it like a key. It stays the same for as long as a webhook trigger of that `name` stays on the agent; remove it and add it again for a new URL.

Every delivery lands in the agent's one session. To mark deliveries as one thread, your ticket id say, send its key in a `NoClick-Conversation` header or give the trigger a `conversation` template ([Keep related deliveries together](https://www.noclick.com/docs/guide/triggers.md#keep-related-deliveries-together)): the key tags each message with where it came from.

## Wake it on an app event

```python
slack = noclick.Connection.from_name("slack", integration="slack", create_if_missing=True)
support = noclick.Agent.from_name(
    "support",
    create_if_missing=True,
    instructions="You answer questions in #support. Reply in the thread.",
    tools=[slack],
    triggers=[noclick.OnEvent(slack, "channel_message", channel="C0123ABCD")],
)
```

```ts
import { Agent, Connection, OnEvent } from "noclick";

const slack = Connection.fromName("slack", { integration: "slack", createIfMissing: true });
const support = Agent.fromName("support", {
  createIfMissing: true,
  instructions: "You answer questions in #support. Reply in the thread.",
  tools: [slack],
  triggers: [new OnEvent(slack, "channel_message", { filters: { channel: "C0123ABCD" } })],
});
```

`OnEvent` subscribes the agent to one of a [connection](https://www.noclick.com/docs/guide/connections.md)'s app events, named as its integration names them: `channel_message` or `app_mention` for Slack, `contact_created` for HubSpot, `issue_created` for Linear, `issue_labeled` for GitHub, `invoice_payment_failed` for Stripe, `receive_webhook_messages` for a [Telegram bot](https://www.noclick.com/docs/guide/connections.md#telegram). The connection is from the agent's own scope, its user's or your account's, named or passed as a `Connection` (an account agent's may be one [connected in the app](https://www.noclick.com/docs/guide/connections.md), by its `credential:` id), and keyword arguments narrow the event, each as the integration's own field takes it: a Slack `channel` is the channel's id, which `slack.lookup("channel")` lists. `message=` works as it does for a webhook.

`events()` lists the app events a connection's integration has, with the filters each takes (one whose description starts `Required.` must be given). Like `operations()`, it reads the catalog, so the connection needn't be connected yet, and `Connection.integrations()` names each integration's `events` too, empty for one that only acts. Only what an app pushes as it happens is an event; new mail in Gmail, which NoClick polls for, isn't one:

```python
for event in slack.events():
    print(event.name, event.description, list(event.filters))
```

```ts
for (const event of await slack.events()) {
  console.log(event.name, event.description, Object.keys(event.filters));
}
```

Each event's `shape` is what its data holds, field by field with its type (`"string"`, `"integer"`, `"boolean"`, `"null"`, an object, or `[...]` for a list), as that event has reached your account, and `sample` is the same with a placeholder for each value; both are `None` until one has, since another account's events can name its own fields and never show here. Code that reads an event's fields (an [app's](https://www.noclick.com/docs/guide/apps.md#hear-app-events), or a filter's) can be written against them.

The turn carries the event as the service described it, with the ids the agent needs to act on it: the channel and thread to reply in, the contact to update. A thread stays one conversation, so a follow-up in the same Slack thread continues the agent's conversation there. Messages the agent itself sends to Slack never wake it again.

An event trigger needs its connection connected. Until it is, the trigger's `status` is `error` and nothing fires; once the account connects (or reconnects), NoClick registers it and the next event wakes the agent. Deleting the connection stops the trigger, with `error` saying so.

To see what the agent does with an event before a real one comes, `rehearse_trigger` runs the turn a sample of it would start (its `sample`, under the trigger's `message`, or a note that it holds no data until one has reached your account) as a [test run](https://www.noclick.com/docs/guide/agents.md): the agent's real model and instructions, with a simulated world answering its tool calls, so nothing is sent and the connection needn't be connected:

```python
run = support.rehearse_trigger(noclick.OnEvent(slack, "channel_message", channel="C0123ABCD"))
print(run.wait().reply)
```

```ts
import { OnEvent } from "noclick";

const run = await support.rehearseTrigger(new OnEvent(slack, "channel_message", { filters: { channel: "C0123ABCD" } }));
console.log((await run.wait()).reply);
```

An app can take the same events at one of its own paths instead, with no agent in between: see [Hear app events](https://www.noclick.com/docs/guide/apps.md#hear-app-events).

A label is a good switch for work you hand an agent. GitHub's `issue_labeled` names the repository to watch, so the agent wakes when someone labels an issue there, one conversation per issue:

```python
github = noclick.Connection.from_name("github", integration="github", create_if_missing=True)
triage = noclick.Agent.from_name(
    "triage",
    create_if_missing=True,
    instructions="When an issue is labelled 'agent', reproduce the bug, then comment with what you found.",
    tools=[github],
    triggers=[noclick.OnEvent(github, "issue_labeled", repository="acme/api", conversation="issue-{issue.number}")],
)
```

```ts
import { Agent, Connection, OnEvent } from "noclick";

const github = Connection.fromName("github", { integration: "github", createIfMissing: true });
const triage = Agent.fromName("triage", {
  createIfMissing: true,
  instructions: "When an issue is labelled 'agent', reproduce the bug, then comment with what you found.",
  tools: [github],
  triggers: [new OnEvent(github, "issue_labeled", { filters: { repository: "acme/api" }, conversation: "issue-{issue.number}" })],
});
```

## Wake it on a NoClick event

The [events](https://www.noclick.com/docs/guide/webhooks.md#event-types) your webhooks receive can wake an agent too, with no server of yours in between: a job failing, a connection breaking, a channel halting.

```python
triage = noclick.Agent.from_name(
    "triage",
    create_if_missing=True,
    instructions="When a job fails, find out why from its error and tell the team in #ops what to do.",
    tools=["slack.send_message_to_channel"],
    triggers=[noclick.OnPlatformEvent("operation.failed", filters={"kind": "agent.task"},
                                      message="A job failed.")],
)
```

```ts
import { Agent, OnPlatformEvent } from "noclick";

const triage = Agent.fromName("triage", {
  createIfMissing: true,
  instructions: "When a job fails, find out why from its error and tell the team in #ops what to do.",
  tools: ["slack.send_message_to_channel"],
  triggers: [new OnPlatformEvent("operation.failed", { filters: { kind: "agent.task" }, message: "A job failed." })],
});
```

`type` is an event type, and `*` matches the rest of a name (`"connection.*"`). `filters` are dotted paths into the event's `data` and the values they must have: the one above hears only failed [jobs](https://www.noclick.com/docs/guide/sub-agents.md). The turn reads `message`, then the event: its type, id, user and `data`. Each event is a conversation of its own unless `conversation` keys it, a template over the event (`"connection-{data.id}"`).

An agent hears its user's events, and one of your account's agents hears every event, your users' included, as your account's webhooks do. It never hears what its own turns caused, so an agent listening for `agent.turn.completed` isn't woken by its own replies, and agents waking each other this way stop after five turns in a row. A NoClick event needs no URL and no connection, so its trigger is `active` from the start; it hears events from the moment it's added.

## Run on a schedule

```python
import noclick

digest = noclick.Agent.from_name(
    "digest",
    create_if_missing=True,
    instructions="You summarize yesterday's support tickets for the team.",
    tools=["search", "slack.send_message_to_channel"],
    triggers=[noclick.Cron("0 8 * * 1-5", tz="Europe/London", message="Post the overnight summary in #support")],
)
```

```ts
import { Agent, Cron } from "noclick";

const digest = Agent.fromName("digest", {
  createIfMissing: true,
  instructions: "You summarize yesterday's support tickets for the team.",
  tools: ["search", "slack.send_message_to_channel"],
  triggers: [new Cron("0 8 * * 1-5", { tz: "Europe/London", message: "Post the overnight summary in #support" })],
});
```

A `Cron` is a five-field cron expression (minute, hour, day of month, month, day of week) read in `tz`, an IANA timezone that defaults to UTC, so the run above happens at 8:00 London time on weekdays, daylight saving included. Each field takes numbers, `*`, ranges (`1-5`), steps (`*/15`), lists (`1,15`) and month or day names (`jan`, `mon-fri`); `L`, `W`, `#` and seconds aren't taken. When both day fields are restricted, a run must match both: `0 9 1-7 * 1` is 9:00 on the first Monday of each month, where plain cron would also run on the 1st to the 7th. `message` is the turn's text; without one, the turn just says the schedule fired. `next_run` on the trigger says when it fires next.

`tz="user"` reads the expression in the [timezone](https://www.noclick.com/docs/guide/users.md) of the user a user's agent belongs to, and follows them: when `user.update(timezone=...)` moves them, the next run is in their new zone, so a morning briefing follows its user when they travel (UTC while they have none; an account agent refuses it, having no user). Every turn is told the date and time too, so a `message` like "Summarize last month's invoices" means the month before the run ([Tell it the time](https://www.noclick.com/docs/guide/agents.md#tell-it-the-time)).

Each run is a conversation of its own, so a daily automation doesn't drag a growing history into every turn. What it should carry from one run to the next belongs in its [memory](https://www.noclick.com/docs/guide/memory.md). For a run that should read what the last one did (report only what changed since yesterday, say), make a [routine](https://www.noclick.com/docs/guide/agents.md#wake-it-up-later) instead: it wakes one conversation on the same kind of schedule. A schedule fires at most once a minute, its turn is your own words rather than something from outside, and it runs on NoClick's scheduler, the same one that runs schedules built on the canvas.

## Wake it from a queue

```python
invoices = noclick.Queue.from_name("invoices", create_if_missing=True)
support = noclick.Agent.from_name(
    "support-bot",
    create_if_missing=True,
    instructions="You chase unpaid invoices by email.",
    tools=["gmail.send_email", "stripe.list_invoices"],
    triggers=[noclick.OnQueue(invoices, message="Chase this unpaid invoice.")],
)
invoices.put({"invoice": "INV-1042", "customer": "acme"})
```

```ts
import { Agent, OnQueue, Queue } from "noclick";

const invoices = Queue.fromName("invoices", { createIfMissing: true });
const support = Agent.fromName("support-bot", {
  createIfMissing: true,
  instructions: "You chase unpaid invoices by email.",
  tools: ["gmail.send_email", "stripe.list_invoices"],
  triggers: [new OnQueue(invoices, { message: "Chase this unpaid invoice." })],
});
await invoices.put({ invoice: "INV-1042", customer: "acme" });
```

`OnQueue` makes each message on a [queue](https://www.noclick.com/docs/guide/queues.md) a turn: the agent reads `message`, then the message's JSON body. The queue is a `Queue` or its name, from the agent's own scope. With `batch_size` (up to 25), one turn takes up to that many waiting messages at once, as a JSON list. The agent takes one turn at a time, oldest messages first; when messages arrive faster than its turns finish, raise `batch_size`, or put several agents on the queue:

```python
enrich = noclick.Agent.from_name("enrich")
enrich.add_trigger(noclick.OnQueue("signups", batch_size=10, message="Research these companies and save what you find."))
```

```ts
import { Agent, OnQueue } from "noclick";

const enrich = Agent.fromName("enrich");
await enrich.addTrigger(new OnQueue("signups", { batchSize: 10, message: "Research these companies and save what you find." }));
```

The queue's delivery rules apply. A turn starts as soon as a message is put (a delayed one, or one handed back, within about half a minute of becoming visible). A turn that finishes acknowledges its messages; a turn that fails hands them back for another try after a pause that grows with each attempt (30 seconds per attempt so far), and a message that fails the queue's `max_attempts` times becomes a dead letter, with the turn's error as its `last_error`. Each turn is a conversation of its own unless `conversation` keys it (below). While the agent is paused, messages wait on the queue rather than being skipped, and the agent works through them after `resume`. The trigger reads the queue by its name in the agent's own scope, and the queue can't be deleted while the trigger is there.

Running out of money isn't a failure. When the agent's budget, its user's [spend cap](https://www.noclick.com/docs/guide/spend.md) or your account's funds run out, the trigger pauses: messages wait on the queue with their attempts unchanged, and the trigger's `status` is `error`, saying why. It looks again every half minute and carries on by itself once there's money again (the month turns, the cap goes up, funds arrive). An agent whose user's spending you've [paused](https://www.noclick.com/docs/guide/users.md#pause-a-user-s-spending) leaves its messages on the queue the same way, until you resume the user.

## Keep related deliveries together

A webhook or app-event trigger takes `conversation`, a template over what arrived: each `{...}` is a dotted path into the webhook's JSON body or the event as the app sent it. Every delivery lands in the agent's one session; the rendered key tags it, so the agent sees an issue's comments, an order's updates or a customer's messages as one thread, and a reply goes back to it:

```python
fulfilment = noclick.Agent.from_name("fulfilment")
fulfilment.add_trigger(noclick.OnWebhook(name="order-updates", conversation="order-{order.id}"))
```

```ts
import { Agent, OnWebhook } from "noclick";

const fulfilment = Agent.fromName("fulfilment");
await fulfilment.addTrigger(new OnWebhook("order-updates", { conversation: "order-{order.id}" }));
```

The key follows the same rules as one you choose yourself (1 to 128 letters, digits and `. _ : @ + -`, after rendering). A delivery that lacks a field the template names carries a key of its own, and a webhook's `NoClick-Conversation` header wins over the template (a header that isn't a valid key is refused with `400`). An agent takes one turn at a time, whichever thread each is from: a delivery that arrives while it works on a turn waits, `pending`, and starts within about half a minute of that turn ending, in the order they arrived. The turn's [operation](https://www.noclick.com/docs/guide/operations.md) records the key it ran in as `input["conversation"]`. A queue trigger keys each turn by its one message (the template is over its JSON body), so it can't take `conversation` with a `batch_size` above 1; a message that comes while the agent works on a turn waits a few seconds on the queue, its attempts unchanged.

## Email and calls

Mail and calls wake an agent from where they're set up: an inbox created with `agent=`, a number routed with `answer_with`. `triggers()` lists them too, as kinds `email` and `call`, so you can see everything that wakes an agent in one place. Change them on the inbox or the number, not here.

An `approval` trigger is listed while your [policy](https://www.noclick.com/docs/guide/policy.md) may hold one of the agent's tools for a person: a `require_approval` rule names one of them, with or without a condition. Its `spec["tools"]` names them as policy does (`stripe.create_refund`, `human.ask`). When the person answers, the agent takes a turn in the conversation the held call came from: with the call's result once it's approved and run, or with the decline and its note ([When a call waits for approval](https://www.noclick.com/docs/guide/agents.md#when-a-call-waits-for-approval)). You change it in your policy: `remove_trigger` on it raises `noclick.InvalidRequest`. An agent's `trigger_kinds` leaves it out, since your policy, not the agent, decides it.

## Keep triggers in your code

`from_name` sets `triggers=` every time it runs, like its instructions and tools. On first use, a trigger your code no longer lists is removed, and one it adds is created. A trigger that stays is left alone, so a webhook keeps its URL across deploys. Email and call triggers are never touched. `triggers=[]` removes every webhook and event trigger; leaving `triggers` out changes nothing. `Agent.create(triggers=...)` checks every definition before it makes anything, so a bad one leaves no agent behind.

## Add, change and remove triggers

For agents whose triggers your code doesn't pass to `from_name`, change triggers one at a time:

```python
support = noclick.Agent.from_name("support")
mentions = support.add_trigger(noclick.OnEvent("slack", "app_mention", message="Someone asked you something."))

support.remove_trigger(mentions)
support.remove_trigger(noclick.OnWebhook(name="orders"))   # or the definition you added
```

```ts
import { Agent, OnEvent, OnWebhook } from "noclick";

const support = Agent.fromName("support");
const mentions = await support.addTrigger(new OnEvent("slack", "app_mention", { message: "Someone asked you something." }));

await support.removeTrigger(mentions);
await support.removeTrigger(new OnWebhook("orders"));   // or the definition you added
```

Adding one the agent already has, defined the same way, adds nothing: you get that trigger back (HTTP 200, its `next_step` saying so), since a second would wake the agent twice for each delivery. On an agent made from NoClick's WhatsApp template, so does any other trigger on its number's messages.

`remove_trigger` takes an `AgentTrigger`, its id, or a definition matching one the agent has (`noclick.NotFound` if none does): an `OnWebhook` by its `name` alone, since an agent's webhook names are unique, and any other definition as you added it. A trigger added this way is removed the next time a definition without it runs, so don't mix the two on one agent.

To move a schedule, change it in place rather than adding another, which would leave the old time firing too:

```python
digest = noclick.Agent.from_name("digest")
[schedule] = [t for t in digest.triggers() if t.kind == "cron"]
digest.update_trigger(schedule, cron=noclick.Cron("30 7 * * 1-5", tz="Europe/London"))
digest.update_trigger(noclick.OnWebhook(name="orders"), message="A new order arrived.")
```

```ts
import { Agent, Cron, OnWebhook } from "noclick";

const digest = Agent.fromName("digest");
const schedule = (await digest.triggers()).find((t) => t.kind === "cron")!;
await digest.updateTrigger(schedule, { cron: new Cron("30 7 * * 1-5", { tz: "Europe/London" }) });
await digest.updateTrigger(new OnWebhook("orders"), { message: "A new order arrived." });
```

`update_trigger` finds the trigger as `remove_trigger` does and keeps its id, its history, and a webhook its URL. `cron` moves a schedule to its new time and `tz` at once (a paused one's when it resumes), `message` changes what any trigger's turn is told, and `conversation` a webhook's, event's or queue's template; `None` clears either. `filters` replaces an app event's or a NoClick event's filters, checked and registered as adding one is, and it hears by them from the next delivery. `mode` (`"mentions"` or `"all"`) changes a channel the agent sits in, for every agent in it, so your key needs `channels`. A webhook's name, an event's connection and event, and a queue stay: remove it and add another for that.

`rehearse_trigger` tries any trigger now as a [test run](https://www.noclick.com/docs/guide/agents.md), its tool calls answered by a simulated world so nothing is sent: pass `sample`, what a delivery would carry (a webhook's body, an event's data, a queue message's body, an email's `{"from", "subject", "text"}`, a channel post's text or `{"text", "from"}`), or leave it out for one of the trigger's own (a schedule's run, a NoClick event's sample from the event catalog). A call and an approval can't be tried this way.

## See what wakes an agent

```python
support = noclick.Agent.from_name("support")
for trigger in support.triggers():
    print(trigger.kind, trigger.status, trigger.url, trigger.last_fired_at, trigger.error)
```

```ts
import { Agent } from "noclick";

const support = Agent.fromName("support");
for (const trigger of await support.triggers()) {
  console.log(trigger.kind, trigger.status, trigger.url, trigger.lastFiredAt, trigger.error);
}
```

Each `AgentTrigger` has its `kind` (`cron`, `webhook`, `event`, `platform`, `queue`, `email`, `call`, `approval`, `app` for a step wired in the app, `channel` for a channel the agent sits in, or `routine` for a recurring wake-up), its `spec` (what it was defined with), and its `state`: `live`, `paused` (the agent, or the trigger itself: `paused` says which) or `stopped` (it can't fire), with `reason` saying why and `fix` what makes it live again (`resume_agent`, `resume`, `connect` its `connection`, `replace` a deleted connection, or `open_in_app`). A webhook has its `url`, a schedule and a routine their `next_run_at` (paused or not), and every trigger its `last_fired_at`, `running` while a turn it started is queued or running, who set it up in `set_by` (a `person`, an `agent`'s own turn, or an `automation` step), `read_only` when it's changed only where it lives, and the `actions` it takes here. `status` (`active`, `paused` or `error`) and `next_run` are the older readings of the same. Every turn a trigger starts is an [operation](https://www.noclick.com/docs/guide/operations.md) like any other, with the agent's `agent_id` and `input["trigger"]` naming the trigger. In the conversation, the message that turn read is a `user` message whose `trigger` says so, so a chat UI can tell it from one a person sent ([Read conversations](https://www.noclick.com/docs/guide/agents.md#read-conversations)).

`agent.trigger_kinds` names the kinds without a read, which is how a listing tells automations apart:

```python
automations = [agent for agent in noclick.Agent.list() if "cron" in agent.trigger_kinds]
```

```ts
import { Agent } from "noclick";

const automations = (await Agent.list()).filter((agent) => agent.triggerKinds.includes("cron"));
```

## Pause an agent

```python
digest = noclick.Agent.from_name("digest")
digest.pause()
print(digest.paused)   # True
digest.resume()
```

```ts
import { Agent } from "noclick";

const digest = Agent.fromName("digest");
await digest.pause();
console.log(digest.paused);   // true
await digest.resume();
```

While an agent is paused, nothing wakes it: scheduled runs are skipped (not made up later), webhook calls are refused with `409` so their sender can retry, and app events and mail that arrive meanwhile don't wake it (the mail is kept, with `agent_error` saying so). A call to its number hears that it can't take calls right now; a call under way goes on. Messages your code sends still run, and so do wake-ups and the jobs it was given. A trigger added while it's paused waits paused too. After `resume`, a schedule picks up at its next run. Pausing and resuming are the agent owner's: a user can't pause your account's agent.

A trigger whose turns keep failing the same way, five in a row over at least 30 minutes, stops firing on its own: its `status` becomes `error` with the failure, its webhook answers `409`, its schedule stops, and the `schedule.paused` event goes to your [webhooks](https://www.noclick.com/docs/guide/webhooks.md). Fix the cause, then `resume_trigger` it, or `resume()` the agent, which starts every stopped trigger again. A turn that fails because your account can't pay, or because a spend cap was reached, never counts toward this.

To stop one trigger and keep the agent running, pause the trigger alone:

```python
support = noclick.Agent.from_name("support")
support.pause_trigger(noclick.OnWebhook(name="orders"))
support.resume_trigger(noclick.OnWebhook(name="orders"))
```

```ts
import { Agent, OnWebhook } from "noclick";

const support = Agent.fromName("support");
await support.pauseTrigger(new OnWebhook("orders"));
await support.resumeTrigger(new OnWebhook("orders"));
```

A paused schedule is skipped (its `next_run_at` still reads), a paused webhook answers its caller `200` and drops the call, app and NoClick events that reach it are dropped, and a queue's messages wait on the queue. Pausing and resuming the agent leaves it paused; `resume_trigger` starts it again, unless the agent itself is paused.

## Limits and billing

- An agent has up to 20 schedules, webhook and app-event triggers (email and call triggers don't count).
- Triggers are free. Each turn one starts is billed like any other turn, to the user the agent belongs to, and counts toward its [budget](https://www.noclick.com/docs/guide/sub-agents.md) and your [spend caps](https://www.noclick.com/docs/guide/spend.md). A delivery your account can't pay for comes back `failed` with the reason, and starts no turn.
- A webhook body is at most 256 KB.

## Errors

| Error | When |
| --- | --- |
| `noclick.InvalidRequest` | An event the integration doesn't have (the error lists its `events`), a filter it doesn't take or a required one left out, a webhook name that isn't 1 to 64 letters, digits and `. _ -`, a `conversation` template that doesn't parse, a cron expression without five fields NoClick reads, a `tz` that isn't an IANA timezone, `tz="user"` on an account agent, or a `batch_size` above 25. |
| `ValueError` | Before anything is sent: an `OnQueue` with `conversation` and a `batch_size` above 1, or a `batch_size` that isn't a whole number of 1 or more. |
| `noclick.NotFound` | `OnEvent` names a connection, or `OnQueue` a queue, the agent's own scope doesn't have, or `remove_trigger` or `update_trigger` matches nothing. |
| `noclick.Conflict` | The agent already has a webhook trigger by that name. |
| `noclick.QuotaExceeded` | The agent already has 20 triggers. |
| `noclick.PermissionDenied` | Inside `as_user`, reading, changing, pausing or resuming your account's agent's triggers. |
| `noclick.Expired` | Pausing or resuming an agent whose `ttl_s` ran out. |

Every method is in the reference: [`Agent.triggers`](https://www.noclick.com/docs/reference/python/Agent.md#Agent.triggers), [`Agent.add_trigger`](https://www.noclick.com/docs/reference/python/Agent.md#Agent.add_trigger), [`Agent.update_trigger`](https://www.noclick.com/docs/reference/python/Agent.md#Agent.update_trigger), [`Agent.remove_trigger`](https://www.noclick.com/docs/reference/python/Agent.md#Agent.remove_trigger), [`Agent.pause_trigger`](https://www.noclick.com/docs/reference/python/Agent.md#Agent.pause_trigger), [`Agent.resume_trigger`](https://www.noclick.com/docs/reference/python/Agent.md#Agent.resume_trigger), [`Agent.rehearse_trigger`](https://www.noclick.com/docs/reference/python/Agent.md#Agent.rehearse_trigger), [`Connection.events`](https://www.noclick.com/docs/reference/python/Connection.md#Connection.events) and the [`IntegrationEvent`](https://www.noclick.com/docs/reference/python/Connection.md#IntegrationEvent) records it returns, [`Agent.pause`](https://www.noclick.com/docs/reference/python/Agent.md#Agent.pause), [`Agent.resume`](https://www.noclick.com/docs/reference/python/Agent.md#Agent.resume), and the definitions [`OnWebhook`](https://www.noclick.com/docs/reference/python/Triggers.md#OnWebhook), [`OnEvent`](https://www.noclick.com/docs/reference/python/Triggers.md#OnEvent), [`OnPlatformEvent`](https://www.noclick.com/docs/reference/python/Triggers.md#OnPlatformEvent), [`Cron`](https://www.noclick.com/docs/reference/python/Triggers.md#Cron), [`OnQueue`](https://www.noclick.com/docs/reference/python/Triggers.md#OnQueue) and [`AgentTrigger`](https://www.noclick.com/docs/reference/python/Triggers.md#AgentTrigger).
