From 8202f39361c66320c849df543fbe9b3537447326 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Thu, 10 Sep 2026 19:56:47 +0000 Subject: [PATCH] docs: clarify child agents vs. named factory agents Explain that multi-agent orchestration spawns ad hoc child agents from any conversation without a factory, that a child's role comes from the parent's prompt (or a skill), and that named agents with standing configuration are a Warp Factories feature dispatched by the foreman. Expand the custom-agents section on the factory agents page with an agent.md example and the skill vs. custom agent distinction, and add skills and subagents rows to the Claude Code migration table. Co-Authored-By: Warp Co-Authored-By: Oz --- src/content/docs/factories/factory-agents.mdx | 19 ++++++++++++++++++- src/content/docs/factories/index.mdx | 2 +- .../migrate-to-warp-from-claude-code.mdx | 2 ++ .../docs/platform/orchestration/index.mdx | 12 ++++++++++-- 4 files changed, 31 insertions(+), 4 deletions(-) diff --git a/src/content/docs/factories/factory-agents.mdx b/src/content/docs/factories/factory-agents.mdx index adb215661..604671f82 100644 --- a/src/content/docs/factories/factory-agents.mdx +++ b/src/content/docs/factories/factory-agents.mdx @@ -131,7 +131,24 @@ With a Warp-managed factory, you can edit harness, auth, and model from the dash ## Add custom agents and automations -Add custom agents for jobs the default agents don't handle, such as documentation, security analysis, migrations, or release checks. A custom agent doesn't have to be a required step for every work item. +Add custom agents for jobs the default agents don't handle, such as documentation, security analysis, migrations, or release checks. A custom agent is a named agent with its own instructions, model, harness, secrets, and MCP servers. The foreman dispatches it by name when a work item calls for it, so it doesn't have to be a required step for every work item. + +On a Warp-managed factory, add one from the **Agents** page in the [factory dashboard](/factories/factory-dashboard/): click **New**, then **Custom agent**. On a GitHub-backed factory, add an `agents//agent.md` file, where the frontmatter holds the configuration and the Markdown body holds the instructions: + +```markdown title="agents/docs-writer/agent.md" +--- +description: Updates user-facing docs when a change affects documented behavior +agentType: CUSTOM +model: auto +--- + +Read the pull request the foreman hands you and update the affected pages +under `docs/`. Push your changes to the same branch; never merge. +``` + +Custom agents have no built-in skills. Add the procedures a custom agent needs as [factory skills](/factories/factory-skills/), under `agents//skills/` when only that agent should use them. If the job is a procedure an existing agent should follow rather than a separate role, a skill on that agent is enough: a skill changes what an agent knows how to do, while a custom agent has its own configuration and its own runs. For every frontmatter key, see the [`agent.md` reference](/factories/factory-as-code/#agentsnameagentmd). + +Factory agents run in the cloud as part of a work item. To spawn ad hoc child agents from any Warp conversation, no factory required, see [multi-agent orchestration](/platform/orchestration/). Automations start a chosen agent on a [schedule](/factories/factory-as-code/#triggersschedule) or when an event fires. They're one more way for work to enter your factory; the foreman still coordinates whatever they start. For all the ways to route work into a factory, see [connect your factory](/factories/connect-your-factory/). diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 67f74eaaa..153f5c4d6 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -75,7 +75,7 @@ Warp Factories is built on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overv The factory layer adds the workflow on top: the foreman and its agents, work items that carry each request across runs, definitions as code, default automations for connected tools, and the Scorer and Self-improvement loop. -A standalone [cloud agent](/platform/) remains the right tool for a single task or a one-trigger automation. Reach for a factory when the work is a standing, multi-stage process your team wants to route, measure, and improve in one place. +A standalone [cloud agent](/platform/) remains the right tool for a single task or a one-trigger automation, and any agent can spawn child agents with [multi-agent orchestration](/platform/orchestration/), no factory required. Reach for a factory when the work is a standing, multi-stage process your team wants to route, measure, and improve in one place, run by named agents that each keep their own instructions, model, harness, secrets, and MCP servers. ## Key terms diff --git a/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx b/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx index 874c72340..ddb9485f1 100644 --- a/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx +++ b/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx @@ -87,6 +87,8 @@ Use this table to find the closest Warp equivalent for Claude Code concepts: | `CLAUDE.md` | `AGENTS.md` (or `WARP.md`) at the project root, picked up as a [Rule](/agents/capabilities/rules/) | | Claude Code slash commands | Warp's own [slash commands](/agents/capabilities/slash-commands/) (`/init`, `/plan`, `/model`, etc.); save your own as [Warp Drive prompts](/knowledge-and-collaboration/warp-drive/prompts/) | | Tool definitions | [MCP](/agents/capabilities/mcp/) | +| Skills (`.claude/skills/`) | [Skills](/agents/capabilities/skills/); Warp discovers `.claude/skills/` as-is, alongside `.agents/skills/` and the other supported directories | +| Subagents (`.claude/agents/`) | [Multi-agent orchestration](/platform/orchestration/) spawns child agents from any conversation; move each subagent's prompt into a skill and ask the parent to have the child use it. For named agents with standing configuration, see [factory agents](/factories/factory-agents/) | | Resume conversation | Warp persists agent conversations per tab; pair with [tab configs](/terminal/windows/tab-configs/) to reopen the same project layout | For a deeper tour of Agent Mode, see [Coding in Warp](/getting-started/quickstart/coding-in-warp/) and the [Agents overview](/agents/). diff --git a/src/content/docs/platform/orchestration/index.mdx b/src/content/docs/platform/orchestration/index.mdx index 47bb61306..9d4ff4172 100644 --- a/src/content/docs/platform/orchestration/index.mdx +++ b/src/content/docs/platform/orchestration/index.mdx @@ -13,7 +13,7 @@ Watch this walkthrough to see how a cloud agent can coordinate a team of agents -This page covers the orchestration model and the patterns it supports. To learn how to start an orchestrated run, see [Running orchestrated agents](/platform/orchestration/multi-agent-runs/). +To start an orchestrated run, see [Running orchestrated agents](/platform/orchestration/multi-agent-runs/). To orchestrate work inside a [Warp factory](/factories/), dispatch through the [factory API](/factories/factory-api/) instead of calling `POST /agent/runs` with the foreman's `agent_identity_uid` directly. The server resolves the foreman for you, and everything on this page still applies to the run it starts. @@ -37,6 +37,14 @@ The parent and child don't have to run in the same place. Orchestration supports Children can also run with a different agent runtime than the parent. A parent running with the default Warp Agent can spawn children that run with [Claude Code](/agents/cli-agents/claude-code/) or [Codex](/agents/cli-agents/codex/), and vice versa. +### How a child agent is configured + +A child agent has no definition file of its own: its prompt comes from the parent at spawn time, and the run-wide settings you approve (model, harness, and where the children run) apply to every child in the batch. + +To give a child a reusable role, put the role's instructions in a [skill](/agents/capabilities/skills/) and ask the parent to have the child use it, for example "spawn one child per package and have each one use the `migrate-tests` skill." A local child starts in the parent's working directory, so it discovers the same repository and home-directory skills as the parent. For a cloud child, the parent attaches the skill when it spawns the child, from a repository in the child's [environment](/platform/environments/). + +Named agents with their own standing configuration (instructions, model, harness, secrets, and MCP servers) are part of [Warp Factories](/factories/): a factory's foreman dispatches its [factory agents](/factories/factory-agents/) by name. Outside a factory, every child runs as the user or cloud agent that started the parent. + ## Run state transitions Each run progresses through a small set of states. The parent observes these transitions to decide what to do next - keep waiting, send a follow-up, spawn a replacement, or finish. @@ -99,7 +107,7 @@ The parent encodes a directed acyclic graph of subtasks where some nodes depend ### Swarm -A flat group of peer agents discover each other through messaging and coordinate without a strict hierarchy. The parent acts more like a coordinator than a supervisor. Use sparingly - swarms are powerful but harder to debug than hierarchical patterns. +A flat group of peer agents discover each other through messaging and coordinate without a strict hierarchy. The parent acts more like a coordinator than a supervisor. Use sparingly - swarms are harder to debug than hierarchical patterns. ## Approval mode