How to build a HubSpot custom agent without burning credits

A client asked me last week about building a custom agent to fill the fields their reps keep leaving empty. Yes, they should. The order they were about to build it in would have cost them.

Their problem is the most common one in HubSpot right now. Contacts land from Salesforce carrying an email address and almost nothing else. No company name, no segment, no industry. Someone fixes them by hand, and the way they do it is by searching the CRM for other contacts on the same domain and copying whatever those records say.

That's a rule. It lives in somebody's head instead of in the portal, which is exactly the kind of job a custom agent should take.

But the order you build it in decides whether it costs you an afternoon or a quarter of credits.

Build it in the chat before you build it in the builder

The instinct is to open Agent Builder and start writing instructions. Skip that.

Open Breeze first and ask for what you want in the same words you'd use with a colleague. "Contacts on this domain that are missing segment and industry." It already sees the CRM, so you don't have to explain your own data to it. Have it fix exactly one record.

Then go and look at that record yourself. When we did this, the first pass quietly skipped a contact in the set. We only caught it because we refreshed the list and counted. Nobody catches that three weeks later with the agent running on every new contact.

Now the step most people skip: ask Breeze to build the agent out of the run it just did. You're handing it a worked example rather than a description, and it writes its own logic from a job you both watched succeed.

Order the actions or the agent has nothing to work with

Inside the agent, sequence matters more than wording.

For this one: resolve the company name from the email domain first, then fill segment and industry from the other contacts already sitting on that domain. Run those steps the other way round and the second one has no cohort to compare against, because the records it needs haven't been identified yet.

The agent won't error. It'll just return less, on some records and not others, which is the failure you discover in a QBR six months on.

No amount of prompt polish fixes that. It's data modelling. It just happens to be written in English.

Testing is free. Running it is not.

Custom agents run on credits. Testing one inside the builder doesn't.

That's the whole cost-control story, and almost nobody uses it properly. Test on a record you already know is empty and check the output against what you'd have typed yourself. Don't publish something because the preview read well.

Once it works, put it behind the Run custom agent workflow action and trigger it on contact created. Not on a list. Not on the database. A contact arrives, the agent looks at that one contact, and it stops. Agent Hub is still in beta in some portals, so the workflow action may not appear until you join.

How often you let the agent run is what you're paying for. The trigger is the line item, not the instructions.

One action doesn't need an agent

Last rule, and it saves the most money.

If the job is a single deterministic step, build a workflow. It costs nothing per run, it does the same thing every time, and you can still read it six months from now. Agents earn their credits when the work takes several steps and one of them needs a judgement call: look this up, compare it to those, decide, then write.

This client's case clears that bar. Most of the half-built agents I find in portals don't.

If you're looking at your own portal and can't tell which of your automations fall on which side of that line, that's the audit to run before you build anything else.

Companion piece to Agent Builder and Agent Hub: scheduled triggers, one-click conversion, and what to build first.