artis-agent

Lightweight remote execution agent for Artis RPA.

Installs on any target PC and executes activities on behalf of the Artis server — without embedding the artengine workflow engine.

---

How it works

Artis Server (artengine)
        │
        │  WebSocket  EXECUTE →
        │             ← RESULT
        ▼
  artis-agent  (this package)
        │
        ├── downloads .actpkg from server if not cached
        ├── installs the wheel locally via pip
        ├── runs the activity class
        └── returns NodeResult to server

The server keeps full control of the workflow state, variables, and scheduling. The agent only executes individual activity nodes.

---

Requirements

• Python 3.11 or 3.12
• Network access to the Artis server (WebSocket + HTTP)
• A token generated by the server admin

---

Installation

pip install artis-agent

---

Quick start

1. Generate a token on the server

From the Artis Studio or via the API:

POST /api/agents/tokens
Content-Type: application/json

{
  "agent_id": "pc-marketing",
  "ttl_days": 365
}

Response:

{
  "agent_id": "pc-marketing",
  "token": "eyJhZ2VudF9pZCI6...",
  "ttl_days": 365
}

2. Start the agent

artis-agent \
  --server-url ws://your-server:8084 \
  --agent-id   pc-marketing \
  --token      eyJhZ2VudF9pZCI6... \
  --capabilities windows,chrome,office

The agent connects, sends its capabilities, and waits for execution requests. It reconnects automatically if the connection drops.

---

Configuration

All options can be set via environment variables instead of CLI flags.

CLI flag	Environment variable	Required	Description
--server-url	ARTIS_SERVER_URL	✅	WebSocket URL of the Artis server
--agent-id	ARTIS_AGENT_ID	✅	Unique identifier for this agent
--token	ARTIS_AGENT_TOKEN	✅	HMAC token generated by the server
--capabilities	ARTIS_CAPABILITIES	❌	Comma-separated capability list

Using environment variables

# Set once in your environment or .env file
export ARTIS_SERVER_URL=ws://192.168.1.10:8084
export ARTIS_AGENT_ID=pc-marketing
export ARTIS_AGENT_TOKEN=eyJhZ2VudF9pZCI6...
export ARTIS_CAPABILITIES=windows,chrome,office

# Then just run
artis-agent

Windows — set as system environment variables

[System.Environment]::SetEnvironmentVariable("ARTIS_SERVER_URL", "ws://192.168.1.10:8084", "Machine")
[System.Environment]::SetEnvironmentVariable("ARTIS_AGENT_ID", "pc-marketing", "Machine")
[System.Environment]::SetEnvironmentVariable("ARTIS_AGENT_TOKEN", "eyJhZ2VudF9pZCI6...", "Machine")
[System.Environment]::SetEnvironmentVariable("ARTIS_CAPABILITIES", "windows,chrome,office", "Machine")

---

Capabilities

Capabilities are labels that describe what the target machine can do. They are declared at startup and used by the server to route activities to the right agent.

--capabilities windows,chrome,office,sap

Common capability names (you define your own):

Capability	Meaning
windows	Running on Windows
linux	Running on Linux
macos	Running on macOS
chrome	Google Chrome installed
office	Microsoft Office installed
sap	SAP GUI installed
excel	Microsoft Excel available

In the Studio, an activity node with required_capabilities: ["office"] will be routed to the first connected agent that declared office in its capabilities list.

---

Agent routing in workflows

In the Studio, each remote activity node has an agent_id property (array of strings). The server tries each ID in order and uses the first available agent.

agent_id: ["pc-marketing", "pc-backup"]

• pc-marketing connected → used
• pc-marketing offline → tries pc-backup
• both offline → workflow fails with a clear error

If agent_id is left empty, the server routes automatically to any agent with the required capabilities.

---

Local cache

The agent caches downloaded packages locally to avoid re-downloading on every execution.

~/.artis-agent/
├── cache/
│   ├── artis_shell_runner-1.0.0.actpkg    ← downloaded package archive
│   └── artis_shell_runner-1.0.0/          ← extracted contents
│       ├── manifest.json
│       ├── wheel/
│       └── dependencies.lock.json
└── assets/
    └── <project_id>/                       ← project assets (downloaded via HTTP)
        └── templates/
            └── invoice.docx

Assets are cached by SHA256 checksum — only downloaded if changed since last execution.

---

Running as a Windows service

Using NSSM (Non-Sucking Service Manager):

nssm install ArtisAgent "C:\path\to\.venv\Scripts\artis-agent.exe"
nssm set ArtisAgent AppParameters "--server-url ws://server:8084 --agent-id pc-marketing --token <token> --capabilities windows,office"
nssm set ArtisAgent Start SERVICE_AUTO_START
nssm start ArtisAgent

Or with a .env file and the environment variables approach — NSSM can load them automatically.

---

Running as a Linux systemd service

Create /etc/systemd/system/artis-agent.service:

[Unit]
Description=Artis RPA Agent
After=network.target

[Service]
Type=simple
User=artis
Environment=ARTIS_SERVER_URL=ws://server:8084
Environment=ARTIS_AGENT_ID=pc-linux-01
Environment=ARTIS_AGENT_TOKEN=eyJhZ2VudF9pZCI6...
Environment=ARTIS_CAPABILITIES=linux,chrome
ExecStart=/usr/local/bin/artis-agent
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable artis-agent
sudo systemctl start artis-agent
sudo systemctl status artis-agent

---

Security

• Token authentication — each agent authenticates with a HMAC-SHA256 signed token generated by the server. Tokens are time-limited (default: 1 year) and can be revoked by the server admin.
• Token scope — a token is bound to a specific agent_id. An agent cannot impersonate another.
• Asset downloads — assets are fetched via HTTP with the same token. The server validates the token on every request.
• No inbound ports — the agent only makes outbound connections (WebSocket + HTTP). No ports need to be opened on the target machine.
• artengine not included — the workflow engine source code is never sent to the agent. The agent only receives the activity package (.actpkg) and the execution context for the specific node being run.

---

What the agent does NOT do

• ❌ No workflow scheduling
• ❌ No workflow compilation
• ❌ No variable scope management
• ❌ No persistence
• ❌ No artengine dependency

The server retains full control of the workflow. The agent is a thin execution layer only.

---

Troubleshooting

Connection refused at startup → Check that the server is running and ARTIS_SERVER_URL uses ws:// (not http://).

Invalid or expired token → Regenerate a token from the server: POST /api/agents/tokens.

No runtime class found for 'my_plugin.MyActivity' → The .actpkg wheel failed to install or the class was not found. Check server logs for the pip install output.

Agent reconnects in a loop → The server is rejecting the HELLO message. Verify that ARTIS_AGENT_ID matches the agent_id in the token.

---

License

MIT