Skip to content

FAQ

See also: ../README.md, getting-started.md, api.md, architecture.md.

What is AbstractFlow?

AbstractFlow is a Python library for defining and executing durable AI workflows: - Programmatic graphs (Flow + FlowRunner) - Portable visual workflows (VisualFlow JSON) that can run outside the editor

Evidence: ../abstractflow/runner.py, ../abstractflow/visual/models.py, ../abstractflow/visual/executor.py.

Is AbstractFlow production-ready?

Not yet. The package is marked Pre-alpha and may introduce breaking changes.

Evidence: ../pyproject.toml (Development Status :: 2 - Pre-Alpha).

What’s the difference between Flow and VisualFlow?

  • Flow: programmatic flow IR (re-exported from AbstractRuntime) used by FlowRunner.
  • Flow requires abstractflow[apple].
  • VisualFlow: portable JSON authoring format (Pydantic models) produced by the web editor and runnable from any host.

Evidence: ../abstractflow/core/flow.py, ../abstractflow/visual/models.py, ../abstractflow/runner.py.

Can I execute a VisualFlow JSON without running the web editor?

Yes. Load the JSON into VisualFlow and run it with abstractflow.visual.execute_visual_flow(...) (or build a runner with create_visual_runner(...) if you need access to the runtime/run state). This requires the runtime stack with pip install "abstractflow[apple]". Agent-node features are included in abstractflow[apple] and abstractflow[gpu]; use abstractflow[agent] only when you need Agent nodes without a host profile.

Evidence: ../abstractflow/visual/executor.py.

How do subflows work?

Subflows are VisualFlows referenced by id from nodes of type subflow: - node.data["subflowId"] (legacy: flowId)

When executing, you must provide a mapping of all flows by id: flows={flow_id: VisualFlow, ...}.

Evidence: ../abstractflow/visual/executor.py, visualflow.md.

How do “waiting” runs work? How do I resume?

Some nodes intentionally block on external input (e.g. user/event/schedule waits). - FlowRunner.run() returns {"waiting": True, ...} when blocked. - The web editor resumes blocked runs over WebSocket (type:"resume").

Evidence: ../abstractflow/runner.py, ../web/backend/routes/ws.py, web-editor.md.

How do custom events work in VisualFlow?

For VisualFlows, VisualSessionRunner starts on_event listeners as child runs in the same session and ticks them so emit_event branches progress.

Evidence: ../abstractflow/visual/session_runner.py, wiring in ../abstractflow/visual/executor.py.

Does pip install abstractflow include the web editor UI?

Not the UI. The visual editor has two parts: - Backend (FastAPI): included when you install a host profile (abstractflow[apple] or abstractflow[gpu]) and runnable via abstractflow serve. - UI (React): published as the npm package @abstractframework/flow (run via npx).

Evidence: ../pyproject.toml (host profile extras + project.scripts), ../abstractflow/cli.py, ../web/frontend/bin/cli.js.

Where does the web editor store flows and run data?

Defaults: - Flows: ./flows/*.json relative to the backend working directory (override with ABSTRACTFLOW_FLOWS_DIR). - Runtime persistence (runs/ledger/artifacts): - source checkout: web/runtime/ - installed package: ~/.abstractflow/runtime - override with ABSTRACTFLOW_RUNTIME_DIR.

Evidence: ../web/backend/routes/flows.py (FLOWS_DIR, ABSTRACTFLOW_FLOWS_DIR), ../web/backend/services/paths.py.

How does tool / file access work (security)?

The web backend creates a per-run workspace directory and wraps tool execution with workspace scoping: - Workspace base: ABSTRACTFLOW_BASE_EXECUTION (or /tmp / OS temp) - Workspace root is injected into input_data (workspace_root) and used to scope tools

Evidence: ../web/backend/services/execution_workspace.py, ../abstractflow/visual/workspace_scoped_tools.py, ../web/backend/routes/ws.py, ../web/backend/routes/flows.py.

How do tools work? How do I add more tools?

The editor backend exposes a conservative default tool set derived from AbstractRuntime’s AbstractCore integration.

To add or customize tools, you have a few host-level options:

  • Custom host (Python): build your own tool executor and pass it to create_visual_runner(...).
  • Gateway-backed editor: extend Gateway tool discovery and the Gateway/Runtime tool executor.
  • Compatibility FastAPI host: set ABSTRACTFLOW_ENABLE_LOCAL_RUNTIME=1, then extend the old tool discovery route (GET /api/tools) and the host tool executor used for local runs.
  • Upstream defaults: depending on your deployment, you may choose to replace/extend AbstractRuntime’s “default tools” selection.

Evidence: - Compatibility tool discovery endpoint: ../web/backend/routes/tools.py (GET /api/tools, only when ABSTRACTFLOW_ENABLE_LOCAL_RUNTIME=1) - Default tool executor wiring: ../abstractflow/visual/workspace_scoped_tools.py - Editor backend wiring: ../web/backend/routes/flows.py, ../web/backend/routes/ws.py - Run guide: web-editor.md

How do I package and share workflows?

Use WorkflowBundle (.flow): - CLI: abstractflow bundle pack|inspect|unpack - The bundle format and packer are owned by AbstractRuntime; AbstractFlow provides a thin wrapper.

Evidence: ../abstractflow/cli.py, ../abstractflow/workflow_bundle.py, tests in ../tests/test_workflow_bundle_pack.py.

Do I need an AbstractGateway?

For the modern browser editor, yes: Gateway is the runtime, persistence, discovery, ledger, and artifact authority. The editor calls same-origin /api/gateway/* through a Flow proxy so bearer auth stays server-side.

For local runtime use, install abstractflow[apple] and run with abstractflow.visual.execute_visual_flow(...) or create_visual_runner(...). The old FastAPI local runtime routes are compatibility-only and are gated by ABSTRACTFLOW_ENABLE_LOCAL_RUNTIME=1.

Evidence: ../web/frontend/src/utils/gatewayClient.ts, ../web/backend/main.py, ../abstractflow/visual/executor.py.

Why do I see pins in node.data.inputs/outputs instead of node.inputs/outputs?

Saved flows from the editor store pin metadata under node.data.inputs / node.data.outputs. The top-level inputs / outputs fields may exist but are often empty.

Evidence: ../abstractflow/visual/interfaces.py (_pin_types reads node.data.*), sample flows in ../web/flows/.

Where is the “compiler” implemented?

Compilation semantics live in AbstractRuntime’s VisualFlow compiler. This package delegates and re-exports: - abstractflow/compiler.py (compile functions) - abstractflow/adapters/* and abstractflow/visual/builtins.py (node adapters/builtins)

Evidence: ../abstractflow/compiler.py, ../abstractflow/adapters/, ../abstractflow/visual/builtins.py.