Subagents

Purpose and Scope

Subagents are Flue’s mechanism for letting one agent delegate focused work to a named specialist while the original agent continues to own the user interaction. Use this pattern when a primary agent needs help with a bounded task such as researching a topic, classifying a support issue, reviewing a proposed answer, or checking a narrow domain assumption before continuing its response. The parent agent remains the visible resource and decision maker; the specialist exists to return an answer that the parent can use in its ongoing work.

Sources: apps/docs/src/content/docs/guide/subagents.md

A subagent is not another routed agent endpoint. In Flue terminology, it is an agent profile declared inside another agent’s configuration. Delegated work runs in a separate child session, which means the specialist receives the delegated request and its own configured context rather than simply appending work to the parent conversation transcript. This distinction matters when designing multi-agent systems: subagents are best for private delegation inside one agent, not for exposing a fleet of independently addressable agents over HTTP.

Sources: apps/docs/src/content/docs/guide/subagents.md

Relevant Source Files

• apps/docs/src/content/docs/guide/subagents.md — Defines the public Subagents guide, including defineAgentProfile(...), subagents configuration, delegation behavior, child-session semantics, configuration inheritance, and the distinction between subagent profiles and independently routed agents.

Core Primitives

The core primitive is defineAgentProfile(...). A profile gives the specialist a stable name, a description, and its own behavioral configuration, such as instructions. The parent agent then includes that profile in its subagents array inside defineAgent(...). The profile description is shown to the parent model alongside the subagent name, so it should be written as delegation guidance rather than marketing copy. A good description tells the parent when the specialist is useful and what kind of answer to expect.

Sources: apps/docs/src/content/docs/guide/subagents.md

import { defineAgent, defineAgentProfile } from '@flue/runtime';
 
const issueClassifier = defineAgentProfile({
  name: 'issue_classifier',
  description: 'Classifies support issues for routing.',
  instructions: 'Return the likely product area and urgency for the reported issue.',
});
 
export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  instructions: 'Help resolve support requests. Delegate classification when it helps your answer.',
  subagents: [issueClassifier],
}));

In this example, support-assistant can delegate to issue_classifier, but Flue does not create a separate /agents/issue_classifier/:id route. The profile configures the specialist role available to the parent, not a new public application resource. This makes subagents a composition tool inside the agent harness: they help one durable agent structure work across named roles without forcing each role to become part of the application’s external routing surface.

Sources: apps/docs/src/content/docs/guide/subagents.md

Delegation Flow

When an agent has configured subagents, Flue gives that agent a built-in task capability. The parent model can choose to use that capability while answering a prompt. A delegated task starts a child session for the selected subagent, sends the delegated request into that child context, waits for the specialist’s result, and returns the child answer to the parent. The parent can then decide how to incorporate that answer into the user-facing response or its next action.

Sources: apps/docs/src/content/docs/guide/subagents.md

The child session is intentionally isolated from the parent conversation transcript. It receives the delegated request and the context configured for the subagent profile, rather than inheriting all prior user and assistant messages from the parent. This keeps specialist work focused and avoids accidentally treating the parent’s full conversation as the specialist’s own memory. When persistence is enabled, retained child history remains owned by the parent session instead of becoming an ordinary named session that users address directly.

Sources: apps/docs/src/content/docs/guide/subagents.md

Sandbox behavior follows the same operational boundary as the parent. If the subagent works in a configured sandbox, it uses that sandbox boundary rather than escaping into a separate uncontrolled environment. This is important for agents that perform code, shell, or file work: delegation should improve role separation, not weaken the safety boundary around workspace and command access. Pair subagent design with sandbox configuration whenever specialists need to inspect files, run commands, or use tool-driven capabilities.

Sources: apps/docs/src/content/docs/guide/subagents.md

Configuration Inheritance

Subagent profiles are self-contained for capability fields. The guide explicitly separates fields that belong to the profile from fields that may inherit runtime defaults from the parent. Capability fields such as instructions, tools, skills, and nested subagents apply only when declared by the profile. If the profile omits one of those fields, the subagent has none for that field; the parent’s declarations do not flow into the child. This prevents accidental privilege or behavior leakage from a broad parent into a narrow specialist.

Sources: apps/docs/src/content/docs/guide/subagents.md

Environment-like fields can fall back to the parent. The profile may declare its own model, thinkingLevel, or compaction; if it does not, the parent value is used as the default. The durability field is different: it is rejected on subagent profiles because delegated task sessions run inside the parent operation. A task() call without an agent name is also not subagent delegation; it creates a fresh child context that reuses the parent’s full configuration instead of selecting a named specialist profile.

Sources: apps/docs/src/content/docs/guide/subagents.md

Design Guidance

Use subagents when the parent benefits from a named role with a clear decision boundary. A support assistant might delegate issue classification, a code review agent might delegate security review, or a research assistant might delegate source-checking. Keep each profile’s instructions narrow enough that the parent can rely on the result without giving up ownership of the interaction. If the work should be publicly invoked, monitored, and routed as its own durable resource, define a normal agent instead of hiding it as a subagent profile.

Sources: apps/docs/src/content/docs/guide/subagents.md

When authoring a profile, start with the delegation contract: the name should be stable and machine-friendly, the description should tell the parent when to call it, and the instructions should tell the child how to respond. Then decide which capabilities the child really needs. Because tools and skills do not automatically inherit, you can use subagents to reduce the scope of sensitive operations. Give the specialist only the tools, skills, and nested delegation abilities required for its job.

Sources: apps/docs/src/content/docs/guide/subagents.md

Next Steps

After defining a subagent profile, test the parent agent with prompts that make delegation useful and prompts where delegation would be unnecessary. Confirm that the parent can identify the specialist by name and that the returned answer is useful enough to continue the interaction. For the surrounding system design, read the Building Agents guide for agent profile context, the Database guide for persistence setup, and the Sandboxes guide for workspace and command-access boundaries.