Metadata-Version: 2.4
Name: artis-agent
Version: 1.0.0
Summary: Artis RPA remote execution agent — runs on target PCs
License: MIT
Keywords: artis,rpa,agent,automation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: websockets>=12.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: click>=8.1.0

# 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

```bash
pip install artis-agent
```

---

## Quick start

### 1. Generate a token on the server

From the Artis Studio or via the API:

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

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

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

### 2. Start the agent

```bash
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

```bash
# 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

```powershell
[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.

```bash
--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](https://nssm.cc/) (Non-Sucking Service Manager):

```powershell
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`:

```ini
[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
```

```bash
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
