Agents, agent-pools and demands

Every activity of a run is done by an agent. Most of the time you don't need to know which: Spider picks one that is free. This chapter explains how it picks, what you can do to make an activity run on the right kind of agent, and what to look at when a run waits for one. Agents themselves are set up by administrators: see Agents.

Agents

An agent is a program on a computer, or in a container, that stays connected to Spider, runs the activities Spider hands it, each with the version of its integration module that it needs, and reports back their logs and results.

• An organization's own agent works for that organization only.
• A shared agent works for every organization on the server.

Events, gateways, sub-processes and the start of other runs need no agent: Spider runs them itself. A timer, a webhook or a form trigger needs none either. Only activities, and the triggers of integration modules, run on an agent.

Agent-pools

An agent-pool is a group of identical agents: copies of one container image, say, started as many times as there is work. Each copy registers itself into the pool with one of the pool's tokens, and takes on the pool's capabilities. A pool can be an organization's own, or shared. See Agent-pools and, for shared pools, Agent-pools in Administration.

To Spider, an agent in a pool is an agent like any other: a pool doesn't choose which of its agents works, and gets no work of its own. It only keeps its agents alike.

Capabilities

Capabilities say what an agent has, as keys with a value. An agent reports some itself when it connects, and an administrator can add more, or override a reported value, on the agent's page or its pool's.

Key	Reported	Value
sdk.version	Always	The version of the Spider SDK the agent is built with, such as 1.3.0.
sdk.line, dotnet.version, agent.rid	Always	The SDK's line (1.3), the .NET version, and the platform, such as win-x64.
browser.chromium, browser.firefox, browser.webkit	When that browser is installed	true
browser.playwright, browser.playwright.line	When browsers are installed	The version and line (1.62) of Playwright, the browser automation the agent has.
browser.headed	On a Windows agent with a desktop session and browsers	true: it can show a browser on a screen, not only run one out of sight.
instance.name, instance.hostname, instance.agent.version	Always	This copy of the agent. These differ between the agents of a pool.

Anything else is up to your administrators: a capability such as network.fileshare = true on the agents that can reach a file share, or office = 2021 on those with Microsoft Office.

Demands

A demand says what an activity needs an agent to have: a Key, and optionally the Value that capability must have. Demands come from three places, and all of them count:

• The integration module. Every module demands the sdk.version it was built with, so its activities run only on agents built with the same SDK. A module can demand more, such as a browser. You can't remove these.
• The node: its Demands tab in the designer. Give one node a demand when only that step needs a particular agent.
• The process definition: its Demands tab, for every activity of the process. Use it when the whole process belongs on certain agents.

How a demand is met:

• The agent must have the key. Keys are compared without regard to case: Browser.Chromium is browser.chromium.
• When the demand has a value, the agent's value must be exactly the same, case included: true is not True, and 1.3 is not 1.3.0.
• Without a value, any value will do: the demand only asks for the key.
• An activity without demands, from a module without demands, can run on any agent. Modules always demand their SDK version, so in practice every activity has at least that one.

When two places demand the same key, the module's demand wins over the node's, and the node's over the definition's. A module's demand without a value doesn't replace a value you gave: it already asks for the key.

Demands go along when a process is exported, so the organization that imports it needs agents that meet them. See Export and import.

How Spider picks an agent

When a run reaches an activity, Spider takes the first agent that is:

1. connected and free (Idle);
2. not in maintenance;
3. the organization's own, or shared;
4. meeting every demand of the activity.

There is no further preference: not for the organization's own agents over shared ones, nor for the agent that has had the least work. The environment the run runs in plays no part either: a run in Test can run on the same agent as a run in Production. To keep them apart, give the agents a capability, such as environment = test, and the processes a demand for it.

When an agent comes free, it takes the work that waited longest, with trigger runs before process runs.

Waiting for an agent

While no agent can take an activity, its node is Waiting for an agent, and shows yellow on the run's diagram. The run is Waiting for an agent when every node it could go on with waits. There is no time limit: the run goes on by itself as soon as an agent can take the activity, whether that is a minute or a week later.

The node's log has a verbose line No agent available for activity …. Hide verbose hides it.

Spider doesn't warn you when no agent could ever take the activity: a demand no agent meets keeps the run waiting for good. When a run keeps waiting, check:

1. Are there agents at all, connected and not in maintenance? Ask an administrator, or look at an agents widget on a dashboard.
2. Do the demands match? Compare the activity's demands, those of its node, of the process, and of its module, with the agents' capabilities. The module's sdk.version is a common cause: a module built with another version of the SDK than the agents have runs on none of them, until there are agents for its version.
3. Are the agents busy with other work? Each agent runs one activity at a time.

When the demands of the process or of its module change, Spider reads them again for the nodes that wait: the run doesn't have to be started again.

Maintenance

An agent in maintenance takes no new work. Spider puts an agent in maintenance by itself, and reports an issue to the support desk, when:

• it reconnects while it was running an activity;
• an activity fails for a reason of the agent's own, rather than of the activity;
• it doesn't start an activity it was given within two minutes.

The activity it was given then fails. It isn't handed to another agent by itself: retry the failed node once the cause is clear, and another agent takes it. See When a run fails.

Only an administrator takes the agent out of maintenance again. See Maintenance.

Robot accounts

An activity that drives a desktop application, or a browser on a screen, needs a Windows desktop to do it on. A Windows agent gets one by signing in with its robot account: a Windows account, set up by an administrator. An agent in a container, or one that only runs browsers out of sight, needs none.

For you, this is a capability like any other: an activity that needs a visible browser demands browser.headed, which only an agent with a desktop session reports. See Robot account.

Related chapters

• Activities and connections: how an activity runs.
• Agents, Agent and Agent-pool: the pages where agents are managed.
• Process definition: a process's demands.