Autonomous AI Agents (RAG)

Required Access Level

Admin, Modeler or Super Admin — agents live on the definition's AI Agents tab, under Process design.

How far an agent may call

An agent that uses the HTTP call tool should declare its allowed hosts in the agent form, one per line:

erp.customer.com
*.partner.com

*.partner.com reaches api.partner.com and does not reach partner.com. The port is ignored in the comparison.

Why this exists: the agent uses a credential without seeing it (see Tenant Variables), but with no list it could send that credential to any external address it composed. Agents read supplier documents, CMS records and knowledge bases — content from outside — and a model steered by that content can compose the wrong request. The list bounds the reach.

New installation: AI_HTTP_TOOL_DEFAULT_POLICY=deny

With allow (the default, for compatibility) an agent with no list calls any external address. With deny, an agent with no list makes no outbound call at all, and each agent that needs the network says where. Internal network addresses stay blocked either way.

The other half of the same control belongs to Webhooks: there the list is the tenant's and not the webhook's, because the webhook is the destination. Same host format, same wildcard, same refusal.

What are AI Agents?

An AI Agent is a record holding what the platform needs in order to call a language model inside a step: which model from the catalogue, at what temperature, under which system prompt, and with which tools by default. A classic Robot runs a JAR with programmed logic; the agent takes text in — the attached document, whatever earlier steps wrote, the passages retrieved from the knowledge bases — and gives text back, which the platform writes into the step's result variable.

Three limits worth knowing before you model anything:

• The diagram decides the path, not the agent. It writes the variable; the gateway (in a process) or the entry condition (in a case) is what reads that variable and picks the next step.
• When it fails, the step fails. An empty answer, a tool that could not run, or a blocking issue raised by the agent all stop the step with the cause written down — the platform does not leave the variable blank and carry on.
• Every call is billed, including the one that got you nothing. The provider charges for the prompt it processed. Empty answers, provider errors and blocking issues all land in the tenant's consumption in AI Governance like any successful call.

Typical uses: auditing an invoice, reviewing a legal filing, triaging a support ticket, classifying an attached document.

This list shows only this tenant's agents

A process that came from a Global Template may use platform agents. They run here normally but do not appear on this screen — the Super Admin registers and edits them, in the template's AI Agents tab. If a global process uses AI and this list is empty, that is why.

BYOK (Bring Your Own Key) Strategy

Flowi Agentic is self-hosted software: the platform charges no markup on token consumption. The model provider (OpenAI, Google, Anthropic) invoices whoever registered the credential, directly.

The key belongs to the installation, not to each tenant. The Super Admin registers it once, in the model catalogue — there is no screen where a tenant administrator supplies a key of their own. In practice the organisation running the installation receives the provider's invoice and uses AI Governance to see how much each tenant consumed and to charge it back.

Where the model and the key are registered

Provider and API key are not on the agent. They live in the model catalogue, under Platform → AI Settings, where each model is registered once with its provider, credential and base URL. The agent only picks a model from that catalogue.

The separation is deliberate: the credential belongs to the platform and to whoever answers for it, and creating an agent should not ask someone to paste an API key again — nor multiply the number of places where it exists.

Editing a model does not ask for the key again. On edit the API Key field comes back empty and whatever is stored is kept; fill it in only when the intention is to replace the credential.

A model in use is neither deleted nor deactivated

If any agent points at the model, if it holds a copilot role or if it is the replacement of a retired model, the platform refuses both the removal and the deactivation, saying what depends on it. It guards against silent damage: deleting the model unbinds it in the database, and every one of those agents starts failing on every call with nothing on the agent screen saying what changed. Point those agents at another model first.

Model price

The price is registered with the model, on the same screen, in the Price section: input, cached input (optional — empty bills it as input), output, currency (USD, BRL or EUR) and effective from (empty means now). Amounts are per one million tokens, as providers publish them. The catalogue list shows input / output for each model; a model with no price shows a No price chip.

A price is appended, never edited. Editing a priced model shows the price in force, a scheduled price when there is one, the history and a New price button. A new price must take effect after the latest one — a backdated price would rewrite the cost of calls already made, and the platform refuses it. A future date schedules the price: the previous one applies until then. Only a price that has not taken effect yet can be removed; to correct one already in force, register another from now on.

Each call stores its cost computed once, at the price in force when the call happened. Changing the price tomorrow does not change yesterday's cost. The cost is matched on the catalogue model that built the call, not on the name the provider echoes back: OpenAI answers gpt-4o-2024-08-06 for a model registered as gpt-4o, and those calls used to stay unpriced.

The first price fills in the past as an estimate

When a model gets its first price, its earlier calls that had no cost are priced at it and marked estimated in the reports. A call that already had a cost is never touched, and later prices fill nothing.

A model that has already billed calls cannot be deleted — the cost of those calls must stay explainable; deactivate it instead. A model registered by mistake, which never served a call, is removed together with its price history.

The embedding price (knowledge bases and RAG retrieval) lives in the Vector Database (RAG) tab: input and currency only, with the same history. Changing the embedding model creates a new configuration that starts unpriced — the previous model's price stays with the calls it served.

Copilot roles

At the top of Platform → AI Settings, the Copilot roles card says which model answers both copilots — the modeler's and the execution one (board and task). None of it is hard-coded: the Super Admin chooses.

• Copilot model — the default of both copilots. Without it, the model marked as default in the catalog answers and, without a default, the first active one.
• Fallback model — answers once per turn when the provider of the first one fails on a rate limit, a provider quota, an outage (5xx), a timeout or a retired model, before any text showed or any tool ran. It must be a different model from the copilot model; it may share the provider, and the screen warns that an outage of that provider takes both down.
• Selectable in the Copilot — a switch on the model form. The models marked appear, together with the copilot model, in the chats' selector. The person sees only the model name: no price, no provider.

The fallback never answers a refused request (400, 401, 403, 422), the tenant's own quota, or a failure after part of the answer showed or a tool already changed something — repeating there would duplicate the effect. Every attempt pays its own token: a turn with a switch writes two usage rows with the same correlation, the first with the model that failed and a zero count, the second with the fallback model. No turn writes more than two, and the provider client on the copilot path retries at most once underneath.

Model lifecycle

Every catalog model has a state, shown on the list next to its status:

State	Answers	New bindings	When
Current	yes	yes	normal
Deprecated	yes	yes, with a warning	the provider announced the end; the shutdown date is optional
Retired	not as itself	refused	calls go to the replacement or fail

Deprecated and the date are chosen on the model form. Retiring is an action of its own — Replace or Retire — because it shows who depends on the model first. A retired model can go back to Current, and the return is recorded.

The platform never retires a model by itself. It checks the provider's model list when a model is registered or edited, every day at 03:00 and when someone clicks Check now — spending no token, through the API's model listing. The Provider list column shows the result: Listed, Not listed (it may be an alias — check before retiring it), Cannot be checked (typical of a compatible base URL that does not publish the list) or Check failed. When the provider answers on a call that the model no longer exists, the model is marked Not found on a call, the failure says the provider no longer serves model X and to choose a replacement in Platform → AI Settings, and the step is not retried.

Replacing a model

On the model row, Where it is used lists, across every tenant, the agents that point at it (with tenant and process), the global template agents grouped by process, the copilot roles it holds, the model classes it is a member of and the models that have it as their replacement. Replace opens the choice of a replacement in a single action, recorded in the model's History:

• the platform suggests a replacement — same provider, current and listed — but applies nothing until you confirm. The suggestion is only pre-selected when it is in the list of choices (active and current); otherwise the field stays empty and you pick;
• Mark as retired retires the model in the same step;
• Move the agents to the replacement rewrites the model of every dependent agent, tenant and global, and records each agent moved. Unchecked, agents keep pointing at the old model and are redirected while the replacement is set — it can be undone.

Running instances pick up the replacement on their next call. Past usage is never rewritten; new calls keep the bound model and the called model, and the cost is the called model's.

Warnings and publishing

The Models that need attention card shows at the top of the screen when a deprecated model shuts down within 30 days and something depends on it, a retired model without replacement still has dependents, the provider no longer lists a model or did not find it on a call, or a copilot role points at a retired model. Publishing a version whose agent step points at a model retired without a replacement is refused, naming the step, the agent and the model; with a replacement, the publish goes through and the agent is answered by the replacement.

Model classes

A model class is a kind of work — Extract (read documents and return fields), Reason (analyse and decide with the process rules) and Write (write texts and summaries) come registered, empty. Each class is an ordered list of catalogue models, built by the Super Admin on the Model classes card of Platform → AI settings: add, remove, move members up and down and Save order. New classes can be created (the code is permanent) and existing ones renamed; every change is recorded.

An agent points either at a class or at a specific model, never both. An agent bound to a class is answered by the first model of the list that can be called (and by the next one when the first is at its limit — see the fallback order): a member switched off or retired without replacement is skipped, and a member retired with a replacement is answered by the replacement. Reordering a class changes the model of every agent of that kind at once, across every tenant and the global templates. Agents that already existed stay pinned to the model they had.

• Binding an agent to a class that has no model able to answer yet is refused.
• A class used by agents cannot be deleted, nor left without any model able to answer.
• A model that is a member of a class cannot be removed from the catalogue; Where it is used shows its classes. Switching it off is allowed: the class simply skips it.
• The Models that need attention card warns when a class used by agents has no model able to answer, when it has a single one (nowhere to go if it fails) and when a member was retired without a replacement.
• Publishing a version whose step uses a class-bound agent with no model able to answer is refused, naming the step, the agent and the class.

The fallback order: if the first one is at its limit, the step uses the next

The AI step of a class-bound agent starts each attempt on the first model of the list that is available now on this server, and switches to the next one between attempts — never in the middle of one (the tool rounds of an attempt all stay on the same model).

What happened to the model	What the step does
The provider quota ran out (daily, plan or billing quota)	moves to the next one at once; the model is marked as exhausted on this server for 60 minutes (or for the time the provider gives), and the next steps already start on the next one
Rate limit (429), provider down (5xx), timeout (408) or network	moves to the next one if it has a free slot now; otherwise waits and retries the same model, as before
The provider says the model no longer exists	moves to the next one if it has a free slot now
No free slot on this server before calling	moves to the next one at once, spending no attempt and costing nothing; if every model is full, it waits
Request refused (400, 401, 403, 422), blocking issue, empty response, security block	does not switch: the next one would fail the same way

• A switch spends an attempt of the step's ceiling. With the default ceiling of 2 attempts, the step switches model once.
• An agent with a specific model does not switch. It only follows the replacement of a retired model; an exhausted quota is still a final failure.
• External tools may run again. The variables the failed attempt was about to write are discarded, but an HTTP call, a started process or a card it created happen again on the next attempt, as on any retry.
• Where to see it. The step detail of the instance shows the Model used and, when it was the next one of the class, a notice naming the first model and why it was skipped (no price). The Failed row of an attempt that failed names the model that failed and the one that answers next.
• The exhausted-quota mark is per server: in an installation with several servers, each one finds out on its own first failing call.

Gemini reasoning models

Gemini models take a thinking budget of their own, set on the catalogue entry:

Value	What happens
empty	uses the platform default (AI_GOOGLE_THINKING_BUDGET, today 0)
-1	the field is not sent and the model decides — what the pro family requires
0	reasoning off, which is how the flash models already run
> 0	an explicit ceiling of reasoning tokens

The field exists because 0 is valid for flash and invalid for pro: registered with the platform default, a gemini-pro-latest answers 400 on every call. Leave -1 on those models and touch nothing else — the default stays exactly what the flash models were already getting.

That is why registration refuses a Gemini pro-family model (gemini-2.5-pro, gemini-pro-latest, gemini-3.1-pro-preview…) with an empty or 0 budget: the screen shows the message, which starts with thinkingBudget: and states the two accepted values — -1 or a positive budget such as 2048. "Empty" is read as the installation default: if that is not 0, empty is accepted. The refusal applies to creating and to editing; models already registered are not changed, and an old model in that state can still be edited (deactivated, renamed) as long as the provider, the model and the budget stay as they are.

Reasoning off on an agent that writes to the process

The agent form shows a warning when the chosen model has reasoning off (budget 0, explicit or inherited from the default) and the agent holds a tool that writes to the process — setProcessVariablesTool or routeProcessDecisionTool. Without reasoning, a multi-step calculation is done "in its head": in a test with gemini-2.5-flash, the written value was wrong in five runs out of five, with no sign of it. The warning changes nothing by itself — pick a model with -1 or a positive budget for this kind of agent. On an agent bound to a model class, the warning looks at the first model the class calls today.

Reasoning is billed tokens

Reasoning tokens count towards the tenant's consumption like any other, billed as output — Gemini included, whose thoughts the platform adds to the output in both the quota and the cost. A high budget shows up in AI Governance as a higher cost per call.

The agent editor warns about the lifecycle

When choosing the agent's model, a deprecated model shows the date the provider ends it, and a retired model leaves the list. An agent still pointing at a retired model shows who answers in its place — or, without a replacement, that the step fails and publishing is refused until another model is chosen.

Configuring the Agent

Agents belong to a process. There is no global agents screen: you register them inside the definition, under Process Catalog → the process → AI Agents tab. This is structural rather than menu organisation — every agent carries the key of the process it serves, which is what lets one process have several agents, each with its own system prompt, model and temperature.

In the form:

• Agent Name and Description — the description is optional and serves whoever maintains the process later.
• Model class or Specific model — the class follows the order built in Model classes, and the list shows its models in order; the specific model is chosen from the catalogue described above. Switching between the two options while editing does not lose the choice: going back to Specific model brings back the model that was selected. If the class saved on the agent has been deleted, the field shows empty and the form asks for a class or a model before saving.
• Temperature (0 to 2.0) — how much freedom the answers have. For a process, 0.0 or 0.1, because what you want is the same input producing the same output.
• AI Tools (System Tools) — read an attachment, search the knowledge base, query a CMS collection, and so on. This list is the default for steps that declare none of their own: every step of the process can pick its own tools, and that is where the decision usually belongs — see What belongs to the agent and what belongs to the step.
• System Prompt — who the agent is and the rules it applies. E.g., "You are a senior financial analyst, always reject proposals submitted on weekends."

A step points at its agent through the aiAgentId field on the Service Task, so different steps of the same process — or of the same case — can use different agents.

RAG Integration (Knowledge Bases)

Artificial Intelligence is much more powerful when paired with RAG (Retrieval-Augmented Generation). In Flowi Agentic, this is managed through the Knowledge Bases module:

1. Base Management: Go to Process design → Knowledge Bases in the sidebar. You can create global bases (available system-wide) or tenant-specific bases.
2. Workflow Linking: Knowledge base content (rules, policy manuals, guides) is not blindly injected. When designing a process (Workflow), go to the RAG tab and explicitly select which Knowledge Bases the process is permitted to access.
3. Rule Injection (System Prompt): The moment an AI step fires, in a process or in a case, the engine fetches the descriptions of the linked Knowledge Bases and automatically injects the rules into the System Prompt. The process link says which bases are within reach; each step can narrow that set — see Knowledge bases for this step.
4. Documents (Vector Search): Attached files (PDF manuals, text sheets) are chunked and converted into vector embeddings using pgvector. During execution, the semantic content most similar to the current task variables is passed as supplementary context. This data never trains the public LLM.

Knowledge base search: mode, chunks and floor

In the agent editor, the Knowledge base search section decides how retrieval runs — on the step's automatic search and on the search tool, which uses the same configuration and the same scope as the step (the model cannot widen retrieval):

Field	Values	Default
Search mode	Vector (similar meaning) or Hybrid (keyword + vector: also matches codes such as 8471.30.12 and art. 37-A literally)	Hybrid on a new agent; an agent that already existed keeps what it had
Chunks per search (topK)	1 to 20; the editor shows the approximate context (topK × 800 tokens per call)	3
Minimum similarity	empty (no floor) or 0 to 1; cuts the vector side only	empty

The number of chunks is the cost lever: every extra chunk enters the input tokens of every call of the step. Hybrid mode itself costs no token — keyword search calls no model.

To choose between vector and hybrid by number, write reference questions on the base and compare both modes — see Knowledge Bases → Measuring search.

Retrieval returns a few passages, not the whole base

Each query returns the configured number of passages (three by default), however many bases are within the step's reach and however many documents they hold. There is no per-base quota: the slots go to whichever passages are closest to the question, wherever they live.

That changes what to expect from loading more content. Loading more does not increase how much context reaches the model — it increases the chance the selected passages are the right ones. A question spanning three subjects will not get them in one search; the agent has to ask once per subject, and it only does that if the System Prompt says so.

Two instructions worth giving any agent that reads a large base: one question per subject, since three narrow queries return nine pertinent passages where one broad query returns three generic ones; and the distinguishing term inside the question, because retrieval is text similarity and does not filter on metadata.

Knowledge base access

In the agent modal, Knowledge base access sets up to which level of classified document (Public, Secret, Top secret) the agent reads from the base — both in the step's automatic context and through the search tool. The default is Public. It is a separate field from the CMS clearance: an agent configured to read secret collections does not start reading secret documents.

• You can only pick levels you reach yourself, and only change an agent whose access you reach (Modeler → Public, Manager → Secret, Admin → Top secret).
• When the search finds an excerpt above the agent's level, the tool answers that access was denied, with the count and the level, never the document name. The agent should report a missing permission instead of concluding the information does not exist.
• The level bounds what reaches the model, not what the agent writes into the case: what it summarises from a Secret document can be seen by whoever works the next task.
• A Modeler cannot create or edit a Secret agent, but can bind an existing Secret agent to a step of a process they design — the step then reads Secret material and may write it into variables the Modeler sees when testing. If that is not acceptable, keep Secret agents out of processes Modelers edit.

How to classify documents: Who may read each document.

Using AI Agents in Workflows

Once your Agent is configured (e.g., "Auditing Agent"), process architects (SUPER_ADMIN users) can use this agent by creating a Service Task and choosing ✨ AI agent as its implementation. This works on both engines: in a BPMN process and, now, inside a CMMN case as well.

The Delegate will automatically gather dynamic variables from previous user form steps, concatenate them with linked Knowledge Bases rules, and send the request to the cognitive agent in real time.

Inside a case the agent writes a variable — the model decides

A case has no arrows. An AI step inside a case does not open the next step: it writes the result variable, and what opens is decided by the entry condition (sentry) that reads it. That is what keeps the reason a task opened visible in the diagram, instead of buried in a call nobody reviews afterwards.

A condition that reads the AI's answer must tolerate its absence

The result variable does not exist until the agent finishes, and the engine evaluates the condition before that. Writing ${documentosConformes == 'false'} brings the case down with Unknown property used in expression. The form that works uses Flowable's variable function: ${var:equals(documentosConformes, 'false')}.

This holds for every AI-driven condition, without exception — it is not an optimisation, it is the only form that runs.

Before an AI step existed inside a case, the only way out was for the case to call a one-step BPMN sub-process (Process Task). That still works and was not deprecated: it is the right shape when the AI part is a whole flow rather than a single call.

The fields of the Service Task

The task carries eight fields, declared in the modeler — the same ones on both engines:

Field	What it is
aiAgentId	Which agent runs the task
aiInstruction	What it must do at this step
aiResultVariable	Which variable receives the answer (default: aiResponse)
aiTools	Which tools this step offers the agent
aiKnowledgeBases	Which knowledge bases this step leaves within reach
aiRagTopK	How many chunks this step's search retrieves (1 to 20; empty inherits from the agent)
aiRagSearchMode	VECTOR or HYBRID on this step (empty inherits from the agent)
aiWritableVariables	Which variables the step may write, with type and whether required
aiPatternTask	Which human task's learned patterns the step consults
aiPatternFields	Which fields of that task the step consults

These fields are read from the model only. A process variable with the same name — from a form, the API or written by another agent — does not change the step. And some variables no agent writes through the Set Variables tool (setProcessVariablesTool): aiDecision and aiDecisionJustification (only the decision tool), escalateToHuman, escalationReason and escalationUrgency (only the escalate-to-human tool), the step's configuration fields, the step's own result variable, tenantId and anything starting with _ or ai_ (such as the ai_audit_trail audit record). If the agent tries to write one of them, nothing from that call is written and it gets back the list of what was refused and why. The same tool also refuses a value that is an internal identifier (UUID), such as an attachment id, and the agent only sees the attachments of its own instance — an id cited in a document does not open another process's file.

On top of those refusals, which hold for every process, the step declares what it may write in aiWritableVariables: the tool then writes only the declared variables, in the declared type, and each write is recorded with the step, the agent and the passage of the document the value came from. See What the step writes.

The agent can ask what the process already decided

Among the available tools there is Learned Pattern Lookup (consultarPadroesTool). Enabled on a step, it lets the agent ask what this process historically decided at the human task the step prepares — and the answer carries the exact frequency, already for the conditions of this case: "Document type: NFS-e in 692 of 692 comparable cases, when Type = NFSE". Which task and which fields it consults is declared by the step, not chosen by the agent — see Patterns the step consults.

The platform tells the agent the step has patterns, but does not inject them: whether it is worth asking is the agent's call. That is deliberate — pushing the majority value into the prompt would bias the agent precisely on the cases where the document is the exception, which in an audit are the ones that matter.

Where there has been enough exposure, the answer also carries how often people accepted that suggestion — the same figure as the Learning health table, on the same threshold. It is what lets the agent discount a frequent pattern users have been refusing.

The tool is read-only and honours the same exclusions as learning: a personal field, or one on the process's exclusion list, never appears — even if the agent asks for it by name. It is capped too: five queries per run of the step, and at most ten patterns per answer — past the cap the tool refuses instead of answering on, so that an agent in a loop does not turn into cost.

The first three are enough for a task to run. The others are the step's scope, covered in What belongs to the agent and what belongs to the step — tools and bases left blank inherit the default; a step that writes variables has to declare which.

Each field can be written in two ways, and the choice changes the outcome:

• Text (string) — the value reaches the agent exactly as written. Use it when the instruction does not depend on anything that happened earlier in the process.
• Expression (expression) — the value is computed at execution time. This is how an instruction receives data that only exists during the instance: Analyse invoice ${execution.getVariable('arquivoNota')}.

If the instruction has to quote something filled in at an earlier step, it must be an expression. Written as text, the agent would receive the literal ${...} and answer about a placeholder — the call is billed, an answer comes back, and it is not about your document.

The five fields can also come from process variables of the same name. A variable takes precedence over what the diagram declares, and it applies to the whole instance — if the process has two AI tasks, both start using the same instruction, and the same goes for the tool and knowledge scope. It works for a one-off; it does not work as a design. The rule is the same inside a case: what differs between the two engines is where the field is written, never how it is read.

Do not mark the agent's step as asynchronous

Leave Run in the background unchecked, on both engines.

The box buys nothing: since 2026-09-09 (processes) and 2026-09-10 (cases), the AI step already steps out of the execution queue on its own as soon as it starts. It reserves the work, gives the turn back, and the platform resumes it when the model answers — whoever started the process is not left waiting on the provider, and no database connection is held during that gap.

Checking the box only adds one more queued item per step, to move a wait that is no longer there. In a process it also pushes the step into the same short queue that serves timers and resumptions — which is precisely what this change exists to free up.

A process published before this version keeps the old behaviour, calling the provider on the spot and making whoever started it wait. To move it: open the task in the modeller, pick ✨ AI Agent again in the implementation field, and republish. In a case there is nothing to do — the change applies to everyone as soon as the version is up.

When the agent does not answer

If the model returns an empty response, the task fails and the instance moves to the With error status. It does not carry on with a blank result variable.

This is deliberate. Were the empty value written and the process allowed to carry on, the next human task would open with a blank field, and there would be no way to tell "the agent analysed it and found nothing to report" from "the agent never answered". In a process that audits fiscal documents, the defect would reach the reviewer looking like a result.

By failing, the instance shows up in the failed-instance list with a message naming the variable that was left unanswered and the finish reason reported by the AI provider — which is what separates a content block, a quota overrun and a genuinely empty answer.

There is one case where the empty answer never becomes an answer at all: the provider returns the call with no candidate, and the conversion fails first. The message now says exactly that, naming provider and model. It is the same empty-response defect seen from the other side — it does not mean a stale catalogue, and it does not call for restarting the application.

An infrastructure administrator can invert this behaviour with the AI_FAIL_ON_EMPTY_RESPONSE=false environment variable, leaving the result variable blank instead of failing the task. The default is to fail.

How many times the step insists with the provider

Not every failure deserves a second call, because the second call is billed just like the first. The platform separates the two halves of the step:

• Before the answer — the provider returned nothing. Repeating means calling the model again and paying again. This is where the step's attempt limit applies, and it is 2 unless the step says otherwise.
• After the answer — the model answered and the failure happened while writing the result. The answer is already stored as a process variable, so finishing the step costs nothing and has no limit: the platform repeats only the completion, never touching the provider.

Within the paid half, the limit is spent only on failures that could plausibly succeed next time:

Provider failure	Retried
Timeout	yes
Provider error (5xx)	yes
Connection lost / network	yes
401 / 403 — rejected credentials	no
Quota exhausted at the provider	no
Refused content	no
Malformed request	no

A failure from the no column ends the step on the first attempt even with the limit untouched, and the reason — with the code the provider returned — reaches the Failed instance list. Insisting there would mean paying again to fail identically.

The limit belongs to the step, not to the process. Two AI steps in the same process do not deserve the same number: a short classification against a cheap model can afford to insist, a long generation against an expensive model may deserve no retry at all. Because the value lives in the process design, changing it means republishing — it is a design decision, not an on-call switch.

Where it is configured. In the modeler, select the Service Task that uses ✨ AI agent and look for the Attempts with the provider field, right below the Return Variable, in the same block where you pick the agent and write the instruction. Leaving it blank is the normal case: the step uses the default of 2. Type a number only when this particular step deserves different treatment, and republish the process for the new value to take effect — an instance already running keeps the limit it was born with.

In a case the field is the same. In the CMMN modeler, select the task that uses ✨ AI agent and the Attempts with the provider field sits in the same place, right below the Return variable, with the same range and the same default. What differs is what happens once the limit runs out: in a process the step becomes a dead-letter item with a retry button; in a case the plan item stays active and the failure shows up on the case detail and in the With errors list — the case stays open and nobody has to reopen it. There, Try again runs the step once more (a new call, counted in usage) and Dismiss takes the failure off the list.

The field accepts 1 to 10. 1 means one call and no insisting — that is what you write for a long generation against an expensive model. Type a number outside that range and the screen brings it back to the nearest allowed one as soon as you leave the field; text that is not a number simply disappears, leaving the step on the default. Whatever stays written there is what will run.

The ceiling of 10 belongs to the installation and applies to every step: even if a hand-published XML asks for more, the platform never calls the provider more than ten times in one step.

Reading process attachments

When the agent has the attachment-reading tool enabled, it can read the instance's file without knowing its identifier. If the process has a single attachment, the tool reads it and tells the agent which file it read. If there are several, it returns the list of names for the agent to choose from — it never guesses on the agent's behalf.

Images and PDFs are attached to the message; everything else the agent reads through the tool. Models accept images and PDFs directly, so those two travel as files. Any other format — XML, JSON, CSV, text — is not sent as a file: the message carries its name and identifier, and the agent uses the tool to read the content. Write the System Prompt accordingly, because an agent told not to call the tool simply never sees the document.

Text formats arrive as they are, with their structure intact. XML and JSON do not go through text extraction — if they did, field names and attributes would disappear and the agent would receive a column of values with nothing saying what each one is. PDF, DOCX and images still go through the extractor, which is what it is for.

A document is capped at 100,000 characters, configurable through AI_ATTACHMENT_MAX_CHARS. Beyond that the tool truncates and says so in the text it returns, giving the document's length and how much arrived. Instruct the agent to repeat that notice in its answer: analysis of a partial document is partial analysis, and whoever reads the result needs to know the difference.

When a tool fails, the task fails

A tool can return two very different things, and the platform treats each one differently.

Answers go to the agent as text, because it can act on them: the collection does not exist, no record matched the filter, the process has no attachment, the process has several attachments and here is the list, the filter you sent is malformed.

Failures do not. If the tool could not run — database down, storage unavailable, extraction broken — the AI task fails, no result is written to any variable, and the instance appears in the With error list of instances, with its cause. The call already sent to the provider lands in the consumption report as a zero-token call: the spend happened and could not be measured, which is how AI Governance records it.

The difference matters because the agent cannot tell a broken tool from an empty result. Hand it the failure as text and it writes something plausible — "the document did not arrive" — and that text becomes the step's result, is read by the next step, and reaches a human looking exactly like any successful task. A fluent audit about nothing is worse than a failed task, because a failed task is something someone fixes.

The rule is about whose problem it is, not how severe it is: a badly written filter is the agent's mistake and goes back for it to correct; a database outage is the platform's and stops the process.

When the input never arrived: three options, and how to choose

A broken tool is one case. The other, far more common, is the input never arriving: the invoice nobody attached, the period the previous step failed to fill in. With nothing checking, the agent honestly answers "the file was not received", that sentence is stored as if it were the transcription, and the next step audits the sentence. The reviewer opens a task identical to every successful one.

There are three ways to prevent this, and they do not compete — they cover different things.

Option	What it catches	What it costs
Gateway before the step	the variable is empty, and there is a business path for that	edit the diagram; nothing else
Required-variables listener	the variable is empty or points at a missing attachment, and that is a modelling error	one line in the step's listener panel
Blocking-issue tool	the file arrived and is unusable — unreadable, wrong type, contradictory	grant the tool to the agent; optionally an error boundary event

Use the gateway when a missing document is normal and someone can fix it. An exclusive gateway before the AI step, testing ${empty arquivoNota}, routes to a human task that asks for the file. The check lives in the drawing — anyone who opens the process sees that the case was considered.

Use the listener when the variable should always be there. In the step's listener panel, add an execution listener on the start event, of type Expression, with:

${requiredVariables.check(execution, 'arquivoNota,competencia')}

It stops the activity before any call to the model — so it spends no tokens at all — when any of the variables is absent, blank, or an attachment id that no longer resolves. That last case is the deceptive one: the variable is populated, with a perfectly shaped UUID, and it is the file behind it that is gone.

The listener is not an AI capability. It works the same on a robot task, an HTTP call or a DMN decision — it is an ordinary BPMN extension point, which is why it exists instead of a field of its own on the AI step.

It stops the instance rather than routing it: absence here means the process was modelled or integrated wrongly, and there is no sensible path for "the previous step did not produce what it promised". If there is a path, the gateway is the right instrument.

Use the blocking-issue tool for what only the model can judge. The file is there and it is unreadable; it is a service invoice where a goods invoice was expected; two attachments contradict each other. No gateway and no listener see any of that, because both only know whether the variable exists.

Turn on Let this agent stop the process with a blocking issue on the agent form. It is off by default: an agent that must never abort a process simply does not receive the tool, like every other capability.

The agent's switch is the default, not a ceiling. Like any tool, a step that declares its own list under Tools for this step may include the blocking issue even with the switch off — and a step that declares its own list without it takes the blocking issue away from an agent that has it. Whoever edits the diagram owns that decision.

Once granted, the agent ends the step reporting a short, stable code (DOCUMENTO_AUSENTE, DOCUMENTO_ILEGIVEL, TIPO_NAO_SUPORTADO) and a one-sentence reason. Then:

• the result variable is not written — no prose takes the place of the data;
• the process receives a business error carrying that code. Attach an error boundary event with the same code to the Service Task and route to a human task, a compensation or a notification;
• the failure record keeps the code where an exception name would be. It does not show on the AI Governance screen, which only reports quota and consumption: today the rate of each code is read from the AI failure list through the API (GET /a/ai-task-failures, with ?open=true for the open ones only), or asked of the execution copilot;
• with no boundary event, the instance stops with a named cause. Handling every code is not required.

Three consequences are worth saying out loud.

With a boundary event, the engine does not retry the blocking issue. A business error is a control-flow signal, not a fault: re-analysing an absent document three times changes nothing and bills three times. A transient failure — provider outage, broken tool — stays an ordinary failure, which the engine does retry.

With no boundary event and the step made asynchronous, the engine retries — and bills again

This is the combination to avoid. With nobody catching the code, the engine treats the blocking issue as any other fault; if the step is ticked Run in the background, it retries until the dead letter queue, and every attempt is a fresh call to the provider. The shortcut that keeps a step from being paid for twice relies on the result variable being filled in — and a blocking issue is precisely the case where it is not.

Two defences, and the first is already this page's general advice: leave Run in the background unticked; and, for every code the agent can raise, either have a boundary event or accept that the instance stops there.

A blocking issue consumes quota. The model was called, read the document and concluded it cannot be done: the token was burned at the provider and appears in the tenant's usage report, even though the step ended in error. Quota measures spend at the provider, not results you got to keep.

In a case (CMMN) a blocking issue does not route. The AI step of a case records the same code and likewise does not write the result variable — the entry condition that depended on it never opens — but CMMN has no error boundary event: to the engine that is an ordinary fault, with the retry and the re-billing described above. Until that changes, a blocking issue with a designed detour is a BPMN-process feature.

One agent per domain

Nothing forces a process to use a single agent. The agent is a field of the Service Task (aiAgentId), read on every execution — each step of the flow can point to a different agent, with its own system prompt, model and temperature. A process that uses the same agent from start to finish does so because it was designed that way, not because the platform requires it.

The difference shows when you measure the prompt. An agent that serves every step has to cover every step, and its prompt grows by addition: the shared discipline, plus each domain's vocabulary, plus the catalogue of what is available to consult.

Split that text by subject and the pattern appears. The part that serves any step — who the agent is, how it reasons, what counts as a result — is usually the smallest. The rest is tied to one domain or one corpus, and in a flow with separate tracks an instance walks only one of them: the other domain's vocabulary crosses every call without ever being used.

And that text is not sent once. It travels with every call the process makes — four calls, four copies, byte for byte identical.

The grouping is by domain, not by step

The immediate reaction to that number is usually to push the specific text down into each step's instruction (aiInstruction) and keep the agent lean. It does not hold: the NF-e block serves three NF-e steps, and pushing it down means writing the same text in three places. On the first rate change someone updates two and forgets the third — and the three steps start auditing under different rules, with nothing in the platform flagging the divergence, because to it they are three unrelated free-text fields.

The cut that holds is by domain: an "NF-e Auditor" agent and an "NFS-e Auditor" agent, each carrying the common discipline plus its own tax block, and each Service Task pointing at the agent of its track. The ICMS text keeps existing in exactly one place, and the NFS-e step stops receiving it. Agents are registered per process and coexist inside the same process: creating the second one is the same work as creating the first, and which one runs is decided step by step.

What belongs in the agent prompt and what belongs in the step instruction

The split is this: the agent prompt holds what is common to the domain — vocabulary, hierarchy of norms, how to query the base, what the base does not cover, how firmly to assert something. The step instruction holds what is specific to that activity — what to analyse now, in what format to answer, what the next step expects to receive.

A step instruction that repeats a domain rule is duplication waiting to diverge. An agent prompt that describes one specific activity travels along to every other step of the domain, taking up room and competing with the instruction that actually applies to that call.

Tools and knowledge bases follow the same split, by field rather than by text: both are declared on the step, and they are what the rest of this section is about.

An available tool is a used tool

The model decides whether to call a tool, call by call. The design does not control whether it gets used; it controls only whether it exists on that call — and that is what turns the tool list into a cost decision, not only a quality one.

The typical case is a consolidation step: everything the earlier steps produced already reaches it as process variables, and all it has to do is put them together. Leave attachment reading available and some fraction of runs will re-read the whole document — the model has two sources for the same value and no reason to prefer one. A call that re-reads costs several times one that does not, and nobody decided the difference.

Asking in the instruction not to re-read helps, but it remains a request. Leaving the tool out of the step is what makes re-reading impossible.

An available base is a used base

The same holds for the corpus, and there the price is not tokens.

A step that consolidates opinions with the legislation within reach can raise a finding no earlier step raised — and support it, because the norm is at hand. The result looks rigorous: it cites an article, concludes, closes. Except the step was not designed to audit; it was designed to assemble what had already been audited.

Both are the same mechanic: the model helps itself to whatever is within reach, and reach is decided before the call goes out. That is why a step's scope is enforced rather than requested — the platform assembles the call with the tools and bases the step declared, and what was left out is not there to be used.

What belongs to the agent and what belongs to the step

The agent is who it is: the role it plays, the discipline it reasons with, the model it runs and the temperature. The step is what it does: the action of that activity, the tools it needs and the bases it consults.

The distinction is practical. While tools and bases lived on the agent, the agent's prompt had to anticipate every possible action of every step that might use it, and the only way to take a tool away from one step was to create a whole agent for that — an agent existing for a reason that has nothing to do with the role it plays.

Tools for this step (aiTools)

In the modeller, select the Service Task (or the listener), pick the agent, and use Tools for this step.

The agent's list is the default, not a ceiling: a step that declares nothing runs with the agent's tools, and a step that declares goes by its own list instead. The selector shows the agent's tools as the ready choices, but the step is not limited to them: any valid platform tool can be declared. Whoever designs the process knows what the step needs in order to work, and whoever edits a diagram is already a tenant administrator — separating those two decisions would separate what belongs to the same person.

For the final opinion, simply leave attachment reading out of that step. Re-reading becomes impossible rather than merely discouraged.

What the step does not decide is reach into confidential data. The CMS confidentiality level stays with the agent (see Large tables and AI agent lookups), and that is deliberate: a tool is an action, confidentiality is reach. Should a modeller role that is not an administrator ever exist, whoever draws the diagram still will not be able to grant the agent access to content they cannot read themselves.

A tool name that does not exist on the platform is refused before the call goes out, with a message naming what failed to resolve. A broken tool sitting in the agent's default but not used by the step does not bring the step down — only the step that asks for it is refused.

While the step runs, the model can call only the tools this step offers. If it asks for another one, the call does not run, even when the tool exists on the platform. That covers a request planted in the text of a document or a form field. The model is told that the tool does not exist, together with the names it may use.

When the step offers the variable read (getProcessVariablesTool), what goes back to the model is the same protected view the screen shows, whether it asks for a list of names or for everything: a configured secret and a form password field arrive as ********, and the platform variables — aiDecision, escalateToHuman, the step configuration (aiInstruction, aiTools…), tenantId and any name starting with _ or ai_, such as the ai_audit_trail trail — are simply absent. A request planted in a document to "read the password" gets the mask, not the value.

Knowledge bases for this step (aiKnowledgeBases)

Same syntax, different reach: the step chooses among the bases the process links. Declaring nothing inherits every base of the process; a list leaves exactly the ones listed; none leaves the step with no base at all — neither the descriptions injected into the System Prompt nor the passages those bases would contribute to vector search.

A base declared that the process does not link is refused, not ignored, and the error message lists the bases the process reaches. Silently dropping it would run the step with less context than its designer asked for, and the output would come out looking like a normal result.

Knowledge search of this step (aiRagTopK, aiRagSearchMode)

The step can change the agent's number of chunks and search mode — for instance, keep the agent on Vector, 3 and turn on Hybrid, 8 only on the step that checks NCM codes. Empty inherits from the agent. A value out of range (aiRagTopK outside 1 to 20, a mode other than VECTOR/HYBRID) is refused at publish, not clamped: clamping silently would run the step with different context from what its designer asked for. The Escopo da etapa log line records what retrieval used (busca=HYBRID topK=8 piso=nenhum).

What the step writes (aiWritableVariables)

A step whose agent uses Set Variables (setProcessVariablesTool) declares, under Variables the step writes, each variable it may write: the name, the type and whether it is required. Use the same name and type as the form field that will read it — Add a form field fills both in.

What the declaration changes:

• Only what is declared is written. A key outside the list is refused, and the refusal tells the agent which ones it may write. As before, one refusal stops the whole call.
• The type is checked. Currency and number arrive as numbers (1074.00, not R$ 1.074,00), a date as 2026-10-18, yes/no as true/false, and a choice accepts only an option of the process's forms. The stored value has the same type the form would store.
• Required means required. If the step ends without writing a required variable it fails with the cause named ("a etapa terminou sem gravar valorReembolsavel") and shows up under With errors. It is not sent back to the provider on its own: calling again would pay again to fail the same way. The agent is told that, without the value, it should report the blocking issue.
• Every write leaves a trace. The step, the agent, the time and the passage the agent cited are recorded; the next task shows the field as Filled by AI (see Tasks). A refusal goes into the instance's audit trail with the key and the reason, never the value.

Four refusals in the same run and the tool tells the agent to stop trying. This step writes no variable (none) refuses every write. aiDecision, escalateToHuman, the step's configuration fields and ai_* variables cannot be declared — publishing refuses them.

A version published before this rule keeps running as it was, writing what the agent sends (except the reserved keys), with the write recorded and a warning in the log. Republishing makes the declaration required — see Publishing.

All of this applies equally to the agent on an execution listener: its tools, the variables it writes and the patterns it consults are the ones declared on the listener itself, never those of the task it hangs on. Until 2026-10-19 the listener ran ignoring those declarations — it wrote any non-reserved variable and offered every tool of the agent; the fix applies without republishing.

Patterns the step consults (aiPatternTask and aiPatternFields)

When the step offers Learned Pattern Lookup, it declares under Patterns the step consults the human task whose patterns the agent reads — usually the next human task in the flow, which the panel offers as Use the next human task — and the fields of that task the agent decides. The picker only lists fields learning mines. Changing the task, or going back to — none —, clears the chosen fields: they belonged to the previous task's form, and would stay hidden while blocking publication.

With that, the tool stops accepting whatever step and field the agent chooses: it answers for the declared task, only for the declared fields, with the pattern that holds for the conditions of this case, and says when the value the case already has differs from the pattern. A case that fell into learning's control group gets no pattern — the answer asks to decide on the content of the case. And what the tool showed counts as a suggestion seen on the task created later, so learning does not count its own echo as a human decision.

A step that enables the tool without declaring the fields still works, for one release, in the old form — and publishing warns.

The none marker

It works on the scope fields and means the same thing on all of them: none at this step. It exists because an empty field and an absent field reach the engine identically, and not configured has to be distinguishable from configured to nothing.

The marker tolerates case and surrounding spaces (NONE, none), and is refused when it comes alongside a real item — none, searchKnowledgeBaseTool does not say whether the step wanted everything or nothing, and guessing would be choosing on the designer's behalf.

In the properties panel both fields appear as soon as an agent is selected: a multiple selector and, below it, a No tools in this step / No knowledge base in this step checkbox, kept separate from an empty selection precisely so the difference shows on screen.

Injected context and tools are not the same thing

They are two ways for the agent to reach information, and they fail differently.

Injected context is material that enters the prompt before the model thinks: the descriptions of the linked bases, the passages retrieved by vector search, the attached document. The model helps itself to all of it, and nothing in the text separates "this is reference" from "this is the case under analysis". In one measured batch, an opinion quoted the municipality from a reference table as if it were the invoice's municipality: the value was in the prompt, it was plausible, and the model used it.

A tool is a question and an answer. The model asks, receives what it asked for, and what comes back arrives identified as the result of a query. It costs one extra round trip and brings less text back.

For design the consequence is practical: large reference material — code tables, registries, rate lists — is safer behind a tool than injected next to the document. And the more the injected material resembles the document under analysis (same fields, same formats, same numbers), the higher the chance one becomes the other in the answer.

Reference cases

A reference case is a known input with the right answer: the step's instruction, the variables it saw, the attachments it read and the checks that decide whether an answer is right. They exist so that changing an agent's model, class or prompt stops being a guess: storing and scoring a case calls no model and spends no quota, and the model comparison runs those cases on the models you pick.

Where they live. When you edit an existing agent (in Definitions → process → AI Agents, or in the global template for the Super Admin), the dialog gains the Reference cases tab: the list, with each case's origin (step or manual), and the editor. Each agent keeps up to 50 cases. Cases are maintained by whoever designs the process — the tenant's ADMIN and MODELER; a global agent's cases belong to the Super Admin only. Deleting the agent deletes its cases.

Saving from a step. On the instance screen, select a completed AI step and click Save as reference case. The case goes to that step's agent with:

• the step's instruction, with its variable placeholders kept;
• the process variables as they were when the step started — secrets and password fields are never copied, not even masked: they are simply left out, like the AI audit trail;
• the ids of the attachments the instance already had when the step started — never their content; a file uploaded later is left out, because the model never read it;
• the answer that step left as the expected result: one check per field when it is JSON, an equality check when it is text. Review the checks afterwards on the agent's tab.

If the result variable changed after the step — another AI step wrote to the same variable (such as aiResponse) or someone edited it — and the history does not keep the value the step left, the button refuses with that explanation instead of saving the wrong answer. In that case, create the case by hand on the agent's tab.

A step that picks its agent by expression (${...}) cannot be saved, because the agent is only known at run time. Case (CMMN) steps do not offer the button yet.

Which attachments a case accepts. Only a process-instance attachment of an instance you can see — ADMIN and MANAGER see every instance; a MODELER only those they started or had a task in. A knowledge-base document, a deleted attachment or a file of somebody else's instance is refused on save, because the model would read the file during the comparison and the answer would be visible to whoever opens the result. The check runs again when the comparison runs, for the person who asked for it: an attachment deleted since, or of an instance that person can no longer see, is left out of that case without bringing the run down. A global agent's case carries no attachment — an instance always belongs to one company, and one company's file does not go into the layer every company uses.

The checks. The case passes when all of them pass.

Check	Passes when
Equal (exact)	the answer, trimmed, equals the expected value — case matters
Contains	the answer contains the text, ignoring accents, case and repeated spaces
Number	the first number in the answer is within the tolerance of the expected one (default 0). Reads 1.074,00 and 1,074.00
JSON field	the answer is JSON, the pointer (e.g. /items/0/value) reaches the field, and it matches as equal or as a number. If the field is a JSON number, the expected value is read as a JSON number: 1.234 against {"rate": 1.234} passes — the pt-BR thousands reading (1.234 → 1234) only applies to text

Evaluating models with reference cases

On the Reference cases tab, Compare models runs the agent's cases on up to five catalog models and shows, side by side, how many each got right. Use it before changing an agent's model: the answer stops being "it looks better" and becomes "it got 18 of 20 cases right, with half the tokens".

How to run it.

1. Click Compare models, tick the models (the tenant sees names only, never a price) and the cases — all are ticked. Each case × model pair is one call; the limit is 100 pairs.

2. Click Estimate. The screen shows how many provider calls to expect, how many tokens — from the average of the agent's own recent runs — and how much of the tenant's AI quota is left. If the agent has not run yet, the token estimate says it does not know instead of guessing. While the estimate is being calculated, the choice of models and cases is locked: what you confirm is exactly what was estimated. Changed the choice afterwards? The estimate disappears and you have to estimate again.

3. Check it and click Confirm and run. The evaluation goes to its own queue, two at a time across the whole installation, and the Model evaluations list follows its progress.

   If the server restarts midway, an evaluation that was queued or running does not stay "running" forever: on the next start-up, one that has been stuck for more than an hour without recording a result shows as Failed, with a reason saying it was interrupted by a server restart. The pairs that had already run stay visible; run the evaluation again to get the full result.

What an evaluation does not do. It opens no instance, fires no webhook or e-mail and writes no process variable: each case runs in an in-memory step, with the same prompt, the same knowledge bases, the same RAG search and the same tool check as the real step, and the instruction filled with the case's variables. The model reads only the attachments saved in the case. Each pair runs once, with no retry — a provider error becomes an Error result and the evaluation carries on. An agent with a tool that acts outside the step — HTTP call, webhook, notification, sub-process, task assignment — is refused, and the message names the tools: evaluating it would call those tools for real. To compare models for it, evaluate a copy of the agent without them.

Quota. An evaluation is optional spend, so it honours the quota: the tenant's quota (and the requester's personal one) is checked on every call. If the quota runs out midway, the remaining pairs show as Not run, the evaluation ends Partial, and what was already spent stays counted. With no quota configured, or with the quota already exhausted, the evaluation is refused on confirmation, with the explanation, instead of running with no pair happening. For the agents of a global template, the quota checked is the global layer's (__global__), which is not created on its own: the Super Admin has to configure it before the first evaluation. In the model's queue, an evaluation waits like a process step — it never jumps ahead of production — and it uses the same model call limit as production, because the limit is the provider's. Since each server runs at most two evaluations at a time, they take at most two places in each model's queue per server. The usage shows in AI Governance as MODEL_EVALUATION, with the case name in place of the step.

The result. In View results, each model is a column with: accuracy (cases that passed every check), average input and output tokens, provider calls per case, median (p50) and maximum latency, failures and pairs not run. Below it, a case × model grid with Passed, Failed, Error or Not run; click a cell to see, check by check, the expected and the actual value, and the model's full answer. The Super Admin also sees a Cost row per model. Each agent keeps its 20 most recent evaluations.

If a chosen model was retired after you asked for the evaluation, its replacement answers, and the column shows both names (Old → New). If the replacement was also among the chosen models, it does not run twice: the retired model's column repeats the replacement's result, without spending tokens again.

Whoever keeps the cases runs them: tenant ADMIN and MODELER; for the agents of a global template, the Super Admin, who spends the platform quota.

Self-learning

Self-learning is configured per process, not per agent: a process running several agents has one configuration shared by all of them, and the agent form carries no learning field at all. The tab lives under Process design → Process Catalog, and is documented in Process Catalog → Self-learning.

The patterns that counting produces feed two places, with the same number in both: the form's autofill and the execution copilot, which answers what is usually filled in on a step by quoting "in 641 of 645 comparable cases". Switching self-learning off for a process removes both: the copilot keeps answering about the process and the instance, but starts saying it has no history for that field — never estimating one. What the copilot receives is described in Tasks → What the copilot knows about the open task.