SDK Overview

Two packages, one surface

Your first script

A workflow script is a single file uploaded to the task slot. Export a run entry point, report progress, return a result:

def run(params: dict, reporter) -> None:
    reporter.set_phase("Summarize")

    summary = summarize(params["text"])
    reporter.set_progress(80)
    return {"summary": summary}

export async function run(params: Record<string, unknown>, reporter) {
  reporter.setPhase("Summarize");

  const summary = await summarize(params.text);
  reporter.setProgress(80);
  return { summary };

Two calling conventions

• Function-based (recommended) — export run(params, reporter); the starter entry calls it and prints the returned dict as the result.
• Module-level — top-level side effects run at import time; background-service scripts define on_change(mutation, state) instead.

What the workflow module injects

Before your script runs, the workflow module materializes into the task slot with preconfigured helpers and the injected environment — TASK_ID, PROJECT_ID, TASK_JWT, ALLYBUILD_API_URL, parsed params, and project_status. The full name list lives in the Workflow module page.

Where to go next

• Workflow module — module-level names and conventions for workflow.py / workflow.ts
• Tasks API — spawn, await, orchestrate tasks, and answer approval gates
• Memories — list and semantically search the memories runs deposit
• Knowledge base — search and lint the project’s OKF knowledge base
• MCP — call tools exposed by project MCP servers
• Reactive state — typed reactive state, optionally persisted across runs