Subagents

eve supports two ways to delegate work: the root-only built-in agent tool, which runs a fresh copy of the root agent, and declared subagents, which are specialists with their own directories. Use a subagent to run independent work in parallel, narrow the available tools, or give a task to a specialist.

The built-in agent tool

The root session receives agent by default. The model calls it to delegate a task to a fresh copy of the root agent:

{
  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 uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only agent and Workflow, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. To run independent tasks in parallel, emit multiple agent calls in one response; eve runs the batch concurrently and returns every result before the root continues. Give parallel children non-overlapping write scopes.

agent is intentionally root-only. Copies created by it cannot call agent, and declared subagents never receive the built-in tool. If a stale or forced recursive call reaches execution, eve rejects it instead of starting another child session.

The parent transfers data to the child through the message input it gives the subagent. 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.

An authored root tool at agent/tools/agent.ts takes priority over the built-in.

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.

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. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose agent.ts leaves it out.

Minimum files:

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/ is not supported inside a declared subagent. Schedules 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, so it has only the instructions, tools, connections, skills, sandbox, hooks, and nested subagents authored under agent/subagents/<id>/. An absent slot falls back to the framework default, not to the root's version.

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/. The sandbox does not inherit from the parent; it falls back to the framework default unless the subagent authors subagents/<id>/sandbox.ts or seeds files via subagents/<id>/sandbox/workspace/.

The root built-in agent tool is the exception. Its children share the root's sandbox and tools because they are copies of the same agent working on the same files.

defineState is never shared, for either kind. Each child starts with fresh durable state.

What the parent sees

eve lowers every subagent visible to the current agent (the root built-in copy, declared, or remote) into a model-visible tool with the same { message, outputSchema? } shape. 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.

Declared subagents can call nested subagents defined under their own directories. eve does not apply a separate depth limit; nesting ends where the authored directory tree ends. The built-in agent follows the stricter root-only rule above, so limits.maxSubagentDepth no longer exists.

Workflow is also root-only. Child sessions can still call their own declared or remote subagents, but they receive neither Workflow nor the built-in agent. The Workflow tool's maxSubagents option caps the number of calls made by one program (default 100); see Dynamic workflows.

A declared subagent's tool name is the bare path-derived name, with no prefix. agent/subagents/researcher/ registers as the tool researcher. Unlike connection tools (<connection>__<tool>), it carries no namespace, so the model, approvals, logs, and evals all reference it by that name. Its input schema is:

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

Because the name lives in the same runtime tool namespace as authored tools, 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.

Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind approval, connection approval, route/session authorization, or other controls wherever those tools can be called.

Each delegated subagent spins up its own child session and stream. The parent stream carries the control-plane events subagent.called and subagent.completed, plus interactive input.requested, authorization.required, and authorization.completed events proxied from descendants so the root channel can prompt the user. To follow the child's other progress, read subagent.called.data.childSessionId and subscribe at GET /eve/v1/session/:childSessionId/stream.

Subagent model calls automatically retry classified transient provider failures, including overload errors delivered after a stream starts. eve makes at most three fresh model-call attempts, repeating only the current uncommitted call so completed earlier steps, tool results, and sandbox work remain available to the child. Other recoverable task errors fall back to Workflow's durable step retry from the last committed session snapshot. Exhausting the transient model-call attempts or the dedicated empty-response reissue returns one failed task result instead of stacking both retry budgets; terminal errors fail immediately.

When to split

Split out a subagent when the task needs a different prompt or specialist role, a narrower tool surface, or its own runtime context. Don't reach for one when a skill would do. If the agent can keep its identity and needs only an optional procedure, a skill is the lighter choice.

What to read next

• Remote agents: call another eve deployment as a subagent.
• Dynamic workflows: have the model orchestrate its subagents programmatically (fan-out, map-reduce).