Your First Workflow

Chain Agents Together with Workflows

A workflow connects multiple agents into a single pipeline with built-in logging and error handling.

1. Create

novium workflow create hello-workflow

workflows/
  hello-workflow/
    workflow.ts

2. Define Steps

Open workflows/hello-workflow/workflow.ts:

export default {
  trigger: {
    type: "http",
    method: "POST",
    path: "/hello-workflow",
  },
  steps: [
    {
      id: "process-name",
      agent: "hello-agent",
      input: { name: "$input.name" },
    },
    {
      id: "count-visits",
      agent: "hello-agent",
      input: { name: "$input.name" },
    },
    {
      id: "finalize",
      action: "log",
      message: "Workflow completed for $input.name",
    },
  ],
};

Concepts:

| Concept | Description | | ------- | ----------- | | trigger | How the workflow starts (HTTP, schedule, or event) | | steps | Ordered list of agent calls and actions | | $input | Reference to the workflow's input payload | | action | Built-in actions: log, wait, condition, approval |

3. Run Locally

novium workflow dev

Workflow "hello-workflow" listening at http://localhost:3001

Trigger:

curl -X POST http://localhost:3001/hello-workflow \
  -H "Content-Type: application/json" \
  -d '{"name": "Novium"}'

Response:

{
  "workflowId": "wf_abc123",
  "status": "completed",
  "steps": [
    { "id": "process-name", "status": "success", "duration": "312ms" },
    { "id": "count-visits", "status": "success", "duration": "287ms" },
    { "id": "finalize", "status": "success", "duration": "0ms" }
  ],
  "duration": "599ms"
}

4. Add Conditions

Only run a step if a condition is met:

{
  id: "vip-greeting",
  agent: "greeting-agent",
  condition: "$input.tier === 'vip'",
  input: { name: "$input.name", tier: "$input.tier" },
}

5. Add Approval Gates

Pause execution until a human approves:

{
  id: "review",
  action: "approval",
  message: "Review agent output before continuing",
  reviewers: ["admin@example.com"],
}

6. Scheduled Triggers

Run a workflow on a schedule:

trigger: {
  type: "schedule",
  cron: "0 9 * * *",   // Every day at 9 AM
}

7. Deploy

novium deploy

Deploying workflow "hello-workflow"...
✓ Deployed
  Endpoint: https://my-workspace.novium.cloud/hello-workflow

8. Monitor

novium workflow list

NAME              TRIGGER   STATUS    LAST RUN
hello-workflow    http      active    2 min ago

View execution history:

novium workflow history hello-workflow