Connect Dixa to AI Agents: Automate Custom Attribute Discovery

Customer service platforms run on metadata. In Dixa, custom attributes dictate how conversations are routed, how user profiles are enriched, and how SLAs are enforced. If you want to connect Dixa to AI Agents to automate support operations, your agents need programmatic access to these schema definitions.

This article is part of a larger series on Dixa automation. If your team uses ChatGPT, check out our guide on connecting Dixa to ChatGPT. For Anthropic-heavy environments, see our companion walkthrough on connecting Dixa to Claude.

In this technical guide, we will focus on building framework-agnostic AI agent workflows using Truto's /tools endpoint. We will cover the quirks of the Dixa API, examine the specific tool schemas you need, and write the execution logic required to make an LLM traverse Dixa's attribute graph autonomously.

Engineering Reality: Navigating the Dixa API

When you connect Dixa to AI Agents, you are not just passing authentication tokens. You are asking an LLM to navigate a highly specific, opinionated data model. Dixa's API has a few distinct characteristics that engineers must account for when designing tool-calling workflows.

First is the concept of Entity Type Ambiguity. In Dixa, a "custom attribute" does not just apply to a generic ticket. Attributes are strictly mapped to an entityType, which can be a conversation, a user profile, or an organization. When an agent queries the API for attributes, it receives a flattened list. Your agent prompt and system instructions must explicitly tell the LLM to inspect the entityType field before attempting to apply an attribute, otherwise the LLM will hallucinate invalid API requests downstream.

Second is the Nested Input Definition Schema. Dixa attributes are not just key-value pairs. They contain complex validation rules stored in the inputDefinition field. An attribute might require a specific regex, dictate a dropdown list of exact string values, or enforce a boolean state. The LLM must be given the capability to read these nested definitions before attempting any write operations in a broader workflow.

Finally, and most importantly, are Strict Rate Limits. Dixa aggressively throttles API traffic to protect platform stability. When building agents, it is critical to understand how Truto handles these limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Dixa API returns an HTTP 429, Truto passes that error directly to the caller.

Truto does, however, normalize the upstream rate limit information into standardized headers per the IETF specification. Every response will include:

• ratelimit-limit: The maximum number of requests permitted in the current window.
• ratelimit-remaining: The number of requests remaining in the current window.
• ratelimit-reset: The time at which the current rate limit window resets.

The caller - your application code managing the agent loop - is entirely responsible for reading these headers and implementing the appropriate retry and exponential backoff logic.

Dixa Tool Inventory

Truto maps Dixa's endpoints into standardized Resources and Methods, converting them into Proxy APIs. These are then exposed as schema-defined tools (much like building MCP servers) ready for LLM consumption.

Below are the primary tools required for automating custom attribute discovery.

Hero Tools

list_all_dixa_custom_attributes

This tool retrieves the complete catalog of custom attributes defined in the Dixa workspace. It returns an array of objects detailing the schema, state, and requirements of each attribute.

• Contextual Usage Notes: This is the primary discovery endpoint. Agents should use this tool when asked to audit schemas, find available fields for a specific entity, or identify stale data configurations. Because it returns a broad dataset, the LLM will naturally filter the resulting JSON array based on the user's prompt.
• Example Prompt: "Audit our Dixa workspace and list all custom attributes associated with the 'conversation' entity type that are marked as required."
• Key Return Fields: id, entityType, identifier, label, inputDefinition, description, createdAt, updatedAt, isRequired, isArchived, isDeactivated.

get_single_dixa_custom_attribute_by_id

This tool retrieves the precise definition of a specific custom attribute using its unique identifier.

• Contextual Usage Notes: When an agent needs to deeply understand the validation rules of a specific field (for instance, reading the inputDefinition to see allowed dropdown values before submitting a ticket update in a separate step), it will call this tool. It is highly effective in multi-step chains where step one is discovery and step two is deep inspection.
• Example Prompt: "Get the full schema definition for the custom attribute with ID 'attr_987654321', and tell me what the allowed input values are."
• Key Return Fields: id, entityType, identifier, label, inputDefinition, description, createdAt, updatedAt, isRequired, isArchived, isDeactivated.

Full Inventory

Here is the complete inventory of additional Dixa tools available. For full schema details, visit the Dixa integration page.

• list_all_dixa_custom_attributes: List all custom attributes in Dixa.
• get_single_dixa_custom_attribute_by_id: Get custom attribute by id in Dixa.

(Note: The custom attribute metadata API surface in Dixa is highly consolidated, meaning these two endpoints provide 100% coverage for schema discovery tasks.)

Workflows in Action

To understand how these tools behave in a production setting, let us look at specific, persona-driven workflows. When you connect Dixa to AI agents, the goal is autonomous problem-solving.

Workflow 1: The CS Ops Audit

Customer Support Operations managers frequently need to clean up CRM and helpdesk schemas to prevent agent confusion.

"Find all custom attributes in our Dixa account that are currently archived or deactivated, and group them by their original entity types (e.g., user vs conversation)."

Agent Execution Steps:

1. The agent calls list_all_dixa_custom_attributes without parameters to fetch the entire schema payload.
2. The LLM receives the JSON array and iterates through the records.
3. The LLM filters the array, isolating objects where isArchived: true or isDeactivated: true.
4. The LLM groups the filtered results by the entityType field.
5. The LLM formats the output into a readable markdown summary for the user.

What the user gets back: A clean, categorized list showing exactly which Dixa metadata fields are obsolete, saving the CS Admin hours of clicking through the Dixa settings UI.

Workflow 2: The Data Engineer's Schema Sync

Data engineers building ETL pipelines need to know exactly how data is structured in the upstream SaaS application to ensure their data warehouse tables match.

"Get the exact schema definition for the Dixa attribute ID 'attr_555444', specifically detailing its required status and breaking down its input definition so I can map it to Postgres."

Agent Execution Steps:

1. The agent parses the prompt and extracts the ID 'attr_555444'.
2. The agent calls get_single_dixa_custom_attribute_by_id, passing the extracted ID as the argument.
3. The Truto Proxy API returns the specific JSON object for that attribute.
4. The LLM reads the isRequired boolean and deeply analyzes the inputDefinition object to understand if the field is a string, a boolean, or an array of specific ENUM values.
5. The agent generates a response translating the Dixa definition into a Postgres-compatible schema recommendation.

What the user gets back: A highly technical breakdown of the attribute's constraints, eliminating guesswork for database mapping.

Building Multi-Step Workflows

Connecting Dixa to AI agents requires an orchestrator. While Truto provides the abstraction layer that maps the API endpoints into LLM-friendly schemas, you need a framework to manage the execution loop. Because Truto's /tools endpoint relies on standard REST architecture, it works universally across LangChain, Vercel AI SDK, CrewAI, or even custom implementations.

Fetching the Tools

When a user connects their Dixa account via Truto, an integrated account ID is generated. You use this ID to fetch the available tools dynamically.

curl -X GET "https://api.truto.one/integrated-account/<dixa_account_id>/tools" \
  -H "Authorization: Bearer <YOUR_TRUTO_API_KEY>"

The response contains a list of Proxy APIs formatted as JSON schemas, explicitly declaring the descriptions, query parameters, and expected payload structures for the LLM.

Binding Tools to the Agent (LangChain Example)

If you are using Node.js, the truto-langchainjs-toolset makes binding these tools trivial. You instantiate the manager, fetch the tools, and bind them to your model.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runDixaAgent(prompt: string, dixaAccountId: string) {
  const llm = new ChatOpenAI({ modelName: "gpt-4o", temperature: 0 });
  
  // Initialize Truto Tool Manager with your Truto API key
  const toolManager = new TrutoToolManager(process.env.TRUTO_API_KEY);
  
  // Fetch Dixa tools specific to the connected account
  const tools = await toolManager.getTools(dixaAccountId);
  
  // Bind the tools to the LLM
  const llmWithTools = llm.bindTools(tools);
  
  // Execute the agent
  const response = await llmWithTools.invoke(prompt);
  
  console.log("Agent decision:", response.tool_calls);
  return response;
}

Handling Rate Limits in the Execution Loop

As mentioned in the Engineering Reality section, Dixa's rate limits must be respected, and Truto expects the caller to handle the fallback. When executing multi-step chains (e.g., an agent calling list_all_dixa_custom_attributes and then looping through 50 IDs by calling get_single_dixa_custom_attribute_by_id in sequence), you will likely hit an HTTP 429.

Your tool executor must catch this error, read the ratelimit-reset header, and pause execution.

// Conceptual error handling wrapper for tool execution
async function executeToolSafely(toolCall) {
  try {
    return await executeTool(toolCall);
  } catch (error) {
    if (error.status === 429) {
      const resetTime = parseInt(error.headers['ratelimit-reset'], 10);
      const sleepDuration = (resetTime * 1000) - Date.now();
      
      console.warn(`Rate limit hit. Sleeping for ${sleepDuration}ms...`);
      await new Promise(resolve => setTimeout(resolve, sleepDuration));
      
      // Retry after backoff
      return await executeTool(toolCall);
    }
    throw error;
  }
}

By managing state and explicitly handling rate limits at the application layer, your agent can traverse the Dixa API reliably without crashing mid-thought.

Connecting Dixa to AI agents changes the paradigm of support operations. Instead of writing custom scripts to audit metadata or sync schemas, you can grant an LLM secure, rate-limit-aware access to the Dixa API and let it solve problems dynamically. By leveraging Truto's /tools endpoint, you bypass the boilerplate of authentication, pagination, and schema mapping - letting your engineers focus entirely on prompt engineering and agent logic.