Connect Planful to AI Agents: Automate Models & User Access Control

You want to connect Planful to an AI agent so your system can autonomously provision finance users, orchestrate Data Load Rules (DLRs), execute complex model calculations, and manage scenario access. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom Continuous Performance Management (CPM) integration from scratch.

Giving a Large Language Model (LLM) read and write access to your Planful instance is a massive engineering undertaking. You either spend sprints deciphering dynamic access tokens and chunked data transfers, or you use a managed infrastructure layer that normalizes the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Planful to ChatGPT, or if you are building on Anthropic's models, read our guide to connecting Planful 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 Planful, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex FP&A (Financial Planning and Analysis) workflows. For a broader look at this design pattern, read our guide on Architecting AI Agents: LangGraph, LangChain, and the SaaS Integration Bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing integration code, you must decide what interface your AI agent will consume. This choice determines the reliability of your autonomous system.

Direct API tools - mapping one tool per raw Planful endpoint - look easy during prototyping but immediately push vendor-specific quirks into the LLM's context window. The model has to "know" when to use an Access ID versus a Dynamic Planning token. It has to inherently understand that chunked data transfers require a 40MB payload limit and a specific IsLoadCompleted header on the final batch. Every one of these undocumented expectations is a hallucination waiting to happen.

Providing an abstracted tool layer places Planful behind standardized schemas. Your agent sees create_a_planful_user, create_a_planful_data_transfer, and create_a_planful_model_calculation_run. That delivers significant engineering advantages:

1. Minimized attack surface for hallucinations: The LLM selects from a tightly scoped list of deterministic function names. It does not invent OData filters unless explicitly schema-defined.
2. Deterministic input validation: Every tool has a strict JSON schema. Invalid arguments are rejected at the proxy layer before they hit the upstream Planful API, failing fast rather than silently corrupting financial models.
3. Decoupled authentication: The LLM does not manage credentials, tenant IDs, or token lifecycles.

The Engineering Reality of the Planful API

Giving an LLM access to external financial data sounds simple until you hit the engineering realities of enterprise CPM systems. Standard REST assumptions break down quickly against Planful's architecture. If you hardcode raw HTTP requests into your agent, your team will spend months writing defensive boilerplate.

The Dual-Auth System

Planful operates using two distinct authentication models depending on the feature you are interacting with. Standard administrative tasks and Data Load Rules (DLRs) require an Access ID and Access Key generated from the application. However, Dynamic Planning - where the heavy lifting for Master and Analytic models happens - requires an X-Access-Token.

If you build this manually, your agent needs to maintain context on which authentication mechanism applies to which endpoint. Truto abstracts this away. The Proxy API layer normalizes authentication, allowing the agent to call tools seamlessly while the infrastructure routes the correct credentials upstream.

Asynchronous Chunking and DLRs

Transferring financial data into Planful via a Data Load Rule is not a standard POST request. The API enforces a strict 40MB payload limit per request. If your dataset exceeds this, it must be batched. More importantly, Planful requires stateful knowledge of these batches. To signal the end of a transfer, you must send an IsLoadCompleted=True header or a null payload.

Standard LLMs are terrible at managing arbitrary chunking math and stateful termination signals. An agent attempting to dump a 100MB dataset in one go will crash. You must encapsulate this chunking logic into the tool execution layer so the agent just says "Sync this dataset" and the underlying tool handles the 40MB slicing and the final termination flag.

Mixed Response Formats (XML and JSON)

While most modern APIs adhere strictly to JSON, Planful's legacy External Source Model (ESM) functionalities, such as exporting leaf-level data, return XML. Conversely, newer endpoints return standard JSON. If your agent framework blindly attempts to parse JSON.parse(response) on an ESM data export, the workflow will throw a fatal error. Truto's integration tooling handles data normalization, ensuring the LLM always receives structured, predictable JSON representations regardless of the underlying vendor format.

High-Leverage Planful Tools for AI Agents

Instead of exposing hundreds of raw endpoints, Truto provides tailored Proxy APIs wrapped as LLM tools. These tools update automatically via Truto's UI when you customize descriptions or schemas.

Here are the hero tools you should bind to your agent for automated Planful administration.

1. Execute Model Calculations

create_a_planful_model_calculation_run

Use this tool to trigger complex calculations defined on a Master or Analytic model. Note that this API only invokes calculations explicitly enabled to run in the background. Because financial models are computationally heavy, this is a fire-and-forget command that returns a success status, allowing the agent to move on to other tasks while Planful crunches the numbers.

"Run the 'Q3_Forecast_Consolidation' calculation script on the 'Corporate_Finance' Master model. Proceed to notify the team in Slack once the calculation request is successfully dispatched."

2. Manage Data Load Rules (DLR)

create_a_planful_data_transfer

This tool handles data ingestion against a specific Data Load Rule. It requires a DataLoadRuleConfig and a payload, managing the push of CSV data into the Planful staging environment. This is critical for agents responsible for syncing external CRM or HRIS data into Planful for headcount or revenue forecasting.

"Initiate a data transfer for the DLR named 'Salesforce_Bookings_Sync'. Use a comma delimiter and send the parsed booking payload into the rule."

3. Provision Planful Users

create_a_planful_user

User access in financial systems must be strictly controlled. This tool allows the AI agent to provision a new user, specify their NavigationRoleName, and set up their base profile. If the user already exists in a broader tenant group, the API maps their details automatically to the current tenant.

"Create a new Planful user for jsmith@example.com. Set their first name to John and assign them the 'FP&A Analyst' navigation role."

4. Manage Granular Scenario Access

create_a_planful_user_scenario_access

In CPM platforms, users should only see the scenarios relevant to their department or clearance. This tool grants specific scenario access permissions to a given user. This is perfect for an IT agent handling automated onboarding requests via Slack or Jira.

"Grant jsmith@example.com access to the 'FY25_Base_Case' and 'FY25_Stretch_Goal' scenario codes."

5. Export External Source Model Data

create_a_planful_source_model_data_export

When an agent needs to retrieve historical actuals or external dataset baselines, this tool exports leaf-level data from a specified ESM. The agent can specify filters to narrow down the export, ensuring it doesn't ingest unnecessary tokens into its context window.

"Export the leaf-level data from the 'Workday_Headcount' external source model. Filter the data to only include records from the Q2 period, and extract the results for analysis."

To view the complete schema definitions and the full inventory of available tools - including bulk updates, file transfers, and specific GL data extractors - visit the Planful integration page.

Building Multi-Step Workflows

Connecting Planful tools to an AI framework requires a programmatic fetch and bind process. Truto handles this via the /tools endpoint, which returns JSON Schema definitions for every method available on the integrated account.

Here is how you fetch these tools and bind them to a LangChain agent using the truto-langchainjs-toolset.

Handling Rate Limits in Agent Loops

Planful enforces strict rate limits on API calls. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Planful API returns an HTTP 429, Truto passes that exact error to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification.

Your agent framework is responsible for handling the retry and backoff logic by intercepting the 429 and reading the ratelimit-reset header.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { ChatPromptTemplate } from "@langchain/core/prompts";
 
async function runPlanfulAgent(prompt: string) {
  // 1. Initialize Truto Tool Manager with your Planful Integrated Account ID
  const trutoManager = new TrutoToolManager({
    trutoToken: process.env.TRUTO_API_KEY,
    accountId: process.env.PLANFUL_ACCOUNT_ID,
  });
 
  // 2. Fetch Proxy APIs as formatted LLM tools
  // We filter for custom tools and write operations specifically
  const tools = await trutoManager.getTools({ 
    methods: ["read", "create", "custom"] 
  });
 
  // 3. Initialize the LLM and bind tools
  const llm = new ChatOpenAI({ 
    modelName: "gpt-4o", 
    temperature: 0 
  }).bindTools(tools);
 
  const promptTemplate = ChatPromptTemplate.fromMessages([
    ["system", "You are an elite financial systems administrator managing Planful. You have access to user provisioning, data transfers, and model calculations."],
    ["user", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  const agent = await createOpenAIFunctionsAgent({
    llm,
    tools,
    prompt: promptTemplate,
  });
 
  const executor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 5,
  });
 
  // 4. Agent execution loop with manual rate limit handling
  try {
    const result = await executor.invoke({ input: prompt });
    console.log("Agent Output:", result.output);
  } catch (error: any) {
    if (error.response && error.response.status === 429) {
      // Truto passes the 429 straight through. We must handle backoff.
      const resetTime = error.response.headers['ratelimit-reset'];
      console.warn(`Rate limit hit. Must backoff until UNIX time: ${resetTime}`);
      // Implement your sleep/retry logic here based on resetTime
    } else {
      console.error("Agent execution failed:", error);
    }
  }
}
 
// Execute the workflow
runPlanfulAgent("Check the status of the 'Q3_Actuals' Data Load Rule. If it is 'Processed', trigger the 'Variance_Analysis' model calculation run.");

The Execution Architecture

When the agent runs, the architecture follows a strict pass-through pattern. The LLM determines which tool to use, formats the JSON arguments, and triggers the local function. The Truto SDK marshals that request to the Proxy API, appends the correct Planful authentication (handling the Access ID or Dynamic Planning Token switch dynamically), and executes the raw HTTP request.

sequenceDiagram
    participant LLM as AI Agent (LangChain)
    participant SDK as Truto SDK / Tools
    participant API as Truto Proxy API
    participant Upstream as Planful API

    LLM->>SDK: Calls "create_a_planful_user" with args
    SDK->>API: POST /proxy/planful/users
    note right of API: Normalizes payload & schema
    API->>Upstream: POST /User (with Access ID/Key)
    Upstream-->>API: 200 OK (User created)
    API-->>SDK: Normalized JSON response
    SDK-->>LLM: Observes result, continues reasoning

Workflows in Action

Connecting tools is only valuable if they solve real business problems. Here are concrete examples of how IT admins and DevOps engineers use Planful AI agents in production.

Scenario 1: Automated Financial Analyst Onboarding

When a new FP&A analyst joins the company, they need immediate access to Planful, mapped to specific user groups, and granted clearance to view sensitive forecasting scenarios. Traditionally, an IT admin executes a Jira ticket by clicking through four different Planful menus.

"A new analyst, Sarah Jenkins (sjenkins@acme.com), just joined the FP&A team. Provision her a Planful account with the 'Analyst' role, map her to the 'Corporate_Finance' user group, and grant her access to the 'FY25_Q1_Forecast' scenario."

Agent Execution Steps:

1. The agent calls create_a_planful_user passing the email, name, and NavigationRoleName.
2. Upon success, the agent extracts the returned UserLogin/ID.
3. The agent calls create_a_planful_user_group_mapping to link Sarah to the "Corporate_Finance" group.
4. Finally, the agent calls create_a_planful_user_scenario_access to explicitly grant access to the "FY25_Q1_Forecast" scenario code.

Result: The agent replies in Slack/Jira stating the user was created, groups were mapped, and scenario access was granted, completing a 15-minute IT task in 3 seconds.

Scenario 2: Autonomous Month-End Data Load and Calculation

Month-end close requires moving data from ERPs into Planful and then running intense calculation models. Timing is critical, and delays require human intervention to check statuses.

"Check the status of the 'NetSuite_GL_Actuals' Data Load Rule. If the execution status is 'Processed', initiate the 'Consolidation_Engine' calculation on the 'Master_Corporate' model."

Agent Execution Steps:

1. The agent calls list_all_planful_running_data_load_status passing the dlrName to see if the rule is currently processing.
2. If it is finished, the agent calls list_all_planful_data_load_status using the specific Execution ID to confirm the final status is "Processed".
3. Seeing a processed status, the agent immediately calls create_a_planful_model_calculation_run, passing modelName: "Master_Corporate" and calcScriptName: "Consolidation_Engine".

Result: The agent autonomously guards the sequencing of financial operations. It refuses to run calculations on partial data, waiting for the DLR to officially finalize before dispatching the heavy compute jobs.

Strategic Wrap-up

Building an AI agent for financial operations requires precision. Planful is a mission-critical CPM, and you cannot afford erratic API interactions, infinite looping, or token mismanagement.

By leveraging Truto's /tools endpoint, you abstract away Planful's complex authentication layers, XML formatting, and payload limitations. Your agent interacts with a clean, unified schema - drastically reducing hallucination risks and allowing your engineering team to focus on workflow logic rather than API maintenance. The result is an autonomous system capable of securely managing financial models, user provisioning, and data synchronization without constant human oversight.