Task AI Python SDK

Public HTTP client for Task AI workflows and agents (/api/v1).

Gumloop equivalents: start_pipeline → start a workbook run; get_pl_run → poll status, log, and outputs.

Install

pip install phthos-task

Requires Python 3.11+.

Auth

1. In Task AI, open Settings → API keys and create a key (tai_…).
2. Enable scope v1:workflow:run to start or kill workflow runs.
3. Pass the key and your Task AI origin (the same host as the web app).

from phthos_task import TaskAI

client = TaskAI(
    api_key="tai_...",           # or TASK_AI_API_KEY
    base_url="https://tasks.example.com",  # or TASK_AI_BASE_URL
)

Local default base_url is http://localhost:3012.

Short runnable scripts: examples/.

Workflows (start_pipeline / get_pl_run)

from phthos_task import TaskAI

with TaskAI(api_key="tai_...", base_url="https://tasks.example.com") as client:
    flows = client.list_workflows()
    wb = flows[0]
    tab = wb.tabs[0]

    started = client.start_pipeline(wb.id, tab_id=tab.id, inputs={"input": "hello"})
    run = client.wait_for_run(started.run_id)
    print(run.state, run.outputs)

    # one-shot
    done = client.run_pipeline(wb.id, tab_id=tab.id, input="hello")

Named Start fields can be passed as kwargs (input="hello") or as inputs={...}. API runs use the tab’s live checkpoint (save/sync on the canvas first) — not unsaved editor state.

PipelineRun.state matches Gumloop: RUNNING, DONE, FAILED, TERMINATED.

status = client.get_pl_run(started.run_id)
client.kill_run(started.run_id)

Connected WORKFLOW tasks

Sync run of a child workflow task (already waits server-side):

result = client.run_workflow("task_...", inputs={"input": "hello"})
print(result.outputs)

Agents

started = client.start_agent("task_...", "Summarize yesterday's leads")
done = client.wait_for_agent(started.task_id, started.interaction_id)
print(done.response)

Agent start/status need v1:agent:start and v1:agent:read.

HTTP map

Develop

cd python
python -m pip install -e ".[dev]"
python -m ruff check src tests
python -m pytest
python -m build

PyPI: from the python/ directory, python -m build then upload (twine or the publish-pypi workflow).