Connect Chameleon to AI Agents: Automate User Events and Deliveries

You want to connect Chameleon to an AI agent so your system can autonomously analyze user onboarding journeys, trigger targeted experiences, and react to microsurvey responses 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 Chameleon integration from scratch.

Giving a Large Language Model (LLM) read and write access to your product adoption platform is a massive engineering undertaking. You either spend weeks building, hosting, and maintaining a custom connector, dealing with complex segmentation filters and rate limits, or you use a managed infrastructure layer that handles the boilerplate for you. If your team relies on ChatGPT, check out our guide on connecting Chameleon to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Chameleon 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 Chameleon, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex product adoption 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 the Chameleon API

Giving an LLM access to external data sounds simple when you are prototyping. You write a Node.js function that makes a fetch request, wrap it in an @tool decorator, and move on. In production against complex product adoption platforms like Chameleon, this approach quickly collapses.

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 Chameleon API introduces several specific integration challenges that break standard REST assumptions.

The Segmentation Filter DSL Trap

Standard LLMs are trained to expect flat, intuitive JSON objects or simple URL query strings for searching (e.g., ?role=admin&plan=pro). Chameleon does not work this way. To query users or companies, Chameleon relies heavily on a complex Segmentation Filter expression language.

When an agent wants to find users who answered a microsurvey with a specific score or completed a specific tour, it must construct heavily nested JSON payloads defining property types, operators, and boolean logic groupings. Pushing this requirement into the LLM's context window is a hallucination waiting to happen. The model will invent operators or misplace nested arrays. By using a unified tool layer, the LLM interacts with a strict, stable JSON schema that validates the filter structure before it ever hits the Chameleon API.

Polymorphic Identifiers and Identity Resolution

Chameleon tracks users across multiple identifier types: Chameleon's internal id, your application's uid, and the user's email. Certain endpoints strictly require the Chameleon id, while others allow a lookup via your uid.

If you expose raw endpoints to an LLM, the model must constantly remember which identifier is valid for which endpoint. It might attempt to delete a user profile by passing an email address to an endpoint that strictly requires a 24-character hex string. Truto's proxy tool layer abstracts this by providing deterministic, strongly-typed tool schemas. The agent sees clear distinctions between chameleon_profiles_get_id and chameleon_profiles_get_number (lookup by your uid), reducing the cognitive load on the LLM.

The Reality of Rate Limits and State Management

When building autonomous agents, rate limits are not just an operational annoyance - they dictate your state management architecture. Chameleon enforces rate limits on API requests, and when your agent iterates over thousands of profiles to trigger deliveries, it will hit them.

Truto does not magically retry, throttle, or apply arbitrary backoff on rate limit errors for you. Masking a 429 error behind a silent retry queue is dangerous for agentic workflows because the LLM loses its temporal context. Instead, when the upstream Chameleon API returns an HTTP 429, Truto passes that error directly to the caller.

However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). This means your agent framework code only ever needs to parse one standard set of headers to handle backoff, regardless of whether it is talking to Chameleon, HubSpot, or Jira.

Hero Tools for Chameleon AI Agents

To build effective AI agents for Chameleon, you do not need to expose all 80+ endpoints. You need a curated set of high-leverage operations. Below are the hero tools you should equip your agent with to orchestrate product adoption workflows.

Search User Profiles (chameleon_profiles_search)

This tool allows the agent to search user profiles using Segmentation filter expressions. It is critical for finding cohorts of users based on properties, experience interactions (like exiting a tour early), or tracked events.

"Find all user profiles on the 'Enterprise' plan who have a 'last_seen_at' date within the last 7 days and exited the 'New Dashboard UI' tour before completing it. Return their Chameleon IDs and emails."

List Tour Interactions (list_all_chameleon_tour_interactions)

This tool retrieves the raw interaction data for a specific tour, allowing the agent to audit exactly how users are navigating multi-step product tours. It returns states like started, displayed, completed, or exited.

"Pull the interaction history for the tour ID '64b5a2...'. I need to calculate the drop-off rate between step 2 and step 3 for the current month."

List Survey Responses (list_all_chameleon_survey_responses)

Microsurveys are goldmines for agentic analysis. This tool fetches the responses for a given survey, including the button clicked, free-text input, dropdown selections, and the associated user profile.

"Fetch all recent responses for the 'Q3 NPS Survey'. Identify any users who gave a score of 6 or lower and extract their free-text comments so we can analyze the negative sentiment."

Create a Delivery (create_a_chameleon_delivery)

This is the primary action tool for proactive agents. It creates a Delivery to directly trigger an Experience (like a tour or microsurvey) for one specific user, bypassing normal segmentation rules.

"Create a delivery to trigger the 'Account Recovery Walkthrough' tour for the user profile ID '5f8d1...'. Set the delivery window to start immediately."

Delete / Reset User Profile (chameleon_profiles_delete_number)

When testing experiences or resetting stuck users, this tool clears a user profile identified by your application's uid. It resets activity properties and reverts experience counts, allowing the user to see onboarding tours again.

"The QA engineer with UID 'usr_99812' needs to re-test the onboarding flow. Reset their Chameleon profile activity so the initial tours will trigger for them again on their next login."

List Experiences in a Segment (chameleon_segments_list_experiences)

This tool lists the experiences attached to a specific audience segment. It is useful for auditing what active tours or launchers are currently targeting a specific cohort of users.

"List all the active microsurveys currently attached to the 'At-Risk Churn' segment. I need to verify we aren't overwhelming these users with too many pop-ups."

For the complete tool inventory and detailed JSON schema definitions, view the Chameleon integration page.

Workflows in Action

Exposing these tools to an LLM allows you to chain them together to solve complex, multi-step revenue operations and product growth problems. Here are concrete examples of how these workflows operate in production.

Scenario 1: Autonomous Churn Risk Mitigation

Customer Success teams often struggle to manually track product usage drops and intervene before a renewal. An agent can automate the discovery and intervention process.

"Analyze yesterday's responses to the 'Quarterly Health Check' survey. If any Enterprise user submitted a score of 4 or below, find their profile, and immediately trigger the 'Executive Sponsor Check-in' microsurvey to their account dashboard."

Execution Steps:

1. The agent calls list_all_chameleon_survey_responses with the ID for the 'Quarterly Health Check' survey.
2. The LLM evaluates the JSON response, filtering for scores <= 4.
3. For a matching response, the agent extracts the profile_id.
4. The agent calls chameleon_profiles_get_id to verify the user's company_id and custom properties (checking if they are an Enterprise tier).
5. If they match the criteria, the agent calls create_a_chameleon_delivery, passing the profile_id and the model_id of the 'Executive Sponsor Check-in' survey.

Output: The agent successfully identifies an at-risk VIP user and programmatically guarantees they receive a highly targeted retention intervention the next time they log in, without manual CS overhead.

Scenario 2: QA and Onboarding Reset Loop

Product and QA teams constantly need to re-test onboarding flows. Manually navigating dashboards to clear user states slows down development.

"My internal test user 'qa_tester_01' is stuck on step 4 of the new billing tour. Reset their Chameleon profile completely, and verify what active tours are currently attached to the 'Internal QA' segment so I know what they will see next."

Execution Steps:

1. The agent calls chameleon_profiles_delete_number, passing uid: 'qa_tester_01' to clear the user's event history and tour completion states.
2. The agent searches for the segment ID using a list tool, or if the ID is known in context, proceeds to the next step.
3. The agent calls chameleon_segments_list_experiences using the ID for the 'Internal QA' segment.
4. The LLM formats the resulting list of tours and launchers into a clean summary.

Output: The agent clears the tester's state instantly and replies with a markdown list of exactly which tours are primed to trigger on their next page load.

Building Multi-Step Workflows

To build these agents, you need a robust loop that handles tool binding, execution, and rate limiting. Because Truto standardizes all Chameleon endpoints into LLM-ready schemas, you can bind them directly to models using frameworks like LangChain, Vercel AI SDK, or CrewAI.

The following architecture diagram illustrates how an agent loop interacts with Truto, specifically highlighting how rate limits are passed back and handled by the caller.

sequenceDiagram
    participant App as Your Agent App
    participant LLM as LLM (OpenAI/Anthropic)
    participant Truto as Truto Unified API
    participant Chameleon as Chameleon API

    App->>Truto: GET /integrated-account/{id}/tools
    Truto-->>App: Returns JSON Schemas for Chameleon Tools
    App->>LLM: Bind tools & send user prompt
    LLM-->>App: ToolCall(create_a_chameleon_delivery, args)
    App->>Truto: Execute tool (Proxy API)
    Truto->>Chameleon: POST /v2/deliveries
    Chameleon-->>Truto: 429 Too Many Requests
    Truto-->>App: 429 Error with IETF ratelimit headers
    Note over App: App parses ratelimit-reset<br>App pauses execution
    App->>Truto: Retry tool execution after delay
    Truto->>Chameleon: POST /v2/deliveries
    Chameleon-->>Truto: 200 OK (Delivery created)
    Truto-->>App: Tool result (Success)
    App->>LLM: Send tool result context
    LLM-->>App: Final natural language response

Implementing the Agent Loop in TypeScript

Here is how you implement this loop using the truto-langchainjs-toolset. This example demonstrates initializing the toolset, binding it to a model, and executing a multi-step query while being prepared to handle 429 errors.

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 runChameleonAgent() {
  // 1. Initialize the Truto Tool Manager for the specific integrated account
  const trutoManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: process.env.CHAMELEON_ACCOUNT_ID,
  });
 
  // 2. Fetch the dynamically generated tools for Chameleon
  // You can filter by methods like ['read', 'write', 'custom']
  const tools = await trutoManager.getTools();
  
  console.log(`Loaded ${tools.length} Chameleon tools from Truto.`);
 
  // 3. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Create the prompt template
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an expert product operations assistant. You manage Chameleon tours, surveys, and user profiles. If a tool fails due to a rate limit, inform the user you must wait before proceeding."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 5. Bind tools to the agent
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
 
  const executor = new AgentExecutor({
    agent,
    tools,
    // Ensure the executor surfaces errors cleanly so we can inspect headers if needed
    handleParsingErrors: true,
  });
 
  // 6. Execute a multi-step workflow
  const query = "Find the recent responses for survey ID 'sur_88412'. For any user who scored below a 5, create a delivery for the 'Retention Offer' tour (model_id: 'tour_55112').";
  
  console.log(`\nExecuting prompt: "${query}"`);
  
  try {
    const result = await executor.invoke({ input: query });
    console.log(`\nAgent Response:\n${result.output}`);
  } catch (error: any) {
    // 7. Handle 429 Rate Limits passed through by Truto
    if (error?.status === 429) {
      const resetTime = error.headers['ratelimit-reset'];
      console.error(`Rate limit exceeded. Chameleon API is exhausted. Wait until ${resetTime} to retry.`);
      // Implement your [application-level backoff and retry logic](/how-to-handle-long-running-saas-api-tasks-in-ai-agent-tool-calling-workflows/) here
    } else {
      console.error("An unexpected error occurred during agent execution:", error);
    }
  }
}
 
runChameleonAgent();

By leveraging the TrutoToolManager, you are completely isolated from writing HTTP clients, managing pagination cursors, or hardcoding JSON schemas for the Chameleon API. The agent can seamlessly interpret the user's intent, query the survey responses, extract the relevant profile IDs, and execute the delivery creation in a single autonomous session.

Strategic Wrap-up

Building an AI agent that can reliably automate product adoption workflows requires a solid integration foundation. If your agent is constantly fighting undocumented API quirks, failing on nested filter JSON structures, or crashing ungracefully on rate limits, it will never reach production.

Truto's unified tool layer collapses the complexity of the Chameleon API into stable, LLM-ready functions. By standardizing the schemas and normalizing the rate limit headers, you can focus on writing better prompts and designing safer agent logic, rather than maintaining point-to-point integration code. Stop writing boilerplate integration logic for your agents, and start orchestrating real business value.