Skip to main content

Agents and agent pools

In briefAn agent runs jobs on a machine: a Universal Agent runs the built-in connectors, and legacy agents are reached through a relay. Agent pools route work: a Universal Agent pool is a queue its agents claim jobs from, and a legacy agent group is a dispatch target for legacy job types. A job assigned to a specific agent can name up to three backup agents, and runs on the first available one when its primary cannot take it. Each agent shows its observed status and any operator mark you set.

WhereAgents in the navigation, with three tabs: Agents, Agent Pools and Relays, each at its own address. Selecting a row opens its edit dialog. Each tab needs its View permission under All workspaces.

When

  • Registering a legacy agent under a relay, or grouping agents so jobs can run on whichever is available.
  • Taking an agent out of service for maintenance with Mark Draining or Mark Offline, or resetting one agent's connection with Mark Offline then Clear Mark.
  • Keeping a specific-agent job running when its agent goes down, by giving it backup agents.
  • Checking a legacy agent whose Status shows a warning because its reported host name changed.
  • Diagnosing a job held in Waiting: Machine, an Unknown or Offline agent, or a pool that takes no work.
  • Use Relays for the relay itself, and the job type's own page for job settings.

How

  1. On the Agents tab, New Agent, choose the type, and fill in the form. A Universal Agent is registered through the API instead, and its program then signs in with the credentials file.
  2. On the Agent Pools tab, New Agent Pool, pick the Type, and add agents of that type.
  3. Assign the pool, group or agent to the job in the workflow. For a specific agent, turn on Configure backup agents to choose up to three backups.
  4. To service a machine, mark it from its row menu, and Clear Mark when you are done.
  5. For the full steps, see Manage agents and agent pools.
Notes
  • A Universal Agent pool job is one job on the pool's queue, claimed by whichever agent polls first, whether the mode is least-tasked or run-all. A job assigned to a specific Universal Agent can run on any agent in that agent's pool.
  • A Universal Agent obeys its own MAX_CONCURRENT_JOBS setting (default 50), not the Concurrent Jobs (max) figure on its row.
  • Use TLS for Scheduling on a Windows, Unix, IBM i, MCP, z/OS or OS 2200 agent has the relay connect to it over TLS. It needs relay 1.24.0 or later and TLS on at the agent, and never falls back to an unencrypted connection.
  • Unknown means the agent's relay is stale, not that the agent is down. A job aimed at an Unknown agent holds in Waiting: Machine until the agent is Online again. If the relay stays gone for an hour, its Unknown agents read Offline.
  • Backup agents are tried in order only while the primary is unavailable, and every run starts again from the primary. A job on a pool or group, a SMAFT File Transfer or OpCon RPA Task job, and a z/OS Tracked or Queued Job never use them. When no backup can take the job, it waits in Waiting: Machine, and it is never sent to an agent that cannot take it.
  • SMAFT File Transfer and OpCon RPA Task jobs run on one specific agent only; the editor offers nothing else, and a save that sets a pool, a group or a backup agent on one is refused.
  • A legacy agent's host-name warning is information only. It clears when you choose Accept Host Name, when the agent reports its earlier name again, or when you change its LSAM Host or LSAM Port.
  • A mark survives a reconnect, warns but does not block when jobs are running, and takes effect within about five seconds.
  • Mark Offline stops communication: the relay closes a legacy agent's connection within about a minute, and Clear Mark opens a new one. Running jobs keep running and report afterwards. Mark Draining keeps the agent connected.
  • Check CRC (every legacy type) and Requires XML Escape Sequences (Windows, SQL, MCP) are set per agent; changing either from its default needs a current relay.
  • A mark set by a $MACHINE:STATUS event a person sent shows that person as Set by; one a job, workflow or machine raised shows Set by system.
  • A clean stop shows offline in about a second. An abrupt loss takes about 90 seconds for a Universal Agent and two minutes for a relay.
  • A newly registered Universal Agent reads Offline, with a last heartbeat of Never, until the agent program first checks in.
  • BIS agents can be registered, but no job type runs on them.
  • An MCP agent's name must end with a period and be at most 24 characters. A z/OS agent's name is saved in upper case, at most 8 characters.
  • A blank JORS Port, or 0, turns JORS off for the agent.
  • A legacy agent's Concurrent Jobs (max) is not enforced.
  • Machine Properties, in the footer of every Edit Agent dialog, holds the agent's own name and value pairs, read by [[MI.Name]]. Changing them needs Agents Edit under All workspaces, and the values are not encrypted.
  • An SAP agent's SAP system details are used by the SAP lookups in the job editor and by Check SAP Job Numbers, not by its jobs.
  • Allow Kill is on by default for every killable legacy type except SAP R/3 and CRM, where it is off.
  • Every action needs the matching Agents, Agent Pools or Relays permission, granted under All workspaces. A legacy agent group follows the Agent Pools permissions.
Watch out
  • The install commands shown for Universal in New Agent do not register an agent. Register it through the API and write its credentials file.
  • Every Universal Agent job has a fixed one-hour limit, and Kill does not stop it.
  • Kill on a legacy job is refused when its agent's Allow Kill is off, and always on SAP BW, OS 2200 and BIS agents.
  • A legacy agent with no default event environment has every event it raises refused.
  • File transfer is opt-in: until a legacy agent has an FT Role, it takes part in no SMAFT transfer.
  • A pool or group that still has agents cannot be deleted.
  • An agent that is online, has jobs on it, or is named by a workflow or an unfinished job cannot be deleted. Mark it offline and clear what the refusal lists first.
  • A backup agent is not checked for the job's type: a backup that cannot run the job is refused it, as the primary would be. Only for OpCon MFT, OpCon RPA and EASE jobs is a backup on a relay with that kind of job turned off skipped.
  • A legacy job whose machine name points at an agent of another type is refused at dispatch, with LSAM_AGENT_TYPE_MISMATCH.