--- title: How to use subagents with eve description: Learn how to use subagents with eve, including the built-in agent tool, declared specialist subagents, the isolation boundary, when to split work into a subagent, and how to verify delegation. url: "https://vercel.com/kb/guide/how-to-use-eve-subagents" published: 2026-06-19 last_updated: 2026-09-30 authors: Ben Sabic related_resources: - title: "How to classify, route, and score with Jev and AI SDK" url: "https://vercel.com/kb/guide/typesafe-jev-and-ai-sdk" description: "Use Jev from TypeSafe AI with AI SDK's experimental evaluate API to classify, route, score, and verify inside your application. Jev returns typed choices, scores, and boolean probabilities through AI Gateway." - title: "How to automatically approve tool calls in eve with Jev" url: "https://vercel.com/kb/guide/auto-approve-tool-calls-eve-jev" description: "Use Jev to review tool calls in eve, allow routine actions, and request human approval when needed. Configure the policy and test its failure paths." install_vercel_plugin: npx plugins add vercel/vercel-plugin --- 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: ### Agent prompt ```txt I want to use subagents with my eve agent. Use this guide as your reference: https://vercel.com/kb/guide/how-to-use-eve-subagents. First, a check: a subagent is a separate worker with its own context and fresh history, not extra instructions for the agent that's already running. If I only need to give the current agent an optional procedure while it keeps its identity, that's a skill rather than a subagent, so tell me and point me to the skills guide (/kb/guide/how-to-add-eve-skills). Before setting anything up, ask me about the work I want to hand off. Find out: - The subtask the child should handle - When you should delegate it, so we can write a description that routes to it - Whether the child needs a different prompt or specialist role, or a different set of tools than you have, which decides the kind of subagent that fits - Whether several units of this work can run at once, like fixing many files or summarizing many documents - Whether the parent needs structured data back, or prose is fine Use my answers to pick the kind: - If the child can share your identity and tools and only needs its own isolated run, you already have the built-in `agent` tool. It delegates to a copy of you that shares your sandbox and tools but starts with fresh history and state, which makes fanning out parallel copies natural. There's nothing to author, so just explain how you'll call it. - If the child needs its own prompt, a specialist role, or a narrower set of tools, declare a specialist subagent. For structured output, open a child session from an authored workflow tool using ctx.agent(name), and pass outputSchema to the session’s send() method. Await response.result() and read the returned object’s data field. To declare a specialist, follow these conventions: - Put it under `agent/subagents//` and define it with `defineAgent` from `eve`. The directory name becomes the tool the parent calls, so `agent/subagents/researcher/` is delegated to as `researcher`. Keep that name distinct from any of your tools, since they share one namespace and a clash fails the build. - Give it a `description`. It's required, and the parent reads it to decide when to delegate, so eve fails the build without it. - A single `agent.ts` is enough, or add `instructions.{md,ts}`, `tools/`, `skills/`, or `sandbox/` siblings when the child needs them. - A declared subagent inherits nothing from the root, so give it its own instructions, tools, and skills, and hand it only the tools it should touch. An absent slot falls back to the framework default, not your root's version, so duplicate what it needs: copy a procedure into its `skills/`, or share typed helpers through `lib/`. Delegation isn't an approval boundary on its own. Keep sensitive tools behind `approval`, connection approval, or route and session auth wherever they can be called, whether or not a subagent is the caller. When it's ready, tell me how to test it: start the dev server with `eve dev`, send a request that should match the subagent's description (or name it directly), then open Agent Runs in the Vercel dashboard to confirm the delegation ran. If any of my requirements are unclear, ask before you set anything up rather than guessing. ``` ## 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 `taskId`. The child never sees the parent's conversation history, so the parent packs all the context it wants the child to have into `message`. The root session receives the built-in `agent` tool by default. Root-agent copies and declared subagents do not receive it. 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. A subagent call returns a task receipt immediately. The child works while the parent continues, and the final reply arrives as the task result. Pass the same `taskId` with a new message to continue that child’s conversation. Each delegated subagent runs in its own child session with its own stream. The parent stream reports `task.started` and `task.settled` for delegation calls, and `agent.started` when a child session opens. The `task.settled` event carries the child’s final output or error. ## Delegate to a copy with the built-in `agent` tool The root session receives an `agent` tool by default. The model calls it to start or continue a copy of the root agent. The copy shares the root’s sandbox, instructions, auth, and connections, and inherits its tools except those restricted to root sessions. File writes are immediately visible to the root. A new copy starts with fresh conversation history and state; continuing it with `taskId` preserves its conversation. Multiple copies can work in parallel, so give them non-overlapping file write scopes. The model passes the child everything it needs through the `message` input: ```typescript { message: string; // everything the child needs; it never sees the parent's history taskId?: string; // continue an existing child } ``` 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. Declared subagents do not receive the built-in `agent` tool, but they can delegate to nested subagents authored under their own directories. ## 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`: ```typescript 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: ```plaintext 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 except root-only tools | 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.** For structured output, open a child session from an authored workflow tool using `ctx.agent(name)`, and pass `outputSchema` to the session’s `send()` method. Read the structured value from `(await response.result()).data` . Don't rely on delegation by itself as an approval boundary. Put sensitive tools behind `approval`, 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 inspect delegation, timing, and token usage, open Agent Runs in the Vercel dashboard. To follow a child’s progress from your client, pass the parent stream’s `agent.started` event to `session.agent(started)` and read the child handle’s `stream()`. The client uses the event’s `streamPath` to follow local and remote children. ## 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. Use Jev to review tool calls in eve, allow routine actions, and request human approval when needed. Configure the policy and test its failure paths. [How to automatically approve tool calls in eve with Jev](/kb/guide/auto-approve-tool-calls-eve-jev) * * * ## Learn more about building with eve [**Add skills to your eve agent.**Write your own under agent/skills/, install published ones, or resolve a different one per caller.](https://vercel.com/kb/guide/how-to-add-eve-skills)[**Add tools to your eve agent.**Define each one in TypeScript under agent/tools/, and gate the sensitive ones on human approval.](https://vercel.com/kb/guide/how-to-add-eve-tools) ## Related Resources - [How to classify, route, and score with Jev and AI SDK](https://vercel.com/kb/guide/typesafe-jev-and-ai-sdk): Use Jev from TypeSafe AI with AI SDK's experimental evaluate API to classify, route, score, and verify inside your application. Jev returns typed choices, scores, and boolean probabilities through AI Gateway. - [How to automatically approve tool calls in eve with Jev](https://vercel.com/kb/guide/auto-approve-tool-calls-eve-jev): Use Jev to review tool calls in eve, allow routine actions, and request human approval when needed. Configure the policy and test its failure paths. ## More eve guides - [How to use Vercel Drives with an eve agent](/kb/guide/vercel-drives-eve-agent): Mount Vercel Drives in an eve agent's sandbox to give each user a persistent workspace and share read-only reference data across sessions. - [How to build a custom eve memory provider](/kb/guide/build-a-custom-eve-memory-provider): Implement the eve memory provider contract with defineMemoryProvider() to back an eve memory slot with your own database, vector index, or memory service. - [How to choose an eve memory provider](/kb/guide/choose-an-eve-memory-provider): Compare File memory, Supermemory, Upstash AgentKit, and Kybernesis Arcana by recall, capture, and storage to choose an eve memory provider for your agent.