Steps & Connections
You’ve created and set up your Start step - now what? Naturally, add more steps!
There are two ways to add new steps in the editor and connect them to the rest of the Spell. Let’s walk through both:
Dragging in Steps
On the left side of the editor, you’ll see the steps sidebar:
When you hover the sidebar, it will expand to show you the different categories of steps we have. Let’s click on Text:
Now, let’s say we want to generate some text. We’ll click and hold to drag the Generate Text block onto the canvas.
Great! But it’s not connected yet. When you drag in a step, you’ll need to connect it manually. To connect the step, hover over a step in the canvas and you’ll notice there are circular dots in the corners. Click and hold, then move your mouse to another dot - you’ve now created a connection between the steps, so now they can share variables.
Inserting Steps
You can also insert steps directly into your Spell. If you know where you want the step to go, inserting a step lets you skip the part where you have to manually connect the steps together.
Inserting a step after another step
If you have a step with no other steps after it (”end of the chain”), when you hover that step you’ll see a + button next to the connection circle:
Clicking the + button will open the step sidebar just like before. When you click a step (you can’t drag them), it will be inserted after the step you clicked the + button on.
Inserting a step between two steps
If you want to add a step between two other steps, you definitely don’t want to have to delete the connections on both sides, move the steps around to make space, then drag in the new step and make two more connections. That’s a lot of work.
Fortunately, when you hover a connection or the surrounding steps, we’ll show a + button in the middle of that connection:
When you click this button, the step sidebar opens up. When you select a step, it will automatically be inserted between the two steps. We’ll also try to move steps around so the canvas doesn’t get too cluttered.
Understanding Connections
Connections from one block to another are simple enough, but what if your Spell is more complex?
Connections are “dependencies”
We’ve been described connections as the way you pass data between steps, but there’s one more concept to understand about connections. When you connect steps A and B like below:
What you’re saying is two things:
- I want A to run before B
- I want B to have access to A’s output variables
After all, if B can run before A, how is it supposed to use A’s variables?
As you build more complex spells, with conditionals, loops, and loopbacks (oh my!), it’ll be helpful to remember that connections indicate that one block is dependent on another and thus dictate the order in which steps will run.
Branching (running in parallel)
One step can connect to multiple other steps after it. Take a look at this:
In this Spell, the Generate Text with AI steps are dependent on the Start step. Start will run, and only then will the AI steps run. In fact, we can do better: the AI steps will run at the same time (in parallel). This can make your larger Spells with multiple branches quite a bit faster.
You can also go the other way. Multiple steps can connect to the same step:
In this case, Display is dependent on both AI steps. As a result, Display will run after both of the AI steps have finished. This guarantees that Display will have the variables available from the AI steps.
Optional connections
What if you don’t care if one of the AI steps finishes? What if it errors out, but that’s OK for Display to run? This is where you would use optional edges.
(image: optional connection)
Optional edges say “try to wait for this step to run, but if the step doesn’t run or encounters an error, keep going anyway”. It’s a way to make sure your Spell can keep running if a step doesn’t finish, but if the step does finish it would be useful to pass its output variables along.
To create an optional connection, first you need to create a normal connection. Then, when you hover the connection on the canvas, you’ll see a dotted line icon:
(image: optional connection creator)
If you click this, the edge will become optional. You can switch it back to a normal edge the same way if you change your mind.