Agent triggers

An Agent Trigger starts sessions automatically. Every deployment serves the trigger API at /v1/triggers. A self-hosted deployment supports cron schedules. StreamNative Cloud extends the same route with Pulsar and Kafka sources, additional session modes, and multiple replicas.

Triggers replace the deprecated Agent Function workflow for running an agent continuously or on a schedule. You declare the automation over an agent resource; the runtime creates ordinary sessions when the source fires.

Get your registry endpoint

How triggers create sessions

Every trigger pins an agent version when you create it. If you omit agent.version, the registry resolves and stores the agent's current version at create time. Updating the agent later does not move an existing trigger to a newer version.

The session_mode field controls how source events map to sessions:

For cron triggers, the source payload becomes the initial user.message in each new session. The session block supplies the environment, vaults, metadata, and title template inherited by the sessions the trigger creates.

Trigger configuration fields

Trigger responses also contain these server-managed fields:

Source configuration

source.type selects the source and its valid fields:

Create a cron trigger

The example below works on both self-hosted and StreamNative Cloud deployments. $AGENT_ID / agent.id comes from creating an agent, and $ENVIRONMENT_ID / environment.id comes from creating an environment.

trigger=$(ork agent triggers create \
  --name "nightly-backlog-review" \
  --agent "$AGENT_ID" \
  --source-type cron \
  --session-mode SESSION_PER_EVENT \
  --schedule "0 2 * * *" \
  --timezone Etc/UTC \
  --payload "Review unresolved tickets and summarize themes." \
  --environment-id "$ENVIRONMENT_ID" \
  -o json)

TRIGGER_ID=$(jq -r '.id' <<< "$trigger")

A successful create returns 200 OK and the complete Trigger resource:

{
  "id": "trg_01H8...",
  "type": "trigger",
  "name": "nightly-backlog-review",
  "agent": { "type": "agent", "id": "agt_01H8...", "version": 1 },
  "session_mode": "SESSION_PER_EVENT",
  "source": {
    "type": "cron",
    "schedule": "0 2 * * *",
    "timezone": "Etc/UTC",
    "payload": "Review unresolved tickets and summarize themes."
  },
  "session": {
    "environment_id": "env_01H8...",
    "title_template": null,
    "metadata": {},
    "vault_ids": []
  },
  "replicas": 1,
  "status": "active",
  "next_fire_at": "2026-08-27T02:00:00.000Z",
  "last_fired_at": null,
  "error": null,
  "archived_at": null,
  "created_at": "2026-08-26T02:00:00.000Z",
  "updated_at": "2026-08-26T02:00:00.000Z"
}

Pass --paused in the CLI or paused: true in the request to create the configuration without scheduling future events.

Create a messaging trigger on StreamNative Cloud

StreamNative Cloud accepts Pulsar and Kafka sources on the same /v1/triggers route. A messaging source requires a connection and exactly one of topics or topic_pattern.

ork agent triggers create \
  --name "support-triage-inbound" \
  --agent "$AGENT_ID" \
  --source-type pulsar \
  --session-mode SESSION_PER_TOPIC \
  --connection inbound-pulsar \
  --topic persistent://public/operations/support-requests \
  --subscription-name support-triage \
  --schema-type json \
  --environment-id "$ENVIRONMENT_ID" \
  -o json

For Kafka, set source.type to kafka. You can also pass consumer_additional_config and input_schema_configs.

Manage triggers

List and retrieve

ork agent triggers list --agent "$AGENT_ID" -o json
ork agent triggers get "$TRIGGER_ID" -o json

Update a trigger

Updates use a partial POST. Send only the mutable fields you want to change; omitted fields keep their stored values. The pinned agent and create-only paused field cannot be updated.

ork agent triggers update "$TRIGGER_ID" \
  --source-type cron \
  --schedule "30 2 * * *" \
  -o json

When updating source fields with the CLI, include --source-type so the command can build the correct source variant.

Pause and unpause

Pause prevents future events from creating sessions. It does not stop sessions that already exist. Unpause resumes from the first future cron slot or new source event; it does not replay the paused interval.

ork agent triggers pause "$TRIGGER_ID"
ork agent triggers unpause "$TRIGGER_ID"

List sessions created by a trigger

ork agent triggers sessions "$TRIGGER_ID" --limit 100 -o json

These are ordinary sessions. Retrieve them, stream events, and inspect resources through the standard Sessions API.

Delete a trigger

ork agent triggers delete "$TRIGGER_ID"

The open-source engine archives the trigger record and returns { "id": "...", "type": "trigger_deleted" }. Existing sessions remain available.

Permissions

See Control registry access for how to separate access with Workspaces.

What's next