Subagents

Purpose and Scope

Subagents are eve’s delegation mechanism for breaking one agent turn into focused child-agent work. A parent agent can hand a specific task to a child when the work should run independently, use a narrower prompt or tool surface, or be handled by a specialist identity. The concept is intentionally filesystem-first: the default delegation path is available automatically, while specialist subagents are declared by placing a full agent definition under a conventional directory. This page explains the two forms, their isolation boundaries, and the practical design choices that matter when you add delegated work to an eve project.

Sources: docs/subagents.mdx

The most important distinction is between the built-in agent tool and a declared subagent. The built-in tool creates a copy of the current agent, so it is best for parallelizing small, independent subtasks without authoring another agent directory. A declared subagent is a separate specialist under agent/subagents/<id>/, with its own configuration and authored slots. Use that form when the child should have a different role, prompt, sandbox, tools, skills, hooks, connections, or nested subagents from the parent.

Sources: docs/subagents.mdx

Relevant Source Files

• docs/subagents.mdx — Defines the public documentation contract for subagents, including the built-in agent tool, declared subagent layout, required description, isolation behavior, unsupported schedules, and delegation guidance.

Core Primitives

The built-in agent tool is available to every agent by default. The model calls it with a message, which must contain everything the child needs, because the child starts with fresh conversation history rather than seeing the parent’s prior messages. The tool also accepts an optional outputSchema; when present, the child runs in task mode and returns structured output. This makes the built-in tool useful for fan-out patterns such as asking several copied agents to inspect separate files, gather independent facts, or produce typed partial results that the parent can combine.

Sources: docs/subagents.mdx

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

A copied child shares the parent’s sandbox and tools. File writes made by the child are immediately visible to the parent, which is powerful but requires coordination. When a parent emits multiple agent calls in one response, eve runs that batch concurrently and returns every result before the parent continues. That concurrency model is intended for a small, fixed set of independent subtasks. Give copied children non-overlapping write scopes when they share a sandbox, because concurrent work that writes the same files can create avoidable conflicts or ambiguous results.

Sources: docs/subagents.mdx

The copy also inherits auth and connections, but it does not inherit conversation state. That boundary means delegation is explicit: the parent transfers data only through the message input. Do not include sensitive information in a subagent request unless the child’s inherited tools, connections, sandbox, and telemetry path are appropriate for that data. If the parent itself is a declared subagent and it calls agent, the child is a copy of that declared subagent, not a copy of the root agent. An authored tool at agent/tools/agent.ts takes priority over the built-in name.

Sources: docs/subagents.mdx

Declared Subagents

A declared subagent lives at agent/subagents/<id>/ and uses the same defineAgent helper as the root agent. Its location under subagents/ is what marks it as a subagent. The subagent’s agent.ts must export a description, because the parent reads that description to decide whether delegation is appropriate. The compiler rejects a declared subagent whose agent.ts omits the description, so treat the description as a routing contract rather than only documentation for humans.

Sources: docs/subagents.mdx

// 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 minimum declared subagent directory contains agent.ts, with optional slots alongside it. A specialist can provide its own instructions.md or instructions.ts, its own tools/, skills/, sandbox/, and nested subagents/. The source documentation explicitly excludes schedules/ inside declared subagents; schedules are root-only. That restriction keeps recurring work anchored at the root agent while still allowing delegated execution to be composed inside the root’s runtime behavior.

Sources: docs/subagents.mdx

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

Isolation Boundary

Declared subagents are not just named copies of the root. Discovery treats the declared subagent directory as its own agent root, so the child has only the authored slots that live under agent/subagents/<id>/. If a slot is absent, eve falls back to the framework default rather than to the root agent’s version. This applies to instructions, tools, connections, skills, sandbox, hooks, and nested subagents. The result is a clear specialist boundary: adding a tool to the root does not silently expand a declared specialist’s capabilities.

Sources: docs/subagents.mdx

This boundary should guide how you choose between the two forms. Use the built-in agent tool when the child should behave like the current agent and only needs a fresh state plus an explicit task message. Use a declared subagent when the delegation target should be constrained or specialized. For example, a researcher subagent might have investigation instructions and read-only tools, while a writer subagent might have formatting skills and a different model. Those differences belong in their own subagent directories, not in conditional logic inside a single root prompt.

Sources: docs/subagents.mdx

Delegation Flow

A safe delegation flow begins with the parent deciding what information the child needs, then packaging that information in the message input. Because the child does not see the parent’s history, vague requests such as “continue the investigation” are poor delegation messages. Prefer self-contained messages that name the objective, constraints, expected output, and any relevant data. If the parent expects a typed response, pass an outputSchema so the child runs in task mode and returns structured output that the parent can merge, validate, or present to the user.

Sources: docs/subagents.mdx

For parallel work, the parent can emit multiple built-in agent tool calls in one model response. eve executes that batch concurrently and returns the full set of results before resuming the parent. This is a good fit for bounded fan-out: compare three approaches, inspect several independent inputs, or generate multiple candidate analyses. It is not a replacement for unlimited background job orchestration. Keep the set small and fixed, and avoid shared write targets when the copied children use the same sandbox.

Sources: docs/subagents.mdx

Compact Reference

Next Steps

When adding subagents, start by writing down the delegation reason: parallelism, narrower capability, or specialist identity. If the answer is only parallelism and the child can safely share the current sandbox and tools, use the built-in agent tool and craft explicit messages. If the answer involves a different role, prompt, tool surface, sandbox, or nested specialists, create agent/subagents/<id>/agent.ts with a clear description, then add only the slots that specialist needs. After implementation, review related pages on tools and approvals, sandboxing, dynamic capabilities, and sessions so delegated work fits the broader runtime model.