How to Build an AI Agent for Pylon (2026)

What a Pylon AI agent does

The loop is the same as any support agent, wired to Pylon: a new issue arrives → the agent reads it and the account's history → it calls tools (look up the account, search your help center, check a policy) → it posts a reply as a message or routes the issue to a human. The trick is doing that reliably against real issues. (New to agents generally? Start with AI agents for customer service.)

Option 1: Build it against the Pylon API

Pylon has a full REST API, so you can build the agent yourself. The pieces:

• Read issues — the Issues API (GET /issues and GET /issues/{id}) to pull the issue, its messages, and the account.
• Reply / act — post a message to the issue or update it via PATCH /issues/{id}.
• Trigger on new issues — a Pylon webhook fires your endpoint when an issue is created.

A reply-and-tag tool against the real Pylon API looks like this:

import requests
PYLON = "https://api.usepylon.com"
HEADERS = {"Authorization": f"Bearer {PYLON_TOKEN}"}

def reply_to_issue(issue_id: str, body: str):
    # post a message on the issue
    m = requests.post(f"{PYLON}/issues/{issue_id}/messages",
        json={"body_html": body}, headers=HEADERS, timeout=10)
    m.raise_for_status()          # handle 429 rate limits, token refresh
    # and, e.g., mark it as needing a human next
    requests.patch(f"{PYLON}/issues/{issue_id}",
        json={"state": "waiting_on_you"}, headers=HEADERS, timeout=10)
    return {"status": "sent"}

Wrap that (and a get_account, a search_help_center) as tools in an agent loop on the model of your choice — see our from-scratch walkthrough in how to build an AI agent: from scratch vs. platform. Full endpoint specs are in Pylon's API docs.

Auth and rate limits. Pylon's API authenticates with a bearer API token (Authorization: Bearer <token>) minted in your Pylon settings — a workspace-scoped credential, so treat it like a secret and rotate it, not per-user OAuth. Like every support API, Pylon rate-limits requests and returns HTTP 429 when you exceed the ceiling; the published limits can change, so read the Pylon API docs for the current numbers rather than trusting a figure hardcoded in a blog post. Practically, that means every call needs a retry-with-backoff wrapper (honor Retry-After when it's present, exponential backoff otherwise), and a bulk backfill — say, embedding a year of issues for evals — has to be paced so it doesn't trip the limit mid-run. Budget for it now; it's the difference between a demo and something that survives a Monday-morning spike.

The production part

The API calls are the easy bit; making the agent run on real issues is the work. You stand up a webhook to trigger the agent, and it has to verify Pylon's signature and dedupe retries so one issue never gets two replies. Here's the handler that does exactly that — signature check first, idempotency second, then the agent:

import hashlib, hmac, os
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = os.environ["PYLON_WEBHOOK_SECRET"].encode()
seen: set[str] = set()   # use Redis/DB in prod, not an in-memory set

def verify_pylon_signature(raw: bytes, sig: str):
    # HMAC-SHA256 over the exact raw request body
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig or ""):
        raise HTTPException(status_code=401, detail="bad signature")

@app.post("/pylon-webhook")
async def on_issue(req: Request):
    raw = await req.body()                       # verify BEFORE parsing JSON
    verify_pylon_signature(raw, req.headers.get("X-Pylon-Signature"))
    event = (await req.json())["data"]
    issue_id, delivery = event["id"], req.headers.get("X-Pylon-Delivery-Id", event["id"])
    if delivery in seen:                         # idempotency — Pylon retries on timeout/5xx
        return {"ok": True, "dedup": True}
    seen.add(delivery)
    run_agent(issue_id)                          # ideally enqueue; ack fast so Pylon won't retry
    return {"ok": True}

Two things earn their keep here. The signature check runs over the raw body before you parse JSON (re-serializing changes the bytes and breaks the HMAC), and it rejects anything unsigned — because your endpoint is public and issue text is attacker-controllable input. The idempotency guard keys off the delivery ID, not the issue ID, so a retried delivery of the same event is dropped while a genuinely new event on the same issue still runs. In production that seen set lives in Redis or your database with a TTL, and you'll want to ack the webhook fast (enqueue the work) so a slow model call doesn't push Pylon past its timeout and trigger a duplicate delivery.

Then the rest: rate-limit handling (Pylon throttles the API, so you back off on 429s as above), grounding in your help center (embed the articles and re-index when they change), guardrails (escalate refunds, redact PII, treat issue text as untrusted input), hosting 24/7, observability so you can see what every run did, and an eval harness that replays real historical issues so you can measure quality before customers do. That's weeks of work plus permanent upkeep — the undifferentiated infrastructure every support agent needs, none of it specific to your product.

What about Pylon's own AI?

Pylon is a modern B2B support platform built for the shared-Slack-channel, high-touch accounts that engineering-heavy teams run — and it ships its own AI features. So before you write a line of code, be honest about which of three routes you actually want:

• Pylon's native AI — the fastest no-code path: you stay on Pylon's model and settings, and it's a fine fit if that covers your cases. Least control, least effort.
• Build on the Pylon API yourself — you need a specific model, custom tools wired to your own systems (accounts, billing, provisioning), or full control of the runtime, and you have the engineering to own it. Most control; weeks to build plus permanent upkeep — the webhook, hosting, evals, and maintenance above.
• Connect a model-agnostic platform (Macha) — the control and model choice of building, but live in days instead of weeks, with the webhook, hosting, observability, and eval harness handled for you. Macha is the AI layer on top of Pylon, not a replacement for it.

The rest of this guide is about the second and third routes — where you want more than Pylon's native automation gives you, whether that's a different model, deeper tool access, or your own grading loop.

Option 2: Connect Pylon via Macha

If the goal is a working agent on your Pylon — not a project to maintain — a platform that connects natively is far faster. Macha layers on top of Pylon (it's not a Pylon replacement or a marketplace app you install — it connects via OAuth/API and works autonomously):

• Native connector — Macha's Pylon connector authorizes once, and the agent can read issues and post replies with a full set of issue tools ready to use.
• Ground on your knowledge — add your help center, Confluence, Google Workspace, or website as a Source so replies quote real articles instead of guessing.
• Any other system as a tool — Custom Tools turn your order/billing/CRM APIs into agent capabilities by describing them; no glue code to host.
• Grade before go-live — the agent runs in the cloud triggered by new issues, and Studies batch-evaluate it against real historical issues — scoring the drafted replies before it ever touches a customer.

Because the connector is native, you skip the webhook, retries, and hosting entirely — Macha handles the trigger and the run.

Build vs. connect — for Pylon

So which should you build?

Build on the API if you need a fully custom runtime, have strict data-residency needs, or the agent is your product. For most Pylon teams who just want issues resolved, a native connector gets you a measurable agent on your real issues far faster — and you keep your model of choice. You can start free on Macha, connect Pylon, and test an agent on your own issues the same day.

FAQ

Is a Pylon AI agent the same as Pylon's built-in AI? Not necessarily. Pylon offers built-in AI, but you can also run a model-agnostic agent on top of Pylon (via its API or a platform like Macha) — useful if you want a specific model, custom tools, or to grade the agent your own way.

Do I need to install a Pylon marketplace app? No — Macha connects to Pylon via OAuth/API and works autonomously; it's an AI layer on top of Pylon, not a marketplace app you install.

Can the agent take actions, not just answer? Yes — via the Pylon API (update, tag, change state) plus your own systems' APIs as tools (account lookups, refunds) via Custom Tools, with guardrails on what it can do unattended.

How do I make sure it's accurate before it replies to customers? Ground it in your help center and grade it against real historical issues first (Macha's Studies do this), start in a draft/approve mode, and widen autonomy per issue type as it earns trust.