Agent tools

Use HubSpot agent tools in Ravenna rules to search contacts, look up companies, retrieve deals, and surface CRM data during ticket conversations.

HubSpot provides AI agent tools for CRM data retrieval and customer information lookup. Reference these tools in agent rules using @ mentions to enable automated customer account lookups and deal tracking.

---

Available tools

Search contacts

Searches for contacts in HubSpot by email address, name, or other criteria. Returns contact details including email, name, company, and associated properties.

Tool name: @Search contacts with HubSpot

Common use cases:

• Look up customer information by email
• Verify contact existence before creating tickets
• Retrieve customer details for support requests
• Find contact IDs for other operations

Example rule:

When a user asks about a customer account, use @Search contacts with HubSpot to find the contact by email. Provide the customer's name, company, and account status to the user.

CopiedCopy prompt

Search companies

Searches for companies in HubSpot by domain, name, or other criteria. Returns company details including name, domain, industry, and associated properties.

Tool name: @Search companies with HubSpot

Common use cases:

• Look up company information
• Verify company existence
• Retrieve company details for account management
• Find company IDs for deal lookups

Example rule:

When a user asks about a company account, use @Search companies with HubSpot to find the company by domain. Summarize the company details and recent activity.

CopiedCopy prompt

Search deals

Searches for deals in HubSpot by deal name, stage, or other criteria. Returns deal details including amount, stage, close date, and associated contacts.

Tool name: @Search deals with HubSpot

Common use cases:

• Look up deal status
• Track sales pipeline
• Retrieve deal details for account reviews
• Find deals by customer or stage

Example rule:

When a user asks about deal status, use @Search deals with HubSpot to find active deals for the customer. Provide a summary of deal stages, amounts, and expected close dates.

CopiedCopy prompt

List deals

Retrieves a list of deals from HubSpot with optional filtering by stage, owner, or date. Returns paginated deal information for analysis and reporting.

Tool name: @List deals with HubSpot

Common use cases:

• Review active deals pipeline
• Generate deal reports
• Track deals by owner or stage
• Monitor sales activity

Example rule:

When a user asks for a pipeline overview, use @List deals with HubSpot to retrieve active deals. Group by stage and provide a summary of total value and count per stage.

CopiedCopy prompt

Get deal

Retrieves detailed information about a specific deal by ID. Returns complete deal properties, associated contacts, companies, and timeline.

Tool name: @Get deal with HubSpot

Common use cases:

• Get complete deal details
• Review deal history
• Check deal associations
• Analyze deal properties

Example rule:

When a user provides a deal ID, use @Get deal with HubSpot to retrieve the complete deal information. Provide a detailed summary including stage, amount, contacts, and recent activity.

CopiedCopy prompt

List owners

Retrieves the list of HubSpot users who can own contacts, companies, or deals. Returns owner names and IDs for assignment and filtering operations.

Tool name: @List owners with HubSpot

Common use cases:

• Find owner information for deal assignment
• Reference owners in queries
• Build owner-specific reports
• Validate owner assignments

---

Setup

1. Install HubSpot integration

   Follow the HubSpot setup guide to connect your HubSpot account to Ravenna.

2. Configure agent

   Navigate to your agent’s settings and ensure HubSpot tools appear in the Tools section under Capabilities.

3. Create rules

   Write rules that reference HubSpot tools using @ mentions.

4. Test tools

   Test your rules in a controlled environment to verify tools work as expected.

---

Best practices

• Combine contact, company, and deal searches for comprehensive customer lookups
• Use search tools before attempting to get specific records by ID
• Consider pagination when listing large numbers of deals
• Provide context about what the user asked for when presenting results
• Format CRM data clearly for easy comprehension

Learn more about configuring agents and writing effective rules