Connect Extole to AI Agents: Automate Fulfillment, Events & Batches

You want to connect Extole to an AI agent so your system can independently launch referral campaigns, process custom reward fulfillments, trigger consumer events, and manage asynchronous batch operations. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to hand-code complex API wrappers for a marketing platform.

Giving a Large Language Model (LLM) read and write access to your Extole instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that navigates Extole's specific campaign state machines, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Extole to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Extole 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 Extole, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex marketing operations 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 Extole Connectors

Building AI agents is easy. Connecting them to external SaaS APIs is hard. Giving an LLM access to external marketing data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production, this approach collapses entirely, especially with a specialized ecosystem like Extole.

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

The Reward State Machine Trap

Unlike a simple CRM contact, Extole Rewards do not operate on basic CRUD principles. A reward transitions through a rigid state machine (e.g., EARNED, FULFILLED, CANCELED, REVOKED). An AI agent cannot simply send a DELETE /rewards/:id request if a customer cancels a referral. It must understand the current state, determine if the reward is eligible for revocation, and submit a highly specific payload to a dedicated state-transition endpoint (like /api/v4/rewards/:id/revoke). When the LLM inevitably hallucinates a state transition - trying to fulfill a canceled reward - the integration fails.

Asynchronous Batch Jobs and Polling

Extole relies heavily on asynchronous batch processing for large-scale operations (like importing manual coupons or evaluating massive audiences). The API often returns a polling_id or batch_id instead of the actual data. An LLM lacks the inherent temporal awareness to gracefully back off and poll an endpoint for 30 seconds. If you hand-code this, you have to build complex orchestration logic to pause the agent, poll the Extole API, and wake the agent back up when the state reaches DONE or FAILED.

Truto's Rate Limit Contract

AI agents are notoriously aggressive API consumers. A single user prompt like "Audit all 50 of our live campaigns and check their components" can trigger dozens of concurrent network requests.

Here is a critical architectural fact: Truto does not automatically retry, throttle, or absorb rate limit errors. When the upstream Extole API throws an HTTP 429 (Too Many Requests), Truto passes that 429 directly back to your agent. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This allows your agent's orchestration framework to implement deterministic, standard exponential backoff without parsing vendor-specific error payloads.

Why a Unified Tool Layer Matters for Agent Safety

Direct API tools (one tool per raw Extole endpoint) look convenient but they push provider quirks into the LLM's context. The model has to remember that Extole identity payloads require specific partner_user_id structures, or that campaign launches require specific version parameters. Every one of those quirks is a hallucination waiting to happen.

Truto maps Extole's endpoints into Resources and Methods, wrapping them in Proxy APIs. We then serve these via the /tools endpoint, giving you three concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from stable function names. It never invents query parameters or payload structures.
2. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit the Extole API, so a broken tool call fails fast.
3. Real-time updates. If Extole updates a required field, the Truto UI updates the JSON schema, and your agent gets the new schema dynamically on the next /tools fetch. No code changes required.

Hero Tools for Extole Marketing Operations

To build a highly capable Extole agent, you don't need to give it access to all 300+ endpoints. You only need to bind the highest-leverage operations. Here are the core "hero tools" to expose to your LLM.

1. create_a_extole_person_shareable

This tool allows the agent to generate a unique referral link or code for a specific person. This is crucial for agents operating in customer support or sales contexts where they need to instantly provision a referral code for a high-value customer.

"Generate a new referral shareable code for person ID 849201 and return the program URL so I can email it to them."

2. create_a_extole_event

This is the workhorse of Extole integrations. It allows the agent to submit a synchronous consumer event (such as a purchase, a signup, or a custom milestone) to the Extole platform. This triggers campaign controllers and potentially issues rewards.

"Log a 'premium_upgrade' event for email 'jane.doe@example.com' with a transaction value of $150.00."

3. create_a_extole_custom_reward_fulfilled

When your system handles fulfillment externally (like issuing a physical gift or an internal account credit), the agent uses this tool to close the loop in Extole, signaling that the reward was successfully delivered.

"Find reward ID 99281. It has been provisioned in our billing system. Mark the custom reward as fulfilled and include the message 'Account credited'."

4. extole_rewards_list_history

Because rewards operate on complex state machines, agents need context on what happened to a reward before modifying it. This tool provides the state-transition history (e.g., when it was earned, when it failed).

"Check the history of reward ID 44123. If it failed fulfillment yesterday, tell me the error message before we try to retry it."

5. create_a_extole_batch

For heavy lifting, agents can initiate asynchronous batch jobs. This tool creates a job that reads a data source row-by-row and dispatches consumer events.

"Start a new batch job using file ID 8831 to process the historical offline conversion events. Give me the batch ID so we can track its status."

6. create_a_extole_campaign_launch_burst

Agents can manage campaign lifecycles. This tool transitions a campaign version into a high-throughput burst mode, validating all components and reward rules before making it live for a time-limited promotional surge.

"Take campaign ID 55102, version 3, and launch it in burst mode for the flash sale starting now."

For the complete inventory of Extole tools, including schema definitions for audiences, webhooks, analytics, and SSO configuration, visit the Extole integration page.

Workflows in Action

How do these tools compose into actual agentic workflows? Here are two real-world sequences.

Scenario 1: Autonomous Reward Troubleshooting & Fulfillment

Customer support agents frequently deal with "Where is my referral bonus?" tickets. An AI agent can autonomously investigate and resolve these.

"Investigate the referral reward status for person ID 112233. If they earned a custom reward that is stuck in a PENDING or FAILED state, mark it as fulfilled and log a note that support intervened."

Execution Steps:

1. The agent calls list_all_extole_person_rewards passing the person_id.
2. The agent inspects the array of rewards. It identifies a reward with the state FAILED.
3. The agent calls extole_rewards_list_history to retrieve the failure reason for context.
4. Seeing it was a temporary API timeout on the client side, the agent calls create_a_extole_custom_reward_fulfilled with the reward_id and a success message, clearing the queue.

Scenario 2: High-Volume Event Ingestion via Batch

Marketing teams often drop large CSVs of offline conversions that need to be processed through the referral engine.

"Upload the new offline conversions dataset to Extole and start a batch processing job for the 'offline_purchase' event."

Execution Steps:

1. The agent calls create_a_extole_file to upload the raw data and receives a file_id.
2. The agent calls create_a_extole_batch, passing the file_id as the data source and specifying the offline_purchase event.
3. The agent receives the batch_id with a PENDING status, allowing the external orchestration framework to monitor it.

sequenceDiagram
    participant Agent as AI Agent
    participant Truto as Truto /tools
    participant Extole as Extole API

    Agent->>Truto: call create_a_extole_file (CSV data)
    Truto->>Extole: POST /v2/files
    Extole-->>Truto: file_id: 8812
    Truto-->>Agent: Returns file_id
    
    Agent->>Truto: call create_a_extole_batch (file_id)
    Truto->>Extole: POST /v2/batches
    Extole-->>Truto: batch_id: 9942, status: PENDING
    Truto-->>Agent: Returns batch details
    
    Note over Agent,Extole: Agent hands batch_id back to user/system for polling

Building Multi-Step Workflows

To build this in code, you need an orchestration framework. We will use LangChain.js, leveraging the truto-langchainjs-toolset to fetch the Extole tools dynamically.

Crucially, we must handle rate limits. As mentioned, Truto passes upstream HTTP 429s directly to you, accompanied by IETF-standard rate limit headers. We will wrap our agent invocation in a retry utility that respects the ratelimit-reset header.

Step 1: Initialize the Tool Manager and Fetch Tools

First, we authenticate with Truto and fetch the tools for our specific Extole integrated account.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
 
// Initialize the Truto SDK with your developer token
const trutoManager = new TrutoToolManager({
  apiKey: process.env.TRUTO_API_KEY,
});
 
async function buildAgent() {
  // Fetch Extole tools. You can filter by 'methods' if you only want read/write.
  const tools = await trutoManager.getTools(
    process.env.EXTOLE_INTEGRATED_ACCOUNT_ID
  );
 
  const llm = new ChatOpenAI({
    modelName: "gpt-4-turbo",
    temperature: 0,
  });
 
  // Define the agent's system prompt
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a marketing operations assistant managing the Extole referral platform. Execute tasks safely and efficiently."],
    ["human", "{input}"],
    new MessagesPlaceholder("agent_scratchpad"),
  ]);
 
  const agent = await createOpenAIToolsAgent({
    llm,
    tools,
    prompt,
  });
 
  return new AgentExecutor({
    agent,
    tools,
  });
}

Step 2: Implement IETF-Compliant Rate Limit Handling

Because an agent might trigger dozens of requests when searching through audiences or reward histories, it will inevitably hit Extole's rate limits. Here is how you capture the 429 error and use Truto's standardized headers to back off.

/**
 * Executes the agent and automatically retries if a 429 Too Many Requests is encountered.
 * Uses Truto's normalized ratelimit-reset header to calculate the wait time.
 */
async function executeWithRateLimitRetry(executor: AgentExecutor, input: string, maxRetries = 3) {
  let attempts = 0;
 
  while (attempts < maxRetries) {
    try {
      const result = await executor.invoke({ input });
      return result;
    } catch (error: any) {
      if (error.response?.status === 429) {
        attempts++;
        
        // Truto normalizes upstream headers to the IETF specification
        const resetTimeSecs = parseInt(error.response.headers['ratelimit-reset'] || "60", 10);
        
        // Calculate wait time in milliseconds, adding a 500ms buffer
        const waitTimeMs = (resetTimeSecs * 1000) + 500;
        
        console.warn(`[429 Rate Limit Hit] Retrying in ${waitTimeMs}ms... (Attempt ${attempts} of ${maxRetries})`);
        
        await new Promise(resolve => setTimeout(resolve, waitTimeMs));
      } else {
        // Re-throw if it is not a rate limit error (e.g., 400 Bad Request, 401 Unauthorized)
        throw error;
      }
    }
  }
  throw new Error("Max retries reached due to rate limits.");
}
 
// Usage:
(async () => {
  const agentExecutor = await buildAgent();
  const task = "Find the pending referral reward for person_id 98765 and mark it as fulfilled with the message 'Approved via Support Agent'.";
  
  const response = await executeWithRateLimitRetry(agentExecutor, task);
  console.log("Agent Response:", response);
})();

flowchart TD
    A["Agent Execution"] --> B{"API Call via Truto"}
    B -->|"Success (200)"| C["Return Data to Agent"]
    B -->|"Rate Limit (429)"| D["Truto passes 429 + <br>ratelimit-reset header"]
    D --> E["executeWithRateLimitRetry()"]
    E -->|"Wait X seconds"| A

The Strategic Advantage of Unified Tools

Building an AI agent that can reliably operate marketing automation platforms requires more than just API keys and raw HTTP clients. The underlying API complexities - like Extole's rigid reward state machines, heavy reliance on asynchronous batching, and strict rate limits - will break naive agent implementations almost instantly.

By leveraging Truto's /tools endpoint, you abstract away the API maintenance layer. Truto handles the schema generation, pagination processing, and header normalization, giving your LLM a stable, deterministic set of functions to call. You retain absolute control over the orchestration and retry logic, ensuring your system behaves safely at scale.