> 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 agents

Create a custom factory agent, add skills, and configure how the foreman dispatches it.

Add a custom agent for work that needs its own instructions, configuration, and runs. For example, create a documentation agent 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 an agent in the web app

For a Warp-managed factory, create the agent 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 **Agents**.
2.  Click **New**, then **Custom agent**.
3.  Enter an agent name and a description of its responsibilities.
4.  Under “Agent resources”, choose the agent’s [harness, model, host, and runner](https://docs.warp.dev/factories/factory-agents/configuration/) as needed. Add [MCP servers](https://docs.warp.dev/platform/mcp/) and [secrets](https://docs.warp.dev/platform/secrets/) for its tools.
5.  Under “Agent prompt”, enter the agent’s instructions.
6.  In the top-right corner, click **Save**.

The new agent appears on the factory’s **Agents** page. Agent names can’t be changed after creation.

## Define an agent in code

For a GitHub-backed factory, add `agents/<name>/agent.md` to the factory’s definition repository, replacing `<name>` with the agent’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 agents have no built-in skills. Add [factory skills](https://docs.warp.dev/factories/factory-skills/) where needed:

-   **One agent** - `agents/<name>/skills/`
-   **All agents** - `skills/`

## Dispatch a configured agent

The foreman uses `run_agents` to dispatch configured factory agents. It receives a list of available agents and their unique IDs (UIDs), then:

1.  The foreman chooses an agent from the available list.
2.  It sets `remote` to run the child in the cloud.
3.  For each child, it supplies the selected agent’s UID in `agent_run_configs[].agent_identity_uid`.

The `name` field only labels the child run. Unless overridden, the run uses the selected agent’s environment, runner, host, harness, and model.

You can start child agents without factory configuration through [multi-agent orchestration](https://docs.warp.dev/platform/orchestration/) from any Warp conversation. For scheduled or event-driven work, use [factory automations](https://docs.warp.dev/factories/automations/). The foreman coordinates the work they start.

### Pass dynamic setup configuration

Select a `backend` or `frontend` setup profile through run metadata and read it in your setup script. Both profiles use the same implementation agent, runner, and environment.

1.  Save a script at `/opt/setup/select-profile.sh` in your image to validate the choice before configuring the workspace. This example calls your own installer at `/opt/setup/setup-profile.sh`. Replace that path with your installer; neither the script nor these profiles are built into Warp.
    
    ```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.  For setup performed per run, add `bash /opt/setup/select-profile.sh` to the agent’s [environment setup commands](https://docs.warp.dev/platform/environments/configuring-environments/). Warp-hosted and self-hosted runs receive metadata as environment variables before this setup and before the agent starts. The key `setup_profile` becomes `WARP_METADATA_SETUP_PROFILE`.
    
    Pre-warmed sandboxes perform their initial setup before a run is assigned, without that run’s metadata, and do not rerun those setup commands on assignment. If your agent uses pre-warming, keep shared preparation in setup instead. In the agent’s instructions, require `bash /opt/setup/select-profile.sh` as its first task action, before development, and require it to stop if initialization fails.
    
3.  In the foreman’s instructions, require it to choose a setup profile for each task and pass the choice in `agent_run_configs[].metadata`. For example:
    
    ```text
    Dispatch the configured implementation agent using its UID from the
    available-agent list. Set setup_profile to backend for service work
    or frontend for UI work. Pass it as per-child metadata in run_agents.
    Keep the agent's configured environment, runner, host, harness, and
    model unless the task independently requires an override.
    ```
    
    A `run_agents` call for backend work looks like this. Replace `IMPLEMENTATION_AGENT_UID` with the implementation agent’s UID from the available-agent list.
    
    ```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"
          }
        }
      ]
    }
    ```
    

Set `run_agents.metadata` for values shared by every child. Use `agent_run_configs[].metadata` to override a value for one child. Children inherit any parent metadata you haven’t overridden.

#### Requirements

-   Metadata keys and values must be strings. A run can have up to 20 keys, including inherited and automatically added keys.
-   Keys must be 1–64 bytes and contain only `A–Z`, `a–z`, `0–9`, `.`, `_`, or `-`. Values can be empty and must be at most 256 UTF-8 bytes, with no NUL characters.
-   To form environment-variable names, Warp adds `WARP_METADATA_`, uppercases the key, and replaces `.` and `-` with `_`. Keys that produce the same name are rejected. Don’t define `WARP_METADATA_*` variables in images, worker environments, or secrets.
-   Anyone who can view a run can read its metadata. Store credentials in [Agent Secrets](https://docs.warp.dev/platform/secrets/).
-   Local runs in the Warp app or a standalone CLI do not receive metadata environment variables.

## Related pages

-   [About factory agents](https://docs.warp.dev/factories/factory-agents/) - Understand default roles and human decision points
-   [Configuring factory agents](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/)