602 - The agent writes the first script

• 601Do not spend AI on what a script can doThe automation gap, what integration platforms and laptop scripts each cost, and the division of labor: a script for the deterministic part, the model for writing it and for judgment.
• 602The agent writes the first scriptThe loop from create to save, what validate and a dry run report, the dialect’s deliberate absences, the traps that fail a draft, and the script’s page in the portal.
• 603Outputs: feeds, reports, and dashboards that refresh themselvesOutput identity across runs, tables and documents, the semi-dynamic dashboard and its data region, the referencing pattern, version caps, and delivery to a bucket drop.
• 604Running it: by hand, from the portal, and on a scheduleThree triggers, the cadence builder, the pinned fire date, what a schedule guarantees, and the run history with every trigger, duration, output, and log.
• 605What a run may do, and the record it leavesThe authority a run carries, what a save refuses, why the language cannot reach out, the lifecycle, ownership and transfer, and the administrator’s view.
• 606Scripts as skills: the weekly review the agent runs on your businessThree scripts attached to one prompt, the agent running them and reading the outputs against the knowledge graph, and a weekly list of action items with the figures behind them.

• platform.query, platform.export, platform.publish_data, platform.call

  The four capabilities. Read-only SQL with :name parameters, a named output, a data-region refresh, and any other Plexara tool by name.

  import

  There is no module system. json and date are already here.

• json, date, sum, and the builtins

  json.encode and decode; date.of, add_days, add_months, start_of_month and the rest, all as YYYY-MM-DD strings; len, range, sorted, min, max, str, int, float, fail, and the string, list, and dict methods.

  try / except

  Errors fail the run by design, so the failure is recorded rather than swallowed. Check first, or call fail("why").

• run.run_id, run.fire_time, run.params

  The frozen run record. The fire time is the only clock a script has, so a re-run months later asks the same question.

  while, recursion

  Unbounded loops are off so a script’s cost is readable from its source. Loop over a list, or do it in SQL.

• print(...)

  Goes to the run log, which is kept with the run and capped at 64 KB.

  f"...", class

  Use "{}".format(x) or "%s" % x. Use dicts for structured values and functions for behavior.

• def, for, if, list comprehensions

  Ordinary functions and bounded loops. A sort key is a named function, since there is no lambda.

  datetime, now(), random

  There is no clock and no randomness. Reading one would make the run unreproducible.

• A named connection

  A script names the connection it queries; Plexara holds the credentials and authorizes each call.

  open, requests, credentials

  There is no filesystem and no direct network. The platform is the only outside world a script has. A credential never goes in the source.

month_start = date.start_of_month(run.params["month"])
month_end = date.add_months(month_start, 1)
conn = run.params["conn"]
print("supplier margin review for %s to %s" % (month_start, month_end))

NOV = """
WITH sold AS (
  SELECT ti.product_id, SUM(ti.quantity) AS units
  FROM warehouse.public.transaction_items ti
  JOIN warehouse.public.transactions t ON t.transaction_id = ti.transaction_id
  WHERE t.transaction_date >= CAST(DATE :start AS TIMESTAMP)
    AND t.transaction_date < CAST(DATE :end AS TIMESTAMP)
  GROUP BY ti.product_id
)
"""

categories = platform.query(
    connection = conn,
    sql = NOV + """
SELECT c.category_name AS category, c.department, COUNT(*) AS quoted_products, SUM(s2.units) AS units,
  ROUND(SUM(s2.units * p.cost), 2) AS cost_of_record,
  ROUND(SUM(s2.units * CAST(s.unit_cost AS DECIMAL(10,2))), 2) AS quoted_cost,
  ROUND(100.0 * (SUM(s2.units * CAST(s.unit_cost AS DECIMAL(10,2))) - SUM(s2.units * p.cost))
        / SUM(s2.units * p.cost), 1) AS cost_change_pct,
  ROUND(100.0 * (SUM(s2.units * p.price) - SUM(s2.units * CAST(s.unit_cost AS DECIMAL(10,2))))
        / SUM(s2.units * p.price), 1) AS margin_projected_pct
FROM scratch.uploads.admin_supplier_price_sheet s
JOIN warehouse.public.products p ON p.sku = s.sku
JOIN warehouse.public.categories c ON c.category_id = p.category_id
JOIN sold s2 ON s2.product_id = p.product_id
GROUP BY c.category_name, c.department
ORDER BY cost_change_pct DESC
""",
    params = {"start": month_start, "end": month_end},
)

at_risk = platform.query(connection = conn, sql = NOV + AT_RISK_SQL,
                         params = {"start": month_start, "end": month_end})
coverage = platform.query(connection = conn, sql = NOV + COVERAGE_SQL,
                          params = {"start": month_start, "end": month_end})

cat_rows = categories["rows"]
if len(cat_rows) == 0:
    fail("no sales joined to the price sheet for %s; nothing to publish" % month_start)

cov = coverage["rows"][0]
total_record = sum([float(r["cost_of_record"]) for r in cat_rows])
total_quoted = sum([float(r["quoted_cost"]) for r in cat_rows])
weighted_change = 100.0 * (total_quoted - total_record) / total_record

def by_change(r):
    return -float(r["cost_change_pct"])

movers = sorted(cat_rows, key = by_change)
print("categories quoted: %d, weighted cost change %s%%" % (len(cat_rows), int(weighted_change * 100) / 100.0))
print("largest increase: %s %s%%" % (movers[0]["category"], movers[0]["cost_change_pct"]))

platform.export(name = "supplier-margin-by-category", rows = cat_rows, format = "csv")
platform.export(
    name = "supplier-margin-feed",
    rows = [{"as_of": run.fire_time, "month": month_start, "coverage": cov,
             "categories": cat_rows, "at_risk": at_risk["rows"]}],
    format = "json",
)

month

date, default 2025-11-01

Any date inside the calendar month to report on. The script takes the start of that month and the month after it, so a schedule can bind the fire date and get the right month.

conn

connection, default acme

A connection parameter binds as a string, but every surface that asks for it offers the connections this script may reach instead of a blank box, and a name outside them is refused where it was entered.

1. 1

   Create

   The agent saves a first version with its parameters, a display name, a category, tags, and a markdown description. The answer says it already runs, and points at run_draft for iterating before the next save.

2. 2

   Validate

   A static read of the source. It reports the two capabilities used, the destination (portal), no tools called by name, and that the connection is computed from a parameter, so the connection list is incomplete. Nothing runs.

3. 3

   Dry run, fails

   Executed as the author with nothing persisted. Three queries ran, 1,705 steps, 6.1 seconds, then line 92: unknown conversion, because the print used a %.2f format the dialect does not have.

4. 4

   Patch

   One anchored edit replaces the format with "%s" and an integer rounding. Version 2, and the answer says this version is what runs now.

5. 5

   Dry run, fails again

   The CSV export was measured (50 rows, 3,378 bytes) before line 103 refused the JSON export: rows must be a list of dicts, and the feed was a dict.

6. 6

   Patch

   The feed is wrapped in a list. Version 3.

7. 7

   Dry run, succeeds

   Three queries, 1,807 steps, 5.1 seconds, two outputs measured and nothing written: the CSV at 50 rows and 3,378 bytes, the JSON feed at 27,626 bytes. The log shows 50 categories quoted and 400 of 450 products covered.

8. 8

   The saved version runs

   Version 3 is what run_script executes and what a schedule fires. The first real run, for December, wrote both outputs as versioned assets in 8.5 seconds.

manage_script command=create  name=acme-supplier-margin
  params=[month: date (default 2025-11-01), conn: connection (default acme)]
  display_name="Supplier Quote Margin Review"  category=merchandising
→ status created   version 1
  "Saved, and it runs: run_script executes it under the access you held
   when you saved it, and a schedule you set will fire it. Use run_draft
   to iterate on changes before saving them."

manage_script command=validate  name=acme-supplier-margin
→ ok true   capabilities [platform.export, platform.query]   destinations [portal]
  connections []   dynamic_connections true   tools []   findings null
  "At least one call computes its connection instead of naming one ...
   so this connection list is incomplete."

manage_script command=run_draft  name=acme-supplier-margin  args={month: 2025-11-01}
→ status failed   queries 3   steps 1705   duration 6,105 ms   run dpx_0107…
  acme-supplier-margin:92:60: Error: unknown conversion %.
  "A script failure is deterministic: the same source on the same inputs
   fails the same way, so retrying it changes nothing."

manage_script command=patch  edits=[replace "%.2f%%" → "%s%%" with int(x * 100) / 100.0]
→ version 2   "Saved, and this version is what runs now"

manage_script command=run_draft
→ status failed   exports [supplier-margin-by-category csv 50 rows 3,378 bytes preview]
  acme-supplier-margin:103:16: Error in platform.export: rows must be a list
  of dicts, or a string body for a document format, got dict

manage_script command=patch  edits=[wrap the feed: rows = [{...}]]
→ version 3

manage_script command=run_draft
→ status succeeded   queries 3   steps 1807   duration 5,111 ms   run dpx_6e26…
  exports  supplier-margin-by-category  csv   50 rows   3,378 bytes   preview
           supplier-margin-feed         json   1 row   27,626 bytes   preview
  "Nothing was persisted. platform.export reported the shape of each
   output rather than writing it."

capabilities

platform.export, platform.query

Which of the four helpers the source uses. A script that only queries and exports can never refresh a dashboard or call another tool without a new version.

connections

[] with dynamic_connections true

The connections named literally in the source. This script takes its connection from a parameter, so validate says the list is incomplete instead of guessing.

destinations

portal

Where the outputs go. A destination Plexara does not have is reported here, before any query has run.

tools

[]

Every tool named in a platform.call. A computed tool name is reported as a gap rather than left out.

findings

null

Anything the static read objects to, with a correction for each: a credential-shaped literal, source that does not parse, a destination passed by position.

Executed as you

A dry run is your own session: your identity, your access, and nothing reachable through it that you could not already reach. A real run executes as the script, presenting the roles you held at the save.

Nothing persisted

Every export is serialized in its declared format to measure it, then discarded. The answer carries the shape and size a real run would write; no asset is versioned.

Tighter limits

A draft is capped at 5,000 rows per query and one minute. A platform run allows 20,000 rows per query, ten minutes, 16 outputs, and 100 MB per output. A source is at most 256 KB.

The account it keeps

Each dry run is recorded: who ran it, when, how it ended, what it printed, and the shape of its outputs. The account is keyed to the exact source that executed, so the version later saved from that source carries it, and a version with no account says so.

Display name

The label every listing, page header, and search result prints. Supplier Quote Margin Review, here.

Description

A markdown document, not a caption: what the script produces, what each parameter means in the reader’s terms, what it assumes about the data, and what somebody re-reading it in six months needs. This one states the three queries, the two outputs, the cast rule, and that a month with no sales fails the run.

Category

One lowercase slug the listings filter on. Reuse an existing one rather than coining a near-duplicate; merchandising, here.

Tags

Free-form labels, up to twenty, for everything one category cannot carry.

A DECIMAL arrives as text

Arithmetic on a cost column refuses, or a sum concatenates strings.

Pass every DECIMAL through float() before arithmetic: sum([float(r["total"]) for r in rows]).

A result hits the row cap

The query fails rather than returning a partial answer.

Aggregate in SQL or narrow the query. A partial result would silently change what the script computes.

SQL built by hand

One apostrophe in an upstream value breaks the statement, or appends one of its own.

Use :name placeholders and pass values in params; the platform quotes them by type. Compare a date as DATE :day.

A format the dialect does not have

Error: unknown conversion %. at the print line.

There is no %.2f. Use "%s" with int(x * 100) / 100.0, or "{}".format(x).

A JSON export given a dict

rows must be a list of dicts, or a string body for a document format, got dict.

Wrap the feed in a list. csv and json take rows; html and jsx take a string body.

One name written twice in a run

output "…" was already written to "portal" by this run.

One output name lands once per destination per run. Give the second write its own name, or branch so only one write happens.