Skip to content
Rival Docs

Sub-agents

Overview

A sub-agent is another Rival Agent that you’ve linked to a parent agent. During a chat (or a ritual run), the parent can delegate part of a task to the sub-agent, which runs its own turn with its own persona and tools and hands back a result.

Sub-agents let you build specialist agents (a researcher, a drafter, a reviewer) and compose them into a single experience for the user.

Limits - read this first

Sub-agents are deliberately constrained to keep behavior predictable:

  • One level deep. A sub-agent cannot have its own sub-agents. There are no grandchildren.
  • No recursion. A sub-agent cannot call back into the parent, and an agent cannot be a sub-agent of itself.
  • OAuth grants don’t inherit. If your sub-agent uses Gmail, it needs its own Gmail connection.

These limits are enforced by the platform - you can’t work around them. Plan flat hierarchies of specialists, not deep chains.

When to use a sub-agent

Reach for a sub-agent when:

  • You have a task with distinct stages - research → draft → format.
  • One agent needs a check or opinion from another - e.g. a policy reviewer before sending.
  • You want to keep each agent focused on what it does well, instead of stuffing one agent with every tool.

If you only need code to run on demand, attach a tool - not a sub-agent.

Attaching a sub-agent

Sub-agents are managed from the Sub-agents section of the agent editor.

  1. Open the parent agent’s editor.
  2. Click the Plus icon on the chat box and go to Sub Agents.
  3. Either create a new sub-agent inline (define its name, instructions, model, tools, and connectors) or clone an existing one from your organization or the Marketplace as a starting point. You can’t pick the parent itself, and you can’t create a loop.
  4. Save.

The sub-agent appears in the sub-agents list. It’s stored inline with this parent agent and scoped to it only - it isn’t a separate, shared agent in your org, so editing or removing it affects just this parent. Cloning from an existing agent copies it in; the original agent is left untouched.

How it works in chat

When the parent decides to delegate, a card appears in the chat showing the sub-agent’s name and result. The sub-agent’s own internal tool calls are hidden to keep the chat readable. The user sees the parent’s final reply.

If multiple sub-agents run in the same turn, the chat shows a small progress indicator while they’re working. You can even select whether the sub-agents run in parallel or sequentially.

Memory and isolation

A sub-agent runs as its own agent with its own memory. The parent only passes the prompt - the sub-agent does not see the parent’s full conversation history, and the parent does not see inside the sub-agent’s memory.

This isolation matters for marketplace agents: adopting an agent that uses a third-party sub-agent will not leak your private context to the sub-agent’s publisher.

Sub-agents from the Marketplace

You can pick a published agent from the Agent Marketplace and link it as a sub-agent. The Marketplace listing has an Adopt action that brings the agent into your org first; once it’s in your org, you can attach it as a sub-agent from the editor.

Next steps