--- title: "Connect Hover to AI Agents: Automate Estimates and Inspections" slug: connect-hover-to-ai-agents-automate-estimates-and-inspections date: 2026-11-04 author: Nidhi KN categories: ["AI & Agents"] excerpt: "Learn how to connect Hover to ai agents using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows." canonical: https://truto.one/blog/connect-hover-to-ai-agents-automate-estimates-and-inspections/ --- # Connect Hover to AI Agents: Automate Estimates and Inspections You want to connect Hover to an AI agent so your system can independently process blueprints, request property captures, download 3D measurements, and generate roofing waste estimates based on historical context. Here is exactly how to do it using Truto's `/tools` endpoint and SDK, bypassing the need to build and maintain a custom REST integration from scratch. Giving a Large Language Model (LLM) read and write access to your Hover instance is a complex engineering challenge. You either spend weeks building, hosting, and maintaining a custom connector, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on [connecting Hover to ChatGPT](https://truto.one/connect-hover-to-chatgpt-manage-property-captures-and-measurements/), or if you are building on Anthropic's models, read our guide on [connecting Hover to Claude](https://truto.one/connect-hover-to-claude-sync-3d-cad-exports-and-blueprint-jobs/). For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your [agent framework](https://truto.one/choosing-the-right-ai-agent-framework-langchain-vs-crewai/). This guide breaks down exactly how to fetch AI-ready tools for Hover, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the [Vercel AI SDK](https://truto.one/connecting-vercel-ai-sdk-to-saas-tools/), and execute complex construction and estimation workflows. For a deeper look at the architecture behind this approach, refer to our research on [architecting AI agents and the SaaS integration bottleneck](https://truto.one/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/). ## Why a Unified Tool Layer Matters for Agent Safety Before writing a line of integration code, decide what layer your agent talks to. This choice determines how reliable and safe your production system will be. Direct API tools - exposing raw Hover endpoints directly to the LLM - look convenient but they push provider-specific quirks directly into the model's context window. The model has to remember that Hover access tokens belong to the organization and require specific `current_user_id` query parameters, or that requesting 3D models requires polling a state machine. Every one of those architectural quirks is a hallucination waiting to happen. A [unified tool layer](https://truto.one/building-reliable-ai-agents-with-unified-tool-definitions/) collapses these complexities behind a standardized schema. Your agent sees `create_a_hover_capture_request` and `list_all_hover_measurements_json` with strictly typed JSON schemas. That gives you concrete safety wins: 1. **Deterministic input validation.** Every tool has a strict JSON schema. Invalid arguments are rejected before they hit the Hover API, so a broken tool call fails fast instead of creating malformed jobs. 2. **Smaller attack surface for [hallucination](https://truto.one/reducing-llm-hallucinations-with-structured-tools/).** The LLM only ever chooses from stable function names. It never invents query parameters or guesses at pagination cursors. 3. **Framework agnosticism.** Because the tools are served via a standard API endpoint (`/tools`), they can be consumed by LangChain, Vercel AI SDK, or custom multi-agent orchestrations seamlessly. ## The Engineering Reality of the Hover API Giving an LLM access to external property data sounds simple in a prototype. In production against complex operational systems like Hover, standard REST assumptions collapse. Hover's API introduces several specific integration challenges. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning capabilities. ### The Asynchronous Polling Trap LLMs operate synchronously in a request-response paradigm. They expect to ask for a file and receive it. Hover's architecture is deeply asynchronous. When a user captures a property via the Hover app, or when you upload a blueprint, the resulting 3D models and measurements are not immediately available. Jobs move through uploading, processing, and complete states. An agent cannot simply call `list_all_hover_measurements_json` immediately after a capture request. It must know to call `get_single_hover_job_by_id`, check the `state` field of the nested models, and only attempt to download artifacts once the state is `complete`. Exposing this state machine directly to an LLM without strict tool descriptions results in infinite retry loops and hallucinated artifact links. ### Organizational Tokens vs User Context In Hover, access tokens belong to the organization, not the individual user. However, many write operations - like creating jobs, initiating blueprints, or sharing workflows - require tracking which specific user initiated the action for audit and notification purposes. To bridge this, the Hover API requires you to pass `current_user_id` or `current_user_email` as parameters on almost every state-mutating call. If you simply give an LLM a generic OpenAPI spec, it will constantly forget to include the user context, resulting in HTTP 400 errors. Truto's proxy layer normalizes this by explicitly requiring these fields in the tool schemas exposed to the LLM, forcing the agent to provide the context before the request fires. ### Multipart Form Data Complexity Creating a job directly in Hover (rather than sending a capture request) requires sending data as `multipart/form-data` instead of standard `application/json`. Standard LLMs cannot construct multipart payloads natively; they generate JSON function arguments. Truto abstracts this away entirely. The agent outputs standard JSON tool arguments, and the proxy layer seamlessly translates this into the multipart form payload the Hover API expects, eliminating a major source of integration failure. ## Fetching Hover Tools via Truto To give your agent access to Hover, you do not need to hardcode specific API routes. Instead, you query Truto's `/tools` endpoint for the specific integrated account. This returns an array of fully-formed function tools that map directly to the underlying product's API endpoints, complete with descriptions and JSON schemas. Here is how you fetch and bind these tools using TypeScript and LangChain: ```typescript import { ChatOpenAI } from "@langchain/openai"; import { TrutoToolManager } from "truto-langchainjs-toolset"; async function initializeHoverAgent(integratedAccountId: string) { // 1. Initialize the Truto Tool Manager with your API key const toolManager = new TrutoToolManager({ apiKey: process.env.TRUTO_API_KEY, }); // 2. Fetch the tools for this specific Hover connection // We filter to just the methods we want the agent to access const hoverTools = await toolManager.getTools(integratedAccountId, { methods: ["read", "write", "custom"] }); // 3. Initialize the LLM const llm = new ChatOpenAI({ modelName: "gpt-4-turbo", temperature: 0, }); // 4. Bind the fetched tools directly to the LLM const llmWithTools = llm.bindTools(hoverTools); return { llmWithTools, hoverTools }; } ``` In this pattern, the agent has no concept of REST, OAuth, or multipart forms. It only sees a set of callable functions. ## Hover Hero Tools for AI Agents Below are the most critical Hover tools you should expose to your agent for estimation and property workflows. These represent the highest-leverage operations within the platform. ### 1. Create a Capture Request `create_a_hover_capture_request` This is the recommended entry point for new jobs. It initiates a property capture by creating a draft job in the organization and sending an email or SMS invitation to a designated user to perform the physical photo capture. It requires the target user's email and the location details. > "Send a capture request to contractor@example.com for the property at 123 Main St, Springfield. Make sure to log it under my user ID." ### 2. Show Job Details `get_single_hover_job_by_id` This tool returns the complete state of a specific job. Crucially, it includes each model (structure) on the property, its current processing state, the deliverable type, and links to all generated artifacts (like measurements and CAD exports). Agents must use this to poll for completion. > "Check the status of job 98765. Are the 3D models complete yet? If so, get the IDs of the complete models." ### 3. Get JSON Measurements `list_all_hover_measurements_json` Once a model is complete, this tool pulls the highly structured measurement data (roof facets, siding areas, pitches, lengths) in JSON format. This is the primary method for pulling data into external estimation systems. > "Fetch the full JSON measurements for model ID 456123. I need to know the total roof square footage and the linear feet of the ridges and hips." ### 4. Get Roof Waste Factors `list_all_hover_roof_waste_factors` This tool uses Hover's internal algorithm to recommend a roof waste percentage based on input measurements. It takes the roof square footage, step flashing, rakes, valleys, and hips as inputs. Agents can pipe the output of the JSON measurements tool directly into this tool. > "Calculate the recommended roof waste factor using 2500 sq ft for the roof, 50 linear feet for step flashing, 120 for rakes, 40 for valleys, and 80 for hips." ### 5. Create Deliverable Change Request `create_a_hover_deliverable_change_request` This tool allows an agent to autonomously upgrade a model's deliverable tier (for example, moving from 'Capture Only' to 'Roof Only', or 'Roof Only' to 'Complete') based on the changing needs of the project. > "Upgrade the deliverable for model 456123 to 'Complete' (ID 3). Log this change request under my user email." ### 6. Blueprint Upload - Build All `create_a_hover_blueprint` Allows the agent to upload blueprint files (by passing external URLs) to reconstruct elevations into 3D models. It requires the blueprint feature to be enabled on the Hover organization. > "Create a new blueprint job named 'Oakwood New Build' using the PDF at this URL. Set it to the 'build_all' workflow." ### 7. Get Inspection PDF `get_single_hover_inspection_pdf_by_id` Retrieves the final inspection data as a PDF document. Because this endpoint returns a binary file, the agent uses the proxy API to receive a secure, temporary download link or base64 encoded stream depending on your setup. > "Download the final inspection PDF for inspection ID 10022 and save the link to the client notes." For the complete inventory of available Hover tools, schema definitions, and required parameters, visit the [Hover integration page](https://truto.one/integrations/detail/hover). ## Workflows in Action Exposing individual endpoints to an LLM is only the first step. The real power emerges when the agent chains these tools together to execute complex, multi-step business logic autonomously. ### Scenario 1: Autonomous Estimation Pipeline **The Prompt:** > "Check if job 84729 is done processing. If it is, get the JSON measurements, calculate the roof waste factor, and write up a summary of the total materials needed for the roof." **Step-by-step Execution:** 1. **`get_single_hover_job_by_id`**: The agent checks the job ID 84729. It parses the response, looking at the `state` of the nested models. It identifies that the model (ID 55511) has a state of `complete`. 2. **`list_all_hover_measurements_json`**: The agent takes model ID 55511 and requests the `full_json` version of the measurements. 3. **Data Parsing**: The agent extracts `roof_facets.area`, `valleys_linear_feet`, `rakes_linear_feet`, etc., from the returned JSON. 4. **`list_all_hover_roof_waste_factors`**: The agent feeds those exact extracted numbers into the waste factor calculation tool. 5. **Final Output**: The agent returns a plain-text summary to the user detailing the total square footage, the algorithmic waste percentage, and the final material order calculation. ### Scenario 2: Upselling Deliverables on Large Properties **The Prompt:** > "Review the recent jobs. Find any job that is currently 'Roof Only' where the total property footprint is over 4,000 square feet, and upgrade those to 'Complete' deliverables using my user ID 99281." **Step-by-step Execution:** 1. **`list_all_hover_jobs`**: The agent fetches recent jobs for the organization. 2. **`get_single_hover_job_by_id`**: The agent loops through the jobs, checking the detailed metadata and attached models. 3. **Logic execution**: The agent identifies a job matching the footprint criteria that is currently on the 'Roof Only' deliverable tier (Deliverable ID 2). 4. **`create_a_hover_deliverable_change_request`**: The agent initiates the upgrade to 'Complete' (Deliverable ID 3), injecting the required `current_user_id` of 99281. 5. **Final Output**: The agent confirms the upgrade has been queued and provides the change request IDs for tracking. ## Building Multi-Step Workflows To facilitate the scenarios above, your agent needs an execution loop that can handle intermediate states, chain function calls, and gracefully handle API failures. When connecting to Hover at scale, you will eventually hit rate limits. It is critical to understand that **Truto does not automatically retry, throttle, or apply backoff on [rate limit errors](https://truto.one/how-to-handle-rate-limits-with-ai-agents/).** When the upstream Hover API returns an HTTP 429, Truto passes that error directly back to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`), but the caller is entirely responsible for retry and backoff logic. Here is how you build a resilient agent loop in TypeScript that handles multi-step reasoning and respects rate limits: ```typescript import { ChatOpenAI } from "@langchain/openai"; import { TrutoToolManager } from "truto-langchainjs-toolset"; import { HumanMessage, AIMessage, SystemMessage } from "@langchain/core/messages"; // A helper function to pause execution if we hit a rate limit const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms)); async function runAutonomousHoverAgent(prompt: string, accountId: string) { const toolManager = new TrutoToolManager({ apiKey: process.env.TRUTO_API_KEY }); const hoverTools = await toolManager.getTools(accountId); const llm = new ChatOpenAI({ modelName: "gpt-4-turbo", }).bindTools(hoverTools); const messages = [ new SystemMessage("You are a construction estimation assistant. Use the provided tools to query Hover."), new HumanMessage(prompt) ]; while (true) { try { const response = await llm.invoke(messages); messages.push(response); // If the LLM decides no more tool calls are needed, exit the loop if (!response.tool_calls || response.tool_calls.length === 0) { console.log("Final Answer:", response.content); break; } // Execute each tool call requested by the LLM for (const toolCall of response.tool_calls) { const tool = hoverTools.find(t => t.name === toolCall.name); if (tool) { console.log(`Executing ${tool.name}...`); // Execute the tool and capture the result const toolResult = await tool.invoke(toolCall.args); messages.push(toolResult); } } } catch (error: any) { // Check if the error is a 429 Rate Limit from Truto/Hover if (error?.response?.status === 429) { const resetTime = error.response.headers.get('ratelimit-reset'); const waitTime = resetTime ? (parseInt(resetTime) * 1000) - Date.now() : 5000; console.warn(`Rate limit hit. Waiting ${waitTime}ms before retrying...`); await sleep(Math.max(waitTime, 1000)); // Ensure at least 1s wait // The loop will continue and retry the last LLM invocation } else { console.error("Workflow failed:", error); break; } } } } ``` ```mermaid sequenceDiagram participant User participant Agent as AI Agent participant Truto as Truto Proxy Layer participant Upstream as Hover API User->>Agent: "Check job 84729, get measurements if complete." Agent->>Truto: Call get_single_hover_job_by_id(84729) Truto->>Upstream: GET /api/v1/jobs/84729 Upstream-->>Truto: 200 OK (state: complete, model: 55511) Truto-->>Agent: JSON Response Agent->>Agent: Parse state == complete Agent->>Truto: Call list_all_hover_measurements_json(55511) Truto->>Upstream: GET /api/v1/models/55511/measurements.json Upstream-->>Truto: 200 OK (Roof data) Truto-->>Agent: JSON Response Agent-->>User: "The job is complete. Total roof area is 2500 sq ft." ``` This architecture keeps the agent logic completely detached from the specific transport mechanics of the Hover API. If Hover changes a pagination cursor, updates an authentication requirement, or adjusts a query parameter format, you modify the integration configuration in the Truto dashboard. The tool schemas update in real-time, the agent reads the new instructions, and the workflow continues unbroken—without a single code deployment. ## Moving from Prototypes to Production Building an AI agent that talks to external infrastructure is straightforward in a local sandbox. Scaling it to production across dozens of SaaS platforms is where engineering teams stall. Direct point-to-point API connections force you to write bespoke logic for authentication, polling, multipart forms, and rate limits for every vendor. By abstracting the Hover API behind a unified tool layer, you reduce the LLM's cognitive load, enforce strict JSON schemas, and ensure that malformed requests never touch the upstream provider. > Want to give your AI agents reliable, standardized access to Hover and 100+ other enterprise SaaS platforms? Book a demo to see how Truto's unified tool layer handles the heavy lifting. > > [Talk to us](https://truto.one/book-a-demo/)