Getting Started
Step Options & Variables
Now that we have a handle on steps, let’s understand data flows throughout a Spell. Let’s take another look at the example from the last section:
When a new contact is added to HubSpot, what data is available? How do we use that data to perform the action in later steps? This section will discuss variables and how to use them in step options.
Generate Text has 2 required options: Model and Prompt. These options have different types: model is a dropdown, and prompt is text. You can manually enter the values for these options, but you can also use data from previous steps. Variables are how you pass data between steps
For example, you may want to generate a personalized email for the new HubSpot contact above. In Generate Text’s prompt option, you’ll want to reference details from the contact to give the AI context on the email recipient. You would insert a variable into the prompt option like this:
Now, when your Spell runs, it will pass the contact’s name into the Generate Text prompt. You can enter any variable into any option, as long as the type matches. We discuss what you can do when the types don’t match below.
Here, we’ve inserted a date variable into a text option. We may want the date to be in a specific format, or only use some parts of the date such as the month or the year. We need to “convert” it to match what we want, and we can use converters to do that:
In this case, we’re converting the date to just the “day” portion (Monday, Tuesday, etc.). When we select a converter for a variable, before that step is run we’ll convert the variable and pass the result as the option.
Converters aren’t only for changing a variable’s format or extracting information about it. Sometimes you may need to change a variable’s type before it can be used in a step. For example, maybe you want to describe an image as text before using it in the next step. You can use the Describe converter on an image variable to do this, instead of adding an entire new Describe Image step.
In this example, the Spell has two branches. Branching can be helpful for making your spell faster (as the blocks run simultaneously), and also to help it look cleaner. But how do we pass variables between the steps?
The simple rule is:
When you click the button, you’ll be shown a dropdown with all of the past steps. If you click a step, it will open the dropdown to show the output variables from that step. Clicking on a variable will insert it into the input.
Different option types may have slightly different experiences. For example, inserting a variable into a file options will show two tabs: a variable picker (same as above), or an option to upload your own file.
When a new contact is added to HubSpot, what data is available? How do we use that data to perform the action in later steps? This section will discuss variables and how to use them in step options.
Step Options
Every step has “options” which change its behavior. Let’s examine the Generate Text block:
Generate Text has 2 required options: Model and Prompt. These options have different types: model is a dropdown, and prompt is text. You can manually enter the values for these options, but you can also use data from previous steps. Variables are how you pass data between steps
For example, you may want to generate a personalized email for the new HubSpot contact above. In Generate Text’s prompt option, you’ll want to reference details from the contact to give the AI context on the email recipient. You would insert a variable into the prompt option like this:
Now, when your Spell runs, it will pass the contact’s name into the Generate Text prompt. You can enter any variable into any option, as long as the type matches. We discuss what you can do when the types don’t match below.
Step Outputs
Each step will make variables available to the steps after it. When we speak about variables from steps, we call them “outputs” For example, Generate Text has one output: response. There are two places where you can view a step’s outputs:- A preview list of the most popular output variables on the step block in the editor canvas
- The outputs tab of the step sidebar
Variable Types & Converters
Every variable has 2 icons next to the name:- The icon on the left indicates the type
- The icon on the right indicates which step the variable comes from
For a full list of types and converters, see our Variable Types Reference and Converters Reference
Converters
You can use converters to transform a variable’s value before it gets passed to the step. When you insert a variable into an option, you can hover over the variable to see the available converters:
Here, we’ve inserted a date variable into a text option. We may want the date to be in a specific format, or only use some parts of the date such as the month or the year. We need to “convert” it to match what we want, and we can use converters to do that:
In this case, we’re converting the date to just the “day” portion (Monday, Tuesday, etc.). When we select a converter for a variable, before that step is run we’ll convert the variable and pass the result as the option.
Converters aren’t only for changing a variable’s format or extracting information about it. Sometimes you may need to change a variable’s type before it can be used in a step. For example, maybe you want to describe an image as text before using it in the next step. You can use the Describe converter on an image variable to do this, instead of adding an entire new Describe Image step.
Many converters, like Summarize, have the same functionality as a step. Steps provide more options to control the output, but oftentimes it may be quicker and easier to add a converter. Plus, fewer steps makes spells easier to understand!
Using Variables
Ensuring variables are available
In order to use variables from one steps in another one, you need to make sure the two steps are connected. Here’s an example:
In this example, the Spell has two branches. Branching can be helpful for making your spell faster (as the blocks run simultaneously), and also to help it look cleaner. But how do we pass variables between the steps?
The simple rule is:
If there is a line from step A to step B, you can use step A’s output variables in step B’s options. In short: if there’s a line between, we can pass data.In this case, Start has a line to all other steps. So we can use Start’s variables in A, B, C, and D. A has a line to B, so B can also use A’s variables. However, there’s no line between A and C, so there’s no way to pass data between those steps. If you want to allow A to pass variables to C, then you need to move C after A and combine it into one chain of four steps in a row.
Tip: because all steps at some point came from the Start step, all variable outputs from the Start step are available everywhere in the Spell!
Inserting variables in options
Once you know the variables you need are available in a step, you’re ready to fill out that step’s options. Near the option’s input, you’ll find a + button:
When you click the button, you’ll be shown a dropdown with all of the past steps. If you click a step, it will open the dropdown to show the output variables from that step. Clicking on a variable will insert it into the input.
Different option types may have slightly different experiences. For example, inserting a variable into a file options will show two tabs: a variable picker (same as above), or an option to upload your own file.