You’ve read the explainer. You know what BrazeAI^™ Agent Console is, what it’s for, and why it’s supposed to save your team hours of manual copywriting and catalog cleanup. 

But then you open the dashboard, click Create agent, and stare at a blank name field. Now what?

That gap, between understanding the concept and actually shipping something that works, is where most marketers get stuck. Not because the idea is complicated. Because nobody walks them through the actual screens.

This Braze Agent Console tutorial is that walkthrough. 

Agent Console now lives inside Canvas as an Agent Step, or inside Catalogs as a Catalog Agent, and we’re building one working agent, start to finish. That includes the handful of settings that quietly cause most first-agent failures. No more “what is Agent Console.” Just the build. 

Let’s cut to the chase and get straight to building our first agency in Braze. 

Pick your pilot use case before you touch the Console

Before you open Agent Console, decide what you’re actually building. This matters more than people think.

Don’t start with a customer-journey-routing agent. It’s tempting. Routing feels like the “real” use of AI. But it gates live decisions inside your Canvas, and it’s harder to debug when something goes sideways.

Start smaller instead. Braze’s own starter templates point toward lower-risk pilots: a Personalized Copywriter or Feedback Analyst agent if you’re working with a Canvas Step Agent, or a Description Writer agent if you’re setting up a Catalog Agent.

Here’s the rule of thumb: pick a use case where a bad output is embarrassing, not damaging. Save the routing and decisioning agents for after you trust your setup. 

How to build your agent in Braze Agent Console, step by step

This is the part everyone actually needs. Seven steps, start to finish.

Step 1: Choose Canvas Step Agent or Catalog Agent

Here’s the fork in the road. A Braze Canvas Step Agent processes one user in real time, inside a journey. It fires the moment someone enters that step. A Catalog Agent works differently. It enriches rows of catalog data in bulk, outside of any live journey.

Before you build either one, check two permissions: access to Agent Console in your workspace, and permission to create and edit custom AI agents. Flag this with your Braze admin now, not mid-tutorial.

Step 2: Build from scratch or let operator start you off

You have two paths here: build a custom agent from a blank slate, or let BrazeAI Operator apply a starting template for you.

For a first agent, use Operator. Canvas Step templates include Personalized Copywriter, Feedback Analyst, and Journey Router. Catalog templates include Description Writer, Item Categorizer, and Localization Translator. Each one pre-fills instructions and an output schema you can review and edit, instead of writing everything from a blank page.

Step 3: Set the guardrails before you write a single instruction

Name and describe your agent clearly. If your team shares a workspace, a vague name like “Agent 1” will confuse someone in three months. Be specific.

Then pick a model. Braze Auto runs on Gemini, needs no API key, and automatically routes each request to an effective model. Or bring your own key, OpenAI, Anthropic, or Gemini, and your provider bills you directly instead of Braze.

If you’re not on Braze Auto, you’ll also set a thinking level: Minimal, Low, Medium, or High. Braze recommends starting at Minimal and only raising it if your outputs start struggling. Higher thinking levels cost more tokens and take longer to respond.

Last, set your daily invocation limit. It defaults to 250,000 and can be raised to 1,000,000. For a first agent, stay conservative here. You can always raise it once you trust the output.

Step 4: Write instructions that survive contact with real users

Here’s the core mistake people make: agents can’t ask clarifying questions. They can’t pause and check with you. They proceed on whatever’s in the prompt, even when the data is missing or contradictory.

So write for that reality. State the goal first. Give the agent a persona. Tell it explicitly what to do with ambiguous cases. Instead of asking for only “positive” or “negative” sentiment, ask it to return “unsure” when it can’t decide. And ask for structured output every time.

One counterintuitive tip: don’t tell the agent what not to do. It sounds backward, but LLMs can still generate the exact content you’re trying to rule out if you mention it in the instructions. Describe the behavior you want, not the behavior you’re avoiding.

And skip conditional Liquid. {% if %} blocks aren’t supported inside agent instructions. If you need conditional logic, describe it in plain language instead.

Step 5: Feed the agent context, not the whole canvas

Agents can pull from five context sources: catalog fields, segment membership (up to five segments), brand guidelines, all Canvas context, and each user’s recent interaction history.

Here’s the catalog-first rule: if your agent recommends something from a defined set of options, connect a catalog. Without one, it will invent plausible-sounding but entirely fictional items. That’s not a bug. It’s just what an LLM does when it has no ground truth to check against.

And resist the urge to select “All Canvas Context” by default. Tighter, curated context keeps token costs and latency down, and that matters a lot more once your agent is running at real send volume.

Step 6: Pick an output format the rest of your canvas can use

You have two options here: basic schemas (a string, number, boolean, or array) or advanced schemas, Fields or JSON Schema, for anything with multiple values, say a likelihood_score, an explanation, and a confidence_score together.

Whatever you choose, make sure your instructions and your Output tab describe the same shape. It sounds obvious, but a mismatch between the two is one of Braze’s most common documented causes of agent timeouts.

One more thing, specific to Canvas Step Agents: you can set fallback values. If an invocation fails, Braze renders your fallback through Liquid instead of leaving the field null. Catalog Agents don’t support this, so build extra care into your Catalog instructions instead.

Step 7: Test it like you don’t trust it yet

The Preview pane is your safety net. Test with a random user, an existing user, or custom data you type in yourself: before any of it touches a live Canvas.

Check three things every time: does the copy feel on-brand? Does the decision logic route the way you expect? Are the calculated values accurate? Then deliberately break it. Test blank inputs and contradictory data, because that’s exactly what real users will eventually send you.

One budget note: test runs count against the daily invocation limit you set in Step 3. Factor your testing volume into that number before you start.

Why first agents fail (and how to read the symptoms)

This is the part most Braze content skips. Once your agent is live, here’s how to read what’s going wrong.

• Timeouts almost always trace back to one of three things: incomplete or contradictory instructions, an edge case you didn’t cover, or a mismatch between your instructions and your output schema.
• Works fine in testing, breaks the moment it goes live? That’s almost always a missing Context step upstream, or Canvas context that was never explicitly passed through Liquid or the “Add all Canvas context” option.
• Struggling with a genuinely complex ask? Braze’s own recommendation isn’t a bigger, pricier model. It’s splitting the job across two or three smaller sub-agents, one to standardize the input, one to match it against a catalog, one to write the final copy.
• Catalog Agent skipping rows? Check for blank required-input columns or unmet column dependencies first. It’s rarely a broken agent. It’s incomplete data.

Wrapping up 

That brings us to the business end of this article, where it’s fair to say that building your first agent in Agent Console isn’t about picking the most ambitious use case you can think of. 

It’s a seven-step path we discussed. 

The teams who get value from Agent Console fastest aren’t chasing the flashiest first build. They treat that first agent as a controlled pilot, guardrails already in place, and they let the wins compound from there.

If you’d like a second pair of eyes on your first agent, or you want to identify the right pilot use case before you build anything, our team at Mavlers works inside Braze Agent Console every day. Let’s talk.