How Subagents Function in Prime Agent: Delegation, Lifecycle, and Communication

Subagents in Prime Agent are lightweight child agents spawned by the main agent through the RLM runtime to execute isolated tasks, with creation, interaction, and cleanup managed via the harness API and asynchronous messaging.

Prime Agent's subagent architecture provides a delegation primitive that keeps the parent agent's execution deterministic while enabling parallel, sandboxed processing. This guide explains how subagents are created, admitted, interacted with, and destroyed based on the PrimeIntellect-ai/prime-agent source code.

Subagent Lifecycle: From Creation to Cleanup

The subagent lifecycle flows through four stages managed by the RLM (Remote-Learning-Model) runtime and harness layer.

1. Creation via the Harness API

A subagent originates from a call to rlm.harness.create_subagent() in prime-agent-runtime/src/rlm/harness.py. This stores a subagent spec containing the task prompt, optional metadata, and a scope path.

await rlm.harness.create_subagent(
    title="Summarise logs",
    content="Read the log files and produce a concise summary."
)

The create_subagent function accepts:

• title – human-readable label for the task
• content – the instruction prompt passed to the child
• path (optional) – directory scope under the harness
• metadata (optional) – arbitrary key-value pairs
• global_ (optional) – when True, persists across parent sessions

2. Admission and Handle Generation

When the model processes the subagent spec, it invokes rlm('sub-task'). The runtime immediately returns a handle with:

Field	Description
rlm_child_id	Unique identifier for the child process
session_name	Isolated execution context name
session_dir	Filesystem path for child I/O
status	running, completed, or error

The admission logic resides in prime-agent-runtime/src/rlm/__init__.py, specifically the _subagent_from_payload helper that translates host JSON into an RLMSubagent object (lines 78–99).

3. Interaction Through Isolated Messaging

Because subagents run in isolated sessions, parents cannot directly read child memory. Communication flows through two channels:

• Asynchronous messages: agent_message.send() with receiver_role='child'
• Filesystem: Reading/writing files in the child's session_dir

# Retrieve active subagents

subagents = await rlm.list_subagents()
child = subagents[0]

# Send follow-up instruction

await agent_message.send(
    "Please summarise the findings.",
    receiver_role="child",
    receiver_name=child.rlm_child_id
)

4. Lifecycle Management Operations

Prime Agent exposes three core operations for managing subagents:

list_subagents() – Returns all live or retained children for the current session as RLMSubagent objects. Implemented in prime-agent-runtime/src/rlm/__init__.py under RLMCallable (lines 84–100).

delete_subagent(target) – Terminates a running child by rlm_child_id and cleans its session directory. Validates the target before forwarding to host_request("rlm.delete_subagent", ...).

Persistence control – Subagents default to session-scoped destruction. Pass global_=True during creation or update_subagent() to create continual harness subagents reusable across sessions.

Complete Working Example

This runnable pattern demonstrates the full subagent workflow in Prime Agent:

# 1. Spawn a subagent to analyse a transcript file

await rlm.harness.create_subagent(
    title="Analyse transcript",
    content="Identify the main topics in transcript.txt.",
    path="analysis",
    metadata={"max_turns": 3},
)

# 2. After the model runs, retrieve the child handle

subagents = await rlm.list_subagents()
child = subagents[0]                     # first (and only) subagent

print(f"Child ID: {child.rlm_child_id}")

# 3. Send a follow-up message to the child (e.g., request a summary)

await agent_message.send(
    "Please summarise the findings.",
    receiver_role="child",
    receiver_name=child.rlm_child_id,
)

# 4. Clean up when finished

await rlm.delete_subagent(child)        # or await rlm.delete_subagent(child.rlm_child_id)

Key Source Files and Functions

File	Key Function/Class	Purpose
prime-agent-runtime/src/rlm/harness.py	create_subagent, update_subagent	Subagent spawning and modification
prime-agent-runtime/src/rlm/__init__.py	list_subagents, delete_subagent, RLMSubagent	Child enumeration, termination, and data model
prime-agent-runtime/src/rlm/__init__.py	_subagent_from_payload	Host JSON to RLMSubagent conversion

The harness overview (lines 30–36) documents the contract: parents compose concise prompts, spawn children, and collect results through the messaging system.

Summary

• Subagents are isolated child processes spawned via rlm.harness.create_subagent() with task-specific prompts
• Handles returned immediately contain rlm_child_id, session_dir, and status—no direct memory access
• Communication is message-based through agent_message.send() or filesystem operations
• Cleanup uses delete_subagent() which terminates the child and removes session artifacts
• Global persistence via global_=True enables reusable subagents across parent sessions

Frequently Asked Questions

What is the RLM runtime in Prime Agent?

The RLM (Remote-Learning-Model) runtime is Prime Agent's execution layer that manages subagent admission, status tracking, and host communication. It exposes list_subagents and delete_subagent through the rlm object and translates between internal RLMSubagent objects and host JSON payloads.

How does a parent agent receive results from a subagent?

Parents cannot directly access subagent memory. Results arrive through two mechanisms: the subagent sends messages via the agent messaging system (agent_message.send), or writes output files to its session_dir which the parent can read. This isolation prevents state corruption but requires explicit result collection.

Can subagents outlive the parent session?

Yes. By passing global_=True to create_subagent or update_subagent, the subagent persists in the continual harness scope. These global subagents remain available across parent session restarts, enabling reusable background services or long-running analytical workers.

What happens if delete_subagent is not called?

Session-scoped subagents are automatically cleaned up when the parent session ends. Global subagents (global_=True) persist indefinitely until explicitly deleted via delete_subagent. Accumulating undeleted global subagents consumes host resources and may exhaust allocation limits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}