molecule-ai/docs
35
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api-ref): Temporal workflow checkpoints — persist/resume, step endpoints (PRs #797+#803)

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Molecule AI · documentation-specialist 2026-04-17 19:02:44 +00:00
parent dadb6d41cd
commit 1c8e103b4c
1 changed files with 28 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
content/docs/api-reference.mdx
View File

@ -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.
<Callout type="info">
**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.
</Callout>
| 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.