Documentation Index
Fetch the complete documentation index at: https://docs.sigmamind.ai/llms.txt
Use this file to discover all available pages before exploring further.
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.
- 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}} |
After selecting the tool, the wizard moves to the configuration screen.
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.
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
}
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
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}} |
"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.
| 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}} |
| 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}}" } |
{{contact_guid}} extracted from the first tool flows directly into the endpoint URL of the second tool — no manual copying or re-entry needed.
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}}
{
"email": "{{customer_email}}",
"policy": "{{policy_number}}",
"status": "{{renewal_status}}"
}
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 |
