How Do Subagents Work and How Do I Set Them Up?

Last updated: May 14, 2026

Subagents let your agent delegate tasks to other agents that run independently — each with its own system prompt, tools, sandbox, and context window. The parent does not read a subagent's configuration; it only sees a name and description. This article explains the mental model, what context flows where, and how to architect multi-agent setups that work reliably.

The Mental Model: What a Subagent Actually Is

A subagent is a completely independent agent conversation that happens to be started by another agent instead of a human. When your coordinator invokes a subagent, Gumloop spins up a fresh session with its own:

System prompt — loaded from the subagent's own configuration, not inherited from the parent
Tools and integrations — whatever the subagent has configured in its own settings
Skills — the subagent's own skill files, completely separate from the parent's
Sandbox — a clean /home/user/ environment (no files carry over from the parent unless explicitly transferred)
Context window — starts empty, filled only with the prompt the parent sends

Think of it this way: invoking a subagent is like handing a colleague a note with instructions. They go do the work in their own office with their own tools, then come back and hand you the results. They don't read your to-do list, rifle through your desk, or inherit your habits.

What the Parent Knows About Its Subagents

This is the most common misunderstanding. The parent agent does not read a subagent's system prompt, AGENT.md, skills, or tool configuration. Here's exactly what the parent sees:

In its system prompt, the parent receives a block like this:

<available_subagents>
You can invoke the following agents using invoke_agent with their gummie_id.

- Sales Research Agent (gummie_id: abc123)
  Description: Pulls CRM data and company background for leads.
  Tools: salesforce, web_search

- Marketing Insights Agent (gummie_id: def456)
  Description: Checks campaign engagement and lead scoring.
  Tools: ganalytics, gsheets
</available_subagents>

That's it — a name, description, and list of tool names. The parent uses this to decide which subagent to call and what prompt to send it. It has no visibility into how the subagent is configured internally.

This is why your subagent's name and description matter so much: they're the only signal the coordinator has when deciding who gets what task.

What the Subagent Receives When Invoked

When the parent calls invoke_agent, the subagent's session is constructed with these layers of context:

Its own system prompt — loaded from the subagent's configuration (not the parent's).
The parent's prompt — the prompt field from the invoke_agent call. This is the subagent's primary instruction for what to do.
Efficiency rules — Gumloop automatically injects guidance telling the subagent to optimize for speed, parallelize tool calls, stay focused on scope, and fail fast on errors.
Parent conversation file — the parent's full conversation history is saved as /home/user/_parent_conversation.json in the subagent's sandbox. The subagent can read this file if it needs broader context about the task.
Transferred files — if the parent specified artifacts, those files are copied into the subagent's sandbox before it starts.
Sibling awareness (parallel invocations only) — if the subagent is running alongside other subagents in the same batch, it receives a roster of its siblings' names and prompt previews, plus access to a broadcast_to_siblings tool for critical coordination notes.
Time budget — the subagent is told how many seconds remain before its 15-minute timeout.

How Results Flow Back to the Parent

When a subagent finishes, the parent receives:

The subagent's final text response — whatever the subagent wrote as its conclusion.
Any files the subagent generated — charts, CSVs, reports, images — all automatically bubble up as attachments in the parent's chat. No extra steps needed.
A conversation transcript — the subagent's full step-by-step conversation is saved to a file in the parent's sandbox. The parent sees a hint like: "Full child conversation (12 messages) saved to [path]. Use sandbox tools to read it."
A status — completed, error, or timeout, so the parent can decide what to do next.

The parent can then combine results from multiple subagents, ask follow-up questions, or take action based on what came back.

Two Types of Subagent Invocations

Self-Cloning: Parallel Copies of the Same Agent

When the parent spawns a clone (no gummie_id specified), Gumloop creates a copy of the parent agent with the same system prompt, tools, and capabilities. This is the simplest way to parallelize work.

Use self-cloning when: you need to do the same type of task multiple times (e.g., research 5 companies, summarize 10 documents, check 3 databases). The clones share the parent's configuration, so you don't need to build separate agents.

You can optionally restrict a clone's tools using tool_scope — for example, giving one clone only gcalendar access and another only gmail. Non-MCP tools (sandbox, web search, image generation) are always available.

Invoking a Different Agent: Specialized Delegation

When the parent specifies a gummie_id, it invokes a completely different agent with its own system prompt, tools, and skills. This is for when different tasks need fundamentally different expertise.

Use specific agents when: the subtask requires a different system prompt, different tools, or domain-specific skills that the parent doesn't have. For example, a coordinator agent delegating to a "Sales Research Agent" that has Salesforce access and CRM-specific instructions.

Setting Up Subagents: The A-to-Z Guide

Step 1: Decide Your Architecture

Before building anything, choose your pattern:

Self-cloning only — one agent splits its own work into parallel tasks. Simplest setup, no extra agents to build. Good for: batch processing, parallel research, splitting a report into sections.
Coordinator + specialists — one coordinator routes tasks to purpose-built agents. More setup, but each agent can have a focused system prompt and tools. Good for: multi-domain workflows (sales + marketing + support), complex pipelines where each step needs different expertise.
Hybrid — a coordinator that uses both self-cloning (for parallel subtasks it can handle itself) and specific agents (for specialized domains). Most flexible, but most complex.

Step 2: Build Your Specialist Agents (if using specific agents)

Create a separate agent for each domain. For each one:

Write a focused system prompt that covers only that agent's domain.
Attach only the tools it needs — fewer tools mean better decisions.
Set a clear name and description — this is what the coordinator sees when deciding who to call.

Step 3: Configure the Coordinator's Subagent List

Open your coordinator agent's configuration at Agents.
Scroll to the Subagents section.
Click + Subagent and select the agents you want it to delegate to.

Note: Only custom agents in the same project appear in the list. Self-cloning (the "(Me)" entry) is enabled by default. To disable it, click the three-dot menu on "(Me)" and select Remove.

Step 4: Tell the Coordinator When to Delegate

This is the step most people skip — and the reason subagents don't work well. The coordinator's system prompt needs to explain when and why to use each subagent. Without this, the coordinator has to guess based solely on names and descriptions.

Example coordinator system prompt:

You are a lead qualification coordinator.

When a new lead comes in:
1. Delegate to "Sales Research Agent" for CRM lookups and company background.
2. Delegate to "Marketing Insights Agent" for campaign engagement data.
3. Run both in parallel using invoke_agent.
4. When both return, combine their findings into a qualification summary.

If you only need to research multiple companies at once, use self-cloning
instead of the specialist agents — spawn one clone per company.

Limits and Constraints

Parallel limit by tier: Free = 2 simultaneous subagents, Starter = 4, Pro/Enterprise = 15.
Self-clone depth: A clone cannot clone itself (depth limit of 1). If a clone needs to delegate further, it must invoke a different agent.
Cross-agent chains: Agent A → Agent B → Agent C is unlimited. The depth limit only applies to self-cloning.
Timeout: Each subagent has a 15-minute execution limit. After that, it receives a graceful abort signal followed by a hard cancellation.
Credentials: Subagents use the credentials of the person who started the conversation with the coordinator — not the coordinator's own credentials.

Common Mistakes and How to Avoid Them

Assuming the parent reads the subagent's prompt. It doesn't. If the coordinator needs to know details about what a subagent can do, put that context in the coordinator's own system prompt — not the subagent's.
Vague subagent names and descriptions. The coordinator sees only the name, description, and tool list. "Helper Agent" with no description means the coordinator can't route tasks effectively.
Overloading a single agent instead of delegating. If your agent is doing 5+ unrelated tasks in sequence, consider splitting into subagents that run in parallel.
Sending vague prompts to subagents. The prompt you pass via invoke_agent is the subagent's primary instruction. Be specific: include the data it needs, the format you want back, and any constraints.
Giving every subagent every tool. Subagents make better decisions with fewer, focused tools. A "Sales Research Agent" doesn't need Google Calendar access.

Related Resources

Still Need Help?

If this didn't resolve your issue, reach out to support at support@gumloop.com.