Flow Spec v1
The portable workflow contract shared by visual, code and agent authoring.
Blocchi Flow Spec v1 is the portable representation of a workflow.
The contract intentionally excludes tenant ID, workflow revision and lifecycle state. Those are platform-owned fields.
executionMode is workflow-level interaction policy, not an Agent permission. agent-driven is the backward-compatible default. guided pauses after each Agent reasoning step for human continuation while preserving all independent Governed Action approval rules.
Generated Guided checkpoints are runtime implementation details. Visual authoring, Flow-as-code and MCP return the portable graph without those generated Approval nodes.
Limits in v1
- Name: 1–200 characters.
- Description: up to 2,000 characters.
- Execution mode:
guidedoragent-driven. - Nodes: 1–200.
- Edges: up to 500.
- Unknown top-level fields are rejected.
One schema
Visual authoring, Flow-as-code and agent-created flows round-trip through this same contract. If a feature cannot be represented safely in Flow Spec, it should not create a second hidden workflow language.
Human-owned MCP clients can use blocchi.list_workflows, blocchi.get_workflow, blocchi.create_workflow and blocchi.save_workflow_revision. Create/save use the exact Flow Spec v1 contract, including executionMode, and create immutable draft revisions through the same workflow service as the product UI. Activation remains a separate human governance step.
Workflow persistence currently records authorship against a human user profile. For that reason, these authoring MCP tools are intentionally unavailable to service actors rather than impersonating a human author.
Monitoring execution (preview)
The visual editor defines a workflow; Activity is where operators can inspect what actually executed. The execution Control Room view (draft PR #987) uses the exact immutable revision pinned to the run, the current node, and its event history. Step bubbles reuse the Blocchi Views experience and link to the existing run details and Human Work. The authoring graph remains the source of branch/loop/dependency topology: the execution overview deliberately does not draw false linear connections between nodes.
The Automation page offers a separate, admin-scoped Control Room for recent Agent operating runs and a selected run's active plan revision. A completed step does not imply verified business impact or advance a sales stage. Both visualizations are read-only and do not create a second Workflow runtime.
Existing GET /v1/ecosystem/operating-runs/{runId} and
blocchi.get_agent_run keep their Automation Identity-scoped read contract.
This visualization adds no generic run-writing API or MCP command. PR #987
requires local/browser certification before this experience is considered
released.
Last updated on