From 1c8e103b4cb237b97684e8f429b8a2275f798136 Mon Sep 17 00:00:00 2001 From: Molecule AI Documentation Specialist Date: Fri, 17 Apr 2026 19:02:44 +0000 Subject: [PATCH] =?UTF-8?q?docs(api-ref):=20Temporal=20workflow=20checkpoi?= =?UTF-8?q?nts=20=E2=80=94=20persist/resume,=20step=20endpoints=20(PRs=20#?= =?UTF-8?q?797+#803)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add '## Workflow Checkpoints' section to api-reference.mdx: - POST /workspaces/:id/checkpoints — upsert step checkpoint (ON CONFLICT safe) - GET /workspaces/:id/checkpoints/:wfid — list checkpoints by workflow ID - DELETE /workspaces/:id/checkpoints/:wfid — clear on clean completion - Callout explaining automatic resume behavior (runtime: langgraph only): checkpoint I/O is non-fatal, resume skips already-completed stages - Step names/indices table (task_receive=0, llm_call=1, task_complete=2) Pairs with monorepo PR #797 (persistence layer) + PR #803 (workspace-template auto-save/resume). Section placed after Activity, before Schedules. Co-Authored-By: Claude Sonnet 4.6 --- content/docs/api-reference.mdx | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/content/docs/api-reference.mdx b/content/docs/api-reference.mdx index adde987..6f84729 100644 --- a/content/docs/api-reference.mdx +++ b/content/docs/api-reference.mdx @@ -212,6 +212,34 @@ Activity logging and search for A2A communications, task updates, and agent logs --- +## Workflow Checkpoints + +Step-level progress persistence for long-running Temporal workflows. Workspaces with `runtime: langgraph` (Temporal) automatically save a checkpoint after each of the three workflow stages (`task_receive`, `llm_call`, `task_complete`) and resume from the last completed stage on restart. + + + **Automatic resume behavior (runtime: langgraph only)** + + When a Temporal workspace restarts mid-workflow, the runtime reads the highest-index checkpoint and sets `resume_from_step` accordingly. Already-completed stages are skipped — the agent picks up exactly where it left off without re-running earlier steps. + + Checkpoint I/O is non-fatal: network errors are silently swallowed. A crashed or unreachable platform never prevents the agent from running. + + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| POST | `/workspaces/:id/checkpoints` | WorkspaceAuth | Upsert a step checkpoint. Body: `{ "workflow_id": "...", "step_name": "task_receive\|llm_call\|task_complete", "step_index": 0, "payload": {...} }`. Uses `ON CONFLICT DO UPDATE` — safe to call multiple times. | +| GET | `/workspaces/:id/checkpoints/:wfid` | WorkspaceAuth | Return all checkpoints for a workflow, ordered by `step_index DESC`. Returns 404 if no checkpoints exist for the workflow. | +| DELETE | `/workspaces/:id/checkpoints/:wfid` | WorkspaceAuth | Clear all checkpoints for a workflow. Called by the runtime on clean task completion. Returns 404 if none exist. | + +**Step names and indices:** + +| Step | `step_index` | Meaning | +|------|-------------|---------| +| `task_receive` | 0 | Task received from A2A message | +| `llm_call` | 1 | LLM inference completed | +| `task_complete` | 2 | Task result sent back to caller | + +--- + ## Schedules Cron-based scheduled tasks per workspace.