How to add AI agents to TOTVS Protheus
Short answer
Put a small tool layer between the agent and Protheus: read-only SQL or REST for lookups, and ExecAuto-based routines for writes that always wait for a human approval. The model reasons and drafts, Protheus validates and posts, so the ERP's own rules stay in force.
Protheus shops tend to have years of customization in AdvPL or TLPP: custom fields in SX3, user entry points (pontos de entrada), and routines that the standard documentation does not describe. An AI agent that ignores that customization will propose actions Protheus rejects or, worse, accepts and gets wrong. The agent has to work through the same routines your users trigger.
The realistic first agents are narrow: a purchasing agent that watches open purchase orders for late deliveries, a PCP agent that triages production orders short of material, and a finance agent that explains why a title is blocked. Each reads a handful of tables, reasons over them, and writes a proposal rather than a transaction.
Most Protheus customers also run on-premises application servers with SQL Server, Oracle or PostgreSQL underneath, so the agent runtime often has to sit inside the same network. That is a deployment decision, not a blocker, and it shapes the options below.
What teams use it for
Late purchase order chaser
Scans SC7 lines whose delivery date has passed with open balance, groups them by supplier from SA2, drafts a follow-up message and proposes a new promise date for a buyer to approve.
Production order shortage triage
Reads open SC2 orders, explodes the structure in SG1 against SB2 balances, and lists which orders cannot start and which purchase or transfer would unblock them.
Blocked sales order explainer
For a sales order in SC5/SC6, checks credit block, stock block and tax rules, and tells the order desk in plain language which block applies and who can release it.
Receivables follow-up drafting
Reads overdue titles in SE1 per customer, drafts collection messages in the customer's language, and queues them for finance review instead of sending directly.
Inbound invoice exception review
Compares the XML of a received NF-e against the purchase order and the pre-note, flags price or quantity differences, and prepares the classification for the fiscal team.
Master data hygiene
Finds duplicate customers or suppliers by tax ID and name similarity across SA1/SA2 and proposes a merge list for a data steward to confirm.
TOTVS Protheus integration surface
- REST services published from the Protheus application server, either the standard REST/FWRest endpoints or custom services written in TLPP or AdvPL with the WsRestFul class. Which endpoints exist depends on your release and licensed modules.
- ExecAuto calls (MsExecAuto) into standard routines such as MATA410 for sales orders and MATA120 for purchase orders, which runs the normal validations and entry points instead of writing tables directly.
- Direct SQL reads against the Protheus database. Tables are named by alias (SA1, SC7, SD1, SE1), carry a filial column, and flag deletions with D_E_L_E_T_, so every query must filter both.
- The data dictionary in SX3 and related SX tables, which tells the agent which fields are custom and what their types and validations are.
- TOTVS Mensagem Unica (EAI) and Fluig for events and approval workflows, where your landscape has them licensed.
How it works
- 1
Pick one process and write the decision rules
Choose something like late PO chasing and write down who decides what. The agent is only as good as the rules you can state, and Protheus parameters (the MV_ settings) often hold half of them.
- 2
Create a read-only database role or REST service account
Grant SELECT on the needed alias tables only. Prefer database views that already join SC7 to SA2 and apply the deleted-record and branch filters, so the model never writes raw table logic.
- 3
Define typed tools
Expose functions such as open_po_lines(supplier, days_late) and shortage_for_order(order). Return small JSON, with Portuguese or English field labels mapped from SX3 titles so the model reads meaningful names.
- 4
Run the agent with an open-weight or approved model
Use a tool-calling model served locally with vLLM or Ollama if data must stay on site, or a cloud API if policy allows. Cap steps per run and log every tool call.
- 5
Write through approval only
The agent saves a proposal in a custom table or a Fluig task. After a person approves, a TLPP routine calls the standard ExecAuto so Protheus validates it like any user entry.
- 6
Replay and measure
Keep run logs, compare proposals with what buyers actually did for a few weeks, and only then widen the agent's scope or reduce review.
Example flows
Weekly late PO sweep
Trigger: A scheduled job runs Monday morning.
- Tool lists SC7 lines past delivery date with open quantity, per branch.
- Agent groups by supplier and checks recent receipts in SD1 to see partial deliveries.
- Agent drafts one message per supplier and a suggested new date.
- Buyer reviews the queue, edits, and approves.
Result: Buyers start the week with a prepared list instead of building it from a report.
Shortage triage before a production release
Trigger: Planner asks which orders for next week cannot be produced.
- Tool fetches SC2 orders in the date window.
- Agent reads SG1 components and SB2 available balance per warehouse.
- It ranks orders by missing component and lead time of the linked supplier.
- It proposes purchase requests, which the planner approves one by one.
Result: The planner sees blockers and candidate fixes in one answer, and each request is posted by the standard routine.
Keeping data on-prem
Run the agent runtime on a server in the same network as the Protheus application server and database, with the model served on local GPUs through vLLM or Ollama. The tool layer connects to a read-replica or a reporting copy of the database when possible, so agent queries do not compete with the transactional load of the DBAccess layer. Nothing leaves the network, which matters for LGPD obligations and for customers with defense or industrial secrecy requirements. Write-back still goes through the application server, never straight to the tables.
Security checklist
- Use a dedicated database account with SELECT on named views, and no access to password or user tables in the Protheus dictionary.
- Map the human approver to a real Protheus user so the ExecAuto posting carries the right permissions and audit trail.
- Treat text from supplier emails or invoice fields as untrusted input to the model, and never let it choose which tool or table to call without schema checks.
- Log prompts, tool calls and results per run, with branch and user, for LGPD data-subject requests and internal audit.
- Keep personal data (CPF, bank details) out of prompts unless the task needs it.
Ways to get it done
Use the AI features TOTVS ships in your release
Effort: Days to configure, subject to licensing.
Good when the question is generic and your license already includes the assistant; check what data it can reach.
Build in-house with TLPP services and an agent framework
Effort: Typically one to three months for a first agent with approvals.
Fits teams with strong AdvPL/TLPP skills and a clear process. You own the tool layer and the guardrails.
Work with a partner such as Netray
Effort: A scoped pilot is usually a few weeks.
Fits when you want a private deployment and agents for several processes, with Protheus consultants and AI engineers together.
Pitfalls
- !Querying tables without the D_E_L_E_T_ and filial filters returns deleted and other-branch rows that look valid.
- !Writing directly into tables skips entry points, dictionary validations and fiscal logic, and corrupts balances.
- !Giving the agent broad tools. Narrow, typed tools are easier to test than a general SQL box.
- !Ignoring custom fields. Many business rules in Protheus live in user fields and entry points the model has never seen.
- !Letting the agent act without approval during the pilot. Trust should come from measured proposal accuracy.
Frequently asked questions
Can an AI agent post transactions in Protheus?
Yes, but through the standard routines using ExecAuto or a published service, after human approval. That way validations, entry points and fiscal rules run exactly as for a user. Avoid direct table writes, which bypass those controls.
Does the agent need a REST API?
Not strictly. Read access can use SQL views, and writes can use a TLPP service you publish. A REST layer is cleaner for permissions and versioning, and the exact standard endpoints depend on your release and modules.
Which Protheus processes suit a first agent?
Read-heavy, repetitive ones: late purchase orders, production shortage triage, overdue receivables follow-up. They touch few tables, have clear rules, and produce a proposal a person can check in seconds.
Can we keep everything on-premises?
Yes. Serve an open-weight model on your own GPUs and run the tool layer next to the application server. The agent reaches Protheus over the internal network, so no ERP data goes to an outside service.
How do we handle multiple branches and companies?
Include company and filial in every tool signature and filter on them in every view. Resolve the user's allowed branches from Protheus and pass them in, so the agent cannot read across entities.
Want AI agents working on your TOTVS Protheus?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment