Connect Kaspr to AI Agents: Scale contact enrichment & usage tracking

You want to connect Kaspr to an AI agent so your system can autonomously discover contact data, enrich LinkedIn profiles, and track credit usage without manual oversight. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom Kaspr API integration from scratch.

Giving a Large Language Model (LLM) read and write access to Kaspr's enrichment engine is an engineering headache. 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 Kaspr to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Kaspr 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 Kaspr tools, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex Kaspr automation AI Agents workflows. For a broader look at the architecture behind this approach, refer to our research on Architecting AI Agents: LangGraph, LangChain, and the SaaS Saas Integration Bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, you must decide what layer your agent talks to. This choice determines the reliability and safety of your production system.

Direct API tools - mapping one tool directly to raw endpoints - look convenient during a prototype. However, this pushes provider-specific quirks directly into the LLM's context window. The model has to remember authentication headers, complex pagination cursors, and deeply nested JSON structures. Every one of those quirks is a hallucination waiting to happen.

Truto collapses these complexities into standardized Proxy APIs. Every integration on Truto is represented as a comprehensive JSON object mapping the underlying API. Integrations have a concept of Resources (e.g., credits or profiles), which map to endpoints. Methods are defined on these resources, translating operations into standard Proxy APIs where Truto handles pagination, authentication, and query parameter processing automatically.

Your agent sees clean, deterministic functions. That gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from stable function names with strict JSON schemas.
2. Deterministic input validation. Invalid arguments are rejected before they hit the Kaspr servers, meaning a broken tool call fails fast.
3. Real-time schema synchronization. As the Kaspr API evolves, the tool definitions provided by the /tools endpoint update seamlessly.

The Engineering Reality of the Kaspr API

Giving an LLM access to external data sounds simple until you hit production. Kaspr introduces specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code.

The Complex Credit Economy

Kaspr is not a standard CRUD database; it is an enrichment engine governed by a strict, multi-tiered credit economy. Every call to enrich a profile does not just return data - it executes a transaction against a ledger. Kaspr tracks workEmailCredits, directEmailCredits, phoneCredits, and exportCredits separately.

If you instruct an AI agent to "enrich these 500 LinkedIn profiles," a naive implementation will blindly fire 500 API requests. Depending on the requested data types and successful hits, the agent can drain a workspace's monthly quota in seconds. Your agent must be contextually aware of the workspace's balance before initiating batch operations.

Strict Rate Limits and the 429 Trap

Kaspr aggressively protects its infrastructure using multi-window rate limits (minutely, hourly, and daily limits). When executing automated prospecting, your agent will inevitably hit an HTTP 429 Too Many Requests response.

This is a critical architectural reality: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Kaspr API returns an HTTP 429, Truto passes that error directly back to the caller.

However, Truto normalizes the upstream rate limit information into standardized headers per the IETF specification:

• ratelimit-limit
• ratelimit-remaining
• ratelimit-reset

The caller - your agent framework or wrapper code - is entirely responsible for reading the ratelimit-reset header, sleeping the thread, and retrying the call. Do not assume the integration layer will magically absorb rate limit violations for you.

Asynchronous Latency and Nested Schemas

LinkedIn profile scraping and enrichment takes time. The Kaspr API returns a heavily nested JSON response containing multiple arrays (professionalEmails, personalEmails, phones) alongside system metadata like processingTime and fetchedAt.

Standard LLMs are trained to expect flat, intuitive JSON objects. When an agent tries to parse a multi-layered enrichment object with varying array lengths, it often drops context or hallucinates data mappings. Providing a strictly typed JSON schema for the return object is mandatory to keep the agent grounded.

Customizing Tools for the LLM

Truto provides basic tool definitions for each Resource and Method by default. However, LLMs rely heavily on the descriptions of tools to know when to use them. Truto allows you to customize these descriptions directly in the UI, and those changes reflect instantly in your agent's context.

1. Go to the Kaspr integration in your Truto account.
2. Click the Edit integration button.
3. Scroll down to the Resources section, expand a resource, and expand the relevant Method.
4. Enter a detailed description. (e.g., "Use this tool to enrich a LinkedIn profile to find work emails and phone numbers. Requires the LinkedIn profile ID.")
5. Switch to the Query Schema tab to verify the accepted parameters.
6. Save the integration.

When your application calls the /integrated-account/<id>/tools endpoint, the updated descriptions are immediately passed to your agent framework.

Building Multi-Step Workflows

To connect Kaspr to AI Agents safely, you must orchestrate the tool execution loop. The following example demonstrates how to fetch Kaspr tools using the Truto Langchain.js SDK, bind them to an agent, and critically, how to handle the HTTP 429 rate limit exceptions that Truto passes through.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
async function runKasprAgent() {
  // 1. Initialize the Truto Tool Manager with your Kaspr Integrated Account ID
  const trutoManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: "kaspr-integrated-account-id",
  });
 
  // 2. Fetch Kaspr tools dynamically from Truto's /tools endpoint
  const tools = await trutoManager.getTools();
 
  // 3. Initialize the LLM and bind the tools
  const llm = new ChatOpenAI({ 
    modelName: "gpt-4-turbo", 
    temperature: 0 
  }).bindTools(tools);
 
  // 4. Setup the agent prompt
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a revenue operations assistant. You manage Kaspr credits, enrich LinkedIn profiles, and respect system constraints."],
    ["user", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  const agent = await createOpenAIToolsAgent({
    llm,
    tools,
    prompt,
  });
 
  const executor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 10,
  });
 
  // 5. Execute the workflow with rate limit backoff logic
  try {
    const result = await executor.invoke({
      input: "Check our Kaspr credit balance. If we have more than 5 work email credits, enrich the LinkedIn profile ID 'johndoe123'."
    });
    console.log("Agent Output:", result.output);
  } catch (error) {
    // Truto passes 429 errors directly. The caller must handle the backoff.
    if (error.response && error.response.status === 429) {
      const resetTime = error.response.headers.get('ratelimit-reset');
      const sleepMs = (parseInt(resetTime, 10) * 1000) - Date.now();
      console.warn(`Rate limit hit. Agent must sleep for ${sleepMs}ms`);
      // Implement delay and retry logic here
    } else {
      console.error("Agent execution failed:", error);
    }
  }
}
 
runKasprAgent();

This architecture ensures that your application logic retains control over system limits while the LLM handles the semantic reasoning and API payload mapping.

High-Leverage Kaspr Tools for AI Agents

Below are the highest-leverage Kaspr tool definitions available via the Truto /tools endpoint. By binding these to your agent, you grant it complete autonomy over the enrichment lifecycle.

list_all_kaspr_credits

This tool retrieves the remaining credits in the Kaspr workspace. It returns distinct balances for workEmailCredits, directEmailCredits, phoneCredits, and exportCredits. A value of -1 indicates unlimited credits for that tier. Agents should call this before executing bulk enrichment tasks to ensure sufficient operational runway.

"Before you start processing the list of 50 target accounts, use the Kaspr API to check our current work email and phone credit balances. If either is below 10, stop and alert me."

kaspr_linkedin_profiles_enrich

The core engine of Kaspr. This tool takes a LinkedIn profile id and name and retrieves the prospect's work email, direct (personal) email, and phone number. Successful hits consume credits based on the requested data types, plus one export credit per successful call. It returns a nested object containing the enriched data, company details, and processingTime.

"Take the LinkedIn ID 'smith-jane-88a9' and enrich the profile to find a direct phone number and work email. Output the results in a structured JSON block."

list_all_kaspr_rate_limits

Retrieves the configured request rate limits for the Kaspr workspace. It returns the exact dailyLimit, hourlyLimit, and minutelyLimit. Agents can use this tool to dynamically calculate batch sizes and introduce jitter before initiating large-scale enrichment loops.

"Check our current Kaspr rate limits. I have a list of 300 leads to process. Based on the hourly limit, tell me the maximum safe batch size we can process per minute."

list_all_kaspr_me

A lightweight diagnostic tool that verifies the connected Kaspr API key is valid. It returns the user object identifying the key owner (typically displaying the owner's email address). Use this to validate connection state before initiating long-running workflows.

"Verify our Kaspr connection is active and tell me the email address associated with the API key owner before we begin the lead sync."

To view the complete inventory of available proxy endpoints and detailed JSON schemas, visit the Kaspr integration page.

Workflows in Action

When you combine these tools, AI agents transition from simple chatbots into autonomous revenue operations engineers. Here are concrete examples of how an LLM navigates the Kaspr API.

Scenario 1: The Credit-Aware Enrichment Loop

If you instruct an agent to enrich high-value leads, it must ensure it doesn't deplete the workspace's resources unexpectedly.

"We need to contact the VP of Engineering at Acme Corp (LinkedIn ID: vp-eng-acme). First, check if we have enough direct email and phone credits. If we have at least 1 of each, enrich the profile. Return the direct contact info."

Agent Execution Trace:

1. The agent calls list_all_kaspr_credits to inspect the workspace balances.
2. It parses the response, confirming directEmailCredits > 1 and phoneCredits > 1.
3. The agent calls kaspr_linkedin_profiles_enrich passing the required id.
4. It parses the nested personalEmails and phones arrays from the response.
5. The agent formats the final output for the user.

Scenario 2: Rate-Limit Managed Bulk Sourcing

When processing multiple profiles, the agent must be aware of its velocity to avoid triggering HTTP 429 errors from Kaspr.

"I have 5 LinkedIn profile IDs. Check our minutely rate limits. If the limit supports it, process all 5 profiles for work emails. If not, tell me how many you can process safely right now."

Agent Execution Trace:

1. The agent calls list_all_kaspr_rate_limits to understand the rules of engagement.
2. It identifies that the minutelyLimit is sufficient for 5 calls.
3. The agent iterates through the list, calling kaspr_linkedin_profiles_enrich sequentially for each ID.
4. If a 429 error occurs during the loop, Truto passes it down. The underlying TypeScript framework catches the error, reads the ratelimit-reset IETF header, pauses, and prompts the agent to resume once the window clears.
5. The agent compiles the enriched work emails into a final summary report.

sequenceDiagram
    participant User as User Prompt
    participant Agent as AI Agent (LangChain)
    participant Truto as Truto /tools API
    participant Kaspr as Kaspr API

    User->>Agent: Check limits and enrich 5 profiles
    Agent->>Truto: call list_all_kaspr_rate_limits
    Truto->>Kaspr: GET /v1/rate_limits
    Kaspr-->>Truto: Return 200 OK (Limits)
    Truto-->>Agent: Return schema-validated limits
    
    rect rgb(235, 232, 226)
    Note right of Agent: Agent validates safe batch size
    end

    Agent->>Truto: call kaspr_linkedin_profiles_enrich (ID 1)
    Truto->>Kaspr: POST /v1/enrich
    Kaspr-->>Truto: Return 200 OK (Profile Data)
    Truto-->>Agent: Return normalized profile
    
    Agent->>Truto: call kaspr_linkedin_profiles_enrich (ID 2)
    Truto->>Kaspr: POST /v1/enrich
    Kaspr-->>Truto: Return 429 Too Many Requests<br>Header: ratelimit-reset: 1718293000
    Truto-->>Agent: Pass 429 Exception + Headers
    
    rect rgb(235, 232, 226)
    Note right of Agent: Code layer catches 429, sleeps,<br>then prompts Agent to resume
    end

Strategic Wrap-Up

Building autonomous AI agents that interact with external data providers like Kaspr is an exercise in strict state management and predictable tooling. By utilizing Truto's /tools endpoint, you decouple the volatile nature of third-party SaaS APIs from your LLM's reasoning engine.

The agent never has to invent authentication headers, guess at pagination structures, or hallucinate request bodies. It operates exclusively against stable, well-documented Proxy APIs. Meanwhile, your application infrastructure remains in complete control of business-critical logic—like reading IETF rate limit headers and backing off safely when the Kaspr API demands it.

Stop writing defensive API wrappers and start focusing on your agent's core reasoning loops.