Channel Configuration — Agentic Extraction
Agentic extraction complements the classic, rule-based field extraction (Header Fields and Line Item Fields) with an AI agent that you instruct in natural language to read additional fields from a document. This is especially useful when information is embedded in free text, can be composed from multiple parts, or must be derived from context.
There are two variants, which appear as separate entries in the navigation under Document Processing:
| Variant | Scope | Typical fields |
|---|---|---|
| Agentic Header Extraction | Per document | Order number, delivery date, order type … |
| Agentic Line Item Extraction | Per line item (order line, invoice line, …) | Article number, quantity, unit, description … |
Operation and configuration are nearly identical. This page describes both together — everything that is not explicitly marked as line-item-specific or header-specific applies equally to both variants. The specifics of line item extraction are summarized in the section Specifics of line item extraction.
When a field does not always appear in the same place, is embedded in free text, or requires combined logic (e.g. "derive order type from brand + shipping address" or "read packaging unit from the description text"). For tightly structured fields, the classic extraction in Header Fields or Line Item Fields is sufficient.
Prerequisites
Before you create an agentic extraction, you should:
- Know which field the AI agent should additionally extract. The field must already be known as an output field: for header extraction, in the Header Fields; for line item extraction, in the Line Item Fields. The agentic configuration can only populate fields that Workist also knows as output.
- Know which data sources the agent should have available (email text, OCR text, already extracted fields, …).
- Optionally: prepare reference files (e.g. a list of common clause phrasings, an assortment list) that the agent may use as additional context.
An agentic extraction does not replace the classic field extraction. It acts as a complement: Workist first runs the regular extraction and passes its result to the AI agent, which then adds or replaces additional fields.
Per channel there can be one default configuration per variant — the default configuration for header extraction is separate from that for line item extraction. You can therefore run both at the same time.
Step 1 — Open the right page
In the channel, select the appropriate entry in the sub-navigation under Document Processing — Agentic Header Extraction or Agentic Line Item Extraction. As long as no configuration has yet been created for this channel, you will only see the notice "No configuration exists. Click 'New Config' to create one.".
At the top you will find two controls:
- Configuration selector ("Select a configuration") — here you switch between several existing configurations.
- + New Config — creates a new, empty configuration for this channel and opens it directly for editing.
Step 2 — Create a new configuration
Click + New Config. Workist creates an empty configuration, selects it automatically, and displays the editing form below.
A configuration always consists of a block of basic settings (name, scope, activation) and a block with the actual logic (instructions, fields, knowledge).
Configuration name
Next to the selector you will find a pencil icon. With it you enable the input field "Edit configuration name" and enter a descriptive name (e.g. "Delivery priority from free text" or "Variant extraction from description text").
The name then appears in the selection list at the top — choose it so that you and your colleagues can tell apart multiple configurations for the same channel.
Default vs. customer configuration
The first toggle in the form is called "Default Config".
The description in the Workbench reads: "Default configs run for all documents. Disable to create a client-specific config."
- Active (default configuration): The configuration runs on all documents of this channel — regardless of which customer they come from.
- Disabled (customer configuration): The configuration runs only for documents of specific business partners. As soon as you disable the toggle, the Workbench shows the additional input field "Client IDs".
Enter one or more customer numbers from your master data here (for invoices, order confirmations and delivery notes: supplier numbers) and confirm each one with Tab or Enter. Workist compares them with the number of the customer or supplier it recognized on the document. Multiple numbers in one configuration mean that this configuration is used jointly for those partners.
If a default configuration already exists for this channel (and this variant), the "Default Config" toggle is grayed out in every additional configuration. The note then reads: "A default configuration already exists for this channel." A default configuration that already has output fields or agent instructions can no longer be turned into a customer configuration; create a new configuration instead.
Workist first runs the default configuration and then at most one customer configuration: the one whose client IDs contain the number of the recognized customer or supplier. Values from the customer configuration override the values from the default configuration. A number can therefore only be in one customer configuration per channel and variant; the Workbench rejects overlapping client IDs when saving.
Activation
The "Enabled" toggle arms the configuration. If it is switched off, the configuration is not run during document processing — handy for "parking" a configuration without deleting it.
Agent instructions (the prompt)
In the "Agent instructions" field you describe in natural language what the AI agent should do. This text is passed to the model as an instruction.
A good prompt …
- states the goal clearly — "Extract …",
- names the source material — "… from the free text of the order …",
- defines the desired format — "… as 'urgent', 'normal', or 'undetermined' …".
Example (header extraction):
Extract the delivery priority from the free text of the order. Return 'urgent' if the text contains terms such as "rush", "urgent", "ASAP", or "immediate delivery"; otherwise return 'normal'. If the order contains no indication of priority, return 'undetermined'.
Example (line item extraction):
From the free text of each line item, extract the packaging unit (e.g. carton, pallet, piece) and the quantity per unit. If no unit is specified, leave the field empty.
If you want to reference an input field or output field in the prompt, type / — the Workbench opens a small menu with the fields you have already selected as input or output fields and inserts the chosen field as a reference. So select the fields first.
Input fields vs. output fields
This is the most important concept on this page — please read here especially carefully.
Input fields are the data sources provided to the agent. They give the model the content from which it should extract something: email text, OCR text of the attachment, already regularly extracted fields, attachment images, and so on.
Via + Add input field a menu opens with all available data sources. Click an entry to add it; use the trash icon to remove it again.
Output fields are the target fields into which the agent writes its results. Exactly these values end up in your output file or your target system.
Via + Add output field you select one or more fields from the channel's configured fields — for header extraction from the Header Fields, for line item extraction from the Line Item Fields. Only fields configured there are available; agentic configurations cannot invent new field names.
Rule of thumb:
| Question | Answer |
|---|---|
| "Where does the information for the agent come from?" | Input fields |
| "Where should the agent's result be written?" | Output fields |
Input and output fields can also be identical: if a field is already populated by the regular extraction but the agent should check and possibly override that value, list it in both areas.
Give the agent only the inputs it really needs. The fewer data sources, the more focused and faster the agent works.
Custom fields as the target of agentic extraction
So far we have only used fields that are already configured in the channel as Header Fields or Line Item Fields. For agentic extraction, however, you often want to create new fields that do not exist at all in the standard schema — such as "delivery priority", "line item variant code", or "order classification". This is exactly what custom fields are for.
Custom fields live in the regular areas Header Fields and Line Item Fields, but are empty there — they are not filled by the classic extraction. Instead, they are typically first populated with content by an agentic configuration, by selecting them as output fields.
The following workflow applies identically to both variants — for a header-wide field you work on Header Fields, for a line-item-wide field on Line Item Fields.
Step A — Create a "Custom field"
In the channel navigation, open Header Fields (or Line Item Fields, depending on whether the new field occurs per document or per line item).
At the top right, next to the heading "Configured fields", click the + symbol. A selection menu opens with two areas: at the very top "Custom field" with a plus sign, and below it — separated by a divider — the list of standard fields not yet added.
Click "Custom field". Immediately a new entry with the placeholder name "Untitled field" is created in the left-hand list and automatically selected. On the right side the associated input fields appear.
As long as you have not yet saved, the field is only visible in your session. If you switch to another page without Saving, the field is gone.
Step B — Fill in the required fields
For a custom field, four inputs are required (marked with * in the UI): the three below and the data type (preset to String, see below). The Required toggle is off for new custom fields.
| Required field | Meaning |
|---|---|
| Data label name | The name of the field in the output file (e.g. delivery_priority). Must be filled in and unique within the channel. The Workbench replaces spaces with underscores as you type. Once saved, this value can no longer be changed — it is part of your data contract with the target system. |
| Field label name | The name under which the field appears in the Workbench assistance (e.g. "Delivery priority"). Can be changed at any time without breaking the output file. |
| Data label instructions | Brief context for the AI on how and where it should recognize the field in your documents. Maximum 500 characters. Example: "The delivery priority is in the top right of the letterhead. Allowed values: high, medium, low." |
We recommend snake_case (lowercase letters, words separated by underscores, e.g. delivery_priority, customer_internal_note, variant_code). The Workbench does not enforce it. Avoid umlauts, hyphens, and uppercase letters — most target systems expect the same convention. Since the value is immutable after the first save, it is worth briefly agreeing on it in advance with your contact at Workist.
As long as the Data label name field is empty, the custom field cannot be saved — the Workbench cancels the save and marks the field red. Therefore enter the value right when creating it.
In addition, you choose the data type, which determines how Workist interprets and validates the extracted value:
| Data type | When to use? |
|---|---|
| String | Free text or categorical values (e.g. "high / medium / low", status codes, classifications). |
| Decimal | Amounts, prices, quantities with decimal places. |
| Integer | Piece counts, week numbers, ID-like numbers without decimal places. |
| Date | Date values. If a date is many months away from the document date, Workist lowers the confidence and explains this at the field. |
| Boolean | Yes/no answers ("Is it urgent?", "Carriage paid?"). |
For String, the field "Provide any options, if you want to constrain the possible values of the field" additionally appears. Enter a list of allowed values here if the AI should commit to a fixed vocabulary.
The choices field appears only for String. For numeric data types or date, the restriction makes no sense and is hidden.
As soon as you have entered the field label name, the left-hand list automatically adopts the new name — for example, "Untitled field" becomes "Delivery priority".
Step C — Formulate instructions carefully
The instructions for data labels are the lever with which you steer the hit rate of your custom field. Write concisely and concretely:
What a good instruction contains:
- Where in the document the value is located (top right? in the table? in a particular column?).
- What the value typically looks like (short examples, allowed values, common phrasings).
- What it is NOT (anti-examples, so the AI avoids confusion).
What you should leave out:
- Long background stories about the business process.
- Instructions to the AI on how it should "think" — that belongs in the agent instructions of the configuration, not in the field instructions.
Maximum 500 characters per field. If your instruction would need to be longer, check whether part of the information can instead be contributed as knowledge (file upload, see further below).
Step D — Save and include as an output field
Click Save at the bottom. Workist adopts the field as a regularly configured field — but initially without values, since the classic extraction does not know how to fill the new field.
Now switch back to the agentic configuration, open your configuration (or create a new one), and under Output fields click + Add output field. Your new custom field appears in the selection list alongside all the other fields of the channel.
Add the field, add appropriate input fields (e.g. the email text), provide the agent instructions, and click Save. From the next document onward, the agent fills the new field automatically.
Per field, only one primary source of truth — either classic (via lookups or fixed mappings) or agentic (via output fields). Agentic extraction runs after the classic one and overrides every field selected as an output field, whether or not it is also an input field.
Step E — Remove a custom field again
When you no longer need a custom field, click the × to the right of the field name in the left-hand field list and then Save. Remove the field beforehand from all agentic configurations in which it is listed as an output field. Otherwise processing of new documents in this channel fails.
If the field is already present in the output file of productive documents, deleting it does not remove it retroactively. Already exported data remains unchanged; only new documents no longer contain the field.
Knowledge (reference files)
In the "Knowledge" area you can upload files that are made available to the agent as additional context — for example a list of your order types, an excerpt from the assortment catalog, or an abbreviation table with customer-internal acronyms.
Allowed file formats are .txt, .csv, .md, and .json. Drag the files into the "Drop files here or click to upload" area, or click into it to open the file selection dialog.
The Workbench shows the estimated number of tokens per file. Files above the size limit or with more than 200,000 tokens are not uploaded. If a knowledge file is too large during processing, the configuration does not run; the output fields keep the values of the classic extraction with confidence 0, and the document shows a hint.
Uploaded knowledge files are passed into the prompt to the AI on every extraction. They are therefore not "secret" with respect to the model. Only upload content whose disclosure to the AI provider used by Workist is unproblematic (no passwords, no personal data that would not already be part of the document, …).
Keep knowledge files lean. The larger the file, the more expensive and slower each individual extraction becomes — and the agent can lose itself in irrelevant details.
RAG for few-shot learning
At the very bottom of the configuration you will find the option "Use Retrieval Augmented Generation (RAG) for few-shot learning".
You have two options:
- Add past assistances to the prompt — for each new document, Workist looks for up to five of the most similar cases from the same channel and provides them to the AI agent as examples. A document is stored as an example when a user changed one of the configuration's output fields in assistance. In many cases this noticeably improves the hit rate, once enough learning material is available.
- Don't include any past assistances — the agent works exclusively with the current document and the instructions.
For header extraction, you typically start with "None" and add RAG later, once a body of experience has built up in the assistance. For line item extraction, RAG is usually worthwhile from the start, because frequently occurring special cases of individual customers are recognized this way.
Tools
In the "Tools" area, you use Add tool to choose which lookups the agent may run on its own during extraction. The tools access the channel's master data: search and query articles, look up customers, contacts, delivery and invoice addresses, and list the existing values of article attributes. Give the agent only the tools it needs for its task.
The AI agent's model, temperature, and reasoning effort are managed by Workist and are not visible in your Workbench login. If you would like an adjustment here, please contact your contact person at Workist.
Step 3 — Save and activate
At the end of the configuration, click Save. On success, a confirmation appears; the configuration is then active for subsequent documents, provided the Enabled toggle is switched on.
Only with the next incoming document. Already processed documents are not re-extracted retroactively.
Recommended order with the default configuration
If you maintain both a default configuration and one or more customer configurations for the same channel:
- Keep the default configuration deliberately simple — it describes what should apply to all customers.
- Use customer configurations only where a single customer or a small group of customers need specifically deviating logic.
- Remember: the customer configuration overrides the values from the default configuration. Fields extracted twice therefore always win from the customer-specific configuration.
Step 4 — Switch, rename, delete configurations
Multiple configurations appear at the top in the selection list. Click the list to load a different configuration — the form below updates automatically.
- Rename: Click the pencil icon next to the selector, enter a new name, and Save.
- Delete: The trash icon to the right of + New Config. Workist asks for confirmation before deleting, just to be safe. Deletion is final — a deleted configuration (including all uploaded knowledge files) cannot be restored. If you only want to pause briefly, switch off the "Enabled" toggle instead.
Specifics of line item extraction
Agentic line item extraction follows all the steps described above — with three differences:
- It runs per line item. The configuration is applied to each individual line of the document. This makes it powerful, but also slower and more expensive than the header variant (each line item produces its own AI call).
- Output fields come from the Line Item Fields. If you want to extract a field that does not yet exist there, first create it as a custom field in the Line Item Fields.
- Structural line item operations can be enabled by Workist on request — the agent may then add, delete, split line items, or link them hierarchically as sub-items (e.g. split "2 pallets of 24 pieces each" into several logical lines). These operations are managed by Workist and cannot be configured by yourself. Documents with sub-items always go into assistance (see When is a document automated?).
If both the classic extraction and the agentic line item extraction populate the same field, the agent overrides the classically extracted value. Therefore, prefer as output fields those that the classic extraction does not reliably capture.
Recommended order when setting up a new channel: first fully configure the Line Item Fields, then observe which fields regularly remain empty or are poorly recognized, and only then create an agentic line item extraction specifically for those problem fields.
Frequently asked questions
Do I have to create a separate configuration for each field? No. A configuration can fill any number of output fields at the same time. It usually makes sense to bundle thematically related fields into one configuration — then the agent "sees" the overall context.
What happens if I deactivate the configuration? Workist skips it on the next processing run. Existing output values from earlier runs remain unchanged.
What happens if the agent cannot extract a field? If the agent finds no value, it returns an empty result — and that overrides the value of the classic extraction. Workist only keeps the classic value if the configuration could not run for technical reasons. The values then stay, their confidence is set to 0, and the document shows a hint that the AI rule could not be run.
How many configurations can I create? One default configuration per variant and any number of customer configurations per channel. Each client ID may only be in one customer configuration; at most one customer configuration runs per document.
Are my knowledge files passed to the AI? Yes — knowledge files are embedded in the AI's prompt. So do not upload content that is not part of the extraction or that you do not want to pass on to Workist's AI provider.
Help and support
If a configuration does not deliver the desired result, contact your contact person at Workist. Have the following information ready:
- the channel name and the configuration name as well as the variant (header or line item extraction),
- whether it is a default or customer configuration (for a customer configuration: the affected client IDs, i.e. customer or supplier numbers),
- a sample document on which the configuration delivered an incorrect result,
- the value the agent delivered and the value you would have expected.