Basic Concepts

An introduction to the concepts in our orchestration component.

Pipeline

The Pipeline is the core orchestration component that sequences and manages the execution of the components in our SDK. The Pipeline wraps the LangGraph library, which provides a powerful way to define and execute complex workflows.

Our Pipeline:

1. Lets you list Steps to run in sequence.

2. Can be empty (acts as a pass-through), contain a list of steps, or be composed from other Pipelines.

3. Supports chaining and nesting so you can build larger flows from smaller ones.

4. Validates and enforces the structure of the data that moves through.

Steps

Steps represent a single action in the Pipeline that reads the current state, does some work, and returns what changed or was added. A Step can wrap a component so that it can be executed within the pipeline framework, with automatic input/output handling through the pipeline’s State.

Each Step:

1. Connects into the Pipeline flow with defined inputs and outputs.

2. Typically has one entry and one exit, but can also branch or merge data.

3. Can be chained easily with the other steps.

4. Uses consistent error handling so failures include helpful context.

State

A State is the data container that flows through your pipeline — it carries inputs, intermediate results, and outputs between steps. It acts as the shared context for the entire workflow, allowing each step to read from and write to it without manually passing variables around.

The State:

1. Acts as the contract between Steps — each Step reads what it needs and writes back updates.

2. Encourages predictable schemata so Steps remain reusable and composable.

3. Supports mapping when entering or leaving nested flows to keep keys aligned.

Subgraph

A Subgraph is a reusable Pipeline that could be embedded inside another Pipeline.

A Subgraph:

1. Encapsulates a sequence of actions, so fomplex logic stays modular and easy to reuse.

2. Maps inputs from the parent flow into its flow.

3. Improves error context by hinting which inner action failed.

When to use a Subgraph

You should consider using a Subgraph when:

1. The same group of actions appear in more than one Pipeline.

2. A portion of your Pipeline is conceptually one functionality (e.g. "retrieve", "format").

3. You intend to evolve or swap implementations without changing the parent flow.

You should NOT use a Subgraph when:

1. The sequence is tiny, only used once, and shares the same State schema as the parent.

2. Nesting adds more mental overhead than it removes.