FrootAI.dev AgentSpace
On this page 4
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 defineCompanyWorkflow that 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 }

Graph validation & non-destructive forks

  • parseWorkflowYaml validates 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.
Verified against repository suites
tests/backend/workflow-contract.test.ts
Markdown specification

Workflow Canvas, YAML & TypeScript