Skip to content

Connect HawkSoft to AI Agents: Automate Policy Search and Tasks

Nachi Raman Nachi Raman 8 min read AI & Agents
TrutoFor teams building AI agents

Give your AI agent HawkSoft tools.

Connect HawkSoft to your AI agents programmatically using Truto's /tools endpoint. This guide covers bypassing HawkSoft's API quirks, implementing framework-agnostic tool calling, and executing autonomous insurance workflows safely.

In this guide

  1. 01Fetch HawkSoft Tools
  2. 02Bind Tools to the LLM
  3. 03Implement Rate Limit Handling
  4. 04Execute the Agent Loop

The guide

Learn how to connect HawkSoft to AI agents using Truto's /tools endpoint. Build autonomous workflows for policy search, log notes, and receipt processing.

You want to connect HawkSoft to an AI agent so your system can autonomously search insurance policies, sync client profiles, generate log notes, and process receipts based on natural language instructions. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom HawkSoft integration from scratch.

Giving a Large Language Model (LLM) read and write access to an agency management system is an engineering challenge. You either spend weeks building custom connectors and normalizing data, or you use an infrastructure layer that handles the boilerplate. If your team uses ChatGPT, check out our guide on connecting HawkSoft to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting HawkSoft to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them directly to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for HawkSoft, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex insurance operations safely. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of the HawkSoft API

Giving an LLM access to external systems sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in a tool decorator. Against complex, domain-specific systems like HawkSoft, this approach collapses in production.

HawkSoft's API introduces several specific integration constraints that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

Non-Standard Text Responses for Mutations

When a modern LLM invokes a tool, it expects a structured JSON object in return. HawkSoft breaks this convention on specific mutation endpoints. For example, when creating a log note, HawkSoft does not return a JSON representation of the created entity. Instead, it returns a plain text message: HTTP 200 The log was created successfully., or HTTP 202 The request was saved and the log will be created next time the agency is connected to the cloud.

If you feed an unparsed text string into an agent framework expecting strict JSON, the parser crashes. A unified tool layer normalizes these upstream text responses into predictable JSON structures containing the message and status code, keeping the agent loop stable.

Strict Rate Limiting and Standardized Headers

The HawkSoft API enforces a hard limit of 25 requests per second. If an overly aggressive agent attempts to pull all changed clients and fetch their details concurrently, the API will immediately return HTTP 429 Too Many Requests errors.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream API returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller is strictly responsible for reading these headers and implementing retry and exponential backoff logic. Do not expect the infrastructure to magically absorb these limits - your agent loop must handle them explicitly.

Narrow Search Constraints

Agents thrive on broad search capabilities, but HawkSoft's client search endpoint is highly constrained. Currently, the only supported search criterion is policyNumber. If an agent wants to find a client by name or phone number, it cannot simply pass those parameters to the search endpoint. It must either maintain a localized cache of clients fetched via the bulk changed clients endpoints or guide the user to provide a policy number. Exposing the exact schema requirements for the search tool prevents the LLM from hallucinating unsupported search filters.

Why a Unified Tool Layer Matters for Agent Safety

Before writing integration code, decide what layer your agent interacts with. Direct API tools push provider quirks directly into the LLM's context window.

A unified tool layer collapses these complexities behind a consistent, predictable schema. That gives you concrete safety wins:

  1. Deterministic input validation. Every tool has a strict JSON schema. If the LLM tries to search by lastName instead of policyNumber, the validation layer rejects it immediately, saving an API round-trip and a rate limit token.
  2. Reduced hallucination surface. The LLM selects from a stable list of predefined functions with explicit descriptions, rather than attempting to guess the exact URL paths or pagination cursors required by HawkSoft.

HawkSoft Hero Tools for AI Agents

Truto provides a comprehensive JSON object representing the integration, mapping HawkSoft's API into resources and methods. Here are the highest-leverage tools available for your agent workflows.

This tool searches an agency's clients. Because of HawkSoft's API constraints, the only supported search criteria is the Policy Number. It supports Client Includes to fetch additional related data in the response.

"Find the client associated with auto policy number PAC-9923841."

get_single_hawk_soft_client_by_id

Once the agent has a client ID (often retrieved via a search or webhook), this tool fetches the full client profile. It is the primary read operation for detailing customer policies, associated people, and contact information.

"Retrieve the full client profile and active policies for client ID 84720."

create_a_hawk_soft_log_note

This tool creates a log note, and optionally a task, on a specific client record. This is vital for auditing. When an AI agent performs an action on behalf of an account manager, it should use this tool to log exactly what was done and when.

"Add a log note to client 84720 stating that their requested policy changes were processed, and assign a review task to the primary agent."

hawk_soft_clients_bulk_get

This tool reads clients in batches of up to 200 using client numbers. It is incredibly useful for batch processing or syncing operations where the agent needs to review a list of updated clients.

"Fetch the full profiles for the following list of client IDs so I can audit their missing coverage limits."

list_all_hawk_soft_changed_clients

This tool returns a list of clients changed since a specific date. Agents can use these IDs as inputs to the bulk get tool to keep external systems or vector databases up to date with agency changes.

"Get all client IDs that have been updated since last Friday."

create_a_hawk_soft_receipt

This tool records a payment received by a client. It requires an array of receipts and automatically creates a log note linked to the receipt. Agents handling customer portals or conversational billing use this to finalize transactions.

"Record a $150 premium payment receipt for client 84720 and attach a confirmation note."

To see the complete tool inventory and schema definitions, visit the HawkSoft integration page.

Workflows in Action

Here is how these tools chain together to execute real-world agency operations.

Scenario 1: Automated Policy Renewals and Auditing

An agency wants to audit a policy and leave a paper trail of the interaction without manual data entry.

"Look up policy AL-55092, check the client's current status, and leave a log note that the automated renewal check was completed."

  1. hawk_soft_clients_search: The agent calls this tool, passing AL-55092 as the policyNumber. HawkSoft returns the client ID (e.g., 10543).
  2. get_single_hawk_soft_client_by_id: The agent calls this tool with ID 10543 to read the full profile and ensure the policy is active.
  3. create_a_hawk_soft_log_note: The agent executes this tool to append a note to the client profile stating "Automated renewal check completed." HawkSoft returns the HTTP 200 text string, which Truto normalizes. The agent reports success to the user.

Scenario 2: Batch Payment Reconciliation

A finance operations bot needs to process payments that cleared overnight.

"I have a list of payments that cleared today. Record a $300 receipt for client 1102 and a $150 receipt for client 908, then verify they were processed."

  1. create_a_hawk_soft_receipt: The agent constructs the required JSON array containing the receipt objects for clients 1102 and 908, and submits them.
  2. hawk_soft_clients_bulk_get: To verify the accounts reflect the new status, the agent calls the bulk get tool, passing the array [1102, 908].
  3. LLM Synthesis: The agent compares the current client data against the submitted receipts and generates a reconciliation summary for the finance team.

Building Multi-Step Workflows

To build these workflows, you need an orchestration loop that can fetch the tools, format them for the LLM, execute the requested functions, handle rate limit errors, and return the data.

Because Truto exposes tools via a standard REST endpoint (/integrated-account/<id>/tools), you can use any framework. Below is a conceptual implementation using LangChain.js and the TrutoToolManager from the truto-langchainjs-toolset.

sequenceDiagram
    participant App as Your App
    participant Agent as AI Agent
    participant Truto as Truto API
    participant HawkSoft as HawkSoft API

    App->>Agent: "Find policy 12345 and add log note"
    Agent->>Truto: GET /integrated-account/{id}/tools
    Truto-->>Agent: Returns JSON schemas for HawkSoft tools
    Agent->>Agent: LLM reasoning (selects hawk_soft_clients_search)
    Agent->>Truto: Execute tool: hawk_soft_clients_search
    Truto->>HawkSoft: GET /api/v2/clients/search?policyNumber=12345
    HawkSoft-->>Truto: 200 OK (Client Data)
    Truto-->>Agent: Standardized JSON response
    Agent->>Truto: Execute tool: create_a_hawk_soft_log_note
    Truto->>HawkSoft: POST /api/v2/clients/{id}/log
    HawkSoft-->>Truto: 202 Accepted (Text message)
    Truto-->>Agent: Normalized tool response
    Agent-->>App: "Log note added to client profile."

Implementing the Agent Loop with Rate Limit Handling

The most critical part of this implementation is error handling. Because HawkSoft limits requests to 25 per second, batch operations or looping agents will hit 429s. Truto provides the ratelimit-reset header on the error response. Your infrastructure must catch this error, pause execution, and retry.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runHawkSoftAgent(prompt: string, integratedAccountId: string) {
  // 1. Initialize the LLM
  const model = new ChatOpenAI({ 
    modelName: "gpt-4o",
    temperature: 0 
  });
 
  // 2. Fetch HawkSoft tools dynamically from Truto
  const toolManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: integratedAccountId,
  });
  
  const tools = await toolManager.getTools();
  
  // 3. Bind the tools to the model
  const modelWithTools = model.bindTools(tools);
 
  // 4. Start the agent loop
  const messages = [{ role: "user", content: prompt }];
  
  while (true) {
    const response = await modelWithTools.invoke(messages);
    messages.push(response);
 
    // If no tool calls are requested, the agent is done
    if (!response.tool_calls || response.tool_calls.length === 0) {
      return response.content;
    }
 
    // 5. Execute the requested tool calls
    for (const toolCall of response.tool_calls) {
      let toolResult;
      
      try {
         // Attempt execution
         toolResult = await toolManager.executeTool(toolCall.name, toolCall.args);
      } catch (error) {
         // Handle HTTP 429 Rate Limits passed through from Truto
         if (error.status === 429) {
            const resetTime = error.headers['ratelimit-reset'];
            console.log(`Rate limited by HawkSoft. Retrying after ${resetTime} seconds...`);
            // Implement your wait and exponential backoff logic here
            await delay(resetTime * 1000);
            toolResult = await toolManager.executeTool(toolCall.name, toolCall.args);
         } else {
            // Pass standard errors back to the LLM to self-correct
            toolResult = { error: error.message };
         }
      }
 
      // 6. Return the tool result to the LLM's context
      messages.push({
        role: "tool",
        tool_call_id: toolCall.id,
        content: JSON.stringify(toolResult),
      });
    }
  }
}
 
// Utility function for backoff
const delay = (ms: number) => new Promise(res => setTimeout(res, ms));

This architecture completely decouples your agent from the underlying HawkSoft API semantics. The agent only knows about the tool definitions, and Truto manages the authentication, pagination, and query parameter processing on the backend.

Moving from Script to Production

When connecting AI agents to production insurance software, you are building a system that handles highly sensitive PII. Hardcoding API requests and building your own schema generation pipelines scales poorly across multiple integrations.

By leveraging an infrastructure layer that maps endpoints to a standardized tool format, your engineering team can focus on agent reasoning, prompt engineering, and UX, rather than maintaining integrations and reading HawkSoft release notes.

Two ways to put HawkSoft to work

Truto

For product teams

Give your agent HawkSoft tools

Your customers connect their own HawkSoft accounts. Your product gets one API and MCP tools for HawkSoft, through Truto.

FAQ

How does Truto handle HawkSoft rate limits?
HawkSoft has a strict limit of 25 requests per second. Truto does not retry, throttle, or apply backoff automatically. Instead, Truto passes the HTTP 429 error directly to the caller and normalizes the upstream headers into standard IETF spec headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). Your application is responsible for implementing retry and backoff logic.
Which agent frameworks are supported?
Truto's /tools endpoint exposes standard JSON schemas, making it framework-agnostic. You can use LangChain, LangGraph, CrewAI, Vercel AI SDK, or custom-built agents.
How does the agent know which HawkSoft tool to use?
When you call the Truto /tools endpoint, it returns a collection of Proxy APIs complete with descriptions and JSON schemas for their parameters. The LLM uses these descriptions to determine which tool to invoke based on the user's prompt.
Does Truto store the insurance data passing through the agent?
No. Truto operates as a pass-through architecture. Data fetched from HawkSoft tools passes through to your agent framework without being stored at rest by Truto.
HawkSoft HawkSoftAI agent tools Get a sandbox

More from our Blog