Skip to main content

The workspace Snapshot

The workspace_snapshot is the one snapshot Circus itself doesn't define — it's built by the plugin for the specific piece of work your run is processing. Where the other three snapshots carry configuration, this one carries domain content: the actual thing your workflow is meant to act on.

It varies by plugin​

Because a plugin decides what goes in it (via its workspace snapshot provider), the exact fields depend on the plugin you're building workflows for. There's no fixed schema here — you read whatever the plugin puts in — so it's worth checking that plugin's own documentation or its snapshot provider to know the shape.

The default plugin's example​

The default plugin gives a concrete picture of the idea. Its workspace snapshot typically includes:

  • the title and description of the Thing (the operator's brief);
  • the current generated text, if a previous workflow produced any;
  • the operator's input / feedback, if they've provided any;
  • the workspace's current status.

So a News Generator workflow reads the title and description to know what story to write; a News Revision workflow reads the current text plus the operator's feedback to know what to change. The workspace snapshot is how the operator's specific request — "write about the wrens in the watering can" — reaches your workflow.

Reading it​

You read the workspace snapshot the same way as the others — off the Init node's output — and it's a natural source for the Agent node's input field (the work item to process). If you're building for a custom plugin, treat its workspace snapshot as the contract between the plugin and your workflows: whatever domain context your steps need, that's where it should arrive.