Connect Pigment to AI Agents: Trigger Data Flows and Manage Snapshots

You want to connect Pigment to an AI agent so your system can autonomously refresh financial models, execute complex data flows, sync external datasets, and monitor environment snapshots. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom connector against Pigment's complex API architecture.

Giving a Large Language Model (LLM) read and write access to enterprise planning software is unforgiving. A hallucinated parameter during a budget snapshot or a malformed payload pushing raw CSV data can corrupt financial models. If your team uses ChatGPT, check out our guide on connecting Pigment to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Pigment 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 Pigment, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and orchestrate asynchronous financial operations. For a broader look at this design pattern across enterprise SaaS, read our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of the Pigment API

Prototyping an AI agent with a simple read-only API is easy. You wrap a basic HTTP GET request in a tool decorator and the LLM figures out the rest. In production against a platform like Pigment, this approach collapses under the weight of the upstream architecture.

Pigment's API is designed for heavy, asynchronous, bulk operations. Standard LLMs are trained to expect synchronous CRUD behavior - they want to send a request, get a JSON object back, and immediately formulate an answer. If you expose raw endpoints directly to the model without standardizing the interaction layer, the agent will fail predictably. Here are the specific integration realities you must handle.

The Asynchronous Execution Trap

When an agent wants to refresh a financial model, it calls an endpoint to trigger a data flow. An LLM expects the response to contain the results of that refresh. Pigment does not work this way.

Calling create_a_pigment_data_flow_trigger or initiating a Looker import via create_a_pigment_push_looker returns immediately with a 202 Accepted style acknowledgment and an execution ID (like dataFlowExecutionId or importId). The job runs asynchronously in the background. The agent must understand that it has to hold state, parse out the ID, and repeatedly poll a secondary endpoint (get_single_pigment_data_flow_status_by_id) until the status transitions to Completed or Failed.

If you do not structure the tool descriptions explicitly to explain this polling loop, the agent will assume the job finished successfully the moment the trigger fires and prematurely alert the user.

UUID Scoping and State Chaining

The Pigment data model is strictly scoped by applications. An agent cannot simply ask to "list all data flows." Every meaningful operation requires an application_id.

Because LLMs do not inherently know your internal Pigment UUIDs, the agent must execute a specific chain of discovery operations. It must first call list_all_pigment_applications to retrieve a list of names and UUIDs. Only then can it filter for the requested application, extract the application_id, and pass it into list_all_pigment_data_flows to find the target pipeline.

flowchart TD
    A["LLM Agent"] -->|"Call: list_all_pigment_applications"| B["Truto Proxy Layer"]
    B -->|"GET /applications"| C["Pigment API"]
    C -->|"Return JSON<br>with application_id"| B
    B -->|"Return Tool Result"| A
    A -->|"Call: list_all_pigment_data_flows<br>(using application_id)"| B

Binary Payloads over JSON

LLMs operate almost exclusively in text and JSON. However, Pigment's export APIs (views, lists, metrics, tables) do not return JSON objects. They stream back raw CSV data (text/csv).

If a user prompts the agent to "export the Q3 sales view," the agent will receive a raw CSV string. Depending on the size of the view, this string can easily exceed the context window of standard models, causing a crash. You must configure your tool layer to either parse and paginate this CSV data, write it directly to a file system, or summarize it before returning it to the context window.

Building Multi-Step Workflows

To bypass these integration headaches, we use Truto's /tools endpoint. Truto maps Pigment's API into REST-based proxy methods, handling authentication, pagination, and query parameter processing automatically. It then exposes these methods as ready-to-use JSON schemas that LLMs can consume natively.

This approach works with any modern framework, but for this guide, we will use TypeScript and the @trutohq/truto-langchainjs-toolset.

Step 1: Fetching the Tools

First, we instantiate the tool manager using a Truto integrated account ID. This ID maps to a specific customer's authenticated Pigment instance. We then fetch the tools dynamically.

import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
 
// Initialize the manager with your specific Pigment account connection
const toolManager = new TrutoToolManager({
  integratedAccountId: "pigment_account_12345",
  trutoApiKey: process.env.TRUTO_API_KEY
});
 
// Fetch the tools dynamically from the Truto API
const tools = await toolManager.getTools();

Step 2: Rate Limit Reality Check

Before executing the agent loop, we need to address rate limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When Pigment returns an HTTP 429 Too Many Requests, Truto passes that error directly back to your agent.

However, Truto normalizes the upstream rate limit information into standard headers per the IETF specification:

• ratelimit-limit: The maximum number of requests allowed.
• ratelimit-remaining: How many requests you have left.
• ratelimit-reset: The time (in seconds) until the limit resets.

Your agent framework or execution loop is entirely responsible for catching the 429 error, reading the ratelimit-reset property from the tool execution result, and pausing execution. If your agent is polling a data flow status in a tight loop, it will hit these limits. You must wrap your agent execution in a backoff handler.

sequenceDiagram
    participant Agent as "Agent Execution Loop"
    participant Truto as "Truto Proxy API"
    participant Pigment as "Pigment Upstream"

    Agent->>Truto: call tool (get_status)
    Truto->>Pigment: GET /api/status/:id
    
    alt Rate Limit Reached
        Pigment-->>Truto: 429 Too Many Requests
        Truto-->>Agent: 429 Error with ratelimit-reset header
        Note over Agent: Agent suspends execution<br>for specified seconds
    else Success
        Pigment-->>Truto: 200 OK (InProgress)
        Truto-->>Agent: Tool Result (InProgress)
    end

Step 3: Binding the LLM

Now we bind the fetched tools to the LLM and create the agent executor. The LLM requires a prompt that explicitly explains how to navigate Pigment's architecture - specifically the requirement to always fetch the application_id first.

const llm = new ChatOpenAI({
  modelName: "gpt-4o-mini",
  temperature: 0,
});
 
// Bind the Truto tools to the model
const llmWithTools = llm.bindTools(tools);
 
const prompt = ChatPromptTemplate.fromMessages([
  ["system", `You are an autonomous revenue operations assistant managing Pigment environments.
  
  CRITICAL RULES:
  1. Pigment operations require an application_id. You MUST call list_all_pigment_applications first to find the correct application ID.
  2. When triggering data flows or imports, the API will return an execution ID immediately. The job is NOT done. You MUST poll the status using that ID until it returns 'Completed'.
  3. If you receive an error indicating rate limits, wait before retrying.`],
  ["human", "{input}"],
  new MessagesPlaceholder("agent_scratchpad"),
]);
 
const agent = createOpenAIToolsAgent({
  llm,
  tools,
  prompt,
});
 
const executor = new AgentExecutor({
  agent,
  tools,
  maxIterations: 15, // High iterations needed for polling loops
});
 
// Execute the workflow
const result = await executor.invoke({
  input: "Trigger the 'Consolidate Headcount' data flow in the 'HR Planning' application and let me know when it finishes."
});
 
console.log(result.output);

Pigment Hero Tools for Autonomous Agents

Do not give your agent raw access to every endpoint in the Pigment documentation. Scope the available tools to the specific workflows the persona needs. Here are the highest-leverage tools available for Pigment through Truto.

List All Pigment Applications

Description: Lists metadata for every Pigment Application in the Workspace. Returns each application's ID (UUID) and name.

Contextual Usage: This is the foundation of almost every Pigment agent workflow. The agent must use this tool to map plain-text application names requested by the user into the UUIDs required by downstream endpoints.

"Find the application ID for the 'Global Supply Chain' model so we can access its data flows."

List All Pigment Data Flows

Description: Lists the Data Flows configured in a Pigment application. Requires an application_id. Returns the dataFlowId, name, description, and steps.

Contextual Usage: Used by the agent to discover what automated pipelines are available to run within a specific application context. It maps human-readable data flow names to the UUIDs needed for execution.

"What data flows are available to run inside the 'Sales Quotas' application?"

Create a Pigment Data Flow Trigger

Description: Triggers an execution of a Data Flow. Requires the dataFlowId. Returns a dataFlowExecutionId.

Contextual Usage: This executes core business logic. Because it returns immediately, the agent must be prompted to capture the execution ID and pass it to the status polling tool.

"Trigger the 'End of Month Revenue Consolidation' data flow."

Get Single Pigment Data Flow Status By Id

Description: Gets the status of a Data Flow execution. Returns the status (InProgress, Completed, PartialFailure, or Failed). Rate limited.

Contextual Usage: The critical second half of the data flow workflow. The agent will call this in a loop to check if the previously triggered job has finished. The agent must handle HTTP 429s gracefully here based on the Retry-After (or Truto ratelimit-reset) delay.

"Check the status of execution ID 8f7d9a-b2c3 and report back if it failed."

List All Pigment Applications Snapshots

Description: Lists metadata for all application snapshots in Pigment, including scheduled, in progress, and failed ones. Returns ID, name, status, date, and applications.

Contextual Usage: Excellent for IT administration and governance agents. The agent can query this tool to run automated health checks on environment backups and alert the team if recent snapshots are failing.

"Audit the Pigment snapshots from the last 48 hours and identify any that have a status of Failed."

Create a Pigment Push Looker

Description: Triggers a Looker Look import in Pigment. Pigment pulls the Look data and runs the import asynchronously. Returns an importId.

Contextual Usage: Used for cross-platform data syncing. The agent triggers Pigment to pull fresh data from Looker, usually preceding a data flow execution to refresh downstream metrics.

"Trigger the Looker import for the 'Active Pipeline' configuration ID."

For the complete schema definitions, query parameters, and a full list of available tools, refer to the Pigment integration page.

Workflows in Action

When you combine these tools into a single context window, you transform a static LLM into an autonomous system administrator and data engineer. Here are three concrete workflows you can run using this setup.

Scenario 1: Automated Financial Model Refresh

An FP&A analyst needs to run a complex data pipeline that takes several minutes, and wants to be notified only when it is complete and successful.

"Trigger the 'Q3 Pipeline Rollup' data flow in the 'Revenue Planning' application. Wait for it to finish and give me a summary of the final status."

Agent Execution Steps:

1. Calls list_all_pigment_applications to find the UUID for "Revenue Planning".
2. Calls list_all_pigment_data_flows passing the application UUID to locate the dataFlowId for "Q3 Pipeline Rollup".
3. Calls create_a_pigment_data_flow_trigger using the flow UUID and receives a dataFlowExecutionId.
4. Enters a polling loop, calling get_single_pigment_data_flow_status_by_id every few seconds (backing off if a 429 is encountered via ratelimit-reset).
5. Once the API returns Completed, the agent breaks the loop and informs the user.

Scenario 2: Diagnostic Snapshot Auditing

An IT systems administrator wants to proactively monitor environment health without logging into the Pigment interface manually.

"Check all Pigment application snapshots. Identify any that have failed recently and list the applications associated with the failure."

Agent Execution Steps:

1. Calls list_all_pigment_applications_snapshots to pull the metadata for all recent system snapshots.
2. The agent analyzes the returned JSON array in-memory, filtering for objects where the status field equals Failed.
3. The agent formats a summary report detailing the failed snapshot IDs, the timestamps, and the specific application names impacted, allowing the IT admin to take immediate remedial action.

Scenario 3: Cross-Platform Data Syncing

A RevOps manager needs to push fresh analytics data into Pigment before running a commission calculation.

"Trigger the Looker import for 'Sales Quotas' in the 'Commissions' app. Once the import is complete, trigger the 'Calculate Payouts' data flow."

Agent Execution Steps:

1. Calls list_all_pigment_applications to get the UUID for "Commissions".
2. Calls list_all_pigment_import_configurations to find the configurationId for the "Sales Quotas" Looker import.
3. Calls create_a_pigment_push_looker to initiate the async import and gets the importId.
4. Polls get_single_pigment_import_status_by_id until the Looker data sync is complete.
5. Calls list_all_pigment_data_flows to find the "Calculate Payouts" flow ID.
6. Calls create_a_pigment_data_flow_trigger to run the calculation based on the freshly imported data.

Strategic Wrap-up

Giving an AI agent access to an enterprise planning platform like Pigment requires architectural discipline. If you attempt to connect an LLM directly to raw Pigment endpoints, your agent will drown in UUID lookups, fail to understand asynchronous execution patterns, and inevitably crash when it hits a rate limit.

By leveraging a unified proxy layer and the /tools endpoint, you collapse the complexity of the integration. The LLM only sees strict, deterministic JSON schemas for operations like create_a_pigment_data_flow_trigger and list_all_pigment_applications. Truto handles the underlying authentication and query processing, leaving your agent to focus purely on workflow orchestration, status polling, and backoff management.