Connect FlowMate to AI Agents: Run flows and analyze system logs

You want to connect FlowMate to an AI agent so your systems can independently trigger automation flows, read system logs, manage tenant configurations, and execute complex reporting queries based on real-time alerts. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually map dozens of deeply nested REST endpoints or maintain stateful API wrappers.

Giving a Large Language Model (LLM) read and write access to your FlowMate environment is an engineering challenge. You either spend weeks building and maintaining a custom orchestration connector that understands the nuances of FlowMate's tenant-scoped endpoints, or you use a managed infrastructure layer that handles the foundational proxy architecture for you. If your team uses ChatGPT, check out our guide on connecting FlowMate to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting FlowMate 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 FlowMate, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex IT automation 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 Custom FlowMate Connectors

Building AI agents is easy. Connecting them to complex, stateful SaaS APIs is hard. Giving an LLM access to external automation data sounds simple in a Jupyter Notebook. You write a fetch request, wrap it in a tool decorator, and move on. In production, this approach collapses entirely, especially with a workflow orchestration system like FlowMate.

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

The Asynchronous Execution Gap

FlowMate is an automation platform. When you trigger a flow via its API, you do not receive the final result of that workflow in the immediate HTTP response. You receive an execution acknowledgment and a flow ID.

If you hand-code this integration, you have to write complex prompts to teach the LLM the exact syntax of asynchronous polling. The agent must learn to call a start endpoint, parse the execution ID, wait, and then query the logging endpoints for that specific flow to determine if it succeeded or failed. If you just hand an LLM the raw FlowMate API specs, it will hallucinate the outcome of a flow immediately after triggering it, assuming the 200 OK means the workflow logic executed flawlessly.

Strict Tenant Contexts

Unlike flat CRMs, FlowMate utilizes a multi-tenant data model where many operational endpoints require strict tenant isolation. For example, to fetch system logs or run specific reports, the API expects a valid tenant parameter.

LLMs constantly fail at context retention across multi-stage tenant lookups. If a user asks, "Check the logs for the failed sync yesterday," an agent needs to know exactly which tenant ID maps to the user's implicit request, pass that into the API payload, and structure the query. Without a standardized proxy layer mapping these endpoints into clear, descriptive LLM tools, your agent will blindly omit the tenant parameter, triggering 400 Bad Request errors that stall the agent loop.

Transparent Rate Limit Handling

When AI agents operate autonomously, they generate API requests much faster than human users. They will aggressively poll logs, list templates, and query reporting endpoints. Eventually, you will hit FlowMate's rate limits. Understanding how to handle third-party API rate limits is critical to prevent agent stall-outs and infinite retry loops.

Most API aggregators try to be "smart" by quietly absorbing these rate limits, applying internal backoffs, and hanging the connection. This is disastrous for LLM agents, which have strict timeout windows. Truto takes a deterministic approach: it does not retry, throttle, or apply backoff on rate limit errors. When the FlowMate API returns an HTTP 429, Truto passes that error directly to the caller.

Crucially, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The agent architecture - your caller logic - is strictly responsible for handling the retry and backoff, giving you complete control over agent execution state and token limits.

Hero Tools for FlowMate

Instead of dumping the entire Swagger file into the LLM context, Truto exposes FlowMate endpoints as clean, descriptive Methods mapped to Resources. This makes it the best unified API for LLM function calling because the model receives contextually relevant tool descriptions rather than raw API endpoints. You can dynamically fetch these via the /tools endpoint.

Here are the highest-leverage tools available for FlowMate orchestration.

List All Flows

Retrieves the definitions of all available automation flows. This tool is critical for giving the agent spatial awareness of what automations are actually configured in the environment. It returns flow IDs, names, types, and current statuses.

"What flows are currently active in our environment related to incident response? Pull the flow names and their IDs."

Start a Flow

Triggers the execution of a specific FlowMate flow by its flow_id. The agent will receive data containing the flow ID and its new active status, along with execution metadata.

"Trigger the flow with ID flw_98234 to restart the staging database sequence. Let me know when the execution has successfully initialized."

Stop a Flow

Halts a currently running flow's integration process. This is the emergency brake tool, allowing an agent to intervene if a downstream alert indicates a flow is stuck in an infinite loop or processing corrupted data.

"The sync flow flw_11223 is causing CPU spikes on the database. Send the command to stop the flow immediately."

List System Logs

Fetches execution logs for a specific tenant. This tool allows the agent to diagnose why a workflow failed. It supports filtering by flow ID, step, or error-only mode, keeping the context window focused purely on stack traces and failure reasons.

"Fetch the error logs for tenant tnt_445 from the last hour. Tell me exactly which step failed and summarize the error message."

List Reporting Execution Counts

Retrieves execution metrics grouped by time frame, user, or tenant. This allows an agent to perform capacity planning, billing analysis, or system health checks by observing how often specific flows are triggered.

"Pull the execution reports for the last 7 days grouped by tenant. Which tenant is consuming the most flow executions?"

Create an Incoming Webhook

Passes a raw JSON payload directly into a FlowMate webhook by its ID. This allows the AI agent to act as a dynamic event source, synthesizing data from its conversation or internal memory and pushing it into a structured FlowMate pipeline.

"Take this list of compromised email addresses and push them as a JSON payload to the security quarantine webhook ID wh_778."

To view the complete schema definitions and the full inventory of available tools, visit the FlowMate integration page.

Workflows in Action

When you expose these capabilities to an LLM, you transition from basic chat interfaces to autonomous system administration. Here is how specific engineering and IT personas can leverage these tools in practice.

Automated Incident Diagnostics

An on-call DevOps engineer receives a page that a critical daily ETL flow failed. Instead of manually logging into the FlowMate dashboard and digging through logs, they ask the agent to investigate.

"The daily ETL flow just failed. Find out why, and if it's a transient network timeout, restart it."

1. list_all_flow_mate_flow: The agent searches for flows matching the name "daily ETL" to retrieve the flow_id.
2. list_all_flow_mate_log: The agent passes the flow_id and the error-only flag to fetch the exact failure reason.
3. LLM Evaluation: The model parses the log, identifies a 504 Gateway Timeout from a downstream database, and categorizes it as a transient error.
4. flow_mate_flow_start: The agent re-triggers the flow using the ID and reports the new execution status back to the engineer.

Multi-Tenant Usage Optimization

An IT operations manager needs to audit which clients (tenants) are burning through the most automation resources and identify unused templates.

"Analyze our FlowMate usage. Find the top 3 tenants by execution volume this month, and list any flow templates that haven't been used."

1. list_all_flow_mate_reporting: The agent fetches the grouped execution counts for the current month, sorting by total executions per tenant to isolate the top three.
2. list_all_flow_mate_flow_template: The agent queries the available templates in the environment.
3. list_all_flow_mate_flow: The agent cross-references instantiated flows against the available templates to determine which templates have zero active implementations.
4. LLM Evaluation: The agent formats this data into a clear markdown report for the operations manager.

Building Multi-Step Workflows

To execute these complex agentic loops, you need to bind Truto's dynamically generated Proxy APIs directly to your LLM framework. For developers looking at modern interface standards, you can also explore building MCP servers for AI agents to standardize how these tools are exposed. Truto provides a dedicated Langchain.js SDK (@trutohq/truto-langchainjs-toolset) that handles the retrieval and formatting of these tools.

Because Truto acts as a translation layer, the framework agnostic tool definitions can be ingested by .bindTools() in LangChain, or converted for use in the Vercel AI SDK.

The System Architecture

sequenceDiagram
    participant LLM as LLM (OpenAI/Anthropic)
    participant Agent as Agent Execution Loop
    participant TrutoSDK as Truto Tool Manager
    participant TrutoAPI as Truto API
    participant Upstream as FlowMate API
    
    Agent->>TrutoAPI: GET /integrated-account/<id>/tools
    TrutoAPI-->>Agent: Returns JSON tool schemas
    Agent->>LLM: Bind tools and send user prompt
    LLM-->>Agent: Emits tool_call (e.g., flow_mate_flow_start)
    Agent->>TrutoSDK: Execute tool with payload
    TrutoSDK->>TrutoAPI: POST /proxy/flowmate/start
    TrutoAPI->>Upstream: Authenticated API Request
    Upstream-->>TrutoAPI: 200 OK (Execution Data)
    TrutoAPI-->>TrutoSDK: Normalized JSON
    TrutoSDK-->>Agent: Tool execution result
    Agent->>LLM: Pass result context back to model

Example: LangChain TypeScript Implementation

This implementation demonstrates how to instantiate the Truto toolset, bind it to an OpenAI model, and handle the crucial 429 rate limit exceptions that Truto bubbles up.

import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage } from "@langchain/core/messages";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
async function runFlowMateAgent(prompt: string, integratedAccountId: string) {
  // 1. Initialize the LLM
  const model = new ChatOpenAI({ 
    modelName: "gpt-4o",
    temperature: 0 
  });
 
  // 2. Fetch the FlowMate tools via Truto
  const toolManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: integratedAccountId
  });
  
  // Filter for FlowMate specific tools if needed, or grab them all
  const tools = await toolManager.getTools();
  
  // 3. Bind tools to the model
  const modelWithTools = model.bindTools(tools);
  
  console.log(`Successfully bound ${tools.length} tools to the model.`);
  
  let messages = [new HumanMessage(prompt)];
  
  // 4. The Agent Execution Loop
  while (true) {
    const response = await modelWithTools.invoke(messages);
    messages.push(response);
    
    // Exit loop if no tool calls are emitted
    if (!response.tool_calls || response.tool_calls.length === 0) {
      console.log("Agent finished execution.");
      return response.content;
    }
    
    for (const toolCall of response.tool_calls) {
      console.log(`Executing tool: ${toolCall.name}`);
      const selectedTool = tools.find(t => t.name === toolCall.name);
      
      if (selectedTool) {
        try {
          // Invoke the Truto proxy API
          const result = await selectedTool.invoke(toolCall.args);
          messages.push({
            role: "tool",
            content: typeof result === 'string' ? result : JSON.stringify(result),
            name: toolCall.name,
            tool_call_id: toolCall.id
          });
        } catch (error: any) {
          // CRITICAL: Handling Rate Limits
          // Truto passes 429s directly. We must handle retry/backoff here.
          if (error.status === 429) {
            const resetSeconds = error.headers['ratelimit-reset'] || 60;
            console.warn(`Rate limit hit on FlowMate. Backing off for ${resetSeconds} seconds.`);
            
            // Tell the LLM that the tool failed due to a rate limit
            messages.push({
              role: "tool",
              content: `Error: FlowMate API rate limited. Caller must wait ${resetSeconds} seconds before retrying.`,
              name: toolCall.name,
              tool_call_id: toolCall.id
            });
          } else {
            // Generic error handling
            messages.push({
              role: "tool",
              content: `Tool execution failed: ${error.message}`,
              name: toolCall.name,
              tool_call_id: toolCall.id
            });
          }
        }
      }
    }
  }
}
 
// Execute the workflow
const userPrompt = "Find the daily reporting flow and start it. If it fails, pull the error logs.";
const accountId = "flowmate_acc_12345";
 
runFlowMateAgent(userPrompt, accountId).then(console.log);

Handling the Integration State

By leveraging Truto's dynamic /tools endpoint, the integration logic is entirely decoupled from the business logic of your application. When FlowMate adds new endpoints or alters their schema, Truto's integration layer updates the Proxy API definition.

The next time your agent initiates its execution loop, the GET /tools call pulls the updated schema definitions, natively re-training the agent on the new capabilities without a single code deployment on your end.

Moving Beyond Proof-of-Concepts

Wiring an LLM to FlowMate using raw fetch requests is fine for a weekend hackathon. In a production environment, unhandled rate limits, shifting pagination schemas, and stateful multi-tenant logic will break agentic loops instantly.

Truto's architecture provides the perfect separation of concerns. It handles the heavy lifting of OAuth, pagination, and unified schema structures via its Proxy APIs. It exposes those definitions in standard LLM-parsable formats. Meanwhile, it respects the physical realities of the underlying systems, strictly passing IETF-standard rate limit headers back to your application so your agent framework retains ultimate control over its state and context windows. This is how you build reliable, autonomous orchestration pipelines at scale.