Writing a plugin tool
For a tenant project that needs the agent to do something config/tools.json cannot: write to your own CRM, say, or call your booking system. A plugin adds a tool of your own, which the agent uses exactly as it uses its built-in ones. You never patch the package, so an upgrade stays a version bump.
The contract this guide follows is spec 036, and spec 039 for a tool that looks something up. Where this guide and the specs disagree, the specs win. A channel, for a platform other than ManyChat, is spec 038, and its API is provisional: see A channel for another platform.
Throughout, agent-plugin-example-crm stands for your plugin and crm_log_lead for its tool.
What a plugin tool can and cannot do
A plugin tool is a staged action, like add_tag or set_field:
- The model calls it while it writes the reply. The call only records the action. Your code runs after the reply has been sent, and not at all if the turn escalates to a person.
- It acts on the contact whose message the agent is answering. You get their subscriber ID from the turn; the model can never name another contact.
- Its parameters are choices, numbers and yes/no flags. Free text is only a
note, at most 500 characters, and names, phone numbers, emails and links are removed from it before your code sees it. - Your code gets the subscriber ID, the parameters, a logger and an abort signal. It never gets the model, the prompt, the catalog or the database.
- A failure is logged and recorded on the turn, and never retried. After 10 seconds the agent stops waiting, records a failure and aborts the signal.
- Before the agent has recorded the contact as a prospect, it refuses the call, as it refuses its own writes (spec 034).
1. Create the package
From your tenant project's root:
pnpm agent plugin new example-crm --write # a tool that acts after the reply
pnpm agent plugin new example-crm --read # a tool that looks something upIt writes plugins/agent-plugin-example-crm/ from the agent's own invented example, with the apiVersion your installed agent supports, and makes the three edits that load it: plugins/* in pnpm-workspace.yaml, "agent-plugin-example-crm": "workspace:*" in your package.json, and the name in config/plugins.json. It makes all of them or none, and it installs nothing. Run the two commands it prints next:
pnpm install
pnpm agent config checkThe tool is named after the plugin, in snake case: example_crm here. Rename it, and replace the invented backend, parameters and description, before the plugin does anything real. Start from the command rather than a copy of another deployment's plugin, which brings that deployment's endpoints and field names with it (spec 041).
The package it writes is laid out like this, and you can write one by hand the same way:
example-tenant/
config/
plugins.json
plugins/
agent-plugin-example-crm/
package.json
index.js
package.json
pnpm-workspace.yaml{
"name": "agent-plugin-example-crm",
"version": "0.1.0",
"private": true,
"type": "module",
"exports": "./index.js",
"peerDependencies": { "manychat-ai-agent": "*" }
}2. Define the plugin
import { definePlugin, defineTool } from 'manychat-ai-agent';
export default definePlugin({
name: 'example-crm',
apiVersion: 1,
tools: [
defineTool({
name: 'crm_log_lead',
description: 'Log the contact as a lead in the CRM once they have named a course.',
parameters: {
temperature: { type: 'enum', values: ['warm', 'hot'] },
seats: { type: 'number', integer: true, min: 1, max: 4, optional: true },
callback: { type: 'boolean' },
summary: { type: 'note', maxLength: 120, optional: true },
},
async perform({ subscriberId, params, logger, signal }) {
const response = await fetch('https://crm.example.com/leads', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ subscriberId, ...params }),
signal,
});
if (!response.ok) throw new Error(`CRM answered ${response.status}`);
logger.info('lead logged', { temperature: params.temperature });
},
}),
],
});nameis lowercase snake case and must not be a built-in tool's name (send_flow,add_tag,remove_tag,set_field,write_note,schedule_nudge,get_contact) or another plugin's.descriptionis the only guidance the model gets. Write it as a condition: when to call the tool, not what it does inside.parameterseach have atypeofenum(withvalues),number(optionallyinteger,min,max),booleanornote(with amaxLengthup to 500). Any may add adescriptionandoptional: true. Astringis refused: use anote.performthrows to report a failure. Passsignalto anything that waits, so the work stops when the agent stops waiting.
In TypeScript, defineTool types params from the declaration: above, params.temperature is 'warm' | 'hot' and params.seats is number | undefined.
A tool that looks something up
A write tool runs after the reply, so the model never sees what it did. When the agent needs your data to answer (seats left, an order's status, an FAQ in your own system), declare a read tool instead. The model calls it while it writes the reply, and is shown what it returns.
import { definePlugin, defineReadTool } from 'manychat-ai-agent';
export default definePlugin({
name: 'example-schedule',
apiVersion: 2,
tools: [
defineReadTool({
name: 'class_availability',
description:
'Look up the seats left on a course when the contact asks whether there is room.',
parameters: {
course: { type: 'enum', values: ['foundation', 'advanced'] },
query: { type: 'query', maxLength: 120, optional: true },
},
result: {
seatsLeft: { type: 'number', integer: true, min: 0 },
summary: { type: 'text', maxLength: 300, optional: true },
},
async read({ params, signal }) {
const response = await fetch(`https://timetable.example.com/${params.course}`, { signal });
if (!response.ok) throw new Error(`timetable answered ${response.status}`);
return response.json();
},
}),
],
});readin place ofperform. A tool declares one or the other, and a read tool needsapiVersion: 2.parametersare a write tool's, less thenote. The one free text is aquery, at most 200 characters. URLs, emails, phone numbers and long numbers are removed from it beforereadsees it; a name is not, so the agent tells the model never to put one there.resultdeclares whatreadmay return:enum,number,boolean,text(up to 1000 characters) andlist(up to 5 strings). The agent drops a key you did not declare and cuts text to its bound. Anything else that does not fit, or a result over 2000 characters, reaches the model as{ available: false }. Text comes back fenced, as data the model never obeys.- A turn makes at most two reads,
get_contactincluded, and each has 1.5 seconds. A read that throws or runs longer reaches the model as{ available: false }, and the agent answers from the catalog or hands the contact to a person. - Only a turn that may read the contact's history reads: one that carries their token, or any turn while
CONTACT_TOKENS_ENFORCEDisfalse. On any other, the tool is not offered. - The turn records which tool read, whether data came back and how long it took. It never stores the query or what you returned.
A channel for another platform
Provisional. The channel API may break in any minor release until a second adapter has been built against it. Pin the agent's exact version while you rely on one.
A plugin can also answer contacts who write somewhere other than ManyChat. A channel translates the platform's request into a turn and the agent's reply into the platform's response. The race, the order of a contact's turns, the outbox and the guardrails are the agent's, exactly as for ManyChat.
import { z } from 'zod';
import { defineChannel, definePlugin } from 'manychat-ai-agent';
export default definePlugin({
name: 'example-widget',
apiVersion: 2,
channels: [
defineChannel({
name: 'example-widget',
apiVersion: 0,
inbound: z.object({ visitor: z.string().min(1), says: z.string().max(2000) }).strict(),
parse: request => ({ subscriberId: request.visitor, text: request.says }),
render: reply => ({ say: reply.messages, handoff: reply.escalate }),
async push({ subscriberId, reply, signal }) {
const response = await fetch(`https://widget.example.com/send/${subscriberId}`, {
method: 'POST',
body: JSON.stringify({ say: reply.messages }),
signal,
});
if (!response.ok) throw new Error(`widget answered ${response.status}`);
},
}),
],
});- It is mounted at
/v1/channels/<name>/message, behind the same shared secret as the ManyChat route. The name is lowercase letters, digits and dashes, and notmanychat. apiVersion: 0on the channel is the channel API's own version. The plugin'sapiVersionstays its tool API's,1or2, even when it adds only channels.inboundis a Zod schema. A request that fails it gets a 400 and never reaches the model.parsereturns the contact's ID on your platform, their text, and optionallycontactNameandlocale. The agent prefixes the ID with the channel's name, so your contacts never share a conversation with a ManyChat contact whose ID is the same.renderturns the reply into your response body. Itsmessagesare empty when the contact's previous reply is still on its way. This one follows throughpush.pushdelivers a reply the model finished after the deadline. It gets the IDparsereturned, the reply, a logger and a signal. Throwing retries it with the outbox's backoff, and past 10 seconds it counts as failed.- There is no contact token. The shared secret is the only proof of who is writing, so every turn reads the contact's history. Keep the secret on your platform's server, never in a browser.
tools.json's tools are not offered on a channel's turns: flows, tags, fields,get_contactand nudges all act on a ManyChat contact. Your plugin tools are, andperformgets the prefixed ID.
3. List it
{ "plugins": ["agent-plugin-example-crm"] }in config/plugins.json, which agent plugin new has already written. List package names, never paths.
4. Check it, then restart
pnpm agent config checkloads every listed plugin exactly as the server does, reports each one's write and read tools, and fails on one that is not installed, names an apiVersion this agent does not support, clashes with another tool or declares a parameter it refuses. The server refuses to start on the same errors, rather than starting with a tool missing.
Plugins load once, at boot. kill -HUP reloads your configuration but not your plugin's code, so a plugin change is a restart.
Running it in the image
The published image runs from /app, with your config/ mounted at /app/config, so it looks for plugins in /app/node_modules. Build your own image on top of the agent's and copy the plugin in:
FROM ghcr.io/<owner>/manychat-ai-agent:<version>
COPY --chown=node:node plugins/agent-plugin-example-crm /app/node_modules/agent-plugin-example-crmThe image links manychat-ai-agent into its own node_modules, so the plugin's import resolves to the agent it runs in. Nothing else of yours is in that node_modules: a plugin that needs another package bundles it, or uses what Node ships, as the fetch above does. Point the image: of your docker-compose.yml at your image, and keep its tag moving with the agent's.
Upgrading
A change to the plugin API is a breaking release of the agent (spec 033), so it never arrives in a patch. If an upgrade moves apiVersion, agent config check says so before you deploy.
The channel API is the one exception: it is provisional, and a minor release may change it (spec 038).