Connect UKG Ready to AI Agents: Automate Benefits and Compensation

You want to connect UKG Ready to an AI agent so your system can autonomously calculate final pay, update compensation histories, manage leave of absence cases, and automate benefits enrollment. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom UKG Ready integration from scratch.

Human Resources Information Systems (HRIS) and payroll platforms are complex, highly relational data stores. Giving a Large Language Model (LLM) read and write access to a UKG Ready instance requires extreme precision. You cannot afford to let an LLM guess at payload structures when dealing with compensation records or payroll finalization. If your team uses ChatGPT, check out our guide on connecting UKG Ready to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting UKG Ready 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 UKG Ready, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex HR operations. For a broader look at this design pattern, read our research on architecting AI agents and the SaaS integration bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing integration code for your AI agent, you must decide how the agent will interact with external APIs. Building direct tool definitions for raw UKG Ready endpoints might seem straightforward in a prototype, but it pushes provider-specific quirks directly into the LLM's context.

When an agent has to remember that one HRIS expects XML, another expects deeply nested JSON:API structures, and a third requires JSON Patch for updates, you are maximizing the attack surface for hallucination.

Providing an agent with a normalized tool layer standardizes the interface. Your agent simply sees well-defined operations with strict JSON schemas. This offers distinct engineering advantages:

1. Deterministic input validation: Every tool has a strict JSON schema that Truto derives from the underlying API. Invalid arguments are rejected fast, before they hit the upstream CRM or HRIS.
2. Reduced prompt context: You do not need to burn tokens teaching the model about UKG's specific authentication headers or pagination cursors. The proxy layer handles the boilerplate.
3. Stable tool boundaries: The LLM chooses from a stable list of function names. It does not invent random URL paths or query parameters.

The Engineering Reality of the UKG Ready API

Integrating with UKG Ready reveals a rigid, highly structured enterprise system. When building AI agent workflows against this API, you will encounter several specific technical constraints that break standard REST assumptions. Hardcoding these rules into your agent's prompt is a brittle strategy.

Conditional Subsystem Dependencies

UKG Ready is highly modular. Endpoints are not universally available; they are strictly gated by the specific subsystems active on the target company's account. For example, querying time-off requests might require the TA, TALITE, or HR functionality to be enabled. Attempting to manage shift collections requires the Advanced Scheduler (__SCHEDULE__) subsystem. If your agent blindly attempts to execute an operation on a disabled subsystem, it will crash against a permissions wall. The tool layer must abstract these capability checks or clearly define the required state in the schema.

The Omnipresent Company ID (CID)

Virtually every endpoint in the UKG Ready API requires a Company ID (cid). UKG Ready is often deployed in multi-entity structures where a single authentication context might span multiple operational companies. Your agent must consistently pass the correct cid in its request parameters to resolve payroll, employees, or profiles.

JSON Patch for Partial Updates

Unlike modern APIs that accept simple PUT or PATCH requests with flat JSON bodies for partial updates, UKG Ready frequently requires standard JSON Patch (RFC 6902) format for updating resources like employee profiles (update_a_ukg_ready_employee_by_id). This means the LLM cannot just send {"account_status": "Terminated"}. It must formulate an array of patch operations: [{"op": "replace", "path": "/account_status", "value": "Terminated"}].

Managing API Rate Limits

Enterprise APIs protect their infrastructure aggressively. When your agent executes a loop that lists employees, parses records, and updates benefits, it can quickly exhaust the allowed request limits.

Truto does not auto-retry, throttle, or apply backoff on rate limit errors. When the upstream UKG Ready API returns an HTTP 429 (Too Many Requests), Truto passes that error directly back to the caller. However, Truto normalizes the upstream rate limit information into standardized IETF spec headers:

• ratelimit-limit: The maximum number of requests permitted in the current window.
• ratelimit-remaining: The number of requests left in the current window.
• ratelimit-reset: The time at which the current rate limit window resets.

Your application code must read these headers, implement an appropriate delay (backoff), and retry the tool execution. Do not rely on the LLM to "wait" - handle the HTTP 429 at the orchestration layer before handing the error back to the model.

Building Multi-Step Workflows

To build autonomous HR operations, you need an orchestration loop that provides the LLM with the UKG Ready tools, executes the chosen tool via Truto, and handles operational errors like rate limits.

Below is a framework-agnostic implementation using TypeScript, LangChain's .bindTools(), and the Truto SDK to connect an AI agent to UKG Ready.

sequenceDiagram
    participant Agent as AI Agent (LLM)
    participant Framework as Execution Loop
    participant TrutoAPI as Truto (/tools)
    participant UKGReady as UKG Ready API

    Agent ->> Framework: Request action (e.g. Terminate Employee)
    Framework ->> TrutoAPI: Call execute_tool(update_employee, payload)
    TrutoAPI ->> UKGReady: Execute upstream HTTP request
    UKGReady -->> TrutoAPI: HTTP 429 Too Many Requests
    TrutoAPI -->> Framework: 429 Error + ratelimit-reset Header
    Framework -->> Framework: Sleep until ratelimit-reset
    Framework ->> TrutoAPI: Retry execute_tool(update_employee, payload)
    TrutoAPI ->> UKGReady: Execute upstream HTTP request
    UKGReady -->> TrutoAPI: 200 OK
    TrutoAPI -->> Framework: Normalized JSON response
    Framework -->> Agent: Tool Result (Success)

Fetching and Binding Tools

First, we instantiate the TrutoToolManager, fetch the proxy tools for the integrated UKG Ready account, and bind them to the LLM.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { HumanMessage } from "@langchain/core/messages";
 
async function runUKGWorkflow() {
  // 1. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 2. Initialize Truto Tool Manager with your Integrated Account ID
  const toolManager = new TrutoToolManager({
    integratedAccountId: process.env.UKG_READY_ACCOUNT_ID,
    trutoApiKey: process.env.TRUTO_API_KEY,
  });
 
  // 3. Fetch tools dynamically from Truto's /tools endpoint
  // We can filter by methods if we only want read or write operations
  const tools = await toolManager.getTools();
  
  console.log(`Loaded ${tools.length} UKG Ready tools.`);
 
  // 4. Bind the tools to the LLM using standard LangChain syntax
  const llmWithTools = llm.bindTools(tools);
 
  // 5. Start the conversation
  const messages = [new HumanMessage("Find employee John Doe and check their leave of absence counter.")];
  
  await executeAgentLoop(llmWithTools, tools, messages);
}

The Execution Loop and Rate Limit Handling

When the agent decides to use a tool, your framework must execute the function. Because Truto passes HTTP 429s directly to you, your execution loop is the perfect place to enforce backoff logic.

async function executeAgentLoop(llmWithTools, tools, messages) {
  let isComplete = false;
 
  while (!isComplete) {
    // Invoke the model with the current conversation history
    const response = await llmWithTools.invoke(messages);
    messages.push(response);
 
    if (response.tool_calls && response.tool_calls.length > 0) {
      for (const toolCall of response.tool_calls) {
        console.log(`Executing tool: ${toolCall.name}`);
        
        // Find the corresponding tool definition
        const tool = tools.find(t => t.name === toolCall.name);
        
        try {
          // Execute the API call via Truto
          const result = await tool.invoke(toolCall.args);
          
          messages.push({
            role: "tool",
            name: toolCall.name,
            tool_call_id: toolCall.id,
            content: JSON.stringify(result)
          });
        } catch (error) {
          // Handle HTTP 429 Rate Limits explicitly
          if (error.status === 429) {
            const resetTimeStr = error.headers['ratelimit-reset'];
            const resetTimeMs = resetTimeStr ? parseInt(resetTimeStr, 10) * 1000 : Date.now() + 5000;
            const waitTime = Math.max(0, resetTimeMs - Date.now());
            
            console.warn(`Rate limited by UKG Ready. Backing off for ${waitTime}ms...`);
            await new Promise(resolve => setTimeout(resolve, waitTime));
            
            // Inform the LLM that a retry is required
            messages.push({
              role: "tool",
              name: toolCall.name,
              tool_call_id: toolCall.id,
              content: "Error: Rate limit exceeded. The system has backed off. Please retry the exact same operation."
            });
          } else {
            // Handle other operational errors (e.g. 400 Bad Request, 404 Not Found)
            messages.push({
              role: "tool",
              name: toolCall.name,
              tool_call_id: toolCall.id,
              content: `Error executing tool: ${error.message}`
            });
          }
        }
      }
    } else {
      // The model returned a final text response
      console.log("Agent finished:", response.content);
      isComplete = true;
    }
  }
}

UKG Ready Hero Tools for AI Agents

Truto exposes the entirety of the UKG Ready API as tools. Here are the highest-leverage endpoints you should supply to an AI agent orchestrating benefits and compensation.

Get Single UKG Ready Employee By ID

Retrieves the core employee record, including account status, employee ID, and external IDs. This is the prerequisite step for almost all operations, as the agent needs the exact internal ID to execute updates or retrieve sub-resources.

"Fetch the core record for employee ID 59281 in company profile 101 to verify their current active status."

Update a UKG Ready Employee By ID

Applies partial updates to an employee record using the JSON Patch specification. This is critical for status changes (like termination), profile updates, or updating custom demographics without overwriting the entire record.

"Update the account status of employee 59281 to 'Terminated' and provide the required termination details in the JSON patch payload."

List All UKG Ready Employee Accrual Balances (v2)

Retrieves the time-off and accrual balances for an employee, allowing the agent to verify if a worker has enough PTO or sick leave remaining to cover an incoming absence request.

"Check the accrual balances for employee 59281 to see if they have at least 40 hours of PTO available for the current period."

Create a UKG Ready LOA Case

Submits a new Leave of Absence (LOA) case into the system. The agent can use this after verifying eligibility or receiving documentation from the worker.

"Open a new Leave of Absence case for employee 59281 starting next Monday, using the medical leave reason code."

Create a UKG Ready Company Payroll

Initiates a new unscheduled payroll run (Historical, Regular, or Void). This is heavily utilized in offboarding workflows where a final paycheck must be calculated outside the normal bi-weekly batch.

"Create a new unscheduled off-cycle payroll for company 101 to process final termination pay for employee 59281."

List All UKG Ready Company Benefits

Lists employee benefit plans for a specific coverage date range. This allows the agent to audit current coverages before triggering open enrollment workflows or processing life event changes.

"List all active benefit plans for company 101 covering the date range of January 1 to December 31 of this year."

For the complete schema definitions and the full list of available operations, view the UKG Ready integration page.

Workflows in Action

When you combine a capable reasoning model with stable API tools, you can automate complex HR operations that traditionally require heavy manual intervention from administrators.

Scenario 1: Autonomous Offboarding and Final Pay

When an employee resigns, HR must terminate their record, clear their schedules, and trigger a final paycheck. An agent can handle this end-to-end.

"Employee John Doe (ID: 59281) submitted his resignation effective today. Terminate his account, delete any future scheduled shifts, and initiate a final off-cycle payroll run for his remaining hours."

1. The agent calls get_single_ukg_ready_employee_by_id to verify John Doe's current status and metadata.
2. The agent calls update_a_ukg_ready_employee_by_id using a JSON Patch array to change the account status to Terminated and injects the termination date.
3. The agent calls ukg_ready_employee_schedules_bulk_delete passing the target dates from tomorrow onward to clear his calendar.
4. Finally, the agent calls create_a_ukg_ready_company_payroll configuring a final payout for the employee.

The user receives confirmation that the employee profile is closed, the schedule is clean, and the final payroll batch is waiting for administrator approval.

Scenario 2: Leave of Absence (LOA) Adjudication

Employees frequently ask HR if they can take extended leave. An AI agent can review the policy, check the balance, and open the case without HR bottlenecking the request.

"I need to take 3 weeks of medical leave starting on October 1st. Do I have enough time accrued, and can you open the case for me?"

1. The agent calls ukg_ready_employees_me (or searches by email) to get the authenticated user's employee_id and cid.
2. The agent calls list_all_ukg_ready_employee_accrual_balances_v_2 to retrieve the current balances and entitlements for sick and vacation time.
3. Seeing the employee has enough banked time, the agent calls create_a_ukg_ready_loa_case passing the start date, estimated end date, and reason code.
4. The agent returns a message to the user confirming the case number and outlining the next steps for medical documentation upload.

Wrapping Up

Integrating AI agents with complex, stateful systems like UKG Ready requires more than a simple HTTP fetch wrapper. It demands structured schemas, predictable tool names, and disciplined handling of enterprise API quirks like subsystem permissions and rate limits.

By leveraging Truto's /tools endpoint, you bypass the friction of writing manual connectors and maintaining JSON schemas for the LLM. Your engineering team can focus strictly on designing agent reasoning loops and enforcing business logic, while the proxy API handles the integration boilerplate.