Connect Kisi to AI Agents: Orchestrate Smart Facility Operations

You want to connect Kisi to an AI agent so your system can autonomously provision employee access, trigger emergency lockdowns, audit facility presence, and manage physical security hardware based on natural language or internal events. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom physical access integration from scratch.

Giving a Large Language Model (LLM) read and write access to your physical security infrastructure is a high-stakes engineering challenge. You either spend weeks reading API docs, dealing with hardware state synchronization, and normalizing complex pagination schemas, or you use an infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Kisi to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Kisi 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 Kisi, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex facility operations workflows. For a broader look at this architectural design pattern, read our research on architecting AI agents and the SaaS integration bottleneck.

Why a Unified Tool Layer Matters for Physical Security

Before writing integration code against physical access control systems (PACS), you must decide what layer your agent talks to. This choice determines the safety and reliability of your production environment.

Direct API tools - exposing raw Kisi endpoints straight to an LLM - force the model to memorize the vendor's internal data structures. The agent has to remember that Kisi requires specific assignee_type payloads, that physical hardware states (like locked_down vs unlocked) have distinct lifecycle rules, and that access rights are governed by a complex hierarchy of Organizations, Places, Groups, and Locks. Every vendor-specific quirk exposed to the prompt is a hallucination waiting to happen.

A unified tool layer collapses these complexities behind strict JSON schemas. Your agent interacts with highly constrained functions. This provides critical safety benefits for physical infrastructure:

1. Deterministic execution: Every tool has a strict JSON schema. If the LLM tries to hallucinate a non-existent lock state or invalid date format, the request fails local validation before it ever touches your facility hardware.
2. Smaller attack surface: The LLM chooses from a curated list of tools with explicit, clear descriptions. It does not invent REST payloads.
3. Abstracted authentication: The agent does not manage API keys or OAuth tokens. It simply requests an action, and the proxy layer securely routes it with the correct credentials.

The Engineering Reality of the Kisi API

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. Against complex physical security systems, this naive approach collapses.

Kisi's API introduces specific integration challenges tied directly to the realities of hardware and physical spaces. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

The Relational Hierarchy of Access Control

Kisi does not use a flat list of doors and users. The data model is strictly hierarchical. An Organization contains Places. Places contain Locks and Elevators. To give a user access to a specific door, you typically do not assign a user to a lock directly. Instead, you add a Member to a Group, and that Group has a GroupLink to a specific Lock at a specific Place.

If you expose the raw API to an LLM, the model must orchestrate five sequential relational lookups just to grant an intern access to the server room. The LLM will inevitably lose context, hallucinate an ID, or attempt an invalid direct assignment.

Asynchronous Hardware State

Unlike standard B2B SaaS where a 200 OK means a database row was updated, physical security APIs deal with asynchronous hardware. When you issue a kisi_locks_unlock command, the API validates the request and queues it for the local controller. The controller must receive the command, actuate the relay, and report back.

Agents must be designed to understand that hardware actions have latency. If an LLM expects instantaneous confirmation that a door physically opened, it will enter failure loops when offline controllers or tampered readers delay the response.

Complex Event Cursor Pagination

Auditing access logs in Kisi is incredibly powerful but requires a specific workflow. You cannot simply pass a page=2 parameter. To read logs, you must first construct an event_set - a server-side cursor that persists for about 24 hours. The API returns a cursor token, which you then use to paginate through the actual events. Standard LLM agents struggle heavily with multi-step cursor initiation patterns unless the tool definitions explicitly guide them through the stateful process.

Fetching and Binding Kisi Tools

Truto resolves these integration hurdles by providing a standardized /tools endpoint. Instead of manually writing and maintaining schemas for Kisi's hierarchical models, you fetch the definitions programmatically.

Truto normalizes the authentication, schema definitions, and request proxying.

A factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Kisi API returns an HTTP 429, Truto passes that exact error back to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your agent framework is strictly responsible for implementing retry and backoff logic.

Here is how you fetch the tools and bind them to an agent using the @trutohq/truto-langchainjs-toolset:

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
// 1. Initialize the Truto Tool Manager with your Integrated Account ID
// This ID points to the specific connected Kisi workspace
const trutoManager = new TrutoToolManager({
  integratedAccountId: process.env.KISI_INTEGRATED_ACCOUNT_ID,
  trutoApiKey: process.env.TRUTO_API_KEY,
});
 
async function initializeAgent() {
  // 2. Fetch the tools programmatically. 
  // These are fully formed, LangChain-compatible tool objects complete with JSON schemas.
  const kisiTools = await trutoManager.getTools();
 
  // 3. Initialize your LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Bind the tools to the model
  const agentWithTools = llm.bindTools(kisiTools);
 
  return { agentWithTools, kisiTools };
}

The architectural flow during execution looks like this:

sequenceDiagram
    participant LLM as Agent Framework
    participant TrutoProxy as Truto Proxy Layer
    participant KisiAPI as "Kisi API"

    LLM->>TrutoProxy: Execute `list_all_kisi_places` (JSON arguments)
    TrutoProxy->>TrutoProxy: Validate JSON Schema
    TrutoProxy->>KisiAPI: Inject Bearer Tokens & Execute REST GET
    KisiAPI-->>TrutoProxy: Return 200 OK (Places Data)
    TrutoProxy-->>LLM: Return Normalized JSON Observation

Essential Kisi Tools for AI Agents

Truto provides comprehensive coverage of the Kisi API, translating the physical security domain into agent-ready tools. Here are the highest-leverage operations for orchestrating facility workflows.

list_all_kisi_places

Every physical security workflow begins by identifying the place_id. This tool allows the agent to discover all facilities managed by the organization, including their geographic coordinates and time zones.

"Fetch all active places in our Kisi account to find the ID for the London office."

list_all_kisi_locks

Once a place is identified, the agent uses this tool to discover the hardware access points (doors, gates, turnstiles) associated with that location. It returns detailed state information, such as whether a door is currently offline, unlocked, or locked down.

"Get a list of all locks at the London office and tell me if any are currently reporting an offline status."

kisi_locks_unlock

This tool allows the agent to trigger a remote unlock for a specific door. It requires the lock_id. This is highly useful for autonomous delivery routing or verified remote access requests.

"Trigger an unlock for the 'Main Delivery Bay' lock (ID: 84729) to let the courier inside."

create_a_kisi_member

This tool provisions a new user in the Kisi directory. The agent must provide an email address. This is the first step in granting someone physical access to a building during automated HR onboarding.

"Create a new Kisi member profile for the new contractor, alice.smith@example.com."

create_a_kisi_group_lock

Instead of assigning users directly to hardware, access is managed through groups. This tool maps a specific Group to a specific Lock, essentially creating an access policy. Agents use this to dynamically adjust zone configurations.

"Bind the 'IT Staff' group to the 'Server Room A' lock so the team has physical access to the networking gear."

create_a_kisi_place_lock_down

This is a critical security tool. It triggers a facility-wide lockdown, immediately securing all access points within a specific place_id and revoking standard physical credential access until the lockdown is manually cancelled.

"Initiate an emergency lockdown for the entire San Francisco HQ facility immediately."

For the complete tool inventory and schema definitions, visit the Kisi integration page.

Building Multi-Step Workflows

AI agents excel when they chain multiple tools together. A real-world facility operation rarely involves a single API call.

When building these loops, your execution framework must handle rate limit errors gracefully. Because Truto passes HTTP 429s directly to your application with standard IETF headers, your agent executor should detect these statuses and pause execution before retrying.

Here is how an agent loops through a multi-step access request:

flowchart TD
    A["User Request:<br>'Lock down the NY office'"] --> B["Agent Reasoner"]
    B -->|Action| C["list_all_kisi_places"]
    C -->|Observation| D["Finds NY Office ID: 4432"]
    D --> B
    B -->|Action| E["create_a_kisi_place_lock_down<br>place_id: 4432"]
    E -->|Observation| F["204 No Content<br>(Lockdown active)"]
    F --> B
    B --> G["Final Output:<br>'NY Office secured'"]

Here is a simplified LangChain loop executing this pattern, demonstrating how to inspect tool errors for rate limits:

import { HumanMessage } from "@langchain/core/messages";
 
async function executeFacilityWorkflow(agent, tools, prompt) {
  const messages = [new HumanMessage(prompt)];
  
  while (true) {
    const response = await agent.invoke(messages);
    messages.push(response);
    
    if (response.tool_calls && response.tool_calls.length > 0) {
      for (const call of response.tool_calls) {
        const tool = tools.find(t => t.name === call.name);
        try {
            const observation = await tool.invoke(call.args);
            messages.push({ role: "tool", tool_call_id: call.id, content: observation });
        } catch (error) {
            // The caller is responsible for handling rate limits
            if (error.status === 429) {
                const resetTime = error.headers.get('ratelimit-reset');
                console.warn(`Rate limit hit. Must backoff until ${resetTime}`);
                // Implement your sleep/retry logic here
                throw new Error("Rate limited by upstream Kisi API");
            }
            messages.push({ role: "tool", tool_call_id: call.id, content: `Error: ${error.message}` });
        }
      }
    } else {
      // The agent has reached a final answer
      return response.content;
    }
  }
}

Workflows in Action

When you equip an agent with the right physical security tools, it can act as an autonomous facility manager. Here are concrete examples of workflows you can deploy immediately.

1. Automated Contractor Provisioning

When a short-term contractor is hired, HR needs them to have physical access to specific zones without requiring IT to manually configure badges and groups.

"A new HVAC contractor, dave@contractors.com, is starting today at the Chicago facility. Create a member profile for him and grant him access to the 'Maintenance Staff' group so he can enter the utility rooms."

Agent Execution Steps:

1. Calls list_all_kisi_places to resolve the ID for "Chicago facility".
2. Calls list_all_kisi_groups using the Chicago place ID to find the ID for the "Maintenance Staff" group.
3. Calls create_a_kisi_member to create the profile for dave@contractors.com, noting the new member_id.
4. Calls create_a_kisi_group_link (or equivalent access tool depending on exact Kisi configuration) to bind the new member to the Maintenance Staff group.

Result: The contractor is automatically provisioned, receives an invite email from Kisi, and the agent confirms the assignment is complete.

2. Emergency Security Response

In physical security, speed is critical. If a threat is detected by a parallel system (like a camera AI), the agent can execute immediate containment protocols.

"We have an unverified security alert on the 3rd floor of the Seattle office. Lock down the entire facility immediately and pull a list of all locks to confirm their status."

Agent Execution Steps:

1. Calls list_all_kisi_places to find the ID for the "Seattle office".
2. Calls create_a_kisi_place_lock_down using that ID, which revokes credential access and physically secures the perimeter.
3. Calls list_all_kisi_locks filtered by the place ID to retrieve the hardware status of every door, ensuring the agent can report back that the doors successfully transitioned to the locked_down state.

Result: The agent executes a zero-hesitation physical lockdown and verifies the hardware state, returning a sitrep to the security team.

3. Auditing Facility Presence

For compliance and safety, administrators frequently need to know who is inside a building on a given day.

"Pull the presence log for the Austin HQ for today. List the names of everyone who unlocked a door, and tell me the name of the last door they used."

Agent Execution Steps:

1. Calls list_all_kisi_places to find the ID for the "Austin HQ".
2. Calls list_all_kisi_presences passing the place ID and today's date.
3. Parses the returned array, mapping actor_name to last_unlocked_lock_name.

Result: The agent returns a clean, formatted manifest of building occupants and their last known access point without the security admin having to log into a dashboard and export a CSV.

Rethinking Facility Operations

Connecting AI agents to physical infrastructure systems like Kisi bridges the gap between software logic and the physical world. By utilizing Truto's /tools endpoint, you abstract away the complexities of hierarchical access models, cursor-based pagination, and hardware state synchronization.

Instead of burning engineering cycles maintaining physical security integrations, your team can focus on writing better agent instructions and building safer, more autonomous facility operations.