Connect HawkSoft to AI Agents: Automate Policy Search and Tasks
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
- 01Fetch HawkSoft Tools
- 02Bind Tools to the LLM
- 03Implement Rate Limit Handling
- 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:
- Deterministic input validation. Every tool has a strict JSON schema. If the LLM tries to search by
lastNameinstead ofpolicyNumber, the validation layer rejects it immediately, saving an API round-trip and a rate limit token. - 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.
hawk_soft_clients_search
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."
- hawk_soft_clients_search: The agent calls this tool, passing
AL-55092as thepolicyNumber. HawkSoft returns the client ID (e.g.,10543). - get_single_hawk_soft_client_by_id: The agent calls this tool with ID
10543to read the full profile and ensure the policy is active. - 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."
- create_a_hawk_soft_receipt: The agent constructs the required JSON array containing the receipt objects for clients 1102 and 908, and submits them.
- 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]. - 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.
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.