Agents

AI agents in Seclai are multi-step LLM pipelines that chain model calls, retrieval, validation, and actions together — with built-in retries, evaluation, governance, observability, and cost tracking at every step.

What are Agents?

Agents are AI-powered workflows that can:

• Call AI models (GPT, Claude, Gemini, and 50+ others) to generate responses
• Search knowledge bases using semantic similarity and metadata filters
• Transform and extract data from JSON, XML, and HTML
• Integrate with external systems via webhooks and APIs
• Send notifications via email
• Run automatically on schedules or when content changes
• Store results in AWS S3 or display them directly
• Remember context across conversations using persistent memory banks
• Branch and merge parallel processing paths with gates, joins, and combinators

Each agent is composed of ordered steps that execute as a directed graph, with outputs from one step feeding into the next. This creates powerful, flexible workflows for content processing and automation.

Agent Definition

An agent definition includes:

Agent definitions are versioned via branches and changes, similar to version control. Each change captures a snapshot of the agent's full configuration including all steps and their settings.

Model Lifecycle Defaults

Agents can define lifecycle defaults for model-based steps:

• prompt_model_auto_upgrade_strategy: none, early_adopter, middle_of_road, or cautious_adopter
• prompt_model_auto_rollback_enabled: enables rollback after configured failure signals
• prompt_model_auto_rollback_triggers: subset of agent_eval_fail, governance_flag, governance_block, agent_run_failed

These defaults apply to Prompt Call and Insight steps unless a step explicitly sets per-step overrides.

Precedence is:

1. Step-level override
2. Agent-level default
3. System default

For field-level details and examples, see Agent Steps: Model Lifecycle Controls.

Configure these settings via the API or MCP:

curl -X PUT "https://api.seclai.com/api/agents/$AGENT_ID" \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_model_auto_upgrade_strategy": "cautious_adopter",
    "prompt_model_auto_rollback_enabled": true,
    "prompt_model_auto_rollback_triggers": ["agent_eval_fail", "governance_block"]
  }'

See Model Lifecycle: Automatic Model Upgrades for strategy descriptions and rollback behaviour.

Triggers

Triggers define when an agent runs and what input it receives. An agent can have multiple triggers, each with its own type, configuration, and optional schedule.

All triggers support metadata — key-value pairs accessible in steps via {{metadata.field_name}}.

For complete trigger documentation, including scheduling, metadata examples, and use cases, see Agent Triggers.

Steps

Agents execute a series of steps in order. Each step type serves a specific purpose:

Steps support string substitutions using {{placeholder}} syntax to reference agent input, other steps' outputs, metadata, dates/times, and more.

For complete step documentation, including all fields, AI assistant support, and detailed examples, see Agent Steps.

Creating an Agent

Via the App

1. Navigate to Agents in your account
2. Click Create Agent
3. Configure the agent:
   • Name — Give it a descriptive name
   • Description — Optional details about its purpose
   • Trigger Type — Select when it should run
   • Knowledge Base — (Optional) Connect to a knowledge base
   • Template — Start with blank or use a retrieval example
4. Add and configure steps
5. Save and test

Via the API

Create agents programmatically using the API. See API Examples for code samples.

Running Agents

Manual Execution

Run agents on demand via the UI or API:

Via the UI:

1. Open the agent
2. Click Run on the trigger
3. For dynamic input triggers: enter your input text and optional metadata
4. For template input triggers: the template renders 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": "What are the latest AI trends?",
    "metadata": {
      "user_id": "123",
      "source": "api"
    }
  }'

Automatic Execution

Agents run automatically when:

• Scheduled triggers fire at the configured time(s) — see Schedules
• Content triggers detect changes in the connected knowledge base — see Content Triggers

Monitoring Runs

Run Status

Each agent run has a status:

Step Runs

Each step within a run tracks:

• Status — Pending, processing, completed, or failed
• Input and output — The data flowing in and out of the step
• Error messages — Details if the step failed
• Duration — How long the step took to execute
• Credit usage — Credits consumed by the step (for AI model calls)

Agent Traces

Agent traces are per-run execution records that show what happened during a run from start to finish. They include status, step-level inputs and outputs, errors, timing, and credit usage.

You can find them here:

• UI: Account → Agents → [Agent Name] → Traces tab
• API: GET /agents/{agent_id}/runs

The primary purpose of traces is operational visibility. Use them to debug failures, validate outputs, diagnose performance bottlenecks, and monitor reliability over time. Traces also support searching across past runs so you can quickly find specific results.

For complete details and best practices, see Agent Traces.

Agent Warnings

The system analyzes your agent definition and provides warnings for:

• Missing required metadata fields referenced in substitutions
• Undefined step references (e.g., {{step.nonexistent.output}})
• Invalid model selections
• Configuration issues that could cause runtime failures

Warnings appear in the agent editor and help you fix issues before deployment.

Validation

Before execution, agents are validated:

• Must have at least one step
• All string substitutions must reference valid steps and fields
• Model configurations must be compatible with selected features
• Required fields (e.g., knowledge base ID for retrieval) must be present
• Gate conditions must use valid operators and targets

Invalid agents cannot be saved or executed.

Alerts

Configure alerts to be notified when agent runs match specific criteria. Alerts can monitor run outcomes and trigger notifications based on conditions you define.

Exporting Agents

Export an agent's full definition as a portable JSON snapshot. The export includes the complete step workflow, trigger configuration with schedules, alert configs, and a dependency manifest that resolves every referenced external entity (knowledge bases, memory banks, source connections, other agents, users) to its human-readable name.

What's included in the export:

• export_version — schema version for forward compatibility
• exported_at — ISO-8601 timestamp
• software_version — application version that produced this export
• agent — name, description, schema version, full definition, timestamps
• trigger — trigger type, input template, and schedules (if any)
• alert_configs — alert type, thresholds, and recipients (if any)
• evaluation_criteria — evaluation settings per step (if any)
• governance_policies — agent-scoped governance policies (if any)
• dependencies — grouped lists of knowledge bases, memory banks, source connections, agents, and users referenced by the definition

How to export:

• UI (detail page): Click the Export button in the agent header.
• UI (list page): Open the agent's action menu (⋮) and select Export.
• Public API: GET /api/agents/{agent_id}/export with your API key.
• MCP: Use the export_agent tool with the agent ID.

The export is a read-only snapshot — it does not modify the agent.

Other export types: You can also export an agent's trace history and evaluation results as bulk data files in JSON, JSONL, or CSV. See Export Formats for all available export types.

Example Workflows

RAG Chat Bot

A customer support bot that answers questions using your documentation:

Trigger: Dynamic Input
Step 1: Retrieval — Search documentation knowledge base
Step 2: Prompt Call — Generate answer using retrieved context
Step 3: Display Result — Show the answer

Content Monitor

Monitor RSS feeds and send email summaries of new articles:

Trigger: Content Added (on news knowledge base)
Step 1: Prompt Call — Summarize the new article
Step 2: Gate — Only continue if article is relevant
Step 3: Send Email — Deliver the summary

Scheduled Report

Generate a daily analysis report from your knowledge base:

Trigger: Template Input (daily schedule at 8 AM)
  Template: "Generate daily report for {{date America/New_York}}"
Step 1: Retrieval — Fetch recent content
Step 2: Prompt Call — Analyze and generate report
Step 3: Write AWS S3 Object — Store the report
Step 4: Send Email — Deliver the report

Parallel Analysis Pipeline

Run multiple analyses in parallel and combine results:

Trigger: Dynamic Input
Step 1: Retrieval — Search knowledge base
  ├── Step 2a: Prompt Call (summarize) → Join → Combinator
  └── Step 2b: Prompt Call (extract entities) → Join → Combinator
Step 3: Combinator — Merge summary and entities
Step 4: Write AWS S3 Object — Store combined result
Step 5: Display Result — Show to user

Next Steps

• Agent Traces — Understand run-level observability, debugging, and monitoring
• Agent Triggers — Deep dive into trigger types, schedules, and metadata
• Agent Steps — Comprehensive reference for all step types
• Knowledge Bases — Connect data sources to agents
• Memory Banks — Give agents persistent memory across conversations
• Content Sources — Learn about content sources for knowledge bases
• API Examples — Code samples for agent automation