Optimizing rapid response hubs placement with AI Agents and Location Allocation

Generate a Workflow

For this tutorial, we will use a pre-built template that examines potential rapid response facilities in Connecticut and pinpoints the optimal sites for maximising network coverage based on specific constrains. In this case, demand is modelled using H3 cells, where the density of cell towers within each hexagon reflects network needs.

To load the template, navigate to the Workflows tab and click Create new workflow > From template. In the search bar, enter 'Location Allocation - Maximize Coverage' and select the template from the results.

Next, choose the CARTO Data Warehouse connection (or one of your own connections) and click Create Workflow to get started.

Include additional components

Once you have explored the workflow, go to the Components section, drag and drop and connect the following:

• Save as Table: to write the results of the analysis to a non-temporary location.

• MCP Tool Output: to define the output of the workflow when used as an MCP Tool by agents. In this case, the output of the tool will reflect the selected optimal locations for rapid response hubs and their assigned demand points (H3 cells of specific cell tower density). Since this process may take some time, select the Async mode.

Add custom variables

When a user interacts with the agent and asks for specific budget constraints, the agent automatically passes the corresponding variable values to the workflow, which then runs the analysis and produces results tailored to that request. We then need to define which are the variables the agent can configure. To do this, go to the upper-right corner next to Run and find Variables. We will allow tailoring the following:

• radius : maximum distance that a facility can cover (in kilometers)

• budget : maximum budget allowed for opening facilities (in dollars)

• max_facilities : maximum number of facilities to be opened

Remember to set up default values and enable the MCP scope for all three of them as in the screenshot below.

Then, specify the variables in the Location Allocation component using {{@variable_name}} as seen below:

Configure the Workflow as MCP Tool

The last step is to enable the Workflow as an MCP Tool. Click the three dots in the top-right section and select MCP Tool. Then, fill in the context the Agents will have when this tool is available to them: this includes a description of what the tool does, and what are its inputs and outputs.

Help network planners determine the optimal locations for Rapid Response Hubs, ensuring that each area of the network is monitored and maintained efficiently through Location Allocation. More specifically, we aim to maximize network coverage so that whenever an emergency occurs (i.e. outages, equipment failures, or natural disaster impacts), the nearest facility can quickly respond and restore service. 

Maximum distance that a facility can cover in kilometers.

Maximum budget allocated to open new facilities in dollars.

Maximum number of facilities to open.

The optimal assignments: how many demand is provided to each demand point (cell tower areas) from each facility (rapid response hubs), together with the linestring geometry that connects both.

Enable the workflow as an MCP Tool by clicking the option in the bottom-left corner. You should then see an MCP Tool enabled flag next to the Share bottom in the upper-right side of the canvas.

Build an interactive map

In the AI Agent tab, click on New AI Agent, then on New Map. A Builder map will be created. Before configuring the agent, we will first add layers to this map that will help understanding the results.

Rename the map to Location Allocation - Maximize Coverage and add the following layers by selecting Add source from > Custom SQL query in the left-bottom corner. Select the CARTO Data Warehouse connection:

• Area of Interest: Connecticut counties

SELECT * FROM cartobq.docs.connecticut_counties

• Candidate facilities: Rapid Response Hubs

SELECT * FROM cartobq.docs.connecticut_candidate_facilities

• Demand points: Cell tower density (H3 cells)

SELECT * FROM cartobq.docs.connecticut_demand_points

Style the map as you wish and add the following widgets:

• Cost of open each facility: a category widget that shows the cost of opening values of each of the facilities. Aggregate the cost_of_open data by uuid using the SUM operation. This is the most important widget, as we are instructing the agent to filter the widget and show only selected facilities.

You can add more widgets on your own, such as:

• Total cost of open: a formula widget that sums the cost_of_open values of the facilities.

• Capacity: a histogram widget that shows the capacity distribution of the facilities.

• Demand per county: a pie widget that sums the num_antennas (demand) in all H3 cells for each county_name.

You should end up with something like this:

Add the AI Agent

Now, go to the AI Agent menu on the left side, click on Create Agent, and provide the following instructions:

Help network planners determine the optimal locations for Rapid Response Hubs, ensuring that each area of the network is monitored and maintained efficiently through Location Allocation. More specifically, we aim to maximize network coverage so that whenever an emergency occurs (i.e. outages, equipment failures, or natural disaster impacts), the nearest facility can quickly respond and restore service.

The agent must compute optimal assignments between facilities and demand points based on user-defined constraints.

## User-Defined Constraints
The following parameters must be provided by the user to guide the analysis:
- Coverage radius: The maximum distance (in kilometers) that each facility can effectively cover.
- Total budget: The maximum amount (in dollars) available for establishing new facilities.
- Number of facilities: The maximum number of Rapid Response Hubs to deploy.

### Instructions:
- Ensure all user inputs are correctly provided before execution.
- Pay close attention to the units of each variable—perform any necessary conversions (e.g., if a user specifies a 1000-meter radius, convert it to 1 kilometer).
- Before executing, the Agent must request user confirmation prior to invoking the /location_allocation_maximize_coverage tool.


## Post-Execution Steps
After obtaining results from the tool, the agent must:
- Add a new map layer showing the resulting facility–demand point assignments.
- Add a new map layer that highlights H3 cells **not** covered by facilities.
- Filter the widgets to display only the opening costs for the selected facilities and the demand per covered demand point (h3 cell).
- Provide summary statistics using the template SQL queries below:
	- Calculate the cell tower coverage percentage by comparing total demand (demand in the Cell Tower Density layer) with the assigned demand (from the tool output)
    - Calculate the cost of opening selected facilities
    - Provide the number of selected facilities
    
### Template SQL Queries
Always use this templates to provide statistics. Replace FQN with the fully qualified name of the output table generated by the /location_allocation_maximize_coverage tool.
1. Compute Total Opening Cost and Number of Selected Facilities
````
SELECT SUM(cost_of_open) as total_cost_of_open, COUNT(facility_id) as num_facilities
FROM (
  SELECT DISTINCT facility_id 
  FROM `FQN`
) AS selected
JOIN (
  SELECT uuid, cost_of_open 
  FROM `cartobq.docs.connecticut_candidate_facilities`
) AS facilities
ON selected.facility_id = facilities.uuid;
`````
2. Compute Coverage Percentage
````
WITH t1 AS (
  SELECT SUM(num_antennas) AS total_demand 
  FROM `cartobq.docs.connecticut_demand_points`
),
t2 AS (
  SELECT SUM(num_antennas) AS assigned_demand 
  FROM (
    SELECT DISTINCT dpoint_id 
    FROM `FQN`
  ) AS assigned
  JOIN (
    SELECT h3, num_antennas 
    FROM `cartobq.docs.connecticut_demand_points`
  ) AS demand
  ON assigned.dpoint_id = demand.h3
)
SELECT 
  (assigned_demand / total_demand) * 100 AS coverage_percentage
FROM t1, t2;
````

## General considerations
- Always confirm user inputs before execution.
- Always update the FQN with the latest output from the /location_allocation_maximize_coverage workflow.
- Ensure map layers and widgets are synchronized with the new results. Clear all widgets before calling the /location_allocation_maximize_coverage tool and filter them to only show results for selected facilities.

Also, make sure to enable the Query sources for insights option so that the agent can run SQL queries via the map's connection, for analysis and creating new sources and layers.

Add the MCP Tool to your Agent

Before finishing, we need to let the agent use the MCP Tool. To do this, click on Show tools and select the location_allocation_maximize_coverage tool we just created.

Click on Create Agent and that's it! Now, we are ready to test it.

Enable AI Agents for viewers

To share the agent with end users, find the Map settings for viewers icon next to the Preview top-right bottom and enable the AI Agent option. Then click on Preview to see how it looks like.