Ch10. Subagents, Workflows, Remote Agents

Delegation and isolation

Root copies do not receive the root-only agent tool recursively. Give parallel children non-overlapping writes. Children do not automatically receive parent conversation history; send necessary evidence and scope in the message.

Distinguish acceptance from completion

Model-facing local and remote subagent calls run as tasks. The parent can continue after receiving a receipt, but its turn does not end while the child is working. Reuse taskId for follow-up messages; a child failure fails the task.

interface DelegationInput {
  message: string;
  taskId?: string;
}

Do not trigger dependent work on acceptance alone. For review-then-publish, await the child result inside an authored workflow before continuing. eve__task_wait waits; eve__task_cancel cancels current work.

Declared specialist

import { defineAgent } from "eve";

export default defineAgent({
  description: "Review proposed operations for risk and missing approvals.",
  model: "anthropic/claude-opus-5.5",
  tool: false,
});

Description is required. tool: false hides the direct model-facing tool but does not prevent workflow ctx.agent calls. Review the child's instructions, tools, connections, skills, and sandbox separately.

Await structured results in a workflow

import { defineWorkflowTool } from "eve/tools";
import { z } from "zod";

export default defineWorkflowTool({
  description: "Obtain a structured risk review of a proposed plan.",
  inputSchema: z.object({ plan: z.string() }),
  async execute({ plan }, ctx) {
    "use workflow";
    const reviewer = ctx.agent("reviewer");
    const response = await reviewer.send(plan, {
      outputSchema: z.object({
        risk: z.enum(["low", "medium", "high"]),
        findings: z.array(z.string()),
      }),
      signal: ctx.abortSignal,
    });
    const result = await response.result();
    if (!result.data) throw new Error("Missing structured review.");
    return result.data;
  },
});

ctx.agent and ctx.ask belong to workflow bodies, not ordinary tools or channel/schedule handlers. Put side effects, clocks, randomness, and environment access in use-step helpers. Sensitive follow-up actions also need execution-time authorization and approval.

Model-generated workflows

Replace the old ExperimentalWorkflow export with this factory:

import { workflow } from "eve/tools/workflow";

export default workflow({ maxSubagents: 20 });

The generated program's host capability is limited to ctx.agent(name, { message, outputSchema? }). It has no direct ordinary-tool, credential, or arbitrary-import access. Each call creates a new child session; the return must be JSON-serializable. maxSubagents defaults to 100 and accepts 1–128. Promise.all supports fan-out; Promise.race does not resume immediately after only one child settles. This tool also runs as a task, so wait for its result.

Remote agents and identity

import { defineRemoteAgent } from "eve";
import { vercelOidc } from "eve/agents/auth";

export default defineRemoteAgent({
  url: "https://weather-agent.example.com",
  description: "Answers weather and forecast questions.",
  auth: vercelOidc(),
});

Configure outbound authentication and receiving-side validation. forwardPrincipal defaults to false; enable identity forwarding only when the receiver explicitly trusts the caller. Deployment authentication does not automatically authorize the end user or tenant. Remote model, usage limits, and retention belong to that deployment.

Release regressions

Subagents · Workflow tools · Remote agents.