Add Integation Tool - SigmaMind AI

The Add Integration Tool lets your AI agent call external apps and APIs during a live conversation. Use it to look up customer records, update CRM contacts, create bookings, trigger webhooks, or perform any real-world action exposed by a connected integration — all without interrupting the call.

When to Use

Configure this tool when your agent needs to:

Look up a customer’s record in HubSpot, Salesforce, or your own CRM
Retrieve a policy status, account balance, or order history in real time
Update a contact’s information based on what the customer says
Create a support ticket, booking, or record mid-conversation
Trigger any external API action based on conversation context

Prerequisites

Before adding an integration tool to your agent, your integration must already be connected and authenticated.

See How to add an Integration and How to Configure Authentication for setup steps.

Once the integration is connected and shows Auth connected, you can add its tools to any agent.

Steps to Add via Agent Builder

Adding an integration tool is a 3-step wizard inside the Agent Builder.

Step 1: Select the Tool

Open the Agent Builder
Click + Add Tool
Select Add Integration Tool
Choose your connected integration from the list (e.g., HubSpot)
The wizard shows all available tool actions for that integration

Each tool action displays:

The action name (e.g., get_customer_list, update_customer_info)
The HTTP method badge (e.g., GET, PATCH, POST)
The endpoint URL the action calls

Click the tool action you want to add to the agent. If your integration has multiple tools, you can add them one at a time. Example — HubSpot tools:

Action	Method	Endpoint
`get_customer_list`	`GET`	`https://api.hubapi.com/contacts/v1/lists/all/contacts/all`
`update_customer_info`	`PATCH`	`https://api.hubapi.com/crm/v3/objects/contacts/{{contact_id}}`

Step 2: Configure the Instruction

After selecting the tool, the wizard moves to the configuration screen.

Instruction (When this tool should be invoked)

Write a clear, specific instruction that tells the AI agent when to trigger this API call during the conversation.

Invoke this tool after the customer provides their name, to look up their
contact record in HubSpot before proceeding.

Call get_customer_list when the customer asks about their account status
or when you need to retrieve their contact details.

Use update_customer_info after the customer confirms a change to their
email address or phone number.

The agent uses this instruction alongside the live conversation to decide when to make the API call. A vague instruction causes the tool to fire at the wrong time or not at all.

Step 3: Map Response Values as Dynamic Variables

The final step lets you extract values from the API response and save them as {{variable_name}} variables for use in subsequent prompts or tool inputs.

View Sample Response

After the tool has been run at least once, click View sample response (from last run) to see the actual JSON returned by the API. Example — HubSpot get_customer_list response:

{
  "is-primary": true,
  "1": {
    "value": "53630cb5-e398-4c5c-978e-97b5c87f688c",
    "timestamp": 1764927922684,
    "saved-at-timestamp": 1764927922687,
    "deleted-changed-timestamp": 0
  },
  "has-more": false,
  "vid-offset": 341631764191
}

Use Copy JSON to copy the full response structure for reference when setting up your mappings.

Root Path

The Root path defines the base key in the response from which field mappings are extracted. It is auto-populated based on the tool name.

Root path: hubspot_get_customer_info

This scopes all variable names under a consistent namespace so they don’t conflict with variables from other tools.

Add Mapping

Click + Add Mapping to define which fields from the API response should be saved as variables. Each mapping row has two parts:

Response field path — the key from the JSON response you want to capture (e.g., 1.value, vid-offset)
Variable name — the {{variable_name}} the value will be stored as

Example mappings for HubSpot response:

Response Field	Saved as Variable
`1.value`	`{{contact_guid}}`
`1.timestamp`	`{{contact_timestamp}}`
`vid-offset`	`{{vid_offset}}`
`has-more`	`{{has_more_contacts}}`

Once mapped, these variables are immediately available in all subsequent prompts and tool inputs within the same agent:

"I found your account, {{customer_name}}. Your contact ID is {{contact_guid}}."

https://api.hubapi.com/crm/v3/objects/contacts/{{contact_guid}}

Reference these variables as {{variable_name}} in any subsequent prompt or tool input field.

Full Example: HubSpot Lookup + Update Flow

Scenario: An insurance renewal agent looks up the customer in HubSpot, then updates their renewal status after confirmation.

Tool 1 — `get_customer_list`

Field	Value
Instruction	Look up the customer in HubSpot after they provide their name and confirm their email address.
Root path	`hubspot_get_customer_info`
Mapping	`1.value` → `{{contact_guid}}`

Tool 2 — `update_customer_info`

Field	Value
Instruction	Call this tool after the customer confirms they want to renew, to update their record in HubSpot.
Endpoint	`https://api.hubapi.com/crm/v3/objects/contacts/{{contact_guid}}`
Body	`{ "renewal_status": "confirmed", "renewal_date": "{{renewal_date}}" }`

The {{contact_guid}} extracted from the first tool flows directly into the endpoint URL of the second tool — no manual copying or re-entry needed.

Using Dynamic Variables in Integration Tools

Variables from Extract Dynamic Variables or from a previous integration tool’s response mapping can be used anywhere in your tool configuration: In endpoint URLs:

https://api.hubapi.com/crm/v3/objects/contacts/{{contact_id}}

In request body:

{
  "email": "{{customer_email}}",
  "policy": "{{policy_number}}",
  "status": "{{renewal_status}}"
}

In headers:

Authorization: Bearer {{access_token}}

Best Practices

Write specific Instructions for each tool — if two tools have similar descriptions, the agent may call the wrong one
Always check Auth connected is showing before adding a tool to your agent — unauthenticated tools will fail silently
Use response mapping to extract IDs and keys from the first API call, so subsequent calls can reference them without re-asking the customer
Add mappings only for fields you will actually use — unnecessary variables add noise to the agent context
Test each tool independently using the Test button in the Tool Library before combining them in a live agent flow
Combine with Extract Dynamic Variables to capture customer-provided values before making API calls that need them

Troubleshooting

Issue	Fix
Auth connected not showing	Re-authenticate the integration in the Integrations section
API call returning an error	Use the sample response viewer to check the endpoint and payload format
Variable not resolving in next tool	Confirm the mapping is saved and the variable name matches exactly
Wrong tool being triggered	Rewrite the Instruction to be more specific and distinct from other tools
Response fields not appearing in sample	Run the tool at least once via the Test button to populate the last run response

​When to Use

​Prerequisites

​Steps to Add via Agent Builder

​Step 1: Select the Tool

​Step 2: Configure the Instruction

​Instruction (When this tool should be invoked)

​Step 3: Map Response Values as Dynamic Variables

​View Sample Response

​Root Path

​Add Mapping

​Full Example: HubSpot Lookup + Update Flow

​Tool 1 — get_customer_list

​Tool 2 — update_customer_info

​Using Dynamic Variables in Integration Tools

​Best Practices

​Troubleshooting