Connect TOPdesk to AI Agents: Orchestrate Tickets, Assets & Bookings

You want to connect TOPdesk to an AI agent so your internal systems can independently read ITSM tickets, orchestrate IT asset assignments, manage facility reservations, and handle visitor logs based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to maintain a fragile, custom-built integration architecture.

Giving a Large Language Model (LLM) read and write access to your TOPdesk instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands TOPdesk's unique querying syntax, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting TOPdesk to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting TOPdesk 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 TOPdesk, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex IT Service Management (ITSM) and facility 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 ITSM Agents

Before writing a line of integration code, decide what layer your agent talks to. This choice determines how reliable and safe your production system will be.

Direct API tools - exposing one tool per raw TOPdesk endpoint - look convenient on day one, but they push provider-specific quirks straight into the LLM's context window. The model has to learn the difference between an operator endpoint and a requester endpoint, memorize specific UUID formats for linked assets, and construct complex query syntax on the fly. Every one of those quirks is a hallucination waiting to happen.

A unified proxy tool layer collapses these complexities behind a consistent schema. Your agent sees create_a_to_pdesk_incident, list_all_to_pdesk_assets, and create_a_to_pdesk_reservation. That gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from stable function names. It never invents invalid query strings or payload structures.
2. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit TOPdesk, so a broken tool call fails fast instead of creating malformed records.
3. Context window efficiency. Raw TOPdesk payloads often include dozens of nested objects and irrelevant metadata. Truto's tools trim these responses down to precisely what the LLM needs to make its next decision.

The Engineering Reality of Custom TOPdesk Connectors

Building AI agents is easy. Connecting them to external SaaS APIs like TOPdesk is hard. If you decide to build the integration layer yourself, you own the entire API lifecycle. TOPdesk introduces several highly specific integration challenges that break standard LLM assumptions.

The FIQL and RSQL Query Trap

Unlike most modern REST APIs that use standard query parameters (like ?status=open&priority=high), TOPdesk relies heavily on FIQL (Feed Item Query Language) and RSQL for filtering endpoints. When an agent needs to retrieve a list of unassigned incidents created today, it must formulate a valid string like archived==false;operator.id==null;creationDate=gt=2023-01-01T00:00:00.000Z.

If you hand-code this integration, you have to write complex prompts to teach the LLM the exact syntax of FIQL. When the LLM inevitably hallucinates an operator (using >= instead of =ge=), the API request fails. Truto abstracts this by providing specific, strongly typed query schemas that map safely to TOPdesk's underlying FIQL requirements.

The Requester vs. Operator Bifurcation

TOPdesk maintains a strict separation between Requesters (Self-Service Portal users) and Operators (IT staff). This isn't just a permissions model - it's an entirely divergent API path. Creating a ticket via the operator endpoint (/api/incidents) requires different payload structures than creating one via the requester endpoint (/api/tas/secure/incidents).

If an agent is interacting with a standard user, it must use requester models. If the agent acts as an IT admin, it uses operator models. Forcing an LLM to dynamically toggle between these two paradigms depending on the active user context is a recipe for auth errors and 400 Bad Requests. Truto defines distinct tools for these paths, ensuring the LLM explicitly selects the right operation for the role.

Asset Templates and Nested Assignments

Asset Management in TOPdesk is not flat. Creating or modifying an asset requires navigating a complex web of Template IDs, Grid Fields, and assignments. You cannot simply POST /assets with a payload of laptop details. You must query the correct template, retrieve its mandatory fields, construct a payload matching that specific schema, and execute a multi-step assignment to a branch, location, or person group.

Hero Tools for TOPdesk AI Agents

Truto provides all the resources defined on a TOPdesk integration as tools for your LLM frameworks to use. Every integration is represented as a comprehensive JSON object mapping API endpoints into standard methods. We generate Proxy APIs where Truto handles the pagination, authentication, and query parameter processing, returning tools your agent can actually understand.

Here are the highest-leverage operations for TOPdesk orchestration.

1. List TOPdesk Incidents

Tool Name: list_all_to_pdesk_incidents

This tool allows the agent to search and filter incidents using TOPdesk's backend indexing. It is critical for triage agents that need to periodically check for new, unassigned, or escalated tickets.

"Find all open incidents submitted by the marketing team regarding the new software deployment, and return their current status and priority levels."

2. Create a TOPdesk Incident

Tool Name: create_a_to_pdesk_incident

This tool creates a new IT incident or service request. It strictly enforces the required fields (like caller, request description, and callType) and prevents the agent from passing read-only metadata into the creation payload.

"The database cluster triggered a high CPU alert. Create a critical incident in TOPdesk assigned to the Database Admin group, including the error logs in the description."

3. Escalate an Incident

Tool Name: to_pdesk_incidents_escalate

Helpdesk agents often need to escalate tickets that breach SLAs or require higher-tier intervention. This tool specifically triggers the escalation workflow in TOPdesk, adjusting the escalationStatus and internal routing logic properly, rather than relying on a generic PATCH update.

"Ticket #23049 has been open for 48 hours without a response. Escalate the incident immediately and add a note that the SLA has been breached."

4. Search and List Assets

Tool Name: list_all_to_pdesk_assets

Before an agent can assign a laptop to a new hire or dispatch a replacement monitor, it must verify inventory. This tool executes searches against TOPdesk's asset management module, allowing agents to filter by template, state, and branch location.

"Check our London office inventory to see if there are any available MacBook Pro M2 assets in the 'In Stock' state."

5. Create a Facility Reservation

Tool Name: create_a_to_pdesk_reservation

TOPdesk isn't just for IT - it handles facility management. Agents can use this tool to autonomously book meeting rooms, company vehicles, or temporary workstations for visitors and employees.

"Book conference room A in the Chicago office for tomorrow at 10 AM, and assign the reservation to John Doe."

6. Register a Visitor

Tool Name: create_a_to_pdesk_visitor

Agents managing physical security or front-desk operations can register visitors autonomously, passing the necessary host information and arrival expectations directly into TOPdesk.

"We have a contractor arriving on Tuesday for server maintenance. Register them as a visitor in TOPdesk and set the IT Director as their host."

To view the complete schema details, query parameters, and the full inventory of over 100+ available TOPdesk tools, visit the TOPdesk integration page.

Workflows in Action

Individual tool calls are useful, but the real power of AI agents lies in autonomous orchestration. Here are two concrete examples of how an LLM can chain TOPdesk tools to solve complete operational tasks.

Use Case 1: Autonomous IT Helpdesk Triage

In this scenario, an AI agent operates as a Level 1 dispatcher. It monitors incoming Slack messages or emails, analyzes the intent, and updates the ITSM system accordingly.

"A user just reported that they cannot connect to the corporate VPN. Find any open VPN-related incidents to see if there is a known outage. If not, create a new high-priority incident, escalate it, and assign it to the Network Operations group."

Agent Execution Flow:

1. The agent calls list_all_to_pdesk_incidents with search terms targeting recent "VPN" issues.
2. Finding no widespread outage tickets, the agent calls create_a_to_pdesk_incident with the user's details, setting the category to Network and subcategory to VPN.
3. Recognizing the critical nature of remote access, the agent immediately calls to_pdesk_incidents_escalate on the newly returned incident ID.
4. Finally, the agent calls update_a_to_pdesk_incident_by_id to route the ticket to the specific Network Operations operator group.

Use Case 2: Employee Onboarding Logistics

When a new employee is hired, multiple systems must be coordinated. A HR agent can handle the physical provisioning through TOPdesk.

"Sarah Jenkins starts next Monday in the Austin office. Find an available Windows laptop in the Austin inventory, assign it to her, and book a hot desk for her first week."

Agent Execution Flow:

1. The agent calls list_all_to_pdesk_assets filtering by the Austin branch, the "Windows Laptop" template, and an "Available" status.
2. After identifying an asset ID, the agent calls to_pdesk_asset_assignments_bulk_update to officially link the asset to Sarah's person record in TOPdesk.
3. The agent then calls list_all_to_pdesk_reservable_locations to find an open desk in Austin.
4. Finally, the agent calls create_a_to_pdesk_reservation for the selected desk, spanning her first five working days.

Building Multi-Step Workflows

To power these workflows, you need to connect your agent framework to Truto. Truto makes this seamless by exposing all integrated endpoints via a single /tools API. This approach works natively with LangChain, LangGraph, CrewAI, Vercel AI SDK, or any custom LLM wrapper.

1. Fetching Tools via the Truto SDK

Instead of hardcoding schemas, you dynamically fetch them based on the connected user's account. This ensures your agent only attempts operations the user actually has permissions to perform.

import { TrutoToolManager } from "truto-langchainjs-toolset";
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
 
async function runAgent() {
    // Initialize the Tool Manager with your Truto API key
    const toolManager = new TrutoToolManager({
        apiKey: process.env.TRUTO_API_KEY,
    });
 
    // Fetch the tools for the specific connected TOPdesk account
    // INTEGRATED_ACCOUNT_ID is obtained when the user authenticates via Truto Link
    const tools = await toolManager.getTools(process.env.TOPDESK_INTEGRATED_ACCOUNT_ID);
 
    // Initialize the LLM
    const llm = new ChatOpenAI({
        modelName: "gpt-4o",
        temperature: 0,
    });
 
    // Bind the Truto tools to the LLM natively
    const llmWithTools = llm.bindTools(tools);
 
    // Define agent behavior
    const prompt = ChatPromptTemplate.fromMessages([
        ["system", "You are an elite IT service management agent orchestrating TOPdesk."],
        ["human", "{input}"],
        ["placeholder", "{agent_scratchpad}"],
    ]);
 
    const agent = createToolCallingAgent({
        llm: llmWithTools,
        tools,
        prompt,
    });
 
    const executor = new AgentExecutor({
        agent,
        tools,
    });
 
    const result = await executor.invoke({
        input: "Create a new incident for a broken printer in the lobby, then list the incident number."
    });
 
    console.log(result.output);
}

2. The Orchestration Loop

When you execute the agent, it enters an autonomous loop. It reasons about the prompt, decides which tool to call, waits for the response, and then determines if it has enough information to proceed or if it needs to call another tool.

sequenceDiagram
    participant User as User
    participant Agent as Agent (LangGraph/LangChain)
    participant Truto as Truto Tools Layer
    participant TOPdesk as TOPdesk API

    User->>Agent: "Find an available laptop and assign it."
    Agent->>Truto: Call list_all_to_pdesk_assets(query)
    Truto->>TOPdesk: GET /api/assets (with FIQL)
    TOPdesk-->>Truto: Asset payload
    Truto-->>Agent: Normalized Asset JSON
    Agent->>Truto: Call to_pdesk_asset_assignments_bulk_update(id)
    Truto->>TOPdesk: PUT /api/assets/{id}/assignments
    TOPdesk-->>Truto: 200 OK
    Truto-->>Agent: Success confirmation
    Agent-->>User: "Laptop assigned successfully."

3. Handling Rate Limits and Errors

When building autonomous loops, error handling is critical. AI agents will frequently hit API concurrency limits if they attempt to execute wide searches or batch updates simultaneously.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec (see Truto Rate Limits). The caller is responsible for retry/backoff.

Do not rely on the agent itself to "guess" when to retry. Your application architecture must intercept 429 errors from the tool execution and implement standard exponential backoff before handing control back to the agent loop. Because Truto normalizes the ratelimit-reset headers, your retry logic can accurately pause the exact required duration without polling blindly.

Moving Beyond Proof of Concepts

Wiring an LLM to an API in a Jupyter notebook takes an hour. Getting that same architecture to survive in an enterprise production environment takes months. By abstracting the TOPdesk API through Truto's proxy layer, you eliminate the need to write custom FIQL parsers, maintain branching logic for operator vs. requester endpoints, or track schema drift across asset management updates.

Your engineering team can focus on refining the AI agent's reasoning capabilities, while Truto handles the SaaS connectivity.