Skip to content

Subagents#

Managed agents can delegate tasks to specialized subagents. Each subagent has its own workspace, memory, token, and audit trail — fully isolated from the parent.

How Delegation Works#

The delegation flow has five steps:

  1. Match — the parent agent receives a task that matches a subagent's capabilities (based on the subagent descriptions configured on the parent).
  2. Invoke — the parent calls the Task tool, specifying the subagent type, a description, and a detailed prompt.
  3. Execute — the subagent runs independently in its own invocation context with its own workspace files, memory, and tools.
  4. Return — the subagent completes its work and returns the result to the parent.
  5. Summarize — the parent summarizes the subagent's output and presents it to the user. The raw subagent output is not shown directly.

The parent decides when and how to delegate. You can also instruct the parent through conversation:

Delegate the Terraform plan review to the infrastructure subagent.

Isolation Properties#

Each subagent is a fully separate entity:

Property Isolation
Workspace files Own Soul, User Profile, Memory Summary, Heartbeat, Vision, Agent Guide
Memory database Separate memory entries, not shared with parent
Identity Own token, auto-provisioned at creation
Audit trail Actions attributed to the subagent's identity
Tool access Full tool access (workspace updates, memory, infrastructure, scheduling)

The parent cannot read or modify the subagent's memory or workspace files. Communication happens only through the delegation interface — the parent sends a prompt and receives a result.

Flat hierarchy#

Subagents cannot delegate to other subagents. The delegation model is always one level deep:

Parent Agent → Subagent (no further delegation)

This prevents runaway agent chains and keeps delegation predictable. If a subagent encounters a task outside its scope, it completes what it can and returns the result to the parent, which can then delegate to a different subagent.

Same-Team Constraint#

Subagents must be in the same team as the parent agent. This ensures:

  • Shared project access — the subagent can access the same infrastructure as the parent
  • Consistent governance — the same team policies apply
  • Administrative simplicity — team admins manage all agents in one place

Output handling#

When a subagent completes its task, the parent agent processes the result before presenting it to you:

  • The parent summarizes the subagent's output, extracting the key findings
  • Raw tool output from the subagent (kubectl results, shell output, etc.) is condensed
  • The parent adds context about which subagent performed the work and what was accomplished

This keeps responses focused. If you need the full detail, ask the parent to show the complete subagent output.

Configuring subagents#

A subagent is created the same way as any managed agent, with a type marker that makes it available for linking as a subagent. Like any other agent, it runs its own bootstrap conversation to configure its specialty (database reasoning, compliance checks, incident triage, etc.).

Subagents are linked to a parent agent with a capability description — a short line that tells the parent when delegation to this subagent is appropriate. A parent can have multiple linked subagents. Links are managed independently: unlinking a subagent stops delegation without deleting the subagent itself. Keep capability descriptions specific so the parent makes accurate routing decisions.

Use cases#

Subagent specialty Parent delegates when...
Security auditor Compliance checks, CVE scanning, RBAC reviews
Database specialist Query optimization, schema changes, backup verification
Cost analyst Spending reports, resource right-sizing, waste identification
Terraform expert Infrastructure changes, plan reviews, state management
Documentation writer Runbook updates, incident summaries, knowledge base articles