How to Connect an AI Agent to Odoo: Architecture and API Basics

You connect an AI agent to Odoo by putting a thin tool layer between the language model and Odoo's external API. The model never talks to Odoo directly. It asks to call a named tool, your code checks the request, and your code makes the API call as a dedicated Odoo user with limited rights. Getting that layer right matters more than which model you choose.

Key takeaways

• Odoo exposes an external API through which an authenticated user can search, read, create and update records, subject to that user's access rights and record rules.
• Give the agent its own Odoo user with the least privilege that lets it do its job. Never use an administrator account.
• Expose a few narrow, well-named tools, not a generic "run any query" tool.
• Validate every tool call in code, create drafts for anything financial, and require human approval before posting.

The architecture in five layers

A production setup has five parts. Each has one job.

1. Channel. Where requests come from: a chat widget, a shared inbox, a messaging app, or an event in Odoo such as a new lead.
2. Agent service. Your application. It holds the instructions, calls the language model, runs the loop of "model asks for a tool, service runs it, result goes back to the model", and enforces limits such as the maximum number of steps.
3. Tool layer. A set of functions, each wrapping one specific Odoo operation with validation.
4. Odoo API. The external interface of your Odoo database, reached over HTTPS.
5. Approval and logging. The review queue for sensitive actions and the record of everything that happened.

Odoo API basics

Odoo's external API has long been available over XML-RPC and JSON-RPC. The concepts are the same either way.

• Authentication. A call identifies the database and a user, with a password or an API key. Use an API key where your version supports it, so the credential can be revoked without changing a password.
• Models. Data is organized in models. Common ones are res.partner for contacts, crm.lead for leads and opportunities, sale.order for quotations and sales orders, account.move for invoices and bills, product.product for products and stock.quant for stock on hand.
• Methods. The everyday ones are search, read, search_read, create and write.
• Domains. Searches use a filter called a domain, a list of conditions. For example, [["email", "=", "buyer@example.com"]] finds contacts with that email.
• Fields. Always request only the fields you need. It is faster and sends less data to the model.
• Permissions. Every call runs as the authenticated user. If that user cannot read a model or a record, the API call cannot either.

Endpoints and authentication details differ between Odoo versions and hosting options, so check the developer documentation for the version you run, and confirm your plan allows external API access before designing anything.

Set up a dedicated API user

Create a user in Odoo only for the agent. This one decision gives you three protections.

• Least privilege. Assign only the access groups the job needs. An agent that drafts quotations needs Sales rights, not Accounting or Settings.
• Record rules. If the agent should see only one company's or one team's records, Odoo's record rules enforce that at the database level, independent of anything the model does.
• Traceability. Every record the agent creates or changes shows that user as the author, so you can always tell agent work from human work.

Avoid granting delete rights. Avoid any group that lets the user change settings, users or access rules.

Design the tools

A tool is a function the model can request by name with structured arguments. The model sees its name, a description and a parameter schema. Good tools are narrow and named after a business action. A definition might look like this:

{ "name": "create_draft_quotation", "description": "Create a draft quotation for an existing customer. Does not confirm it.", "parameters": { "customer_id": "integer", "lines": [ { "product_id": "integer", "quantity": "number" } ], "note": "string" } }

A sensible starting set for a sales agent has five or six tools:

• search_customer: find contacts by name, email or phone, returning a short list.
• search_product: find products by name or internal reference.
• get_customer_orders: list recent orders and their status for one customer.
• create_draft_quotation: create a quotation in draft state.
• post_internal_note: add a note to a record's chatter explaining what was done and what is uncertain.
• request_human_review: hand over with a reason.

Do not give the model a tool that accepts any model name and any domain. It leaves the user's access rights as the only protection. Narrow tools give you a second layer. For more on how models choose and call tools, see function calling explained.

What each tool should do internally

1. Validate the arguments. Check types and ranges. Confirm that the customer and product ids exist. Reject a quantity of zero or one that is far outside the normal range.
2. Apply business rules in code. Limits such as "no quotation above a set value without review" belong here, not in the prompt.
3. Make the API call. One specific operation, with fixed fields.
4. Return a compact result. Give the model ids, names and status, not the whole record.
5. Return clear errors. "No customer found for that email" lets the model recover or ask. A raw stack trace does not.

Drafts, approvals and write safety

Odoo's own document states make safe writing straightforward. Quotations, purchase orders, invoices and bills all start as drafts and take effect only when confirmed or posted. Let the agent create drafts. Let people confirm them.

Action	Recommended control
Search and read records	Automatic, within the API user's rights
Post an internal note, schedule an activity	Automatic
Create a lead or a draft quotation	Automatic, with a note for the reviewer
Create a draft bill or invoice	Automatic as draft, human posts it
Confirm orders, post entries, register payments	Human only
Change prices, bank details, payment terms	Human only

Also make writes safe to repeat. If a network error causes a retry, the tool should detect that the draft already exists, for example by checking a source reference, instead of creating a duplicate.

Logging and monitoring

Keep two records. In your agent service, store each run: the trigger, the tool calls with arguments, the results, the final output and any error. In Odoo, have the agent post a short note on each record it touches, so a user looking at the quotation can see where it came from without opening another system. Review failed and escalated runs weekly at first.

External service or custom module?

An external service is the usual starting point because it needs no change to Odoo. A custom Odoo module, written in Python, is worth adding when you want a button or chat panel inside Odoo's screens, or when Odoo events should call the agent directly through an automation rule. Custom modules need a hosting option that permits them, so this choice depends on how your Odoo is hosted.

Related guides

• AI Agents for Odoo: What They Are and What They Can Do
• Building an AI Support Agent on Odoo Helpdesk
• Automating Odoo CRM with AI: Lead Scoring, Notes and Follow-Ups
• AI for Odoo Inventory: Reordering, Forecasting and Stock Questions
• Service: AI Agents for Odoo and ERP

Frequently asked questions

Can the agent query the Odoo database directly with SQL?

It should not. Direct database access bypasses Odoo's access rights, record rules and business logic, and it is not available on every hosting option. Going through the API keeps all of Odoo's own protections in force.

How do we test before going live?

Point the agent at a copy of your database and run a fixed set of real examples through it, including awkward ones. Check the records it creates, not only its replies. Then launch in draft-only mode with a human reviewing every result.

What stops the agent from seeing data it should not?

Two things: the access rights and record rules on its Odoo user, and the fact that it can only call the specific tools you built. Instructions in the prompt are a third, weaker layer and should never be the only one.

Sources and further reading

Primary documentation and research behind this guide.

• Odoo 18 documentation: External API
• OWASP: Top 10 for large language model applications

This architecture is deliberately plain, which is why it holds up in daily use. It is how Growmerz builds AI agents for Odoo and ERP. If you would like to talk through how it would fit your Odoo setup, book a free AI audit.