Connect Jrni to AI Agents: Automate Check-ins and Event Logistics

You want to connect Jrni to an AI agent so your system can independently handle event check-ins, resolve booking conflicts, search complex availability schedules, and block staff calendars based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to write custom API wrappers for Jrni's complex hierarchical resource structures.

Giving a Large Language Model (LLM) read and write access to your Jrni instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands the difference between Event Chains, Slots, and Services, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Jrni to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Jrni 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 Jrni, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex booking and logistics operations. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, you must decide what layer your agent talks to. This choice determines the reliability and safety of your production system.

Direct API tools (mapping one tool per raw Jrni endpoint) look convenient, but they push provider-specific quirks directly into the LLM's context window. The model has to remember that Jrni requires specific ElasticSearch DSL queries for searching bookings, that availability is nested deep inside parent-child company hierarchies, and that creating a booking requires fetching a dynamic schema first. Every one of those quirks is a hallucination waiting to happen.

Truto collapses these endpoints into a standardized tool layer. Your agent sees normalized operations like jrni_admin_bookings_search and update_a_jrni_check_in_by_id with strict JSON schemas. That gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from stable function names with deterministic inputs.
2. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments (like sending a string to an integer-only Service ID field) are rejected by the framework before they hit the Jrni API, failing fast.
3. Isolated authentication. Your agent never sees the Jrni API keys. It uses a short-lived Truto token to access the tool layer.

The Engineering Reality of Custom Jrni Connectors

Building AI agents is easy. Connecting them to external SaaS APIs safely is hard. Giving an LLM access to external scheduling data sounds simple in a prototype - you write a node fetch request and wrap it in a tool decorator. In production, this approach collapses, especially with an ecosystem as complex as Jrni.

If you decide to integrate Jrni yourself, you own the entire API lifecycle. Jrni introduces several highly specific integration challenges that break standard LLM assumptions.

The Parent-Child Company Hierarchy

Jrni is designed for enterprise scale, which means its data model relies heavily on parent-child company hierarchies to represent physical locations, franchises, or divisions. When an agent needs to retrieve a list of events or services, it cannot simply ask for "all events". It must know which company_id to query. If an organization has a parent location and 50 child locations, querying the parent does not always roll up the availability of the children automatically unless specified.

If you hand-code this integration, you have to write complex prompts teaching the LLM how to traverse jrni_companies_search and jrni_companies_list_children before it can even look up a bookable service.

The Elasticsearch DSL Trap

Most REST APIs use simple query parameters for filtering (e.g., ?status=active&date=2024-01-01). Jrni's advanced search endpoints - specifically jrni_admin_bookings_search and jrni_admin_clients_search - require an Elasticsearch Query DSL request body.

LLMs are notoriously bad at writing valid, optimized Elasticsearch DSL JSON from scratch without strict schema guidance. They will invent fields, mess up boolean queries (must vs should), or hallucinate nested aggregation syntax. Using Truto's proxy APIs, the schema for these tools is strictly defined, drastically reducing the chances of a hallucinated query crashing the request.

Event Chains vs. Single Events

In Jrni, recurring events are not just single records with a cron-like string. They are complex structures. You have an Event Group, which contains an Event Chain, which in turn contains Events and Slots, which finally hold Ticket Sets. If an AI agent needs to modify a booking for a specific Friday class in a 10-week course, it must successfully navigate this entire relational tree. Hand-coding the context required for an LLM to understand this graph takes hundreds of lines of prompt engineering.

AI-Ready Jrni Tools for Event Logistics

To interact with Jrni successfully, an AI agent needs a subset of high-leverage tools. Do not dump 100+ raw endpoints into the LLM context - that guarantees confusion. Instead, provide specific tools for specific tasks.

Here are the critical "hero tools" for Jrni check-in and logistics operations.

1. Admin Bookings Search

This tool allows the agent to find bookings across the organization using Elasticsearch Query DSL. It is vital for locating a guest's reservation when they arrive at the front desk.

Contextual usage notes: The agent must construct a valid Elasticsearch JSON body. It will return the booking ID, datetime, client name, service name, and status.

"Find the booking ID for John Doe, who has a reservation for the 'Advanced Yoga' service happening sometime today at the downtown branch."

2. Update Check-In by ID

This is the core operational tool for event logistics. It marks a specific guest as checked in for an appointment or event based on their unique check-in code.

Contextual usage notes: Requires the company_id and the specific check-in id. This operates on the proxy API level, meaning Truto handles the path parameter formatting automatically.

"The guest provided check-in code 84729. Mark them as checked in for their appointment and confirm their status."

3. List All Admin Times

Before an agent can reschedule a guest or create a new booking, it must query availability. This tool lists available booking start times for a company on a particular day, including durations and prices.

Contextual usage notes: Requires company_id, service_id, and a start_date. The agent must use this before attempting to create a booking to avoid guessing available slots.

"Check the availability for the 'Consultation' service at the main office for tomorrow. Return the available start times."

4. Create Admin Booking

This tool creates a new booking in Jrni for a service or event appointment.

Contextual usage notes: This tool requires a valid company_id, service_id, client_id, and a selected datetime from the availability check. If the agent does not have a client_id, it must create or search for the client first.

"Create a new booking for client ID 4592 for the Consultation service tomorrow at 10:00 AM."

5. Admin People Create Block

This tool allows the agent to block out a time slot for a bookable person (staff member). This is critical for autonomous scheduling assistants managing staff capacity.

Contextual usage notes: Requires company_id, people_id, start_time, and end_time. Use this when a staff member reports they are sick or need an ad-hoc break.

"Dr. Smith just called in sick for the afternoon. Block out their calendar from 1:00 PM to 5:00 PM today at the Northside clinic."

6. Admin Booking Attendees Add Attendees

For group events, this tool adds an attendee to an existing booking or event space.

Contextual usage notes: Requires company_id, space_id, and the attendee type.

"Add Sarah Jenkins to the confirmed attendee list for the morning workshop session (Space ID 9928)."

To view the complete inventory of available Jrni tools and their exact JSON schemas, visit the Jrni integration page.

Workflows in Action

When you combine these tools inside an agent framework, you move beyond simple API wrappers into autonomous revenue operations. Here are two real-world sequences.

Scenario 1: Autonomous Event Check-In and Conflict Resolution

An attendee arrives at an event but is running late and missed their original time slot. They text the AI agent asking to be checked in to the next available session.

"I'm at the venue for the VIP Tour but I missed my 10 AM slot. Can you check me in for the 11 AM if there's space? My email is john@example.com."

Step-by-step execution:

1. jrni_admin_clients_get_by_email: The agent looks up the client ID using john@example.com.
2. jrni_admin_bookings_search: The agent finds the original 10 AM booking using the client ID.
3. jrni_admin_bookings_cancel: The agent cancels the missed 10 AM booking to free up capacity.
4. list_all_jrni_admin_times: The agent queries availability for the VIP Tour service starting at 11 AM.
5. create_a_jrni_admin_booking: The agent books John into the 11 AM slot.
6. update_a_jrni_check_in_by_id: Since John is already at the venue, the agent immediately marks him as checked in for the new 11 AM slot.

Outcome: The agent autonomously handles cancellation, rebooking, and check-in without front-desk intervention.

Scenario 2: Staff Capacity Management

A manager informs the internal AI assistant that a specific location needs to close early due to a facility issue.

"The HVAC is broken at the Eastside branch. We need to close at 2 PM today. Block out the remaining schedules for all staff there."

Step-by-step execution:

1. jrni_companies_search: The agent searches for the "Eastside branch" to retrieve its company_id.
2. list_all_jrni_admin_people: The agent retrieves the list of all bookable staff at that specific company_id.
3. jrni_admin_people_create_block: The agent loops through the staff list, calling this tool for each person to block their schedule from 14:00 to the end of the day.

Outcome: The agent protects the company from receiving invalid bookings by instantly adjusting capacity across the entire location.

Building Multi-Step Workflows

To build these workflows, you need to load the Truto tools into your agent framework. Truto provides the truto-langchainjs-toolset for Node.js developers, which handles the orchestration of calling the /tools endpoint and converting the JSON schemas into runnable functions.

sequenceDiagram
    participant App as Your App (Agent)
    participant Truto as Truto API
    participant Jrni as Jrni Upstream API
    
    App->>Truto: GET /integrated-account/<id>/tools
    Truto-->>App: Return normalized tool schemas
    App->>App: llm.bindTools(tools)
    App->>App: Agent decides to search bookings
    App->>Truto: Execute tool: jrni_admin_bookings_search
    Truto->>Jrni: Forward Proxy Request (Auth handled)
    Jrni-->>Truto: Return Search Results
    Truto-->>App: Return JSON payload
    App->>App: LLM analyzes data & plans next step

Handling Rate Limits with Truto Tools

When working with autonomous agents, rate limiting is your biggest operational threat. An LLM can loop through a list of 50 staff members and execute 50 jrni_admin_people_create_block requests in two seconds. This will instantly trigger an HTTP 429 Too Many Requests response from the upstream Jrni API.

Factual note on Truto's rate limiting architecture: Truto does not automatically retry, throttle, or apply backoff on rate limit errors. When the upstream API (Jrni) returns an HTTP 429, Truto passes that exact error down to the caller.

However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (your agent framework or application code) is strictly responsible for inspecting these headers and implementing retry/backoff logic. Do not assume the infrastructure will absorb the 429.

Here is how you bind tools to a LangChain agent and implement a safety wrapper for rate limits.

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 runJrniAgent() {
  // 1. Initialize the Truto Tool Manager
  // Requires TRUTO_API_KEY environment variable
  const toolManager = new TrutoToolManager();
  
  // 2. Fetch Jrni proxy tools for a specific integrated account
  const tools = await toolManager.getTools(
    "<jrni-integrated-account-id>",
    { methods: ["list", "get", "create", "update", "custom"] }
  );
 
  // 3. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Create the prompt instruction
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", `You are a logistics operations manager. 
      Use the provided Jrni tools to manage bookings and staff blocks.
      Always retrieve the company_id before acting on resources. 
      If you receive a 429 Too Many Requests error, STOP and wait before retrying.`],
    ["placeholder", "{chat_history}"],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 5. Bind tools to the agent
  const agent = createToolCallingAgent({ llm, tools, prompt });
  
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 10, // Prevent runaway loops
  });
 
  console.log("Starting Jrni logistics task...");
  
  // Wrap execution to gracefully catch unhandled 429s thrown by the tools
  try {
      const result = await agentExecutor.invoke({
        input: "Dr. Smith called in sick. Block out their calendar from 1:00 PM to 5:00 PM today at the Northside clinic.",
      });
      console.log(result.output);
  } catch (error: any) {
      if (error.response?.status === 429) {
          const resetTime = error.response.headers.get('ratelimit-reset');
          console.error(`Rate limited by Jrni. Agent halted. Try again at ${resetTime}`);
          // Implement your queue/backoff logic here
      } else {
          console.error("Agent execution failed:", error);
      }
  }
}
 
runJrniAgent();

Because Truto dynamically pulls tool definitions via the /tools endpoint, any updates you make to the tool descriptions or JSON schemas inside the Truto UI instantly propagate to your agent. If the LLM is struggling to format the Elasticsearch DSL query, you can literally log into Truto, update the description for jrni_admin_bookings_search to include an example JSON payload, and the LLM will use it on the next run.

Moving from Prototypes to Production Logistics

Integrating AI agents with complex scheduling systems like Jrni requires absolute precision. You cannot afford an agent hallucinating appointment times or corrupting the parent-child company hierarchy.

By routing your LLM through Truto's proxy APIs, you transform a massive, unpredictable REST architecture into a bounded, schema-validated toolset. You enforce strict boundaries on what the agent can touch, you abstract away authentication complexity, and you ensure that when the agent hits a rate limit, your application can catch it predictably using standardized IETF headers.

Stop writing fragile prompt engineering to teach models how Jrni's API works. Give them concrete, validated tools instead.