Skip to main content

How AutessaScript runs

The execution model: the autessa.* global, the ok/data/errors response envelope, dispatch guards (depth, budget, read-only, strict validation), and scripts calling scripts.

The decision: you are writing an AutessaScript. What can you rely on about how it runs, and how do you read the result of every autessa.* call?

The globals​

Every script runs with a globalThis.autessa object already in scope — the whole SDK tree, one function per method. You never import or construct it; autessa.agents.create({...}) is just there. Namespaces nest (autessa.autessadb.query.query), and a call takes a body object and an optional options argument.

The response contract: the ok/data/errors envelope​

Every autessa.* call returns an envelope, not a bare value:

const { ok, data, errors } = autessa.agents.create({ agentType: 'SIMPLE', agentName: 'Bot' });
if (ok) {
  console.log('created', data.agent.agentId);
} else {
  console.error('failed', errors);
}
  • ok is a boolean — always check it before using data.
  • data holds the response shape documented for that method (the response schema in its docs).
  • errors is a non-empty array of human-readable reason strings whenever ok is false — so errors (and errors[0]) always tells you what went wrong. It is absent on success.

A script's own final result follows the same idea: return the value you want the caller to receive; failures surface through the envelope rather than by throwing raw exceptions.

Dispatch guards​

Each autessa.* call passes a guard chain before it reaches the backing endpoint:

  1. Depth — a script may call other scripts/tools, which may call more; the runtime caps how deep that recursion can go, so a runaway call tree is stopped.
  2. Budget — there is a per-run ceiling on how many SDK calls a single run may make (a read-then-write counts as more than one). Exceeding it fails the call rather than the run spinning forever.
  3. Read-only policy — a run can be marked read-only; under it, any MUTATE-classified call is refused. Read calls still work. This is how a plan/preview run is kept side-effect-free.
  4. Strict validation — mutations are validated against the authored request shape, and an undeclared field is rejected rather than silently forwarded. The documented request schema is the contract; if a field isn't in the docs, it won't reach the endpoint.

Created-resource tracking and calling scripts from scripts​

  • When a run creates resources (a table, an agent, a row), the runtime tracks what was created, so a run's side effects are attributable.
  • Scripts can invoke other scripts and tools through the SDK; the depth and budget guards above govern that fan-out. Design chains to stay well within the caps — prefer a trigger chain (see the automations guide) over one script that recurses deeply.

Decision rules​

  1. Always destructure and check ok. Never use data before confirming ok is true.
  2. Send only documented fields on mutations. Strict validation rejects the rest.
  3. Mark preview runs read-only. Rely on the read-only policy to guarantee no writes during a dry run.
  4. Respect the budget. Batch where the SDK offers a batch method (e.g. autessa.autessadb.query.batchUpdate) instead of a call per row.

Worked example​

const { ok, data } = autessa.autessadb.query.query({ tableId: 'tbl_leads',
  whereGroups: [{ logicalOperator: 'AND', conditions: [
    { columnName: 'status', operator: 'EQUALS', value: 'new' } ] }], page: 1, pageSize: 50 });
if (!ok) return { processed: 0 };
// one batched write instead of one call per row — stays within the SDK budget
autessa.autessadb.query.batchUpdate({ tableId: 'tbl_leads',
  rowIds: data.rows.map(r => r.id), columnData: { status: { textValue: 'queued' } } });

See also​

  • agents-tools-managers — when to script directly versus configure an agent.
  • automations — trigger chains as the alternative to deep script recursion.