Last modified: September 3, 2025
In HubSpot, you can create an AI agent that will perform various actions based on your instructions. For example, you can create an agent to send an email to you every morning with notes about the day’s upcoming meetings. To perform tasks, agents rely on agent tools. Tools are like functions in a programming language: they have parameters you pass into the tool, and the tool returns an output. Tools in HubSpot are similar to the concept of tools in MCP (Model Context Protocol). An agent tool will package API calls, LLM steps, and other supporting context to enable the AI to do the job. Tools are designed to perform specific, well-defined tasks, such as querying a database, performing CRUD (Create, Read, Update, Delete) operations, or using generative AI to summarize content. In implementation terms, an agent tool is an enhanced version of a custom workflow action, which you’ll build using HubSpot’s developer project framework. This tutorial will guide you through how to start building an agent tool.

​
Prerequisites

Before getting started, you’ll need to:
  • Install the latest version of the HubSpot CLI by running npm install -g @hubspot/cli. If you’ve already installed the CLI, you can update to the latest version by running npm install -g @hubspot/cli@latest.
  • Create a developer test account from within the developer account that’s opted in to the beta.
  • Authenticate the test account with the CLI by running the hs account auth command in your terminal.

​
Build and deploy an agent tool

1

Create a project

If you’re starting from scratch, you’ll first need to create a new project. Alternatively, if you’d like to use an existing project (project version 2025.2 required), skip to the next section.To create a new project:
  1. In the terminal, run the command below to create a new project from one of the boilerplate quickstart templates.
hs project create
  1. Follow the terminal prompts to configure the project name and location, then select a template. Several template options are provided depending on how you plan to distribute your app. For the purposes of this tutorial, select the Getting stated project with marketplace app template.
  2. The project template will then be downloaded to your working directory where you can view its contents.
This project template includes all the files needed to upload a project with an app that includes a few example app features. These features include a boilerplate app card, webhook, and workflow action. For the purposes of this tutorial, these components aren’t needed, but may be helpful to review should you want to experiment with them later.
2

Add an agent tool to the project

  • If your project doesn’t have one yet, create a workflow-actions/ directory in src/app/.
  • In the workflow-actions directory, create a new JSON file for the tool configuration. The file can have any name, but must end with -hsmeta.json (e.g., my-agent-tool-hsmeta.json).
  • Build out the action configuration using the agent tools reference documentation. Be sure to include the supportedClients array along with its client, toolType, and llmConfig fields, as shown in the example code below.
{
  "uid": "agent_tool_action",
  "type": "workflow-action",
  "config": {
    "actionUrl": "https://example.com/api-endpoint",
    "isPublished": false,
    "supportedClients": [
      {
        "client": "AGENTS",
        "toolType": "GET_DATA",
        "llmConfig" : {
          "actionDescription": "Use this tool to fetch data from an external API."
        }
      }
    ],
    "inputFields": [
      {
        "typeDefinition": {
          "name": "message",
          "type": "string",
          "fieldType": "textarea"
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": false
      }
    ],
    "labels": {
      "en": {
        "actionName": "My custom agent tool",
        "actionDescription": "A description of the tool.",
        "actionCardContent": "Send a notification",
        "inputFieldLabels": {
          "message": "Notification Message"
        },
        "inputFieldDescriptions": {
          "message": "Enter the message to be sent in the notification"
        }
      }
    },
    "objectTypes": ["CONTACT"]
  }
}
As you build your tool, keep the following in mind:
  • When actively developing, you should not set your input fields to required, as required fields cannot be updated or removed once uploaded.
  • Requests to public endpoints will be made as POST requests.
  • Unlike custom workflow actions, you cannot include functions in agent tools.
  • The agent does not have access to CRM data unless explicitly given tools to get that data.
  • The agent can’t request information from the user after it’s invoked if given insufficient information to complete the task.
When you’re ready to upload to your test account, save your files, then run hs project upload. If you started with a new project, you’ll be prompted press y to create the project in the account.

​
Testing agent tools in HubSpot

There are multiple aspects of your agent tool that you’ll want to test before making it available to users. HubSpot provides two primary methods for testing: the workflows tool, and the developer tool testing agent.

​
Test with workflows

It’s recommended to start testing with a workflow to evaluate the core logic of your tool. Using workflows for testing is especially useful for testing input and output behavior, such as providing both correct and incorrect inputs to see what the result is. This is the same type of testing you would perform for a custom workflow action, as tools are custom workflow actions with additional fields for agent configuration. To test with workflows:
  1. Create a workflow.
  2. Add your tool as a workflow action.
  3. Ensure you’re passing the inputs and outputs you want to pass, then execute the workflow.
  4. Iterate on your back-end code to ensure the logic is properly handling the inputs and returning the expected outputs.

​
Test with the developer tool testing agent

Using HubSpot’s Developer Tool Testing Agent, you can test how your tool works in the context of an agent. Testing with this method will help you to better understand the LLM side of your agent tool and how it will behave for end-users prompting the agent. To use the Developer Tool Testing Agent:
  • Navigate to the Developer Tool Testing Agent in the HubSpot Marketplace.
  • Click Sign in to add to navigate to the install page in your account. Once in your account, click Add to install the agent.
  • In the pop-up banner, click Configure. Alternatively, you can click Open to open the agent page, then click Configure in the top right.
  • In the What this agent can access section, click Add tool.
Screenshot showing the Add tool button in the HubSpot agent builder
  • In the right sidebar, select your agent tool.
With your agent tool added, you can now begin testing your tool by adding a prompt to the Your message field, then clicking **Test agent. As needed, you can click Add extra instructions to add to the existing agent instructions. For example, you may want to instruct the agent to perform in specific ways or make it easier to repeatedly test something you’re trying to improve. The aspects you should test with this agent are:
  • Tool name and description clarity: test whether the LLM correctly understands when to use your tool based on its name and description, especially when compared to other default or custom tools.
  • Direct vs. indirect prompts: test both direct commands (e.g., “Use Tool X to do Y”) and more abstract, goal-oriented prompts to see if the LLM can correctly infer the user’s intent. Ideally the user doesn’t need to tell the agent to use a tool, the agent can intuit what it needs to do and just execute.
  • Parameter extraction: verify that the agent correctly identifies and extracts all required parameters from natural language prompts. The testing agent is designed to report exactly what parameters it passed to help with this verification.
  • Sequential operations: test scenarios where your tool must work in a sequence with other tools. This includes checking if the agent can correctly pass the output from one tool as the input for the next.
With each run, the agent will return its reasoning and the data it’s passing to the tools to help you troubleshoot. As you identify, issues, you can to update your llmConfig and your labels properties in your tool’s hsmeta.json file to give the LLM more clarity and specificity into what your tool does, and how to provide inputs to it.