Create and customize agents in the agent builder

Create custom agents that can analyze data, generate outputs, and take actions based on your business processes. Within the updated builder, you can define what an agent should do, what data it can access, and how it should respond.

Custom agents help standardize how tasks are performed and reduce manual effort by applying consistent logic to your data. This is useful for processes that require reviewing records, generating structured outputs, or making decisions based on multiple data sources.

For an overview of configuring your account for AI features, review how to set up your HubSpot account to adopt AI features.

Please note: you can manage AI feature access in your AI settings and configure what data is shared. Review HubSpot's AI Trust FAQs and AI Model Cards for detailed information on AI security controls, data use, and compliance.

Understand requirements

Before you begin creating and customizing agents in the agent builder, review the requirements and considerations.

• A Super Admin must toggle the following switches on in your AI settings:
  • Give users access to generative AI tools and features
  • CRM data
  • Customer conversion data
  • Files data
  • Give users access to Breeze Assistant

Create an agent in the agent builder

Create a custom agent by defining its instructions, selecting actions, and configuring the data and inputs it'll use.

1. In your HubSpot account, click More, then navigate to Agents > Agent Hub. If More doesn't appear in your account, navigate to Agents > Agent Hub directly.

2. On the Intro tab, click the Create dropdown menu on the top right and select Agents.

3. In the agent builder, configure your agent's instructions, actions, knowledge, and inputs.

Instructions

Define what the agent should do and how it should behave. Include the agent’s role, goal, approach, and expected output.

In the agent builder, enter text in the Instructions field. Clearly define the agent’s role, goal, approach, and expected output.

For example, you could add the following instructions:

Role:
You’re a customer onboarding review agent responsible for preparing internal handoffs after a deal is closed.
Goal:
Analyze customer information and summarize key details needed for a successful onboarding process.
Approach: 
Review contact and company properties, deal details, and recent activity.
Identify important context such as customer goals, purchased products, timeline expectations, and risks.
Flag any missing or unclear information that may impact onboarding.
Output:
Section 1: Customer summary (3-5 bullet points).
Section 2: Key onboarding considerations.
Section 3: Missing information or risks.
Keep responses concise, structured, and actionable.

Actions

Select the actions the agent can perform. Actions determine what tasks the agent can complete based on instructions.

1. In the agent builder, click Add action in the left panel.

2. In the right panel, click the HubSpot, Default, or MCP tabs and select your actions.

   • HubSpot: select from different types of actions (e.g., Get data, Generate, Take action). To filter the types of actions, click the Types dropdown menu and select a type (e.g., Generate).

   • Default: select from default actions such as Browsing the web or Reading your HubSpot CRM records.

     • Browse the web: this gives the agent access to browse the web.

     • Read your HubSpot CRM records: this gives the agent access to read your CRM records.

     • Write to your HubSpot CRM records: this gives the agent access to write to your CRM records.

   • MCP: connect your agent to external systems using the Model Context Protocol (MCP). Learn more about supported MCP servers.

Knowledge

Add specific use case context the agent can reference when generating outputs, such as uploaded documents, brand guidelines, knowledge vaults, or relevant CRM data.

Use the Knowledge section to provide supporting information the agent can draw from when analyzing data or generating responses. Unlike inputs, this context is available to the agent without being redefined each time it runs.

For example, an onboarding-focused agent may rely on deal details, associated company information, and recent activity, while a content-focused agent may use uploaded documents or files.

1. In the agent builder, click Add knowledge in the Knowledge section.

2. In the right panel, click Custom, Default, or Integrations and select your knowledge.

   • Custom: select a knowledge vault. Learn more about managing agent context with knowledge vaults.

   • Default: select from default context such as your brand kit or ICPs.

   • Integrations: click an integration to configure what is included.

Inputs

Define the specific data the agent uses each time it runs, such as a record, user-provided value, or information passed from another tool or process.

Use inputs to specify what the agent should act on for a given run. Unlike knowledge, inputs are provided at runtime and can vary depending on the context.

For example, an onboarding-focused agent may use inputs such as deal name, close date, or customer goals, while a content-focused agent may require a topic, audience or key message.

1. In the agent builder, click Add input in the Inputs section.
2. Click the Input type dropdown menu and select an option (e.g., CRM Object).
3. In the Label field, enter a name for the input. 

Manage agent access

Control which users have access to each agent. By default, Super Admins can edit agents and all users can run them.

If an agent’s configuration relies on other HubSpot features (e.g., blog or landing pages) that a user doesn't have access to, the agent can't be run by that user, even if the user has permission to edit or run the agent.

1. In the top left of the agent builder, click the  three vertical dots icon and select Assign access.
2. In the right panel, select an access option:
   • Owners and super admins can edit and run: only the user, who created or installed the agent, and Super Admins can edit and run the agent.
   • Owners and super admins can edit, everyone can run: only the user, who created or installed the agent, and Super Admins can edit the agent. Every user can run the agent.
   • Everyone can edit and run: any user can edit and run the agent.
   • Custom team and user access: only selected users and teams can edit or run the agent. If you select this option there will be additional access options:
     • Run and edit: selected users or teams can run and edit the agent.
     • Run: selected users or teams can run the agent.
3. When finished, click Update.

Test an agent in the agent builder

Test your agent without consuming HubSpot Credits to confirm the output meets your expectations. Review if the agent is using the correct inputs and referencing the correct data to provide the expected output. 

1. In the right panel, enter the required inputs.
2. Click Test agent.
3. In the dialog box, click Run.
4. On the Outputs tab, review the output for the following:
   • Confirm the agent follows the expected format.
   • The agent uses the expected data and context.
   • Identify any gaps, inaccuracies, or unclear responses.
5. Update the agent configuration as needed:
   • Refine instructions to improve clarity or specificity.
   • Adjust knowledge sources if relevant data is missing or incorrect.
   • Update inputs to ensure required information is included.
6. Repeat testing until the output is consistent and meets your requirements. Then continue to review estimated credit costs and set run limits.

Review estimated credit costs and set run limits

After testing the agent, review the estimated HubSpot credits required for the task. You can also set run limits to control how many credits an agent can use during execution, helping you manage credit usage across your account.

1. In the agent builder, click the Run history tab.
2. In the left panel, click an agent run.
3. In the right panel, review the estimated credits.

These estimates are provided for informational purposes only. Actual costs may vary. Learn more about reviewing estimated credit costs for agents and setting monthly run limits.

Publish a custom agent

Once you've tested your agent and confirmed the output meets your expectations, save and publish the agent to make it available for use.

1. In your HubSpot account, click More, then navigate to Agents > Agent Hub. If More doesn't appear in your account, navigate to Agents > Agent Hub directly.
2. Click the Agents tab.
3. Click Edit on the agent you want to publish.

After publishing, use the agent as part of your broader processes and include agents in other automations. Learn more about adding agents to workflows.

Run agents from other sources

After publishing your agent, you can trigger and run your agents from other sources, such as workflows or CRM cards.

1. In your HubSpot account, click More, then navigate to Agents > Agent Hub. If More doesn't appear in your account, navigate to Agents > Agent Hub directly.
2. Click the Agents tab.
3. Click Edit on the agent you want to publish.
4. To run your agent from a workflow or automation, in the Run from section, click Automate. Then, set up your workflow or automation. 
   • If you have a Starter account, run your agent from a automation in the automation side panel. Learn how to create automations in Agent Hub.
   • If you have a Professional or Enterprise account, run your agent from a workflow in the Agent Hub workflow builder. Learn how to create workflows in Agent Hub.

1. To run your agent from a CRM card directly in your CRM records. 
   • In the Run from section, click CRM cards.
   • In the right panel, click Add to a CRM card and select the object type that you'd like to run your agent from. You can add your agent to multiple object types.
     
     

Next steps

• Run agents and review output in the agent inbox
• Review estimated credit costs when using agents