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

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.

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

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.

Metadata limits and behavior

• 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.
• Local runs in the Warp app or a standalone CLI do not receive metadata environment variables.

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