跳到主要内容
新品云 ERP 正式上线,几分钟开通专属实例

技术分享

Putting an agent inside a business system: five design principles from the engineering side

Wiring agentic AI into a business system (Odoo 20, in our case) looks from the outside like "adding a chatty assistant". Engineering-wise it is opening a channel through which automation gets to act with power — and the more power, the more precisely the boundaries need writing. Our agentic_ai engineering ended up as four layers — a core plus a sales bridge, an ERP tools bundle and an MCP bridge — each installed separately, each owning one stretch of the boundary. These five principles come out of the v2 design review and were hardened through eight further rounds of independent review plus one design-level review; product figures below reflect the state after the October 2026 review close-out.

The four layers of agentic_ai: core, sales bridge, ERP toolkit and MCP bridge — installed separately, each owning one stretch of the boundary

Principle 1: a tool is a business action, not a database channel

The most tempting design in a tool list — one universal "run any query" tool — is exactly the one to refuse. Every tool maps to a business action with clear semantics: "list unpaid orders for this customer", "create a follow-up task for this order".

Two reasons: permissions can be aligned (business actions have a natural permission owner; "any query" has none), and audit can be explained (the log says "which business object changed", not "some SQL ran"). The engineering counterpart is a trusted registry: tool execution never resolves arbitrary import paths — it takes pre-registered native handlers from an allow-list, and anything unregistered is refused (fail-closed).

Principle 2: permissions align on two levels — natural language is not a bypass

Whether a tool may run is the intersection of two layers:

  1. The operator's real permissions in Odoo (record rules, multi-company filters all in force);
  2. The agent's configured tool allow-list.

A natural-language entry point must never become a bypass around any permission — that is the floor for putting an agent into a business system. Any over-reach (even "saw data it should not") is a blocker, not a nice-to-improve.

That alignment now reaches the field level rather than staying a convention: for health and audit data, raw values are readable only by the admin group, while display values are recomputed per reader — a reader needs both the metric's access group and read access to the evidence model, or sees nothing; free-text summaries are gated by the set of groups that could appear in them, hidden as a whole if the reader lacks any. No readable value, no "blurred" middle state.

Principle 3: guardrails in front of the plan, not only before execution

Safety checks run at two layers: filtering during planning + checks at execution.

  • Planning-time filtering is the experience layer: tools the operator cannot use, actions unavailable in context — removed while the plan is formed, so users never watch the agent walk into dead ends;
  • Execution-time checks are the backstop: the full check chain still runs before every call, preventing bypasses.

Both layers carry rate and cost limits: estimates at the plan layer, deductions at the execution layer.

Principle 4: tier write confirmations by blast radius

"Confirm everything" trains users to click through blindly; "confirm nothing" is an incident in waiting. Tier by impact:

Risk tier Examples Confirmation
Low Drafts, internal tasks Automatic, undo available
Medium Field edits, status moves Batched confirmation
High Over-threshold amounts, deletions, external sends Item by item, with before/after

After approval the tool runs, and the result stays verbatim in the conversation and the audit log

The tiers themselves are configuration — the confirmation flow is the enterprise's policy made executable, not a hard-coded product behaviour. And every step lands in an immutable audit log: who started it, what was read, what was done, who approved — fully reconstructable afterwards.

The audit contract is complete in the same way: every model call — including failures, retries and provider fallbacks — leaves a row with its duration and the model used (without failure rows, a success rate reports the worst stretch as 100%). Confirmations carry freeze semantics: if the record moves after the preview, the approval lapses and a fresh confirmation is required — no silent overwrite.

Principle 5: honest acceptance — demos do not sign off

An agent is easiest to fool with one beautiful demo. Our acceptance runs in graded task suites:

  • Read-only Q&A → single write → multi-step cross-module, each level passed before the next;
  • Metrics include an over-reach rate that must be zero, confirmation-trigger accuracy and traceability;
  • The suite deliberately contains "should refuse / hand to a human" cases — when the agent is unsure, the correct behaviour is to stop and ask, not to guess; passing those counts as passing.

This is not theory: the product-side agentic_ai module currently holds 13 test files and 205 cases, with every review fix landing with a regression test and the security and confirmation paths taking the largest share — the shape of the test suite is the engineering stance made visible.

Acceptance has also moved from a one-off exercise to a standing state: the product's Implementation & Health Center turns those boundaries into a visible instrument — 34 runtime and business metrics, each with its definition, thresholds and recommendation (the whole metric dictionary is generated straight from the definitions, so the doc cannot drift); issues are tracked per company × metric × period and auto-resolve when healthy; missing data reads "not scoreable" and is never back-filled with a zero; agent-written assessment summaries are re-checked against the groups visible at generation time before any reader sees them. Every level of the graded acceptance has its current evidence on that board.

The Implementation & Health Center: 34 runtime and business metrics, per-period issues, and a

In closing

Not one of these five principles is "AI technology" — all of them are engineering boundaries. Which may be the truest picture of agentic AI in practice: model capability sets the ceiling; engineering boundaries decide whether it ships.

We condensed the whole design spec into a full implementation document on Odoo 20 — “Agentic AI for Odoo 20: design and implementation document (v2)”, covering architecture, the tool system, guardrails and acceptance; the full document is available on request via the site's contact channel.

Updated 2026-10-12: product state after the review close-out — suite size (205 green), reader-level masking and the observation contract, the Implementation & Health Center.

相关产品与 ERP 实践文章在宏斋博客。 宏斋云ERP · Blog

返回列表