Connect FlowMate to AI Agents: Monitor Logs and Trigger Flow Actions

You want to connect FlowMate to an AI agent so your orchestration systems can autonomously execute flows, pause failing templates, and pull execution logs for real-time observability. Here is exactly how to do it using Truto's /tools endpoint, bypassing the need to maintain complex API wrappers or custom function definitions.

Giving a Large Language Model (LLM) read and write access to your FlowMate instance introduces immediate engineering friction. You either spend weeks building and updating custom HTTP clients to wrap FlowMate's specific execution endpoints, or you leverage a managed infrastructure layer that handles the translation 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 across diverse data environments, 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 administration workflows. For a deeper look at the architecture behind this tool-calling 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 external SaaS APIs is hard. Giving an LLM access to external data sounds simple in a local script. You write a Node.js function that makes a fetch request and wrap it in a tool decorator. In production, this approach collapses entirely, especially with highly structured automation platforms like FlowMate.

If you decide to build a custom FlowMate AI Agents integration yourself, you own the entire API lifecycle. The FlowMate API introduces several highly specific integration challenges that break standard LLM assumptions.

The Graph Schema Complexity

Unlike a standard CRM where you update a flat list of fields to modify a record, FlowMate relies on a complex graph-based structure for its automation flows. When updating a flow via the API, you cannot simply patch a status string. The endpoint requires the full graph schema, representing nodes and edges of the integration logic. If an AI agent hallucinates the structure of this graph or omits required nested attributes, the API will reject the payload with deep validation errors. Teaching an LLM to reliably generate and modify these massive nested JSON objects via static prompts is an uphill battle.

Strict Tenant-Scoped Log Extraction

Log extraction in FlowMate is not a simple global /logs endpoint. Data is strictly siloed, meaning your API requests must inject the correct tenant scope. Furthermore, retrieving actionable trace data requires filtering logs by specific flow, step, or error-only modes. When an agent attempts to diagnose a failed execution, it must first query the overarching flow state, extract the specific tenant and execution IDs, and then chain a subsequent request to pull the exact localized logs.

Handling Grouped Execution Reporting

Extracting analytics from FlowMate requires interacting with its reporting endpoints, which do not return flat arrays. They return grouped execution counts nested under specific metadata objects. Agents must accurately format start and end timeframe parameters, and explicitly define groupby logic. Parsing the resulting multidimensional arrays into contextual insight is historically difficult for raw text models without heavily structured function schemas.

Essential FlowMate Tools for AI Agents

To safely execute tasks against FlowMate, your agent needs precise, well-described tools. By using Truto's /tools endpoint, you automatically receive Proxy APIs - RESTful representations of FlowMate's upstream endpoints, bundled with JSON schemas that enforce parameter requirements.

Here are the hero tools available for building a FlowMate API AI agent.

List All Flows

Retrieves a complete inventory of flows within the FlowMate environment. This tool returns the structural metadata required for subsequent operations, including the id, name, type, and status of each flow record.

Contextual usage notes: Agents should default to calling this tool first when asked to monitor or modify an active integration. It provides the critical internal IDs needed to trigger state changes.

"Fetch all active flows in FlowMate and list any that are currently marked as paused or failed."

Start Flow Execution

Triggers the execution of a specific FlowMate flow by its flow_id. The endpoint returns the new status and response metadata.

Contextual usage notes: Because starting a flow causes real-world downstream actions, ensure your agent is configured to verify the flow_id before execution. It is highly recommended to implement a human-in-the-loop approval state in your agent framework before allowing this tool to fire.

"Start the daily data synchronization flow using the ID you just retrieved. Confirm the new status once it has successfully launched."

Stop Flow Execution

Halts a running or scheduled FlowMate integration process by its flow_id. It returns the exact flow ID and confirms the new stopped status.

Contextual usage notes: Ideal for automated incident remediation. If a downstream API begins throwing errors or consuming excessive compute, the agent can use this tool to kill the runaway process immediately.

"Stop the customer ingestion flow immediately. It is causing a rate limit spike on our upstream CRM."

List Execution Logs

Retrieves the detailed system logs for a specific tenant. This tool accepts optional filters for narrowing down logs to a particular flow, an individual step, or filtering strictly for error-state logs.

Contextual usage notes: This is the primary diagnostic tool. When a flow fails, instruct your agent to query this endpoint with the error-only flag enabled to extract the exact stack trace or upstream rejection message.

"Pull the error logs for the billing tenant over the last hour. Summarize the failure reason for the invoice generation step."

Aggregate Reporting Analytics

Lists execution counts for FlowMate reporting across a specified timeframe. It groups execution records by user or tenant and provides metadata regarding start, end, and totalExecutions.

Contextual usage notes: Use this tool for generating weekly capacity or usage reports. Ensure the agent passes correctly formatted ISO-8601 date strings to the start and end arguments to prevent parsing errors.

"Generate a report of all flow executions over the past 7 days, grouped by tenant, and tell me which tenant consumed the most compute."

Create Incoming Webhook Payload

Transmits a JSON payload directly into a FlowMate incoming webhook by referencing the webhook_id (which maps to the flow ID).

Contextual usage notes: This tool allows your agent to bridge external systems into FlowMate. If the agent detects an event in a separate observability platform, it can dynamically construct a JSON payload and push it into FlowMate to trigger a reactive workflow.

"Send a payload to the incident response webhook containing the current server CPU metrics and the critical alert tag."

To view the complete schema details and remaining operations available, visit the FlowMate integration page.

Workflows in Action

Connecting an LLM to these APIs transforms static chat interfaces into active infrastructure engineers. Here is how specific personas leverage FlowMate tool calling in production.

Scenario 1: Automated Incident Triage and Remediation

Persona: DevOps Engineer

When a critical alert fires regarding an overloaded downstream database, the agent is tasked with pausing low-priority batch jobs in FlowMate to relieve pressure.

"We have a database bottleneck. Stop the 'Nightly Batch Analytics' flow in FlowMate immediately. Once stopped, pull the execution logs for that flow over the last 15 minutes to see where it hung up."

Execution Steps:

1. list_all_flow_mate_flow: The agent queries the system to find the internal ID associated with "Nightly Batch Analytics".
2. flow_mate_flow_stop: Using the retrieved ID, the agent issues the command to halt the active execution.
3. list_all_flow_mate_log: The agent queries the logs for that specific flow and tenant to extract the failure trace.

Output: The agent successfully halts the flow, mitigating the database load, and returns a summarized diagnostic report indicating that step 4 of the flow timed out waiting for a database lock.

Scenario 2: Infrastructure Auditing and Reporting

Persona: IT Administrator

At the end of a billing cycle, IT needs to understand which tenants are executing the most complex automation tasks to allocate costs accurately.

"Analyze FlowMate execution data for the last 30 days. Group the data by tenant and identify the top three tenants by total execution volume."

Execution Steps:

1. list_all_flow_mate_reporting: The agent calculates the ISO dates for the last 30 days, sets the groupby parameter to tenant, and fires the request.
2. The agent ingests the grouped JSON data, sorts the totalExecutions integers natively, and formats the output.

Output: The user receives a clean, bulleted list of the top three tenants by execution volume, allowing immediate cost distribution without writing SQL or navigating reporting dashboards manually.

Building Multi-Step Workflows

Architecting a resilient multi-step workflow requires an agent loop capable of parsing tool schemas, executing HTTP requests against the proxy API, and handling operational realities like rate limits.

sequenceDiagram
    participant UserApp as User Application
    participant Agent as Agent Framework (LangChain)
    participant Truto as Truto API Proxy
    participant Upstream as Upstream API (FlowMate)

    UserApp->>Agent: Prompt: "Stop failing flows"
    Agent->>Truto: GET /integrated-account/<id>/tools
    Truto-->>Agent: Returns JSON Schema of Tools
    Agent->>Agent: Bind tools to LLM context
    Agent->>Truto: Call list_all_flow_mate_flow
    Truto->>Upstream: Forward Request
    Upstream-->>Truto: Return Flow states
    Truto-->>Agent: Flow states (JSON)
    Agent->>Truto: Call flow_mate_flow_stop (ID: 123)
    Truto->>Upstream: Forward Request
    Upstream-->>Truto: 200 OK / 429 Rate Limit
    Truto-->>Agent: Passes normalized headers back
    Agent->>Agent: Handle 429 Backoff (if required)
    Agent-->>UserApp: Final Summary Output

The Reality of Rate Limits

When writing a FlowMate automation AI Agents integration, you must account for API throttling. Truto does not retry, throttle, or apply backoff on rate limit errors. If FlowMate returns an HTTP 429 Too Many Requests error, Truto passes that exact error code directly back to your agent framework.

To ensure your agent does not crash during high-volume tool execution, you must parse the headers. Truto normalizes upstream rate limit information into standardized IETF headers: ratelimit-limit, ratelimit-remaining, and ratelimit-reset. Your agent's tool execution node is responsible for reading the ratelimit-reset header and sleeping the thread before retrying.

Code Example: Fetching Tools and Handling Limits

Here is how you fetch the tools programmatically and prepare them for a LangChain agent. This approach uses standard HTTP conventions, allowing it to drop into any TypeScript environment.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
// Example assumes you have a wrapper to map Truto's JSON schema to LangChain Tool objects
import { fetchTrutoTools } from "./truto-helpers"; 
 
async function runFlowMateAgent(prompt: string, accountId: string) {
  const TRUTO_API_KEY = process.env.TRUTO_API_KEY;
  
  // 1. Fetch available FlowMate tools for the specific connected account
  const toolsResponse = await fetch(`https://api.truto.one/integrated-account/${accountId}/tools`, {
    headers: {
      "Authorization": `Bearer ${TRUTO_API_KEY}`
    }
  });
 
  if (!toolsResponse.ok) {
    throw new Error(`Failed to fetch tools: ${toolsResponse.statusText}`);
  }
 
  const rawTools = await toolsResponse.json();
  
  // Convert Truto schema definitions into standard framework tools
  const tools = fetchTrutoTools(rawTools);
 
  // 2. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 3. Bind the FlowMate tools to the LLM
  const llmWithTools = llm.bindTools(tools);
 
  // Note on Tool Execution & Rate Limits:
  // When the agent executes a tool, the underlying HTTP request might return a 429.
  // Your custom tool execution logic must catch this status code, check the 
  // 'ratelimit-reset' header, and apply a delay before returning control to the agent.
 
  // 4. Create and execute the agent loop
  // (Agent prompt construction omitted for brevity)
  const agent = await createOpenAIToolsAgent({ llm: llmWithTools, tools, prompt: customPrompt });
  const executor = new AgentExecutor({ agent, tools });
 
  const result = await executor.invoke({ input: prompt });
  console.log("Agent Output:", result.output);
}
 
runFlowMateAgent(
  "Find any active FlowMate flows and stop them.", 
  "flowmate_account_01xyz"
);

By leveraging the /tools endpoint, you completely decouple your agent's core logic from the volatile nature of upstream API changes. When FlowMate introduces a new query parameter to their logs endpoint, the Truto integration schema updates automatically, and your agent inherits the new capability on its next execution cycle.

Next Steps

Hardcoding API wrappers for LLMs is technical debt that scales linearly with every tool you support. By utilizing standard JSON schemas generated directly from the underlying API integration, you ensure your agents have safe, predictable, and fully documented access to systems like FlowMate.