Listeners

Listeners allow Karyam to react to events happening outside the platform.

Instead of waiting for a user to manually start an Agent or AI Flow, Listeners automatically trigger execution when specific events occur.

This enables event-driven AI systems that operate continuously in the background.

Why Listeners Exist

Most business processes start because something happens:

A file is uploaded
An email arrives
A webhook is received
A document is added to a folder

Listeners allow AI systems to react immediately when these events occur.

This transforms AI from a reactive assistant into an operational system.

How Listeners Work

A Listener waits for an external event.

When the event occurs, Karyam automatically triggers the configured workflow.

External Event
      ↓
Listener
      ↓
AI Flow / Processing
      ↓
Run

Every listener execution creates normal Runs and participates in observability, logging, and governance.

Listener Types

Karyam currently supports four listener types.

HTTP Listener

HTTP Listeners allow external systems to trigger AI workflows using webhooks or API requests.

Examples include:

GitHub webhooks
CRM updates
CI/CD pipelines
Internal applications
Third-party integrations

Example:

Customer submits support form
            ↓
HTTP Listener receives request
            ↓
AI Flow executes
            ↓
Support ticket created

HTTP listeners are ideal for real-time integrations.

Email Listener

Email Listeners monitor mailboxes and trigger workflows when new emails arrive.

Examples include:

Support inbox automation
Invoice processing
HR requests
Approval workflows

Example:

support@company.com receives email
            ↓
Email Listener triggers flow
            ↓
AI extracts request details
            ↓
Ticket created automatically

Email listeners allow organizations to modernize existing email-driven processes without changing user behavior.

Folder Listener

Folder Listeners monitor specific directories for new files.

When files are added, modified, or uploaded, Karyam automatically starts processing.

Examples include:

Invoice ingestion
Contract processing
Report analysis
Document classification

Example:

New PDF uploaded
        ↓
Folder Listener detects file
        ↓
AI Flow executes
        ↓
Information extracted

Folder listeners are commonly used in document automation pipelines.

Embedding Listener

Embedding Listeners power Karyam’s knowledge ingestion pipeline.

Unlike traditional knowledge bases, Karyam uses an event-driven ingestion model.

When a file is uploaded:

File Upload
    ↓
Embedding Listener Triggered
    ↓
Artifacts Generated
    ↓
Chunking
    ↓
Embeddings Created
    ↓
Stored in Vector Database

The resulting embeddings become immediately available for semantic retrieval.

Typical Embedding Workflow

An embedding listener is usually configured with:

A Vector Database
An Embedding Model
A Folder Path

Example:

Files Upload
    ↓
Folder: knowledge-base/hr
    ↓
Embedding Model
    ↓
Vector Database

Supported Knowledge Sources

Embedding listeners commonly process:

PDFs
Text files
Images
Markdown files
Documents
Audio transcripts

RAG Observability

All ingestion activity performed by embedding listeners can be observed through:

AI INFRA
└── RAG Runs

RAG Runs provide visibility into:

Artifact generation
Chunking
Embedding creation
Vector storage
Retrieval operations
Failures

Listeners and Runs

Every listener execution creates a standard Run.

This means listener-driven executions automatically benefit from:

Logs
Token tracking
Cost analytics
Audit logs
Approval workflows

Listeners and Governance

Listeners do not bypass governance controls.

If an AI Flow triggered by a listener requires approval:

Event
   ↓
Listener
   ↓
Flow Starts
   ↓
Approval Required
   ↓
Execution Paused

Human approvals continue to function normally.

Relationship to Other Concepts

External Event
      ↓
Listener
      ↓
Agent / AI Flow
      ↓
Run
      ↓
Logs

Listeners act as the bridge between external systems and AI execution.

The Karyam Philosophy

Business systems are event-driven.

AI systems should be too.

Listeners allow AI to react automatically to changes happening across your organization.