Template agent
This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.
The Agent tab configures how Cogneris refines a template's extraction after the first pass: which AI model runs each step, how often low-confidence fields are re-extracted, which domain agents (such as fraud detection) run, and how much a run may cost. You can test an unsaved configuration on a sample document and review every run of the template.
| How to get here | Templates › open a template › Agent tab (between Schema and Redaction). It opens on Mode. See Templates. |
| Who can use it | Tenant administrators and technical administrators (customer-admin, customer-tech) and the Cogneris roles cogneris-admin, cogneris-tech and cogneris-platform-admin. The service refuses reading, saving, cost preview and dry runs for other roles. The run history is readable by any signed-in user of the tenant. |
| Content status | From source; not observed (vision-fe 0b724a0 + cogneris-vision-fe#192, vision-be fce7fcc + cogneris-vision-be#504, 2026-10-22) |
How the agent works at run time
- When it runs. When an extraction is requested with a template and the agent engine is enabled in the service, Cogneris first extracts the document in a single pass. If the template has a saved agent configuration, the agent then refines that result; without one, the single-pass result is returned unchanged.
- Checks before the run. The saved configuration is combined with the tenant's agent guards (see Tenant agents). The run is refused, and the extraction fails with
code: reason, when the tenant has paused agents (agents_paused), when a model the run could use breaks the tenant's model rules (model_not_allowed), or when an enabled domain agent is not on the tenant's allowed list (agent_disabled). Only synchronous mode is accepted. - Monthly cap. Before a run (not a dry run), the tenant's month-to-date agent spend is compared with its monthly cap; at or above the cap the run fails with
monthly_cap_exceeded. See Budget. - Refinement. A validator model scores every extracted field. Fields below the Confidence threshold are re-extracted by a focused extractor call and scored again, up to Max attempts times (see Retry). Then each enabled domain agent runs in turn.
- Limits during the run. The whole run must finish within the sync timeout (
sync_timeout, see Mode), and no model call may push the run over the per-run cost cap (budget_exceeded, see Budget). - What is kept. Every run is recorded with its status, cost, the configuration it actually ran with, and one entry per step (model, latency, cost, outcome). These appear under History.
Effective configuration banner
A collapsible bar above the tabs, labelled Effective configuration. Expanded, it shows as JSON what would actually run for this template: the saved configuration after the service has applied the platform's default per-run budget and the tenant guard checks. It reflects the saved configuration, not unsaved edits, and refreshes after each save.
- It shows an empty JSON object when the template has no saved configuration, or when the guard checks would refuse the run (the reason is not shown here — run a dry run to see it).
- After the Router tab has computed a cost preview, the bar also shows ≈ … per typical doc.
- If the service cannot be reached, the bar is not shown.
Save bar
Always visible at the bottom of the tab. All six tabs edit one shared draft; nothing is stored until Save.
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| Test on sample | Opens the dry-run dialog with the current, unsaved draft. See Dry run. | Administrators | — |
| Discard | Returns every tab to the last loaded or saved configuration. Enabled only when there are unsaved changes. | Administrators | — |
| Save (Saving...) | Sends the whole configuration with the version number you loaded. Enabled only when there are unsaved changes. | Administrators | Yes — save again with other values |
Versions. The first save stores version 1; each later save increases the number by one. The number only detects concurrent edits: if someone saved in between, your save is refused with version_conflict: expected …, actual …. Reload and retry. Previous configurations are not kept, so there is no version to roll back to. What a past run used is kept with the run itself.
A save keeps settings that have no control on this screen as they are stored — in particular react_retry_enabled (whether the retry pass runs at all; on by default), which you set through the API.
When the configuration is saved, the service also removes workflow-only agents (face extraction, facematch, cross-document validation) from the enabled list; those run only when a workflow step asks for them.
Messages that can appear in the save bar:
| Message | Cause | What to do |
|---|---|---|
version_conflict: expected …, actual …. Reload and retry. | Someone else saved this template's configuration after you opened it. | Reload the page, reapply your changes, save. |
retry.max_attempts must be in [0, 4]. · retry.confidence_threshold must be in [0.0, 1.0]. · per_run_budget_cents must be greater than 0; omit it to use the default. · sync_budget must be greater than 0s and at most 60s; omit it to use the default. | A value outside the service's range (the screen normally prevents these). A cost cap of 0 or a sync timeout of 0 seconds is refused because no run could succeed with it. | Correct the value, or leave the field empty to use the default. |
| Request failed | Loading or saving failed without a message from the service. | Try again. |
Mode
Card Execution mode.
Fields
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Execution | How the agent runs. Runs are always Synchronous; the card states it, and there is no other mode to choose. | — | Synchronous | Synchronous | — |
| Sync timeout (seconds) | Maximum time the whole agent run may take. The current value is shown next to the label. Maximum time to wait for sync extraction. Range: 1–60s. Engine default is 12s when unset. | No | Slider, whole seconds 1–60 | 12 (not stored until you move the slider) | sync_budget must be greater than 0s and at most 60s; omit it to use the default. |
At run time. When the time runs out, the run stops and fails with sync_timeout (Sync budget of … s elapsed before the agent finished.). The service's hint for this error suggests faster or cheaper models. A timeout of 0 seconds is refused when you save, because the run would have no time at all; a configuration saved with 0 before this check existed opens with the default (12s) and is repaired by the next save.
Router
Card Per-step model selection — Choose which AI model handles extraction and validation. Tier presets fill both steps with fast, balanced, or premium models.
Fields
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Extractor | Model pinned for the focused re-extraction in Retry. | No | Use tenant default, or one of the active models recommended for this step, shown as name — tier (Fast, Balanced or Premium) | Use tenant default | — |
| Validator | Model pinned for the validator that scores fields, and for the other validator-type calls of a run. | No | As above | Use tenant default | — |
Loading... is shown while the model lists load. If they fail to load, the lists stay empty.
Buttons and actions
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| Tier preset: Fast / Balanced / Premium | For each of the two steps, picks the first model of that tier in the step's list. A step with no model of that tier is left as it is. | Administrators | Yes — Discard or change the selects |
Cost preview
About 0.4 s after each change, the service estimates the cost of the configuration and the card header shows ≈ … per typical doc in US dollars. The estimate uses fixed token counts per step (extractor 5,000 in / 2,000 out, validator 3,000 / 1,000), the model's price, and a typical document of 5 pages. Steps you have not pinned are estimated with the models the platform would use. If the estimate fails: Preview cost failed followed by the service's message.
At run time.
- Use tenant default removes the pin: the step uses the model the platform configures for it, with the platform's fallback model if the first one is rate-limited.
- A pinned model always wins and has no fallback.
- A run dispatches extractor and validator calls only. The screen no longer offers Planner or Post-process pins; a pin for them saved by an earlier version stays in the configuration but is neither used by a run nor priced by the preview.
- Saving does not check pins against the tenant's model rules. A pin that breaks them (provider, region, model class, no-training, zero-retention, or the health-data rule) is refused when the run starts, with
model_not_allowed.
Retry
Card Retry policy — When a field's confidence falls below the threshold, the engine re-extracts that field up to the configured number of times.
Fields
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Max attempts | How many focused re-extraction rounds a run may make. The current value is shown next to the label. 0–4 attempts. | Yes | Whole number 0–4 (typed values are rounded and clamped) | 2 | retry.max_attempts must be in [0, 4]. |
| Confidence threshold | Score a field must reach to be left alone. 0.00–1.00. Higher values trigger more retries. | Yes | Slider 0.00–1.00, step 0.01 | 0.85 | retry.confidence_threshold must be in [0.0, 1.0]. |
At run time. The validator scores every field (this score is the validator's own, not the extractor's self-reported confidence). While any field is below the threshold and attempts remain, the run makes one focused extractor call for those fields and one more validator call. Each round therefore costs two model calls. Max attempts 0 keeps the scoring but never re-extracts. Fields still below the threshold at the end stay flagged; whether they go to human review is decided by the tenant's minimum field confidence (see Tenant agents), not by this threshold.
Domain agents
Card Domain agents — Domain-specific agents add extra checks (fraud detection, GL coding, cross-document validation) to extraction runs for this template.
Notice: Per-agent settings are now delivered to enabled agents at runtime. Some agents may still ignore specific fields as their implementations mature.
The list comes from the service and contains every registered agent that a template may enable, each with a checkbox, its name and its key. At vision-be fce7fcc these are:
| Agent (label) | Key | Settings |
|---|---|---|
| Fraud detection in Playground | fraud-detection | Fraud detection settings: sensitivity (required) — select Select, low, medium, high — How aggressive to flag potential fraud markers. |
| ReAct retry on low-confidence fields | react-retry | None — This agent doesn't expose a configuration schema yet. |
The settings form appears only while the agent is enabled. Agents of a workflow (face extraction, facematch, cross-document validation) are not offered here.
Fields
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Agent checkbox | Adds the agent to the template's enabled list. | No | On / off | Off | — |
| Fraud detection in Playground checkbox | As above. Disabled when the tenant has not allowed fraud detection, with Fraud detection in Playground is unavailable because your tenant has not enabled it., or when the tenant guards could not be loaded, with Fraud detection in Playground is unavailable because tenant permissions could not be loaded. | No | On / off | Off | — |
| sensitivity | Fraud risk appetite. It moves the two risk thresholds only: low review 0.50 / suspect 0.85; medium 0.35 / 0.70; high 0.20 / 0.55. | Marked required | low, medium, high | Unset, which runs as medium | — |
Agents with other settings would render them with a generic form: text, number (with its minimum and maximum), yes/no, a choice list, or a comma-separated list (Comma-separated list of values., placeholder value-1, value-2, value-3). Any other type shows This field type isn't yet supported by the v1 form renderer.
At run time. Enabled agents run after the retry pass, in the order they were enabled, each on the result of the previous one; each one's cost adds to the run, and a failing agent fails the run. Fraud detection examines the refined fields and the document's bytes and records a fraud assessment (see Playground). If the tenant's allowed list of domain agents is not empty and does not contain an enabled agent, every run fails with agent_disabled.
Messages: Loading...; Could not load domain agents followed by the error; No domain agents are registered yet.
Budget
Card Budget.
Fields
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Per-run cost cap (USD) | Hard cost ceiling for one run. Optional. Hard cap per run. Leave empty to use the tenant default. | No | US dollars, two decimals (stored in cents), at least 0.01; a value that rounds to 0 cents or is negative is ignored | Empty (placeholder 0.00) | per_run_budget_cents must be greater than 0; omit it to use the default. |
At run time. Before every model call the service adds an estimate of that call to what the run has already spent; if the sum would exceed the cap, the run stops with budget_exceeded (Estimated next-step cost (…¢) would exceed per-run budget (…¢, accumulated …¢).). The service's hint: Increase the per-run budget on the template, or move the validator to a cheaper model. When the field is empty, the service applies the platform's default per-run budget if one is configured, otherwise no per-run cap. A cap of 0 is refused when you save, because it would refuse every model call; a configuration saved with 0 before this check existed opens with the field empty and is repaired by the next save.
Month-to-date spend
Below the field, the Month-to-date spend chart shows one bar per day of the current month with this template's agent spend in US dollars, and a dashed line at the monthly cap.
| Element | Content |
|---|---|
| MTD spend | Sum of this template's daily spend since the first of the month. Dry runs are not counted. |
| Monthly cap | The tenant's monthly cost cap, which is what runs are checked against. Hidden when there is no cap. |
Messages: Loading...; Could not load chart followed by the error.
Monthly cap and plan ceiling. The monthly cap is a tenant-wide setting on Tenant agents, not on this tab. When it is saved, the service checks it against the maximum cost cap of the company's billing plan (a plan maximum of 0 means unlimited) and refuses a higher value with plan_ceiling_exceeded: requested … > ceiling …. Upgrade your plan to raise this cap. If billing cannot be reached the save is refused (plan_ceiling_unavailable). The check is skipped when a Cogneris platform administrator has set an override for the tenant. At run time, a cap of 0 means no monthly cap; otherwise every non-dry run is refused once the tenant's month-to-date spend over all templates reaches the cap.
History
Card Run history: the runs of this template, newest first, 100 at a time.
| Column | Content |
|---|---|
| Status | Run status as the service reports it, colour-coded. |
| Started | Start date and time. |
| Finished | End date and time; — while running. |
| Cost | Total cost in US dollars. |
| Flags | Dry run for runs started from Test on sample. |
| Error | Error code of a failed run, such as budget_exceeded, sync_timeout, monthly_cap_exceeded, model_not_allowed or policy_blocked. |
Click a row to open Run detail: Status, Started, Cost, Error (when there is one) and Steps — one line per step with its kind, model, latency in ms, cost and outcome, or No steps recorded. Close it with ×.
Buttons and actions
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| Load more (Loading...) | Loads the next 100 runs. Shown while more exist. | Any tenant user | — |
| Export CSV (Exporting...) | Downloads agent-runs-…csv with up to the 5,000 most recent runs of this template: request_id, template_id, status, started_at, finished_at, total_cost_cents, is_dry_run, error_code. A failed export only re-enables the button. | Any tenant user | — |
Messages: Loading...; Could not load runs followed by the error; No runs recorded for this template yet.
Dry runs are deleted 30 days after they were made (the service sweeps them every hour). Other runs stay.
Dry run
Test on sample opens Dry-run on a sample — Run this template's draft configuration against a sample document. The result is stored for 30 days and is not used for billing.
Fields
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Sample document | The document to test on. The file name and size in bytes are shown once chosen. The file is sent inline with the request. | Yes | Any file | — | sample_doc_base64 is required (FE must inline the test document bytes). |
Buttons and actions
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| Run (Running...) | Runs the current draft — saved or not — on the sample. Enabled once a file is read. | Administrators | — |
| Cancel / × | Closes the dialog and clears it. | — | — |
Result
| Element | Content |
|---|---|
| Result header | Run ID, status (succeeded or failed) and total cost, plus the fraud check badge for this run. |
| Error line | code: reason when the run failed. |
| Refined draft (dry-run output) | The fields the agent produced, as JSON, or No refined draft was produced. |
| Production comparison | A side-by-side production extraction will appear here in a future update. |
What the service does.
- The draft is applied over the saved configuration: its execution mode and retry settings win; its model pins are added to the saved ones (a pin removed only in the draft still applies); an empty domain-agent list or an empty per-run cap falls back to the saved value.
- The same tenant guard checks as a real run apply. A refusal shows as Dry-run failed or as
code: reason. - The monthly cap is not checked, and dry runs are left out of month-to-date spend.
- The run starts from an empty set of fields — the template's single-pass extraction is not run on the sample first — and the sample counts as one page.
- The run is recorded in History with the Dry run flag and deleted after 30 days.
Common problems
| Message | Cause | What to do |
|---|---|---|
version_conflict: … | Concurrent save. | Reload, reapply, save. |
agents_paused: Tenant has paused agents. | Agents are paused for the tenant. | Resume agents on Tenant agents. |
model_not_allowed: Model '…' … | A pinned or platform model breaks the tenant's model rules. | Pick another model on Router, or adjust the tenant guards. |
agent_disabled: Domain agent '…' is not in tenant allowed_domain_agents. | An enabled agent is not allowed for the tenant. | Disable it on Domain agents, or allow it on Tenant agents. |
budget_exceeded | The per-run cost cap is too low for the models used. | Raise Per-run cost cap (USD) or choose cheaper models. |
sync_timeout | The run took longer than Sync timeout (seconds). | Raise the timeout or choose faster models. |
monthly_cap_exceeded | The tenant's month-to-date spend reached the monthly cap. | Raise the cap on Tenant agents (within the plan) or wait for the next month. |
| Fraud detection in Playground is unavailable because your tenant has not enabled it. | Fraud detection is not on the tenant's allowed list. | Allow it on Tenant agents. |
| The effective configuration shows an empty JSON object | No saved configuration, or the run would be refused. | Save the configuration; run a dry run to see the reason. |
Related
Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation