Connect Herd Security to AI Agents: Track Security Education Progress

You want to connect Herd Security to an AI agent so your internal systems can independently track security education progress, audit training enrollments, cross-reference compliance tags, and manage user directories. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually code dozens of API wrappers or maintain complex authentication logic.

Giving a Large Language Model (LLM) read and write access to your security awareness platform is an engineering challenge, especially when navigating how to safely give an AI agent access to third-party SaaS data. You either spend weeks building, hosting, and maintaining a custom connector that understands the relational graph between users, enrollments, and tags, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Herd Security to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Herd Security 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 Herd Security, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex compliance auditing 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 Herd Security Connectors

Building AI agents is easy. Connecting them to external SaaS 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. In production, this approach collapses entirely, especially with highly relational data models like those found in security compliance platforms.

If you decide to build a custom Herd Security integration yourself, you own the entire API lifecycle. The Herd Security API introduces specific integration challenges that break standard LLM assumptions.

The Multi-Hop Relational Trap

Herd Security does not provide a single flat endpoint that says "Give me all users who failed their SOC 2 training." Instead, it relies on a highly normalized relational model. Trainings are associated with tags. Users are associated with enrollments. Enrollments reference trainings.

When an AI agent wants to find non-compliant users for a specific framework, standard REST conventions fail if the agent isn't given precise, isolated tools. The agent must first query the tags to find the tag_id for "SOC 2". It must then query the tag trainings to find the associated training_ids. Next, it must fetch enrollments to find which users have those trainings assigned, checking the status and completion_date. Finally, it must query the user directory to map a user_id to an actual email address.

If you hand-code this integration, you have to write complex prompts to teach the LLM the exact order of operations. When the LLM inevitably hallucinates an aggregate endpoint like GET /users?failed_tag=SOC2, the workflow breaks. You need a system that provides discrete, schema-defined tools that force the LLM to traverse the graph one logical step at a time.

Silent Failures and Temporal State

Security training data is inherently temporal. An enrollment isn't just a boolean "done" or "not done". It possesses an enrollment_date, a completion_date, and various statuses (assigned, in progress, completed, expired).

When an LLM attempts to analyze compliance, it often struggles to parse the delta between dates unless the data is returned in a strict, predictable schema. If your custom API wrapper silently drops null fields - for example, omitting completion_date entirely when a course isn't finished rather than explicitly returning null - the LLM loses contextual grounding. The LLM might assume the field doesn't exist, leading to hallucinations about the user's status. Truto's proxy architecture enforces strict schema adherence, ensuring that the LLM receives consistently formatted payloads regardless of how the underlying Herd Security API structures its empty states.

Truto's Architecture for Tool Calling

To solve these challenges, Truto maps the Herd Security API into a comprehensive JSON object that represents how the underlying product behaves. Think of it as an optimized Swagger file built specifically for deterministic agent execution, making it the best unified API for LLM function calling and AI agent tools.

Integrations in Truto possess Resources (e.g., users, enrollments), which map to endpoints on the underlying API. Every Resource has Methods defined on them (List, Get, Create, Update, Delete).

The Methods on the Resources are exposed as Proxy APIs. Truto handles all the underlying pagination, authentication, and query parameter processing. We then provide a set of tools for your LLM frameworks by offering a description and JSON schema for all the Methods defined on an integration.

By calling the GET https://api.truto.one/integrated-account/<id>/tools endpoint, your application receives an array of perfectly formatted AI tools. You can bind these directly to your agent.

sequenceDiagram
    participant Agent as "LLM Agent (LangChain)"
    participant Truto as "Truto Tool Manager"
    participant Herd as "Herd Security API"

    Agent->>Truto: GET /integrated-account/<id>/tools
    Truto-->>Agent: Returns JSON Schema for Herd Tools
    Agent->>Agent: .bindTools(tools)
    Note right of Agent: Agent now understands<br>Herd Security schema natively

A Crucial Note on Rate Limits

When connecting AI agents to SaaS platforms, rate limits are the silent killer of autonomous workflows. An agent executing a multi-step audit might trigger a dozen API calls in under a second.

It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When the Herd Security API returns an HTTP 429 Too Many Requests error, 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 and applying the appropriate retry or backoff logic. Do not assume the infrastructure layer will absorb these errors. You must build your agent loops to gracefully pause execution when a 429 is encountered.

Herd Security Hero Tools for AI Agents

Rather than dumping hundreds of raw endpoints into your LLM's context window - which guarantees hallucinations and context exhaustion - Truto exposes highly targeted, schema-backed tools. Here are the core Herd Security tools you can leverage immediately.

List All Herd Security Enrollments

This tool retrieves the complete ledger of training enrollments for your organization. It returns the critical junction data: enrollment_id, user_id, tag_id, training_id, enrollment_date, completion_date, and status.

Because this tool returns raw foreign keys (user_id, training_id), the LLM will naturally learn to cross-reference this data with other tools to build a complete picture of a user's compliance state.

"Fetch the latest training enrollments for our organization and identify any enrollments where the status is 'assigned' but the enrollment_date was over 30 days ago."

List All Herd Security Users

This tool exposes the core employee directory within Herd Security, returning user_id, first_name, last_name, email, and status.

Agents use this tool primarily as a resolution layer. When analyzing an enrollment record, the agent needs to translate a meaningless UUID into an actionable email address to notify a manager or compile a human-readable audit report.

"Retrieve the user directory from Herd Security. Find the user ID for alice.smith@company.com so we can look up her training records."

List All Herd Security Tags

Tags are the organizational backbone of Herd Security. They group trainings by compliance framework (e.g., GDPR, HIPAA), department (e.g., Engineering, Sales), or timeframe (e.g., Q1 Security Refresh). This tool returns the tag_id, name, status, start_date, end_date, and created_at.

"List all active tags in Herd Security and find the specific tag ID associated with our 'Annual SOC 2 Compliance' requirement."

List All Herd Security Tag Trainings

Once an agent identifies a specific tag, it uses this tool to discover exactly which trainings are bundled under that tag. It requires the tag_id as a parameter and returns the training_id, title, and description.

"Using the tag ID for 'Annual SOC 2 Compliance', list all the specific trainings required to satisfy that tag."

To view the complete inventory of available methods, schemas, and required parameters, visit the Herd Security integration page.

Workflows in Action

Giving an LLM access to these tools enables complex, autonomous revenue and compliance operations. Here is exactly how an agent behaves when tasked with real-world scenarios.

Scenario 1: The SOC 2 Compliance Audit

IT and Security administrators spend hours chasing down employees who haven't completed mandatory compliance training. An agent can fully automate this audit.

"Identify all employees who have not completed their required SOC 2 training and compile a list of their names and email addresses."

Step-by-step Execution:

1. The agent calls list_all_herd_security_tags to search for the tag named "SOC 2" and extracts the tag_id.
2. The agent calls list_all_herd_security_tag_trainings passing the tag_id to get the list of required training_ids.
3. The agent calls list_all_herd_security_enrollments to fetch the global enrollment ledger.
4. The agent filters the enrollments locally, matching the SOC 2 training_ids and isolating records where the status does not equal "completed".
5. The agent gathers the user_ids from the incomplete enrollments.
6. The agent calls list_all_herd_security_users to resolve those IDs into actual names and email addresses.

Result: The user receives a perfectly formatted markdown table of non-compliant employees, ready to be exported to an IT ticketing system or Slack.

Scenario 2: New Hire Onboarding Verification

When a new batch of employees is provisioned, HR needs to verify that their foundational security modules have been properly assigned and activated in the system.

"Check the Herd Security user list for anyone added this week. Verify if they have been assigned the 'Phishing Defense 101' training, and tell me their current enrollment status."

Step-by-step Execution:

1. The agent calls list_all_herd_security_users and filters the returned array for users created or activated in the last 7 days.
2. The agent calls list_all_herd_security_enrollments to pull the active training assignments.
3. The agent cross-references the new user_ids with the enrollments.
4. If "Phishing Defense 101" is not explicitly linked to a tag, the agent might infer the training directly from the enrollments payload or request a tag lookup to verify the specific training_id.

Result: The user receives a status report confirming which new hires are correctly enrolled and highlights any missing assignments that require manual intervention.

Building Multi-Step Workflows

Building this in code requires mapping the Truto tools to your agent framework. While this example uses LangChain, the concept is framework-agnostic and applies equally to Vercel AI SDK, LlamaIndex, or raw API calls.

First, you initialize the TrutoToolManager using the truto-langchainjs-toolset. This fetches the proxy APIs dynamically based on the integrated account ID.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { HumanMessage } from "@langchain/core/messages";
 
async function runHerdSecurityAudit(integratedAccountId: string) {
  // 1. Initialize the LLM
  const llm = new ChatOpenAI({ 
    modelName: "gpt-4o",
    temperature: 0 
  });
 
  // 2. Fetch tools from Truto
  const toolManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY,
  });
 
  // Fetch all read-only methods for Herd Security
  const tools = await toolManager.getTools(integratedAccountId, ["read"]);
 
  // 3. Bind tools to the LLM natively
  const agentWithTools = llm.bindTools(tools);
 
  // 4. Invoke the agent
  const response = await agentWithTools.invoke([
    new HumanMessage("Find all users who haven't finished their SOC 2 training.")
  ]);
 
  return response;
}

Handling Rate Limits in the Agent Loop

As mentioned earlier, Truto passes 429 rate limit errors directly to you. An autonomous agent will crash if it hits a 429 while trying to page through 10,000 enrollments. You must intercept the tool execution or wrap the tool calls in a backoff handler that respects the ratelimit-reset header.

flowchart TD
    A["Agent Invokes Tool"] --> B["Truto Proxy API"]
    B --> C["Herd Security Upstream"]
    C -- "HTTP 429 Too Many Requests" --> B
    B -- "Passes 429 + ratelimit-* headers" --> A
    A --> D{"Check ratelimit-reset header"}
    D -- "Wait X seconds" --> A
    C -- "HTTP 200 OK" --> E["Return Data to LLM Context"]

When building a production-grade agent loop (for example, using LangGraph), you must check the metadata of the failed tool call. If the status is 429, extract ratelimit-reset, pause the agent's execution thread, and retry the tool call before returning control to the LLM. If you allow the LLM to see the 429 error text directly, it will often apologize and give up, hallucinating a failure message to the end user.

Strategic Architecture for Agent Integration

The era of hardcoding point-to-point API wrappers for AI agents is over. Hardcoded integrations are fragile, require constant maintenance to keep up with schema drift, and force your engineering team to become experts in the proprietary quirks of every vendor in your ecosystem.

By leveraging Truto's /tools endpoint, you abstract the connectivity layer entirely. The LLM receives standard, deterministic JSON schemas for Herd Security resources. It can securely traverse relational graphs, execute complex audits, and map users to compliance statuses without you writing a single line of Herd Security-specific code. Your engineering team focuses on building better agentic logic and optimizing prompts, while Truto handles the underlying infrastructure.