---
title: "Connect Alloy to AI Agents: Orchestrate Fraud & Case Investigations"
slug: connect-alloy-to-ai-agents-orchestrate-fraud-case-investigations
date: 2026-07-07
author: Yuvraj Muley
categories: ["AI & Agents"]
excerpt: "Learn how to connect Alloy to AI agents using Truto. Programmatically fetch Alloy API tools, bind them to your LLM, and automate fraud investigations and KYC."
tldr: "Connecting Alloy to AI agents requires navigating complex token-based schemas and journey application lifecycles. This guide details how to bypass custom integration builds using Truto's unified proxy tools to fetch, bind, and orchestrate fraud detection and KYC workflows using LLM frameworks like LangChain."
canonical: https://truto.one/blog/connect-alloy-to-ai-agents-orchestrate-fraud-case-investigations/
---

# Connect Alloy to AI Agents: Orchestrate Fraud & Case Investigations


You want to connect Alloy to an AI agent so your internal systems can independently triage fraud cases, run evaluations, review KYC documentation, and orchestrate journey applications based on historical risk context. Here is exactly how to do it using Truto's `/tools` endpoint and SDK, bypassing the need to manually code dozens of endpoints or maintain complex API wrappers for identity decisioning.

Giving a Large Language Model (LLM) read and write access to your Alloy instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands the deeply nested token architecture of Alloy's entity models, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on [connecting Alloy to ChatGPT](https://truto.one/connect-alloy-to-chatgpt-automate-kyc-and-identity-decisioning/), or if you are building on Anthropic's models, read our guide on [connecting Alloy to Claude](https://truto.one/connect-alloy-to-claude-manage-onboarding-journeys-compliance/). 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 Alloy, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex fraud operations 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/).

::cta{buttonText="Talk to us" buttonUrl="https://cal.com/truto/partner-with-truto"}
Stop wasting engineering cycles on custom API wrappers. Truto provides instant, AI-ready tool schemas for Alloy and 200+ other SaaS platforms.
::

## The Engineering Reality of Custom Alloy Connectors

Building AI agents is easy. Connecting them to external compliance and fraud APIs is hard. Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an `@tool` decorator. (See our guide on [LLM function calling for integrations](https://truto.one/what-is-llm-function-calling-for-integrations-2026-guide/) for a deeper explanation of this mechanism.) In production, this approach collapses entirely, especially with an ecosystem as complex and regulated as Alloy.

If you decide to integrate Alloy yourself, you own the entire API lifecycle. Alloy's API introduces several highly specific integration challenges that break standard LLM assumptions.

### The Tokenized Relationship Maze

Unlike legacy systems that use standard sequential IDs or simple foreign keys for relationships, Alloy relies heavily on an intricate web of tokenized identifiers. A user is not simply an ID - they are an `entity_token`. That entity goes through a `journey_token` via a `journey_application_token`. During that journey, they trigger an `evaluation_token`, which might generate a `case_token`, which rolls up into an `investigation_token`.

When an AI agent wants to find the underlying KYC evidence for a flagged onboarding event, it cannot simply query the user and read a `documents` array. It must first query the Investigation object, retrieve the associated `journey_application_token`, query the Journey Applications API to find the `evaluation_token`, pull the Case Evidence alerts via the `case_token`, and finally request the document data linked to the `entity_token`. 

LLMs consistently fail at this multi-step relationship traversal if they are not provided with explicit, perfectly typed OpenAPI schemas for every single endpoint. If you hand-code this integration, you have to write complex prompts to teach the LLM the exact lifecycle of an Alloy entity. 

### Polymorphic Entity Schemas

Alloy handles both Person and Business entities. The data structures for these are fundamentally different. A Person entity contains `name_first`, `name_last`, and `birth_date`. A Business entity contains `business_name` and `external_entity_id`. 

If your AI agent needs to update an entity based on new documentation, it must know exactly which endpoint to hit (`/v1/entities/person/{id}` vs `/v1/entities/business/{id}`) and which schema to strictly enforce. If an LLM hallucinations a `business_name` into a Person update payload, the Alloy API will reject the request. Maintaining these diverging, strict JSON schemas as manual `@tool` wrappers in Python or TypeScript requires constant upkeep as Alloy releases new API versions.

### Factual Note on Handling Alloy Rate Limits

When orchestrating high-volume fraud triaging, your agent will inevitably hit rate limits. It is critical to architect your agent loop to respect upstream limits.

Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Alloy API returns an HTTP 429 status code, Truto passes that exact error directly back to the caller. This is a core part of our [zero data retention pass-through architecture](https://truto.one/zero-data-retention-for-ai-agents-why-pass-through-architecture-wins/), ensuring your data is never stored while maintaining direct control over API traffic.

To make this easier to handle programmatically, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification:
*   `ratelimit-limit`: The maximum number of requests allowed in the current window.
*   `ratelimit-remaining`: The number of requests left in the current window.
*   `ratelimit-reset`: The timestamp when the rate limit window resets.

The caller (your agent's execution loop) is solely responsible for reading these headers, implementing retry logic, and applying exponential backoff. Do not design your agent assuming the proxy layer will automatically absorb rate limit errors.

## Hero Tools for Alloy AI Agents

Truto abstracts away the complexity of managing integration authentication, pagination, and schema mapping. By querying the `/tools` endpoint, your agent dynamically receives perfectly formatted tool definitions for Alloy. 

Here are the highest-leverage hero tools your agent can use to orchestrate fraud and identity workflows.

### 1. List All Alloy Investigations (`list_all_alloy_investigations`)

This tool retrieves a paginated list of investigations. It is the primary entry point for an agent tasked with triaging queues. It returns critical top-level data including the `investigation_state`, `total_alerts`, and the overall `risk_score`.

> "Fetch all currently open investigations in Alloy with a risk score higher than 80, and list their associated entity tokens."

### 2. Get Single Person Entity (`get_single_alloy_person_entity_by_id`)

Once an investigation is flagged, the agent needs context on the user. This tool fetches the comprehensive Person entity record using the `entity_token`, returning name fields, birth dates, addresses, emails, phones, and the current PII status.

> "Retrieve the full person entity details for entity token 'ent_abc123'. Check their listed address against the flagged transaction location."

### 3. Create an Alloy Evaluation (`create_a_alloy_evaluation`)

Evaluations are the core engine of Alloy. This tool allows the agent to run a new evaluation against a configured workflow. It accepts dynamic evaluation data and returns the `evaluation_token` along with the status code and any immediate errors.

> "Run a new risk evaluation for the user with entity token 'ent_xyz789' using the standard onboarding workflow configuration."

### 4. Create an Investigation Note (`create_a_alloy_investigation_note`)

Autonomous agents must document their reasoning. This tool allows the agent to append a note directly to an investigation, detailing why a case was flagged, promoted, or archived. It requires the `investigation_token` and the note content.

> "Add a note to investigation 'inv_456' stating that the user's IP address matches a known proxy pool and requires manual compliance review."

### 5. Submit a Journey Application Case Review (`create_a_alloy_journey_application_case_review`)

This tool allows an agent to finalize a pending manual review within a Journey Application. It requires the `journey_token`, `journey_application_token`, and `case_token`, along with the final outcome (e.g., approved, denied) and the reasons for the decision.

> "Submit a case review for case 'case_888' in journey application 'app_999'. Set the outcome to 'denied' and list 'Fraudulent document detected' as the reason."

### 6. Create an Entity Document (`create_a_alloy_entity_document`)

When new KYC evidence is generated or retrieved from a third-party, the agent can attach it directly to the entity. This tool creates a new document record, returning the `document_token` and approval status.

> "Upload the newly verified passport data as an approved entity document for entity token 'ent_abc123' and mark it as a proof of identity."

To view the complete inventory of available Alloy tools, including custom list management, transaction endpoints, and business entity schemas, visit the [Alloy integration page](https://truto.one/integrations/detail/alloy).

## Workflows in Action

Individual tools are useful, but the real power of AI agents lies in chaining these operations together to automate complex fraud operations. Here are two real-world scenarios showing how an agent navigates the Alloy API.

### Scenario 1: Autonomous Triage of High-Risk Onboarding Events

**The Problem:** The fraud team has a backlog of investigations that require basic data collection and initial triage before a human analyst looks at them.

> "Review all open investigations. For any investigation with a risk score above 75, retrieve the associated person entities, summarize their PII data, and leave an investigation note with the summary to aid the human analyst."

**The Agent Workflow:**
1.  **`list_all_alloy_investigations`:** The agent fetches the current list of investigations, filtering for open states and parsing the `risk_score` fields.
2.  **`get_single_alloy_person_entity_by_id`:** For the flagged investigations, the agent extracts the `entity_tokens` and calls this tool to retrieve the PII payload (name, address, phone).
3.  **`create_a_alloy_investigation_note`:** The agent synthesizes the retrieved data into a concise summary and uses this tool to post the note directly to the investigation timeline in Alloy.

**The Result:** Analysts open their dashboards to find investigations already enriched with context, saving them 10-15 minutes of manual clicking per case.

### Scenario 2: Orchestrating KYC Document Verification and Case Decisioning

**The Problem:** A user uploaded a new ID document after an initial failure. The system needs to run a new evaluation and, if successful, approve the pending case.

> "Look up the case details for case token 'case_123'. Run a new evaluation for the associated entity. If the evaluation passes, submit a case review marking it as 'approved'."

**The Agent Workflow:**
1.  **`alloy_cases_list_2`** (Get Case by Token): The agent retrieves the specific case to identify the underlying `entity_token` and `journey_application_token`.
2.  **`create_a_alloy_evaluation`:** The agent triggers a new risk evaluation against the entity to verify the updated document status.
3.  **`create_a_alloy_journey_application_case_review`:** Upon receiving a successful evaluation response, the agent completes the pending review, transitioning the user from a blocked state to fully onboarded.

**The Result:** The onboarding bottleneck is cleared automatically in seconds, without requiring a human compliance officer to manually clear the case.

## Building Multi-Step Workflows

To execute these workflows, you need to connect your agent framework to Truto. Truto acts as the proxy layer, dynamically supplying the OpenAPI specifications for Alloy and routing the authenticated API calls. This works natively with LangChain, LangGraph, CrewAI, or the Vercel AI SDK.

### 1. Fetching the Tools

First, your application needs to query Truto to retrieve the available proxy tools for your connected Alloy account. Truto handles the OAuth token lifecycle and tenancy mapping.

```bash
curl -X GET "https://api.truto.one/integrated-account/{integrated_account_id}/tools" \
  -H "Authorization: Bearer <TRUTO_API_KEY>"
```

If you want to restrict the agent to read-only operations to prevent accidental data modification, you can use the `methods` query parameter:

```bash
curl -X GET "https://api.truto.one/integrated-account/{integrated_account_id}/tools?methods[0]=read" \
  -H "Authorization: Bearer <TRUTO_API_KEY>"
```

### 2. Binding Tools to the Agent

If you are using LangChain.js, Truto provides the `truto-langchainjs-toolset` which handles the dynamic registration of these tools. You initialize the tool manager, fetch the tools, and bind them directly to your chosen LLM (e.g., GPT-4o, Claude 3.5 Sonnet).

```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 runAlloyFraudAgent() {
  // 1. Initialize the Truto Tool Manager with your API Key and Account ID
  const trutoToolManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: "your_alloy_account_id",
  });

  // 2. Fetch the tools programmatically
  const tools = await trutoToolManager.getTools();

  // 3. Initialize your LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });

  // 4. Bind the tools to the LLM
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an elite fraud operations agent. You have access to Alloy to triage investigations and review cases. Respect the required token schemas carefully."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);

  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });

  const agentExecutor = new AgentExecutor({
    agent,
    tools,
    verbose: true,
  });

  // 5. Execute the workflow
  const result = await agentExecutor.invoke({
    input: "Review all open investigations. For any investigation with a risk score above 75, retrieve the associated person entities and leave an investigation note summarizing their details."
  });

  console.log(result.output);
}

runAlloyFraudAgent();
```

### 3. Handling Errors and Rate Limits in the Agent Loop

The `AgentExecutor` runs a ReAct (Reasoning and Acting) loop. When a tool call is executed, the request passes through Truto to Alloy. 

```mermaid
sequenceDiagram
    participant Agent as AI Agent
    participant Truto as Truto Proxy Layer
    participant Alloy as Alloy API
    
    Agent->>Truto: Execute get_single_alloy_case_by_id
    Truto->>Alloy: GET /v1/cases/{id}
    Alloy-->>Truto: Return 200 OK (Case JSON)
    Truto-->>Agent: Return normalized JSON schema
    Agent->>Agent: Parse entity_token for next step
    Agent->>Truto: Execute create_a_alloy_evaluation
```

As noted earlier, if your agent makes too many requests and triggers a 429 rate limit, Truto will pass the 429 status and the standardized `ratelimit-reset` header directly back to the `TrutoToolManager`. 

In a production environment, you should wrap your agent execution or tool invocation logic in a backoff handler that reads these headers. Frameworks like LangGraph allow you to build explicit error-handling edges in your graph to gracefully pause execution and wait for the rate limit window to clear before retrying the node.

## Moving Past the Integration Bottleneck

Building AI agents that interact with highly complex, regulated APIs like Alloy is an architectural challenge. The integration bottleneck - managing authentication, parsing deeply nested JSON schemas, tracking polymorphic entity types, and handling token chains - derails AI projects before they reach production.

By using Truto's `/tools` endpoint, you completely bypass the need to write and maintain custom integration code. Your engineering team can focus on refining agent prompts, designing secure human-in-the-loop approval workflows, and improving compliance models, while Truto handles the underlying API proxying and schema normalization.

::cta{buttonText="Talk to us" buttonUrl="https://cal.com/truto/partner-with-truto"}
Ready to give your AI agents autonomous access to Alloy? Partner with Truto to instantly deploy enterprise-grade integrations without writing a single line of API wrapper code.
::