You build a Raven AI agent inside ERPNext by turning on AI in Raven Settings, choosing a model provider, creating a bot, writing plain-English instructions, attaching document functions, and testing on staging before anyone touches live data. No custom code is needed; it all happens in the Frappe desk.
Short answer
Turn on AI in Raven Settings with an OpenAI API key or a local model (Ollama, LM Studio, LocalAI or any OpenAI-compatible server). Create a Raven bot, tick Is AI Bot?, pick its model provider, write its instructions in plain English (Jinja for dynamic values), attach functions such as Get Document and Create Document, limit who can reach it, then test every prompt on a staging site before you switch it on in production.
I lead ERPNext and Frappe programmes at MithTech, a team of Frappe specialists in Bengaluru, and Raven is the most direct way I know to ship a working AI agent inside ERPNext without writing an app. The no-code part is real, but a sloppy agent creates wrong documents quickly, so the work is in the instructions, the function scope and the staging tests.
What is a Raven AI agent, and what can it do?
A Raven AI agent is a chat bot inside your ERPNext that reads a plain-language request and acts on your data: it fetches records, creates documents or reads an uploaded file. Raven is an open-source team chat app for Frappe, and its AI layer turns a bot into an agent that calls real ERPNext functions.
Jobs I have seen work well: pulling a supplier's details from a GSTIN, drafting a Purchase Invoice from an uploaded bill, reading a receipt photo into an Expense Claim, and answering "how many open Sales Orders does this customer have?". With OpenAI as the provider, a bot can also use file search and a code interpreter when a task needs them. For the wider picture, see what Raven is for ERPNext.
Skimmable summary: a Raven agent is an in-ERPNext chat bot that reads plain language and performs real document actions on permissioned data.
What do you need before building a Raven AI agent?
Five things: Raven installed on your Frappe/ERPNext bench, an OpenAI API key or a local model server, the System Manager role to change settings, a staging site, and one clear, narrow task for the agent. Starting narrow (one job, one DocType) is what makes the first agent work.
Raven has no licence fee. With OpenAI as the provider, the model is a paid, usage-billed service; check OpenAI's pricing page for current rates. A local model costs only the compute it runs on. Decide where the agent's prompts may go before you start: with OpenAI, the message and any records or files the agent reads are sent to OpenAI; with a local model, they stay on your server. If you are still deciding whether AI belongs in your ERP, read my look at ERPNext's AI features first.
Skimmable summary: Raven installed, an OpenAI key or local model, admin rights, a staging site and one narrow task.
How do you configure a Raven AI agent step by step?
It all happens in the Frappe desk, with no bench commands after install. Work in order: turn on AI, choose the provider, create the bot, write instructions, attach functions, limit access, then test.
Turn on AI in Raven Settings
Open Raven Settings, tick Enable AI Integration, then either Enable OpenAI Services and paste your OpenAI API key, or Enable Local LLM and choose the provider (LM Studio, Ollama, LocalAI or OpenAI Compatible) with its API URL.
Create a bot and make it an AI bot
Create a Raven Bot with a clear name and description, tick Is AI Bot?, and set its Model Provider to OpenAI or Local LLM. Pick the model it should use.
Write the agent's instructions
In the instructions field, describe the agent's job, its limits and its output in plain English. Turn on Dynamic Instructions to use Jinja tags for values like the current user or today's date.
Attach functions (its tools)
Add the functions the agent may call (Get Document, Create Document, Get List and so on), each tied to a specific DocType. Anything you do not attach, it cannot touch. Tick Allow Bot to Write Documents only if the job needs writes.
Limit who can use it
Put the bot only in the channels and in front of the roles that should use it.
Test on staging, then promote
Run the full range of real prompts on a staging site, check every created or edited record by hand, then copy the exact configuration to production.
Skimmable summary: turn on AI, choose OpenAI or a local model, create an AI bot, write instructions, attach functions, limit access, test on staging, then promote.
How do you give a Raven agent tools and functions?
Functions are the only way an agent touches your data; without them it can only chat. Raven's function types are set up in the desk: Get Document, Get Multiple Documents, Get List, Get Value, Set Value, Create, Update, Submit, Cancel and Delete Document (single and multiple), Get Report Result, Attach File to Document and Send Message, each tied to a DocType such as Sales Order or Item.
For anything beyond plain document work, attach a Custom Function that points to a whitelisted Frappe method, the same kind of method path as frappe.client.get_list. Then the agent calls existing, tested code instead of improvising. Logic you want the agent to trigger belongs in a whitelisted Python method; Server Scripts are not among the function types. Give each agent the fewest functions it needs: a receipt-to-Expense-Claim agent needs create and read on a couple of DocTypes, nothing more.
| Get Document / Get Value | Read one record or field | "What's the status of SO-0042?" |
| Get List / Get Report Result | Query records with filters, or run a report | "List open invoices for this customer" |
| Create Document | Make a new record | Draft a Purchase Invoice from a bill |
| Update / Submit / Cancel / Delete | Change or remove a record | Adjust a draft before a human submits it |
| Custom Function | Call a whitelisted method | Fetch a supplier by GSTIN, call an external API |
Skimmable summary: attach the minimum document functions plus any whitelisted custom methods; Server Scripts are not a function type.
How do you write instructions that make an agent behave?
Good instructions read like a job description with hard rules. Spell out the one task, the DocType to use, which fields to fill, what to do when data is missing and, above all, what the agent must never do, such as submitting documents. Ambiguity is where wrong records come from.
Use Jinja tags for live context so you never hard-code changing values: the current user's name and ID, or today's date. Tell the agent to ask a clarifying question when a request is under-specified rather than guess. Keep drafts as drafts: I almost always instruct agents to create documents in draft and leave submission to a human. If you want AI that reasons across the whole ERP from an external assistant, that is a different pattern; see connecting ERPNext to ChatGPT and Claude over MCP.
Skimmable summary: write instructions as strict rules with explicit refusals, use Jinja for live context, and keep created documents in draft.
How do you keep a Raven agent secure and correctly permissioned?
Raven's document functions call ERPNext through its normal permission checks, so an agent is limited by the roles of the user it acts for, and the bot cannot write at all unless Allow Bot to Write Documents is ticked. Check on staging which user a write is recorded under before you rely on it.
Permissions are the safety net, not the whole of it. Limit each bot to specific channels and roles, attach only the functions the task needs, and keep Delete, Cancel and Submit off any agent that does not strictly need them. Raven runs on your own Frappe and ERPNext site, so the app, your data and the API key stay there. With OpenAI as the provider, the prompt and any records or files the agent reads are sent to OpenAI under its API terms; with a local model they stay on your server. Put that in your data-handling policy.
Skimmable summary: ERPNext permissions apply and writes need an explicit switch; still limit roles and functions, and know what goes to the model provider.
How should you test a Raven agent before going live?
Run the agent against a staging copy of your ERP and check every action it takes by hand; never validate on production. Feed it messy real inputs: blurry receipts, missing GSTINs, ambiguous requests and prompts that try to push it past its rules.
Clone to staging
Test on a separate staging site with representative data, so a wrong Create Document never lands in real books.
Run normal and edge-case prompts
Cover the normal request, then the awkward ones (incomplete data, wrong formats, off-topic asks) and confirm the agent asks or refuses instead of guessing.
Inspect every record it creates
Open each draft the agent made and check the fields line by line. Drafts, not submissions, keep mistakes cheap.
Try to break the rules
Prompt it to submit or act outside its scope. If it complies, tighten the instructions and re-test until it refuses.
Copy exactly to production
Once it is reliable, rebuild the same settings, instructions and functions on the live site, and watch the first real conversations closely.
Skimmable summary: rehearse on staging with messy and adversarial inputs, check every record by hand, then copy the exact configuration to production.
How do Raven AI agents compare with other ERPNext AI options?
Raven agents fit best when the AI should live inside ERPNext, act on documents and follow Frappe permissions. Other approaches suit other jobs, and teams often mix them.
| Approach | Suits | Runs where |
|---|---|---|
| Raven AI agent | In-ERP document actions, chat-driven tasks | Inside your Frappe/ERPNext site |
| ChatGPT or Claude over MCP | Questions and analysis across your data | External assistant reaching into ERPNext |
| Custom Frappe app | Bespoke, tightly controlled automation | Your codebase |
For a repetitive back-office task, a Raven agent is usually the fastest safe start. For open-ended analysis, an MCP connection to an external assistant often fits better.
Skimmable summary: Raven agents for in-ERP document work, MCP for questions from an external assistant, custom apps for bespoke control.
Frequently asked questions
+Is Raven free to use for AI agents?
Raven is free and open source under AGPL-3.0, so the app and its agent features have no licence fee. With OpenAI as the provider you pay OpenAI for usage; check its pricing page for current rates. With a local model you pay for the compute. Otherwise the cost is hosting your Frappe site.
+Do I need to write code to build a Raven AI agent?
No, not for the standard flow. You turn on AI, create a bot, write plain-English instructions and attach built-in document functions in the Frappe desk. Code comes in only for a Custom Function, which points to a whitelisted Python method, and even then you reuse a method rather than write the agent.
+Can a Raven agent do things a user isn't allowed to do?
Raven's document functions go through ERPNext's permission checks, so an agent is bound by Frappe role permissions, and it cannot write unless the bot allows writes. That is the core safeguard. Still limit each agent's functions and channels deliberately, and check on staging which user its writes are recorded under.
+Does Raven support AI models other than OpenAI?
Yes. Raven Settings has a Local LLM option with LM Studio, Ollama, LocalAI or any OpenAI-compatible server as the provider, and each bot chooses OpenAI or Local LLM. Some features, such as file search and the code interpreter, depend on the provider; test the ones you need with the model you pick.
+What happened to Raven agents built on the OpenAI Assistants API?
Early Raven agents were created as OpenAI Assistants, and OpenAI scheduled the Assistants API to shut down on 26 August 2026. Current Raven runs bots with a model provider set on the OpenAI Agents SDK; bots still tied to an old OpenAI Assistant ID use the legacy path. If you have such bots, update Raven and recreate them with a model provider.
+What's the safest first agent to build?
A read-only or draft-only agent on one DocType: "list a customer's open orders" (read-only) or "create a draft Expense Claim from a receipt photo" (a draft a human submits). Prove the pattern, check every output on staging, then widen the scope once you trust it.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 20 July 2026
Worked with us? Leave a Google review