An AI agent for Subiekt GT: the queue you have to build yourself

Why I'm Writing This

Two weeks ago I put a developer's guide to Sfera for Subiekt GT on this blog, and yesterday a three-way API comparison that set enova365, Optima and Subiekt next to each other. One row of that table has bothered me ever since. enova365 gives you a buffer. Optima gives you three provisional stops. Subiekt GT gives you nothing, and all I left in the cell was: design it on your side.

That note is the entire project. So here is what "design it on your side" actually means — the Subiekt counterpart of what I've already written for enova365 and for Optima.

The Missing Buffer Is Not a Detail

In enova365 an agent creates a document with the Bufor flag set. Saved, visible, editable, no stock moved, no VAT register touched. A person opens it, fixes what's wrong, approves. If the agent produced nonsense, somebody deletes a draft and nothing happened.

Sfera doesn't work that way — and that's a deliberate decision by InsERT, not an oversight. A document created through Sfera is a real document. It takes the next number from the series. It prices itself through the same rules a salesperson would trigger. A WZ or an FS moves stock, an FS creates a receivable. Which is exactly why you use Sfera instead of writing to the tables: the document behaves the way Subiekt would make it behave. The flip side is that there's nowhere safe to be wrong.

Put the asymmetry plainly, because it's what changes the cost of a mistake across the three systems:

• A wrong draft in enova365 costs a delete.
• A wrong document in Subiekt GT costs a number in the series, a stock movement to reverse, and — if it already went out — a conversation with a customer who's holding the PDF.

Check on your own installation what removing one actually does. It depends on the document type and on how your series are configured, and the answer is never "everything goes back to how it was". That's the ceiling on how brave an agent gets to be here.

The Queue Is the Product

Everything follows from that. On Subiekt, an agent isn't a thing that writes into your ERP and lets people tidy up afterwards. It's a process that ends in one click, and the Sfera call comes after the click. Never before. Never "and then someone reviews it".

Concretely: the shim from the guide — the small Windows service that owns the COM session — holds a queue. Each item is a proposal. This email, from this customer, means this document, with these lines, at these prices, and here's why I think so. A person sees the proposal next to the original message, changes what needs changing, approves. Only then does the shim touch Sfera.

The inversion has a side effect nobody expects. Since the review happens in your interface rather than in Subiekt, the reviewer needs no Subiekt licence seat, doesn't have to sit at the Windows host and doesn't have to know the ERP. In a wholesale business that usually means the person who actually knows the customers can approve orders from a phone. The ERP was never going to allow that.

Start With ZK, Not FS

If you're going to write anything, write a customer order. ZK is as close to a reviewable state as Subiekt GT gets: it can hold a reservation, it creates no receivable, and a person realises it into a WZ or an FS — someone who has to open it anyway. Compare that with issuing a sales invoice straight off an email. You've just built a tax document out of a parsed message, and the only reviewer is the customer.

There's a second reason, and it's commercial rather than technical. In most of the wholesalers I've worked with, the order arrives as an email or a PDF and somebody retypes it. Reservation logic, price levels, the credit check — all of it already sits in the ERP and simply never runs, because the order isn't in the ERP yet. I made the same argument from the credit side in the post on credit limits: the earliest check is the cheapest, and it's also the rarest, because the order never reaches the system as an order. As for how reservations really behave — what they hold, what they don't, where they quietly expire — that's the Optima reservation post. Different mechanics, same trap.

Getting the email into Subiekt as a ZK, correctly, with the reservation it implies — that's the whole project. Everything after it is Subiekt doing what it already does.

Where the Work Actually Is

Everything expensive happens before the click, and none of it is model work:

The contractor. A NIP resolves almost always. A company name pulled from an email signature resolves badly, and the near-duplicate cards sitting in every Subiekt database — the same company entered twice by two salespeople — make it worse. Match on NIP, then on the sender's email domain if you store it, then stop. Anything less certain goes into the queue as "which of these two?", which a human answers in a second.

The items. This is where projects die, and it has nothing to do with AI. Customers order in their own language: "ten cartons of the 5-litre", a photo of last month's delivery note, a spreadsheet full of their internal codes. Before anyone builds anything, count what share of order lines resolve to exactly one item in Subiekt. In practice it lands between 40 and 70 percent, unless the customer orders from your catalogue codes. Below half, the fix is a per-customer alias table — their code, your symbol — filled in from history. It'll move the number further than any model will.

The price. Subiekt already knows the answer, through price levels and per-customer discounts. The agent's job is to read it, not to compute it. A proposal showing a price the ERP wouldn't have produced is a bug, not a feature.

The stock and the limit. Read both before proposing, then put them in the proposal. "This order is 3 400 zł and takes the customer to 96 percent of their limit" turns approval into a decision instead of a formality.

The Retry Problem

Here's the failure specific to a system with no drafts. You call Sfera, the call times out, and you've no idea whether the document exists. Nothing to look at, either, because a document the agent created is indistinguishable from one a person made.

Never retry blind. Two rules:

1. Carry your own key into the document. Write the queue item's identifier into a field the document actually holds — Uwagi, or a custom field if your document type exposes one through Sfera — and query Subiekt for that key before any retry. This is the one piece of integration hygiene I'd refuse to ship without.
2. Sweep. Every few minutes, reconcile open queue items against documents created in the last hour. Timeouts resolve themselves; you just have to look.

The other failure mode from the guide belongs here too. Sfera holds a live handle to a running subiekt.exe. Somebody closes it, an update restarts it, the machine reboots overnight — and the handle is dead, and it doesn't heal. A queue that quietly stops producing documents looks exactly like a quiet week. Alert on "no successful Sfera call in N hours" rather than on errors, because a dead handle usually throws none.

Who the Agent Is When It Logs In

The Sfera connection carries two identities: a SQL Server login and a Subiekt operator. Give the agent its own operator account instead of borrowing a person's. Not for security theatre — for the audit trail. Every document it creates then carries a name that isn't a salesperson's, and six months later, when somebody asks how this order got in, the answer sits in the document rather than in somebody's memory.

Same boundary I described as the four permission levels: read, propose, write, send. On Subiekt the agent lives at level two and crosses to three only on a click. It never issues an FS unprompted, never releases stock, never emails a customer a document. The click is the signature, and it belongs to a person.

The First Build Has No Downside

Write nothing for the first month. Point the agent at the mailbox where orders land and have it produce a daily read-only report with three numbers:

• Match rate: order lines resolvable to exactly one item in Subiekt, plus the list of the ones that aren't. That list is your alias table, ready to fill in.
• Would-have-been-blocked: orders that came in from customers already over their credit limit or sitting on overdue invoices. Every one of those is an order somebody accepted without knowing.
• Time to system: hours between the email arriving and the matching ZK existing in Subiekt. Nobody measures this, and everybody guesses low.

A month of that costs nothing and settles the question. High match rate, two hours to system? You have a good process and no project — a real result, cheaply bought. Half the lines unresolved and orders sitting for a day and a half? Now you know what to build, and you have the baseline to prove later that it helped. Then switch proposals on for one customer, watch what share a person edits before approving, and widen once that drops under ten percent.

Running Subiekt GT with orders arriving by email? Get in touch. This is the kind of AI agent I build: read first, propose second, and the click stays with the person who owns the customer.