Connect Kayako to AI Agents: Sync Customer Profiles and Service Logs

You want to connect Kayako to an AI agent so your system can independently triage support tickets, sync customer profiles, query knowledge base articles, and log service interactions based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually code dozens of endpoints or maintain complex API wrappers.

Giving a Large Language Model (LLM) read and write access to your Kayako instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that handles complex payload schemas, or you use a managed infrastructure layer that abstracts the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Kayako to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Kayako 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 Kayako, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex IT service management and customer support workflows. 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 Custom Kayako Connectors

Building AI agents is easy. Connecting them to external SaaS APIs is hard. 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 a tool decorator. In production, this approach collapses entirely, especially with an ecosystem as robust as Kayako.

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

The Dynamic Predicate Filtering Trap

Kayako relies on a complex, dynamic filtering system rather than standard query parameters. If you want to search for specific users or organizations, you cannot simply GET /users?email=test@example.com. Instead, you must first query /api/v1/users/definitions to understand available fields, operators, and types. Then, you must construct a deeply nested predicates array and send it to POST /api/v1/users/filter.

If you hand-code this integration, you have to write complex prompts to teach the LLM the exact syntax of Kayako's predicate arrays, including operator names like string_contains_insensitive or collection_contains_any_insensitive. When the LLM inevitably hallucinates a predicate operator or forgets to wrap a value in the correct data structure, the API rejects the request with a vague validation error.

Shadow Posts and Real-Time State

Kayako separates conversation messages into standard posts and shadow_posts. This architecture supports real-time client communication (using client_id tracking) so messages reflect immediately in the UI. If an LLM needs to read a conversation timeline, it has to understand how to merge and sequence these different resource types. Furthermore, creating a reply requires exact mapping to a source_channel (MAIL, HELPCENTER, TWITTER, MESSENGER) rather than just pushing text to a generic message endpoint. Forcing the LLM to manage these state distinctions consumes massive context windows and increases error rates.

Strict SLA and Status State Transitions

Updating a case in Kayako isn't a simple PATCH request updating a string field. Cases are bound to SLA metrics, custom case statuses, and priority configurations that exist as distinct entities (/api/v1/slas, /api/v1/statuses). If your agent attempts to update a case status using a string like "Resolved" instead of the specific integer ID associated with that status in your specific Kayako instance, the request fails.

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 Kayako endpoint) look convenient, but they push provider quirks directly into the LLM's context. The model has to remember that Kayako needs nested predicate arrays, that case statuses are integers, and that replies require specific channel enumerations. Every one of those quirks is a hallucination waiting to happen.

A unified tool layer collapses these complexities behind a stable schema. Your agent sees standard function names and receives clean JSON schemas detailing exactly what is required.

That gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from stable function names. It never invents predicate operators or attempts invalid state transitions.
2. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit the upstream API, so a broken tool call fails fast instead of creating corrupted data.
3. Decoupled authentication. The agent never sees an API key or OAuth token. It authenticates with Truto, which handles the upstream Kayako authentication securely.

sequenceDiagram
  participant Agent as AI Agent
  participant ToolManager as Truto Tool Manager
  participant Truto as Truto API
  participant Kayako as Kayako API

  Agent ->> ToolManager: Request tools for Kayako
  ToolManager ->> Truto: GET /integrated-account/{id}/tools
  Truto -->> ToolManager: Returns JSON schemas
  ToolManager -->> Agent: Binds tools to LLM
  
  Agent ->> ToolManager: Call create_a_kayako_case(args)
  ToolManager ->> Truto: POST proxy request
  Truto ->> Kayako: Upstream API call
  Kayako -->> Truto: 201 Created
  Truto -->> ToolManager: Normalized JSON response
  ToolManager -->> Agent: Tool execution result

Kayako Hero Tools for AI Agents

Truto exposes Kayako's endpoints as AI-ready tools. You can customize the tool descriptions inside the Truto dashboard to guide the LLM's behavior. Here are the highest-leverage operations for automating Kayako workflows.

list_all_kayako_cases

Retrieves a list of cases (conversations) ordered by updated time. Crucial for agents acting as automated triage systems that need to constantly poll or check recent inbox activity. It returns deep context including SLA metrics, read markers, and custom fields.

"Fetch the 10 most recently updated support cases. Check their SLA metrics and status to see if any high-priority tickets are in danger of breaching their SLA targets."

create_a_kayako_case

Allows the agent to generate new conversations programmatically. This is useful for AI workflows that monitor external systems (like Datadog or an internal database) and proactively create tickets for the support or engineering teams.

"Create a new high-priority case in Kayako for the customer 'Acme Corp'. Set the subject to 'Database Outage Alert' and assign it to the Tier 2 Infrastructure team."

update_a_kayako_case_by_id

Updates an existing Kayako conversation. Agents use this to modify ticket metadata, such as escalating priority, changing the assigned agent, or updating custom fields after analyzing the conversation context.

"Update case ID 49201. Change the status to 'Pending Customer Response' and set the priority level to 'Low'."

kayako_cases_create_reply

Adds a reply to a specific case. This is the primary action tool for an AI agent acting as a Level 1 support representative, allowing it to respond directly to users through the correct source channel.

"Draft and send a reply for case ID 51022. Inform the customer that their refund has been processed and will appear in their account within 3 to 5 business days. Use the MAIL channel."

kayako_help_center_search_search

Executes a unified search against the Kayako help center for articles and conversations. Agents use this as an internal RAG (Retrieval-Augmented Generation) step to look up policy or troubleshooting steps before attempting to answer a customer.

"Search the help center for articles related to 'SSO configuration errors' to find the exact steps for resetting SAML certificates."

list_all_kayako_users

Retrieves the user directory. Agents use this to cross-reference customer profiles, check organizational associations, and verify identities before authorizing destructive actions or sharing sensitive ticket data.

"Retrieve the user record for jane.doe@example.com to verify which organization she belongs to and whether she has administrator privileges."

For the complete tool inventory and schema details, visit the Kayako integration page.

Workflows in Action

To understand how this looks in production, here are concrete examples of how an AI agent strings these tools together to execute multi-step operations.

1. Automated L1 Ticket Triage and Response

Customer support teams spend hours reading tickets just to categorize them and point users to existing documentation. An agent handles this instantly.

"Review new cases, search the knowledge base for answers, reply to the user if an article solves their problem, and tag the ticket as pending."

1. The agent calls list_all_kayako_cases to fetch tickets with a "New" status.
2. It reads the contents of a ticket asking about password resets.
3. It calls kayako_help_center_search_search using the query "password reset".
4. It reads the retrieved article content.
5. It calls kayako_cases_create_reply to send the instructions to the user.
6. Finally, it calls update_a_kayako_case_by_id to change the status to "Pending".

2. Escalating Breaching SLAs

IT service desks require strict adherence to Service Level Agreements. An agent can act as an SLA enforcer.

"Find cases assigned to the billing team that are within 2 hours of SLA breach. Escalate their priority and notify the on-call manager."

1. The agent calls list_all_kayako_cases and evaluates the sla_metrics array in the response payload.
2. It identifies three tickets close to breaching.
3. For each ticket, it calls update_a_kayako_case_by_id to increase the priority to "Urgent".
4. It calls kayako_cases_create_reply (acting as an internal note channel if configured, or sending an alert) to ping the on-call manager with the ticket IDs.

3. VIP Customer Context Enrichment

When enterprise customers write in, agents need full context. An AI agent can automatically enrich tickets with user data the moment they arrive.

"Whenever a ticket comes in from a user at 'BigTech Inc', lookup their user profile, check their organization tier, and pin an internal note to the case with their account details."

1. The agent fetches a new case via list_all_kayako_cases.
2. It calls list_all_kayako_users or kayako_users_filter to retrieve the requester's profile.
3. It parses the custom fields to identify their organization tier.
4. It calls list_all_kayako_case_notes (or the create note equivalent) to pin an internal summary of the customer's tier and previous interactions to the top of the conversation.

Building Multi-Step Workflows

To build these workflows, you need to bind Truto's proxy API tools to your agent framework. In this example, we use LangChain.js, though the same principles apply to LangGraph, Vercel AI SDK, or CrewAI.

Handling Rate Limits in Agent Loops

Before deploying to production, you must understand how Truto handles rate limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Kayako API returns an HTTP 429 Too Many Requests, Truto passes that error directly back to your agent.

However, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification: ratelimit-limit, ratelimit-remaining, and ratelimit-reset. Your code is responsible for catching the 429 error, reading the ratelimit-reset header, and forcing the agent to wait. If you fail to implement this, your agent will enter an infinite retry loop and burn through its execution tokens.

Here is how you initialize the toolset and handle execution in a robust agent loop:

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 runKayakoAgent(promptText: string) {
  // 1. Initialize the Truto Tool Manager
  const truto = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
  });
 
  // 2. Fetch all tools for the connected Kayako account
  // Replace with your specific Kayako integrated account ID
  const kayakoTools = await truto.getTools("kayako_integrated_account_id");
 
  // 3. Initialize the LLM (e.g., GPT-4o)
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Create the system prompt
  const prompt = ChatPromptTemplate.fromMessages([
    [
      "system",
      "You are an autonomous IT support agent connected to Kayako. " +
      "Use the provided tools to query cases, read articles, and reply to users. " +
      "Always verify user context before modifying case state."
    ],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 5. Bind tools and create the agent
  const agent = createToolCallingAgent({
    llm,
    tools: kayakoTools,
    prompt,
  });
 
  const executor = new AgentExecutor({
    agent,
    tools: kayakoTools,
    maxIterations: 10,
  });
 
  // 6. Execute with custom Rate Limit backoff logic
  try {
    const result = await executor.invoke({ input: promptText });
    console.log("Workflow Complete:", result.output);
  } catch (error: any) {
    if (error.response && error.response.status === 429) {
      const resetTime = error.response.headers['ratelimit-reset'];
      console.warn(`Rate limited by upstream API. Must backoff until ${resetTime}`);
      // Implement your application-level backoff and queue retry here
    } else {
      console.error("Agent execution failed:", error);
    }
  }
}
 
// Trigger the workflow
runKayakoAgent(
  "Find the latest unassigned case. Search the help center for a related article, and draft a reply to the user using the MAIL channel."
);

How This Architecture Scales

By using Truto's getTools method, the agent dynamically fetches the JSON schema for every configured resource. If you modify a tool's description in the Truto UI - for example, adding a note like "Only use this tool for tier-1 support tickets" - the schema updates immediately. The next time the agent boots, it inherits the new behavioral guardrails without you changing a single line of deployment code.

This completely separates the integration logic from your agent logic. Your AI engineers focus on prompt engineering and workflow orchestration, while the integration layer handles authentication, pagination abstraction, and payload validation.

Connecting Kayako to AI agents shouldn't require reading hundreds of pages of API documentation to figure out shadow posts and predicate filtering. By leveraging a unified tool layer, you bound the LLM to deterministic, safe schemas that enforce strict input validation. This approach scales across any framework, protects your upstream API integrity, and lets your team focus on building intelligent autonomous workflows instead of fighting integration boilerplate.