> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Creating custom workers

Create a custom factory worker, add skills, and assign it work in a Blueprint or a direct dispatch.

Add a custom worker for work that needs its own instructions, configuration, and runs. For example, create a documentation worker to update reference pages after code changes.

## Prerequisites

-   [Editor access to this factory, or team or workspace admin access](https://docs.warp.dev/factories/infrastructure-and-security/#factory-roles-and-permissions).
-   An existing factory. Follow the [Warp Factories quickstart](https://docs.warp.dev/factories/quickstart/) to create one.

## Create a worker in the web app

For a Warp-managed factory, create the worker in the [Warp Factories web app](https://platform.warp.dev). For a GitHub-backed factory, use [definition files](#define-an-agent-in-code) instead.

1.  In the web app sidebar, click your factory to expand it, then click **Workers**.
2.  Click **New**.
3.  Enter a worker name and a description of its responsibilities.
4.  Under “Worker resources”, choose the worker’s [harness, model, host, and runner](https://docs.warp.dev/factories/factory-agents/configuration/) as needed. Add [MCP servers](https://docs.warp.dev/factories/mcp/) and [secrets](https://docs.warp.dev/platform/secrets/) for its tools.
5.  Under “Worker prompt”, enter the worker’s instructions.
6.  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

For a GitHub-backed factory, add `agents/<name>/agent.md` to the factory’s definition repository, replacing `<name>` with the worker’s directory name. Define its instructions and configuration using the [`agent.md` configuration keys](https://docs.warp.dev/factories/factory-as-code/#agentsnameagentmd). Follow your repository’s pull request process to apply the change.

## Add skills

Custom workers have no built-in skills. Add [factory skills](https://docs.warp.dev/factories/factory-skills/) where needed:

-   **One worker** - `agents/<name>/skills/`
-   **All workers** - `skills/`

## Assign the worker to a Blueprint stage

To include the worker in a standing workflow:

1.  In `factory.yaml`, find the stage under `blueprint.stages`, or add one. Set its `worker` to the custom worker’s directory name.
2.  Define its procedure and required results with `prompt`, `inputs`, and `outputs`. Keep guidance that applies across stages in `agent.md`.
3.  Connect the stage with entry or outgoing transitions, then [validate and apply the definition](https://docs.warp.dev/factories/factory-as-code/#validate-a-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](https://docs.warp.dev/factories/blueprints/stages/) for an implementation-to-review example.

## 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:

1.  The foreman chooses a worker from the available list.
2.  It sets `remote` to run the child in the cloud.
3.  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](#change-settings-for-one-dispatch).

For scheduled or event-driven work, use [factory automations](https://docs.warp.dev/factories/automations/).

### 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 the `base_prompt` text, then this text.
-   `name` and `title` - Labels for the child run.
-   `metadata` - Values for setup scripts and the worker. See [Select a setup profile for each task](#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](https://docs.warp.dev/factories/environments/), which supplies the repositories, toolchain, and workspace setup.
-   `remote.runner_id` - The UID of the [runner](https://docs.warp.dev/factories/runners/), which selects the operating system, CPU architecture, instance size, and sandbox image.
-   `remote.worker_host` - The host. Use `warp` for Warp-hosted workers, or use the ID of a [self-hosted worker](https://docs.warp.dev/factories/self-hosting/).
-   `remote.harness` - The [harness](https://docs.warp.dev/factories/harnesses/), such as Claude Code or Codex.
-   `model_id` - The model. A model for a third-party harness also needs `remote.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

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.

1.  Find the UID of the runner. To list runners and their UIDs, run `oz runner list` in the Oz CLI. See [List runners](https://docs.warp.dev/factories/runners/#list-runners).
    
2.  In the foreman instructions, tell the foreman which tasks use the runner. Tell the foreman to put the runner UID in `remote.runner_id`.
    
    ```text
    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_UID` to the runner UID from step 1.
    
    For a full build, the foreman sends this `run_agents` call. `IMPLEMENTATION_AGENT_UID` is the UID from the list of available workers. The `runner_id` field in `remote` selects the runner for all children in the call.
    
    ```json
    {
      "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

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.

1.  Add this script to your image at `/opt/setup/select-profile.sh`. Change `/opt/setup/setup-profile.sh` to the path of your installer. Warp does not supply these scripts or profiles.
    
    ```bash title="/opt/setup/select-profile.sh"
    profile="${WARP_METADATA_SETUP_PROFILE:-}"
    case "$profile" in
      backend|frontend)
        bash /opt/setup/setup-profile.sh "$profile"
        ;;
      "")
        printf '%s\n' 'Missing WARP_METADATA_SETUP_PROFILE' >&2
        exit 1
        ;;
      *)
        printf '%s\n' 'Unsupported setup profile; expected backend or frontend' >&2
        exit 1
        ;;
    esac
    ```
    
2.  If the environment does setup for each run, add `bash /opt/setup/select-profile.sh` to its [setup commands](https://docs.warp.dev/platform/environments/configuring-environments/). Warp sets `WARP_METADATA_SETUP_PROFILE` for the `setup_profile` key 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.sh` first for each task. If the command gives exit code `0`, tell the worker to start development. If the command gives a different exit code, tell the worker to stop.
    
3.  In the foreman instructions, tell the foreman to select a setup profile for each task. Put the profile in `agent_run_configs[].metadata`.
    
    ```text
    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 `backend` work, the foreman sends this `run_agents` call. `IMPLEMENTATION_AGENT_UID` is the UID from the list of available workers. The `remote: {}` field starts the child in the cloud.
    
    ```json
    {
      "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

-   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](https://docs.warp.dev/platform/secrets/) for credentials.

## Related pages

-   [About factory workers](https://docs.warp.dev/factories/factory-agents/) - Understand default workers and stage responsibilities
-   [Configuring factory workers](https://docs.warp.dev/factories/factory-agents/configuration/) - Edit instructions, models, harnesses, and tools
-   [Factory skills](https://docs.warp.dev/factories/factory-skills/)
-   [Factory automations](https://docs.warp.dev/factories/automations/)
-   [Definitions as code](https://docs.warp.dev/factories/factory-as-code/)
