Workflows & AI agents

A workflow is a project-scoped, multi-step process that starts when a record lands in its entry dataset. Steps run in order, share a JSON context scratchpad seeded from the entry record, and can emit events, call AI, branch on a condition, wait for other events, or sleep. You compose pipelines like lead → AI score → branch on score → notify → wait for approval → follow up without running your own queue or state store.

Build it visually

Every workflow is edited through the same definition in three interchangeable views — pick whichever fits the moment, and switch anytime without losing anything.

Mode	What it's for
Canvas	A true drag-and-drop, box-and-wire editor. Every step type sits in a toolbox; branch renders as a native switch with labeled then/else lanes you drop steps straight into. Undo, a control bar, and a per-step property panel — all self-hosted, zero third-party script calls.
Form	Structured step cards with typed fields per step type — dataset autocomplete, an AI-agent dropdown, a reusable condition-row builder (path / operator / value). Reorder by drag or ↑/↓. Validated client-side before you even hit save.
JSON	The full-fidelity raw definition, for anything the form doesn't cover yet. Always available — switching modes round-trips losslessly, so you're never locked out of a workflow someone else built in JSON.

See the whole flow at a glance

Every workflow — and every running instance of it — renders as a diagram, not just a list of steps. A branch step expands into labeled then/else lanes right where it sits, so the decision tree is visible without opening the editor. Below is the shape of the lead-qualification workflow from the JSON example further down:

▶

Entry

leads · tier = enterprise

✦

1. Call AI

score lead → context.score

completed

⑂

2. Branch

if score > 7

current

then

→

Emit event

→ hot_leads

else

→

Emit event

→ nurture_leads

⏸

3. Wait for event

approvals · status = approved

This is the same diagram whether you're looking at the workflow's definition or a live, running instance — running instances recolor each node from execution history: completed, current, waiting, failed (with the error inline), or not yet reached.

Branching

A branch step evaluates one or more conditions against the instance context — the same condition shape used everywhere else in Hookie (equals · not_equals · contains · exists · gt · lt) — and runs then when they match, else otherwise. Because conditions read the context, you can branch on anything an earlier step produced: score a lead with AI, then route high-scorers one way and everyone else another. Branches nest up to 3 levels deep, and every taken path is recorded in step history so you can see exactly which way an instance went.

Branch sub-steps run synchronously — emit_event, call_ai, agent_call, and nested branch only. A delay or wait_for_event can't sit inside a branch; put it after the branch instead. This keeps a branch's execution atomic and its outcome immediately visible in the diagram.

Defining a workflow

Create workflows in the console under Project → Workflows — start in Canvas, Form, or JSON, whichever you reach for first. Entry conditions use the shared condition shape — an empty array matches every record in the dataset.

{
  "name": "Lead qualification",
  "entry_dataset": "leads",
  "entry_conditions": [
    { "path": "tier", "op": "equals", "value": "enterprise" }
  ],
  "steps": [
    { "type": "call_ai",
      "instructions": "Score this lead 1-10 for ICP fit; reply with JSON.",
      "output_key": "score", "output_dataset": "lead_qualification" },
    { "type": "branch",
      "conditions": [{ "path": "score", "op": "gt", "value": 7 }],
      "then": [
        { "type": "emit_event", "dataset": "hot_leads", "payload": { "priority": "high" } }
      ],
      "else": [
        { "type": "emit_event", "dataset": "nurture_leads" }
      ] },
    { "type": "wait_for_event",
      "dataset": "approvals",
      "conditions": [{ "path": "status", "op": "equals", "value": "approved" }],
      "timeout_seconds": 86400 },
    { "type": "delay", "seconds": 3600 }
  ]
}

Step types

Type	What it does
`emit_event`	Write a record into a dataset (entry context merged with an optional payload) and enqueue signed deliveries for it. Emitted records never re-trigger workflow entry — no feedback loops.
`call_ai`	Run an AI prompt over the instance context. The text result lands in the context under output_key (default ai_result) and, optionally, in output_dataset.
`agent_call`	Invoke a reusable AI agent by id — its model, system prompt, and memory dataset apply. The result lands under output_key (default agent_result).
`branch`	Conditional if/then/else. Evaluate conditions against the instance context and run the matching then or else sub-sequence — including branching on an earlier call_ai or agent_call result. Branches can nest up to 3 levels deep.
`wait_for_event`	Suspend until a record matching the conditions arrives in a dataset. An optional timeout_seconds moves the instance to timed_out if nothing arrives.
`delay`	Suspend for N seconds before the next step.

AI agents

An AI agent is a reusable, named LLM persona — a model, a system prompt, a bounded token cap, and an optional memory dataset that every output is also written to for recall. Define agents next to your workflows in the console, then reference one from any workflow with an agent_call step — including inside a branch. Update the agent once; every workflow that uses it picks up the change.

Instances & observability

Each matching entry record starts an instance. The console lists instances per workflow with a drill-down into the live context, the recolored progress diagram, and a per-step history (started / completed / failed, including which branch was taken), so you can see exactly where a flow is and why it stopped.

State	Meaning
`pending`	Created from a matching entry record; about to run.
`running`	Executing steps.
`waiting`	Suspended on a delay or wait_for_event.
`completed`	Every step finished.
`failed`	A step errored; last_error records why.
`timed_out`	A wait_for_event passed its deadline.

Limits

Up to 32 steps per workflow (branch sub-steps count toward the total).
Branch nesting depth: 3 levels.
Active-instance cap per plan: 25 on Free, 500 on Pro, 2,000 on Team.
delay and wait_for_event timeouts resolve on the platform scheduler (~5-minute resolution).
AI steps are bounded to 1,024 output tokens and count toward your plan's AI usage.

Workflows are managed from the console — sign in and open a project's Workflows tab. For end-to-end patterns, see the use cases.