Creating custom agents

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.
• An existing factory. Follow the Warp 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. For a GitHub-backed factory, use definition files 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 as needed. Add MCP servers and 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. Follow your repository’s pull request process to apply the change.

Add skills

Custom agents have no built-in skills. Add 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 from any Warp conversation. For scheduled or event-driven work, use factory 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 select a backend or frontend setup profile for 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/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.

   /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. 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:

   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.

   {
     "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"
         }
       }
     ]
   }

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 for credentials. Local runs in the Warp app or a standalone CLI do not receive this environment-variable injection.

Related pages

• About factory agents - Understand default roles and human decision points
• Configuring factory agents - Edit instructions, models, harnesses, and tools
• Factory skills
• Factory automations
• Definitions as code