Event sources define external triggers that can start agent tasks or workflows. They allow agents to respond to file changes, webhooks, scheduled events, and connection events.

Overview¶

LLMling-Agent supports multiple event source types that enable reactive agent workflows:

File Watch: Trigger on file system changes
Webhook: HTTP endpoint for external triggers
Email: Email-based triggers
Time: Scheduled/periodic execution
Connection: Trigger on agent connection events

Event sources are typically used with task configurations to create event-driven agent systems.

Configuration Reference¶

Event Sources¶

File watching¶

File watching event source.

File watching (YAML)
- type: file
  paths:  # Paths or patterns to watch for changes.
  - /home/user/documents
  - /var/log
  extensions: null  # File extensions to monitor (e.g. ['.py', '.md']).
  ignore_paths: null  # Paths or patterns to ignore.
  recursive: true  # Whether to watch subdirectories.
  debounce: 1600  # Minimum time (ms) between trigger events.
  name: file_watcher  # Unique identifier for this event source.
  enabled: true  # Whether this event source is active.
  template: '  # Jinja2 template for formatting events.

    {%- if include_timestamp %}at {{ timestamp }}{% endif %}

    Event from {{ source }}:

    {%- if include_metadata %}

    Metadata:

    {% for key, value in metadata.items() %}

    {{ key }}: {{ value }}

    {% endfor %}

    {% endif %}

    {{ content }}

    '
  include_metadata: true  # Control metadata visibility in template.
  include_timestamp: true  # Control timestamp visibility in template.

Webhook¶

Webhook event source.

Webhook (YAML)
- type: webhook
  port: 8080  # Port to listen on.
  path: /webhook  # URL path to handle requests.
  secret: null  # Optional secret for request validation.
  name: file_watcher  # Unique identifier for this event source.
  enabled: true  # Whether this event source is active.
  template: '  # Jinja2 template for formatting events.

    {%- if include_timestamp %}at {{ timestamp }}{% endif %}

    Event from {{ source }}:

    {%- if include_metadata %}

    Metadata:

    {% for key, value in metadata.items() %}

    {{ key }}: {{ value }}

    {% endfor %}

    {% endif %}

    {{ content }}

    '
  include_metadata: true  # Control metadata visibility in template.
  include_timestamp: true  # Control timestamp visibility in template.

Email¶

Email event source configuration.

Monitors an email inbox for new messages and converts them to events.

Email (YAML)
- type: email
  host: imap.gmail.com  # IMAP server hostname (e.g. 'imap.gmail.com')
  port: 993  # Server port (defaults to 993 for IMAP SSL)
  username: user@gmail.com  # Email account username/address
  password: '!ENV ENV_VAR_NAME'  # Account password or app-specific password
  folder: INBOX  # Folder/mailbox to monitor
  ssl: true  # Whether to use SSL/TLS connection
  check_interval: 60  # How often to check for new emails (in seconds)
  mark_seen: true  # Whether to mark processed emails as seen
  filters: {}  # Filtering rules for emails (subject, from, etc)
  max_size: null  # Size limit for processed emails in bytes
  name: file_watcher  # Unique identifier for this event source.
  enabled: true  # Whether this event source is active.
  template: '  # Jinja2 template for formatting events.

    {%- if include_timestamp %}at {{ timestamp }}{% endif %}

    Event from {{ source }}:

    {%- if include_metadata %}

    Metadata:

    {% for key, value in metadata.items() %}

    {{ key }}: {{ value }}

    {% endfor %}

    {% endif %}

    {{ content }}

    '
  include_metadata: true  # Control metadata visibility in template.
  include_timestamp: true  # Control timestamp visibility in template.

Time event¶

Time-based event source configuration.

Time event (YAML)
- type: time
  schedule: 0 9 * * 1-5  # Cron expression for scheduling (e.g. '0 9 * * 1-5' for weekdays at 9am)
  prompt: Generate daily report  # Prompt to send to the agent when the schedule triggers.
  timezone: null  # Timezone for schedule (defaults to system timezone)
  skip_missed: false  # Whether to skip executions missed while agent was inactive
  name: file_watcher  # Unique identifier for this event source.
  enabled: true  # Whether this event source is active.
  template: '  # Jinja2 template for formatting events.

    {%- if include_timestamp %}at {{ timestamp }}{% endif %}

    Event from {{ source }}:

    {%- if include_metadata %}

    Metadata:

    {% for key, value in metadata.items() %}

    {{ key }}: {{ value }}

    {% endfor %}

    {% endif %}

    {{ content }}

    '
  include_metadata: true  # Control metadata visibility in template.
  include_timestamp: true  # Control timestamp visibility in template.

Event source¶

Trigger config specifically for connection events.

Event source (YAML)
- type: connection
  source: null  # Connection source name.
  target: null  # Connection to trigger.
  event: message_received  # Event type to trigger on.
  condition: null  # Condition-based filter for the event.
  name: file_watcher  # Unique identifier for this event source.
  enabled: true  # Whether this event source is active.
  template: '  # Jinja2 template for formatting events.

    {%- if include_timestamp %}at {{ timestamp }}{% endif %}

    Event from {{ source }}:

    {%- if include_metadata %}

    Metadata:

    {% for key, value in metadata.items() %}

    {{ key }}: {{ value }}

    {% endfor %}

    {% endif %}

    {{ content }}

    '
  include_metadata: true  # Control metadata visibility in template.
  include_timestamp: true  # Control timestamp visibility in template.

Connection Event Conditions¶

Connection events can be filtered using conditions:

Content Condition¶

Simple content matching for connection events.

Content Condition (YAML)
- type: content
  words:  # List of words to match.
  - error
  - warning
  mode: any  # Matching mode.

Jinja2 Condition¶

Flexible Jinja2 condition for connection events.

Jinja2 Condition (YAML)
- type: jinja2
  template: '{{ event.message.content | length > 100 }}'  # Jinja2-Template (needs to return a "boolean" string).

Usage with Tasks¶

Event sources are configured with tasks to create reactive workflows:

tasks:
  monitor_logs:
    agent: log_analyzer
    event_source:
      type: file_watch
      paths: ["logs/*.log"]
      recursive: false
    parameters:
      analysis_level: "detailed"

  scheduled_backup:
    agent: backup_agent
    event_source:
      type: time
      schedule: "0 2 * * *"  # 2 AM daily

Best Practices¶

File Watching¶

Use specific glob patterns to minimize events
Set appropriate ignore_patterns to exclude temporary files
Consider recursive: false for better performance if subdirectories aren't needed

Webhooks¶

Always use authentication for production webhooks
Validate webhook payloads in your agent logic
Use environment variables for sensitive tokens

Email Events¶

Use dedicated email accounts for automation
Configure appropriate filters to avoid processing spam
Consider rate limiting for high-volume scenarios

Time Events¶

Use cron syntax for recurring schedules
Test schedules with online cron expression validators
Consider timezone implications for scheduled tasks

Connection Events¶

Use specific source/target filters to reduce noise
Combine with conditions for fine-grained control
Monitor event frequency to avoid performance issues

Configuration Notes¶

Event sources can be shared across multiple tasks
File watch and webhook events require the system to be running
Email events poll at configurable intervals
Connection events are processed in real-time
Time events use system timezone unless specified
All event sources support async operation