Skip to main content

​
Introduction

Custom tools are the bridge between your AlloMia voice agent and your clinic’s essential systems. By configuring a tool, you enable the agent to securely interact with external APIs (Application Programming Interfaces) to fetch data, update records, or trigger actions. This guide walks you through the process of creating and configuring a new custom tool.

​
Step 1: Define Name and Description

Start by giving your tool a clear, descriptive name that reflects its purpose. This name will appear in the tools list and when assigning it to agents. Naming Requirements:
  • Must start with a lowercase letter
  • Can contain only letters and numbers (no spaces or special characters)
  • Should be descriptive and concise (e.g., fetchPatientRecord, checkCalendarAvailability)
Next, add a detailed description explaining what the tool does. This is crucial because:
  • It helps others understand the tool’s purpose and functionality
  • The AI uses this description to determine when and how to use the tool during conversations
Write your description as if explaining when and how the AI should use this tool, including potential triggers and actions. Good description examples:
  • Checks the clinic calendar for available appointment slots on a specific date
  • Retrieves patient contact information from the EHR system using a patient ID
  • Sends appointment reminder notifications via the clinic’s SMS system

​
Step 2: Configure the API Endpoint

Define how your tool will connect to the external system:

​
1. Select the HTTP Method:

Choose the appropriate method for your API request:
  • GET: For retrieving data (e.g., fetching patient records, checking available slots)
  • POST: For creating data or sending commands (e.g., booking appointments, sending messages)
  • PUT: For updating existing data (e.g., modifying patient information)
  • DELETE: For removing data (e.g., canceling appointments)

​
2. Define the URL:

Enter the complete API endpoint URL. You can use variable placeholders (enclosed in curly braces) that will be populated at runtime. Example: https://api.myclinic.com/patients/{patientId}/appointments Variables in the URL path will be replaced with actual values during execution.

​
Step 3: Set Execution Mode

Decide how the agent should handle the tool’s execution:

​
Synchronous vs. Asynchronous:

  • Synchronous (default): The agent waits for the tool’s response before continuing the conversation. Best for quick API calls where the agent needs the data immediately to respond to the caller.
  • Asynchronous: The agent can continue the conversation while waiting for the API response. Better for operations that might take longer, allowing the agent to maintain engagement with the caller.
Toggle ‘Asynchronous Execution’ on if you want the agent to continue the conversation while the tool executes in the background.

​
Step 4: Configure Request Headers

Many APIs require specific HTTP headers to be sent with each request:

​
Common Headers:

  • Content-Type: Usually set to ‘application/json’ for sending JSON data
  • Accept: Set to ‘application/json’ to indicate you expect a JSON response
To add a header:
  1. Click ‘Add Header’
  2. Enter the header name (e.g., ‘Content-Type’)
  3. Enter the header value (e.g., ‘application/json’)
You can add as many headers as needed for your specific API requirements.

​
Step 5: Configure Request Body

For POST and PUT requests, you’ll typically need to send data in the request body:

​
JSON Body Format:

Enter the JSON structure that your API expects. You can include variables that will be replaced with actual values. Example: Your JSON might look like this:
  • “patientName”: “VARIABLE_PATIENT_NAME”
  • “appointmentDate”: “VARIABLE_DATE”
  • “appointmentTime”: “VARIABLE_TIME”
  • “notes”: “VARIABLE_NOTES”
During a conversation, the agent will replace these placeholder variables with actual values collected from the caller or from context.

​
Step 6: Configure Variables

Define variables that your tool will use by setting up parameters the agent can extract from the conversation:
  1. Add each required variable (e.g., ‘patientId’, ‘appointmentDate’)
  2. Define the expected data type (string, number, boolean, etc.)
  3. Mark whether the variable is required or optional
These variables will be dynamically filled with data gathered during the conversation and inserted into your API request (URL, headers, or body).

​
Step 7: Configure Authentication

Securely connecting to external APIs is vital. Navigate to the ‘Authentication’ section to set up the appropriate method:
  • API Key: For simple key-based authentication
  • Bearer Token: For JWT or OAuth token-based authentication
  • Basic Authentication: For username/password authentication
Refer to the ‘Configuring Tool Authentication’ guide for detailed setup instructions for each method.

​
Next Steps

You’ve configured the core elements of your custom tool! The next critical steps are:
  • Testing your tool thoroughly (‘Testing Your Custom Tools’ guide).
  • Connecting the tool to your voice agents (‘Connecting Tools to Voice Agents’ guide).