Workflows SDKQuickstart

Code-first Approach

The instructions below will guide you through creating a Workflow using a starter template with the Vellum CLI.

1

Install the Vellum Workflows SDK

$uv add vellum-ai
2

Initialize a new Workflow from a template

Before using vellum workflows init, make sure you have set your VELLUM_API_KEY environment variable. See the installation guide for instructions on how to set this up.

Use the Vellum CLI to clone a starter template:

$vellum workflows init

You’ll see available templates. For this example, we’ll use the Prompt Chaining template:

Vellum workflows init showing available templates
Available Workflow templates

Select Prompt Chaining (option 1). When it completes succesfully, you’ll get a message like: Successfully pulled Workflow into ~/.../prompt_chaining

3

Understanding the Prompt Chaining template

The Prompt Chaining template generates blog topics, outlines, and full posts tailored to specific industries and audiences. It demonstrates key concepts like:

  • Workflow Inputs: Parameters that customize the workflow behavior
  • Connecting Nodes: How nodes pass data between each other
  • Scenarios: Test cases for experimentation

The cloned Workflow includes these core files:

Project structure
prompt_chaining/                    # Project root directory
├── nodes/                          # Directory containing workflow nodes
│   ├── __init__.py
│   ├── topic_researcher.py        # Node for researching blog topics
│   ├── outline_creator.py         # Node for creating outlines
│   ├── content_generator.py       # Node for generating blog posts
│   └── final_output.py            # Final output node
├── display/                        # UI-specific files (auto-generated)
│   └── [UI-specific files]
├── __init__.py                     # Python package initialization
├── workflow.py                     # Main workflow definition
├── inputs.py                       # Workflow input schema
├── sandbox.py                      # Test scenarios and experimentation
├── vellum.lock.json               # Tracks workflow state for push/pull
└── pyproject.toml                 # Project configuration (alternative)

The display/ directory contains UI-specific files that are useful when pushing back to the Vellum UI later. You don’t need to modify these files.

4

Run your Workflow

Test your Workflow using the sandbox file:

$python -m prompt_chaining.sandbox

The sandbox.py file contains test cases that you can use as a “vibe-check” while experimenting. For more rigorous testing, use our Evaluations product.

5

Configuration files

Your project will include configuration files:

  • vellum.lock.json: Tracks the state of your Workflow for push/pull operations
  • pyproject.toml: Alternative configuration approach (learn more)

Push to Vellum UI

Once you’ve built and tested your Workflow locally, you can push it to the Vellum UI for debugging, collaboration, or to let subject matter experts help with prompt optimization.

1

Create a new Workflow Sandbox

  1. Go to app.vellum.ai/workflow-sandboxes
  2. Click “Create Workflow” to make a new Workflow Sandbox
Create Workflow button in Workflow Sandboxes
Create a new Workflow Sandbox
2

Get the push command

From your Sandbox, click:

  1. The “Command Line” button
  2. The “Push” tab
  3. “Copy” to get the CLI snippet
Command Line push tab with copy button
Copy the push command from the UI

The snippet will look like:

$vellum workflows push --workflow-sandbox-id=f059da6f-f7e4-4e18-aad2-23569baff905
3

Push your Workflow

Add your module name to the command and run it:

$vellum workflows push --workflow-sandbox-id=f059da6f-f7e4-4e18-aad2-23569baff905 prompt_chaining

You may need to remove the display/ directory and vellum.lock.json file, or delete from .display import * from your prompt_chaining/__init__.py file before pushing.

4

Success!

Once pushed successfully, you’ll see a confirmation with a link to your Sandbox:

Success message with link to Workflow Sandbox
Successful push with Sandbox link

If needed, you can click the “Autolayout” button in the Workflow editor to arrange the nodes nicely:

Autolayout button in the Workflow editor

Next Steps