Agent step

The Agent step lets you add AI-powered decisioning and content generation directly into your Canvas workflow. For more general information, see Braze Agents.

How it works

When a user reaches an Agent step in a Canvas, Braze sends the input data you’ve configured (full context or selected fields) to your chosen agent. The agent then processes the input using its model and instructions, and returns an output. That output is stored in the output variable you defined in the step.

You can then use this variable in two main ways:

• Decisioning: Route users down different Canvas paths based on the agent’s response. For example, a lead scoring agent might return a number between 1 and 10. You can use this score to decide whether to continue messaging a user or drop them from the journey.
• Personalization: Insert the agent’s response directly into a message. For example, an agent could analyze customer feedback and generate an empathetic follow-up email that references the customer’s comment and suggests a resolution.

Creating an Agent step

Step 1: Add a step

Drag and drop the Agent component from the sidebar, or select the plus button at the bottom of a step and select Agent.

Step 2: Select your agent

Select the agent that will process data in this step. Choose an existing agent, or create a new one directly from this step. For setup guidance, see Creating custom agents.

Step 3: Define the output variable

Agent outputs are called “output variables” and are stored in a context variable for easy access. To define the output variable:

1. Give the variable a name.
2. Select a data type.

Agent outputs can be saved as strings, numbers, booleans, or objects. This makes them flexible for both text personalization and conditional logic in your Canvas. Here are some common uses for each type:

Data type	Common uses
String	Message personalization (subject lines, copy, responses)
Number	Scoring, thresholds, routing in Audience Paths
Boolean	Yes/No branching in Decision Splits
Object	Leverage one or more of the above data types with a single LLM call in a predictable data structure

When defined, you can use an output variable throughout the Canvas by using the same template syntax as you would with a context variable. Either use the Context Variable segment filter, or template agent responses directly using Liquid: {{context.${response_variable_name}}} .

To use a specific property from an object output variable, use dot notation to access that property using Liquid: {{context.${response_variable_name}.field_name}}

Use the Liquid syntax patterns shown above to reference particular fields from the agent output in future Canvas steps.

Step 4: Decide what context to provide the agent

You must decide what data the agent should receive at runtime. The following options are available:

• Include all Canvas context: Pass all available Canvas context variables (such as Canvas entry properties) into the Agent step. You can use Context steps upstream of the agent steps to add more data to Context ahead of it.
• Provide values: Pass only selected properties, such as a user’s first name or favorite color. Choose this option to only give the agent access to the values you assign here. For each Key, enter the Liquid tag that defines the specific user profile field or context variable.

Step 5: Test the agent

After setting up your Agent step, you can test and preview the output of this step.

Error handling

• If the connected model returns a rate limit error, Braze retries up to five times with exponential backoff.
• If the agent fails for any other reason (such as invalid API key), the output variable is set to null.
• Responses are cached for identical inputs to reduce repeated invocations.

Analytics

Refer to the following metrics to track how your Agent steps perform:

Metric	Description
Entered	The number of times users entered the Agent step.
Proceeded to Next Step	The number of users that proceeded to the next step in the flow after passing through the Agent step.
Exited Canvas	The number of users that exited the Canvas after passing through the Agent step.

Frequently asked questions

When should I use an Agent step?

In general, we recommend using an Agent step when you want to feed particular contextual data into an LLM and have it agentically assign Canvas context variables intelligently at a scale impossible for humans.

Let’s say you’re sending a personalized message to recommend a new ice cream flavor to a user who previously ordered chocolate and strawberry. Here’s the difference between using an Agent step versus AI item recommendations:

• Agent step: Uses LLMs to make a qualitative decision on what the user might want based on the instructions and context data points given to the agent. In this example, an Agent step might recommend a new flavor based on the possibility of the user wanting to try different flavors.
• AI item recommendations: Uses machine learning models to predict the products that a user is most likely to want based on past user events, such as purchases. In this example, AI item recommendations would suggest a flavor (vanilla) based on the user’s previous two orders (chocolate and strawberry) and how those compare to the behaviors of other users in your workspace.

When should I use a standard output format for an agent?

We recommend using the output format when you want the agent to return a data structure with multiple values defined in a structured manner, rather than a single-value output. This allows the output to be better formatted as a consistent context variable.

For example, you may use an output format within an agent that is intended to create a sample travel itinerary for a user based on a form they submitted. The output format allows you to define that every agent response should come back with values for tripStartDate, tripEndDate, and destination values. Each of these values can be extracted from context variables and placed in a Message step for personalization using Liquid.

How do Agent steps use input data?

Agent steps use specific context data that is provided to the agent.

You can choose to either pass the entirety of Canvas context into the agent as context, or pass specific values using Liquid tags into the context of that Agent step. You can also use Connected Content as an input value in an Agent step.

Related articles

• Braze Agents overview
• Creating custom agents
• Deploying agents