Building agents on Plain

Build a support agent on Plain, or connect one you already have, using the same API your team’s app uses.

Plain is designed to be a great home for agents. You can build your own customer support agent using whatever AI stack you prefer and have it work alongside your team in the same threads, with the same tools, and the same audit trail as everyone else.

These docs are about the plumbing of building an agent on Plain: how it gets an identity, how it receives events, how it decides when to act, and how it replies. The AI part (e.g. model choice, prompts, RAG, tool use) is up to you.

To chat about support data with a local agent, the MCP server is the fastest way to get a model talking to Plain. This guide is about building autonomous agents within Plain.

What an agent looks like in Plain

An agent in Plain is made of three pieces:

A machine user

The agent’s identity in Plain. Has a public name, an avatar, and one or more API keys.

A webhook listener

A public HTTPS endpoint that receives Plain events like new threads, incoming messages, and assignment changes.

A GraphQL client

Makes calls back to Plain to read threads, reply, change assignment, add labels, create notes, and more.

When something happens in Plain (a customer sends an email, a user assigns a thread), Plain delivers a webhook to your endpoint. Your code decides whether the agent should act and uses the GraphQL API to do whatever it does: read context, reply, label, summarize, hand off, post a note, anything else.

Agents come in many shapes. Some reply to every new thread; some only act when assigned; some never reply at all and only classify, summarize, or post internal notes. The building blocks below are the same regardless of what your agent does.

Two journeys

There are two places an agent can work in Plain, and they share only an identity and your knowledge sources. Pick the one you are building; the pages below are each complete on their own.

1. Create a machine user

   Both journeys start here. A machine user is the agent’s identity in Plain, with a public name, an avatar, and one or more API keys.

   Set up a machine user →

2. Build a support agent, working customer threads

   Your agent receives thread events, decides which threads are its own, reads it, and replies, labels, notes, or hands off to a person. One page covers identity through to the actions it takes.

   Build a support agent →

3. Or build an internal agent, answering your team

   Your team asks your agent questions inside Plain, where they ask Sidekick. It reports its progress and tool calls, and can put an approval in front of a person before it acts.

   Build an internal agent →

4. Ground it in your own content

   Either agent can search your Help Center articles and indexed documents so its answers come from real content.

   Search knowledge sources →

A minimal example

Here’s one possible shape: an agent that replies to every new thread. It uses Express, but the same shape works with any HTTP framework. Your own agent will likely do something different in the handler.

import express from "express";
import { verifyPlainWebhook } from "@team-plain/webhooks";
import { PlainClient } from "@team-plain/graphql";

const plain = new PlainClient({ apiKey: process.env.PLAIN_API_KEY! });

const app = express();
app.use(express.text({ type: "*/*" })); // we need the raw body for signature verification

app.post("/webhooks/plain", async (req, res) => {
  const result = verifyPlainWebhook(
    req.body,
    req.header("plain-request-signature")!,
    process.env.PLAIN_WEBHOOK_SECRET!,
  );

  if (result.error) {
    return res.status(400).send(result.error.message);
  }

  const event = result.data;

  if (event.payload.eventType === "thread.thread_created") {
    const reply = await generateReply(event.payload.thread); // your AI goes here

    await plain.mutation.replyToThread({
      input: {
        threadId: event.payload.thread.id,
        textContent: reply,
      },
    });
  }

  res.sendStatus(200);
});

app.listen(3000);

Replace generateReply with whatever AI library you prefer, like the Vercel AI SDK, Anthropic SDK, OpenAI SDK, or your own.

What’s next

Machine users

Create the agent’s identity and API key.

Support agent

Webhooks, routing, reading threads, and the five actions, in order.

Internal agent

Answer your own team in a Sidekick discussion, with an approval gate.

Searching knowledge

Ground replies in your Help Center and indexed documents.

Agent integrations

Connect Plain to your editor or a local AI assistant instead.