Skip to main content

Worker Definitions and Workers

WRM separates the template for a worker from the running instance. A worker definition is the template; a worker is the instance. This page explains how the two relate, what each contains, and how to create custom worker definitions.

Worker definitions​

A worker definition is a reusable configuration template that describes:

  • Role — the function the worker fulfils (e.g. docs_writer, db_migration)
  • Name and description — a human-readable label and explanation of what the worker does
  • System prompt — the instructions given to an AI worker when it starts
  • Model preferences — an ordered list of AI models the worker should use, with priority and parameter overrides
  • MCP servers and tools — which tool servers the worker can connect to, and which specific tools it is allowed to call

Worker definitions are tenant-scoped and reusable. You define a template once and create as many worker instances from it as you need.

Built-in definitions​

Raytio ships with a starter set of worker definitions that cover common roles. These are included in each tenant and can be used as-is or customised. Examples include definitions for code review, documentation writing, database migration, and general-purpose assistance.

Creating a custom worker definition​

To create a custom worker definition:

  1. Choose a role. Select an existing role or create a new one that describes the function your worker will perform. Roles are shared with PPM, so a role you create here can also be used to assign work items.

  2. Write a system prompt. The system prompt defines the worker's behaviour, expertise, and constraints. A good system prompt is specific and actionable — it tells the worker what it is responsible for, what conventions to follow, and what to avoid.

  3. Set model preferences. Add one or more model availabilities in priority order. The first available model will be used. For each preference you can optionally override default parameters (temperature, max tokens, etc.).

  4. Configure tool access. Select which MCP servers the worker can use. You can grant access to an entire server (all its tools) or restrict access to specific tools within a server. Tool configuration follows an allowlist — a worker can only use tools that are explicitly granted.

  5. Save the definition. Once created, the definition is available for creating worker instances.

tip

Start by duplicating a built-in definition that is close to what you need, then adjust the system prompt, model preferences, and tool access. This is faster than building from scratch and ensures you inherit sensible defaults.

Workers​

A worker is a concrete instance created from a worker definition. It represents a specific entity — person, AI agent, or service — that is actively performing work in the system.

Each worker has:

  • Party link — every worker is linked to a party record. AI agents and services use dedicated party types, while human workers link to their existing user record.
  • Definition link — the worker definition this instance was created from
  • Optional overrides — a worker instance can override its definition's model preferences and MCP server configuration without changing the template

Definition inheritance and overrides​

When a worker is created from a definition, it inherits all the definition's configuration by default. The instance-level override tables are optional — if no overrides are set, the worker uses exactly what the definition specifies.

Overrides work at the collection level:

  • Model preferences — the worker can specify its own ordered list of model preferences, completely replacing the definition's list
  • MCP servers — the worker can specify its own set of MCP servers. Per-server tool restrictions from the definition are inherited unless explicitly overridden at the instance level

This design means you can create a standard "code reviewer" definition and then create specialised instances that use different models or have access to additional tools, without duplicating the entire configuration.

The relationship between roles, definitions, and workers​

  • A role is a named function (e.g. docs_writer). Multiple definitions can share the same role.
  • A worker definition is a specific configuration for that role — one role might have definitions for different model stacks or tool configurations.
  • A worker is an instance of a definition, linked to a party that actually performs work.

This three-level structure gives you flexibility: define the role once, create different flavours of configuration for it, and instantiate as many workers as you need.