Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vercel/eve/llms.txt

Use this file to discover all available pages before exploring further.

A subagent is a child agent that one agent delegates a focused subtask to. Split work into a subagent to run it in parallel, to give the child a narrower tool surface, or to give a specialist its own identity and instructions. There are two kinds: the built-in agent tool (a copy of the agent itself), and declared subagents (specialists with their own directory under agent/subagents/).

​
The built-in agent tool

Every agent gets an agent tool by default. The model calls it to delegate a subtask to a copy of itself. The copy shares the parent’s sandbox and tools, and its file writes are immediately visible to the parent — which makes parallel fan-out natural: 
// The model invokes the built-in agent tool with this shape:
{
  message: string;       // everything the child needs; it does not see the parent's history
  outputSchema?: object; // when set, the child runs in task mode and returns structured output
}
The copy inherits auth and connections, but starts with fresh conversation history and fresh durable state. If a declared subagent calls agent, the child is a copy of that subagent, not the root.
An authored tool at agent/tools/agent.ts takes priority over the built-in agent tool.

​
Declared subagents

A declared subagent lives under agent/subagents/<id>/ and uses the same defineAgent helper as the root. Its location under subagents/ is the only thing that marks it as a subagent. Declare one when the child needs a clearly different prompt, role, or tool surface.
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",
});
description is required on every declared subagent. The parent reads it to decide whether to delegate, so the compiler rejects any subagent agent.ts that omits it.

​
Minimum file structure

agent/subagents/researcher/
├── agent.ts            # required (must export a description)
├── instructions.md     # optional
├── tools/              # optional, its own tools
├── skills/             # optional, its own skills
├── sandbox/            # optional, its own sandbox + workspace seed
└── subagents/          # optional, nested subagents
schedules/ and channels/ are not supported inside declared subagents — those are root-only.

​
The isolation boundary

A declared subagent inherits nothing from the root’s authored slots. Discovery treats its directory as its own agent root. An absent slot falls back to the framework default, not to the root’s version.
SlotBuilt-in agent toolDeclared subagent
InstructionsInherited (copy of the agent)Own instructions.{md,ts}, optional
ToolsInheritedOwn tools/
ConnectionsInheritedOwn connections/
SkillsInheritedOwn skills/
SandboxShared with parentOwn sandbox/, else framework default
HooksInheritedOwn hooks/
StateFreshFresh
ChannelsRoot-onlyRoot-only
SchedulesRoot-onlyRoot-only
For a declared subagent this means duplicating anything the child needs. When two subagents need the same procedure, copy the markdown under each skills/ directory, or share typed helpers via lib/. defineState is never shared — each child starts with fresh durable state.

​
What the parent sees

eve lowers every subagent into a model-visible tool with the { message, outputSchema? } input shape. A declared subagent’s tool name is the bare path-derived name, with no prefix. agent/subagents/researcher/ registers as the tool researcher. The parent packs message with everything the child needs, since the child never sees the parent’s history. Set outputSchema to run the child in task mode, returning structured output as the tool result:
agent/subagents/researcher/agent.ts
import { defineAgent } from "eve";
import { z } from "zod";

export default defineAgent({
  description: "Research a topic and return a structured summary.",
  model: "anthropic/claude-opus-4.8",
  outputSchema: z.object({
    summary: z.string(),
    sources: z.array(z.string()),
  }),
});
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.

​
Nested subagents

Subagents can have their own subagents. A nested subagent follows the same rules — its own directory, its own isolation boundary, its own agent.ts with a description: 
agent/subagents/
└── coordinator/
    ├── agent.ts
    ├── instructions.md
    └── subagents/
        └── specialist/
            ├── agent.ts
            └── tools/

​
Monitoring child sessions

Each delegated subagent spins up its own child session and stream. The parent stream carries only the control-plane events subagent.called and subagent.completed. To follow the child’s full progress, read subagent.called.data.childSessionId and subscribe at GET /eve/v1/session/:childSessionId/stream.

​
Remote agents

To call another eve deployment as a subagent, use defineRemoteAgent from 'eve':
agent/subagents/remote-researcher/agent.ts
import { defineRemoteAgent } from "eve";

export default defineRemoteAgent({
  description: "A remote research agent running on a separate deployment.",
  url: "https://researcher.example.com",
});
See the remote agents guide for authentication and routing details.

​
When to use a subagent vs a skill

Split out a subagent when the 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.
Do not rely on subagent delegation alone as an approval boundary. Put sensitive tools behind needsApproval, connection approval, route/session authorization, or other controls wherever those tools can be called.

​
Data handling

The parent transfers data to the child through the message input. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.

Build docs developers (and LLMs) love

Get started for freeTalk to us