Connect SAP HANA to AI Agents: Orchestrate SCIM lifecycles

You want to connect SAP HANA to an AI agent so your IT system can autonomously provision users, orchestrate SCIM group memberships, execute role transitions, and run compliance audits based on natural language triggers. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build a custom SCIM 2.0 integration from scratch.

Giving a Large Language Model (LLM) read and write access to SAP Cloud Identity Services is an engineering minefield. You either spend months building, hosting, and maintaining a custom connector that conforms strictly to SAP's specific flavor of SCIM, or you use a managed infrastructure layer that handles the authentication and schema boilerplate for you. If your team uses ChatGPT, check out our guide on connecting SAP HANA to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting SAP HANA to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them directly to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for SAP HANA, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex identity operations. This approach is completely framework-agnostic and relies on standard function calling capabilities. For a deeper look at the architecture behind this approach, refer to our research on Architecting AI Agents: LangGraph, LangChain, and the SaaS Integration Bottleneck.

The Engineering Reality of the SAP HANA API

Building an AI agent is largely an exercise in prompting, context management, and workflow routing. Giving that agent reliable access to external infrastructure APIs is where projects stall. If you decide to build a custom SAP HANA connector, you own the entire API lifecycle.

SAP HANA's identity and user management relies heavily on SAP Cloud Identity Services, which implements the SCIM 2.0 (System for Cross-domain Identity Management) specification. While standardizing on SCIM sounds great on paper, it introduces several specific integration challenges that break standard REST assumptions and consistently cause LLMs to hallucinate.

The SCIM 2.0 JSON Patch Trap

SCIM 2.0 is heavily nested. When an agent wants to update a user's department, a standard LLM will intuitively attempt to send a flat payload like {"department": "Engineering"}.

SAP HANA will reject this immediately. To execute a partial update, the API requires a strictly formatted PatchOp array defining the exact operation, path, and value. The LLM has to perfectly generate a payload like this:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
      "value": "Engineering"
    }
  ]
}

Expecting a generalized LLM to perfectly recall and construct these URI paths for every operation is a hallucination waiting to happen. If you expose the raw API to the agent, you will spend your sprints writing defensive integration code to catch malformed PatchOp arrays.

SAP-Specific Extension Attributes

Beyond the core SCIM schemas, SAP HANA uses heavily customized extension attributes. To send an activation email upon user creation, you must append urn:ietf:params:scim:schemas:extension:sap:2.0:User to your schemas array and nest a sendMail boolean flag deep inside the payload.

Directly exposing these vendor-specific schema URIs to an LLM drastically increases the prompt size and pollutes the context window with integration trivia. Your agent should be focused on the business logic of onboarding an employee, not memorizing SAP's internal URN structure.

Strict Rate Limiting Realities

Enterprise IT directories enforce strict rate limits to prevent denial-of-service scenarios. When an agent loops through a directory to audit 500 users, it will inevitably hit a rate limit.

It is a factual reality that Truto does not retry, throttle, or apply backoff on rate limit errors automatically. When the SAP HANA upstream 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 headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) conforming to the IETF specification. This makes it significantly easier to build a single, standardized backoff mechanism in your agent loop without needing to parse SAP's specific rate limit header formats.

Hero Tools for SAP HANA Identity Operations

A unified tool layer collapses these API quirks behind a clean schema. Your agent sees create_a_sap_hana_user with a strict JSON schema, not the raw /service/scim/Users endpoint. Invalid arguments are rejected locally before they even reach the SAP network.

Here are the most highly leveraged tools available for SAP HANA via Truto.

List All SAP HANA Users

This tool retrieves users from SAP Cloud Identity Services. It supports SCIM filter expressions, allowing your agent to search for specific users without downloading the entire directory.

Usage Note: The agent can use this tool to discover user IDs, check if a username is already taken, or find users modified after a specific date. It natively understands SCIM filter queries (e.g., userName eq "jdoe").

"Find the user ID for John Doe in SAP HANA. If there are multiple, return the one where the active status is true."

Get Single SAP HANA User by ID

Retrieves a complete SCIM user resource, exposing phone numbers, group memberships, and SAP-specific enterprise attributes like employeeNumber and department.

Usage Note: This is the critical first step before executing a full replacement update. Because full updates clear omitted attributes, the agent must read the user state first.

"Fetch the full profile for user ID 8f7e6d5c-4b3a-2109-8765-43210fedcba9 so we can audit their current group memberships and manager assignment."

Create a SAP HANA User

Provisions a new identity in SAP Cloud Identity Services. It handles the baseline SCIM schemas and allows the agent to define enterprise and SAP extension attributes seamlessly.

Usage Note: Instruct the agent to set the sendMail attribute to true if the newly provisioned user needs an automated activation email from SAP.

"Provision a new SAP HANA account for Sarah Connor. Her email is sarah@example.com, set her userType to 'Contractor', and trigger the activation email."

SAP HANA Users Partial Update

Updates selected attributes of a user without resending the entire record. This translates flat agent instructions into the complex SCIM PatchOp structure.

Usage Note: This is the safest way to modify user status. Instead of risking a full payload overwrite, the agent can issue a targeted patch command to deactivate a departing employee.

"Deactivate the SAP HANA user with ID 12345-abcde immediately by setting their active status to false. Do not modify any other attributes."

List All SAP HANA Groups

Retrieves the directory of groups, returning display names, full member lists, and the SAP group extensions (technical name, description, type).

Usage Note: Useful for mapping organizational roles to technical identifiers before assigning a new hire to a specific access tier.

"List all SAP HANA groups that contain the word 'Admin' in their display name and return their group IDs."

SAP HANA Groups Partial Update

Adds or removes members from a group or changes group attributes via SCIM Patch operations.

Usage Note: The agent provides the Group ID and the exact operation (e.g., op: "add", path: "members", value: [{"value": "<user_id>"}]). The tool handles translating this into the strict SCIM specification.

"Add user ID 8f7e6d5c to the 'Finance-Admins' group. Make sure to use the partial update tool to avoid dropping existing members."

To view the complete schema definitions and the full inventory of SAP HANA tools, visit the SAP HANA Integration Page.

Workflows in Action

When you bind these tools to a reasoning engine like GPT-4o or Claude 3.5 Sonnet, you can execute complex orchestration scenarios simply by defining the goal in natural language.

Scenario 1: Autonomous Security Offboarding

When an employee leaves under sensitive circumstances, IT security needs to revoke access across all systems instantly and flawlessly.

"Terminate access for alice.smith@company.com in SAP HANA immediately. Revoke her active status, identify any 'Admin' groups she belongs to, and remove her from them."

Execution Steps:

1. The agent calls list_all_sap_hana_users with the filter userName eq "alice.smith@company.com" to retrieve her user UUID.
2. The agent calls sap_hana_users_partial_update targeting her UUID, issuing a PatchOp to replace active with false.
3. The agent calls get_single_sap_hana_user_by_id to inspect her current groups array.
4. For any group matching the 'Admin' criteria, the agent extracts the Group ID.
5. The agent loops through the identified groups, calling sap_hana_groups_partial_update with an op: "remove" payload specifically targeting her user UUID.

Result: The employee is fully disabled and stripped of privileged access within seconds, generating an auditable trail of actions without manual intervention.

Scenario 2: Contractor to Full-Time Conversion

HR processes a status change in the HRIS. The AI agent listens to this webhook and updates the identity provider accordingly.

"Update the SAP profile for bob.jones. He is converting from Contractor to Full-Time. Update his userType, change his department to 'Engineering', and add him to the 'Engineering-General' group. Group ID is 9999-8888."

Execution Steps:

1. The agent calls list_all_sap_hana_users to find Bob's user UUID.
2. The agent calls sap_hana_users_partial_update, sending two operations: replacing userType with 'Full-Time' and replacing the enterprise department attribute with 'Engineering'.
3. The agent calls sap_hana_groups_partial_update on Group ID 9999-8888, passing an op: "add" command with Bob's UUID in the members array.

Result: The IT team avoids a manual helpdesk ticket. The user transitions seamlessly into their new role with the correct system metadata and group permissions applied instantly.

Building Multi-Step Workflows

To make this work in production, you need a robust agent loop. Truto's /tools endpoint dynamically serves OpenAPI-compliant tool schemas that plug directly into frameworks like LangChain, LangGraph, or the Vercel AI SDK.

The code block below demonstrates how to fetch the SAP HANA tools using the Truto SDK, bind them to an LLM, and execute a workflow with explicit handling for the IETF rate limit headers Truto provides.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runSAPHanaAgent() {
  // 1. Initialize the Truto Tool Manager with your Integrated Account ID
  const trutoManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: "sap-hana-account-id-123",
  });
 
  // 2. Fetch the SAP HANA tools directly from Truto's /tools endpoint
  const sapTools = await trutoManager.getTools();
 
  // 3. Initialize your LLM and bind the tools
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  }).bindTools(sapTools);
 
  // 4. Define the Agent Prompt
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an elite IT Security Agent managing SAP HANA identities. You follow SCIM 2.0 protocols strictly."],
    ["human", "{input}"],
    new MessagesPlaceholder("agent_scratchpad"),
  ]);
 
  // 5. Create the Agent
  const agent = await createOpenAIToolsAgent({
    llm,
    tools: sapTools,
    prompt,
  });
 
  const agentExecutor = new AgentExecutor({
    agent,
    tools: sapTools,
    maxIterations: 10,
  });
 
  // 6. Execute the workflow inside a retry wrapper to handle 429 Rate Limits
  const executeWithRateLimitHandling = async (input: string) => {
    try {
        console.log("Executing agent workflow...");
        const result = await agentExecutor.invoke({ input });
        console.log("Result:", result.output);
    } catch (error) {
        // Truto passes 429s directly to you. You must handle backoff.
        if (error.status === 429) {
            // Truto normalizes these to the IETF specification
            const retryAfter = error.headers['ratelimit-reset'];
            const resetSeconds = retryAfter ? parseInt(retryAfter, 10) : 60;
            console.warn(`Rate limit hit! Backing off for ${resetSeconds} seconds...`);
            
            // Implement your preferred backoff logic here (e.g., setTimeout)
            await new Promise(res => setTimeout(res, resetSeconds * 1000));
            
            // Retry execution
            return executeWithRateLimitHandling(input);
        }
        throw error;
    }
  };
 
  await executeWithRateLimitHandling(
    "Deactivate user ID 1234-abcd and remove them from the 'System Admins' group."
  );
}
 
runSAPHanaAgent();

The Anatomy of the Integration Loop

The true power of this architecture is the abstraction layer. Let's look at how the data flows when your agent executes a complex instruction.

sequenceDiagram
    participant App as "Your App (LangChain)"
    participant Truto as "Truto API"
    participant SAP as "SAP HANA"
    
    Note over App: Agent decides to partial update a user
    App->>Truto: Call sap_hana_users_partial_update (Clean JSON)
    Truto->>SAP: Execute PATCH /service/scim/Users/{id}<br>(Formatted PatchOp)
    
    alt Rate Limit Reached
        SAP-->>Truto: HTTP 429 Too Many Requests
        Truto-->>App: HTTP 429 (ratelimit-reset header)
        Note over App: App reads header, waits 10s, Retries
        App->>Truto: Call sap_hana_users_partial_update
    end
    
    SAP-->>Truto: 200 OK (Complex SCIM JSON)
    Truto-->>App: Normalized success response
    Note over App: Agent continues reasoning

By separating the tool execution from the underlying API complexity, the LLM stays focused on orchestration. Truto acts as the proxy layer, managing authentication signatures, parameter processing, and passing unified rate limit headers back so your code can execute a deterministic backoff strategy.

Moving From Integration Code to Agent Logic

Building autonomous AI workflows against enterprise infrastructure like SAP HANA requires absolute predictability. You cannot rely on an LLM to consistently generate flawless SCIM 2.0 PatchOp payloads or remember the exact URN strings for custom SAP extension attributes. Every time you ask a model to write raw API requests, you increase the attack surface for hallucinations.

By routing your agent through Truto's /tools endpoint, you collapse hundreds of pages of SAP documentation into a handful of strict, deterministic tools. Your engineering team stops writing defensive API wrapper code and starts building more sophisticated agent reasoning loops.