Skip to content
AI Agent How-To

Home ›Connect agents to apps

Connect an AI Agent to HubSpot with n8n

Intermediate ~6 min read Last tested October 2026

Updated 2026-10-28

You connect an AI agent to HubSpot in n8n by attaching the HubSpot node as a tool on the AI Agent node. The agent can then search and read contacts. A service key or OAuth2 supplies the credential. Pair it with n8n AI agent memory when users ask follow-up CRM questions. Last tested 2026-10-20.

Prerequisites

  • An n8n Cloud account, or self-hosted n8n. The AI Agent node should be a current version. n8n deprecated the agent type setting in 1.82.0, and that v1 node is removed in n8n 3.0. Update older AI Agent nodes before you rely on this workflow.
  • A HubSpot account with super admin access, or the Developer tools access permission, if you create a service key.
  • A chat model credential in n8n, such as OpenAI or Anthropic.

Docs used for the steps below:

Steps

1. Create a HubSpot credential

n8n’s HubSpot credential supports a service key, a developer API key, and OAuth2. HubSpot deprecated the regular API key. The option can still appear in n8n. Use a service key or OAuth2 instead.

Service key, which n8n recommends for the HubSpot node:

  1. In HubSpot, open Development, then Keys, then Service Keys. The same page is under Settings, then Account Management, then Integrations, then Service Keys.
  2. Select Create service key. Enter a name.
  3. Select Add new scope, then choose the permissions this workflow needs. For contact search, include crm.objects.contacts.read. n8n lists recommended scopes for the HubSpot node on the credentials page.
  4. Select Update, then Create, and confirm.
  5. Open the new key, select Show, and copy the value.
  6. In n8n, create a HubSpot credential and paste the key into App Token.

n8n Cloud can use OAuth2 without you pasting a client secret. Select Connect my account and approve HubSpot in the browser. Self-hosted OAuth2 needs a HubSpot public app, the n8n OAuth redirect URL, and the scopes on that same credentials page.

Service keys are in public beta. Confirm the click path on HubSpot’s service key docs if the menu has moved.

2. Add the AI Agent and a chat model

  1. Add an AI Agent node. You must connect at least one tool sub-node or the agent has nothing to call.
  2. Connect a chat model with the Chat Model connector. If n8n reports “A Chat Model sub-node must be connected”, use the + Chat Model button on the open node, or the Chat Model + connector when the node is closed.
  3. For a chat box, add a Chat Trigger and leave the agent’s Prompt on Connected Chat Trigger Node.

If you still have an AI Agent v1 node that shows an agent type, update it. Current nodes all run as a Tools Agent.

Optional: attach n8n AI agent memory so a follow-up like “show that contact’s last deal” keeps the earlier search context.

3. Attach the HubSpot node as a tool

The HubSpot node docs say the node can be used as an AI tool. Connect it as a tool sub-node on the AI Agent.

  1. Choose the Contact operations, then Search contacts. The node also supports Get a contact, Create/Update a contact, and the company and deal operations listed on the HubSpot node page. Start with Search and Get so the agent cannot delete records.
  2. Select the HubSpot credential from step 1.
  3. On a parameter the model should fill, use the button at the end of the field. n8n writes the expression for you. You can instead type $fromAI() yourself. The key argument is a hint, 1 to 64 characters, letters, numbers, underscores, and hyphens only.
{{ $fromAI('query', 'Text to find a HubSpot contact', 'string') }}

$fromAI() works only on tools connected to the AI Agent node. It does not work on the Code tool.

Open the chat panel and ask for a contact you know is in the portal, by email or name. The execution log should show the HubSpot tool running and returning contact fields.

If the Prompt is Connected Chat Trigger Node and n8n reports “No prompt specified”, switch Prompt to Define below and reference the incoming chatInput field. That field name is the one named in n8n’s common issues for a null chat input.

Common errors

A Chat Model sub-node must be connected. Connect a chat model with the Chat Model connector before you execute the agent.

No prompt specified. The agent expects the Chat Trigger to supply the prompt. Set Prompt to Define below, or fix the Chat Trigger connection.

400 Invalid value for ‘content’, expected a string, got null. The prompt expression resolved to null, or chatInput on the trigger item is null. Point the expression at a field that has text.

HubSpot 401 or a missing scope. The service key does not include the scope for that operation. Edit the key, add the scope, and paste the key into the n8n credential again. Do not switch back to HubSpot’s deprecated API key.

The agent deletes or edits a contact you did not mention. The tool node includes a write or delete operation. Use Search contacts or Get a contact on the tool the agent can call.

FAQ

How do I connect an AI agent to HubSpot with n8n?

Create a HubSpot credential with a service key or OAuth2, add an AI Agent node with a chat model, and connect the HubSpot node as a tool. Set the tool to Search contacts and let $fromAI() fill the search text.

Can I still use a HubSpot API key in n8n?

HubSpot deprecated that API key. n8n may still show the option. Use a service key or OAuth2, as described on n8n’s HubSpot credentials page.

Why does the agent never call HubSpot?

The AI Agent node requires a tool sub-node, and it requires a chat model. If either connector is empty, the run fails before a search, or the model has no HubSpot tool to pick.

More in Connect agents to apps