Worker Management Overview
The WRM module provides a unified way to define, configure, and manage workers across your organisation. A "worker" in Raytio is any entity that performs work — a human team member, an AI agent, or an automated service. WRM gives each worker a structured identity and tracks the resources it needs to operate.
Key concepts
WRM is built around these core concepts:
| Concept | What it represents |
|---|---|
| Role | A named function a worker fulfils (e.g. docs_writer, code_reviewer, qa_tester) |
| Worker definition | A reusable template that specifies a role, system prompt, model preferences, and toolset |
| Worker | A running instance created from a definition, linked to a party in the system |
| Domain | An area of specialisation (e.g. billing, platform) with its own repositories and context |
| Assignment | A worker holding a role, optionally within a domain |
| Memory | Knowledge a worker has accumulated, scoped to the organisation, a domain, a role, a repository, or itself |
| Knowledge source | Existing documentation or code that workers can search by meaning |
| Provider | An AI inference service (e.g. Anthropic, OpenAI, Amazon Bedrock) |
| Model | A specific AI model offered by a provider (e.g. Claude Opus 4, GPT-4o) |
| MCP server | A Model Context Protocol server that exposes tools a worker can use |
How it works
Definitions are templates; workers are instances
The split between worker definitions and workers is the central design idea. A definition is a reusable template — it describes what a worker should do and how it should be configured. A worker is a running instance created from that definition, bound to a specific party (person, agent, or service) in the system.
This separation means you can define a "code reviewer" template once and then create multiple worker instances from it — one for each AI agent or team member that fills that role. Each instance inherits the definition's configuration but can optionally override specific settings like model preferences or tool access.
The model stack
Workers that use AI models are configured through a three-tier model stack:
- Providers — the companies or services that host AI models (Anthropic, OpenAI, Bedrock)
- Models — the specific models available from each provider (Claude Opus, GPT-4o)
- Availabilities — the deployment endpoints where a model can be accessed, with region and pricing information
Worker definitions specify model preferences — an ordered list of model availabilities the worker should use, with priority ranking and optional parameter overrides. This lets you configure fallback behaviour: if the preferred model is unavailable, the worker can fall back to alternatives.
Roles, domains, and assignments
A role says what a worker does; a domain says where. The same role means different things in different areas of the organisation — for example, a product owner for billing and one for platform hold the same role but work against different repositories and different accumulated knowledge.
An assignment ties the two together: a worker holds a role, optionally scoped to a domain. One worker can hold several assignments and cover more than one domain, and an assignment with no domain applies everywhere, which suits workers who perform the same job in every area — for example, an executor that implements whichever work item it is given.
Assignments are also where scheduled workers are configured. A worker that wakes on a schedule to review its domain, rather than being dispatched in response to a work item, carries that schedule on its assignment along with a switch to pause it.
Accumulated knowledge
Workers build up memories as they work — corrections from users, lessons from things that went wrong, pointers to where information lives, and current project context. Memories are scoped, so a lesson about one repository stays with the work that repository is part of, and shared-scope memories are reviewed before other workers see them.
Alongside memories, knowledge sources give workers searchable access to material your organisation has already written — documentation, code, API specifications. Memories are what workers have learned; knowledge sources are what you have authored.
Tools via MCP
Workers can be given access to tools through MCP (Model Context Protocol) servers. Each MCP server exposes a set of tools, and worker definitions specify which servers (and optionally which specific tools from each server) the worker is allowed to use.
Tool access follows an allowlist model:
- A definition specifies which MCP servers the worker can connect to
- Within each server, specific tools can be included or excluded
- Worker instances inherit their definition's tool configuration but can override the server set
Cross-module integration
WRM does not exist in isolation — it connects to several other areas of the Raytio platform:
- Parties — every worker is a party in the system. AI agents and services use dedicated party types, while human workers link to their existing user record.
- Credentials — AI provider credentials are held separately from worker configuration, encrypted. Secrets an individual agent needs for its own task are requested from a person and shared through Raytio's encrypted sharing flow. See Agent Credentials.
- Projects — work items and epic template slots reference WRM roles, so the same role definitions are shared between how work is assigned and how workers are configured. Domains can be linked to a project portfolio, and domain repositories are the repositories tracked as external systems.
Multi-tenancy
Like all Raytio modules, WRM is fully tenant-scoped. Provider configurations, worker definitions, workers, domains, assignments, memories, and knowledge sources all belong to a specific tenant. Starter data (built-in providers, models, worker definitions, and knowledge sources) is provided per tenant and can be customised without affecting other tenants.