Connect Tray.ai to AI Agents: Automate Auth and User Lifecycle

You want to connect Tray.ai to an AI agent so your system can autonomously provision embedded users, generate access tokens, deploy solution instances, and manage integration environments. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build a custom GraphQL integration layer from scratch.

Giving a Large Language Model (LLM) read and write access to your Tray.ai instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector to handle Tray's GraphQL 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 Tray.ai to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Tray.ai 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 Tray.ai, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex embedded integration operations. 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 Tray.ai 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 integration platforms like Tray.ai, this approach collapses quickly.

Tray.ai'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 capabilities.

The GraphQL Node and Edge Trap

Tray.ai relies heavily on a GraphQL-based architecture for its modern endpoints. Standard LLMs are trained to expect flat, intuitive JSON objects. When an agent wants to list available solutions, it naturally attempts to generate a simple REST-like request for an array of solution objects.

Instead, Tray.ai returns highly nested structures defining connections, edges, and nodes. To read a solution's configuration slots, your system must traverse data.viewer.solutions.edges [n].node.configSlots. Pushing this deeply nested graph traversal onto the LLM's context window is a guaranteed way to induce hallucinations. The model will invent missing properties or fail to navigate the edge arrays entirely.

Opaque Cursor-Based Pagination

When your agent asks to retrieve all embedded users, it expects simple integer-based pagination (e.g., page=2). Tray.ai uses opaque cursor-based pagination tied to its GraphQL connections. To fetch the next page, the agent must extract a specific pageInfo.endCursor string from the previous response and pass it identically into the next query's after parameter.

LLMs are notoriously bad at strictly preserving opaque strings across turns. If the model truncates the cursor or invents a generic string like "cursor_123", the API call fails, and the agent gets stuck in a loop.

Strict Mutation Shapes and Client IDs

When writing data - such as updating a solution instance or deleting a user - Tray.ai requires specific mutation structures and often expects a clientMutationId for tracking. If the LLM misses these wrapper objects or sends a boolean where a string enum is expected for an auth slot, the entire deployment fails. You need a layer that strictly validates input arguments against a predefined schema before the request ever touches the Tray.ai API.

Why a Unified Tool Layer Matters for Agent Safety

Direct raw API tools push provider quirks directly into the LLM's context. A unified tool layer collapses these complexities behind standard, stable JSON schemas. Your agent sees create_a_tray_ai_user and list_all_tray_ai_solutions instead of managing raw GraphQL queries and mutations.

Truto achieves this by treating every integration as a comprehensive JSON object that represents how the underlying product behaves - similar to an advanced Swagger file built for integrations. We map endpoints to Resources and define Methods (List, Get, Create, Update, Custom) on them.

These Proxy APIs handle the pagination normalization, authentication injection, and query parameter processing. They provide a strict schema for your LLM frameworks to ingest, guaranteeing that the model only sees and selects valid operations.

flowchart TD
    Agent["AI Agent Core<br>(LangChain, CrewAI)"]
    ToolsAPI["Truto /tools Endpoint<br>(Schema Provider)"]
    Proxy["Truto Proxy API<br>(Execution Layer)"]
    Tray["Tray.ai API<br>(GraphQL / REST)"]

    Agent -->|"1. Fetch schemas"| ToolsAPI
    ToolsAPI -->|"2. Returns JSON schemas"| Agent
    Agent -->|"3. LLM decides to call tool"| Proxy
    Proxy -->|"4. Handles Auth & Pagination"| Tray
    Tray -->|"5. Raw Graph/JSON response"| Proxy
    Proxy -->|"6. Clean validated JSON"| Agent

Hero Tools for Tray.ai Workflows

Truto provides a comprehensive suite of tools for Tray.ai. Rather than dumping the entire inventory into your LLM's context, you should provide only the tools necessary for the persona your agent is executing. Here are the highest-leverage hero tools for automating embedded integrations.

1. list_all_tray_ai_users

Retrieves all Tray embedded end users in your organization. This tool automatically handles the cursor-based pagination and extracts the node array into a clean list containing the user ID, name, external user ID, auth type, and test-user status.

"Find all embedded end users currently active in our organization, and identify which ones are marked as test users."

2. create_a_tray_ai_user

Provisions a new Tray Embedded end user. This is the first step in onboarding a new tenant to your embedded integrations. It requires a display name and your system's external_user_id.

"Create a new Tray.ai user for our new customer 'Acme Corp' using their external ID 'tenant_9942'."

3. tray_ai_users_create_user_token

Generates a short-lived user access token for a specific embedded end user. This token is required to initialize the Tray.ai Configuration Wizard UI in your frontend application so the user can authenticate their own third-party accounts.

"Generate a user access token for the user ID '82394-abc' so they can access the integration config wizard."

4. list_all_tray_ai_solutions

Discovers the Tray Embedded solutions available to your end users. It parses the complex GraphQL edge nodes to return clean objects containing the solution ID, title, description, and the critical configSlots and authSlots required for deployment.

"List all available integration solutions and tell me what auth slots are required to deploy the ' HubSpot to Snowflake' template."

5. create_a_tray_ai_solution_instance

Deploys a solution instance for an end user based on a published solution. This tool expects the solution ID and instance name, effectively standing up the integration infrastructure for that specific tenant.

"Create a new solution instance named 'Acme Corp Salesforce Sync' using solution ID 'sol_48291'."

6. update_a_tray_ai_solution_instance_by_id

Updates an existing solution instance. This is primarily used to toggle the enabled state of a workflow (turning the integration on or off for a customer) or renaming it.

"Disable the solution instance ID 'inst_99921' immediately because the customer's subscription has expired."

7. tray_ai_projects_export

Exports an entire Tray project as a JSON payload. This is an advanced workflow tool used for automated backups, auditing, or promoting workspaces between development and production environments.

"Export the configuration for project ID 'proj_55112' and return the JSON payload for our backup system."

For the complete tool inventory and schema definitions, visit the Tray.ai integration page.

Building Multi-Step Workflows

Building a reliable agent loop requires more than just fetching a tool schema. Your execution framework must handle tool binding, state management, and strict error handling.

We provide an SDK like the truto-langchainjs-toolset which parses Truto's /tools endpoint and registers them directly into LangChain's .bindTools() format. This works equally well if you are using Vercel AI SDK or CrewAI.

Handling Rate Limits and State

CRITICAL: Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API like Tray.ai returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller.

Truto normalizes upstream rate limit information into standardized headers per the IETF specification (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller - your agent loop or wrapper function - is strictly responsible for inspecting these headers, pausing execution, and implementing retry/backoff logic. Do not assume your infrastructure will absorb 429s automatically.

Here is how you structure a framework-agnostic agent loop using LangChain.js to handle multi-step executions safely.

import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage } from "@langchain/core/messages";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runTrayAgent(prompt: string, integratedAccountId: string) {
  // 1. Initialize the Tool Manager with your Truto API key
  const toolManager = new TrutoToolManager(process.env.TRUTO_API_KEY);
  
  // 2. Fetch the specific Tray.ai tools for this integrated account
  // We filter to only fetch user and solution instance tools to save context space
  const tools = await toolManager.getTools(integratedAccountId, {
    methods: ["read", "create", "update", "custom"]
  });
 
  // 3. Initialize the LLM and bind the strict JSON schemas
  const model = new ChatOpenAI({ modelName: "gpt-4o", temperature: 0 });
  const modelWithTools = model.bindTools(tools);
 
  // 4. Set up the conversation state
  const messages = [new HumanMessage(prompt)];
 
  // 5. Execute the agent loop
  while (true) {
    const response = await modelWithTools.invoke(messages);
    messages.push(response);
 
    if (!response.tool_calls || response.tool_calls.length === 0) {
      // The model has finished its task and returned a natural language response
      console.log("Agent finished:", response.content);
      break;
    }
 
    // Execute each tool call requested by the model
    for (const toolCall of response.tool_calls) {
      console.log(`Executing tool: ${toolCall.name}`);
      
      try {
        // The tool manager executes the API request through Truto's Proxy API
        const toolResult = await toolManager.executeTool(toolCall, integratedAccountId);
        messages.push(toolResult);
      } catch (error: any) {
        // Explicit rate limit handling using standardized headers
        if (error.status === 429) {
          const resetTime = error.headers['ratelimit-reset'];
          console.warn(`Rate limit hit. Caller must backoff until ${resetTime}`);
          // Implement your delay/backoff logic here based on the header
          throw new Error("Rate limit exceeded, execution paused.");
        }
        
        // Append the error to the prompt so the LLM can attempt a correction
        console.error(`Tool execution failed: ${error.message}`);
        messages.push({
          role: "tool",
          tool_call_id: toolCall.id,
          content: `Error: ${error.message}. Please fix the arguments and try again.`
        });
      }
    }
  }
}

Workflows in Action

Once the agent loop is configured, you can execute complex integration operations through simple natural language commands. Here are real-world scenarios showing the exact tool sequences the agent orchestrates.

Scenario 1: Embedded User Onboarding and Token Generation

When a new customer signs up for your SaaS product, your agent can autonomously provision their embedded integration environment.

"A new customer 'Stark Industries' just signed up with tenant ID 't_9934'. Provision them as a Tray.ai user, fetch the available CRM solutions, and generate an access token so they can configure their integrations."

Step-by-step execution:

1. The agent calls create_a_tray_ai_user with {"name": "Stark Industries", "external_user_id": "t_9934"}.
2. Tray.ai responds with the new user ID (e.g., user_8829).
3. The agent calls list_all_tray_ai_solutions to retrieve the catalog of available templates.
4. The agent calls tray_ai_users_create_user_token with {"user_id": "user_8829"} to retrieve the short-lived access token.
5. The agent formats a final response to the application layer containing the solutions array and the JWT token required to render the frontend configuration wizard.

Scenario 2: Autonomous Instance Auditing and Offboarding

When a customer churns, leaving active integration instances running costs you money and introduces security risks. Your agent can clean up infrastructure automatically.

"Audit our Tray.ai account. Find the user associated with external ID 't_4412', list all their active solution instances, and disable every running instance. Then delete the user."

Step-by-step execution:

1. The agent calls list_all_tray_ai_users to map the external ID t_4412 to the internal Tray user ID.
2. The agent calls list_all_tray_ai_solution_instances to fetch all deployments owned by that user.
3. For each active instance, the agent calls update_a_tray_ai_solution_instance_by_id passing {"id": "<instance_id>", "enabled": false} to immediately stop the workflows.
4. Finally, the agent calls delete_a_tray_ai_user_by_id to purge the user record from the system, returning a success confirmation to the operations team.

sequenceDiagram
    participant Admin as Ops Team
    participant Agent as AI Agent
    participant Truto as Truto Proxy API
    participant Tray as Tray.ai API

    Admin->>Agent: "Offboard user t_4412 and disable instances"
    Agent->>Truto: list_all_tray_ai_users()
    Truto->>Tray: GraphQL Query (Users)
    Tray-->>Truto: Nodes & Edges payload
    Truto-->>Agent: Clean JSON list
    Agent->>Truto: list_all_tray_ai_solution_instances(user_id)
    Truto->>Tray: GraphQL Query (Instances)
    Tray-->>Truto: Instances payload
    Truto-->>Agent: Clean JSON list
    
    loop For Each Instance
        Agent->>Truto: update_a_tray_ai_solution_instance_by_id(id, enabled: false)
        Truto->>Tray: GraphQL Mutation (Update)
        Tray-->>Truto: Mutation ID
        Truto-->>Agent: Success
    end
    
    Agent->>Truto: delete_a_tray_ai_user_by_id(user_id)
    Truto->>Tray: GraphQL Mutation (Delete)
    Tray-->>Truto: Success
    Truto-->>Agent: Success
    Agent-->>Admin: "All instances disabled and user deleted."

Moving from Scripting to Autonomy

Connecting an AI agent to an integration platform like Tray.ai transforms how you manage embedded infrastructure. Instead of maintaining fragile scripts to orchestrate user creation, token generation, and instance lifecycle management, you hand strict, typed JSON schemas to an LLM and let it reason through the workflow.

By leveraging Truto's proxy toolset, you shield your agent from the GraphQL schema complexities, opaque pagination cursors, and strict mutation requirements inherent to the underlying APIs. The model operates on clear concepts - users, tokens, and solution instances - while you maintain deterministic control over the API execution boundaries and rate limit backoff logic.