Connect Totango to AI Agents: Manage Usage Data and System Users

You want to connect Totango to an AI agent so your system can independently read account health, sync usage events, provision SCIM users, and generate objectives based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom Customer Success integration from scratch.

Giving a Large Language Model (LLM) read and write access to your Totango instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Totango to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Totango 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 Totango, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex customer success operations. For a broader look at this architectural design pattern, read our research on Architecting AI Agents: LangGraph, LangChain, and the SaaS Integration Bottleneck.

The Engineering Reality of the Totango API

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 an @tool decorator. In production against complex Customer Success platforms, this approach collapses quickly.

Totango's API introduces several specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

Irreversible Bulk Ingestion

Unlike standard CRUD APIs where a single record creation can often be rolled back or deleted, Totango heavily relies on bulk ingestion endpoints for core metrics. Endpoints like update_a_totango_usage_by_id or account updates accept batches of up to 1,000 records. Crucially, once these updates are received and accepted, they are entirely irreversible.

If your AI agent hallucinates an array of usage payloads or modifies critical account tags by mistake, you cannot simply issue a DELETE request to undo the damage. The LLM must be strictly constrained by accurate JSON schemas and deterministic tool boundaries to prevent catastrophic data corruption.

Asynchronous Processing and Status Polling

When you push data to Totango's attribute or collection endpoints, the API does not execute the change synchronously. Instead, it returns a 202 Accepted status with a batch_id. The data is ingested asynchronously.

Standard LLM tool calling assumes synchronous execution - the tool runs, the data is updated, and the LLM proceeds. With Totango, the agent must be trained (or the tool wrapper must handle) the concept of polling. The agent fires the update tool, receives a batch_id, and must then use the get_single_totango_status_by_id tool to check if the percentComplete is 100 before making subsequent decisions based on that data.

Segment-Style Search Envelopes

Searching for accounts or users in Totango is not a matter of passing simple query parameters like ?name=Acme. Totango requires a highly specific, nested JSON envelope defining segment-style filter criteria, terms, and selected fields.

If an agent is left to figure out this query DSL (Domain Specific Language) on its own via raw API access, it will hallucinate invalid JSON structures or unsupported query operators. A proxy tool layer is mandatory to enforce the schema boundaries before the request ever reaches Totango.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, you must decide what layer your agent talks to. Direct API tools (one tool per raw Totango endpoint) look convenient, but they push provider quirks directly into the LLM's context window.

Truto operates as a proxy architecture. Every integration in Truto defines Resources and Methods that map to the underlying product's API. Truto handles the pagination, authentication, and query parameter processing, returning Proxy APIs that accept and return data in a predefined, reliable format.

We provide a set of tools for your LLM frameworks by offering descriptions and schemas for all these methods. By calling the GET /integrated-account/<id>/tools endpoint, your system retrieves a list of AI-ready tools that map perfectly to the underlying integration. The model chooses from concrete function names with strict JSON schemas, providing massive safety benefits:

1. Smaller attack surface. The LLM only chooses from stable function names and predictable schemas, rather than inventing Totango search query syntax on the fly.
2. Deterministic input validation. Invalid arguments are rejected locally before they consume network bandwidth or corrupt remote data.
3. Decoupled authentication. The agent knows nothing about Totango API tokens or SCIM service IDs. It just executes tools.

Hero Tools for Totango AI Agents

When you call the Truto /tools endpoint for a connected Totango account, you receive a comprehensive array of available functions. To build an effective Customer Success agent, you should focus on the highest-leverage operations. Here are the core hero tools you will use to manage usage data, accounts, and system users.

totango_accounts_search

This tool allows the agent to search Totango accounts matching specific filter criteria. Because Totango uses a complex segment-style query structure, this tool's strict schema ensures the agent only requests fields and terms that actually exist.

Contextual usage notes: The tool returns a response envelope containing total_hits and an array of hits. Pagination is handled via offset. Limit queries to 1,000 results per page.

"Find all enterprise tier accounts where the health score dropped below 50 in the last 7 days and return their account IDs and display names."

update_a_totango_usage_by_id

This is the primary pipeline for injecting product telemetry into Totango. It accepts a batch of up to 1,000 usage updates per request.

Contextual usage notes: Updates are irreversible once received. Do not allow the agent to guess usage metrics; ensure this tool is invoked downstream of an accurate data retrieval step (e.g., querying your internal database or a data warehouse).

"Submit a batch usage update for account ID 98765, recording 450 API calls made by user jdoe@example.com over the last 24 hours."

create_a_totango_task

Agents are highly effective at identifying risk, but human intervention is often required. This tool creates a task in Totango, assigning it to the relevant Customer Success Manager (CSM).

Contextual usage notes: You must provide the activity_type_id. Attempting to create a task for an unknown account_id will result in a hard 400 error.

"Create an urgent task for the CSM assigned to account ID 12345 to schedule a churn-risk intervention call by Friday."

update_a_totango_account_by_id

This tool is used to upsert Totango accounts in batch, modifying their core attributes, health tags, or lifecycle stages.

Contextual usage notes: Like usage updates, accepted updates cannot be undone. Always verify the current state of the account using totango_accounts_search before instructing the agent to overwrite attributes.

"Update the lifecycle stage of account ID 55544 to 'Onboarding Risk' and append the tag 'Executive_Escalation'."

totango_events_search

To give your agent historical context before it interacts with a customer, it needs to read past touchpoints, notes, and alerts. This tool searches the event timeline.

Contextual usage notes: Returns a status envelope with matching events up to 1,000 per call. It is excellent for retrieving meeting notes or past support escalations.

"Retrieve the last 5 touchpoint notes and campaign events for account ID 99887 to summarize their recent onboarding experience."

create_a_totango_scim_user

Beyond managing customer data, IT and RevOps teams need to manage the Totango instance itself. This tool provisions a new Totango system user via the SCIM API.

Contextual usage notes: Requires the service_id, an email address (max 100 characters) for userName, and given/family names.

"Provision a new Totango system user seat for sarah.connors@ourcompany.com in the Customer Success department."

For the complete inventory of available Totango tools, schemas, and required parameters, visit the Totango integration page.

Workflows in Action

To understand how these tools fit together, let us look at two concrete scenarios where an AI agent orchestrates multi-step processes inside Totango.

Scenario 1: Automated Churn Risk Remediation

Customer Success Operations teams spend hours hunting for accounts exhibiting poor telemetry and manually flagging them for intervention. An agent can automate this loop entirely.

"Scan our Totango instance for any 'Pro Tier' accounts with a health score in the red zone. For each account, review their last 3 touchpoint notes. If there has been no communication in 14 days, create a high-priority task for their CSM to reach out."

Agent Execution Steps:

1. The agent calls totango_accounts_search using terms that filter for Pro Tier and Red health status.
2. For each returned account_id, the agent loops and calls totango_events_search to fetch recent touchpoints.
3. The agent's internal reasoning evaluates the timestamps of the returned events.
4. If the 14-day criteria is met, the agent calls create_a_totango_task to assign an intervention task to the account owner.

Result: The LLM returns a summarized list of accounts it processed and confirms the exact task IDs it generated for the CS team.

Scenario 2: IT Onboarding via SCIM

When a new employee joins the RevOps or CS team, IT must grant them access to various systems. The agent can bridge the gap between an IT ticketing system and Totango's SCIM endpoints.

"We have a new hire, Marcus Vance. Provision him a Totango user seat using his email marcus.vance@company.com and add him to the 'Enterprise Support' SCIM group."

Agent Execution Steps:

1. The agent calls create_a_totango_scim_user passing the required name and email payload, returning a new id.
2. The agent calls list_all_totango_scim_groups to find the exact group_id for 'Enterprise Support'.
3. The agent calls update_a_totango_scim_group_by_id, appending Marcus's new user id via a SCIM PatchOp operation.

Result: The agent replies confirming that Marcus has been provisioned and successfully mapped to the correct permissions group.

Building Multi-Step Workflows

To put this into production, you need to write the scaffolding that binds Truto's proxy tools to your agent framework. The code below demonstrates how to achieve this using standard frameworks like LangChain, though the pattern applies identically to Vercel AI SDK or CrewAI.

The Architecture of the Tool Loop

When building an agentic loop, the architecture follows a distinct path. The application layer fetches the tool schemas from Truto, binds them to the LLM, and enters an evaluation loop.

flowchart TD
    User["User Prompt"] --> Agent["Agent Framework<br>(LangChain/LangGraph)"]
    
    subgraph Tooling Layer
        Agent -->|1. Request Tool Schemas| TrutoAPI["Truto /tools Endpoint"]
        TrutoAPI -->|2. Return JSON Schemas| Agent
    end

    subgraph Execution Loop
        Agent -->|3. Evaluate & Decide Function| LLM["Large Language Model"]
        LLM -->|4. Return Tool Call| Agent
        Agent -->|5. Execute Proxy API| TrutoProxy["Truto Proxy API"]
        TrutoProxy -->|6. Pass through to Vendor| Totango["Totango API"]
        Totango -->|7. Return Raw Data| TrutoProxy
        TrutoProxy -->|8. Return to Agent Context| Agent
    end
    
    Agent -->|9. Final Response| User

Handling Rate Limits and the IETF Spec

Before we look at the code, we must address the reality of network constraints. Totango enforces API rate limits to protect its infrastructure.

It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When Totango returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the caller.

However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. It is entirely the responsibility of your agent's execution loop to catch HTTP 429 errors, read the ratelimit-reset header, and apply a backoff strategy before re-prompting the LLM or re-executing the tool.

Implementation Code

Using the truto-langchainjs-toolset, you can instantiate a tool manager that handles fetching the schemas and executing the underlying proxy methods.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { HumanMessage } from "@langchain/core/messages";
 
async function runTotangoAgent() {
  // 1. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 2. Initialize the Truto Tool Manager for the Totango Integrated Account
  // Requires TRUTO_API_KEY environment variable
  const toolManager = new TrutoToolManager({
    integratedAccountId: "your-totango-integrated-account-id",
  });
 
  // 3. Fetch all AI-ready tools from Truto's Proxy API layer
  console.log("Fetching Totango tools from Truto...");
  const tools = await toolManager.getTools();
  
  // 4. Bind the strict JSON schemas to the LLM
  const llmWithTools = llm.bindTools(tools);
 
  // 5. Provide the prompt to the agent
  const messages = [
    new HumanMessage(
      "Find all accounts with a health score below 40 and create a task for the CSM to intervene."
    )
  ];
 
  // 6. Execute the Agent Loop with defensive rate limit handling
  let keepRunning = true;
  
  while (keepRunning) {
    const response = await llmWithTools.invoke(messages);
    messages.push(response);
 
    if (response.tool_calls && response.tool_calls.length > 0) {
      for (const toolCall of response.tool_calls) {
        console.log(`Executing tool: ${toolCall.name}`);
        
        try {
          // Locate and execute the tool dynamically
          const tool = tools.find((t) => t.name === toolCall.name);
          if (tool) {
            const toolResult = await tool.invoke(toolCall.args);
            messages.push({
              role: "tool",
              name: toolCall.name,
              tool_call_id: toolCall.id,
              content: JSON.stringify(toolResult),
            });
          }
        } catch (error: any) {
          // Defensive handling for HTTP 429 Rate Limits
          if (error.status === 429) {
            const resetTime = error.headers['ratelimit-reset'];
            console.warn(`Rate limit hit. Must backoff until timestamp: ${resetTime}`);
            // Implement your backoff/retry logic here based on the IETF headers
            throw new Error("Agent execution paused due to upstream rate limit.");
          }
          console.error(`Tool execution failed:`, error.message);
          throw error;
        }
      }
    } else {
      // The LLM has finished its reasoning loop
      console.log("Agent Final Response:", response.content);
      keepRunning = false;
    }
  }
}
 
runTotangoAgent().catch(console.error);

This architecture keeps your integration code minimal. The LLM handles the orchestration, Truto handles the schema parsing, auth, and pagination via the /tools endpoint, and you only maintain the logic for handling network realities like rate limiting.

Moving from Script to Production Workflows

Building an AI agent that can reliably parse customer usage data and modify CS records requires structural discipline. If you attempt to wire raw Totango endpoints directly into an LLM, you will spend your development cycles managing authentication drift, writing defensive JSON schema validators, and wrestling with segment-style query formats.

By leveraging Truto's Proxy APIs via the /tools endpoint, you abstract away the SaaS integration bottleneck. Your agent framework simply ingests clean, deterministic schemas, allowing your engineering team to focus entirely on improving the LLM's reasoning and workflow architecture.