Orchestrating Workflows with BisenseFlow & Weaver

Agent Orchestration•Difficulty: Advanced•Time to Implement: 2–4 hours

Who This Guide Is For

Staff engineers, architects, and technical founders standardizing how their org builds on BisenseAI. You need a repeatable pattern for binding UI to agentic backends without API contract drift.

Prerequisites

BisenseAI workspace with BisenseFlow (backend logic canvas) and Weaver Studio (frontend canvas)
LLM and integration API keys stored in the BisenseAI secrets panel—not in node text
Sample inputs prepared that mirror production shape, size, and failure modes
Familiarity with workflow I/O binding and the interactive playground
Optional: LangSmith or LangFuse project for traces, cost, and latency dashboards
Optional: Composio account if the guide uses OAuth SaaS nodes (Slack, GitHub, GA4, etc.)

Key Outcomes

→Documented I/O contract between Weaver and BisenseFlow
→End-to-end time-travel replay from UI event to node outputs
→Same workflow version deployed to REST and MCP surfaces
→Control-flow patterns for HITL, loops, and parallel macros
→Observability baseline with LangSmith/LangFuse

Core Challenge

Backend-only workflow tools cannot ship end-user products; frontend-only builders lack real agent logic.

Teams duplicate business rules in React and Python, then spend weeks debugging mismatched JSON field names.

BisenseAI's dual canvas exists so one runtime powers UI and logic with shared versioning and debugging.

Teams stitching separate UI and orchestration codebases lose observability and ship brittle demos. 2025-2026 production platforms unify BisenseFlow graphs and Weaver experience with shared I/O contracts, LangGraph-style checkpointed HITL, macro subgraph reuse, and correlated LangSmith traces—one deploy boundary for API, MCP, and human operators.

What You Will Build

Reference project: Weaver app with forms/results; BisenseFlow graph with LLM/Agent/integrations; explicit I/O manifest checked in CI.

Deploy panel publishes API + optional MCP; documentation auto-lists tool schemas from workflow metadata.

Platform Architecture on BisenseAI

BisenseFlow: Input/Output, LLM, Agent, Vector Store, HTTP, Composio, Playwright, control flow.

Weaver: App, Macro, Trigger, Logic nodes; React import; AI-assisted linking.

┌──────────────── Weaver ────────────────┐
│ App / Logic / Trigger nodes             │
└───────────────┬────────────────────────┘
                │ I/O contract
┌───────────────▼────────────────────────┐
│ BisenseFlow: agents + integrations      │
└───────────────┬────────────────────────┘
                ▼ Deploy: REST · MCP · hosted UI

Shared I/O contract

Single manifest: input ports, output ports, types, examples. CI fails if Weaver binding references removed ports.

Time-travel across layers

Replay shows UI payload → each backend node. Pinpoints whether bug is binding or business logic.

Atomic version deploy

Tag v1.4.0 publishes Flow + Weaver together. Rollback restores both canvases.

MCP and REST parity

Same graph serves web users and Claude Desktop tools. No second codebase for integrations.

Backend Logic Canvas (BisenseFlow)

Define Input/Output ports with JSON Schema
Core processing subgraph (LLM/Agent/tools)
Control flow: branches, loops, macros
HITL interrupt + webhook resume
JSON Output standardized envelope
LangSmith/LangFuse tracing
Deploy REST routes
Deploy MCP server manifest
Rate limit + auth at gateway
Error taxonomy Logic nodes

Frontend Canvas (Weaver Studio)

App Nodes for primary forms and results panels
Logic Nodes for loading, empty, validation, and error UI states
I/O bindings verified with AI-assisted linking suggestions
Real-time execution status during long-running workflows
Time-travel debug entry for internal support roles
Playground embed or staging route for QA sign-off
Optional React import for brand-specific layout
Environment-specific API base URL configuration
Streaming bindings where LLM or media outputs stream
Admin vs end-user route separation where applicable

Node Configuration Reference

Workflow I/O manifest

Document every port in project README generated from canvas.

Include example payloads.

Agent

max_tool_calls; tool descriptions; subgraph per tool.

Never one mega-agent.

HITL interrupt

Persist state; expose approval_id to Weaver.

Resume via signed webhook.

Where logic belongs

Authorization, payments, PII, and agent tools always on BisenseFlow. Weaver handles presentation state only—tabs, modals, client validation for UX.

Enterprise governance

RBAC on workflow edit vs run. Audit log exports node outputs hash for regulated industries.

I/O contract versioning between canvases

Document every workflow input and output port in OpenAPI-style schema checked into repo. Weaver AI-assisted linking reads schema; breaking field renames require major version bump. JSON Output node fields (status, data, error_code, job_id) must remain stable across minor versions for mobile clients and MCP consumers sharing same API.

Contract tests: playground fixtures assert schema; Weaver E2E tests mock API responses matching same schema.

Latest Research & Industry Context (2025–2026)

Dual-canvas orchestration patterns

BisenseFlow plus Weaver dual-canvas architecture mirrors 2025 enterprise MLOps split: backend graph owns deterministic I/O, retries, and integrations; frontend canvas owns user experience and HITL gates. LangGraph 1.2 durable execution influenced BisenseFlow checkpoint semantics—long workflows survive worker restarts when state is externalized. Anti-pattern: duplicating business logic in Weaver JavaScript and BisenseFlow nodes. Single source of truth stays on backend; Weaver binds ports only.

Macro nodes and subgraphs (2025 BisenseFlow) encapsulate reusable pipelines—ingest, QA, publish—so dual-canvas projects compose without copy-paste. Version macros independently from parent workflow.

Sources: LangGraph 1.2 documentation · BisenseAI product architecture

Observability across canvas boundary

LangSmith and LangFuse traces must include correlation_id shared between Weaver session and BisenseFlow execution. Support tickets reference one ID to replay time-travel on backend while inspecting UI state snapshot. Weaver real-time execution streams should map backend node names to user-friendly step labels defined in workflow metadata JSON—not raw internal node UUIDs.

Deploy alignment: publish backend workflow version tag before Weaver production deploy. Mismatch causes I/O port binding errors that playground catches if regression fixtures run in CI.

Step-by-Step: Build in BisenseAI

1
Sketch user journey
Inputs user provides; outputs they see; error cases.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
2
Implement BisenseFlow first
Truth layer; expose minimal I/O.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
3
Compose Weaver UI
Bind fields; loading/error states.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
4
AI-assisted linking review
Accept suggestions; verify in playground.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
5
Time-travel E2E test
Three scenarios including failure paths.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
6
Publish version tag
Atomic deploy Flow + Weaver.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
7
Enable MCP optional
Generate Claude Desktop config snippet.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
8
Observability dashboards
Latency per node; cost per tenant.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
9
Document I/O manifest
For API consumers and QA.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
10
Load test critical path
Rate limits; queue long jobs.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
11
Runbook
Rollback; provider outages.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.
12
Production checklist
Sign off all items.
Validate this step in the BisenseAI playground with time-travel debugging enabled. Confirm I/O bindings on Weaver match backend port names before publishing the workflow.

Production Checklist

Every branch exercised in playground with time-travel debugging on representative inputs
Secrets rotated and scoped per environment (dev/staging/prod) in BisenseAI vault
LangSmith/LangFuse traces tagged with tenant_id and workflow version
Structured JSON errors returned for UI and API consumers—not raw stack traces
Rate limits and max_steps/TTL configured on agents and loops
Weaver deploy version pinned to matching BisenseFlow workflow publish
PII/toxicity guards on user inputs before expensive media or LLM nodes
Webhook/async jobs use idempotency keys to prevent duplicate side effects
Production smoke test documented with rollback steps
Runbook links provider status pages for each external integration
Cost estimate recorded for LLM, embedding, and media nodes at target volume
On-call alert thresholds set for error rate and p95 latency per critical node

Common Pitfalls

Business logic in Weaver

Moves to React-only; breaks MCP/API parity.

Drifted I/O versions

Deploy Weaver without matching Flow version.

Skipping HITL for destructive tools

Always interrupt before payments/sends.

No tracing

Cannot debug multi-node failures in prod.

God agent

Split tools; use router agent.

Frequently Asked Questions

What belongs on BisenseFlow versus Weaver?

BisenseFlow: LLM, Agent, HTTP, Composio, Vector Store, control flow, secrets, webhooks, deploy surfaces. Weaver: forms, App Nodes, approval UI, streaming display, auth gates. Never call LLM providers directly from Weaver client code—always through deployed workflow API.

How do I sync workflow versions between canvases?

Tag each backend publish with semver or git sha. Weaver environment config points api_base_url/workflow_id/version. CI fails if Weaver deploy references unpublished workflow tag.

Can one BisenseFlow workflow power multiple Weaver apps?

Yes—deploy one REST API with tenant_id input; multiple Weaver projects bind different UI layouts to same ports. Useful for white-label products.

How does HITL work across the canvas boundary?

BisenseFlow pauses at HITL interrupt node; stores checkpoint. Weaver approval button calls resume API with decision payload. Graph continues from checkpoint—not from start.

What tracing setup is recommended for dual-canvas apps?

Enable LangSmith on all BisenseFlow workflows. Pass weaver_session_id into first node as metadata. Dashboard filter by session links UI recording to backend spans.

How do subgraphs help dual-canvas maintenance?

Extract ingest, QA, and publish into macro subgraphs with documented I/O. Parent workflow on BisenseFlow stays readable; macros version independently. Weaver unchanged when macro internals update if ports stable.

Architect on the dual canvas

BisenseFlow + Weaver is core BisenseAI.

Enterprise Architecture Call