What is an agent

The agent is the component that executes the automations in your infrastructure. It’s the muscle of the platform: while Zoan Cloud decides what and when to run, the agent is the one who actually opens the browser, moves the mouse, reads the Excel and does the work, on a machine of yours.

It is the Zoan Agent application (part of the Zoan Platform installer) running on a Windows computer or server. It connects to Zoan Cloud, announces that it is available and waits for orders.

In the portal, each computer running the Agent shows up as a machine, under Centro › Máquinas (Center › Machines), next to Sesiones de robot (Robot sessions). There you create one with Nueva máquina (New machine), and its ⋮ menu lets you Cambiar nombre (Rename), Regenerar clave (Regenerate key), Desconectar ya (Disconnect now), Suspender (Suspend) or Eliminar (Delete). For a folder’s processes to run on a machine, assign it under that folder’s Acceso › Máquinas tab.

Headless processes on Zoan Cloud

Sin pantalla (headless) processes, which don’t need a desktop, can also run on Zoan Cloud without installing anything: it shows up as one more machine when you launch the execution.

Why does it run on my machine and not in the cloud?

Because your bots need to access your applications: the ERP installed on your network, your team’s Excel, internal systems that are not exposed to the internet. The agent lives where those applications live. Zoan Cloud, in the cloud, just coordinates it.

What does an agent do?

• Maintains connection with Zoan Cloud and sends periodic heartbeats (“I’m still alive” signal).
• Downloads the automation package when it receives an execution order.
• Run the process locally with the Runner, step by step.
• Send logs in real time while it runs.
• Report the result (success or error) upon completion.

Operating modes

Mode	how it runs	When to use it
Attended	Inside an open Windows user session	Personal assistants; automations that a user launches on their computer
Unattended	As a Windows service in the background, on a server/VM with no one present	Automatic processes, typically programmed

In attended mode the person signs in to the Agent with their Zoan Cloud account: the Agent opens the browser on the Autorizar Zoan Agent (Authorize Zoan Agent) page, they confirm and go back to the app. If they already signed in to Zoan Designer, the Agent uses that same session and does not ask again (since version 1.2.30; see The person’s account). Each attended execution runs in their name (listed with type Atendida, attended) and requires their Robot atendido (attended robot) license; without it, the Ejecutar (Run) button is disabled. See Licenses.

The choice is made when installing. See Windows Installation.

Unattended + interface automation

If an unattended process automates the interface (desktop or windowed browser), it needs a Windows desktop to act on — and on a server with no one connected, that desktop doesn’t exist on its own. That’s what robot sessions are for: a Windows account that the agent uses to open the bot’s desktop session. It is chosen when launching the execution.

Which one do I choose?

In practice, most business processes are unattended: they are the ones you want to run alone, at night or by schedule, without taking up anyone’s computer. The attended is for cases where a person participates.

Elige atendido si…	Elige desatendido si…
A user hand-launches it on their own computer when they need it	Run alone, by schedule or in queue, without intervention
The bot assists the person in their daily work (a “co-pilot”)	Procesa lotes o tareas repetitivas en segundo plano
You need the session and permissions of that user	Must run 24/7 on a dedicated server or VM
The volume is occasional and punctual	You want to scale with multiple bots in parallel

The simple rule

If the phrase “I want this to run alone at dawn without anyone there” describes your process → unattended (on a server, with a robot session). If it is “I want to click a button on my PC and have the bot help me” → attended.

How to connect to Zoan Cloud

1. The agent boots up and authenticates against Zoan Cloud with its Machine Key.
2. Establishes a secure persistent WebSocket connection (outgoing, on port 443).
3. Zoan Cloud marks it as online and you can now assign runs to it.
4. The agent sends a periodic heartbeat to indicate that it is still active.
5. If the connection is lost, Zoan Cloud marks it as offline after a grace period.

The agent always initiates the connection to Zoan Cloud; Zoan Cloud never opens connections to the agent. This simplifies the network: just allow HTTPS/WSS output. See Architecture › How they communicate.

Machine Key

The Machine Key is the secret key that identifies an agent to Zoan Cloud — their “password.” It is generated automatically when creating the agent in the portal and is configured on the Agent one time.

Shown only once

The Machine Key only appears once, when creating or regenerating the agent. Copy it and save it somewhere safe before closing the modal. If you lose it, you will have to regenerate it (which invalidates the previous one) and reconfigure the Agent.

An agent = a machine

Each agent represents a physical or virtual machine. It is not designed to run multiple instances with the same Machine Key: each machine must have its own key. To run multiple processes in parallel, you need multiple agents (multiple machines or VMs).

Next steps

• Windows Installation — install and connect the Agent step by step.
• Settings — agent settings.
• Monitoring and statuses — monitor agents from the portal.