Build an AI Agent to collect map-based fleet safety feedback

Create your interactive fleet safety map

To begin, open CARTO and click on «Create Map» or «New Map» if you're in the Maps Section. Once you're inside your new Builder map, do the following:

• Give this title to your map: Fleet Safety & Operational Map Reporting

• Create an area of interest using this SQL query in a new source. Name your new source area_of_interest. This will frame our map in a specific New York city area:

SELECT ST_GEOGFROMTEXT('POLYGON((-74.05572433530303 40.83699883356528, -74.05572433530303 40.693995875776984, -73.87821900799537 40.693995875776984, -73.87821900799537 40.83699883356528, -74.05572433530303 40.83699883356528))') as geom

• Style your new layer: remove the Fill attribute and make sure to use a light-colored Stroke that will contrast later with the vehicle data. We named this layer Area of Interest .

• Let's now add our road network data: create a new source (name it road_network) using the following SQL query:

SELECT * FROM `cartobq.docs.ny_incidents_network_agent_tutorial`

• Style your new road network using a darker color. We named this layer Roads :

• To finish adding data, let's add our vehicle collisions: add a new source (name it transportation_incidents_ny)to your map with the following SQL query:

SELECT * FROM `cartobq.docs.ny_incidents_data_agent_tutorial`

• Style your collision point-based dataset using a fixed Radius (we used roughly 4px) and simple colors for your Fill and Stroke attributes. In our own map we chose blue and white respectively. Lastly, our name for this layer is Incidents .

• Let's now add helpful click tooltips to our road and collision layers: Click on the Interactions tab and make sure Click interactions are enabled for both Roads and Incidents. Add the relevant columns and modify the tooltip column names for a polished result.

• Our map is ready! It should be a basic-yet-informative vehicle incident dashboard at this point. Our next step is to add an AI agent that will collect feedback from safety analysts.

Add an AI Agent to the map

Let's build our AI Agent. To do that, open the AI Agents tab in the top-left menu and click on Create Agent:

A menu will appear where you can configure your AI Agent. Our next step is to give our agent a clear mission. To do that, copy and paste this into the Use Case section.

This agent assists fleet managers, safety analysts, and operators in debugging vehicle trajectory data and improving operational maps. The user's goal is to review existing AV incident data overlaid with road network information on the map, identify discrepancies or errors, and provide precise, location-based feedback. The agent's role is to facilitate the submission of this feedback.

Click on Create Agent to save your changes. You’ll see it listed in the left panel and you can chat with your new agent in Testing mode.

Get and finalize the workflow for feedback reporting

Great news! This step will be very easy because we've prepared the workflow for you. Download the workflow as a .sql file and import it in your CARTO Workspace:

https://storage.googleapis.com/carto-workflows-examples/files/academy_fleet_safety_feedback_mcp_tool.sql

This workflow enables the Agent to correctly submit feedback using a series of simple steps:

• First, it retrieves the required input parameters

• Then, it validates the inputs (non-null feedback, valid WKT, etc.)

• It generates a unique identifier for each feedback

• Lastly, it appends the new feedback to a specific table in the data warehouse

Add a Save as Table component

In order for the agent to submit the feedback, you need to specify which table it will append the feedback to. Add a Save as Table component, specify your desired location, and make sure you select the Append to existing table option, so that new feedback doesn't override the existing data. Connect your component to the output of the Generate UUID component.

Add the MCP Tool Output (Sync) component to your workflow

A requisite for the AI Agent to be able to invoke this workflow is to enable it as a MCP Tool, by configuring an MCP Tool Output. To do that:

• In the Workflow editor, add the MCP Tool Output component at the end and connect it to the Generate UUID component.

• Set Type = Sync. This will make our agent wait for the response of this workflow, which should be pretty quick.

The output of this workflow should be a JSON, including the raw data returned by the workflow and the FQN of the table that contains the feedback. This allows the Agent to visualize the submitted feedback in the map!

Enable the Workflow as an MCP tool

The MCP (Model Context Protocol) standard allows us not only to provide tools for AI Agents, but also to provide context about how and when to use the tools, and how to fill the required tool parameters. Let's add that context and enable our workflow as an MCP tool.

Click on the three-dot menu in the top-right and click on MCP Tool, and use the following values to fill in the context for the agent to understand this workflow:

This agent assists fleet managers, safety analysts, and operators in debugging vehicle trajectory data and improving operational maps. It enables users to provide precise, location-based feedback directly on an interactive map.

Geographic coordinates in Well-Known Text (WKT) format representing the location of the reported issue. Must be a valid POINT or POLYGON geometry.

Detailed description of the observed issue, including context about AV behavior, map discrepancies, or operational problems. Should provide sufficient detail for debugging and resolution.

UTC timestamp when the feedback observation occurred or when the user initiated the feedback report. Must be in ISO 8601 format.

Unique identifier of the user submitting the feedback, used for tracking purposes.

Provides the output results of the submitted feedback.

Once all parameters are filled, click on Enable as MCP Tool located at the left bottom corner. Once enabled, the Workflow shows an MCP badge and becomes available to Agents (inside and outside CARTO).

Add the MCP tool to your AI Agent

Now we need to instruct the agent to use our new tool. To do that:

• Open the Fleet Safety & Operational Map Reporting map, and in the AI Agent Configuration dialog, click on Show tools — You'll see all the MCP tools you have access to.

• Find your MCP tool, it should be named like your workflow ("report_location_feedback" or similar), and click on Add. Reload the map if it doesn't appear at first.

• Verify that your workflow now appears under MCP Tools. You can expand the tool to review the description, inputs, and output metadata.

Give instructions to the Agent

To finish our agent, let's give it a prompt with a good structure and examples. This also instructs the agent how and when to use the tools we made available. Copy and paste this prompt into the Instructions panel in your agent.

# Core Behavior
- Your primary function is to guide a user to a specific location for review and then capture a clear description of their feedback on the map or incident data. Once the location and feedback are confirmed, you will immediately submit this information using the /Report_location_feedback tool. All other actions are performed only to support this core mission.

# Communication Style
- Adopt a helpful, natural, and slightly conversational tone. Your dialogue should be clear and guide the user through the process smoothly. Follow this checklist: **Acknowledge, Locate, Confirm, Submit, and Inform.**
- Use markdown when possible so users can easily read the provided details.

# The Feedback Submission Flow
1.  **Acknowledge & Locate**: When the user asks to submit feedback, your first action is to use tools to identify the Area of Interest (AOI). The AOI can be an address, coordinates, a drawn region, or the current map viewport. **If an address or coordinates are not provided, automatically use /get_spatial_filter to retrieve the viewport or a drawn region.**
2.  **Confirm Address Location**: If geocoding an address, ask for confirmation in a natural way: "I've marked the location at [Address/Coordinates]. Is this correct?"
3.  **Gather Details & Confirm**: After establishing the location, review the user's message(s) to see if the feedback description and username have already been provided.
    - **Do not ask for information you already have.**
    - If any details are missing, ask only for what is needed (e.g., "I have the feedback text, but I'll need your username to proceed.").
    - Once all three components (location, feedback, username) are gathered, confirm everything in a single message before submitting. For example: "Ok, I will submit the feedback '[User's feedback description]' for username '[username]' at the specified location. Is this correct?"
4.  **Submit**: Upon final confirmation, call the /Report_location_feedback tool. Including all parameters (location, feedback_text, timestamp and user_id)
5.  **Report Status & Inform**: After a successful submission, inform the user and guide them to the result on the map. For example: "Feedback report was successfully submitted. I've added the submitted location and details to the map, which you can inspect by hovering over the new layer. Is there anything else I can help with?"
6. **Render Results and Inform**: After the /Report_location_feedback tool returns a successful result, add a new layer to render the feedback location on the map. Once the layer has been successfully added, inform the user that the process is complete. For example: "Your feedback has been successfully submitted and is now visible on the map. You can inspect the details by hovering over the new layer. Is there anything else I can help with?"

Once the prompt is added to your agent, click on Done.

Test your Agent (editor mode)

Let's now test the agent using a semi-real case. This will let us know if everything is working correctly including the feedback submission tool, before we expose it to end users:

1. Draw an Area of Interest: Use the custom polygon mask tool to mark the area you want to report on.

2. Tell the Agent to submit some feedback about this area. Example: Incidents in this drawn region are due to failing intersection negotiation. Please submit feedback. Username: <your_username>.

3. The Agent will now start thinking and use the available tools/context to:

   1. Retrieve the area of interest (your polygon). It may ask for confirmation.

   2. Invoke the MCP Tool to submit the feedback (with the location, feedback_text, user_id and timestamp).

   3. On success, it will add a new layer to the map showing the submitted geometry.

      
4. Let's use the new AI-generated layer to verify the results: Hover on the new layer to see details about the newly submitted feedback and confirm it matches what you requested (location, feedback text, timestamp, user).

Enable your Agent to end-users

Looks like we're ready! Let's now make sure that our agent is prepared and available for viewers of our map.

• Go to Map settings for viewers and toggle AI Agent = ON as well as the Selection tool.

• Use the Preview mode if you want to test the end-user experience.

Share your AI Agent with your organization

• Click on Share and share your map with others. Make sure to click on Publish if you make any changes. The published map includes your Agent so end-users can interact with it!

• If you want, copy the link and confirm the Agent can be accessible in Viewer mode.