Design & Extend · Hybrid
Workflow Canvas, YAML & TypeScript
Design governed human-and-agent workflows visually, validate structural invariants, and round-trip canonical YAML and TypeScript.
Status: Available Architecture: O1 · Orchestration Read: 5 min Verified: 2026-11-16
Visualizer, YAML, and TypeScript
Workflow Canvas gives operators and engineers one shared contract across three synchronized representations in AgentSpace Processes:
- Visualizer: Interactive DAG layout displaying participant roles, required evidence badges, and conditional branches.
- Canonical YAML: Strict, deterministic schema (
version: 1) suitable for pull-request review and portable templates. - Generated TypeScript: Read-only module using
defineCompanyWorkflowthat strips non-executable canvas notes cleanly.
Supported node and branch types
| Node kind | Owner requirement | Behavioral contract |
|---|---|---|
start | null | Single workflow entrypoint defining trigger conditions. |
agent | agent | Bounded AI execution step with declared evidence outputs. |
human | person | Explicit human review, editing, or Decision Gate sign-off step. |
condition | Optional | Deterministic branch router emitting true, false, or error edges. |
action | service / agent | Scoped connector call governed by Exchange read/write policy. |
end | null | Terminal outcome node recording final evidence state. |
note | null | Documentation annotation preserved in YAML but omitted from generated TypeScript. |
Canonical YAML contract
version: 1
nodes:
- id: intake
kind: start
title: Question received
description: Scoped question from approved team channel
position: { x: 80, y: 140 }
ownerKind: null
evidenceTypes: []
condition: null
- id: retrieve
kind: agent
title: Retrieve cited sources
description: Rank approved knowledge documents
position: { x: 340, y: 140 }
ownerKind: agent
evidenceTypes: [source-citations, eval-score]
condition: null
- id: approve
kind: human
title: Owner sign-off
description: Verify citations before publishing answer
position: { x: 600, y: 140 }
ownerKind: person
evidenceTypes: [approval-note]
condition: null
- id: complete
kind: end
title: Answer published
description: Verified response archived with evidence
position: { x: 860, y: 140 }
ownerKind: null
evidenceTypes: []
condition: null
edges:
- { id: e1, source: intake, target: retrieve, label: null, branch: default }
- { id: e2, source: retrieve, target: approve, label: Citations ready, branch: default }
- { id: e3, source: approve, target: complete, label: Approved, branch: true } import { defineCompanyWorkflow } from '@frootai/agentspace';
export default defineCompanyWorkflow({
id: "prc-knowledge-answer",
version: 1,
nodes: {
"intake": { kind: "start", title: "Question received", owner: null, evidence: [], condition: null },
"retrieve": { kind: "agent", title: "Retrieve cited sources", owner: "agent", evidence: ["source-citations", "eval-score"], condition: null },
"approve": { kind: "human", title: "Owner sign-off", owner: "person", evidence: ["approval-note"], condition: null },
"complete": { kind: "end", title: "Answer published", owner: null, evidence: [], condition: null },
},
transitions: [
{ from: "intake", to: "retrieve", branch: "default", label: null },
{ from: "retrieve", to: "approve", branch: "default", label: "Citations ready" },
{ from: "approve", to: "complete", branch: "true", label: "Approved" },
],
}); Graph validation & non-destructive forks
parseWorkflowYamlvalidates both strict Zod field types and structural graph invariants (start/end presence, valid node references, reachable paths).- Invalid YAML edits surface exact field paths without corrupting the last valid visual graph.
- Editing an active workflow or importing a Hub blueprint creates a versioned draft fork so in-flight Workstream items keep their bound workflow version.
tests/backend/workflow-contract.test.ts