Factories > Factory agents

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

Team or workspace admin access, or the team-level Warp Factories Editor role.
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.

In the web app sidebar, click your factory to expand it, then click Agents.
Click New, then Custom agent.
Enter an agent name and a description of its responsibilities.
Under “Agent resources”, choose its harness, model, host, and runner as needed. Add MCP servers and secrets for the tools it needs. See Configuring factory agents for configuration and authentication details.
Under “Agent prompt”, enter the agent’s instructions.
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.

Create an agent in definition files

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/

Choose a configured factory agent

The foreman uses run_agents to dispatch configured factory agents. It receives a list of available agents and their unique IDs (UIDs). The call selects the agent as follows:

Choose an agent from the provided list.
Set remote to run the child in the cloud.
Set agent_run_configs[].agent_identity_uid to the chosen UID for every child in the call.

The name field labels the child run; it does not select the agent. Warp loads the selected agent’s environment, runner, host, harness, and model unless the call overrides them.

To start a child without factory configuration, use multi-agent orchestration from any Warp conversation. To start an agent on a schedule or when an event fires, configure a factory automation. The foreman coordinates work started by automations.

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