Overview

A play runs a workflow over a data model, emitting a run for each row that changes. Where a tool is triggered on demand, a play continuously watches its model and fires when matching changes occur. You define one with definePlay.

Define a play

plays/onboarding.ts

import { definePlay, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";
import { contacts } from "../models/contacts";
import { enrich } from "../tools/enrich";

const onboardRow = defineWorkflow(
  "onboard-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ welcomed: z.boolean(), message: z.string() }),
    uses: { enrich },
  },
  ({ input, uses, ai }) => {
    const enriched = uses.enrich({ email: input.email });
    const message = ai(
      `Draft a one-line welcome for ${input.email} at ${enriched.company}.`,
    );
    return { welcomed: true, message };
  },
);

export const onboarding = definePlay("onboarding", {
  model: contacts,                    // the model whose rows drive it
  workflow: onboardRow,               // per-row automation, deployed as the release
  changeKinds: ["added", "updated"],  // which row changes fire a run
  runCreationRule: "always",
  schedule: { type: "realtime" },     // fire as rows change; see below for other types
});

The per-row workflow is deployed as the play’s release. changeKinds and schedule control when runs are created. schedule accepts one of:

`type`	Fires…
`realtime`	as the model’s rows change (the reactive default for row-driven plays)
`cron`	on a cron expression — `{ type: "cron", cron: "0 * * * *" }`
`dbt`	after a dbt job completes
`dependency`	after another play finishes — `{ type: "dependency", play: upstream }`
`watch`	on a watched external schedule

realtime and watch are distinct: realtime reacts to row changes in the model, while watch follows an externally managed schedule.

Deploy and trigger

cargo-ai cdk deploy
cargo-ai orchestration play list                 # → workflowUuid, modelUuid
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"filter","modelUuid":"<uuid>"}' \
  --wait-until-finished

{"kind":"filter"} enrols every row of the model; add a filter to narrow it. See Triggering for the other data kinds.

Plays always use batch create, never run create — run create on a play’s workflow returns a playNotCompatible error.

Do not pass the segmentUuid returned by play list to {"kind":"segment"}. That is the play’s internally generated segment, whose record count is never populated, so the batch fails with noRecords. {"kind":"segment"} is for standalone segments from segmentation segment list — see Segments.

Fallbacks and health

Add fallback paths so a failed step doesn’t fail the whole run (notify, try an alternative provider, write defaults, or skip and continue). Watch success rate and set batch-health alerts. See Triggering for schedules and enrolment, and Monitoring for records and metrics. Batch health is declarative on the play: healthThreshold is the minimum percentage of successful runs (0–100) for a finished batch to count healthy, and healthAlertActions fire — each as its own run — when a batch lands below it. Actions take a connector action, an agent, or a tool:

export const onboarding = definePlay("onboarding", {
  model: contacts,
  workflow: onboardRow,
  healthThreshold: 90,
  healthAlertActions: [
    {
      ref: slack.actions.postMessage,
      config: {
        channelId: "C0123456789",
        format: "markdown",
        body: "Onboarding batch unhealthy — {{batch.url}}",
      },
    },
    { ref: sentinel, config: { prompt: "Investigate the unhealthy batch" } },
  ],
});

Omit both fields to keep health managed from the UI; an explicit [] clears the actions. These are the same action shapes an alert fires, so config can be type-checked the same way — wrap a connector action in alertConnectorAction or a tool in alertToolAction, and an agent’s is typed already. Here the interpolation roots are play and batch ({{batch.url}}) rather than an alert’s alert and event.

Using the UI

See Using the UI for the visual play editor — publishing, manual enrolment, re-running failed runs, and fallback configuration.

Get started

Resources

Deploy

CLI

Skills

Reference

Define a play

Deploy and trigger

Fallbacks and health

Using the UI

​Define a play

​Deploy and trigger

​Fallbacks and health

​Using the UI

Define a play

Deploy and trigger

Fallbacks and health

Using the UI