← All documentation

Agent guide

The Plugsync AI agent helps you configure connectors, identity strategies, field mappings, and event handlers — all in natural language. This guide explains how to get the most out of it.

Where the agent lives

Inside any connector you’ll find an Agent tab. Type or paste a description of what you’re trying to integrate; the agent proposes a configuration and explains its reasoning. You stay in control — every change is staged in a draft revision until you approve it.

What the agent is good at

• Field mapping suggestions. Paste a sample event payload and the agent matches fields to HubSpot properties, including custom objects and associations.
• Identity strategy selection. The agent recommends match_by_email, match_by_vat, or composite-key strategies based on the data you describe.
• Event handler scaffolding. Tell the agent the events you want to handle and it creates the handler stubs in the right shape.
• Troubleshooting failed events. Paste an error from the dashboard and the agent explains the root cause and proposes a fix.

How to talk to it

Treat it like a thoughtful junior engineer who has read every HubSpot doc but has never seen your business. Tell it:

1. What system you’re connecting (Shopify, custom ERP, internal app).
2. What entities you care about (contacts, companies, deals, custom objects).
3. The shape of your data (paste a sample payload — JSON or just describe the fields).
4. Any constraints (compliance, multi-store, custom identity rules).

The more concrete you are, the better the proposal.

Example prompt

“I’m syncing customers from a custom Italian ERP. Each customer has VAT number, name, address, PEC, and Codice SDI. They map to HubSpot Companies. Use VAT as the identity key, and store the PEC and SDI on the company in custom properties named pec and codice_sdi.”

The agent will respond with a draft mapping and identity config. Click Apply to stage it as a new revision, or ask follow-up questions to refine.

What the agent will not do

• It will not push changes to production without your explicit approval.
• It will not invent HubSpot custom properties that don’t exist — it will tell you they need to be created.
• It will not ignore your existing connector revisions; every change creates a new draft.

Tips

• Use /help in the agent chat for in-context shortcuts.
• Save useful prompts as snippets for reuse across connectors.
• If the agent gets something wrong, tell it specifically what was wrong and it usually self-corrects.