> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Graphs of typed components that run in the cloud: how one is built, coded and run.

export const Scope = ({type, href}) => {
  const scopes = {
    workflow: ['the ', 'Workflow', ' blob type', '/blob-types/introduction#workflow'],
    scheduler: ['the ', 'Scheduler', ' blob type', '/blob-types/scheduler/overview'],
    onnx: ['the ', 'ONNX Model', ' blob type', '/blob-types/introduction#onnx'],
    worker: ['', 'blobhub-worker', ', which runs on your machines', '/worker/introduction']
  };
  const scope = scopes[type];
  if (!scope) {
    return <p>Unknown scope: {type}</p>;
  }
  return <p className="text-sm text-gray-600 dark:text-gray-400">
      Provided by {scope[0]}<strong>{scope[1]}</strong>{scope[2]}. · <a href={href || scope[3]}>Reference</a>
    </p>;
};

export const Shot = ({src, alt, caption}) => <Frame caption={caption}>
    <img className="block dark:hidden" src={src} alt={alt} />
    <img className="hidden dark:block" src={src.replace(/\.(png|svg)$/, '.dark.$1')} alt={alt} />
  </Frame>;

<Scope type="workflow" href="/blob-types/workflow/workflows/definition-format" />

A workflow definition is a graph of typed components wired together by routed connections. The platform's engine
runs it in the cloud, one component at a time, following the route each component leaves by. You build one on the
web app's canvas, or as files in your repository with the CLI, and run it from a playground, a schedule, the SDK or
any API call.

## Definitions

Each revision of a workflow can hold several definitions side by side, each with its own id and an alias unique
among its workflow definitions, up to the `workflow.definitions_per_revision` [limit](/general/limits#workflow).
Playgrounds are stored the same way, as definitions of their own category with aliases and a limit of their own, so
a playground may share a workflow definition's alias. A definition has two parts: its components, the nodes, and its
connections, the edges between their ports.

Saving a definition checks nothing, so a broken graph saves. It is checked at exactly two moments: when you ask,
with the editor's **Check workflow** control, `blobhub workflow check` or the
[Check Definition](/blob-types/workflow/operations/check-definition) call, and when a run starts, which refuses to
begin if the same check finds an error.

A new revision carries every definition forward under its alias with a new id. A reference by `default` and alias
follows the definition to the new revision; one that pins the old id stays with the old revision. Sessions do not
come along: they are a revision's runtime, not its content.
[How BlobHub works](/general/how-it-works#revisions-and-the-revision-lifecycle) covers revisions.

<Shot src="/general/images/workflows/canvas.png" alt="The workflow editor: palette, graph and details pane" caption="A definition is built on the editor's canvas, one typed component at a time." />

## Components

Every component has a dotted type, such as `genai.chat.openai` or `logic.for`, which fixes its ports and its
configuration. The palette groups them into families: Flow, Data, Logic, Generative AI Chat, Generative AI Agents,
Vector Databases, The Web, and Text Processing. The editor reads the palette from the platform's component registry,
so what the registry lists is what exists. The [Components](/blob-types/workflow/workflows/components) reference
describes each family.

A component's ports come in three kinds. Flow ports carry control in and out. Data ports carry a typed value, such
as text, a number, a message or a credential reference. Provider ports plug in another component that supplies a
service, such as a credential for a model provider. Every port has a route, a name unique among the component's
ports of its kind, and each one is either filled inline with a value or left for a connection to fill at run time.

A component finishes by naming the route it leaves by, usually `success` or `failure`, and the engine follows the
connection wired to that route. If nothing is wired to the route it names, the run fails.

## Code

`logic.code` runs your Python. The code runs in one flat namespace with no import machinery: the standard-library
modules the platform binds in advance, helpers for reading inputs, writing outputs, choosing a route and reaching
the run's own session, and the third-party modules the session's blob allows through `workflow.code_imports`. An
`import` statement fails at run time. A code component builds its exits from the routes wired to it, so it can
branch as many ways as you draw connections.

Hand-typing more than a few lines into one namespace gets unwieldy. The [CLI](/cli/workflow/overview) lets you
write the code as an ordinary Python package instead, with real imports, tests and an editor. Its
[compiler](/cli/workflow/compiler) walks the package's imports, tells local modules from those the platform
already binds and those the blob allows, and inlines the local ones into the flat namespace in dependency order. An
import the platform cannot provide is a build error rather than a failed run, and the same sources always compile
to the same bytes, so the output belongs in version control.
[What the runtime binds](/cli/workflow/sandbox) lists every name, and
[Code Component](/blob-types/workflow/workflows/component-code) the helpers.

<Shot src="/general/images/workflows/code.png" alt="A code component's Python, opened from its code input" caption="Code components hold Python, which the CLI can build from an ordinary local package." />

## Running one

A run is an **execution**, and it always happens inside a [session](/general/sessions), which must be open. The
execution copies the definition it names when it is created, and that copy, its
[snapshot](/blob-types/workflow/workflows/execution-snapshot), is all it reads from then on. Editing or deleting the
definition changes the next run, never one that has started, and the debugger draws the graph the run used.

The engine checks the snapshot, finds its entry point, seeds any input you passed, and then runs one component at a
time until a component ends the run. An exception, or a route with nowhere to go, fails it instead. Each step
is written to the execution's event log as it happens, and that log is what the [Debugger](/general/debugger)
reads back.

You start a run from the debugger's **New Execution**, the editor, a playground's chat widget,
[`blobhub workflow execute`](/cli/workflow/commands/execute), the SDK's [`Workflow`](/sdk/workflow) module, a
[schedule](/general/schedules), or a [Create Execution](/blob-types/workflow/operations/create-execution) call.
Whichever starts it, everything that depends on where the run happens follows the session.

## Workflow references

A run names its definition with a [workflow reference](/blob-types/workflow/workflows/workflow-reference): an
organization, a workflow and a definition, each by id or alias, and a revision, by id or as `default` for whichever
revision is the workflow's default. The definition can be in any workflow you can read, public ones included, and
the run still happens in a session you can write. Nothing is copied into your workflow; the run keeps its snapshot
in your session.

What depends on where the run happens follows that session, never the definition's source. Credentials the
definition names by alias resolve against whoever started the run (your user, or your API key's target), the
third-party modules and the limits are those of the session's blob, and every write lands in your session. A shared
definition therefore never runs with its author's credentials: one that names credential aliases runs only where
you hold [credentials](/general/credentials) under the same aliases. A reference is resolved once, when the run is
created, so `default` means the revision that was the default at that moment.

Where a reference is written as one string, in `blobhub workflow execute`, a chat widget's port or the SDK, it takes
the path form `org/blob/revision/definition`, or just a definition's alias or id for one in the session's own
revision.

The [Gallery](https://blobhub.io/gallery) on blobhub.io lists public workflows to start from: Deep Research,
Discussion Board, Trip Planner, Open Canvas, Basic RAG and Finance Ticker Data. Open one to read its definitions.
Run one by reference from a session of your own, where it uses your credentials under the aliases it names. Or name
it in a [CLI manifest](/cli/workflow/manifest) and `blobhub workflow pull` its definitions into files you can edit
and deploy to a workflow of yours.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.