Basics & Reporter

Environment variables

These are injected automatically at startup:

Variable	Type	Description
TASK_ID	str	Current task-instance UUID
PROJECT_ID	str	Project UUID
TASK_JWT	str	Short-lived JWT for calling the TaskFlow API
TASKFLOW_API_URL	str	TaskFlow API base URL, e.g. http://localhost:8000/api
BG_SERVICE_ID	str	Non-empty when the script is triggered by a background service

params

params is a plain Python dict containing the parameters passed when the task was created, matching the task type's param_schema.

def run(params: dict, reporter) -> None:
    url = params["url"]              # required parameter
    depth = params.get("depth", 3)  # optional with default

reporter

reporter updates the task's current phase and progress, displayed in real time on the TaskFlow kanban.

def run(params: dict, reporter) -> None:
    reporter.set_phase("Fetching data")
    reporter.set_progress(10)
    # ...
    reporter.set_phase("Generating report")
    reporter.set_progress(80)
    reporter.set_progress(100)

reporter.set_phase(phase: str) -> None

Parameter	Type	Description
phase	str	Phase label shown in the UI

reporter.set_progress(pct: int) -> None

Parameter	Type	Description
pct	int	Progress percentage, 0–100

project_tokens

Read-only dict of tokens configured in the project settings (Settings → Tokens). Use it to store API keys and other secrets.

def run(params: dict, reporter) -> None:
    github_token = project_tokens.get("github_pat", "")
    openai_key = project_tokens["openai_api_key"]

Return value

The return value of run() is stored as the task's result and retrievable via wait_task() or the API.

def run(params: dict, reporter) -> dict:
    return {"summary": "...", "count": 42}

The return value must be JSON-serialisable (dict, list, str, int, float, bool, or None).