HubSpot · Solution guide
HubSpot AI Agents: Breeze Agent Setup vs a Custom Agent Built on HubSpot's APIs
Written scope and quote after the call. NDA on request. You own the code.
Quick answer
HubSpot AI agents come in two forms. Breeze agents (customer, prospecting, data and others) run inside HubSpot on HubSpot Credits, from 50 credits per resolved conversation. Custom agents are either built in HubSpot's agent builder or run outside HubSpot and write back through the API, workflows, custom coded actions and webhooks. This page explains what each Breeze agent does, which tiers it needs, what it costs to run, and when our in-house team builds a custom agent instead.
Builds like this
Part of the guide: CRM AI agents
Key takeaways
- HubSpot's own agents (customer, prospecting, data, deal progression, AEO and others) run inside HubSpot and are paid in HubSpot Credits at $0.01 a credit: 50 credits per resolved customer agent conversation, 100 per lead the prospecting agent recommends, 10 per data agent response for one record (HubSpot rate sheet, checked Oct 31, 2026).
- Seat-based plans include 500, 3,000 or 5,000 credits a month on Starter, Professional and Enterprise of most hubs. Unused credits expire monthly, and usage features pause when credits run out unless you add packs or pay as you go.
- Customer agent and prospecting agent need Professional or Enterprise. HubSpot's pages disagree on whether Starter can build custom agents in agent builder, so confirm it in your own account before you plan around it.
- Use a Breeze agent when your job matches it closely. Build a custom agent when it needs your own rules, systems HubSpot cannot reach, approval steps, or a model and logging you control.
- A custom agent can live inside HubSpot (agent builder plus your own agent tools or MCP server) or outside it, triggered by webhooks or workflows and writing back through the CRM API within HubSpot's rate limits.
HubSpot AI agents are AI workers that read and act on your HubSpot records. There are two kinds. HubSpot’s own Breeze agents, such as the customer agent and the prospecting agent, run inside HubSpot and are billed in HubSpot Credits, for example 50 credits ($0.50) each time the customer agent resolves a conversation. Custom agents are ones you design: either in HubSpot’s agent builder, or on your own infrastructure with HubSpot’s API, workflows and webhooks carrying data in and out. A typical engagement with us is one agent, one job, one pipeline or inbox, tested on real records before it runs alone. This page covers what each HubSpot agent does, which plans include it, what it costs to run, and when our in-house engineers build a custom one instead.
Sources: HubSpot Products & Services Catalog, HubSpot Credits rate sheet, HubSpot Credits and customer agent pages, all checked Oct 31, 2026. Customers on HubSpot’s flexible seats-and-credits pricing have a separate rate sheet.
What HubSpot AI agents are available, and what does each one do?
HubSpot’s Agent Hub lists the agents below. Each one has a narrow job, reads specific data and writes to specific places. That narrowness is the reason to check fit before you switch one on.
| Agent | What it does in the CRM | Plan HubSpot names | Credits per unit (checked Oct 31, 2026) |
|---|---|---|---|
| Customer agent | Answers chat, email, form, WhatsApp and Messenger conversations from your knowledge base, website, CRM data and past conversations; hands off to your team with context; can take actions in the CRM within your rules | Professional or Enterprise | 50 per resolved text conversation; 50 per minute of voice (beta) |
| Prospecting agent | Researches target accounts, finds contacts and drafts personalised outreach, driven by “plays” you configure | Professional or Enterprise (per HubSpot’s April 2026 pricing post) | 100 per lead recommended for outreach |
| Data agent | Answers questions about records from CRM data, calls and documents; HubSpot also describes it as enriching and maintaining CRM data | Starter, Professional or Enterprise (Data agent page) | 10 per response to one prompt for one record, so a question that spans 50 records is 500 credits |
| Deal progression | Gives sales teams recommendations for moving deals through the pipeline | Not stated per agent | Not listed on the rate sheet |
| AEO | Works on your brand’s visibility in AI search | Marketing Hub Professional or Enterprise | Not listed on the rate sheet |
| Breeze Assistant | In-app assistant grounded in your CRM data and role | Not stated per agent | Not listed on the rate sheet |
| Custom agents (agent builder) | Your instructions, your chosen actions, run from workflows, CRM cards or the agent inbox | See the note below | 1 per action unit (beta) |
Sources: HubSpot Agent Hub article, AI agents page, customer agent page, pricing change post and the Credits rate sheet, checked Oct 31, 2026. HubSpot’s credits page also lists content (1,000 credits per piece), nurture (10 per email), revenue (500 per invoice) and knowledge base (200 per article) agents.
On plan requirements, HubSpot’s pages do not agree. The agent builder help article and the AI agents page list Starter, Professional and Enterprise of Marketing, Sales, Service, Data and Content Hub. The Fall 2026 developer changelog (Sep 15, 2026) says “Agent Hub and Agent Builder require Professional or Enterprise.” We check the account itself during scoping rather than relying on either page. For the wider plan picture, see HubSpot pricing and limits 2026, and if you are deciding between tiers, is HubSpot Free or Starter better.
Setting up a Breeze agent in HubSpot
Setup is configuration, not code, but most of the work is in the data the agent reads. A Super Admin first turns on the AI settings: generative AI tools, CRM data, customer conversation data and files data (HubSpot agent builder article, checked Oct 31, 2026). Then each agent has its own setup:
- Customer agent. Connect knowledge sources (knowledge base, website pages, PDFs, past conversations), pick channels, write handoff rules and decide which CRM actions it may take. The quality of answers depends on the knowledge base more than on any setting, so we audit it first.
- Prospecting agent. Build plays: the target audience, buying signals, personas, selling context, outreach strategy and how much runs automatically. HubSpot requires prospecting agent admin permission to create or edit plays.
- Data agent. Decide which properties it may fill or answer about, and which it must leave alone. A data agent writing into properties that feed your lead scoring or routing needs the same review as any other integration.
- Context and knowledge vaults. Agent Hub holds company-wide context (messaging, tone, ICP) and narrower “knowledge vaults” for product details or support guidance. Keep one owner for each.
Then test on real records, not a demo account. We run a sample of past tickets or leads through the agent, compare its output to what your team did, and only then turn on automatic runs. HubSpot lets you test custom agents without consuming credits and set monthly run limits, which we use from day one.
Should you use a Breeze agent or build a custom one?
HubSpot’s own guidance is a good starting rule: use a workflow when fixed rules can define the job, a HubSpot agent when its function matches yours, and a custom agent when you need instructions, inputs or actions beyond the defaults (HubSpot: when to use AI agents or workflows, checked Oct 31, 2026). Many teams skip the first step. Routing leads by country or setting a lifecycle stage does not need an agent, and a workflow does it with no credits.
| Situation | Better fit | Why |
|---|---|---|
| Support answers come from a clean knowledge base, handoff is simple | Breeze customer agent | Built for this, priced per resolution, nothing to host |
| Outbound to a defined ICP with your own messaging | Breeze prospecting agent | Plays cover audience, signals and tone |
| Job follows fixed rules (routing, stage changes, task creation) | Workflow, no agent | No judgment needed, no credits |
| Agent must read or write a system HubSpot cannot reach (ERP, billing, a clinic system, your own database) | Custom agent | Needs your own tools or an external service |
| Every action needs a human approval step, or an audit log you own | Custom agent, or agent builder with your tools | You control the approval and the record of what happened |
| High monthly volume where per-resolution credits add up | Compare both | A custom agent has model and hosting costs instead of credits |
| Data cannot be sent to a model you have not approved | Custom agent on your chosen model | You choose the model, region and retention |
Source: aibrevo scoping checklist for HubSpot agent work, Oct 31, 2026, built on HubSpot’s guidance above.
Two ways a custom AI agent connects to HubSpot
There are two architectures, and they can be combined.
Inside HubSpot, through agent builder. A custom agent built in agent builder gets instructions, data and actions. The Actions panel has three tabs: HubSpot actions (get data, generate, take action), default actions (browse the web, read CRM records, write CRM records) and MCP tools that connect to external systems. It can run from workflows, from CRM record cards or from the agent inbox. Our engineers extend it with your own tools: HubSpot’s developer platform lets an app define agent tools (beta) that call your endpoint, and since Sep 15, 2026 an app can add an mcp-server component so your own MCP tools appear inside HubSpot agents. Two limits matter: an agent has no CRM data access unless you give it tools for that data, and it cannot ask the user for more information after it is invoked.
Outside HubSpot, writing back to records. The agent runs on infrastructure you control with a model you choose. HubSpot sends it work through a webhook subscription or a workflow, the agent reasons and calls your other systems, then writes results back to HubSpot through the CRM API: a property update, a note, a task, a ticket reply draft for a human to approve. Inside a workflow, a custom coded action can call the agent directly. HubSpot limits these to Data Hub Professional or Enterprise, 20 seconds of run time, 128 MB of memory and 1,000 characters of secrets in total (checked Oct 31, 2026), so a long-running agent call should be queued and finish by writing back through the API, not inside the action.
Either way, the app that holds the tokens is built on HubSpot’s current developer platform, which is covered on our HubSpot custom app development page. Legacy private apps can no longer be created, and HubSpot says legacy apps and v1 to v3 APIs become unsupported in September 2027, as summarised in our HubSpot October 2026 updates.
1. Trigger
A webhook (new ticket, deal stage change) or a workflow enrolment sends the record ID to the agent.
2. Read
The agent fetches only the properties and associations it needs through the CRM API, inside rate limits.
3. Reason and act
The model drafts, scores or classifies, and calls your other systems through defined tools.
4. Approve
Risky actions wait for a human: a task or a draft on the record, not a sent email.
5. Write back and log
Results land on the record, and every run is logged with input, output and who approved it.
How do we build a HubSpot AI agent?
Our in-house engineering team, 16 engineers led by co-founder and CTO Shivam, builds HubSpot agents in five stages.
- Discovery. One job, written as a sentence: “draft a reply to every inbound pricing question and route it to the account owner for approval.” We list the records it reads, the properties it writes and what must never happen.
- Data model and permissions. Which objects, properties and associations the agent touches, which scopes the app requests, which users can run or edit the agent. Properties the agent writes get a clear name and a change source so your team can see what the agent changed.
- Build. Breeze configuration, agent builder with our own tools, or an external agent with webhooks and API write-back, whichever the job needs.
- Test on real records. We replay past tickets, leads or deals and compare the agent’s output with what your team did. Credits are estimated per run from this test before anything goes live.
- Guardrails, then go-live. Human approval for outbound messages and record deletions, logging of every run, back-off and retry for HubSpot’s API limits, run caps, and rules for personal data (what is sent to the model, what is masked, how long logs are kept).
For external agents the API limits shape the design. HubSpot allows privately distributed apps 100 requests per 10 seconds on Free and Starter and 190 on Professional and Enterprise, with daily caps of 250,000, 625,000 and 1,000,000 per account; a marketplace OAuth app gets 110 requests per 10 seconds per installing account (HubSpot usage guidelines, checked Oct 31, 2026). An agent that re-reads a full contact history on every run can hit those numbers, so we cache and fetch only what changed.
What does a HubSpot AI agent cost to run?
Running cost depends on volume, and for Breeze agents it is plain arithmetic on the rate sheet. Paid seats on seat-based plans include credits each month: 500 on Starter, 3,000 on Professional and 5,000 on Enterprise for Smart CRM, Marketing, Sales, Service, Content and Revenue Hub, and 500, 5,000 or 10,000 on Data Hub. With several hubs you get the highest allotment, not the sum. Extra credits are $10 per 1,000 as a capacity pack, or $0.01 each pay-as-you-go (HubSpot catalog, checked Oct 31, 2026).
| Example month | Credits used | Included on Professional | Extra credits | Extra cost at $0.01 |
|---|---|---|---|---|
| Customer agent resolves 300 chats | 15,000 | 3,000 | 12,000 | $120 |
| Prospecting agent recommends 200 leads | 20,000 | 3,000 | 17,000 | $170 |
| Data agent answers 500 record prompts | 5,000 | 3,000 | 2,000 | $20 |
| A workflow with one AI action runs 1,000 times | 10,000 | 3,000 | 7,000 | $70 |
Illustrative arithmetic, one agent at a time, using rates from HubSpot’s Credits rate sheet checked Oct 31, 2026. Real accounts share one credit allotment across every feature, so add the rows you would actually run. Excludes seat prices, onboarding fees and tax.
Three rules from HubSpot’s billing article are worth knowing before you go live: unused credits expire at the end of each month, usage features pause when credits run out unless you have packs or pay-as-you-go turned on, and only paid seats can use credits (HubSpot Credits and billing, checked Oct 31, 2026). A paused customer agent at month end is a support outage, so we set an alert well before the cap.
A custom external agent has no credit cost for the work it does outside HubSpot, but it has model usage, hosting and monitoring costs, and it still counts against your API limits. We estimate both sides from the test run during scoping. Seat costs and the one-time onboarding fees HubSpot charges on Professional and Enterprise are covered in HubSpot implementation cost, and you can model seats with our HubSpot pricing calculator.
How long does a HubSpot AI agent project take?
Typical scoping ranges, with the firm date set in the written scope: configuring a Breeze customer or prospecting agent on a clean account is usually days to two weeks, most of it on the knowledge base or plays and on testing. An agent-builder agent with one or two custom tools typically takes two to four weeks. An external agent that reads several systems, writes back to HubSpot and includes an approval step tends to run four to eight weeks. The slowest part is almost always agreeing what the agent may do without asking, not the code.
Checks before switching an agent on
- Knowledge quality. A customer agent answering from out-of-date help articles gives out-of-date answers with confidence.
- Who owns each property. If an agent and an integration both write to the same field, the last write wins and nobody can tell why it changed.
- Credit ceiling. Know the monthly number at which features pause, and who gets alerted.
- Plan fit. Confirm the tier in your account, given that HubSpot’s own pages disagree for Starter.
- Personal and regulated data. Decide what the model may see. For health data, read HubSpot’s terms for your account before sending anything to any AI feature.
- Handoff. Every agent needs a clear point where a person takes over, and a way for the customer to ask for one.
- API version. HubSpot’s 2026-09 API version enforces admin validation rules on API writes, so an external agent that skips a required property gets a 400 error.
Who is this for, and who is it not for?
It suits HubSpot Professional or Enterprise teams with a repeated, describable job: support questions that already have documented answers, outbound to a defined account list, record clean-up, or a judgment step between two systems. It also suits teams whose agent must reach a system outside HubSpot. It is not a fit when the process is not yet written down (fix the process first), when a workflow would do the job, or when you are still choosing a CRM, where the HubSpot vs Pipedrive comparison is a better first read. Agencies running many client portals should also read HubSpot for agencies.
We publish no price list for agent builds. Each one is scoped and quoted after a free 30-minute call, with the job, the records touched, the guardrails and the expected credit use written down. For agents on other CRMs, start from our CRM AI agents overview.
Have a HubSpot job you want an agent to do? Book a free 30-minute call or send a message with your hubs and tiers, the job in one sentence and roughly how many times a month it happens. You get back whether a Breeze agent, a workflow or a custom build fits, and an estimate of the monthly credits.
Sources
All pages opened on Oct 31, 2026.
- HubSpot, Products & Services Catalog: Credits rate sheet, included credits by hub and edition, credit and pack prices.
- HubSpot, HubSpot Credits: per-agent credit rates including content, nurture, revenue and knowledge base agents.
- HubSpot, AI agents and customer agent: agent descriptions, channels, plan requirement, resolution definition.
- HubSpot, Customer Agent and Prospecting Agent pricing change (effective Apr 14, 2026).
- HubSpot Knowledge Base, Understand Agent Hub, agent builder, when to use agents or workflows, prospecting agent, Credits and billing.
- HubSpot Developers, Fall 2026 Spotlight changelog, agent tools (beta), custom code actions, usage guidelines.
