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 theworkflow.definitions_per_revision limit.
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 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 covers revisions.
Components
Every component has a dotted type, such asgenai.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 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 lets you
write the code as an ordinary Python package instead, with real imports, tests and an editor. Its
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 lists every name, and
Code Component the helpers.
Running one
A run is an execution, and it always happens inside a session, which must be open. The execution copies the definition it names when it is created, and that copy, its 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 reads back. You start a run from the debugger’s New Execution, the editor, a playground’s chat widget,blobhub workflow execute, the SDK’s Workflow module, a
schedule, or a 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: an organization, a workflow and a definition, each by id or alias, and a revision, by id or asdefault 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 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 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 and blobhub workflow pull its definitions into files you can edit
and deploy to a workflow of yours.