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 available. Click 'New configuration' to create one.".
At the top you will find two controls:
- Configuration selector ("Select a configuration") — here you switch between several existing configurations.
- + New configuration — creates a new, empty configuration for this channel and opens it directly for editing.
Step 2 — Create a new configuration
Click + New configuration. 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 configuration".
The description in the Workbench reads: "Default configurations work for all documents. Disable to create a customer-specific configuration."
- Active (default configuration): The configuration runs on all documents of this channel — regardless of which customer / tenant they come from.
- Disabled (customer configuration): The configuration runs only for documents of specific client IDs (tenants). As soon as you disable the toggle, the Workbench shows the additional input field "Client IDs".
Enter one or more client IDs here and confirm each one with Tab or Enter. Multiple client IDs in one configuration mean that this configuration is used jointly for those customers.
If a default configuration already exists for this channel (and this variant), the "Default configuration" toggle is grayed out in every additional configuration. The note then reads: "A default configuration already exists for this channel."
Workist first runs the default configuration and then all matching customer configurations (all whose client IDs match the document). Values from the customer configurations override the values from the default configuration. This allows customer-specific particularities to be modeled as targeted additions to a general baseline.
Activation
The "Activated" 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 a single quote ' (or /) — the Workbench opens a small menu with all available field names that you can insert as a reference. This keeps the prompt correct even if field names change later.
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 "Unnamed 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, three inputs are required (marked with * in the UI):
| Required field | Meaning |
|---|---|
| Data label name | The name of the field in the output file (e.g. delivery_priority). Must be filled in, unique within the channel, and in snake_case — that is, only lowercase letters, digits, and underscores, no spaces or special characters. 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. |
| Instructions for data labels | 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." |
Use exclusively snake_case (lowercase letters, words separated by underscores, e.g. delivery_priority, customer_internal_note, variant_code). Avoid umlauts, hyphens, spaces, 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 — additionally validated against the date format of the channel. |
| Boolean | Yes/no answers ("Is it urgent?", "Carriage paid?"). |
For String, the field "Specify options if you want to restrict 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, "Unnamed 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 custom field, only one primary source of truth — either classic (via lookups or fixed mappings) or agentic (via output fields). If both try to write the same field, the classic extraction wins first; agentic configurations can, however, override the result, provided the field is also listed as 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. Be sure to also remove the field beforehand from all agentic configurations in which it is listed as an output field — otherwise those configurations may fail when saving.
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, and .md. Drag the files into the "Drop files here or click to upload" area, or click into it to open the file selection dialog.
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 previous assistances to the query — for each new document, Workist looks for similar cases that have already been corrected in the assistance and provides them to the AI agent as examples. In many cases this noticeably improves the hit rate, once enough learning material is available.
- Do not include previous 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.
The AI agent's model, temperature, and reasoning effort — as well as the tools (e.g. an article search that the agent may call during extraction) — are managed by Workist and are usually 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 Activated 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 configurations override 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 configuration. 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 "Activated" 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.
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? The field remains empty. The classic extraction (if the same field is also configured there) provides the value in that case.
How many configurations can I create? One default configuration per variant and any number of customer configurations per channel. If you create multiple customer configurations for overlapping client IDs, all matching ones are executed — the order corresponds to the save order.
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),
- a sample document on which the configuration delivered an incorrect result,
- the value the agent delivered and the value you would have expected.