How to use subagents with eve

Subagents let an 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, 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.

Copy link to headingPrerequisites

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.

Copy link to headingQuick 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:

Copy link to headingHow 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.

Copy link to headingDelegate 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:

{
  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.

Copy link to headingDeclare 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/<id>/ 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/<id>/. 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.

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.

Copy link to headingWhen 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 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.

Copy link to headingVerify 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.

Copy link to headingResources and next steps

• Subagents in eve: both kinds of subagent, the isolation boundary, and what the parent sees.
• agent.ts configuration: defineAgent, the model field, and the description requirement.
• Remote agents: call another eve deployment as a subagent.
• Dynamic capabilities: have the model orchestrate its subagents programmatically, including fan-out and map-reduce.
• Skills in eve: add an on-demand procedure when a separate agent would be more than you need.

Copy link to headingLearn more about building with eve