Connect Humaans to AI Agents: Automate Lifecycles and Timesheets

You want to connect Humaans to an AI agent so your system can autonomously onboard employees, audit timesheets, process promotions, and orchestrate complex HR lifecycles. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to write custom integration boilerplate for your Human Resources Information System (HRIS).

Giving a Large Language Model (LLM) read and write access to an HRIS requires strict state management and flawless schema validation. You cannot afford for a model to hallucinate a salary update or corrupt an employee's organizational assignment. If your team relies on ChatGPT, check out our guide on connecting Humaans to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Humaans to Claude. For engineers building custom autonomous systems, you need a programmatic way to fetch HR tools and bind them to your agent architecture securely.

This guide details exactly how to fetch AI-ready tools for Humaans, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute automated HR operations workflows. For a deeper look at the core design patterns behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of the Humaans API

Building an AI agent is fundamentally an exercise in prompt engineering and state management. However, giving that agent reliable access to external infrastructure APIs is where production deployments fail. If you decide to build a custom Humaans connector from scratch, you own the entire API lifecycle. You must write the JSON schemas for the LLM to understand the endpoints, handle the OAuth token lifecycle, normalize pagination, and maintain strict data validation.

Humaans introduces several highly 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 instead of improving your model's reasoning capabilities.

Temporal Data and Effective Dates

In standard SaaS APIs, if a user gets a promotion, you issue a PATCH request to the user endpoint and update their job_title. In Humaans, this approach is fundamentally invalid.

Humaans relies on temporal data models. A person is the root object, but their roles and compensation exist as independent, time-bound records. When an employee is promoted, you do not update the humaans_people record. Instead, you create a new humaans_job_roles record and a new humaans_compensations record, both bound to an effective_date. If you expose raw endpoints to an LLM without strict tool definitions, the agent will inevitably attempt to directly patch the person object and fail.

Relational Graph Fragmentation

HR data in Humaans is heavily normalized. To fully understand an employee's profile, an agent must traverse multiple discrete resources. An employee's department lives in humaans_org_unit_assignments, their schedule lives in humaans_working_pattern_allocations, and their physical location lives in humaans_locations.

Without an orchestration layer providing clean, structured tools, an LLM easily loses track of foreign keys. It will attempt to pass a string like "Engineering" to a field that strictly requires an org_unit_id UUID.

Handling Strict Rate Limits

Agent loops are aggressive. An autonomous agent tasked with auditing 500 timesheets can easily exhaust API rate limits in seconds.

It is critical to understand how Truto interacts with upstream limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Humaans API returns an HTTP 429, Truto passes that exact error to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF specification.

Do not expect the infrastructure layer to absorb these errors automatically. The caller (your agent framework) is entirely responsible for retry and backoff logic. Your system must read the ratelimit-reset header and sleep the agent thread accordingly.

Why a Unified Tool Layer Matters for Agent Safety

Direct API tools - exposing one tool per raw Humaans endpoint - push provider quirks into the LLM's context window. The model has to memorize that Humaans requires $limit and $skip for pagination, that temporal records require specific ISO 8601 string formats for effective dates, and that bank accounts are stored distinctly from the core profile.

A unified tool layer maps the underlying resources into clean, deterministic Proxy APIs. By collapsing these quirks behind a strict schema, your agent sees reliable operations like list_all_humaans_people and create_a_humaans_compensation.

This provides three concrete safety wins for production agents:

1. Elimination of syntax hallucinations. The LLM only chooses from stable function names and strict JSON schema parameters. It never invents proprietary Humaans query operators.
2. Deterministic validation. Invalid arguments are rejected at the proxy layer before they ever hit the Humaans API, causing the tool call to fail fast and prompting the agent to correct itself.
3. Cross-platform portability. By abstracting the HTTP boilerplate, your agent orchestration logic remains clean and focused solely on the business rules of human resources.

Core Humaans AI Agent Tools

Truto provides all defined resources on an integration as tools for your LLM frameworks to use. By calling the /integrated-account/:id/tools endpoint, you receive a payload of Proxy APIs with descriptions and schemas ready to be bound to your agent.

Here are the highest-leverage hero tools for automating Humaans workflows.

list_all_humaans_people

This is the starting point for almost every agentic HR workflow. It allows the agent to search the directory, find specific employees by name or email, and retrieve their root id which is required for all subsequent operations.

Usage note: Because Humaans separates roles and profiles, the agent uses this tool purely to locate the employee and establish the target UUID before calling downstream tools.

"Find the Humaans profile for Sarah Connor in the Engineering department and return her unique person ID."

create_a_humaans_job_role

Automates promotions, title changes, and organizational restructuring. Instead of overwriting a current role, this tool creates a new temporal record indicating when the new job title and reporting line take effect.

Usage note: Ensure your agent's system prompt explicitly instructs it to provide the effective_date parameter in YYYY-MM-DD format.

"Sarah Connor has been promoted to Senior Backend Engineer. Create a new job role record for her starting on the first of next month, reporting to the VP of Engineering."

create_a_humaans_compensation

Handles salary adjustments, bonuses, and equity grants. Like job roles, compensations are time-bound records tied to the person object.

Usage note: The LLM must pass the exact currency code and amount alongside the effective date. Do not allow the model to guess the currency; configure the tool schema or system prompt to enforce standard fiat codes.

"Increase Sarah Connor's base salary to $165,000 USD, effective immediately alongside her promotion."

update_a_humaans_time_away_by_id

Enables AI agents to act as intelligent approval mechanisms for leave requests. The agent can review an unapproved time away entry, check it against project deadlines or team capacity, and patch the status to approved or rejected.

Usage note: The agent must first use the list tools to find pending requests, identify the target ID, and then issue the update.

"Review the pending time away request ID 84729 for next week. Our project schedule shows no conflicts, so go ahead and mark the request as approved."

list_all_humaans_timesheet_submissions

Critical for automated payroll auditing. This tool retrieves blocks of worked time submitted by employees, allowing the agent to verify hours against standard working pattern allocations.

Usage note: Supports Humaans query filters and $limit / $skip pagination, meaning the agent can safely request submissions for a specific week without overloading its context window.

"Fetch all pending timesheet submissions for the London office from the past 14 days so we can audit them for overtime compliance."

list_all_humaans_org_unit_assignments

Maps the company hierarchy. An agent can use this tool to determine which team, department, or division an employee currently belongs to, which is essential for routing approval workflows.

Usage note: Often used in tandem with list_all_humaans_people to resolve the current organizational graph.

"List all employees currently assigned to the 'Platform Infrastructure' organizational unit."

For the complete inventory of available operations - including bank accounts, emergency contacts, public holidays, and custom fields - refer to the Humaans integration page.

Workflows in Action

Single tool calls are useful for chat interfaces, but true agentic automation requires chaining multiple operations based on business logic. Here is how these tools power concrete, real-world HR workflows.

Workflow 1: The Automated Promotion Pipeline

When a promotion is approved in Slack or Jira, HR teams traditionally spend 20 minutes manually updating disparate records in Humaans. An AI agent can orchestrate this entire lifecycle instantly.

"Marcus Johnson was just approved for a promotion to Staff Product Manager with a salary increase to £95,000 GBP, effective on the 15th of this month. Process this in Humaans."

1. Identify Target: The agent calls list_all_humaans_people filtering for "Marcus Johnson" to retrieve his id.
2. Assign New Role: The agent calls create_a_humaans_job_role passing Marcus's ID, the title "Staff Product Manager", and the effective date of the 15th.
3. Update Salary: The agent calls create_a_humaans_compensation passing Marcus's ID, the amount 95000, the currency GBP, and the matching effective date.

Outcome: The system successfully registers the promotion without losing historical records of Marcus's previous role and salary, adhering perfectly to Humaans's temporal data requirements.

Workflow 2: Timesheet Overtime Auditing

Payroll administrators waste hours manually verifying timesheets against expected working patterns. An AI agent can autonomously audit these submissions.

"Run the weekly timesheet audit for the customer support team. Flag any submission that exceeds 40 hours and approve the rest."

1. Retrieve Roster: The agent calls list_all_humaans_org_unit_assignments to find all employees in the "Customer Support" unit.
2. Fetch Timesheets: The agent iterates through the roster, calling list_all_humaans_timesheet_submissions for each employee over the specified date range.
3. Analyze and Act: The agent calculates total hours. For compliant timesheets, it calls the update tool to mark them as approved. For violations, it triggers an external alert (e.g., sending a Slack message via a different integration tool).

Outcome: Hundreds of timesheets are processed in seconds. The HR team only reviews the flagged exceptions.

sequenceDiagram
    participant AI as AI Agent
    participant Truto as Truto Tool Layer
    participant Humaans as Humaans API

    AI->>Truto: Call list_all_humaans_org_unit_assignments
    Truto->>Humaans: GET /org-unit-assignments
    Humaans-->>Truto: Return assignments
    Truto-->>AI: Employee IDs

    loop For Each Employee
        AI->>Truto: Call list_all_humaans_timesheet_submissions
        Truto->>Humaans: GET /timesheets
        Humaans-->>Truto: Return hours
        Truto-->>AI: Audit data
        alt Hours <= 40
            AI->>Truto: update_a_humaans_timesheet_submission
            Truto->>Humaans: PATCH /timesheets/:id (Approve)
        else Hours > 40
            AI->>AI: Flag for manual review
        end
    end

Building Multi-Step Workflows

To build these multi-step workflows, you need to programmatically load the Humaans tools into your framework of choice. Truto is framework-agnostic. The /tools endpoint serves definitions that can be consumed by LangChain, Vercel AI SDK, or custom orchestration loops.

The critical engineering task is handling execution failures, specifically rate limits. Because Truto passes HTTP 429 errors directly to the caller and standardizes the headers to ratelimit-reset, your code must catch these exceptions and pause the agent.

Here is how you initialize the agent and handle execution using the TrutoToolManager from the truto-langchainjs-toolset:

import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage } from "@langchain/core/messages";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runHumaansAgent() {
  // 1. Initialize the LLM
  const model = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 2. Fetch Humaans tools for the specific integrated account
  const toolManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: "humaans-account-uuid-1234",
  });
 
  // Filter for specific HR tools to save context window
  const tools = await toolManager.getTools({
    methods: ["read", "write"],
  });
 
  // 3. Bind the Truto proxy tools to the LLM
  const modelWithTools = model.bindTools(tools);
 
  // 4. Issue the prompt to start the workflow
  const messages = [new HumanMessage("Process a promotion for Sarah Connor to Senior Engineer with a new salary of $150k effective today.")];
  
  let isComplete = false;
 
  // 5. The Agent Loop
  while (!isComplete) {
    const response = await modelWithTools.invoke(messages);
    messages.push(response);
 
    if (response.tool_calls && response.tool_calls.length > 0) {
      for (const toolCall of response.tool_calls) {
        try {
          console.log(`Agent executing tool: ${toolCall.name}`);
          
          // Execute the tool against the Truto Proxy API
          const toolResult = await toolManager.executeTool(
            toolCall.name,
            toolCall.args
          );
          
          messages.push({
            role: "tool",
            name: toolCall.name,
            content: JSON.stringify(toolResult),
            tool_call_id: toolCall.id,
          });
          
        } catch (error) {
          // 6. Mandatory Rate Limit Handling
          if (error.status === 429) {
            // Truto normalizes these headers directly from Humaans
            const resetInSeconds = error.headers['ratelimit-reset'] || 5;
            console.warn(`Rate limit hit. Agent sleeping for ${resetInSeconds} seconds.`);
            
            await new Promise(resolve => setTimeout(resolve, resetInSeconds * 1000));
            
            // Inform the agent of the delay so it can retry the operation
            messages.push({
              role: "tool",
              name: toolCall.name,
              content: `Error: Rate limit exceeded. Paused for ${resetInSeconds}s. Please retry the operation.`,
              tool_call_id: toolCall.id,
            });
          } else {
            // Handle standard API errors (e.g., validation failures)
            messages.push({
              role: "tool",
              name: toolCall.name,
              content: `Error executing tool: ${error.message}`,
              tool_call_id: toolCall.id,
            });
          }
        }
      }
    } else {
      // No more tool calls required
      isComplete = true;
      console.log("Agent finished:", response.content);
    }
  }
}
 
runHumaansAgent();

This execution loop gives the LLM total autonomy over Humaans data while safely trapping state changes inside standard JSON validation. When Humaans throttles the connection, the agent thread sleeps, respecting the ratelimit-reset header, and automatically retries without crashing the pipeline.

Scale HR Automation with Truto

Providing an AI agent with access to an HRIS like Humaans is dangerous if done incorrectly. Direct integration scripts fall apart against temporal data models, strict pagination formats, and rate limits. By utilizing Truto's /tools endpoint, you abstract the entire integration lifecycle into safe, predictable, framework-agnostic function calls.

Your engineers stop writing defensive integration code and start focusing on the core reasoning loops of your agents.