Connect Leap to AI Agents: Coordinate Appointments and Field Service

You want to connect Leap to an AI agent so your system can autonomously schedule appointments, track job progress, coordinate field service operations, and manage customer records. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build a custom Leap integration from scratch.

Building an autonomous field service agent requires giving a Large Language Model (LLM) read and write access to your Leap instance. This is inherently risky. Standard LLMs are trained to expect simple, flat JSON structures, but FSM (Field Service Management) APIs are notoriously complex. If your team uses ChatGPT, check out our guide on connecting Leap to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Leap to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch pre-formatted tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Leap, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex field service operations. 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 the Leap API

Giving an LLM access to external field data sounds simple in a prototype. You write a standard HTTP fetch wrapper and hand it to the model. In production, against an API like Leap, this approach collapses. Leap has specific architectural quirks that will cause your agent to hallucinate payloads or destroy customer data if left unchecked.

Destructive Updates by Default

The most dangerous quirk of the Leap API is its update behavior. For core entities like Appointments and Customers, Leap uses complete replacement rather than partial patching. If you omit a field in your update payload, Leap assumes you want to clear it.

LLMs are notoriously lazy. If you ask an agent to "Update the appointment time to 2 PM," a raw LLM will likely generate a payload containing only the id and the title or time. If you send that raw payload to Leap's update_a_leap_appointment_by_id endpoint, Leap will wipe out the location, the assigned technicians, and the status. To fix this, your agent must be strictly instructed to execute a GET request first, merge the new data into the full payload in memory, and then send the complete object back.

Relational Data via Includes

Leap does not heavily nest related data in its standard list responses. Instead, it utilizes an includes [] array pattern. When an agent queries a job, the core job details are returned, but related customer data, trades, or divisions must be requested via specific query parameters. An LLM interacting with raw endpoints will often hallucinate nested fields that do not exist, or it will fail to append the correct includes [] parameters, resulting in repeated, failed tool calls as it searches for missing data.

Multipart Form Requirements

Field service requires heavy file handling - contracts, photos, measurements, and work orders. Leap's API requires multipart/form-data for creating these records (e.g., create_a_leap_measurement). LLMs natively output JSON. Translating an LLM's JSON tool call into a valid multipart payload with boundary headers requires a dedicated proxy layer. Hardcoding this translation into your agent framework bloats your context window and introduces brittle parsing logic.

Hero Tools for Leap

Truto's Proxy API layer handles data normalization, authentication, and pagination, exposing these endpoints as standardized LLM tools via the /integrated-account/<id>/tools endpoint. Here are the core tools your agent needs to orchestrate field service.

1. list_all_leap_jobs

This tool retrieves a paginated list of jobs. Truto handles the cursor pagination natively (mapping Leap's default 10-item limit to a standardized page and limit up to 100). The agent can use the includes [] parameter to pull related data without hallucinating nested structures.

"Find all open roofing jobs assigned to customer ID 4591. Ensure you include the related customer and division data in the response."

2. update_a_leap_job_by_id

Updates an existing job. Because Leap replaces the job's fields entirely, the agent must pass the complete payload. The strict JSON schema provided by Truto enforces required fields like customer_id, description, and trades, preventing the LLM from executing a destructive partial update.

"Update job ID 8821 to reflect the new scope of work. First, fetch the current job details, then update the description to 'Roof replacement and gutter repair', and submit the complete payload back to the update tool."

3. create_a_leap_appointment

Creates a new appointment for a job. The tool schema automatically handles Leap's requirement for multipart/form-data under the hood, allowing the LLM to simply output standard JSON arguments (like title, start_time, and location).

"Schedule a new site inspection appointment for tomorrow at 9 AM for job ID 332. Title the appointment 'Initial Site Survey'."

4. list_all_leap_contacts

Provides a read-only, paginated listing of the company's contacts. Because contacts in Leap are shared across jobs, this tool is critical for agentic inbound routing. When an AI agent receives an SMS or call, it can use this tool to identify the customer before querying specific jobs.

"Look up the phone number +1-555-0198 in the contacts directory to find the associated customer name and active jobs."

5. create_a_leap_measurement

Field service workflows live and die by measurements. This tool creates a measurement form attached to a specific job. The agent passes the job_id, title, and form values. Truto translates the LLM's JSON into the required multipart payload.

"Generate a new measurement form for job ID 441 based on the field tech's notes. Set the title to 'Exterior Dimensions' and input the square footage values provided in the chat."

6. list_all_leap_appointment_result_options

Retrieves the available result options for a specific appointment. This is a critical state-management tool. Instead of an LLM guessing what statuses are allowed (e.g., guessing "Completed" when the system requires "Done"), it fetches the exact allowed enumerations dynamically.

"Check the available result options for appointment ID 992, then update the appointment to indicate the customer was not home."

To view the complete inventory of Leap tools, including custom fields, financial summaries, and invoice endpoints, review the Leap integration page.

Building Multi-Step Workflows

To build an autonomous field service agent, you need to fetch the Leap tools from Truto and bind them to your LLM framework. The following example uses TypeScript and LangChain, though this exact pattern applies to LangGraph, Vercel AI SDK, or custom loops.

First, define the API call to fetch the tools for a connected Leap account.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
 
// Fetch the tools specific to the connected Leap account
async function getLeapTools(accountId: string, trutoApiKey: string) {
  const response = await fetch(`https://api.truto.one/integrated-account/${accountId}/tools?methods[0]=read&methods[1]=write`, {
    headers: {
      "Authorization": `Bearer ${trutoApiKey}`,
      "Content-Type": "application/json"
    }
  });
 
  if (!response.ok) {
    throw new Error(`Failed to fetch tools: ${response.statusText}`);
  }
 
  return await response.json();
}

Once fetched, these tools contain the precise JSON schemas required to safely interact with Leap. You bind these schemas to your LLM.

async function runFieldServiceAgent(userPrompt: string) {
  const TRUTO_API_KEY = process.env.TRUTO_API_KEY!;
  const LEAP_ACCOUNT_ID = process.env.LEAP_ACCOUNT_ID!;
 
  // 1. Get the dynamic tools
  const tools = await getLeapTools(LEAP_ACCOUNT_ID, TRUTO_API_KEY);
 
  // 2. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 3. Create a strict system prompt regarding Leap's update behavior
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an autonomous field service dispatcher. You manage Leap jobs and appointments.\n" +
               "CRITICAL INSTRUCTION: When updating a job or appointment, you MUST fetch the existing record first. " +
               "Leap uses complete replacement for updates. If you do not include all original fields in your update payload, they will be deleted."],
    ["human", "{input}"],
    new MessagesPlaceholder("agent_scratchpad"),
  ]);
 
  // 4. Build and run the agent
  const agent = await createOpenAIFunctionsAgent({
    llm,
    tools,
    prompt,
  });
 
  const executor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 10,
  });
 
  const result = await executor.invoke({ input: userPrompt });
  console.log(result.output);
}

Handling API Rate Limits in the Agent Loop

When your agent chains multiple tools together - such as scanning a list of jobs and updating each one - it will inevitably hit Leap's rate limits.

Truto does not silently absorb or retry rate limit errors. Silent retries introduce unpredictable latency into agent loops, which causes LLM timeouts. Instead, when the upstream Leap API returns an HTTP 429, Truto passes that error directly back to your agent. Truto normalizes the rate limit information into standardized IETF headers: ratelimit-limit, ratelimit-remaining, and ratelimit-reset.

Your agent framework must catch the 429 error, read the ratelimit-reset header, pause execution, and retry the specific tool call. LangGraph provides native check-pointing for exactly this scenario, allowing the agent to suspend state and resume once the window clears.

Workflows in Action

Here is how these tools behave when executing complex field service tasks.

Scenario 1: Post-Inspection Status Update

Field technicians often dump raw notes into a chat interface after a site visit. The agent must translate these notes into structured FSM updates.

"The tech just finished the site survey for job ID 1094. The roof needs a full tear-off. Add a note to the job with this info, check the available appointment result options, and mark the survey appointment (ID 551) as completed."

Agent Execution Steps:

1. create_a_leap_job_note: The agent creates a note on job ID 1094 detailing the "full tear-off" requirement.
2. list_all_leap_appointment_result_options: The agent queries appointment ID 551 to see the exact string Leap requires for a completed status (e.g., "Completed_Success").
3. get_single_leap_appointment_by_id (implicit from instructions): The agent fetches the current state of appointment 551.
4. leap_appointment_results_bulk_update: The agent applies the specific result option to the appointment, closing out the step.

sequenceDiagram
    participant User as Field Tech
    participant Agent as AI Agent
    participant Truto as Truto Proxy
    participant Leap as Leap API

    User->>Agent: "Add tear-off note and mark survey complete"
    Agent->>Truto: create_a_leap_job_note(job_id: 1094)
    Truto->>Leap: POST /jobs/1094/notes
    Leap-->>Truto: 201 Created
    Truto-->>Agent: Note added
    
    Agent->>Truto: list_all_leap_appointment_result_options(appointment_id: 551)
    Truto->>Leap: GET /appointments/551/results
    Leap-->>Truto: 200 OK (Options: ['Completed_Success', 'No_Show'])
    Truto-->>Agent: Result Options
    
    Agent->>Truto: leap_appointment_results_bulk_update(result: 'Completed_Success')
    Truto->>Leap: POST /appointments/551/results_bulk
    Leap-->>Truto: 200 OK
    Truto-->>Agent: Success
    Agent-->>User: "Note added and appointment marked as Completed_Success."

Scenario 2: Emergency Rescheduling

When a customer calls in to cancel, the agent needs to identify them, find their active jobs, and coordinate the schedule.

"Customer phone number 555-0198 just called. They need to push their installation job out by one week. Find their job and update the timeline."

Agent Execution Steps:

1. list_all_leap_contacts: The agent searches for the provided phone number to resolve the customer ID and name.
2. list_all_leap_jobs: The agent queries jobs using the customer_id and uses includes [] to fetch related schedule data.
3. get_single_leap_job_by_id: The agent pulls the full job record to prepare for a destructive update.
4. update_a_leap_job_by_id: The agent modifies the start/end dates in memory, leaves all other fields intact, and pushes the entire updated payload back to Leap.

The dispatcher gets a confirmation that the job has been moved, without the risk of the LLM accidentally deleting the job's line items or assigned division.

Moving Beyond Point-to-Point Integration

Building AI agents that reliably orchestrate FSM tools is an exercise in schema constraint and API normalization. If you expose raw Leap endpoints to an LLM, you will spend your engineering cycles writing defensive code to handle destructive updates, multipart translations, and nested includes.

By leveraging Truto's /tools endpoint, you collapse the integration surface area. Your agent gets strictly typed JSON schemas, standardized pagination, and deterministic error handling. This allows you to focus on the intelligence of your dispatch and routing logic, rather than maintaining boilerplate API wrappers.