Agent Triggers

Triggers define when an agent runs and what input it receives. Each trigger is attached to an agent and determines the execution context — including input data, metadata, and optional scheduling.

An agent can have multiple triggers, each with its own type, configuration, and schedule.

Trigger Types

Seclai supports these trigger types, each suited to different use cases:

Trigger Type	Input Source	Runs When	Best For
Dynamic Input	Provided at runtime	On-demand (API call or UI)	Chat bots, interactive tools, API integrations
Template Input	Pre-defined template	On-demand or on schedule	Recurring reports, periodic tasks
Content Added	From new content	Automatically when content is added	Document processing, RSS monitoring
Content Updated	From updated content	Automatically when content changes	Change tracking, update alerts
Content Added or Updated	From new or changed content	Automatically on any content change	Comprehensive monitoring pipelines
Email Received	From an inbound email	Automatically when email arrives	Email-to-agent inboxes, forwarding workflows
Cloud File Added	The changed file	A file is added to a connected drive	Auto-processing new uploads (Dropbox, ...)
Cloud File Updated	The changed file	A file changes on a connected drive	Reprocessing edited documents
Cloud File Added or Updated	The changed file	A file is added or changed on a drive	Comprehensive file-change automation

Dynamic Input

The dynamic_input trigger runs an agent on demand with input provided at execution time. This is the most flexible trigger type — the caller supplies the input text and optional metadata with each run.

How It Works

A user or application sends a request to run the agent
The request includes the input text and optional metadata
The agent processes the input through its steps
Results are returned to the caller

Configuration Fields

Field	Type	Required	Description
`name`	string	No	A label for this trigger
`allow_empty_input`	boolean	No	Whether to allow runs with empty input (default: `false`)
`default_input`	string	No	Default input text used when no input is provided
`metadata`	object	No	Default metadata key-value pairs

Use Cases & Examples

Building a Chat Bot

The most common use of dynamic input triggers is building conversational interfaces. Your application sends user messages as input and receives agent responses.

Agent setup:

Trigger type: dynamic_input
Steps: Retrieval → Prompt Call → Display Result

API call from your app:

curl -X POST https://api.seclai.com/agents/{agent_id}/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What is the return policy for electronics?",
    "metadata": {
      "user_id": "customer-456",
      "session_id": "chat-session-789",
      "channel": "web"
    }
  }'

The agent receives the user's question as {{agent.input}}, searches the knowledge base for relevant documents, and generates a contextual response.

Figure 1.Dynamic input trigger — the user provides input via API or UI, the agent scans it, retrieves context, generates a response, and delivers the result.

Using metadata in steps:

In the prompt call step, you can personalize the system prompt:

You are a helpful customer support assistant for {{organization.name}}.
The customer is contacting us via the {{metadata.channel}} channel.

Answer the following question using only the provided context:

Context: {{step.retrieval.output}}

Question: {{agent.input}}

Running an Agent from Your Application

Dynamic input triggers let any application invoke agents as an API. For example, a content management system could run an agent to analyze new articles:

curl -X POST https://api.seclai.com/agents/{agent_id}/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "<article><title>New Product Launch</title><body>We are excited to announce...</body></article>",
    "metadata": {
      "content_type": "application/xml",
      "article_id": "art-2025-001",
      "author": "marketing-team",
      "category": "product-news"
    }
  }'

How metadata flows through steps:

The metadata is available to every step in the agent via {{metadata.field_name}}:

Gate step: Check {{metadata.category}} to route processing
Prompt call: Include {{metadata.author}} in the system prompt for context
Webhook step: Forward {{metadata.article_id}} to an external system
S3 step: Use {{metadata.category}}/{{metadata.article_id}}.json as the object key

Form Processing

Process form submissions by passing form data as JSON input:

curl -X POST https://api.seclai.com/agents/{agent_id}/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "{\"name\": \"Jane\", \"question\": \"How do I upgrade?\", \"plan\": \"starter\"}",
    "metadata": {
      "content_type": "application/json",
      "form_type": "support-request",
      "priority": "normal"
    }
  }'

The agent can extract JSON fields, look up relevant help articles, generate a response, and send it via email — all in one workflow.

Template Input

The template_input trigger generates the agent's input from a pre-defined template string. Templates can include substitution variables that are resolved at runtime.

This trigger type is ideal for recurring tasks where the input structure is known in advance but values change each run (e.g., today's date, metadata values).

Configuration Fields

Field	Type	Required	Description
`name`	string	No	A label for this trigger
`input`	string	Yes	The template string with `{{placeholder}}` substitutions
`input_content_type`	string	No	MIME type for the rendered input (see below)
`allow_empty_input`	boolean	No	Whether to allow runs with empty rendered input (default: `false`)
`metadata`	object	No	Default metadata key-value pairs available as `{{metadata.*}}`

Input Content Type

The input_content_type field tells Seclai how to interpret and store the rendered trigger input. Supported values:

text/plain
text/html
application/json
application/xml

You can also provide a templated value so the content type is determined dynamically:

{{metadata.content_type}}

Validation:

At save-time, template expressions are accepted as strings
At run-time, the resolved value must be one of the supported content types above

Examples

Daily summary report:

Generate a summary report for {{date America/New_York}}.
Focus on key metrics and notable events from the past 24 hours.

Weekly newsletter with metadata:

Template:

Create a {{metadata.format}} newsletter for the week of {{date UTC}}.
Topic: {{metadata.topic}}
Audience: {{metadata.audience}}
Tone: {{metadata.tone}}

Metadata:

{
  "format": "HTML",
  "topic": "AI Industry News",
  "audience": "Technical Leaders",
  "tone": "professional"
}

Figure 2.Template input trigger with schedule — a daily schedule resolves the template, the agent summarizes a feed and delivers the newsletter via email.

Schedules

Template input triggers can run on automated schedules. You can attach one or more schedules to a trigger, and each schedule defines a recurring pattern.

Schedule Frequencies

Frequency	Required Fields	Description
Hourly	`minute_of_hour`	Runs every N hours at the specified minute
Daily	`hour_of_day`, `minute_of_hour`	Runs every N days at the specified time
Weekly	`day_of_week`, `hour_of_day`, `minute_of_hour`	Runs every N weeks on the specified day and time
Monthly	`day_of_month` or `weekday_of_month`, `hour_of_day`, `minute_of_hour`	Runs every N months on the specified day and time

Schedule Fields

Field	Type	Range	Description
`frequency`	enum	—	`hourly`, `daily`, `weekly`, or `monthly`
`repeat_interval`	integer	≥ 1	How often the schedule repeats (e.g., every 2 hours, every 3 days)
`minute_of_hour`	integer	0–59	The minute within the hour to run
`hour_of_day`	integer	0–23	The hour within the day to run (24-hour format)
`day_of_week`	integer	0–6	Day of the week (0 = Monday, 6 = Sunday)
`day_of_month`	integer	1–31 or -1 to -31	Day of the month. Negative values count from the end (e.g., -1 = last day)
`weekday_of_month`	integer	0–35	Specific weekday occurrence within a month (e.g., 0 = first Monday, 7 = second Monday)

Schedule Examples

Every hour at minute 30:

{
  "frequency": "hourly",
  "repeat_interval": 1,
  "minute_of_hour": 30
}

Every day at 9:00 AM:

{
  "frequency": "daily",
  "repeat_interval": 1,
  "hour_of_day": 9,
  "minute_of_hour": 0
}

Every Monday at 8:00 AM:

{
  "frequency": "weekly",
  "repeat_interval": 1,
  "day_of_week": 0,
  "hour_of_day": 8,
  "minute_of_hour": 0
}

Every 2 weeks on Friday at 5:00 PM:

{
  "frequency": "weekly",
  "repeat_interval": 2,
  "day_of_week": 4,
  "hour_of_day": 17,
  "minute_of_hour": 0
}

First day of every month at midnight:

{
  "frequency": "monthly",
  "repeat_interval": 1,
  "day_of_month": 1,
  "hour_of_day": 0,
  "minute_of_hour": 0
}

Last day of every month at 6:00 PM:

{
  "frequency": "monthly",
  "repeat_interval": 1,
  "day_of_month": -1,
  "hour_of_day": 18,
  "minute_of_hour": 0
}

First Monday of every quarter (every 3 months):

{
  "frequency": "monthly",
  "repeat_interval": 3,
  "weekday_of_month": 0,
  "hour_of_day": 9,
  "minute_of_hour": 0
}

Multiple Schedules

A single trigger can have multiple schedules. For example, to run both on weekday mornings and Sunday evenings:

Schedule 1: Weekly, Monday at 8:00 AM (day_of_week: 0)
Schedule 2: Weekly, Tuesday at 8:00 AM (day_of_week: 1)
Schedule 3: Weekly, Wednesday at 8:00 AM (day_of_week: 2)
Schedule 4: Weekly, Thursday at 8:00 AM (day_of_week: 3)
Schedule 5: Weekly, Friday at 8:00 AM (day_of_week: 4)
Schedule 6: Weekly, Sunday at 6:00 PM (day_of_week: 6)

Seclai automatically detects redundant schedules (ones that would never produce new runs compared to existing schedules) and intersecting schedules (ones that would fire at the same time), warning you before saving.

Content Added

The content_added trigger runs the agent automatically whenever new content is added to a connected knowledge base.

How It Works

A content source fetches new content (e.g., a new RSS article, a new web page)
The content is indexed into the knowledge base
All content_added triggers linked to that knowledge base fire
The new content's text becomes the agent's input
Content metadata (title, author, URL, publish date, etc.) is available via {{metadata.*}}

Configuration Fields

Field	Type	Required	Description
`name`	string	No	A label for this trigger
`knowledge_base_id`	UUID	Yes	The knowledge base to monitor for new content
`metadata`	object	No	Additional default metadata merged with content metadata

Examples

RSS feed summarizer:

When a new article arrives in a knowledge base fed by RSS sources, automatically summarize it and send a notification:

Trigger: content_added on the "Industry News" knowledge base
Step 1: Prompt Call — Summarize {{agent.input}} using the article metadata
Step 2: Send Email — Email the summary to the team

The content metadata from the source is automatically available:

Summarize this article:

Title: {{metadata.title}}
Author: {{metadata.author}}
Published: {{metadata.published_date}}
Source: {{metadata.source_url}}

Content:
{{agent.input}}

New document classifier:

Automatically tag and categorize new documents:

Trigger: content_added on a document knowledge base
Step 1: Prompt Call — Classify the document and output JSON
Step 2: Extract JSON — Parse the classification result
Step 3: Webhook Call — Send classification to your CMS

Figure 3.Content-triggered automation — a content source event automatically fires the agent, which analyzes the new content and notifies the team via email.

Content Updated

The content_updated trigger runs the agent automatically whenever existing content in a connected knowledge base is updated (e.g., a web page's content changes, an RSS article is revised).

How It Works

A content source detects that previously indexed content has changed
The updated content is re-indexed in the knowledge base
All content_updated triggers linked to that knowledge base fire
The updated content becomes the agent's input
Content metadata is available via {{metadata.*}}

Configuration Fields

Field	Type	Required	Description
`name`	string	No	A label for this trigger
`knowledge_base_id`	UUID	Yes	The knowledge base to monitor for content changes
`metadata`	object	No	Additional default metadata merged with content metadata

Examples

Change tracking:

Detect and report significant changes to monitored web pages:

Trigger: content_updated on a competitor monitoring knowledge base
Step 1: Prompt Call — Analyze what changed and assess significance
Step 2: Gate — Only continue if changes are significant
Step 3: Send Email — Notify the team about the changes

Figure 4.Change tracking — content updates trigger an analysis, a gate filters for significance, and important changes are emailed to the team.

Compliance monitoring:

Re-analyze documents when they change for regulatory compliance:

Trigger: content_updated on a policy document knowledge base
Step 1: Prompt Call — Check updated content against compliance rules
Step 2: Extract JSON — Parse compliance check results
Step 3: Webhook Call — Update compliance dashboard

Figure 5.Compliance monitoring — updated documents are checked against compliance rules, results are extracted as JSON, and the dashboard is updated via webhook.

Content Added or Updated

The content_added_or_updated trigger combines both behaviors — it fires whenever content is added to or updated in a connected knowledge base. This is the most common content trigger type when you want to process all content changes uniformly.

Configuration Fields

Field	Type	Required	Description
`name`	string	No	A label for this trigger
`knowledge_base_id`	UUID	Yes	The knowledge base to monitor
`metadata`	object	No	Additional default metadata merged with content metadata

Example

Content processing pipeline:

Process all content changes through a standardized pipeline:

Trigger: content_added_or_updated on a documentation knowledge base
Step 1: Prompt Call — Extract key topics and generate a summary
Step 2: Extract JSON — Parse structured output
Step 3: Write AWS S3 Object — Store the processed result
Step 4: Webhook Call — Notify the search index to update

Figure 6.Content processing pipeline — all content changes flow through extraction, storage, and webhook notification in a linear pipeline.

Email Received

The email_received trigger turns an agent into a virtual email inbox. The agent runs whenever email arrives at its address — the message body becomes the agent's input and any attachments become agent input attachments.

Account‑level email settings — branded sender identity, custom and vanity domains, DMARC monitoring, recipient opt‑outs, the blocked‑senders list, and the per‑plan rate limits — are documented on the Email page. This section covers the per‑agent trigger behavior.

Inbox Addresses

Every email trigger has a built-in address derived from the agent's ID (a short, base32-encoded form):

<agent-id>@agent.seclai.com

You can also set a friendly alias, which adds a second address scoped to your account:

<alias>.<account-id>@agent.seclai.com

An alias may contain letters, digits, +, ., and -, must be 1–32 characters, and must not start or end with +, ., or -. Both addresses route to the same agent; you can see and copy them from the trigger's configuration. (For convenience, the long unencoded UUID form of the address — with or without dashes — also routes to the agent, so any address you've already shared keeps working.)

Branded Domains

On the Team and Pro plans you can send and receive agent email from your own branded domain instead of the shared agent.seclai.com — a vanity subdomain (<name>.seclai.com, no domain of your own required; Team and Pro) or a custom domain you own (agent.mycompany.com; Pro). You configure, verify, and monitor these under Settings → Email → Domains. The full walkthrough — the exact DNS records for each option, ownership verification, DMARC monitoring, choosing a primary domain, and safe removal — lives on the Email page.

Once a domain is verified and set as your primary domain, agent addresses become clean — <agent-id>@yourdomain and <alias>@yourdomain (no account suffix needed, since the domain is dedicated to your account) — and agent replies are sent from that domain. A new alias you set is placed on your primary domain; existing aliases keep their address, and if you remove a domain its aliases fall back to the shared agent.seclai.com form. Vanity and custom domains cover both receiving and sending. See Email → Sending domains for the details.

How It Works

Someone sends an email to one of the agent's addresses
The message is received, authenticated (SPF/DMARC), and screened for spam/viruses
The body becomes the agent's input; attachments become input attachments. If the email has no body or usable attachments, the subject line is used as the input instead
The sender, subject, and received time are captured as run metadata
The agent processes the email through its steps

Use Cases & Examples

Email-to-Agent Support Inbox

Turn an agent into a self-serve support inbox. Mail sent to the agent's address is authenticated and screened, scanned, answered against a knowledge base, and a reply is sent straight back to the sender.

Agent setup:

Trigger type: email_received (optionally with an allowed_senders allowlist)
Steps: Retrieval → Prompt Call → Send Email (to {{metadata.email_from}})

Figure 7.Email Received trigger — an inbound message is authenticated and screened, scanned, answered from the knowledge base, and a reply is emailed back to the sender.

The reply step targets the sender via the captured {{metadata.email_from}} field, and the system prompt can use {{metadata.email_subject}} for context:

You are a support assistant. A customer emailed with the subject
"{{metadata.email_subject}}".

Answer their message using only the provided context:

Context: {{step.retrieval.output}}

Message: {{agent.input}}

Triage & Forwarding

Use an inbox to classify incoming mail and route it onward — for example, extracting the request type and priority, then opening a ticket in an external system via a webhook.

Agent setup:

Trigger type: email_received
Steps: Extract Data (classify) → Gate (route by priority) → Webhook Call (create ticket)

Figure 8.Triage workflow — an inbound email is screened, its request type and priority extracted, then routed through a gate to a webhook that opens a ticket.

Replying to the Sender

An agent can email a response back to the person who wrote in. Add a Send Email step and turn on Reply to original sender (reply_to_sender) — the recipient is resolved at run time from the message's authenticated sender, so you never set an address yourself. For safety this only sends when the inbound message passed SPF or DMARC (a spoofed sender gets no reply), and it only works on email_received agents. A good subject is Re: {{metadata.email_subject}}. Replies are threaded (with a Reply-To back to the agent's inbox), so when the sender replies it returns to the agent and can continue the conversation.

Agent emails are sent from a noreply@agent.seclai.com address (or, for a reply, the agent's own inbox address) rather than a Seclai address, so the From aligns with the agent and replies route back to it.

If you instead send a notification to a registered user (a normal recipient_user_id send, not a reply) but still want their reply to come back to the agent, turn on Reply to agent inbox (reply_to_agent_inbox) on the Send Email step. It sets Reply-To to the agent's inbox and only takes effect when the agent has an email_received trigger — useful for a sustained conversation that starts from a notification.

Multi-Turn Conversations (Trusted Memory)

For a back-and-forth email assistant, do not rely on the quoted reply chain in the incoming email body — it's written by the sender and can be forged or trimmed. Instead, keep the conversation in a memory bank keyed by the authenticated sender ({{metadata.email_from}}): load that sender's history, answer in context, append the new turn, and reply. Because the sender is authenticated (keep Require sender authentication on), the per-sender history is trustworthy server-side state.

Figure 9.Multi-turn email conversation — history is loaded and stored against the authenticated sender (not the email's quoted reply chain), and the answer is emailed back to them.

Configuration Fields

Field	Type	Required	Description
`alias`	string	No	Friendly local part for the `<alias>.<account-id>@` address. Leave empty to use only the agent-ID address.
`allowed_senders`	string[]	No	Allowlist of sender addresses and/or bare domains. Leave empty to accept mail from any sender.
`ignore_auto_generated`	boolean	No	When true (the default), automated mail — auto-replies, vacation responders, bulk/mailing-list mail, and bounces — is dropped so the agent can't ping-pong with an auto-responder. Turn it off for agents that should process automated mail (alerts, reports, newsletters).
`require_sender_auth`	boolean	No	When true (the default), the sender must pass SPF or DMARC even on an open inbox (no allowlist), so the address can't be flooded with spoofed mail. Turn it off only to accept mail from senders that can't be authenticated.
`queue_on_quota`	boolean	No	When true, an email that exceeds your plan's hourly inbound-email rate limit is queued (shown as a Queued run) instead of failed, and runs automatically as capacity frees over the following minutes. When false (the default), over-limit mail fails immediately. Queuing never bypasses the limit — it just catches up in order. (A message with insufficient account credits still fails immediately, since queuing wouldn't help.)

The Send Email step also gains reply_to_sender and reply_to_agent_inbox options for email_received agents (see Replying to the Sender).

Captured Metadata

Each run records the email context as metadata, available to steps via {{metadata.field}}:

Metadata Key	Description
`email_from`	The sender address (authenticated envelope sender)
`email_to`	The address the email was sent to
`email_subject`	The subject line
`email_cc`	Carbon-copied recipients (when present)
`email_reply_to`	Reply-To address (when present)
`email_date`	The sender's claimed send time (Date header)
`email_in_reply_to`	Message-ID this email replies to, for threading
`email_received_at`	When the email was received
`email_message_id`	The message ID (used for de-duping)
`email_auto_generated`	`true`/`false` — whether the message is automated
`email_spf`	SES SPF check result (when known)
`email_dkim`	SES DKIM check result (when known)
`email_dmarc`	SES DMARC check result (when known)

Header-derived fields (email_cc, email_reply_to, email_date, email_in_reply_to, email_message_id) are informational and not authenticated — only email_from is verified by SPF/DMARC. In particular, never reply to email_reply_to; a reply-to-sender step always uses the authenticated email_from.

Security & Limits

Sender allowlist: Optional, but recommended. Each entry is either a full email address (e.g. alice@example.com) or a bare domain (e.g. example.com, which also matches sub-domains like mail.example.com). Wildcard syntax (*@…) is not used — a bare domain already covers every address at that domain. When an allowlist is set, Seclai additionally requires the email to pass SPF or DMARC, so a spoofed sender cannot match it. (A DKIM signature alone is not enough — it can authenticate a domain different from the one being matched.)
Automated mail (loop prevention): By default, machine-generated mail — auto-replies / vacation responders, mailing-list and bulk mail, and bounces — is dropped before a run, so an auto-responder on the other end can't ping-pong with your agent. Turn off Ignore automated email on the trigger only if the agent is meant to process automated mail (alerts, reports, newsletters).
Sender authentication on open inboxes: By default, even an open inbox (no allowlist) requires the sender to pass SPF or DMARC, so the guessable agent address can't be flooded with spoofed mail. Turn off Require sender authentication on the trigger only to accept mail from senders that can't be authenticated — with it off, anyone can spoof any sender address to the inbox.
Open addresses can be abused: Leaving the allowlist empty accepts mail from any (authenticated) sender — this is your choice, but anyone who learns the address can trigger runs (consuming credits) and flood it up to the hourly rate limit. Set an allowlist if the address might become known publicly.
Spam & viruses: Messages that fail the SES spam check are discarded. Messages that fail the virus check — or that SES could not virus-scan (e.g. very large attachments) — are also discarded, so an agent never runs on unscanned content.
Rate limits: Inbound email triggers are rate-limited per plan (the hourly quota per plan), plus a hard per-trigger ceiling. Mail that exceeds the limit, or is sent to an open agent with insufficient credits, surfaces as a failed agent run so you can see it — unless you enable Queue over-limit email (queue_on_quota), in which case over-limit mail is queued and caught up automatically as capacity frees (see the field above).
Sustained overload: If inbound mail keeps arriving faster than your plan can process it and the queued backlog grows beyond what can realistically catch up, Seclai sends a mandatory inbound email overload alert to the account owner and automatically pauses the worst-affected agent (and auto-blocks a single flooding sender). This safeguard is covered in full on the Email → Alerts page — re-enable a paused agent from its page once the volume subsides or your plan is upgraded.
Blocked senders: A sender on your account's blocked-senders list is turned away before a run, shown as a Blocked sender rejection.
Rejections: Mail discarded before a run (unknown alias, unauthorized sender, spam, flood, automated mail, blocked sender) appears in the agent's Traces tab as a trace with a Rejected status — open it to see why the email didn't run, or filter the Traces status to Rejected to see only these. The same records are also available via the API (GET /api/agents/inbound-email-rejections) and the list_inbound_email_rejections MCP tool. To be proactively notified when a sender is turned away by your allowlist (so you can add a legitimate correspondent you forgot), enable the Inbound Email Turned Away alert on the agent's Alerts tab.
Attachments: Attachments must satisfy the agent's declared attachment references, the same as the interactive run path. An email with more than 25 attachments surfaces as a failed agent run.

Blocking senders

Your account keeps a blocked-senders list (Settings → Email → Blocked senders) that applies to every EMAIL_RECEIVED agent on the account. Mail from a blocked sender is quietly rejected before any agent runs — no run, no credits, no notification — and appears only as a Blocked sender rejection in the agent's Traces. You can block a single address or a whole domain, manually or automatically (via governance policies or the overload safeguard). Only SPF/DMARC-authenticated senders are matched, since an unauthenticated From is forgeable.

The full reference — match types, manual vs. automatic blocking, one-click blocking from a rejection, and owner/admin gating — is on the Email → Blocked senders page.

Testing

Use Simulate Email on the trigger to test the agent without sending real mail — fill in From, Subject, body, metadata, and attachments, and it runs the agent exactly as an inbound email would (the simulation bypasses the sender allowlist and spam checks, since you're the authenticated owner). Exporting an agent carries its sender allowlist over; the custom alias is not exported (it's account-scoped, and the imported agent gets a new default address).

Trigger Metadata

All trigger types support metadata — a set of key-value pairs that are available to every step in the agent via {{metadata.field_name}} substitutions.

Where Metadata Comes From

Trigger Type	Metadata Sources
`dynamic_input`	Provided in the API request body + default metadata from trigger config
`template_input`	Defined in the trigger configuration
`content_added` / `content_updated` / `content_added_or_updated`	Content source metadata (title, URL, author, etc.) + default metadata from trigger config

For content-based triggers, metadata from the content source is automatically included. This typically contains fields like title, author, source_url, published_date, content_type, and any custom metadata defined on the source.

Content-based triggers also provide source_connection_content_version_id in the run metadata. This ID is required by the Write Metadata, Write Content Attachment, and Load Content Attachment step types to identify which content record to read from or write to. You do not need to configure this manually — it is set automatically when the agent is triggered by a content event.

Using Metadata in Steps

Metadata is accessed via {{metadata.field_name}} in any step field that supports string substitutions:

In a prompt call system prompt:

You are analyzing content from {{metadata.source_url}}.
Author: {{metadata.author}}
Category: {{metadata.category}}

In a gate condition:

Target: metadata.category
Operator: $eq
Value: technology

In an S3 object key:

reports/{{metadata.category}}/{{metadata.article_id}}/{{date UTC}}.json

In a webhook payload:

{
  "source": "{{metadata.source_url}}",
  "title": "{{metadata.title}}",
  "summary": "{{step.summarize.output}}",
  "processed_at": "{{datetime UTC}}"
}

In an email subject:

New {{metadata.category}} article: {{metadata.title}}

Running Triggers

Manual Execution

Both dynamic_input and template_input triggers can be run manually:

Via the UI:

Navigate to your agent
Click Run on the trigger
For dynamic input: enter your input text and optional metadata
For template input: the template is rendered automatically

Via the API:

curl -X POST https://api.seclai.com/agents/{agent_id}/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Your input text here",
    "metadata": {
      "key": "value"
    }
  }'

Cloud File Triggers

Cloud file triggers run an agent automatically whenever a file is added or updated on a connected cloud drive. The changed file is downloaded and passed to the agent as its input, so the agent can process it directly.

Setup

Go to Integrations → Cloud Drives and connect a drive (e.g. Dropbox). You'll be redirected to authorize read-only access; only files that change after you connect will trigger runs (your existing files are not reprocessed).
On your agent, set the trigger type to a Cloud File trigger and pick the connected drive.
Optionally narrow which files trigger the agent with the filters below.

Optional filters

File path pattern — a case-insensitive glob matched against the file path, e.g. /reports/* or **/*.pdf. Leave blank to match all files.
File content types — an allowlist of formats, e.g. application/pdf or image/*. Leave blank to allow any type.
Max file size (MB) — files larger than this are skipped.

File metadata

Each run captures the changed file's identity and the drive event as metadata, available to every step via {{metadata.field}}:

Metadata Key	Description
`file_name`	The file name
`file_path`	The file's path on the drive
`file_id`	The provider's stable file identifier
`file_rev`	The provider's file revision identifier
`file_event_type`	`file_added` or `file_updated`
`file_size`	The file size in bytes
`file_content_type`	The file's MIME type
`file_modified_at`	When the file was last modified on the drive
`file_client_modified_at`	The client-reported modification time (when present)
`cloud_drive_provider`	The drive provider (e.g. `dropbox`)
`cloud_drive_connection_id`	The Seclai cloud-drive connection ID
`external_account_id`	The provider account the file belongs to

Reference them in steps with {{metadata.file_name}} etc.

Note: Files that are skipped (too large, download failed, or during a very large burst) are recorded on the connection's Skipped files tab. If a drive needs re-authorization, the connection is marked Error — reconnect it from the connection page.

Reading and writing drive files from a workflow

Triggers are only one way an agent touches a cloud drive. Inside a workflow you can also add cloud-drive steps — List folder, Read file, and Write file — that operate on a connected drive on demand (for example, list a folder, read a specific file by path, or write a generated report back to the drive). A prompt_call step can additionally enable a cloud-drive tool so the model itself can browse, read, and (optionally) write files during a tool loop, scoped to one connection and bounded by per-run call and byte limits. All of these use the same connections you set up under Integrations → Cloud Drives.

Automatic Execution

Scheduled triggers — Fire at the times defined by their schedule(s)
Content triggers — Fire when the connected knowledge base detects content changes
Cloud file triggers — Fire when a file is added or updated on a connected cloud drive

Automatic runs appear in the agent's traces alongside manual runs.

Next Steps

Agent Steps — Learn about each step type in detail
Agents Overview — Back to the agents overview
Knowledge Bases — Connect data sources to triggers
Content Sources — Understand how content flows into knowledge bases
API Examples — Code samples for agent automation