HailTrace Integration

Connect your AI agents to HailTrace storm data for automated hail and severe-weather workflows. Agents use five read-only tools to query recent storms, impact polygons, affected ZIP codes, and severity scores.

Overview

The HailTrace Integration authenticates with a single API key per tenant and creates five read-only tools automatically on connection. Because HailTrace is a data source only, there are no write operations or safety-control warnings.

Tools Created on Connection

Tool	Description
hailtrace_get_recent_storms	List recent hail storms within a date range and region
hailtrace_get_storm_details	Get full details for a single storm event
hailtrace_get_storm_polygon	Retrieve the geographic impact polygon for a storm
hailtrace_get_impacted_zipcodes	List ZIP codes affected by a storm
hailtrace_get_storm_severity	Get the severity score for a storm event

info

HailTrace Integration requires the custom.hailtrace feature code on your subscription.

Getting Started

Prerequisites

Before connecting HailTrace:

1. Subscription feature code - Your tenant must have custom.hailtrace enabled
2. HailTrace API key - Obtain an API key from your HailTrace account
3. Control Bridge Admin Access - You must be a Control Bridge administrator to configure the integration

Step 1: Navigate to HailTrace Settings

1. Navigate to Capabilities > Connections > HailTrace
2. The page shows an empty state with prerequisites and a Connect HailTrace button

Step 2: Enter Your API Key

1. Click Connect HailTrace
2. Enter your HailTrace API key in the API Key field
3. Click Connect - the system validates your key against the HailTrace API before saving

While validation is running, a spinner displays "Validating key with HailTrace...". If the key is invalid, the HailTrace error message appears inline so you can correct it without leaving the page.

Step 3: Review the Connected State

Once connected, the page displays:

Field	Description
Status	Connection health (active / error)
Account Name	Account name returned by HailTrace, if available
Connected By	The admin who created the connection
Created	Connection creation date

The five HailTrace tools are listed below the connection card. All tools are read-only - none carry write-tool warning styling.

Step 4: Assign Tools to Agents

1. Navigate to Workforce > Agents > Agents & SMEs
2. Edit the agent that should use HailTrace data
3. In the Tools section, find the five HailTrace tools
4. Enable the tools the agent needs
5. Save the agent

Managing the Connection

Test Connection

Click Test Connection on the connection card to verify the stored API key is still valid. The result shows current connectivity status and any error returned by HailTrace.

Update API Key

To rotate your API key:

1. Click Update API Key
2. Enter the new key in the form
3. Click Update - the new key is validated before replacing the old one

Disconnect

Click Disconnect to remove the integration. This soft-deletes the connection and removes all five HailTrace tools from your tenant. Agents that had those tools assigned will no longer be able to call them.

warning

Disconnecting removes the five tools immediately. Agents mid-execution that call a HailTrace tool after the disconnect will receive a tool-not-found error.

Execution Logs

The HailTrace connection page includes an Execution Logs section that shows recent tool calls made by your agents.

1. Scroll to the Execution Logs section on the connection page
2. Logs are fetched from GET /api/console/hailtrace/logs
3. Each entry shows the tool name, execution time, status, and associated agent

Use these logs to verify that agents are querying the correct storms and to diagnose tool failures.

Troubleshooting

Invalid API Key (400 / 401)

Problem: Connection fails with an authentication error from HailTrace

Solutions:

1. Verify the API key is copied correctly with no leading or trailing spaces
2. Confirm the key is active in your HailTrace account dashboard
3. Generate a new key in HailTrace and use Update API Key to replace it

Connection Shows Error Status

Problem: The connection card shows an error status after previously working

Solutions:

1. Click Test Connection to get the current error message from HailTrace
2. If HailTrace reports an expired or revoked key, rotate the key using Update API Key
3. Check HailTrace's status page for service outages

Tools Not Appearing in Agent Configuration

Problem: HailTrace tools do not appear when editing an agent

Solutions:

1. Verify the connection status is active on the HailTrace page
2. Confirm your subscription includes the custom.hailtrace feature code
3. Refresh the page and try again

Related Topics

• Tools Overview - All available agent tools
• Agents - Configure agents to use tools
• Agent Executions - View tool execution logs