Factories > Factory workers
Creating custom workers
Create a custom factory worker, add skills, and assign it work in a Blueprint or a direct dispatch.
A custom worker is an agent configured for your factory. Create one when work needs its own instructions or tools, such as a documentation agent that updates reference pages after code changes.
Prerequisites
Section titled “Prerequisites”- Editor access to this factory, or team or workspace admin access.
- An existing factory. Follow the Warp Factories quickstart to create one.
Create a worker in the web app
Section titled “Create a worker in the web app”For a Warp-managed factory, create the worker in the Warp Factories web app. For a GitHub-backed factory, use definition files instead.
- In the web app sidebar, click your factory to expand it, then click Workers.
- Click New.
- Enter a worker name and a description of its responsibilities.
- Under “Worker resources”, choose the worker’s harness, model, host, and runner as needed. Add MCP servers and secrets for its tools.
- Under “Worker prompt”, enter the worker’s instructions.
- In the top-right corner, click Save.
The new worker appears on the factory’s Workers page. Worker names can’t be changed after creation.
Define a worker in code
Section titled “Define a worker in code”For a GitHub-backed factory, preserve the definition’s existing root: add workers/<name>/worker.md for a workers/ tree or agents/<name>/agent.md for an agents/ tree. Replace <name> with the worker’s directory name. To edit an existing worker, keep its filename. Use the worker configuration keys, then apply the change through a pull request.
Add skills
Section titled “Add skills”Custom workers have no built-in skills. Add factory skills where needed:
- One worker -
skills/beside its existingworker.mdoragent.md - All workers -
skills/
Assign the worker to a Blueprint stage
Section titled “Assign the worker to a Blueprint stage”To include the worker in a standing workflow:
- In
factory.yaml, find the stage underblueprint.stages, or add one. Set itsworkerto the custom worker’s directory name. - Define its procedure and required results with
prompt,inputs, andoutputs. Keep shared guidance in the worker file. - Connect the stage with entry or outgoing transitions, then validate and apply the definition. Start new test work and inspect the assigned worker’s conversation and outputs.
Creating a worker alone does not add a workflow stage. See Defining Blueprint stages for an implementation-to-review example.
Dispatch a configured worker
Section titled “Dispatch a configured worker”For delegated Blueprint stages, the coordinator selects the worker declared by the stage and supplies its stage-specific inputs. It continues that worker’s existing conversation for later stages or revisions in the same task.
For direct dispatch, the foreman uses run_agents to dispatch configured factory workers. It receives a list of available workers and their unique IDs (UIDs), then:
- The foreman chooses a worker from the available list.
- It sets
remoteto run the child in the cloud. - For each child, it supplies the selected worker’s UID in
agent_run_configs[].agent_identity_uid.
The name field only labels the child run. By default, the run uses the environment, runner, host, harness, and model of the selected worker. To change these settings for one dispatch, see Change settings for one dispatch.
For scheduled or event-driven work, use factory automations.
Change settings for one dispatch
Section titled “Change settings for one dispatch”Settings in a run_agents call affect only the children it starts, not the saved worker configuration.
Each field in an agent_run_configs[] entry applies to one child:
agent_identity_uid- The UID of the configured worker that does the task.prompt- The task for this child. The child receives thebase_prompttext, then this text.nameandtitle- Labels for the child run.metadata- Values for setup scripts and the worker. See Select a setup profile for each task.
These fields apply to all children in the call. Each field replaces a setting from the worker configuration:
remote.environment_id- The environment, which supplies the repositories, toolchain, and workspace setup.remote.runner_id- The UID of the runner, which selects the operating system, CPU architecture, instance size, and sandbox image.remote.worker_host- The host. Usewarpfor Warp-hosted workers, or use the ID of a self-hosted worker.remote.harness- The harness, such as Claude Code or Codex.model_id- The model. A model for a third-party harness also needsremote.harness.
If the call does not set one of these fields, the child runs use the setting from the worker configuration. The call-level metadata field sets default metadata for all children in the call.
A call gives the same settings to all of its children. To use a different runner or environment for some children, start those children with a different run_agents call.
The environment and the runner are separate settings. If the call sets only the environment, the child runs keep the runner from the worker configuration. If the worker configuration has no runner, the child runs use the default runner of the environment.
Select a runner for a task
Section titled “Select a runner for a task”Use a different runner when a task needs more compute or a different operating system. You do not need a separate worker for the task.
-
Find the UID of the runner. To list runners and their UIDs, run
oz runner listin the Oz CLI. See List runners. -
In the foreman instructions, tell the foreman which tasks use the runner. Tell the foreman to put the runner UID in
remote.runner_id.Select the configured implementation worker from the list of available workers.Set agent_identity_uid to the UID of that worker.For full builds and integration tests, set remote.runner_id to LARGE_RUNNER_UID.For all other tasks, do not set remote.runner_id.Keep the configured environment, host, harness, and model.Change
LARGE_RUNNER_UIDto the runner UID from step 1.For a full build, the foreman sends this
run_agentscall.IMPLEMENTATION_AGENT_UIDis the UID from the list of available workers. Therunner_idfield inremoteselects the runner for all children in the call.{"summary": "Run the full build on the large runner","base_prompt": "Implement the task and verify the change.","remote": {"runner_id": "LARGE_RUNNER_UID"},"agent_run_configs": [{"name": "full-build","agent_identity_uid": "IMPLEMENTATION_AGENT_UID","prompt": "Run the full build and fix the failing integration tests."}]}
The child run uses the large runner, and the environment, host, harness, and model from the worker configuration.
Select a setup profile for each task
Section titled “Select a setup profile for each task”Run metadata supplies string keys and values for setup scripts and the worker. Children with the same configuration can receive different values without changing their saved settings.
For Warp-hosted and self-hosted runs, Warp makes these inputs available as WARP_METADATA_* environment variables. For setup that starts with each run, Warp sets these variables before the setup commands start. Your scripts can read these variables to select a test group or a build target. Metadata does not select commands or install tools.
The setup example uses backend and frontend profiles with the same implementation worker, runner, and environment.
-
Add this script to your image at
/opt/setup/select-profile.sh. Change/opt/setup/setup-profile.shto the path of your installer. Warp does not supply these scripts or profiles./opt/setup/select-profile.sh profile="${WARP_METADATA_SETUP_PROFILE:-}"case "$profile" inbackend|frontend)bash /opt/setup/setup-profile.sh "$profile";;"")printf '%s\n' 'Missing WARP_METADATA_SETUP_PROFILE' >&2exit 1;;*)printf '%s\n' 'Unsupported setup profile; expected backend or frontend' >&2exit 1;;esac -
If the environment does setup for each run, add
bash /opt/setup/select-profile.shto its setup commands. Warp setsWARP_METADATA_SETUP_PROFILEfor thesetup_profilekey before per-run setup and the worker start.Pre-warmed sandboxes do their initial setup before Warp selects them for a run. This setup does not receive the metadata for that run. Warp does not do this setup again when it selects the sandbox for a run.
For pre-warmed sandboxes, use setup commands only for work that is the same for all runs. In the worker instructions, tell the worker to run
bash /opt/setup/select-profile.shfirst for each task. If the command gives exit code0, tell the worker to start development. If the command gives a different exit code, tell the worker to stop. -
In the foreman instructions, tell the foreman to select a setup profile for each task. Put the profile in
agent_run_configs[].metadata.Select the configured implementation agent from the list of available agents.Set agent_identity_uid to the UID of that agent.For service work, set setup_profile to backend.For UI work, set setup_profile to frontend.Put setup_profile in the metadata for that child.Keep the configured environment, runner, host, harness, and model.For
backendwork, the foreman sends thisrun_agentscall.IMPLEMENTATION_AGENT_UIDis the UID from the list of available workers. Theremote: {}field starts the child in the cloud.{"summary": "Delegate backend work to the configured implementation agent","base_prompt": "Implement the task and verify the change.","remote": {},"agent_run_configs": [{"name": "backend-implementation","agent_identity_uid": "IMPLEMENTATION_AGENT_UID","prompt": "Fix the API service's failing tests.","metadata": {"setup_profile": "backend"}}]}
To set a batch value for all children, use run_agents.metadata. To set a value for one child, use agent_run_configs[].metadata.
For each key, Warp uses the child value first. If no child value is available, Warp uses the batch value. If no child or batch value is available, Warp keeps the parent value.
Metadata limits and environment variables
Section titled “Metadata limits and environment variables”- Metadata keys and values must be strings. A run can have a maximum of 20 keys. This total includes keys from the parent and keys that Warp adds automatically.
- Keys must have 1–64 bytes. Keys can contain only
A–Z,a–z,0–9,.,_, and-. Values must have 0–256 bytes of UTF-8 text. Values cannot contain NUL characters. - Warp makes environment variable names from the metadata keys. Warp adds
WARP_METADATA_, changes letters to uppercase, and changes.and-to_. If two keys make the same environment variable name, Warp rejects them. - The
WARP_METADATA_prefix is for metadata only. Images, worker environments, and secrets must not set variables with this prefix. - Local runs in the Warp app or a standalone CLI do not receive these environment variables.
Each person with access to a run can read its metadata. Do not put credentials in metadata. Use Agent Secrets for credentials.
Related pages
Section titled “Related pages”- About factory workers - Understand default workers and stage responsibilities
- Configuring factory workers - Edit instructions, models, harnesses, and tools
- Factory skills
- Factory automations
- Definitions as code