Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.copass.com/llms.txt

Use this file to discover all available pages before exploring further.

A trigger binds an agent to events from a data source. When the data source emits a matching event (a Slack mention, a GitHub issue opened, a Linear status change), the agent runs against that event payload. Triggers are how your agents stop being request/response endpoints and start being autonomous reactors.

​
What you can do

  • Attach an agent to any data source in the same sandbox.
  • Filter by event type (e.g. message.created) or by a custom filter config (e.g. only mentions of a specific user).
  • Rate-limit per hour to contain runaway fire rates.
  • Pause and resume reversibly; destroy permanently.
  • Inspect fire counts and last-fire timestamps.
“Wire the support agent to fire on Slack mentions of @on-call.” “What triggers does the triage agent have? Are any quiet?” “Pause the GitHub-issues trigger overnight; resume at 9am.” “Set a rate limit of 60/hour on this trigger while I test.”

​
Via the CLI

# CRUD
copass agent trigger list <slug>
copass agent trigger show <slug> <trigger_id>
copass agent trigger create <slug> \
  --data-source-id <source_id> \
  --event-type-filter "message.created" \
  --rate-limit-per-hour 60
copass agent trigger update <slug> <trigger_id> --rate-limit-per-hour 120
copass agent trigger destroy <slug> <trigger_id>     # permanent

​
Via the SDK

const trigger = await client.agents.triggers.create(sandboxId, 'support', {
  data_source_id,
  event_type_filter: 'message.created',
  filter_config: { mentions: ['U0123456'] },
  rate_limit_per_hour: 60,
});

await client.agents.triggers.pause(sandboxId, 'support', trigger.trigger_id);
await client.agents.triggers.resume(sandboxId, 'support', trigger.trigger_id);

​
Anatomy of a trigger

FieldPurpose
agent_idWhich agent this trigger fires.
data_source_idWhich source emits the events.
event_type_filter"*" (all events) or a specific type (message.created, issue.opened, …).
filter_configOptional structured filter (channel, label, sender, etc.). Source-specific.
rate_limit_per_hourCap fires per hour. null = no cap.
statusactive / paused. Pausing is reversible; destroying is permanent.
fire_count, last_fired_atServer-maintained, useful for diagnostics.

​
Pause vs destroy

  • Pause — flips status to paused. Reversible via resume. Use for cost containment, debugging, or seasonal quiet periods.
  • Destroy — permanent. CLI-only by deliberate policy; the Concierge surfaces the copass agent trigger destroy command rather than running it.

​
Common patterns

Start with a low rate limit

Set rate-limit-per-hour 60 while the agent is new. Watch a few runs, tune the prompt, then raise the cap.

One agent, multiple triggers

Same agent can react to Slack mentions and GitHub issues. Each trigger has its own filter and rate limit.

Test before binding

Use agent test with a synthetic payload to validate the prompt before attaching a live trigger. See Runs.

Pause without losing history

Pausing keeps the run history and the trigger config — flip it back on whenever. No need to recreate.

​
Next steps

  • Build an agent — create the agent before wiring triggers.
  • Runs — see what happens when triggers fire.
  • Data Sources — where the events come from.
  • Tools — what the agent has at its disposal once a trigger fires.