Skip to content
Orvanta Docs

Agent workers

Agent workers are a Cloud & Self-hosted Enterprise feature that function as remote computing resources capable of executing Orvanta jobs from anywhere globally, including environments with limited network connectivity to the main cluster.

Key characteristics

Section titled “Key characteristics”

Billing model: agent workers count as 1 compute unit per worker on self-hosted EE (when unused for compute) and 0.5 compute unit on cloud EE (when unused for compute).

Execution mode: agent workers operate using MODE=agent instead of MODE=worker, requiring only an HTTP connection to an internal cluster URL rather than direct database access.

Use cases

Section titled “Use cases”

Agent workers are recommended for:

  • Remote workers experiencing high latency or unreliable connectivity to the main database/cluster
  • Untrusted environments where database access is prohibited
  • Deployments requiring thousands of workers, as they reduce database connection strain through server connection pooling

Setup process

Section titled “Setup process”
  1. Navigate to the Workers page (/workers) as a superadmin.
  2. Click ”+ New agent worker”.
  3. Configure in the drawer:
    • Agent group: used solely for grouping on the workers page.
    • Tags: static list encoded in the JWT token; defines which jobs the worker executes.

Deployment configuration

Section titled “Deployment configuration”

Start the Orvanta binary with these environment variables:

Terminal window
MODE=agent
AGENT_TOKEN="<token>"
BASE_INTERNAL_URL="<internal url>"

Optionally include INIT_SCRIPT with startup commands.

The BASE_INTERNAL_URL should reference the Orvanta instance’s internal base URL (no trailing slash).

Dynamic tags

Section titled “Dynamic tags”

Tags can incorporate dynamic elements based on job arguments (tag-$args[argName]) or workspace ID (tag-$workspace) to enable flexible worker targeting.

Architecture

Section titled “Architecture”

Agent workers communicate exclusively via HTTP requests using JWT-authenticated endpoints at /api/agent_workers/ and /api/w/<workspace>/agent_workers/. The JWT token contains worker tags and group information, ensuring workers only access jobs matching their assigned tags.

Key advantages: a secure, lightweight architecture with built-in request retry logic for resilience. Supports significantly more concurrent workers than traditional workers due to connection pooling.

Complementary requirement

Section titled “Complementary requirement”

Systems require at least one normal worker listening to tags flow and dependency (or workspace-specific variants), since agent workers cannot execute dependency jobs or manage flow state machines.

Section titled “Related”