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.

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.

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.

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:

1
{
2
  message: string;       // everything the child needs; it never sees the parent's history
3
  outputSchema?: object; // when set, the child runs in task mode and returns structured output
4
}

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

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

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

• 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 workflows: 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.