Docs/Workflows & Playbooks
OrchestrationAgentWorkflow · 5 Execution Modes · HITL Approvals · Per-Run Guardrails

Workflows & Workflow Runs

When an assignment spans multiple data sources, calculations, and downstream updates, Nunc executes it as a durable Workflow Run powered by AgentWorkflow. Runs execute on the server even if you close your browser tab, pause cleanly at human approval gates, enforce strict token and cost guardrails, and promote into reusable Saved Workflows in Console → Build → Workflows.

Five AgentWorkflow execution modes

mode: "direct"
Direct Execution
Single-pass governed execution for focused analytical queries, summary generation, and low-latency operational tasks that still benefit from durable run tracking and audit lineage.
mode: "goal_loop"
Goal Loop & Checklists
Iterative autonomous loop driven by a transparent Markdown checklist (tasks_md). Inspects progress after each step, checks off verified items, and adapts until the objective is met or a guardrail triggers.
mode: "subagents"
Parallel Subagent Fan-Out
Delegates independent workstreams concurrently across domain Specialists (Finance, RevOps, Data Warehouse) under shared parent budget and permission intersections, then synthesizes verified findings.
mode: "saved"
Saved Runbooks
Replays a frozen, parameterized multi-step workflow graph on demand, on a recurring cron schedule, or from signed inbound webhooks while preserving every approval checkpoint.
mode: "sandbox"
Isolated Sandbox
Executes deterministic Python, TypeScript, or JavaScript inside an isolated container with staged file I/O and zero access to tenant databases or connector secrets.

Workflow Runs API (/api/workflows/runs)

Manage workflow runs programmatically via @nunc/sdk (nunc.workflows.runs.*) or direct HTTPS requests:

Method & PathPurpose
POST /api/workflows/runsStart a new AgentWorkflow run (direct, goal_loop with tasks_md, subagents, saved, or sandbox).
GET /api/workflows/runs · GET /api/workflows/runs/:id?waitMs=...List runs or inspect live run status, steps, findings, and tasks_md progress with optional long-polling.
POST /api/workflows/runs/:id/approve · /reject
POST /api/workflows/runs/:id/steps/:stepId/approve · /reject
Approve or reject a paused run or a specific human-gated mutating step with reviewer attribution.
POST /api/workflows/runs/:id/terminateImmediately cancel an active or paused workflow run.
POST /api/workflows/runs/:id/save-as-workflowPromote a completed workflow run into a reusable Saved Workflow runbook for cron scheduling or webhook triggers.
GET / PUT /api/workflows/runs/guardrailsRead or configure tenant-wide per-run token, cost, step, wall-clock, and concurrency limits.
Human-in-the-loop approval gates

Scheduled and autonomous workflow runs never bypass governance. Whenever a step proposes mutating Salesforce, Sage Intacct, Jira, or Slack records, execution pauses at that step and notifies designated reviewers in Data Studio, Console, or Slack / Microsoft Teams.

Approvers inspect the exact target system and parameter diff before approving or rejecting, and every decision is recorded in the tamper-evident audit trail.

Per-run budgets & runtime guardrails

Every run enforces configurable ceilings across maxTokensPerRun, maxCostUsdPerRun, maxStepsPerRun, maxWallClockSec, and maxConcurrentRuns.

Long-horizon goal_loop runs can optionally hand off remaining tasks_md checklist items across bounded continuations (autoRespawnOnLimit) while respecting overall tenant spend caps.