Write Plays

Write a Play when the business decision is yours: custom routing, a specific provider order, a scheduled refresh, or an outbound destination. Use a Prebuilt Play when the maintained contract already does the job.

Discover a live contract before provider work

Do not copy a provider ID or payload from an old example. Search the current workspace, then read the schema before you add a provider action:

deepline search --type tools "company search"
deepline tools describe free_simple_company_search --json

deepline tools get free_simple_company_search --json remains a backward-compatible alias for tools describe; prefer describe in new automation. Save this first example as lead-routing.play.ts. Keep it decision-only and validate it before you add provider work:

deepline plays check lead-routing.play.ts

The authoring contract

A deployable Play has one default definePlay(...) export, typed input, a plain-object return value, and a non-empty description. The handler runs in Deepline; ctx.* records the work that it performs.

import { definePlay } from 'deepline';

type Lead = {
  lead_id: string;
  linkedin_url: string;
};

export default definePlay(
  'enrich-lead-file',
  async (ctx, input: { csv: string }) => {
    const leads = await ctx.csv<Lead>(input.csv);
    const rows = await ctx
      .dataset('lead_email', leads)
      .withColumn('email', (lead, rowCtx) =>
        rowCtx.runPlay(
          'person_email',
          'person-linkedin-to-email',
          { linkedin_url: lead.linkedin_url },
          { description: 'Find a verified work email for this lead.' },
        ),
      )
      .run({
        key: 'lead_id',
        description: 'Find one email for each lead.',
      });

    return { rows };
  },
  {
    description: 'Find verified work emails for a CSV of LinkedIn profiles.',
  },
);

This example composes a scalar prebuilt Play. It keeps one durable row per lead_id, so a failed row is visible rather than silently dropped.

Choose the runtime primitive

Use	When the work is	What must be stable
`ctx.dataset(...).withColumn(...).run(...)`	Row-oriented and exportable	The dataset row key
`ctx.step(...)`	One scalar action or checkpoint	The step key
`ctx.tools.execute(...)`	One provider-backed operation	The tool call `id`
`ctx.runPlay(...)`	A statically resolvable scalar child Play	The child-call key
`ctx.fetch(...)`	An external HTTP request that should appear in run history	The request id and downstream idempotency key

Use ctx.runPlay(...) for a Play, not ctx.tools.execute(...). A tool is one provider-backed operation. A child Play is reusable business logic and must be small enough to run inline; a child that owns a dataset, CSV, event wait, or explicit timeout must run as a top-level Play instead.

Validate before deployment or spend

deepline plays check ./enrich-lead-file.play.ts --json

This validates the Play without deploying it or starting provider-backed work. Fix the reported contract or authoring error before you publish or run it.

Add operational guardrails

Put durable operational policy next to the code it governs:

import { definePlay } from 'deepline';

export default definePlay(
  'nightly-refresh',
  async (_ctx) => ({ refreshed_at: new Date().toISOString() }),
  {
    description: 'Refresh account context once per day.',
    billing: { maxCreditsPerRun: 25 },
    cron: {
      schedule: '0 9 * * *',
      timezone: 'America/New_York',
    },
  },
);

Use the smallest credit cap and schedule that fit the job. For a file pilot and export review, use Batch CSV enrichment. For trigger semantics, use Webhooks and schedules.

Next steps

Prebuilt Plays

Discover a maintained Play or compose a scalar child Play.

SDK reference

Read the exact definePlay, ctx, dataset, and tool contracts.

Get started

Build and automate

Common workflows

Data and integrations

Reference

Discover a live contract before provider work

The authoring contract

Choose the runtime primitive

Validate before deployment or spend

Add operational guardrails

Next steps

Prebuilt Plays

SDK reference

​Discover a live contract before provider work

​The authoring contract

​Choose the runtime primitive

​Validate before deployment or spend

​Add operational guardrails

​Next steps

Prebuilt Plays

SDK reference

Discover a live contract before provider work

The authoring contract

Choose the runtime primitive

Validate before deployment or spend

Add operational guardrails

Next steps