You build a Raven AI agent inside ERPNext by enabling AI in Raven Settings, creating a bot, writing plain-English instructions, attaching document functions, and testing on staging before anyone touches live data. No custom code required. The whole flow lives in the Frappe desk UI.
Short answer
Enable AI in Raven Settings with an OpenAI API key, create a Raven bot and mark it as an agent, write its instructions in plain English (with Jinja for dynamic values), attach functions like Get Document and Create Document, restrict it to the right roles, then test every prompt on a staging site before switching it on in production.
I run ERPNext implementations at Mith Tech in Bengaluru, and Raven is the first ERPNext-native way I've seen to ship a working AI agent without writing an app. Honest take: the no-code promise is real, but a sloppy agent is a fast way to create wrong documents — the discipline is all in the instructions, the function scope, and the testing.
What is a Raven AI agent, and what can it actually do?
A Raven AI agent is a chat bot inside your ERPNext instance that reads a request in plain language and acts on your data — fetching records, creating documents, or reading an uploaded file. Raven itself is an open-source team-messaging app for Frappe, and its AI layer turns a bot into an agent that calls real ERPNext functions.
Practical jobs I've seen work well: pulling a supplier's details from a GST number, drafting a Purchase Invoice from an uploaded bill, reading a receipt photo into an Expense Claim, or answering "how many open Sales Orders does this customer have?" The agent runs on OpenAI's Assistants API behind the scenes, so it can also use vision, file search, and a code interpreter when a task needs them. For the bigger 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 your permissioned data.
What do you need before building a Raven AI agent?
Four things must be in place first: Raven installed on your Frappe/ERPNext bench, an OpenAI API key, the System Manager role to configure settings, and a clear, narrow task for the agent to own. Starting narrow — one job, one doctype — is the single biggest predictor of success.
Raven is free and open source, but the OpenAI Assistants API that powers the agent is a paid, usage-billed service — check OpenAI's official pricing page for current rates, since that cost is separate from Raven. Also decide upfront which staging site you'll test on, because you never rehearse an agent that writes records against live books. If you're weighing whether AI belongs in your ERP at all, my honest look at ERPNext's AI features is a good sanity check first.
Keep your API key out of version control
The OpenAI key lives in Raven Settings, not in your site config or a committed file. Treat it like any other production secret, and rotate it if it ever leaks into logs or screenshots.
Skimmable summary: you need Raven installed, an OpenAI key, admin rights, a staging site, and one narrow task before you start.
How do you configure a Raven AI agent step by step?
Configuration happens entirely in the Frappe desk — no bench commands after install. Work through it in order: enable AI, create the bot, write instructions, attach functions, scope permissions, then test. Each step below maps to a doctype you fill in through the UI.
Enable AI in Raven Settings
Open Raven Settings, turn on the AI feature, and paste your OpenAI API key. This is the switch that unlocks the agent fields on every bot.
Create a bot and mark it as an agent
Create a new Raven bot, give it a clear name and description, and enable its AI/agent option. Pick the model you want it to use from the ones Raven exposes.
Write the agent's instructions
In the instructions field, describe the agent's job, its boundaries, and its output in plain English. Use Jinja tags for anything dynamic, like the current user or today's date.
Attach functions (its tools)
Add the functions the agent is allowed to call — Get Document, Create Document, Get List, and so on — each pointed at a specific doctype. Nothing you don't attach can be touched.
Scope who can use it
Restrict the bot to the right channels and roles so only the intended team can invoke it. The agent still runs under each user's own permissions.
Test on staging, then promote
Run the full range of real prompts on a staging site, verify every created or edited record by hand, then replicate the exact configuration on production.
Skimmable summary: enable AI, create an agent bot, write instructions, attach functions, scope roles, 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 ships document-level function types you attach through the UI: Get Document, Get List, Create Document, Update Document, Delete Document, and value getters, each bound to a specific doctype like Sales Order or Item.
For anything beyond plain document operations, you attach a custom function that points to a whitelisted Frappe method — the same kind of method path as frappe.client.get_list. That lets an agent call existing, tested API endpoints instead of improvising. One current limitation worth knowing: bot functions can't call Server Scripts yet, so logic you want the agent to trigger should live in a whitelisted Python method. 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.
| Function type | What the agent can do | Typical use |
|---|---|---|
| Get Document / Get Value | Read one record or field | "What's the status of SO-0042?" |
| Get List | Query multiple records with filters | "List open invoices for this customer" |
| Create Document | Make a new record | Draft a Purchase Invoice from a bill |
| Update / Delete Document | Modify or remove a record | Adjust a draft before submission |
| Custom function | Call a whitelisted method | Fetch supplier by GST, call an external API |
Skimmable summary: attach the minimum document functions plus any whitelisted custom methods; server scripts aren't callable as bot functions yet.
How do you write instructions that make an agent behave?
Good instructions read like a job description with hard rules, not a friendly summary. Spell out the single task, the exact doctype to use, which fields to fill, what to do when data is missing, and — critically — what the agent must never do, such as submitting documents automatically. Ambiguity is where wrong records come from.
Use Jinja tags to inject live context so you never hardcode changing values — the current user's name and ID, or today's date, flow in automatically. A strong instruction set also tells the agent to ask a clarifying question when a request is under-specified, rather than guessing. Keep drafts as drafts: I almost always instruct agents to create documents in draft state and leave submission to a human. If you also want AI that reasons across your whole ERP via external assistants, that's a different pattern — see connecting ERPNext to ChatGPT and Claude over MCP.
Write the failure cases first
Before listing what the agent should do, list what it must refuse: no auto-submitting, no editing submitted documents, no guessing a supplier when the GST doesn't match. Explicit refusals prevent most bad outcomes.
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?
Permissions are enforced by Frappe, not by the agent's goodwill: an agent acts as the user who invoked it, so it can only read or write what that user's roles already allow. A salesperson's agent can't create a Journal Entry if the salesperson can't — the permission check is identical to a manual action.
That model is the safety net, but it isn't the whole seatbelt. Scope each bot to specific channels and roles, attach only the functions the task requires, and keep destructive functions (Delete, Update on submitted docs) off any agent that doesn't strictly need them. Because Raven is AGPLv3 and self-hosted on your own Frappe and ERPNext platform, your data and API key stay on your infrastructure — the only thing leaving is the prompt content sent to OpenAI, which you should factor into your data-handling policy.
Skimmable summary: agents inherit the invoking user's Frappe permissions; still scope roles, minimise functions, and account for prompt data sent to OpenAI.
How should you test a Raven agent before going live?
Testing means running the agent against a staging copy of your ERP and manually checking every action it takes — never validating on production. Feed it the messy real inputs: blurry receipts, missing GST numbers, 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 happy-path and edge-case prompts
Cover the normal request, then the awkward ones — incomplete data, wrong formats, and off-topic asks — and confirm the agent asks or refuses instead of guessing.
Inspect every record it creates
Open each draft the agent produced and check fields line by line. Drafts, not submissions, mean mistakes are cheap to catch.
Try to break the rules
Prompt it to auto-submit or act outside its scope. If it complies, tighten the instructions and re-test until it refuses.
Replicate exactly on production
Once it's reliable, rebuild the same settings, instructions, and functions on the live site — then monitor the first real interactions closely.
Skimmable summary: rehearse on staging with messy and adversarial inputs, hand-verify every record, then replicate the exact config to production.
Raven AI agents vs other ERPNext AI options
Raven agents fit best when the AI needs to live inside ERPNext, act on documents, and respect Frappe permissions out of the box. Other approaches suit different jobs, and mixing them is common.
| Approach | Best for | Runs where |
|---|---|---|
| Raven AI agent | In-ERP document actions, chat-driven tasks | Inside your Frappe/ERPNext site |
| ChatGPT/Claude over MCP | Cross-system reasoning, ad-hoc analysis | External assistant reaching into ERP |
| Custom Frappe app | Bespoke, tightly-controlled automation | Your codebase |
For a Bengaluru SMB automating a repetitive back-office task, a Raven agent is usually the fastest safe start. For open-ended analysis across tools, an MCP connection to an external assistant often fits better.
Skimmable summary: use Raven agents for in-ERP document work, MCP for external cross-system reasoning, and custom apps for bespoke control.
Frequently asked questions
Is Raven free to use for AI agents?
Raven itself is free and open source under AGPLv3, so the app and its agent-building features cost nothing to install. The AI runs on OpenAI's Assistants API, which is a separate paid, usage-billed service — check OpenAI's official pricing page for current rates. Your only Raven-side cost is hosting your own Frappe instance.
Do I need to write code to build a Raven AI agent?
No code is required for the standard flow. You enable AI, create a bot, write plain-English instructions, and attach built-in document functions entirely through the Frappe desk UI. Code only enters the picture if you want a custom function, which points to a whitelisted Python method — and even then you're reusing existing methods, not writing the agent itself.
Can a Raven agent do things a user isn't allowed to do?
No. An agent acts as the user who invoked it and is bound by that user's Frappe role permissions. If a user can't create or read a particular document manually, the agent can't either. This permission inheritance is the core safety guarantee, though you should still limit each agent's functions and roles deliberately.
Does Raven support AI models other than OpenAI?
As implemented today, Raven's agents run on OpenAI's Assistants API. The maintainers have publicly discussed exploring other large language models and open-source options, but OpenAI is what's wired in. If you need local or alternative models, plan around OpenAI for now and watch the project's releases for changes.
Can a Raven agent call a Server Script?
Not currently. Bot functions can't invoke Server Scripts as of now, and the maintainers have noted plans to add support. If you need custom logic, expose it as a whitelisted Python method and attach it as a custom function — that path works and is the recommended approach today.
What's the safest first agent to build?
A read-only or draft-only agent on one doctype. Something like "list a customer's open orders" (read-only) or "create a draft Expense Claim from a receipt photo" (creates a draft a human submits) keeps the blast radius tiny. Prove the pattern, verify every output on staging, then expand scope once you trust it.
About the author
I'm Manoj, an ERPNext implementation consultant at Mith Tech, an independent open-source ERPNext and Frappe studio in Bengaluru. I help Indian SMBs adopt ERPNext without over-engineering it — including practical, permission-safe AI automation with tools like Raven.