Flows

Visual node-based workflow builder with branching, retries, signed traces, and governance.

Flows is the visual, node-based workflow builder in OpenAgentic. You compose agentic workflows on a drag-and-drop canvas (built on React Flow), then run them on a dedicated execution engine that orchestrates LLM calls, MCP tools, control logic, code execution, and integrations.

Workflows are stored as JSON graph definitions (nodes plus edges) and executed by a graph-traversal engine that runs separately from the chat API, so long-running flows do not block chat and can scale independently. Flows reach the same nine built-in MCP servers that chat uses (aws, azure, gcp, kubernetes, prometheus, loki, github, admin, web), so a workflow can call cloud, Kubernetes, and observability tools through an mcp_tool node.

How flows differ from chat

Chat and Flows share infrastructure but serve different execution models.

Both use the same MCP tool ecosystem, the same provider abstraction (Ollama, Anthropic, OpenAI, Azure OpenAI, Vertex AI, AWS Bedrock), and the same Milvus vector store. A flow can call chat through the openagentic_chat node. Chat cannot yet invoke flows as tools; that direction is a planned feature.

Nodes and edges

A flow is a set of nodes joined by edges. Every node is schema-driven: a schema.json declares its type, ports, settings, and output assertions, and an executor.ts runs it. This keeps the canvas consistent, since every node configures the same way. The engine ships 73 node types across the following categories:

• Triggers: the trigger node (manual, webhook, schedule, event, workflow_finished).
• Control flow: condition, loop, switch, parallel, error_handler, retry_with_backoff, flow_tool, sub_workflow, wait, wait_for, rate_limiter.
• LLM and AI: llm_completion, bedrock, vertex, azure_ai, reasoning, llm_router, anomaly_detect.
• MCP tools: mcp_tool (invokes MCP tools through the MCP proxy).
• Data and RAG: knowledge_ingest, knowledge_search, rag_query, vector_store, embedding, text_splitter, document_loader, file_upload, rerank, multi_query, data_query, data_source_query.
• Code execution: code (JavaScript, Python, or Bash in an isolated sandbox), k8s_sandbox_run.
• Data transformation: transform, filter_data, select_data, extract_key, parse_json, regex, csv_processor, aggregate, dedup, merge, text.
• Integrations: slack_message, teams_message, discord_message, send_email, outlook_email, jira_issue, servicenow_ticket, pagerduty_incident, http_request, splunk_search, webhook_response, save_file.
• Agents and multi-agent: agent_single, agent_spawn, agent_pool, agent_supervisor, a2a, multi_agent.
• Annotations and utilities: human_approval, human_input, user_context, grounding_check, guardrails, structured_output, map_reduce, prompt_template, conversation_memory.

Edges define the execution path: the engine follows the edges you draw. An edge whose source handle is error is the failure path; route a failed step to a handler, continue past it, or rethrow.

Each node is configured from its own schema, with {{...}} templating to pull in upstream results and trigger input. Supported references include {{steps.X.output}}, {{trigger.foo}}, {{env.BAR}}, and {{secret:name}}.

A run, end to end

A flow fires from a trigger, executes its nodes in topological order, and follows edges to completion. If a step fails, the engine follows the error edge to a retry or a handler before the run reaches a terminal node.

trigger -> run nodes (in edge order) -> [on error -> retry / handler] -> done

The engine threads an execution context (executionId, workflowId, userId, tenantId, userEmail, authToken, input, variables, node results, resolved secrets, and secret ACLs) to every executor. Routing nodes (condition, switch, loop, parallel, llm_router) own their downstream routing; the engine does not re-fire their edges, which prevents double execution. Multi-input merge nodes act as barriers and wait for all upstream branches to arrive.

Build a flow

You can build flows two ways:

• Drag-and-drop canvas. Use the React Flow canvas with a node palette and a properties panel. Drop nodes, draw edges by connecting ports, and configure each step in its properties panel. The MCP tool palette is auto-populated from connected MCP servers.
• AI Flow Builder (experimental). Describe the workflow in plain language. The builder reads the live node registry plus current canvas and execution state, then streams patches or full definitions back and applies the generated nodes to the canvas.

Before execution, the MissingSecretsWizard prompts you to fill in any unresolved {{secret:*}} references, and PreflightValidationPopover runs pre-execution checks.

You can export a flow as JSON and import it back. Workflows are persisted through the API, with version snapshots stored in the WorkflowVersion table so you can roll back to a past version.

Triggers

A flow does not have to be run by hand. The trigger node supports five types:

• manual
• webhook
• schedule
• event
• workflow_finished

A saved flow can also be wrapped as a callable tool through the flow_tool node and invoked from another flow, or invoked as a nested sub-execution through the sub_workflow node. Nested execution depth is capped at 3 by default and is configurable on flow_tool via maxDepth.

Error handling and retries

Failures get their own path. An edge whose source handle is error is reserved for the failure branch, and each node decides what happens when its retries are exhausted:

• Per-node retry. Set a maximum number of retries and a delay. Exponential backoff multiplies the wait between attempts and emits a node_retry event each round.
• Route to an error handler. Send the failure, along with the error, the failed node, and its input, down the error edge to an error_handler node that can log, notify, or transform it.
• Continue or rethrow. Store the error and continue down the main path, or let it surface and stop the run.

Beyond per-node retries, the engine provides a retry_with_backoff node with configurable maxRetries, initialDelay, maxDelay, and backoffMultiplier, plus FallbackConfig and fallbackNodeId for graceful degradation. The parallel node uses settled fan-out so that one branch failing does not collapse the rest.

MCP tool authentication

Note: These docs cover the self-hosted build of OpenAgentic.

In the self-hosted build, MCP tools authenticate with static, service-account credentials only. There is no IdP-based on-behalf-of (OBO) delegation in the self-hosted build.

An mcp_tool node names a toolName and a toolServer (for example, azure_list_keyvaults on openagentic_azure). The MCP proxy spawns the matching MCP subprocess, injects the configured credentials, and relays the call.

Governance, traces, and audit

Flows are built for teams that have to account for what ran. Every execute, resume, and compile request is gated behind an internal service key, requires a tenant ID, and runs inside a tenant-scoped frame for multi-tenant isolation. Mutating tool calls and explicit human_approval nodes pause for human sign-off.

The engine emits an execution event stream over SSE/NDJSON, with event types including execution_start, node_start, node_complete, node_error, node_stream, node_progress, node_canonical, node_retry, node_fallback, approval_required, approval_received, needs_input, execution_paused, execution_resumed, execution_complete, and execution_error. Per-entry logs are written to the WorkflowExecutionLog table (execution_id, node_id, level, message, data, trace_id, span_id, timestamp), and the UI execution panel displays per-node input and output, execution time, token count, and error stacks. Past runs are queryable through GET /api/workflows/:id/executions. Per-execution cost is accumulated from LLM nodes using DB-driven per-token rates and persisted to WorkflowExecution.cost.

Secret resolution happens before execution: the engine scans node data for {{secret:name}} patterns, loads and decrypts values from the WorkflowSecret table, and enforces per-node ACLs inline at interpolation time. A failed ACL check aborts node execution with an ACL error.

On completion, the engine produces a signed run trace. A TraceCollector buffers all events and signs them with HMAC-SHA256 (using SIGNING_SECRET, falling back to JWT_SECRET or INTERNAL_SERVICE_SECRET). The SignedExecutionTrace records contentHash, signature, algorithm, eventCount, signedAt, and executionId, so a run is replay-identical and any tampering to events, hash, or signature is detectable.

Note: Durable trace persistence to a dedicated workflow_traces table is planned but not yet in the Prisma schema. Today, signed traces are written to logs and verify end to end.

What’s next

• Install OpenAgentic
• Chat concepts