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 five 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

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.

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"
}

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

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

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

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

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"
    }
  }'

Automatic Execution

Scheduled triggers — Fire at the times defined by their schedule(s)
Content triggers — Fire when the connected knowledge base detects content changes

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