Connect Nango to AI Agents: Automate Syncs & Proxy Requests

You want to connect Nango to an AI agent so your system can independently orchestrate integration workflows, trigger data syncs, manage connect sessions, and route complex requests through the Nango proxy. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to write custom boilerplate to expose Nango's API surface to your Large Language Model (LLM).

If your team uses ChatGPT, check out our guide on connecting Nango to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Nango to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools, inject them into your context window, and bind them natively to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Nango, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute meta-integration operations. We are essentially giving an agent control over your integration infrastructure. For a deeper look at the theory and architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of Custom Nango Connectors

Building AI agents is straightforward when you are prototyping. Connecting them to a complex external infrastructure API like Nango is a completely different engineering reality. If you decide to hand-code this connection, you assume responsibility for the entire API lifecycle, and you immediately run into a few integration challenges highly specific to Nango that break standard LLM assumptions.

Nango is an integration platform itself. When you ask an LLM to control Nango, you are essentially asking it to orchestrate meta-integrations. This introduces significant cognitive overhead for the model.

The Tripartite ID Matrix

Standard REST APIs rely on simple primary keys. Nango's architecture relies on a highly specific matrix of identifiers: connection_id (the specific user's authentication), provider_config_key (the configuration for the external SaaS), and unique_key (the identifier for an integration deployment).

If you hand-code individual tools for Nango, the LLM has to perfectly recall which endpoint requires which combination of IDs. When the model hallucinates a connection_id into a provider_config_key field, the API rejects the request. A unified tool layer enforces strict JSON schemas for every tool, ensuring that the LLM is forced to provide the exact right ID parameter before the network request is ever dispatched.

The Opaque Proxy Problem

Nango's proxy endpoints (/proxy) are incredibly powerful, allowing you to forward requests to external APIs using managed credentials. However, to an LLM, a proxy endpoint is a black box. The payload it needs to construct for a POST request via Nango Proxy depends entirely on the upstream SaaS provider's schema, not Nango's schema.

If you expose raw fetch functions to the LLM, it struggles to differentiate between "Nango's API structure" and "the external API structure". Providing well-typed, specific proxy tools forces the LLM to structure the any_path and payload correctly, separating the transport layer (Nango) from the execution layer (the upstream SaaS).

Connection Metadata State

Nango allows you to store custom metadata on connections. But the API provides both legacy full-replacement endpoints and modern bulk-update (patch) endpoints. If an LLM uses a legacy PUT endpoint to update a single metadata tag, it will inadvertently wipe out all other existing metadata on that connection. By wrapping Nango's API in strict, validated tools, we expose only the safe nango_connections_bulk_update endpoint, preventing the LLM from accidentally destroying state.

High-Leverage Nango Tools for AI Agents

To build a highly capable agent, you do not need to give it access to every single Nango endpoint. You need to provide it with high-leverage primitives. Below are the six hero tools that enable the majority of autonomous integration management workflows.

create_a_nango_connect_session

This tool allows the agent to provision a short-lived (30 minute) connect session for the Connect UI auth flow. It returns a token and a connection link. This is critical for agents that interact with end-users and need to prompt them to authenticate a new SaaS app.

"Generate a new Nango connect session for the Salesforce integration and tag it with the user's internal ID so we can send them the authorization link."

nango_sync_trigger

This tool allows the agent to bypass scheduled syncs and force a one-off execution of specific data models for a given connection. This is highly useful for agents that need the absolute latest data before making a decision.

"Trigger an immediate sync for the 'tickets' data model on the Zendesk connection for customer ID 8849, then let me know when it starts."

list_all_nango_records

After an agent triggers a sync, it needs to read the data. This tool lists the synced records from Nango's managed storage for a given data model, returning the structured payloads.

"Fetch the latest 50 synced records from the 'contacts' model for connection ID usr_123 and summarize the recently added entries."

create_a_nango_proxy

This is the workhorse for autonomous operations. It forwards a POST request with a JSON body to an external API through the Nango Proxy. The agent uses this to write data back to the upstream SaaS without managing the OAuth tokens itself.

"Using the Nango proxy for the HubSpot provider configuration, send a POST request to '/crm/v3/objects/contacts' to create a new contact with the email provided in the chat."

nango_connections_bulk_update

Agents often need to tag connections with specific states (e.g., 'needs_review', 'sync_failed', 'premium_tier'). This tool allows the agent to safely patch custom metadata for one or more connections without overwriting existing keys.

"Update the metadata for connection ID 9938 to set the 'sync_status' property to 'paused' without changing any of the other existing metadata tags."

nango_functions_create_deployment

For advanced DevOps agents, this tool deploys a function to an existing Nango integration using submitted TypeScript source code. It allows the agent to autonomously update integration logic.

"Deploy the updated data transformation script to the 'salesforce_sync' integration and monitor the deployment status."

For the complete tool inventory and detailed JSON schema definitions for each endpoint, visit the Nango integration page.

Workflows in Action

When you combine these tools into an agentic loop, the LLM can execute complex operations that would normally require a human support engineer or a hardcoded cron job. Here are three concrete examples of what this looks like in practice.

1. Autonomous Connection Auditing and Tagging

Integration health monitoring is tedious. You can deploy an agent to audit connection states and tag them appropriately based on recent activity.

"Check all current Nango connections. Find any connections where the last fetched date is older than 30 days, and update their metadata to include a 'status: stale' tag."

Execution Steps:

1. The agent calls list_all_nango_connection to retrieve the list of all active connections and their metadata.
2. The agent processes the JSON response in its context, filtering out connections where last_fetched_at is beyond the 30-day threshold.
3. The agent calls nango_connections_bulk_update passing the array of stale connection_ids, the required provider_config_key, and the payload {"status": "stale"} to patch the metadata safely.

Result: The system automatically flags stale connections without any manual database queries, allowing your customer success team to follow up.

2. On-Demand Data Sync and Record Pruning

Sometimes an agent needs fresh context before answering a user query, but storing stale data wastes database rows. The agent can trigger a sync, read the data, and clean up after itself.

"I need the latest invoice data from Xero for connection ABC. Trigger a sync, read the new records, and then prune the record payload to save space."

Execution Steps:

1. The agent calls nango_sync_trigger for connection_id ABC and the specific invoice sync name.
2. The agent (using a built-in delay or status polling) waits for completion, then calls list_all_nango_records targeting the invoice model to read the fresh data into its context window.
3. After processing the answer for the user, the agent calls nango_records_prune to empty the record payloads from Nango's database while preserving the metadata.

Result: The user gets an answer based on real-time data, and your Nango database footprint remains optimized, completely autonomously.

3. External API Proxy Mutations

Agents often need to take action in external systems. Instead of building specific connectors, the agent can use Nango's proxy to execute arbitrary downstream actions.

"The user wants to create a new task in Asana. Use their Nango connection to proxy a request to Asana's API to create a task called 'Review Q3 Metrics'."

Execution Steps:

1. The agent parses the user's intent and formulates the correct Asana API payload (knowing Asana expects {"data": {"name": "Review Q3 Metrics"}}).
2. The agent calls create_a_nango_proxy, specifying the any_path as /tasks and providing the structured JSON body.
3. Nango injects the correct Bearer token for that specific connection and forwards the request. Nango returns the raw 201 Created response to the agent.

Result: The agent successfully modifies external state without ever seeing or handling the raw OAuth credentials.

Building Multi-Step Workflows

To make this operational in a production environment, you need to bind these proxy APIs to your agent framework. Truto handles the authentication, schema normalization, and routing, but your code controls the execution loop.

Using the truto-langchainjs-toolset, fetching and binding Nango tools takes just a few lines of code. This example demonstrates how to initialize the tools and pass them to an OpenAI model within LangChain.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
async function runNangoAgent() {
  // 1. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 2. Fetch Nango tools from Truto for your specific Integrated Account
  const truto = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
  });
  
  const nangoTools = await truto.getTools(process.env.NANGO_INTEGRATED_ACCOUNT_ID);
 
  // 3. Set up the agent prompt
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an infrastructure agent that manages Nango integrations. You use the provided tools to trigger syncs, manage connections, and execute proxy requests."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 4. Bind tools and create the executor
  const agent = createToolCallingAgent({
    llm,
    tools: nangoTools,
    prompt,
  });
 
  const agentExecutor = new AgentExecutor({
    agent,
    tools: nangoTools,
  });
 
  // 5. Execute the autonomous workflow
  const result = await agentExecutor.invoke({
    input: "Check if connection 'usr_99' has any stale data, and if so, trigger a sync for the 'users' model.",
  });
 
  console.log(result.output);
}
 
runNangoAgent();

Handling Rate Limits and Upstream Errors

When building autonomous loops, error handling is the difference between a resilient agent and a broken system. Nango, and the downstream APIs it connects to, enforce rate limits.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API (like Nango or the external SaaS via proxy) returns an HTTP 429 Too Many Requests, Truto passes that error directly back to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification.

The caller - your agent framework or application infrastructure - is strictly responsible for inspecting these headers, pausing execution, and applying retry or exponential backoff logic.

Here is exactly how that architecture looks in practice:

sequenceDiagram
  participant Agent as AI Agent Infrastructure
  participant Truto as Truto Tools Layer
  participant Nango as Nango API
  
  Agent->>Truto: Call nango_sync_trigger tool
  Truto->>Nango: POST /sync/trigger
  Nango-->>Truto: 429 Too Many Requests
  Truto-->>Agent: 429 Error (with ratelimit-reset header)
  Note over Agent: Agent catches exception<br>Parses ratelimit-reset<br>Sleeps for required duration
  Agent->>Truto: Retry nango_sync_trigger tool
  Truto->>Nango: POST /sync/trigger
  Nango-->>Truto: 200 OK
  Truto-->>Agent: Success Response

If you do not implement this loop, your agent will immediately fail upon hitting a rate limit, or worse, hallucinate a success state because the tool call crashed. Modern agent frameworks like LangGraph allow you to route errors back into the agent's context, letting the LLM decide to wait or attempt a different action.

Framework Agnostic Execution

Because Truto exposes Nango operations as standardized JSON schemas via the /tools endpoint, you are not locked into LangChain. If your engineering team prefers the Vercel AI SDK for edge-deployed streaming apps, or CrewAI for multi-agent orchestration, the exact same underlying schemas apply. The unified tool layer abstracts away the complex REST semantics of the Nango API, transforming integration operations into predictable function calls.

Moving Beyond Hardcoded Orchestration

The standard approach to managing complex integration infrastructure involves writing hundreds of lines of procedural code: polling loops, cron jobs, and fragile error handlers. By mapping Nango's API surface into discrete, schema-validated tools, you unlock a fundamentally different paradigm.

You can now deploy agents that monitor connection health, dynamically provision proxy requests, and resolve sync failures based on semantic understanding of the system's state. You stop writing integration maintenance scripts, and start instructing infrastructure agents.