Agents

An Agent is the scheduling primitive in Machina: it runs your workflows on a schedule, each with a cadence, a status, and an execution history.

Concretely, an Agent has:

Identity: title (display name), name (slug, set once at creation and immutable), description.
Status: active or inactive.
Frequency: how often it runs, stored as context["config-frequency"] in minutes (e.g. 0.5 = every 30 seconds).
Workflows: the one or more workflows it triggers on that cadence.
Documents: records associated with the agent, shown on its detail page.
Execution history: every past run, inspectable individually.

When to use an Agent

Use an Agent when you need something to run on its own, repeatedly — syncing data, refreshing embeddings, posting scheduled content — without a human or an external caller triggering it each time. If you need to run something on demand instead (a one-off pipeline triggered by a request), that's a plain Workflow run directly, not an Agent.