Write Plays - Deepline

Author one bounded Play, check its contract, and inspect a representative run before publication.

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 describe free_simple_company_search

Use deepline describe <id> for both tool and Prebuilt Play contracts. 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 under edition 10, so a failed row is visible rather than silently dropped. Edition 11 CSV inputs retain each source-row occurrence, including repeated keys. Non-CSV datasets and earlier admitted editions keep their existing key-based deduplication behavior. Choose the row policy from the admitted contract and reconcile every expected input occurrence.

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

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',
    },
  },
);

Deepline enforces maxCreditsPerRun on every run. To replace it for one run, pass --max-credits to deepline plays run; see Cost control. 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.

Compose an Engine from Plays

Use the Engine pattern when records need durable business states across executions. Keep the orchestrator and new transition Plays in a versioned project directory.

Define the state matrix: current state, transition Play, allowed next states, terminal outcome, and input/output table roles.
Search for existing owned or prebuilt Plays for each transformation. Inspect the input and output contracts before choosing one.
Use ctx.runPlay only for compatible scalar children. A child that owns a dataset, CSV, event wait, or explicit timeout needs a top-level lifecycle.
Implement state persistence through ctx.customerDb.query(...) in permitted, schema-qualified customer tables. Give each business record a stable key.
Define deterministic transition and handoff keys. Use database constraints and supported conflict handling, such as INSERT ... ON CONFLICT, to recognize completed writes. Repair missing handoffs without inserting a second completed transition.
Record invalid states, forbidden moves, child failures, and invalid results. Do not hand a failed transition to the next state.
Check each new child and the orchestrator, then publish compatible children before code that invokes them. Run a synthetic pilot before provider work.

Test terminal states, unknown states, invalid next states, child failures, repeated inputs, and an interrupted handoff. If concurrent runs can advance the same record, implement and test the workflow’s conflict policy explicitly. Stable call labels alone do not prevent independent executions. For provider-backed pilots, set the smallest practical per-run credit cap. External writes also need destination-supported idempotency or reconciliation. The Engine pattern does not provide an automatic cross-system transaction.

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.

Verify this task

Check the actual source file. Test a supported small input and inspect outputs and errors against the intended business rule. Ask your agent to explain a failed check before repeating work or expanding the scope.

​Discover a live contract before provider work

​The authoring contract

​Choose the runtime primitive

​Validate before deployment or spend

​Add operational guardrails

​Compose an Engine from Plays

​Next steps

Prebuilt Plays

SDK reference

​Verify this task

Discover a live contract before provider work

The authoring contract

Choose the runtime primitive

Validate before deployment or spend

Add operational guardrails

Compose an Engine from Plays

Next steps

Verify this task