# 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](#specifics-of-line-item-extraction). :::tip When agentic extraction pays off 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](/en/docs/channel-configuration/document-processing/header-fields.md) or [Line Item Fields](/en/docs/channel-configuration/document-processing/line-item-fields.md) 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](/en/docs/channel-configuration/document-processing/header-fields.md); for line item extraction, in the [Line Item Fields](/en/docs/channel-configuration/document-processing/line-item-fields.md). 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. :::note 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**. :::note Only one default configuration per channel 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. ::: :::note Execution order 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 … 1. **states the goal clearly** — "Extract …", 2. **names the source material** — "… from the free text of the order …", 3. **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. :::tip 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. :::tip Tip for selecting input fields 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](/en/docs/channel-configuration/document-processing/header-fields.md) and [Line Item Fields](/en/docs/channel-configuration/document-processing/line-item-fields.md), 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. :::note 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."* | :::tip Naming the data label name 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. ::: :::warning Saving requires a value 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. :::note 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. :::note Limit 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. :::tip Rule of thumb 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. :::warning 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. :::warning Confidentiality 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, …). ::: :::tip 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. :::note Settings managed by Workist 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. :::note When does the new configuration take effect? 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: 1. Keep the default configuration **deliberately simple** — it describes what should apply to **all** customers. 2. Use **customer configurations only where** a single customer or a small group of customers need **specifically deviating logic**. 3. 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](#custom-fields-as-the-target-of-agentic-extraction) 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?](/en/docs/channel-configuration/document-processing/validation-checks.md#when-is-a-document-automated)). :::warning Overrides the classic extraction 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](/en/docs/channel-configuration/document-processing/line-item-fields.md), 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.