Agents overview

An agent is the operational unit in Flexor. It watches for a trigger, executes a task sequence using skills, and produces a result. Agents are what operators run, monitor, and tune over time.

What makes an agent different from a skill

Skills are reusable units of work - stateless, composable, and invokable. Agents are processes - they run on their own, respond to external events, and have operational properties like schedules, retry policies, and audit trails.

A skill answers: “how do we do this?”
An agent answers: “when do we do this, and what do we do when it goes wrong?”

Agent anatomy

name: feed-monitor
version: "1.0"
description: "Monitor critical data feeds for freshness. Alert on stale feeds."
owner: "ops-team"

trigger:
  type: schedule
  cron: "*/30 * * * *"

environment: production

retry:
  max_attempts: 2
  backoff_seconds: 60

tasks:
  - skill: data-freshness-check
    args:
      feed_name: "equity-prices"
      max_age_minutes: 30
    capture: result

  - condition: "{{ !result.is_fresh }}"
  - skill: core.notify.slack
    args:
      channel: "#data-ops"
      message: "equity-prices is {{ result.staleness_minutes }} min stale."
  - end_condition

  - skill: core.audit.log
    args:
      event: "feed_freshness_check"
      result: "{{ result }}"

Trigger types

Type	When it fires	Use case
schedule	Cron expression	Recurring checks, periodic reports
event	PlexiFact data event (feed update, anomaly flag)	React to data changes in real time
webhook	HTTP POST to an agent-specific endpoint	Triggered by external systems (portfolio system, risk platform)
manual	Explicitly invoked via CLI or dashboard	On-demand runs, testing, one-off operations

The agent roster

The agent roster is the set of agents configured in a vault. Viewing the roster:

flexor agents list

Output:

NAME              TRIGGER     ENVIRONMENT  STATUS   LAST RUN
feed-monitor      schedule    production   active   2026-04-30 14:30 UTC
weekly-nav-report schedule    production   active   2026-04-28 08:00 UTC
lp-notice         webhook     production   active   2026-04-25 11:15 UTC
recon-check       event       staging      paused   2026-04-22 09:00 UTC

When to use an agent vs. a skill

Use an agent when:

• The work needs to happen on a schedule or in response to an event
• The work has multiple steps that need sequencing and error handling
• The work needs to be monitored, logged, and audited
• The outcome of the work affects other systems (sends messages, creates tickets)

Use a skill when:

• You are defining a reusable capability to be called by agents or other skills
• The work is a single logical operation (query, transform, check, format)
• You want to compose the capability with others in different contexts

The distinction matters for operations: agents appear in your monitoring dashboard, have run histories, and generate audit log entries. Skills are invisible at the operational level - they execute inside agents but do not appear as independent operational entities.

Agent metadata fields

Field	Type	Required	Description
name	string	Yes	Unique agent name. Snake_case.
version	string	Yes	Semantic version.
description	string	Yes	One sentence. Shown in the agent roster.
owner	string	No	Team or individual responsible. Used in alert routing.
trigger	object	Yes	Trigger configuration. See trigger types above.
environment	string	Yes	"sandbox" | "staging" | "production"
retry	object	No	Retry policy for task failures.
tasks	array	Yes	Ordered list of skill invocations and conditions.
paused	boolean	No	If true, agent will not fire even if its trigger condition is met.