Agents

An agent is a Windows machine that runs your tasks: the Botream Agent connects it to Botream Server, receives the commands of a run and reports the log and the result back.

#How an agent works

Each machine has one agent identity. The Botream Agent has two parts:

When you exit the tray app on a workstation, it stays closed until the next sign-in. On an unattended robot machine the service always starts it again, and Windows signs in automatically with the robot account chosen at installation.

The agent sends a heartbeat every 30 seconds. If the connection drops, it reconnects by itself, waiting a little longer after each failed attempt (up to a minute).

To install an agent, see Install the agent.

#The tray app

The Botream icon in the notification area shows the connection state:

Right-click the icon for its menu. The first line shows the current state (for example Connected, Running task name, Waiting for administrator approval or Refused: reason). Below it:

• Open dashboard: opens the agent's dashboard window (a left click on the icon does the same).
• View logs: opens the dashboard on its Logs tab.
• Settings: server address, agent name and registration token.
• Reconnect: connects to the server again now.
• Exit: closes the tray app.

When the agent waits for approval, or the server refuses it (for example because it was rejected or deactivated, or the token is wrong), Windows shows a notification once with the reason.

#Dashboard window

The Overview tab shows:

• The connection state, with Reconnect and Settings buttons.
• CURRENT TASK: the task running now and for how long, with a Stop button. When nothing runs, it says Idle — waiting for tasks.
• THIS AGENT: name, server, machine, IP address, Windows version and agent version.
• RECENT RUNS: the runs since the agent started, with their result, time and duration. Hover a failed run to see its error.

#Agent activity log

The Logs tab of the dashboard lists what the agent did since it started: connections, runs and their log lines. Use Copy to put the log on the clipboard (for example to send it to support) and Clear to empty the list.

Tip: The full log of every run is also stored on the server. Open it from Executions in the web app; see Running tasks.

#Agent settings

The Settings window has three fields:

• Server address: the address of Botream Server, for example http://rpa-server:3000.
• Agent name: shown in the web app when you choose where a task runs. Each machine needs its own name.
• Registration token: the shared secret from Administration → Agents → Install an agent → Show token.

Click Save and connect. On a machine where the agent is installed as a service, these are machine settings: click Change as administrator to edit them. The running tray app picks up the change without a restart.

Below the fields, Language sets the language of the tray app (its menu, windows, progress panel, dialogs and recorder bar): Automatic (Windows language) shows Turkish on a Turkish Windows and English otherwise, or choose English or Türkçe. The choice belongs to the signed-in Windows user, so every user can change it, also on a machine with machine settings. It is saved right away and used the next time the tray app starts: choose Exit in the tray menu and start Botream Agent again. Log lines, and the reasons the server gives, stay in English.

#Watching a run on the machine

Whoever looks at the agent's screen can follow a run:

• Progress window: a small window at the bottom right that never takes the focus. It shows the status, the task name, the elapsed time, the current command, and the line it is on (for example Line 12 of 40) with a progress bar. You can drag it by its header; the close button hides it while the task keeps running.
• The window in front: before each element action, the window it works in — the browser with the page's tab selected, or the desktop program — comes to the front (and is restored when minimized). Headless browsers have no window. (click, type, select…), a pointer moves to the element and an orange frame labelled with the action (for example Click or Type) marks it for about a second.
• Desktop actions: before each element action, the mouse pointer moves to the element and an orange frame surrounds it briefly.

The progress window closes as soon as the run ends. The result appears in the web app that started the run and in the tray app's list of recent runs.

#Pause, resume and stop

The progress window has two buttons:

• Pause holds the run before its next command. The command that is running (for example a wait) finishes first. The button then reads Run: click it to continue.
• Stop task cancels the run. The execution ends as Stopped.

Pausing is handy when you need the machine for a moment, or want to watch a step closely.

#Registration and approval

An agent registers itself the first time it connects with a valid registration token. What happens next depends on the setting Require approval for new agents (see Settings):

• Off (default): the new agent can run tasks at once.
• On: the agent registers as Waiting for approval and runs nothing until an administrator approves it. The tray app shows Waiting for administrator approval with an amber icon.

#Approving and retiring agents

Administrators manage agents under Administration → Agents. A banner tells you how many agents are waiting for approval, and the Agents tab shows a badge with that number.

The table lists every agent with its machine name and IP address, Status, Groups, Version, Runs (number of executions) and Last seen. Use the row's Approve button or its actions menu:

Every approval, rejection, activation and deactivation is recorded in the audit log.

Note: When the server offers a newer agent installer, the Version column shows Update to version. Installed agents update themselves while no task runs, unless Update agents automatically is off in Settings. See Upgrade and backup.

#Agent statuses

The dashboard shows the same live state for every agent, with a link to the run it is busy with.

#Agent groups

A group lets a schedule run on whichever of several agents is free. Open Administration → Agents → Groups and click New group:

• Name, for example Finance robots.
• Description: what these agents are for.
• Agents: the members. An agent can belong to several groups.

A schedule that targets a group runs on the first free, online and approved member. You cannot delete a group while schedules still use it; deleting a group never removes its agents. See Schedules.

#One run at a time

An agent runs one execution at a time. A run that is started on a busy agent is refused with a message such as Agent 'FINANCE-PC-01' is already running a task.

If an agent loses its connection during a run, the server marks that execution as Failed. Work items it had taken from a work queue go back to the queue.

#How a run picks its agent

Runs are not queued: when no suitable agent is free, a manual run is refused (for example All online agents are busy) and a scheduled run is recorded as Skipped and tries again at its next time.