# How to use subagents with eve **Author:** Ben Sabic --- Subagents let an [eve](https://vercel.com/eve) agent hand off a focused subtask to a child agent that runs in its own context. You can use one to run work in parallel, to give a child a narrower set of tools, or to give a specialist their own identity. eve offers two kinds. The built-in `agent` tool delegates to a copy of the agent itself, and declared subagents live in their own directory with their own prompt, tools, and skills. Unlike a [skill](https://vercel.com/kb/guide/how-to-add-eve-skills), which adds instructions to the agent that's already running, a subagent works as a separate agent with fresh conversation history and state. This guide walks you through delegating with the built-in `agent` tool, declaring a specialist subagent, and confirming that your agent delegates for the right requests. ## Prerequisites Before you begin, you need an eve project and Node.js installed. - To create a new project, run `npx eve@latest init my-agent`. - To add eve to an existing app, follow the [quickstart steps](https://eve.dev/docs/getting-started#quick-start). ## Quick start with an AI coding agent If you're using an AI coding agent like Claude Code or Cursor, give it this prompt, and it'll help you set up a subagent for your eve agent: ## How eve loads subagents eve turns every subagent into a tool the model can call, whether it's the built-in copy or one you declare, and each one takes the same input: a `message` with everything the child needs, plus an optional `outputSchema`. The child never sees the parent's conversation history, so the parent packs all the context it wants the child to have into `message`. Every agent starts with the built-in `agent` tool. eve discovers declared subagents under `agent/subagents/` at build time and advertises each one to the model by its `description`, so the model knows when to delegate tasks. When `outputSchema` is set, the child runs in task mode and returns structured output as the tool result; without it, the child replies in prose. Each delegated subagent runs in its own child session with its own stream, and the parent stream carries `subagent.called` and `subagent.completed` events so you can trace the handoff. ## Delegate to a copy with the built-in `agent` tool Every agent gets an `agent` tool by default, and the model calls it to delegate a subtask to a copy of itself. The copy shares the parent's sandbox and tools, so anything it writes to a file is immediately visible to the parent. That shared workspace makes parallel delegation natural, since the model can fan out several copies to fix different files at once and then collect the results. Each copy inherits the parent's auth and connections, but starts with a fresh conversation history and a fresh state. The model passes the child everything it needs through the `message` input: `{ message: string; // everything the child needs; it never sees the parent's history outputSchema?: object; // when set, the child runs in task mode and returns structured output }` The model composes `message` at runtime, so the parent, not you, decides what the copy receives. Because the copy shares the parent's tools, connections, sandbox, and telemetry path, apply the same care to anything the parent delegates as you would to the data the parent handles itself. If a declared subagent calls `agent`, the child is a copy of that subagent, not the root. You can also replace the built-in tool, since an authored tool at `agent/tools/agent.ts` takes priority over it. ## Declare a specialist subagent Declare a subagent when the child needs a different prompt, a specialist role, or its own set of tools. Declared subagents live under `agent/subagents//` and use the same `defineAgent` helper as the root agent. Its location under `subagents/` is the only thing that marks it as a subagent. Create `agent/subagents/researcher/agent.ts`: `import { defineAgent } from "eve"; export default defineAgent({ description: "Investigate ambiguous questions before the parent agent responds.", model: "anthropic/claude-opus-4.8", });` The `description` is required. The parent reads it to decide whether to delegate a task, so eve rejects the build if a subagent's `agent.ts` leaves it out. A subagent can be a single `agent.ts`, or a directory with its own instructions, tools, skills, and sandbox alongside it: `agent/subagents/researcher/ ├── agent.ts # required (must export a description) ├── instructions.md # or instructions.ts, optional ├── tools/ # optional, its own tools ├── skills/ # optional, its own skills ├── sandbox/ # optional, its own sandbox + workspace seed └── subagents/ # optional, nested subagents` Schedules aren't supported inside a declared subagent; they're root-only. eve registers a declared subagent under its path-derived name with no namespace, so `agent/subagents/researcher/` becomes a tool the model calls as `researcher`. That name shares the same namespace as your authored tools, so a subagent named `researcher` collides with a tool named `researcher`. eve rejects the build rather than picking a winner, so keep subagent directory names distinct from tool names. The declared subagent inherits nothing from the root's authored slots. eve treats its directory as its own agent root, so the child has only the instructions, tools, connections, skills, sandbox, hooks, and nested subagents authored under `agent/subagents//`. When a slot is absent, it falls back to the framework default, not to the root's version. The built-in `agent` tool is the exception, because its copies share the parent's sandbox and tools while they work on the same files. | Slot | Built-in `agent` tool | Declared subagent | | ------------ | ----------------------------- | -------------------------------------- | | Instructions | Inherited (copy of the agent) | Own `instructions.{md,ts}`, optional | | Tools | Inherited | Own `tools/` | | Connections | Inherited | Own `connections/` | | Skills | Inherited | Own `skills/` | | Sandbox | Shared with parent | Own `sandbox/`, else framework default | | Hooks | Inherited | Own `hooks/` | | State | Fresh | Fresh | | Channels | Root-only | Root-only | | Schedules | Root-only | Root-only | In practice, a declared subagent duplicates anything it needs. When two subagents rely on the same procedure, copy the markdown into each `skills/` directory, or share typed helpers through `lib/`. Durable state from `defineState` is never shared for either kind, so every child starts fresh. ## When to use a subagent Reach for a subagent when a task needs a different prompt or specialist role, a narrower tool surface, or its own runtime context. If the agent can keep its identity and only needs an optional procedure, a [skill](https://eve.dev/docs/skills) is the lighter choice. Prefer a skill for guidance, and a subagent for a genuinely separate worker. Common reasons to split out a subagent: - **Run work in parallel.** Fan out copies of the built-in `agent` tool to handle independent units at once, such as fixing several files or summarizing many documents, then combine what each one returns. This is the map step of a map-reduce, with the parent doing the reduce. - **Restrict the tool surface.** Give a child only the tools they should touch. A subagent that drafts release notes doesn't need your deployment or refund tools, and leaving them out removes the chance of calling them. - **Give a specialist their own identity.** A research subagent with its own instructions and model can investigate an ambiguous question before the parent answers, without the parent's prompt pulling it off task. - **Return structured output.** Set `outputSchema` so the child runs in task mode and hands back typed data the parent can act on, instead of prose the parent has to parse. Don't rely on delegation by itself as an approval boundary. Put sensitive tools behind `needsApproval`, connection approval, or route and session authorization wherever those tools can be called, whether or not a subagent is the one calling them. ## Verify the subagent runs Start your agent and send a request that matches a subagent's description, or name the subagent directly. The init command starts the dev server for you when you scaffold a project; otherwise, use `eve dev`. When a request matches, the model delegates the work. The built-in agent tool runs a copy of the agent, and a declared subagent runs as a separate child that the parent calls by name. To see which subagents ran, along with timing and token usage, open [Agent Runs](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fobservability%2Fagent-runs) in the Vercel dashboard. Each delegation starts its own child session, so to follow a child's full progress, read `subagent.called.data.childSessionId` from the parent stream and subscribe at `GET /eve/v1/session/:childSessionId/stream`. ## Resources and next steps - [Subagents in eve](https://eve.dev/docs/subagents): both kinds of subagent, the isolation boundary, and what the parent sees. - [agent.ts configuration](https://eve.dev/docs/agent-config): `defineAgent`, the model field, and the `description` requirement. - [Remote agents](https://eve.dev/docs/guides/remote-agents): call another eve deployment as a subagent. - [Dynamic capabilities](https://eve.dev/docs/guides/dynamic-capabilities): have the model orchestrate its subagents programmatically, including fan-out and map-reduce. - [Skills in eve](https://eve.dev/docs/skills): add an on-demand procedure when a separate agent would be more than you need. * * * ## Learn more about building with eve --- [View full KB sitemap](/kb/sitemap.md)