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

> Discover how subagents function in Prime Agent. Learn about their role in task delegation, lifecycle management, and communication within the RLM runtime.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: deep-dive
- Published: 2026-08-15

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent-runtime/src/rlm/harness.py). This stores a **subagent spec** containing the task prompt, optional metadata, and a scope path.

```python
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`

```python

# 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```python

# 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent-runtime/src/rlm/harness.py) | `create_subagent`, `update_subagent` | Subagent spawning and modification |
| [`prime-agent-runtime/src/rlm/__init__.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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.