Connect UserTesting to AI Agents: Sync Research & Export Highlights

You want to connect UserTesting to an AI agent so your internal systems can independently fetch studies, parse massive WebVTT session transcripts, extract QX scores, and generate automated UX research summaries based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually build custom API wrappers for complex research data.

Giving a Large Language Model (LLM) read and write access to your UserTesting instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands the deeply nested UX metrics schemas, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting UserTesting to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting UserTesting 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 UserTesting, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex UX research automation 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 UserTesting 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 an @tool decorator. In production, this approach collapses entirely, especially with an ecosystem as data-heavy as UserTesting.

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

The WebVTT Transcript Context Trap

UserTesting session transcripts are returned as raw WebVTT formatted text files, complete with timestamped cue entries (e.g., 00:00:00.000 --> 00:00:02.000). If you naively pass a raw 60-minute WebVTT transcript directly into an LLM context window without stripping or chunking, you will blow up your token limits or severely degrade the model's reasoning capabilities. An AI agent needs a structured tool that specifically requests transcripts and handles the pagination of results, rather than trying to digest a massive raw text blob in a single pass.

Nested QX Scores and Metric Complexities

UX research data is inherently complex. When querying a study's results, UserTesting returns highly nested data structures. A QX score isn't just a single integer. It is an array of task groups containing behavioral components, attitudinal components, usability metrics, trust metrics, appearance scores, and loyalty values. If an LLM is forced to formulate queries against these raw, un-normalized objects, hallucination rates spike. The model might invent property paths that don't exist. You need a strict, schema-enforced abstraction layer that explicitly tells the LLM exactly what arguments it can pass and exactly what JSON structure it will receive in return.

Workspace-Scoped Authentication

Unlike simpler SaaS tools where a single API key provides global access, UserTesting heavily relies on workspace-scoped UUIDs. Almost all critical operations - listing studies, retrieving session data - require a specific workspaceUuid. If you build your own connector, you have to write complex prompt instructions teaching the agent to first query for workspaces, cache the UUID, and inject it into subsequent API calls. A unified tool layer enforces this strictly via JSON Schema requirements, rejecting invalid LLM calls before they ever hit the upstream network.

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 UserTesting endpoint) look convenient but they push provider quirks into the LLM's context. A unified tool layer collapses these complexities behind a clean schema. Your agent sees deterministic functions like list_all_user_testing_studies and list_all_user_testing_session_transcripts.

This gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from stable function names. It never invents endpoint paths or query parameters.
2. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit UserTesting, so a broken tool call fails fast instead of confusing the model with an upstream HTTP 400 HTML error page.
3. Normalized Error Handling. If UserTesting throws a rate limit error, the agent receives a standardized payload it understands, rather than failing on an unhandled exception.

Fetching AI-Ready Tools via the Truto API

Truto maps UserTesting endpoints into a REST-based CRUD abstraction. Every integration has Resources (like studies or sessions) and Methods (like List, Get, Create).

Truto provides a set of tools for your LLM frameworks by offering a description and schema for all these Methods. By calling the /integrated-account/<id>/tools endpoint, Truto returns all available Proxy APIs formatted as LLM-ready tools.

Our LLM SDKs (like truto-langchainjs-toolset) use this endpoint to register tools natively in your framework. You don't have to write individual Zod schemas for every UserTesting feature.

Hero Tools for UserTesting AI Agents

Instead of exposing the entire UserTesting API to your agent at once - which consumes unnecessary context tokens - you should provide targeted tools based on the persona the agent is adopting. Here are the highest-leverage tools available for UserTesting automation.

List All Studies

Tool Name: list_all_user_testing_studies

This tool allows the agent to retrieve a list of all active studies within a specific workspace. It requires the workspaceUuid and returns high-level metadata needed to drill down into specific sessions.

"Find all the recent unmoderated mobile testing studies we ran in the core product workspace and list their titles."

Get Single Study Details

Tool Name: get_single_user_testing_study_by_id

Once an agent identifies a study, it needs context. This tool returns the full study object, including the session count, the exact test plan, the tasks assigned to participants, and the aggregate Net Promoter Scores (NPS) broken down into detractor, passive, and promoter percentages.

"Retrieve the full test plan and the overall NPS score breakdown for the checkout flow study ID 12345."

List Session Results

Tool Name: list_all_user_testing_session_results

Studies contain multiple sessions (individual participants taking the test). This tool returns the summary for all sessions within a specific test, returning the sessionId, status, and duration timestamps.

"Get the list of all completed session results for test ID 9876, and tell me how many sessions lasted longer than 15 minutes."

Retrieve Session Transcripts

Tool Name: list_all_user_testing_session_transcripts

This is the most critical tool for automated research analysis. It retrieves the full video transcript for a specific UserTesting session in WebVTT format. The agent can use this text to extract quotes, summarize pain points, or generate structured bug reports.

"Fetch the transcript for session ID 5555. Summarize the participant's reaction when they tried to find the pricing page, and extract any direct quotes where they expressed confusion."

Fetch QX Scores

Tool Name: list_all_user_testing_test_qx_scores

For quantitative analysis, this tool fetches the QXscore results for an interaction test. It returns granular metrics across task groups, breaking down behavioral and attitudinal components, as well as specific values for usability, trust, and appearance.

"Pull the QX scores for our latest onboarding test. Compare the trust and usability metrics between task group A and task group B."

Get Highlight Reels

Tool Name: get_single_user_testing_test_highlight_reel_by_id

When a researcher compiles clips into a highlight reel, this tool allows the agent to programmatically fetch the secure download link and metadata for that reel, making it easy to distribute insights to stakeholders via Slack or Jira.

"Get the download link for the highlight reel ID 444 from test ID 9876 so I can attach it to our product roadmap document."

To view the complete inventory of available methods, schemas, and required parameters, visit the UserTesting integration page.

Building Multi-Step Workflows

To build a resilient agent, you need an execution loop that can fetch these tools, pass them to the LLM, and execute the underlying API calls when the LLM requests them.

Here is how you initialize the TrutoToolManager from the truto-langchainjs-toolset, bind the tools to an LLM, and execute a multi-step research workflow.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
 
// 1. Initialize the Truto Tool Manager with your UserTesting Integrated Account ID
const toolManager = new TrutoToolManager({
  trutoApiKey: process.env.TRUTO_API_KEY,
  integratedAccountId: "your-usertesting-account-id",
});
 
async function runResearchAgent() {
  // 2. Fetch UserTesting tools dynamically via the Truto API
  const tools = await toolManager.getTools();
  
  // 3. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Define the agent prompt
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an expert UX research assistant. Use the provided tools to extract UserTesting data, parse transcripts, and summarize findings. Always ask for clarification if a workspace UUID or test ID is missing."],
    ["human", "{input}"],
    new MessagesPlaceholder("agent_scratchpad"),
  ]);
 
  // 5. Bind tools and create the executor
  const agent = await createOpenAIFunctionsAgent({
    llm,
    tools,
    prompt,
  });
 
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 10,
    tools,
  });
 
  // 6. Execute the workflow
  const result = await agentExecutor.invoke({
    input: "Find the study ID 102938. Fetch the QX scores for it, and then retrieve the transcript for session ID 555444. Summarize what the user struggled with during the checkout task."
  });
 
  console.log(result.output);
}
 
runResearchAgent();

Handling API Rate Limits in the Agent Loop

When building autonomous agents that scrape through dozens of transcripts, you will hit upstream API rate limits.

It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. If the upstream UserTesting API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to your caller.

Truto normalizes the upstream rate limit information into standardized IETF headers:

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

Your agent execution loop is entirely responsible for catching the HTTP 429 response, reading the ratelimit-reset header, and pausing execution or alerting the user. If you blindly retry without checking these headers, your agent will burn through its context tokens reading error messages and ultimately fail the run.

Here is how the architecture flows during a multi-step agent execution involving rate limits:

sequenceDiagram
    participant AgentEngine as Agent Engine
    participant Truto as Truto API
    participant UT as UserTesting API

    AgentEngine ->> Truto: Tool Call (list_all_user_testing_session_transcripts)
    Truto ->> UT: GET /v1/sessions/555/transcript
    UT -->> Truto: HTTP 429 Too Many Requests
    Truto -->> AgentEngine: HTTP 429 (Headers: ratelimit-reset)
    Note over AgentEngine: Agent catches 429 error<br>Reads ratelimit-reset header<br>Pauses execution
    AgentEngine ->> Truto: Retry Tool Call after delay
    Truto ->> UT: GET /v1/sessions/555/transcript
    UT -->> Truto: HTTP 200 OK (WebVTT payload)
    Truto -->> AgentEngine: Standardized JSON Response

Workflows in Action

Providing individual tools to an LLM is only the foundation. The real value is unlocked when the agent chains these tools together to execute multi-step research workflows autonomously.

Here are three concrete examples of how product and research teams are using this integration in production.

1. Auto-Summarizing Detractor Sessions

UX Researchers spend hours watching session videos to understand why a product's NPS score dropped. An agent can automate the heavy lifting of identifying and summarizing the exact moments of friction.

"Find the Q3 Onboarding Study. Look at the NPS breakdown. For any session that resulted in a detractor score, pull the transcript and summarize the specific usability issues the participant encountered during the account creation step."

Step-by-step execution:

1. Agent calls get_single_user_testing_study_by_id to retrieve the study data and NPS breakdown.
2. Agent calls list_all_user_testing_session_results to find the specific sessions.
3. Agent filters for detractor sessions and calls list_all_user_testing_session_transcripts for each.
4. Agent reads the WebVTT files, synthesizes the text, and outputs a formatted Markdown report of the usability friction points.

2. Aggregating QX Scores for Product QBRs

Product Managers need hard data for Quarterly Business Reviews. Pulling QX scores across multiple tests manually is tedious.

"Retrieve the QX scores for all studies in the 'Mobile App Redesign' workspace. Build a table comparing the behavioral and attitudinal components across the different tests."

Step-by-step execution:

1. Agent calls list_all_user_testing_studies using the provided workspace UUID.
2. For each study returned, the agent calls list_all_user_testing_test_qx_scores.
3. The agent parses the nested JSON (extracting trust, appearance, and usability metrics) and formats the structured data into a comparative table.

3. Extracting Positive Testimonial Clips

Marketing teams frequently need soundbites for promotional material, but finding them requires digging through hours of footage.

"Review the transcripts for the 'New Feature Beta' study. Find three instances where the user explicitly praised the speed of the new UI. Get the video download URLs for those specific sessions so I can clip them."

Step-by-step execution:

1. Agent calls list_all_user_testing_session_results to get the session IDs for the beta study.
2. Agent calls list_all_user_testing_session_transcripts to fetch the text.
3. The LLM analyzes the transcripts for positive sentiment regarding UI speed.
4. Agent calls list_all_user_testing_session_video_download_urls for the sessions containing the positive quotes, returning the pre-signed videoUrl links to the user.

Escaping the SaaS Integration Bottleneck

If you want your AI agents to be truly useful, they need real-time access to the systems where your business actually works. UserTesting is a massive repository of qualitative and quantitative human insight. Locking that data behind a manual API integration roadmap starves your AI initiatives of context.

By leveraging Truto's /tools endpoint, you bypass the boilerplate of OAuth token management, pagination, and custom schema mapping. You give your agent deterministic, type-safe functions that map directly to UserTesting's data model, allowing you to focus on writing better agent logic instead of debugging API connectivity.