Erxes Support Agent

Expose curated tRPC procedures as agent-callable tools and manage them from the tool registry. This guide follows version 3.1.7 (03acdf712c).

For the annotation pattern, see GraphQL & tRPC. For gateway auth, see Authentication.

How agent tools work

There is no mastra_api backend plugin in the checked revision. Agent capability comes from the generic agent-tools layer in backend/erxes-api-shared/src/utils/agent-tools/ (manifest.ts, endpoints.ts, auth.ts, types.ts, responseLimit.ts):

1. A tRPC procedure is invisible to agents by default.
2. Adding .meta({ agent: { description, permission } }) admits it. Helpers exist at backend/core-api/src/utils/agentMeta.ts, backend/plugins/sales_api/src/trpc/agentMeta.ts, and backend/plugins/frontline_api/src/trpc/agentMeta.ts.
3. The platform auto-mounts GET /agent-tools/manifest and POST /agent-tools/call on every plugin with a trpcAppRouter.
4. Calls enforce tenant curation (default-deny per plugin), HMAC service auth (x-erxes-agent-auth via JWT_TOKEN_SECRET), user permission checks, destructive-operation approval, and a response byte cap (default 64KB).

Mutations whose names match /(remove|delete|merge|destroy)/i require explicit user approval. Use typed Zod inputs so the manifest can describe fields.

Tool registry UI

frontend/plugins/mastra_ui/src/pages/tools/ToolFormPage.tsx manages the tool registry:

• Built-in types (webSearch, fetchUrl, calculator) versus erxes-operation tools fed by MASTRA_AVAILABLE_ERXES_TOOLS runtime introspection.
• Fields for toolId, name, description, response fields, and the isEnabled toggle.
• Mutations MASTRA_TOOL_CREATE/MASTRA_TOOL_UPDATE with duplicate-guard via the MASTRA_TOOLS map.

Only annotate safe, well-scoped procedures. Never annotate raw-mongo helpers, system-user internals, device-sync endpoints, or bulk-update utilities.

Source references

• Agent-tools endpoints.
• Sales agentMeta helper (example).
• Tool registry page.