Skip to content
HubSpot Updates

HubSpot Custom Agent Permissions: User Identity and Audit Log

November 16, 2026

What This Update Actually Is

Every custom agent you build in HubSpot now has its own user identity called an Agent User. HubSpot creates it automatically when you create the agent. No extra setup is required.

That Agent User lives in Users and Teams right alongside your human teammates. You assign it roles, permission sets, teams, and object permissions the same way you would for any new hire. The agent's Actions, Knowledge, and Connectors still define what it can do. But permissions now set a hard ceiling on how far it can reach.

Every CRM change the agent makes is recorded in the Audit Log under its own name, labeled as a Custom Agent so you can tell humans and agents apart at a glance. If the agent changed something it shouldn't have, you can restore the previous value directly from the log entry.

Important caveat: this applies to custom agents only. Customer agents, Agent Builder workflows, and third-party agents are not covered by this update.

Why HubSpot Shipped This

Here's the pattern we've seen across portals: a team builds a capable custom agent, it starts touching CRM records, and then a compliance lead or IT admin asks two questions. What is this agent allowed to do? And how do we prove what it did?

Before this update, those questions had no clean answer. Agents ran on their builder's full access. That's a governance problem. It means an agent could reach anything the builder could reach, with no independent trail.

The internal frustration is real. Humans building agents want to ship faster. Security and legal want controls before they'll approve production use. Those two things were in direct conflict until now.

Agent Users solve both sides. Builders get a clear, familiar model for setting boundaries. Compliance teams get a named actor in the Audit Log and a restore option. Everyone can move forward.

How to Use It Step by Step

  1. Find your agent's user record. Go to Settings, then Users and Teams. Each custom agent already has an Agent User created automatically. You don't need to create one.
  2. Review the default permissions. Out of the box, agents get a broad baseline set of permissions. High-risk actions like Delete are restricted by default. Check whether that baseline fits your use case before you rely on the agent in production.
  3. Tighten or extend access. Assign direct roles, permission sets, teams (including a primary team), and object permissions including custom objects. Apply the principle of least privilege: give the agent exactly what it needs to do its job and nothing more.
  4. Test in a sandbox first. Create a sandbox copy and review the agent's access there. Its roles, permission sets, teams, and object permissions carry over automatically. If a team, custom object, or property doesn't exist in the target, that assignment is dropped and the sync still completes. The agent will end up with less access, never more.
  5. Move to production with confidence. When you're satisfied with the sandbox review, copy the agent to your production portal. Permissions travel with it.
  6. Monitor the Audit Log. Go to Settings, then Account Management, then Audit Log, then CRM Data. Use the Actor filter to find your agent's name. Open any entry to see the record, the action, the timestamp, and the before and after values. Restore any value the agent changed if you need to.

What It Touches in Your HubSpot Strategy

This update touches more than just AI settings. It ripples into how you govern your entire CRM.

Users and Teams structure matters more now. The roles and permission sets you built for humans are the same ones you'll apply to agents. If your Users and Teams setup is loose or undocumented, that problem will show up in every agent you deploy. Tightening your human permission model first makes your agent permission model cleaner from day one.

Key Takeaway

Permissions are a ceiling, not a capability. Giving an agent a wider permission set doesn't give it new abilities. Its Actions, Knowledge, and Connectors still define what it can actually do. Permissions just cap how far those capabilities can reach inside your CRM.

The Audit Log is now a governance tool, not just a troubleshooting tool. Compliance teams can filter by agent actor, see property source values labeled as Custom Agent, and restore records. That changes the conversation with legal and IT from 'can we trust this?' to 'here's the full trail.'

Custom objects are covered. You can assign object permissions for custom objects to an agent, which means agents operating in complex data models are fully within scope. If you're building agents that touch custom objects, review those permissions specifically before going live.

If you're also running Customer Agent for SMS or other channel-specific agents, note that those aren't covered by this update. Agent Users apply to custom agents only. For more context on how HubSpot's agent ecosystem is expanding across channels, see our breakdown of Customer Agent for SMS.

The bigger strategic point here is that agentic automation only scales when humans stay in control of the trajectory. If you're thinking through how to adopt AI in your sales and marketing stack without losing oversight, our article on human-centered AI and trajectory before speed is worth your time.

Key Takeaway

Agent Users don't consume a paid seat. You can deploy multiple custom agents with scoped permissions at no additional seat cost, which removes one of the common objections to expanding agent use across your portal.

Who Should Care Most

This update matters most to the humans who build, approve, or audit automation in a HubSpot portal.

  • HubSpot admins: Review every custom agent's Agent User in Users and Teams right now. Default permissions are broad. Don't wait for a compliance review to discover an agent had more access than it needed.
  • RevOps and operations leaders: This is the governance layer that makes agentic automation deployable at scale. Use it to document which agents have access to which objects, the same way you document human roles.
  • Compliance and IT teams: The Audit Log now gives you a named actor, a property source label, and a restore option for every change a custom agent makes. You have the proof trail you've been asking for.
  • Growing companies on Starter or Professional tiers: Agent Users are available across nearly every HubSpot tier. If you've held off on deploying custom agents because of governance concerns, that blocker is now removed.

If your organization has been skeptical about letting AI agents write to your CRM, this update is the conversation-changer. You now have the same controls for agents that you have for humans.

George's Take

Every time I walk into a portal where custom agents are running, the first question I ask is who's accountable for what the agent does. Before this update, the honest answer was usually 'the builder, sort of.' That's not governance. That's hope. What HubSpot shipped here is the foundation that makes agentic automation a real business tool and not just a demo. When you can point your compliance team to a named actor in the Audit Log, show them the before and after values, and restore any change with two clicks, the conversation shifts from 'should we allow this?' to 'how do we scale it responsibly?' That's the shift we need to help the humans on our teams flourish with AI, not get steamrolled by it.

“Real governance isn't about slowing down AI. It's about giving humans the controls they need to trust it enough to actually use it.”
— George B. Thomas

If you're setting up custom agents in a portal that wasn't built with governance in mind from the start, you may need to revisit your foundation first. Our HubSpot implementation checklist walks through how to build a portal your team and your agents can operate in with confidence.

Want help scoping permissions for your custom agents or reviewing your Users and Teams structure before you go live? Book a strategy call with the Sidekick team and we'll walk through your portal together.

Frequently Asked Questions

What is a HubSpot Agent User?

An Agent User is the user identity HubSpot automatically creates for each custom agent you build. It lives in Users and Teams alongside your human teammates. You assign it roles, permission sets, teams, and object permissions the same way you would for a person. It doesn't consume a paid seat.

Do HubSpot custom agents now have their own Audit Log entries?

Yes. Every CRM change a custom agent makes is recorded in the HubSpot Audit Log under the agent's own name, labeled as a Custom Agent. Admins can filter by agent, see before and after values for any property, check the Property Source, and restore a previous value directly from the log entry.

Can a HubSpot custom agent exceed its assigned permissions?

No. Permissions are a hard ceiling. An agent can never exceed its assigned permissions regardless of the Actions, Knowledge, or Connectors you give it. Those tools define what the agent can attempt to do, but permissions determine how far it can reach inside your CRM.

Does a HubSpot Agent User cost an extra seat?

No. Agent Users don't consume a paid seat in HubSpot. You can create multiple custom agents with scoped permissions at no additional seat cost. Each portal provisions its own Agent Users, and they aren't shared or copied between portals.

What happens to a custom agent's permissions when it's copied to a sandbox or another portal?

The agent's roles, permission sets, teams, and object permissions are applied to its new Agent User in the target portal. If a team, custom object, or property doesn't exist in that portal, the assignment is dropped and the sync still completes. The agent always ends up with less access, never more.

Does the new Agent User permission model apply to Customer Agents or third-party agents?

No. This update applies to custom agents only. Customer agents built for end-user support, Agent Builder workflows, and third-party agents are not covered. If you're running Customer Agent for SMS or similar channel tools, those operate under a different model.

Free, In Your Inbox

Get Every HubSpot Update

No spam. Unsubscribe anytime.

Comments

Join the conversation. Share what resonated, ask questions, or add your perspective.

Leave a Comment

We'd love to hear your thoughts. Your comment will appear after review.

Never shared publicly.

0/2,000

Ready To Talk?

Need Help Making Sense of HubSpot?

Sidekick Strategies helps your humans get the most out of every HubSpot update, feature, and tool. Let's make your portal work harder for you.