AI features

Botream can use a large language model to write tasks for you, explore a web application and capture its elements, clean up recordings, read documents inside a running task and explain why a run failed. All of these use one model that an administrator sets up once for the whole platform.

#Setting up a model

AI features stay off until an administrator enters a model under Administration → Settings, in the AI card. See AI settings for the full reference.

Botream talks to any service that offers an OpenAI-compatible chat completions API: a cloud provider such as OpenAI or NVIDIA build, or a model server on your own network. The Botream Server makes every call itself; agents and browsers never contact the model and never see the key.

All three of API base URL, API key and Model must be filled in. Until they are, every AI feature answers with a message like "The AI Task Generator is not set up: an administrator enters the API key under Administration → Settings → AI".

#On-premise models

To keep all data inside your network, run a model server that exposes an OpenAI-compatible API on a machine the Botream Server can reach, and enter its address as API base URL. Botream sends requests to <API base URL>/chat/completions with the key as a bearer token.

Note: The API key field is required even when your own model server does not check keys. Enter any placeholder value in that case.

#Choosing timeout and answer length

• Free or busy endpoints can queue a request for minutes before they start answering. If you see timeouts, choose a faster model or raise Timeout.
• "Thinking" models spend part of Maximum answer length on reasoning before they write the answer. Keep the value generous; if answers come back cut off, raise it.
• Pictures (in the ai command, in failure screenshots and while exploring) need a model that reads images.

#Privacy: what is sent where

Only the Botream Server talks to the model, and only for the features below. Every call is written to the audit log (Administration → Audit log) with the model and the sizes involved, never with the content.

Warning: Screen pictures and task data can contain personal data. Leave Send failure screenshots to the model off, and consider turning Allow the ai command in tasks off, unless the model runs on your own servers or your provider agreement allows it.

#AI Task Generator

Open a task you can edit (pulled into your local workspace, see Versions) and click AI Task Generator in the editor toolbar. Users with the Edit tasks permission (Developer by default) can use it. The dialog has two modes.

#Write the task

The model writes the commands from your description.

1. Select Write the task.
2. Describe what the task should do, for example: "Open https://shop.example.com, search for the customer given as input, read the first 5 order numbers into a list and write them to C:\Reports\orders.txt".
3. Choose Append to the task (the new commands are added and can use the variables the task already has) or Replace the task.
4. Click Generate (or press Ctrl+Enter).

Botream checks the generated code. If the model's first answer has errors, Botream asks it once to fix them. Valid code is inserted right away as one undo step (Ctrl+Z restores the previous state). If problems remain, the dialog lists them and you can click Insert into code anyway; the code goes into the code tab with the faulty lines marked.

In this mode the model has never seen your application, so elements it cannot know get placeholder selectors. Replace them with the Capture button, or use Explore in a browser instead.

Tip: While the model works, the dialog shows the elapsed time. After 30 seconds it notes that the AI service may be busy; Cancel stops waiting.

#Explore in a browser

In this mode the model works in a real browser on an agent the way a person would. Every click and entry is captured with its real element, exactly as the recorder captures it, and the steps are then turned into a structured task.

Requirements

• The Botream Agent tray app must be running and connected on the machine. The Windows service alone cannot explore, because it has no desktop.
• If several agents are online, choose the one whose browser the model should use (normally your own computer). With exactly one online agent, it is used automatically.
• Only one exploration runs per agent at a time.

Starting

1. Select Explore in a browser (captures the elements).
2. Describe the task and enter the address in Start at (an http or https address).
3. Click Start exploring.

A visible browser opens on the agent with its own profile. The dialog shows the page title, a log of what the model thinks and does, and a counter of the steps taken. An exploration takes at most 40 steps.

What the model sees

At every step the agent reads the page the way a person sees it, and the model gets:

• The elements a person can use now, numbered, each with the name a person reads for it: its label, or the text written next to it (also in table layouts), its placeholder, and the section, form or dialog it is in. Fields also show their state: value, required, read-only, the date format of date fields, and whether a menu or list is expanded or collapsed.
• Frames and components: elements inside iframes (back-office applications often show their forms in one) and inside web components (open shadow roots) are listed like the others. Recorded steps keep the frame (--frame), so the finished task finds them again.
• Only what can be used: links in a closed drawer menu, elements behind an open dialog and hidden elements are left out. Elements outside the visible area are listed after the visible ones, marked to scroll to.
• Lists that open by script: dropdowns built by web frameworks, which are not real select lists, are recognised too. The model clicks them, then picks the option from the list that appears.
• What each action changed: a new page, a dialog that opened, options that appeared, a field's new value, or nothing visible changed, so the model tries another way instead of repeating a click. The agent waits until the page stops changing (animations included) before it reads it.
• Today's date and time as the browser has them, with its time zone and date format.
• A picture of the browser with the element numbers drawn on it, when Show the page to the model while exploring is on under Administration → Settings → AI (on by default). Models that read images recognise pages far better. A model that only reads text refuses the picture; the exploration then goes on without pictures and says so in the log.

Values computed when the task runs

When the description asks for a value that depends on the day or on earlier steps, such as "the date 2 days ago" or "the first day of this month", the model types the value for today and notes how it is worked out. The recorded step gets a comment such as Computed value: today minus 2 days, as dd.MM.yyyy (recorded: 05.10.2026). Refining then writes the commands that compute it on every run (set --type:datetime --value:now, datetime --action:adddays, datetime --action:format), so the task never types a fixed date.

Taking part

The model stops and waits for you in three situations:

Every question also offers Stop here. A question that gets no answer within 15 minutes ends the exploration.

Stopping and the result

• Stop and use the steps so far ends the exploration at any time and keeps the recorded steps. Closing the dialog also stops it.
• When the exploration ends, the recorded steps are refined with AI at once (see the next section), with your description as the goal. You then choose between the recorded and the refined version.
• The browser on the agent is closed when the exploration ends.

Note: If the agent does not answer within 90 seconds for one step (offline, or the page did not load), the exploration fails with a message saying so.

#Recording + AI

After you stop a recording, the editor offers Insert as recorded or Improve with AI. With Improve with AI the model:

• removes noise such as double clicks, focus clicks before typing and needless scrolling;
• groups the commands into named steps;
• turns typed values into task inputs (the recorded value becomes the default) and repeats into a loop over a list input;
• computes values that depend on the day the task runs (a date 2 days ago, this month) instead of typing the recorded date;
• adds waits after page changes;
• replaces password steps with a credential variable.

The model never changes or invents elements: every selector in the result must be one that was recorded. A result that breaks this rule, or does not validate, goes back to the model once; if it still has problems, they are listed and only the recording can be inserted. Both versions are shown side by side with the model's list of changes. Click Use the AI version to insert it.

#The ai command

The ai command lets a task use the model while it runs: answer a question, pull fields out of a document or an email, or sort a text into categories. The agent sends the request to the Botream Server, which calls the model with the server's AI settings, so the key never reaches the robot.

Common parameters: --input (text or any variable; records and lists are sent as JSON), --file, --instructions (extra guidance), --timeout (default 120 seconds), --retry and --retryinterval.

#Ask

file --action:read --path:"C:\In\complaint.txt" --output:complaint
ai --action:ask --prompt:"Summarize this complaint in two sentences" --input:$complaint$ --output:summary
log --message:"Summary: $summary$"

#Extract

List the fields separated by commas. Each field can have a type: :text (default), :number, :date, :boolean or :list. A field the input does not contain is empty. Numbers written as 1.250,00 EUR or 1,250.00 become 1250, and dates become date values.

ai --action:extract --file:"C:\In\invoice.pdf" --fields:"InvoiceNo, Date:date, Total:number, Lines:list" --instructions:"Amounts are in EUR" --output:invoice
if --condition:$invoice.Total$>1000
    log --message:"Invoice $invoice.InvoiceNo$ needs approval"
endif

#Classify

ai --action:classify --input:$complaint$ --categories:"Invoice, Complaint, Order, Other" --output:kind
log --message:"$kind.Label$ ($kind.Confidence$): $kind.Reason$"

#Files the model can read

With both --input and --file, both are sent. Input longer than 200,000 characters is cut, with a warning in the log.

#When the ai command fails

• The step fails when Allow the ai command in tasks is off: "The ai command is turned off under Administration → Settings → AI".
• An agent without a connection to the Botream Server cannot run the command.
• For extract and classify, Botream asks the model for JSON. If the answer is not valid JSON, it asks once more; if a classify answer is not one of the categories, the step fails.
• These are system errors, so --retry and try/catch apply. See Error handling.

#AI failure analysis

When a run fails, its execution page shows the error, the screen picture and the variables at the moment of the failure (see Debugging). With a model set up, the AI failure analysis card adds an explanation:

1. Open the failed run from Executions.
2. Click Analyze with AI.

The model writes what happened, the likely cause and how to fix it, in your browser's language. The answer is stored with the run, so others see it too, together with the model and the time. Analyze again asks for a new answer. Users who run tasks or see all runs can use it on the runs they can see; only failed runs can be analyzed.

Warning: AI can be wrong. Check the explanation before you act on it.