Connect Arcadia to AI Agents: Automate Utility Data Pipelines

You want to connect Arcadia to your AI agents so your system can autonomously read meter intervals, ingest utility bills, and monitor facility energy consumption. If your team uses ChatGPT, check out our guide on connecting Arcadia to ChatGPT, or if you prefer Anthropic's ecosystem, read about connecting Arcadia to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

Giving a Large Language Model (LLM) read and write access to utility data infrastructure is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector for Arcadia, or you use a managed infrastructure layer that handles the boilerplate for you. This guide breaks down exactly how to fetch AI-ready tools for Arcadia using Truto's /tools endpoint, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or Vercel AI SDK, and execute complex energy data workflows.

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 Arcadia Connectors

Building AI agents is easy. Connecting them to external specialized APIs is hard. A custom integration layer is essentially a translation service that converts an LLM's tool calls into standard REST API requests. While modern models are excellent at generating JSON payloads, implementing those payloads against utility vendor APIs is highly error-prone.

If you decide to build a custom integration for Arcadia, you own the entire API lifecycle. You must write and maintain massive JSON schemas for every endpoint you want the LLM to access. Arcadia's API introduces several highly specific integration challenges that break standard LLM assumptions entirely.

The Asynchronous 2-Step Polling Problem

Unlike standard CRUD APIs that return immediate data, much of Arcadia's heavy-lifting - such as pulling large statement PDFs, meter interval CSVs, or global organization exports - relies on a two-step asynchronous architecture. You cannot simply ask an agent to "Get the CSV for this meter."

Instead, the agent must first submit a POST request to prepare the download. Arcadia responds with an HTTP 202 Accepted and a webhook or URL ID. The agent must then know to execute a second tool call, polling a GET endpoint using that ID until the status shifts from 202 to an HTTP 200 OK with the actual payload. Hand-coding this logic into an agent requires massive system prompts or complex state machines. For a deeper dive into managing these patterns, see our guide on how to handle long-running SaaS API tasks in AI agent tool-calling workflows. Truto simplifies this by surfacing the proxy methods natively, allowing you to append descriptions that guide the LLM exactly on how to orchestrate the loop.

Utility Data Hierarchies

Utility data is deeply nested and relational. A single utility bill does not exist in a vacuum. An AI agent must understand the strict hierarchy: Credentials belong to Providers. Accounts are linked to Credentials. Sites aggregate Accounts. Meters belong to Sites. Intervals and Statements belong to Meters and Accounts.

If an agent is instructed to "analyze power usage for the New York warehouse", it must know to query the Sites endpoint, retrieve the Site ID, find the associated Meter IDs, and finally pull the normalized intervals. Building custom wrappers for this means hardcoding specific mapping logic. Truto's proxy APIs expose these resources exactly as they are defined, enabling the agent to traverse the hierarchy dynamically.

The Reality of Rate Limits and Backoff

When AI agents traverse large hierarchies, they generate massive spikes in API requests. Arcadia strictly enforces rate limits. A critical architectural detail: Truto does not retry, throttle, or apply backoff on rate limit errors.

When the upstream Arcadia API returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification.

The caller - meaning your agent framework or application layer - is entirely responsible for reading the ratelimit-reset header, pausing execution, and retrying the tool call. We cover this extensively in our post on how to handle third-party API rate limits when an AI agent is scraping data. Do not rely on your integration platform to magically absorb rate limits.

Hero Tools for Arcadia

Truto provides a comprehensive set of resources mapped to Arcadia's API endpoints. By calling Truto's /tools endpoint, you automatically generate full JSON schemas and descriptions that an LLM can natively understand.

Here are the most critical, high-leverage tools for automating utility workflows.

List Plug Credentials

Retrieves the status of all configured utility provider connections. This is the starting point for any diagnostic workflow, allowing the agent to check if a credential requires MFA or human intervention.

Get Normalized Meter Intervals

Fetches time-series, 15-minute granular energy data for a specific meter. This is essential for solar and storage modeling, demand response validation, and deep facility analytics.

List Discovered Statements

Queries Arcadia for newly discovered utility statements across accounts. This tool allows an agent to autonomously audit incoming bills before they are processed by accounts payable.

Upload Statement PDF for OCR

Uploads raw utility bill PDFs directly to Arcadia's system for optical character recognition processing. This turns unstructured physical or digital mail into structured data.

Update Plug Credential One-Time Passcode

Submits an MFA token for a credential's current verification job. This tool is critical for human-in-the-loop workflows where the agent requests an SMS code from a user and submits it back to the utility.

Prepare Intervals CSV Download

Initiates the first step of Arcadia's asynchronous 2-step download process for large meter interval datasets. It returns the URL needed to poll for the completed file.

To view the complete inventory of available endpoints and their schema structures, visit the Arcadia integration page.

Workflows in Action

Exposing tools is only half the battle. The true value of AI agents emerges when they chain multiple complex Arcadia API calls together to solve domain-specific problems autonomously.

Scenario 1: Auditing Facility Energy Consumption

A facility manager wants to investigate power usage anomalies for a specific site over the weekend. Instead of clicking through dashboards, they prompt the agent directly.

Scenario 2: Autonomous MFA Remediation

Utility portals frequently force password resets or trigger MFA challenges, silently breaking data pipelines. An IT admin wants the system to handle this proactively.

Building Multi-Step Workflows

To build these workflows, you need a framework-agnostic approach. While Model Context Protocol (MCP) is gaining popularity for local agent environments, production-grade enterprise SaaS applications typically rely on cloud-hosted frameworks like LangChain, Vercel AI SDK, or custom procedural loops.

Truto abstracts the complexity by mapping Arcadia's endpoints into REST-based CRUD proxy methods. You simply call the /tools endpoint to retrieve them.

Handling Rate Limits in the Agent Loop

As previously stated, Truto does not absorb rate limits. If your agent rapidly loops through 500 meters to pull intervals, Arcadia will return an HTTP 429. Truto passes this 429 back to your application, alongside standardized ratelimit-reset headers.

Your agent execution layer must catch this error, read the header, sleep the thread, and retry. If you rely on basic framework retry defaults, your agent will likely crash or hallucinate a success state.

TypeScript Implementation with LangChain

Here is a complete architectural example of how to fetch Arcadia tools from Truto, handle Truto's standardized rate limit headers, and bind the tools to an LLM using LangChain.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import {
  ChatPromptTemplate,
  MessagesPlaceholder,
} from "@langchain/core/prompts";
// Assuming a custom wrapper or Truto SDK that fetches from /integrated-account/:id/tools
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function buildArcadiaAgent() {
  const TRUTO_API_KEY = process.env.TRUTO_API_KEY;
  const ARCADIA_ACCOUNT_ID = process.env.ARCADIA_ACCOUNT_ID;
 
  // 1. Initialize the Tool Manager
  const toolManager = new TrutoToolManager({
    apiKey: TRUTO_API_KEY,
  });
 
  // 2. Fetch the tools dynamically from Truto's API
  const arcadiaTools = await toolManager.getTools(ARCADIA_ACCOUNT_ID);
 
  // 3. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Create the Prompt with instructions for asynchronous polling
  const prompt = ChatPromptTemplate.fromMessages([
    [
      "system",
      `You are an elite utility data analyst. You have access to Arcadia via API tools.
      
      CRITICAL INSTRUCTIONS FOR ASYNC DOWNLOADS:
      When you use tools like 'create_a_arcadia_downloads_interval', the API will return a 202 Accepted and a URL/ID.
      You MUST then use the corresponding polling tool repeatedly until it returns the actual data payload.`,
    ],
    ["human", "{input}"],
    new MessagesPlaceholder("agent_scratchpad"),
  ]);
 
  // 5. Bind tools and create the agent
  const agent = await createOpenAIToolsAgent({
    llm,
    tools: arcadiaTools,
    prompt,
  });
 
  // 6. Wrap execution in a custom rate limit handler
  const executor = new AgentExecutor({
    agent,
    tools: arcadiaTools,
  });
 
  return async (input: string) => {
    let attempts = 0;
    const maxAttempts = 3;
 
    while (attempts < maxAttempts) {
      try {
        const result = await executor.invoke({ input });
        return result;
      } catch (error: any) {
        if (error.status === 429) {
          attempts++;
          const resetTimeStr = error.headers['ratelimit-reset'];
          const resetTime = resetTimeStr ? parseInt(resetTimeStr, 10) : 5;
          await new Promise((resolve) => setTimeout(resolve, resetTime * 1000));
          continue;
        }
        throw error;
      }
    }
    throw new Error("Max retry attempts exceeded after rate limits.");
  };
}

Architecting the Asynchronous Workflow Loop

To visualize how the LLM orchestrates Arcadia's specific two-step polling architecture, consider the following interaction sequence. The LLM acts as the orchestrator, making sequential decisions based on the HTTP status codes returned via Truto.

sequenceDiagram
    participant Agent as AI Agent
    participant Truto as Truto Proxy Layer
    participant Arcadia as Upstream API (Arcadia)

    Agent->>Truto: Call create_a_arcadia_downloads_interval(meterIds)
    Truto->>Arcadia: POST /downloads/intervals<br>Payload: meterIds
    Arcadia-->>Truto: 202 Accepted<br>Body: { url: ".../downloads/12345" }
    Truto-->>Agent: Returns Tool Output (ID: 12345)
    
    Note over Agent: Agent parses system prompt, knows to poll
    
    loop Polling until 200 OK
        Agent->>Truto: Call list_all_arcadia_download_sources(12345)
        Truto->>Arcadia: GET /downloads/intervals/12345
        
        alt Still Processing
            Arcadia-->>Truto: 202 Accepted (Processing)
            Truto-->>Agent: Tool Output: Processing...
        else File Ready
            Arcadia-->>Truto: 200 OK (CSV Stream)
            Truto-->>Agent: Tool Output: CSV Data
        end
    end

Strategic Architecture for Utility Data

Connecting AI agents to Arcadia is not about writing standard HTTP wrappers. It is about managing the complex realities of utility data: asynchronous reporting, deeply nested meter hierarchies, and fragile MFA connections.

By leveraging Truto's /tools endpoint, you bypass the need to manually build, host, and maintain massive JSON schemas for Arcadia. You expose proxy APIs directly to your LLM framework of choice, enforce strict rate limit handling at the execution layer, and allow the agent to traverse energy data autonomously.

Stop hand-coding SaaS API wrappers and start shipping autonomous agents.