How to add AI agents to ERPNext
Short answer
Add AI agents to ERPNext by giving a model a small set of tools that call the Frappe REST API as a dedicated, role-limited API user. Let agents read freely, create only Draft documents, and leave Submit to a person. The same pattern works on Frappe Cloud and on a self-hosted bench.
ERPNext teams in manufacturing usually have the same backlog: Material Requests that nobody turns into Purchase Orders on time, Work Orders stuck because one raw material is short, Quality Inspections that are never filled in, and a month-end close that depends on one accountant's memory. These are multi-step chores with clear rules, which is where an agent helps more than a dashboard.
ERPNext is a good target because everything is a DocType with a consistent API. Item, BOM, Work Order, Job Card, Purchase Order and Stock Entry all expose the same list, get, insert and method-call patterns, and the docstatus field (0 Draft, 1 Submitted, 2 Cancelled) gives you a natural safety boundary. An agent that can only produce Drafts cannot post to the ledger by accident.
The hard part is not the model call. It is deciding which tools the agent gets, how it authenticates, and what a human must approve. This page walks through that design for ERPNext specifically, including what to do when the instance sits on a plant server that cannot reach a cloud model.
What teams use it for
Material Request to Purchase Order triage
The agent reads open Material Requests, checks Bin quantities and Item Supplier defaults, groups lines by supplier and creates Draft Purchase Orders for a buyer to review.
Work Order shortage explainer
For a delayed Work Order, the agent walks the BOM, compares required quantities against Bin actual and projected quantity, and writes a plain list of which components block which operation.
Quality Inspection follow-up
After a Purchase Receipt, the agent finds items with an inspection required flag, creates the Draft Quality Inspection with the right template readings and pings the inspector.
Overdue receivable chaser
The agent lists overdue Sales Invoices by customer, drafts a reminder in the customer's language and logs a Communication against the invoice once a person approves the text.
Master data hygiene
Agents scan Items for missing UOM conversions, duplicate descriptions or empty default warehouses and propose corrections as a reviewable list rather than editing silently.
Production planning assistant
Given a Sales Order, the agent checks capacity assumptions, suggests a Production Plan and raises Draft Work Orders and Material Requests for the planner to adjust.
ERPNext integration surface
- Frappe REST API: GET and POST on /api/resource/<DocType>, with fields, filters, order_by and limit_page_length query parameters for list reads.
- Whitelisted methods under /api/method/, for example frappe.client.get_list and frappe.client.get_value, plus your own @frappe.whitelist() functions in a custom app.
- Token authentication with an API key and secret generated on a User record, sent as an Authorization: token key:secret header. OAuth 2 is also supported if you need delegated access.
- Role Permissions and User Permissions apply to every API call, so a purpose-built user with narrow roles limits what an agent can see or touch.
- Webhooks (the Webhook DocType) and server-side doc_events in a custom app can notify an agent runtime when a document is created, submitted or changed.
- Direct MariaDB access (tables prefixed with tab, such as tabBin) is possible on self-hosted benches, but it bypasses permissions, so keep it for read-only analytics.
How it works
- 1
Create a dedicated agent user
Add a User with no desk login, give it only the roles the agent needs (for example Stock User and Purchase User, not System Manager) and generate an API key and secret.
- 2
Define a narrow tool list
Write functions such as get_open_material_requests, get_item_stock, get_bom and create_draft_purchase_order. Each wraps one REST call with validated arguments, so the model never builds raw URLs.
- 3
Force Draft on writes
Tools that write call insert only and never submit. Check that the returned docstatus is 0 before the agent reports success. Submission stays a button a human presses.
- 4
Add an approval queue
Store each agent proposal with its source documents and reasoning, show it in a simple page or a Frappe custom DocType, and record who approved it.
- 5
Trigger by schedule and by event
Use a Scheduled Job Type or an external cron for daily sweeps, and a Webhook on Material Request or Work Order changes for event-driven runs.
- 6
Log every tool call
Keep the prompt, tool arguments, response codes and the resulting document names so any odd draft can be traced back in minutes.
- 7
Test on a copy site
Restore a backup to a staging site with bench restore, point the agent there first and compare its drafts with what your buyers would have done.
Example flows
Daily shortage sweep
Trigger: Scheduled run at 06:30 on weekdays.
- Fetch Work Orders with status Not Started or In Process due in the next 5 days.
- For each, expand the BOM and read Bin quantities for the source warehouse.
- Where required exceeds available, find open Purchase Orders for the item and their schedule dates.
- Create a Draft Material Request for anything with no inbound supply.
- Post a ranked list to the planner with the blocked Work Orders first.
Result: Planners start the day with a prioritised shortage list and ready Draft requests instead of building it from three reports.
Supplier consolidation
Trigger: A buyer clicks a custom button on a batch of approved Material Requests.
- The button calls a whitelisted method that passes the Material Request names to the agent.
- The agent groups lines by default supplier and checks last Purchase Order rates.
- It creates one Draft Purchase Order per supplier with the requested schedule dates.
- It flags any line where the rate moved more than a configured percentage.
Result: Buyers review a few Drafts with flagged exceptions rather than keying each order by hand.
Keeping data on-prem
Self-hosted ERPNext on a bench or Docker stack is easy to keep private. Run the agent runtime on the same network, point it at the site URL, and serve an open-weight model on local GPUs with vLLM or Ollama so no prompt or document leaves the plant. Pick a model that handles tool calling reliably and test it against your own DocTypes, because smaller models fumble multi-step reads more often. If the site is on Frappe Cloud, the API is reachable from your own network, so you can still keep the model local while the data stays with the host. Keep the agent user's key in a secret store, not in code, and restrict the site to the agent host by IP where your proxy allows it.
Security checklist
- Use a separate API user per agent so permissions, revocation and audit are independent of any human account.
- Never grant System Manager or Administrator to an agent user, and review its roles at each release.
- Treat text inside documents (remarks, supplier emails, item descriptions) as untrusted input that could carry prompt injection, and never let it choose tools or targets.
- Rate limit the agent and cap list sizes so a loop cannot flood the site or pull every record.
- Keep the audit trail of prompts and tool calls inside your own storage for the same retention period as the ERP documents.
Ways to get it done
Build in-house on the Frappe API
Effort: A first read-only agent in a few weeks; draft-writing agents with an approval queue take longer.
You have a Python developer who knows Frappe and wants full control of tools and prompts.
Use a community or Marketplace app
Effort: Days to evaluate, but plan for review of the code and its permission model.
You want a quick trial of chat or automation features; check the app's maintenance and the Frappe version it supports before relying on it.
Work with a partner such as Netray
Effort: Scoped pilot on one workflow, then expansion once drafts match your team's judgement.
You need private on-prem models, an audited tool layer and an ERP-savvy partner to tune agents to your BOMs and approval rules.
Pitfalls
- !Letting the agent submit documents because it is faster. A wrong submitted Stock Entry needs cancellation and reposting, which is painful.
- !Giving a broad role to avoid permission errors. Fix the missing role precisely instead.
- !Ignoring custom fields and mandatory validations in your own apps, which make agent inserts fail in confusing ways.
- !Reading large child tables repeatedly, which is slow. Fetch with explicit fields and cache BOM reads per run.
- !Upgrading ERPNext versions without retesting tools, since field names and workflows change between major releases.
Frequently asked questions
Can an AI agent post transactions in ERPNext on its own?
Technically yes, because the API can call submit. In practice it is better to restrict agents to Draft documents and keep Submit with a person. This keeps the ledger clean, gives you an approval record and limits the damage from a wrong plan or prompt injection.
Do I need a custom Frappe app to build agents?
Not for a first version. The standard REST API and a dedicated API user are enough. A custom app becomes useful when you want whitelisted methods, doc_events hooks, an approval DocType or tighter validation close to the data.
Which ERPNext version should I target?
Target the version you run and pin the tool layer to it. Core DocTypes like Item, BOM and Work Order are stable, but field names, workflows and some endpoints can differ across major versions, so test tools after every upgrade.
Can agents work with an air-gapped ERPNext?
Yes. Run the agent runtime and an open-weight model inside the same network as the bench. The agent only needs to reach the site's HTTP port and your local model server, so no internet access is required once weights and packages are loaded.
Is the built-in ERPNext automation enough?
For rule-based steps, often yes. Assignment Rules, Auto Repeat, Notifications and Server Scripts cover many chores without AI. Use agents when the task needs reading messy text, weighing several documents or explaining a decision, and keep rules for everything deterministic.
Want AI agents working on your ERPNext?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment