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.
What does an agent do?
Section titled “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
Section titled “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 |
The choice is made when installing. See Windows Installation.
Which one do I choose?
Section titled “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 |
How to connect to Zoan Cloud
Section titled “How to connect to Zoan Cloud”- The agent boots up and authenticates against Zoan Cloud with its Machine Key.
- Establishes a secure persistent WebSocket connection (outgoing, on port 443).
- Zoan Cloud marks it as
onlineand you can now assign runs to it. - The agent sends a periodic heartbeat to indicate that it is still active.
- If the connection is lost, Zoan Cloud marks it as
offlineafter 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
Section titled “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.
An agent = a machine
Section titled “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
Section titled “Next steps”- Windows Installation — install and connect the Agent step by step.
- Settings — agent settings.
- Monitoring and statuses — monitor agents from the portal.