Connect Lumos to AI Agents: Orchestrate SaaS tasks and vendor data

You want to connect Lumos to an AI agent so your internal systems can independently execute IT helpdesk requests, run access review campaigns, approve app provisioning, and audit vendor agreements based on your company's governance policies. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually build dozens of custom REST wrappers to handle complex identity and access management workflows.

Giving a Large Language Model (LLM) read and write access to your Lumos instance is a significant engineering challenge. You either spend sprints building, authenticating, and maintaining a custom connector that understands the nuanced difference between the Lumos AppStore and domain apps, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Lumos to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Lumos 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 Lumos, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex IT 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.

The Engineering Reality of Custom Lumos Connectors

Building AI agents is easy. Connecting them to external SaaS APIs - specifically identity governance and administration (IGA) platforms - is exceptionally hard. Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request, wrap it in an @tool decorator, and call it a day. In production, this approach collapses entirely, especially with a platform as complex as Lumos.

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

The AppStore vs. Domain App Dichotomy

Unlike standard CRMs where a "Company" is a globally understood entity, Lumos splits applications into two distinct paradigms: the global Lumos AppStore catalog and your company's localized Domain Apps.

When an AI agent receives a prompt like "Request access to Figma," it cannot simply POST a request to a generic app endpoint. It must first query the AppStore using list_all_lumos_appstore_apps to find the catalog definition, resolve the app_class_id or instance_id, and determine if the app supports multiple permission selections. If the agent queries the domain apps instead of the AppStore catalog, it will fail to find requestable apps that haven't been provisioned yet. Hard-coding this logic into an LLM system prompt is brittle and consumes valuable context window space.

Task Resolution State Machines

IT approval workflows in Lumos are not simple boolean flags. They operate as complex state machines represented by Tasks.

When a manager asks an AI agent to "approve pending access requests for the engineering team," the agent must fetch tasks, but standard GET requests do not reveal the dynamic actions available. The agent must query get_single_lumos_task_by_id with a specific query parameter (expand=actions) to hydrate the nested action fields. Only then does it receive the specific dynamic action ID required to transition the task using the lumos_tasks_perform_action endpoint. Custom connectors typically fail here because the LLM tries to guess the approval schema rather than navigating the precise multi-step hydration required by the vendor.

Asynchronous Access Review Campaigns

Compliance automation requires triggering Access Reviews for SOC 2 or SOX compliance. However, creating a campaign via create_a_lumos_access_review is strictly asynchronous.

When an agent creates a review with a defined scope of apps, the campaign does not start immediately. It enters an IN_PREPARATION state while Lumos takes snapshots of accounts and entitlements across all connected integrations. It transitions to IN_PROGRESS automatically only after snapshotting completes. If your agent is built on synchronous assumptions, it will attempt to assign reviewers immediately and crash when the campaign is still locked in preparation.

How Truto Standardizes AI Tools

Truto solves this by providing a unified proxy layer. Every integration on Truto is essentially a comprehensive JSON object that represents how the underlying product's API behaves. Integrations use Resources (like apps, tasks, or reviews) and Methods (List, Get, Create, Update, Delete) to map any external API into a standardized REST-based interface.

Instead of manually wrapping the Lumos API, you connect an account and call the GET /integrated-account/<id>/tools endpoint on the Truto API. This returns a JSON array of fully documented, schema-validated Proxy APIs ready to be bound to your agent framework.

Factual Note on Rate Limits

When operating agents at scale - such as processing hundreds of vendor agreements - rate limits are a mathematical certainty. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Lumos API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller.

Truto normalizes upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller - your agent loop - is strictly responsible for implementing retry logic and backoff using these headers.

Hero Tools for Lumos AI Agents

To build a highly capable IT agent, you need to expose the right operations. Instead of overwhelming the LLM with 80+ endpoints, you should provide high-leverage tools that orchestrate core governance functions. Here are the core tools you can fetch from Truto to build a Lumos agent.

List AppStore Apps

The list_all_lumos_appstore_apps tool allows the agent to search the catalog of requestable applications. It returns essential identifiers (app_class_id, instance_id) and visibility status. This is the required first step before initiating any access request.

"Find the AppStore record for 'GitHub' and check if it allows multiple permission selections. Return its instance ID so I can request access."

Create Access Request

The create_a_lumos_appstore_access_request tool initiates an actual request for a specific application or permission level. The agent uses this to automate onboarding or just-in-time (JIT) access based on conversational prompts.

"Submit an access request for User ID 88392 to the AWS Production app instance. Include the business justification: 'Required for Q3 database migration weekend project'."

Fetch Lumos Task

The get_single_lumos_task_by_id tool retrieves the full context of a pending IT task (like an approval or manual provisioning step). By passing expand=actions, the agent retrieves the exact action payload required to complete the task.

"Retrieve task ID TASK-9923. Expand the available actions and tell me if 'approve' is currently an option for this access request."

Perform Task Action

The lumos_tasks_perform_action tool executes a state transition on a given task. This is the write-operation counterpart to fetching a task, allowing the agent to programmatically approve, deny, or escalate requests without human intervention in the Lumos UI.

"Execute the 'approve' action on task ID TASK-9923. The security checks have passed in our internal monitoring tool."

Create Access Review

The create_a_lumos_access_review tool initializes an asynchronous access review campaign. The agent can define the scope, target launch date, and recurrence configuration for continuous compliance monitoring.

"Create a new quarterly access review campaign targeting the 'Salesforce' and 'Snowflake' apps. Set the deadline for two weeks from today."

List Vendor Agreements

The list_all_lumos_vendor_agreements tool extracts contract and pricing data. Agents use this to monitor renewals, audit projected annualized costs, and cross-reference SaaS usage against active vendor contracts.

"List all vendor agreements that have a renewal stage approaching in the next 90 days. Summarize their total projected annualized cost."

To see the complete inventory of available proxy tools, query parameters, and detailed JSON schemas, visit the Lumos integration page on Truto.

Workflows in Action

When you equip an LLM with these tools, you move beyond simple chat interfaces into autonomous IT orchestration. Here are two concrete examples of how an agent sequences these tools to solve real engineering problems.

Workflow 1: Automated Just-In-Time Access Provisioning

Engineers frequently request temporary access to production systems. A manual IT ticket takes hours to resolve. An AI agent can handle the end-to-end approval and provisioning flow in seconds based on Slack commands.

"I am an on-call engineer handling an incident. I need temporary access to the Datadog production environment for the next 4 hours to view APM traces."

1. The agent calls list_all_lumos_appstore_apps with exact_match=Datadog to retrieve the instance_id.
2. The agent calls create_a_lumos_appstore_access_request using the engineer's user ID and the fetched app instance, passing the incident context as notes.
3. The agent receives the generated access_request_id and polls list_all_lumos_tasks filtering by that request ID to find the pending approval task.
4. Evaluating that the user is currently on the PagerDuty schedule (via another tool), the agent calls lumos_tasks_perform_action to automatically approve the Lumos task.

The user immediately receives notification that the workflow has completed, and Lumos provisions the account via its downstream IdP connection.

Workflow 2: Vendor Risk and Renewal Auditing

Finance and compliance teams spend weeks manually correlating SaaS spend against actual usage and vendor contracts. An agent can automate this data aggregation.

"Generate a report of all vendor agreements renewing in Q4. For each, tell me the projected annual cost and verify if we have an active access review campaign running for that vendor's application."

1. The agent calls list_all_lumos_vendor_agreements and parses the end_date and renewal_stage fields to isolate Q4 renewals.
2. For each identified vendor (e.g., "Mixpanel"), the agent stores the projected_annualized_cost.
3. The agent then calls list_all_lumos_access_reviews to see if a review exists with a matching application scope.
4. If an app lacks a review, the agent calls create_a_lumos_access_review specifically targeting that app to ensure compliance prior to renewal.

The user gets a formatted markdown table summarizing costs, renewal dates, and confirmation that compliance audits have been initiated for all upcoming renewals.

Building Multi-Step Workflows

To implement this in code, you need a framework-agnostic approach. Truto's proxy architecture means these tools work identically whether you are using LangChain, Vercel AI SDK, or custom control loops.

The code below demonstrates how to fetch the tools dynamically, bind them to an OpenAI model using LangChain, and implement the critical rate limit handling required when dealing with enterprise SaaS APIs.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function buildLumosAgent(integratedAccountId: string) {
  // 1. Initialize the Truto Tool Manager with your API key
  const toolManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
  });
 
  // 2. Fetch all configured tools for the Lumos integration
  const tools = await toolManager.getTools(integratedAccountId);
 
  // 3. Initialize the LLM and bind the dynamically fetched tools
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  }).bindTools(tools);
 
  // 4. Define the system prompt with strict IT governance instructions
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an elite IT orchestration agent managing a Lumos environment. You must verify app visibility before submitting access requests. If a tool call fails due to a rate limit, you must observe the ratelimit-reset instruction."],
    ["placeholder", "{chat_history}"],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 5. Create the execution agent
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
 
  return new AgentExecutor({
    agent,
    tools,
    max_tools: tools,
    maxIterations: 10,
  });
}
 
// --- Custom Tool Execution Loop for Rate Limit Handling ---
// Truto passes 429s directly to the caller. You must handle backoff.
async function executeWithRateLimitHandling(executor: AgentExecutor, input: string) {
  const maxRetries = 3;
  let attempts = 0;
 
  while (attempts < maxRetries) {
    try {
      const result = await executor.invoke({ input });
      return result;
    } catch (error: any) {
      if (error.response && error.response.status === 429) {
        attempts++;
        // Extract the normalized IETF ratelimit-reset header provided by Truto
        const resetTimeSecs = parseInt(error.response.headers.get('ratelimit-reset') || '5', 10);
        console.warn(`[Rate Limit Hit] Waiting ${resetTimeSecs} seconds before retry... (Attempt ${attempts})`);
        await new Promise(resolve => setTimeout(resolve, resetTimeSecs * 1000));
      } else {
        throw error; // Re-throw non-429 errors
      }
    }
  }
  throw new Error("Max retries exceeded for rate limit backoff.");
}
 
// Example Invocation
const agentId = "lumos_acct_88f92a"; 
const executor = await buildLumosAgent(agentId);
const response = await executeWithRateLimitHandling(
    executor, 
    "Find the AppStore record for Slack, get its instance ID, and submit an access request for User 1044."
);
console.log(response.output);

The Execution Flow

When this script runs, the interaction between your agent, Truto, and the upstream Lumos API follows a strict proxy pattern. The diagram below illustrates how rate limits are surfaced to the caller, ensuring your application remains in control of its execution state without relying on hidden internal queues.

sequenceDiagram
    participant Agent as AI Agent
    participant Truto as Truto Unified API
    participant Lumos as Lumos API

    Agent->>Truto: GET /integrated-account/{id}/tools
    Truto-->>Agent: Returns JSON schema array
    Agent->>Agent: Bind tools to LLM
    Agent->>Truto: Execute tool: list_all_lumos_appstore_apps
    Truto->>Lumos: Proxy Request
    Lumos-->>Truto: 429 Too Many Requests
    Truto-->>Agent: HTTP 429 + ratelimit-reset header
    Agent->>Agent: Wait for reset window
    Agent->>Truto: Retry execution
    Truto->>Lumos: Proxy Request
    Lumos-->>Truto: 200 OK
    Truto-->>Agent: Normalized App Data

By fetching tools dynamically from the Truto API, your agent inherits any schema updates automatically. If Lumos adds a new required field to their access requests tomorrow, the Truto platform updates the integration definition, the /tools endpoint serves the new JSON schema, and your LLM adapts its tool calling format on the next request - requiring zero deployments on your end.

Moving from Chat to Autonomous Governance

Integrating Lumos into an AI agent transforms IT operations from a manual ticketing bottleneck into a reactive, policy-driven automation layer. Instead of waiting for an IT admin to manually expand tasks and click approval buttons in a dashboard, your agent handles the entire state machine programmatically.

By leveraging Truto to abstract the API authentication, pagination, and schema mapping, your engineering team can focus entirely on writing the business logic and agentic prompts. The integration infrastructure handles the rest.