Skip to content

Connect Boulevard to AI Agents: Sync Staff and Schedule Workflows

Uday Gajavalli Uday Gajavalli 10 min read AI & Agents
TrutoFor teams building AI agents

Give your AI agent Boulevard tools.

Connect Boulevard to AI agents using Truto's unified tools endpoint to automate complex GraphQL mutations. This guide covers bypassing raw API quirks, managing nested booking schemas, and building agentic scheduling workflows.

In this guide

  1. 01Fetch Boulevard Tools
  2. 02Bind Tools to the LLM
  3. 03Construct the Agent Prompt
  4. 04Execute the Workflow
  5. 05Handle Rate Limits and State

The guide

Learn how to connect Boulevard to AI agents using Truto's tools endpoint to autonomously orchestrate staff schedules, bookings, and waitlist workflows.

You want to connect Boulevard to an AI agent so your system can independently read waitlists, generate new bookings, adjust staff schedules, and issue vouchers based on historical client context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build a bespoke GraphQL connector from scratch.

Giving a Large Language Model (LLM) read and write access to your Boulevard instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom GraphQL client layer, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Boulevard to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Boulevard 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 Boulevard, bind them natively to an LLM using frameworks like LangChain, CrewAI, or the Vercel AI SDK, and execute complex scheduling and staffing workflows. 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, decide what layer your agent talks to. This choice determines how safe your production system will be.

Direct API tools (one tool per raw Boulevard GraphQL endpoint) look convenient but they push provider quirks into the LLM's context window. The model has to remember that Boulevard uses a strict graph structure, that appointmentId is required for some mutations while bookingId is required for others, and that updating a service requires navigating a complex nested node tree. Every one of those quirks is a hallucination waiting to happen.

Truto abstracts these underlying mechanics. We map Boulevard's underlying GraphQL resources into proxy REST methods, normalizing the schema into flat, stable, descriptive JSON tools. Your agent sees create_a_boulevard_waitlist_entry or boulevard_appointments_reschedule - not arbitrary GraphQL query strings. That gives you concrete safety wins:

  1. Smaller attack surface for hallucination. The LLM only ever chooses from highly descriptive, stable function names. It never invents GraphQL syntax or attempts invalid query structures.
  2. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit the underlying platform, meaning a broken tool call fails fast instead of silently executing partial state changes.
  3. Decoupled authentication. Your agent reasoning loop never handles raw OAuth tokens, refresh lifecycles, or tenant-specific location IDs in its prompt context. Truto manages the session securely at the infrastructure layer.

The Engineering Reality of the Boulevard API

Giving an LLM access to external scheduling data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in a tool decorator. In production against complex operational systems like Boulevard, this approach collapses.

Boulevard's API introduces several specific integration challenges. 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 GraphQL Payload Trap

Boulevard's API is exclusively GraphQL. While this is powerful for explicit data fetching in traditional front-end applications, it is a nightmare for generative AI. LLMs are notoriously bad at reliably generating raw GraphQL query strings without hallucinating variables, omitting mandatory fragment spreads, or corrupting syntax. Furthermore, Boulevard's booking model requires strict sequential logic: you don't just "create an appointment." You often have to create a booking, add service add-ons, assign specific staff, set delivery methods, and then complete the booking. Expecting an LLM to dynamically construct these chained mutations in raw GraphQL is a recipe for catastrophic failure.

Truto solves this by exposing these complex mutations as flat, individual REST-like tools (e.g., create_a_boulevard_booking_service_addon). The agent just fills in standard JSON properties, and the Truto proxy handles the translation into the required GraphQL mutation format.

Granular Scope and Location Context

Boulevard operates heavily on the concept of locationId. Almost every significant entity - staff, appointments, products, inventory - is bound to a specific physical location. When building AI agents, you cannot rely on the LLM to "remember" the location ID across a conversation thread. If an agent tries to reschedule a client at location A using a staff member only available at location B, the API will reject the request with complex domain-specific error codes. Truto's proxy methods enforce schema requirements upfront, ensuring that necessary constraints like locationId and staffId are provided before making the network hop.

Rate Limiting and Resilience

A common misconception when building agentic workflows is that the integration layer will magically absorb all traffic spikes. This is structurally unsafe for AI agents.

Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Boulevard 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 HTTP headers per the IETF specification: ratelimit-limit, ratelimit-remaining, and ratelimit-reset (see our API Reference).

It is the responsibility of your agent's execution environment to read the ratelimit-reset header, pause execution, and retry. If your agent is autonomously burning through waitlist lookups and hits a limit, Truto provides the exact timestamp to resume - but your code must handle the backoff.

Boulevard Hero Tools for AI Agents

Rather than exposing every single Boulevard endpoint to your LLM, you should restrict your agent to the highest-leverage operations. We call these "hero tools." By limiting the toolset, you improve the LLM's instruction-following reliability.

Here are the critical tools you can fetch dynamically via Truto's /tools endpoint to orchestrate staff and schedule workflows.

Reschedule Appointments

boulevard_appointments_reschedule

Rescheduling is one of the most common operational tasks in salon and spa management. This tool executes the appointmentReschedule mutation, moving an existing appointment to a new bookable time slot and optionally triggering notifications to the client.

"Client Sarah Jenkins just called - she is stuck in traffic. Check the available times for her current appointment today, and reschedule it to the next available slot after 3:00 PM. Make sure to send her a confirmation text."

Manage Waitlist Entries

create_a_boulevard_waitlist_entry

Waitlists are the lifeblood of high-demand service businesses. This tool executes the waitlistEntryCreate mutation, allowing an agent to autonomously place a client in the queue for specific services, logging their time preferences and contextual notes.

"Add Michael Chang to the waitlist for a deep tissue massage this Friday. He prefers the afternoon and specifically requested David as his massage therapist if possible."

Unpublish Staff Shifts

boulevard_shifts_unpublish

When a staff member calls out sick, schedules must be cleared immediately to prevent double-booking. This tool allows the agent to execute the unpublishShift mutation across a specific date range for a given staff member and location.

"Emma just reported that she has the flu and cannot come in today or tomorrow. Unpublish all of her shifts at the Downtown location for the next 48 hours."

Issue Voucher Gift Cards

create_a_boulevard_voucher_gift_card

Service recovery requires speed. When a client has a poor experience or an appointment is abruptly cancelled, this tool allows the agent to execute the createVoucherGiftCard mutation, issuing an immediate service credit to the client's account.

"We had to cancel Marcus's appointment last minute because of the water leak. Issue a $50 voucher gift card to his profile with the note 'Apology for late cancellation' and email him the code."

Update Staff Service Rules

create_a_boulevard_staff_service_rule

Managing who can perform what service is a constant operational chore. This tool executes the staffServiceRuleUpsert mutation, allowing the agent to dynamically assign or unassign specific bookable services to a staff member's profile.

"Jessica has completed her advanced color correction certification. Update her staff service rules to make the 'Advanced Color Correction' service bookable for her at the Westside location."

Assign Staff to Booking Services

update_a_boulevard_booking_service_staff_by_id

During a busy day, front desk agents constantly shuffle staff assignments on active bookings to optimize flow. This tool targets a specific service item within an existing booking and updates the assigned staff member via the bookingServiceSetStaff mutation.

"Alex is running 20 minutes behind. Look up his upcoming haircut appointment at 10 AM, and reassign the service to Jordan so the client doesn't have to wait."

To view the complete inventory of available tools, including detailed parameter schemas for products, inventory, and point-of-sale operations, visit the Boulevard integration page.

Workflows in Action

Exposing tools is only the first step. The true value of AI agents comes from chaining these tools together to execute multi-step operational workflows autonomously.

Scenario 1: Autonomous Sick-Day Reassignment

When a service provider calls out sick, front desk staff typically spend hours manually clearing schedules, calling clients, and shuffling appointments. An AI agent can handle this entire sequence in seconds.

"David called out sick for today at the Uptown location. Clear his schedule, find all clients booked with him today, see if there are open times with other staff for the same services, and rebook them. If there are no open spots, add the clients to the waitlist and issue a $25 apology voucher."

Agent Execution Trace:

  1. list_all_boulevard_shifts: The agent queries the schedule to confirm David's working hours for the day.
  2. boulevard_shifts_unpublish: The agent removes David's shifts to prevent any new online bookings.
  3. list_all_boulevard_appointments: The agent filters appointments by staffId and date to find impacted clients.
  4. boulevard_appointments_lookup_reschedule_times: For each appointment, the agent checks availability with other staff members for the exact same services.
  5. update_a_boulevard_booking_service_staff_by_id: If an alternative staff member is available at the same time, the agent reassigns the service.
  6. create_a_boulevard_waitlist_entry: If no slot is available, the agent moves the client to the waitlist.
  7. create_a_boulevard_voucher_gift_card: The agent issues a courtesy voucher to the unbooked clients for the inconvenience.

Scenario 2: VIP Client Waitlist Promotion

Waitlist management is often a game of tetris. When an appointment is cancelled, an agent can intelligently promote the right client from the waitlist based on their history or requested services.

"A 90-minute massage slot just opened up at 2 PM. Check the waitlist for any VIP clients who requested a massage today. If you find one, remove them from the waitlist, book the appointment, and attach the 'Aromatherapy' service add-on since they usually request it."

Agent Execution Trace:

  1. list_all_boulevard_waitlist_entries: The agent retrieves the current waitlist for the location.
  2. get_single_boulevard_client_by_id: The agent cross-references waitlisted clients to check for VIP tags or historical preferences.
  3. delete_a_boulevard_waitlist_entry_by_id: The agent removes the selected VIP from the waitlist.
  4. create_a_boulevard_booking & create_a_boulevard_booking_service: The agent constructs the new booking and attaches the primary massage service.
  5. create_a_boulevard_booking_service_addon: The agent dynamically appends the aromatherapy add-on to the booking based on the prompt instructions.

Building Multi-Step Workflows

To build these workflows in your application, you need to fetch the proxy tool schemas from Truto and bind them to your LLM framework. The following example demonstrates how to do this using LangChain and the @trutohq/truto-langchainjs-toolset package.

We will also implement a wrapper to gracefully handle HTTP 429 rate limits, ensuring the agent pauses and retries based on Truto's strict IETF header passthrough.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
// 1. Initialize the LLM
const llm = new ChatOpenAI({
  modelName: "gpt-4o",
  temperature: 0,
});
 
// 2. Fetch Boulevard tools for a specific integrated account
// We filter for 'write' and 'read' methods relevant to scheduling.
const trutoManager = new TrutoToolManager({
  trutoApiKey: process.env.TRUTO_API_KEY,
  integratedAccountId: "your_boulevard_account_id"
});
 
async function runBoulevardAgent() {
  console.log("Fetching Boulevard tools from Truto...");
  const tools = await trutoManager.getTools({
    methods: ["read", "write"]
  });
 
  // 3. Define the autonomous scheduling prompt
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a highly capable salon operations AI. You manage schedules, bookings, and waitlists in Boulevard. Always verify location IDs and staff availability before mutating records. If an API call fails due to a rate limit (HTTP 429), the system will handle the backoff, but you must attempt the operation again if instructed."],
    ["placeholder", "{chat_history}"],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 4. Bind the normalized Truto tools to the LLM
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
 
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 10,
    // Ensure we handle tool errors gracefully without crashing the agent loop
    handleParsingErrors: true,
  });
 
  // 5. Execute a complex operational prompt
  const userInput = "David called out sick for today at the Uptown location (Location ID: loc_123). Unpublish his shifts for today. Find all appointments booked with him today, and move them to the waitlist.";
  
  try {
    console.log("Executing workflow...");
    const result = await agentExecutor.invoke({
      input: userInput,
    });
    console.log("Workflow Complete:", result.output);
  } catch (error) {
    // Rate Limit Handling Logic
    // Truto passes the exact 429 response from Boulevard.
    // You must check for the IETF ratelimit-reset header.
    if (error.status === 429 && error.headers && error.headers['ratelimit-reset']) {
      const resetTime = parseInt(error.headers['ratelimit-reset'], 10);
      const waitSeconds = Math.max(0, resetTime - Math.floor(Date.now() / 1000));
      console.warn(`Rate limit hit. Must wait ${waitSeconds} seconds before retrying.`);
      // Implement your application-level delay and retry logic here.
    } else {
      console.error("Agent execution failed:", error);
    }
  }
}
 
runBoulevardAgent();

The Data Flow Architecture

When your agent makes a decision, the data flow must be secure, strictly typed, and isolated from token lifecycle management. Here is how Truto handles the execution pipeline when the LLM triggers a tool call:

sequenceDiagram
    participant LLM as Agent (LangChain)
    participant TrutoProxy as Truto Proxy API
    participant TrutoCore as Truto Infrastructure
    participant BoulevardAPI as Boulevard GraphQL API

    LLM->>TrutoProxy: POST /proxy/boulevard/create_waitlist_entry<br>(JSON Payload)
    TrutoProxy->>TrutoCore: Validate JSON Schema
    TrutoCore->>TrutoCore: Inject secure OAuth credentials
    TrutoCore->>BoulevardAPI: GraphQL Mutation (waitlistEntryCreate)
    
    alt Rate Limit Exceeded
        BoulevardAPI-->>TrutoCore: 429 Too Many Requests
        TrutoCore-->>TrutoProxy: 429 + ratelimit-reset Header
        TrutoProxy-->>LLM: Error: Implement Caller Backoff
    else Success
        BoulevardAPI-->>TrutoCore: 200 OK (GraphQL Data)
        TrutoCore-->>TrutoProxy: Flatten to flat JSON
        TrutoProxy-->>LLM: Tool Execution Success
    end

By keeping the complexity of GraphQL, authentication, and schema validation entirely on the Truto side, your LLM context window remains unpolluted. The agent focuses entirely on operational reasoning, while Truto ensures the underlying integration behaves deterministically.

Building AI agents on top of legacy or complex SaaS platforms does not require writing custom connectors from scratch. By treating integrations as standardized tools, you can move from prototype to production workflows in days, not quarters.

Two ways to put Boulevard to work

Truto

For product teams

Give your agent Boulevard tools

Your customers connect their own Boulevard accounts. Your product gets one API and MCP tools for Boulevard, through Truto.

FAQ

How do AI agents interact with Boulevard's GraphQL API?
Instead of forcing the LLM to write raw GraphQL queries, Truto abstracts Boulevard's API into flat, REST-like JSON tools. These tools are dynamically fetched and bound to frameworks like LangChain, ensuring deterministic and safe execution.
Does Truto automatically retry rate-limited API calls?
No. Truto passes HTTP 429 Too Many Requests errors directly back to the caller, along with standardized IETF headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`). The agent's execution environment is responsible for implementing retry and backoff logic.
Can I filter which tools my AI agent has access to?
Yes. When calling the Truto `/tools` endpoint, you can pass query parameters to filter tools by method type. For example, you can restrict an agent to only use read-only tools to prevent accidental data modification.
Which LLM frameworks are supported for tool calling?
The Truto `/tools` endpoint provides standard JSON schemas that can be used with any major framework, including LangChain, LangGraph, CrewAI, and the Vercel AI SDK.
Boulevard BoulevardAI agent tools Get a sandbox

More from our Blog