> 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

Use run metadata to pass task-specific initialization choices to an existing agent. For example, let the foreman pass `java-dev` or `trading-analytics` to the same implementation agent without creating separate runners, environments, or agents. Metadata supplies the choice; your setup script must act on it.

1.  Save a script at `/opt/company/select-bundle.sh` in your image to validate the choice before configuring the workspace. This example calls your own bundle installer at `/opt/company/setup-bundle.sh`. Replace that path with your installer; neither the script nor these bundles are built into Warp.
    
    ```bash title="/opt/company/select-bundle.sh"
    bundle="${WARP_METADATA_IMC_BUNDLE:-}"
    case "$bundle" in
      java-dev|trading-analytics)
        bash /opt/company/setup-bundle.sh "$bundle"
        ;;
      "")
        printf '%s\n' 'Missing WARP_METADATA_IMC_BUNDLE' >&2
        exit 1
        ;;
      *)
        printf '%s\n' 'Unsupported bundle; expected java-dev or trading-analytics' >&2
        exit 1
        ;;
    esac
    ```
    
2.  For setup performed per run, add `bash /opt/company/select-bundle.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 `imc_bundle` becomes `WARP_METADATA_IMC_BUNDLE`.
    
    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/company/select-bundle.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 bundle 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. Choose imc_bundle: java-dev for Java development,
    or trading-analytics for analytics 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 Java work looks like this. Replace `IMPLEMENTATION_AGENT_UID` with the implementation agent’s UID from the available-agent list.
    
    ```json
    {
      "summary": "Delegate Java work to the configured implementation agent",
      "base_prompt": "Implement the task and verify the change.",
      "remote": {},
      "agent_run_configs": [
        {
          "name": "java-implementation",
          "agent_identity_uid": "IMPLEMENTATION_AGENT_UID",
          "prompt": "Fix the Java service's failing tests.",
          "metadata": {
            "imc_bundle": "java-dev"
          }
        }
      ]
    }
    ```
    

Top-level `run_agents.metadata` supplies defaults for the batch; per-child values override matching keys. These explicit values override inherited parent metadata per key, leaving other inherited keys intact.

Keep metadata small and non-secret:

-   **Format and bounds** - Use a map of strings, not nested JSON or typed values. Each run’s effective map, including inherited and automatically supplied keys, permits at most 20 keys. Keys must be 1–64 bytes and contain only `A–Z`, `a–z`, `0–9`, `.`, `_`, or `-`. Values must be 0–256 bytes of UTF-8 without NUL characters.
-   **Environment names** - Warp uppercases keys and replaces `.` and `-` with `_` after the `WARP_METADATA_` prefix. Keys that produce the same environment name are rejected. Reserve this namespace: don’t define it in images, worker environment variables, or secrets.
-   **Secrets and local runs** - Metadata is visible to anyone who can view the run. Use [Agent Secrets](https://docs.warp.dev/platform/secrets/) for credentials. Local runs in the Warp app or a standalone CLI do not receive this environment-variable injection.

## 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/)