Connect Truuth to AI Agents: Orchestrate Biometric and Repeat Checks

You want to connect Truuth to an AI agent so your internal systems can independently orchestrate biometric verifications, conduct liveness checks, extract document OCR data, and run repeat offender matching without human intervention. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually build custom identity verification polling loops or maintain complex API wrappers.

Giving a Large Language Model (LLM) read and write access to a secure Know Your Customer (KYC) and biometrics platform like Truuth is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands the nuances of asynchronous biometric processing and base64 image handling, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Truuth to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Truuth to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Truuth, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex fraud prevention workflows. 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 Custom Truuth Connectors

Building AI agents is easy. Connecting them to external Identity APIs is hard. Giving an LLM access to external verification data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production, this approach collapses entirely, especially with a specialized security ecosystem like Truuth.

If you decide to build a custom Truuth integration yourself, you own the entire API lifecycle. Truuth's biometrics and KYC API introduces highly specific integration challenges that break standard LLM assumptions.

The Asynchronous Polling Trap

Identity verification is rarely an instantaneous operation. When you initiate a KYC invite or submit a document for fraud checking, Truuth processes these operations asynchronously. A standard HTTP request does not immediately return a VERIFIED status. Instead, it returns an identifier, requiring the calling system to poll a status endpoint or listen for a webhook. AI agents struggle with asynchronous wait states. If you give an agent a generic API call, it will often assume the task failed if the immediate response does not contain the final verification outcome. You must structure the agent's tools to distinctly separate the "initiation" action from the "status checking" action, training the agent to loop and check the status over time.

Ephemeral Pre-Signed URLs and Payload Limits

Biometric data consists of high-fidelity images and dense PDF verification reports. You cannot simply pass a 5MB base64 encoded face image or a 100-page PDF report directly into an LLM's context window. Doing so will immediately exceed token limits and incur massive compute costs. Truuth handles large payload retrieval by issuing pre-signed URLs. However, these URLs are ephemeral - often valid for only 15 minutes. Handing a URL to an agent means the agent must possess the capability to download, parse, and summarize the contents of that URL independently before it expires, requiring secondary tooling beyond the base API connector.

Deeply Nested Anomaly Matrices

Truuth's Repeat User Match and Document Authenticity endpoints return highly complex, nested JSON objects. A single response might include sub-objects for facial similarity scores, liveness confidences, IP tumbling risks, and multiple authenticityChecks arrays. LLMs are notorious for hallucinating when forced to parse undocumented, deeply nested JSON structures to find a single boolean flag. Without an intermediating proxy layer that provides strict schemas and descriptions for these nested fields, an agent will frequently misinterpret a "Failed Document Type" sub-flag as a successful verification if the parent object simply returns 200 OK.

Automating Biometrics: Core Truuth Tools for AI Agents

Instead of manually mapping these nested endpoints and asynchronous states, Truto exposes Truuth's functionality as standardized LLM tools. Truto handles the authentication, schema generation, and query parameter processing, returning Proxy APIs that agents can immediately consume.

Here are the high-leverage hero tools you can supply to your agent for Truuth automation.

1. Initiate KYC Verification

The create_a_truuth_verification_invite tool sends a verification invite to a user via email. It dispatches a KYC URL to a customer, initiating the identity verification process and returning the verificationId required for tracking the process.

Contextual Usage: Give this tool to agents responsible for automated onboarding flows. The agent can use this to kick off background checks the moment a user signs up for a regulated financial product.

"A new vendor, John Doe (john.doe@example.com), has completed the initial onboarding form. Please initiate a Truuth KYC verification invite for him and log the verification ID to our database."

2. Retrieve Verification Status and Results

The get_single_truuth_verification_by_id tool is the counterpart to the invite tool. It fetches the full verification details by ID, returning the current state (like pending, verified, or failed), the identity owner details, and the compiled results of the checks.

Contextual Usage: Agents use this tool in a polling loop or as a secondary step after a delay to finalize an onboarding decision.

"Check the status of Truuth verification ID 'ver-84729'. If the status is completed, extract the outcome and update the user's CRM profile to approved. If it is still pending, wait and check again."

3. Verify Document Authenticity

The create_a_truuth_document_authenticity tool allows an agent to directly verify the authenticity of a submitted ID document. It requires up to two document-page images (via base64 or URL) and returns an authenticity score and an array of specific authenticity checks.

Contextual Usage: Ideal for agents handling manual document upload reviews where users bypassed the standard mobile flow.

"The user uploaded their passport image to the support ticket. Run the image URL through the Truuth document authenticity tool and tell me if the authenticity score passes our risk threshold."

4. Perform Face Match and Liveness Checks

The create_a_truuth_face_liveness tool verifies whether the face on a photo ID document matches the face in a selfie image while simultaneously running liveness detection to prevent spoofing.

Contextual Usage: Use this when an agent is triaging high-risk transactions (like large wire transfers) that require step-up biometric authentication.

"Execute a face liveness check using the submitted selfie URL against the user's stored photo ID URL. If the liveness score is below 0.8, flag the transaction for manual review."

5. Retrieve Fraud Check Reports

The list_all_truuth_verification_fraud_check_report tool fetches the pre-signed URL for a comprehensive Truuth fraud check report associated with a specific verification ID.

Contextual Usage: Give this to compliance analyst agents that need to compile audit trails. The agent can fetch the URL, download the report, and archive it into a company drive.

"Retrieve the fraud check report for verification 'ver-11223'. Get the pre-signed URL and download the base64 content so we can attach it to the compliance audit log."

6. Detect Repeat Offenders

The create_a_truuth_repeat_user_match tool checks a newly submitted profile against the historical dataset for a given Truuth instance. It determines if the identity owner has previously applied under different credentials.

Contextual Usage: A critical tool for AML (Anti-Money Laundering) and fraud prevention agents tracking synthetic identity rings.

"Run a repeat user match for the newly submitted onboarding record on instance 'inst-555'. Let me know if this user's biometrics match any previously blacklisted accounts."

For the complete tool inventory and granular query schema details, visit the Truuth integration page.

Workflows in Action

AI agents shine when they autonomously chain multiple Truuth tools together to complete complex, multi-step risk operations. Here is how specific personas utilize these tools in production.

The Automated KYC Triage Flow

Persona: Risk Operations Engineer

Instead of human analysts reviewing pending verifications, an agent can orchestrate the entire end-to-end KYC flow based on CRM triggers.

"A new user just entered the 'Verification Required' stage in our system. Send them a Truuth invite. Check the status. Once complete, pull the verification report and summarize any flags."

Step-by-Step Execution:

1. The agent calls create_a_truuth_verification_invite to email the user and retrieve the verificationId.
2. The agent schedules a delayed execution or uses an internal loop to periodically call get_single_truuth_verification_by_id.
3. Upon receiving a completed status, the agent parses the results object.
4. If anomalies exist, the agent calls list_all_truuth_verification_report to get the pre-signed URL for the PDF and routes the summary to a human analyst.

Result: The system autonomously handles the "happy path" approvals and only escalates detailed audit reports for borderline cases, drastically reducing manual review times.

The Synthetic Identity Interception

Persona: AML Compliance Officer

Fraud rings often reuse slightly modified documents and faces across multiple synthetic identities. Agents can actively hunt these patterns upon submission.

"Review the ID documents uploaded by user 9901. Check the document for tampering, and then cross-reference the user against our historical repeat offender database."

Step-by-Step Execution:

1. The agent fetches the uploaded images and calls create_a_truuth_document_authenticity to analyze the font, holograms, and machine-readable zones (MRZ).
2. If the document passes basic checks, the agent then calls create_a_truuth_repeat_user_match.
3. The agent calls get_single_truuth_repeat_user_match_by_id to retrieve the results of the transaction.
4. If the matchedRecords array contains known malicious IDs, the agent immediately locks the account and generates an alert.

Result: A fully autonomous fraud gate that prevents bad actors from onboarding by chaining real-time document forensic tools with historical database matching.

Building Multi-Step Workflows

To build these workflows, you need to bind Truto's tools to your AI agent framework. Truto is framework-agnostic, meaning you can integrate it seamlessly into LangChain, LangGraph, CrewAI, or the Vercel AI SDK.

Below is a practical implementation using LangChain.js and the @trutohq/truto-langchainjs-toolset to fetch Truuth tools and execute a workflow.

Handling Rate Limits in Agent Workflows

When orchestrating high-volume biometric API calls, you will eventually hit API rate limits. Factual note on rate limits: Truto does not automatically retry, throttle, or apply backoff on rate limit errors. When the upstream Truuth API returns an HTTP 429, Truto passes that exact error to your application.

However, Truto normalizes the upstream rate limit information into standardized headers per the IETF specification: ratelimit-limit, ratelimit-remaining, and ratelimit-reset. Your agent's execution loop is fully responsible for catching these 429s, reading the reset headers, and applying appropriate backoff logic.

Here is how you orchestrate the agent and handle the rate limit realities.

graph TD
  A["Initialize LangChain Agent"]
  B["TrutoToolManager.getTools()"]
  C["Agent Execution Loop"]
  D["Truuth Tool Call via Truto"]
  E["HTTP 429 Rate Limit Error"]
  F["Parse ratelimit-reset Header"]
  G["Wait & Retry Backoff"]
  H["HTTP 200 Success"]
  
  A --> B
  B --> C
  C --> D
  D --> E
  E --> F
  F --> G
  G --> D
  D --> H
  H --> C

Implementation Code (TypeScript)

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
async function runBiometricAgent() {
  // 1. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4-turbo",
    temperature: 0,
  });
 
  // 2. Initialize Truto Tool Manager with your Integrated Account ID for Truuth
  const trutoManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY!,
    integratedAccountId: "your-truuth-account-id",
  });
 
  // 3. Fetch all Truuth tools dynamically
  const tools = await trutoManager.getTools();
 
  // 4. Create the Prompt Template
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an elite AML compliance agent. You have access to Truuth biometric tools."],
    ["placeholder", "{chat_history}"],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 5. Create the Agent
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
 
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
  });
 
  // 6. Execute with custom retry wrapper for HTTP 429s
  const executeWithRateLimitHandling = async (input: string) => {
    let attempts = 0;
    const maxAttempts = 3;
 
    while (attempts < maxAttempts) {
      try {
        const result = await agentExecutor.invoke({ input });
        console.log("Agent Result:", result.output);
        return result;
      } catch (error: any) {
        // Catch standard 429s passed through by Truto
        if (error.response && error.response.status === 429) {
          const resetTimeStr = error.response.headers['ratelimit-reset'];
          const resetSeconds = resetTimeStr ? parseInt(resetTimeStr, 10) : 60;
          
          console.warn(`Rate limit hit. Waiting ${resetSeconds} seconds before retry...`);
          await new Promise(res => setTimeout(res, resetSeconds * 1000));
          attempts++;
        } else {
          console.error("Agent execution failed with a non-429 error.");
          throw error;
        }
      }
    }
    throw new Error("Max retries exceeded due to rate limits.");
  };
 
  // Run the workflow
  await executeWithRateLimitHandling(
    "A user uploaded an ID. Please trigger a document authenticity check for image URL 'https://example.com/id.jpg' and inform me if the score is above 0.85."
  );
}
 
runBiometricAgent();

This architecture guarantees that your agent has access to real-time biometric tools while ensuring your application layer robustly handles upstream rate constraints without dropping critical fraud checks.

Moving Past Manual Integration Workflows

Forcing engineering teams to build custom API wrappers, parse nested biometric payloads, and manually decode base64 strings every time you want to give an AI agent a new capability is unsustainable. By leveraging Truto's /tools endpoint, you abstract the entire integration layer into a single, standardized set of definitions that your LLM can natively understand.

Your agents can now securely invite users, analyze liveness, detect repeat fraudsters, and pull compliance PDFs without a single line of custom Truuth integration code.