# OpenHuman Orchestration: Subagent Fleets, Checkpointed Runs, and Reasoning Split

> Discover OpenHuman orchestration: leverage subagent fleets, checkpointed runs, and reasoning split for efficient AI development. Execute tasks in parallel with Rust-native power.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: deep-dive
- Published: 2026-08-29

---

**OpenHuman's Rust-native orchestration engine enables parent agents to spawn lightweight subagent fleets that execute in parallel, checkpoint their progress via world-diff uploads, and maintain clean reasoning separation between parent and child processes.**

OpenHuman is a Rust-native engine designed to power sophisticated AI-assistant behavior through coordinated multi-agent execution. At the heart of this system lies **OpenHuman orchestration**, a framework that implements subagent fleets capable of running independent tasks while maintaining durable state through checkpointed runs. This architecture allows complex workloads to be distributed across isolated agent processes that can be monitored, awaited, or fired as background tasks without blocking the main reasoning loop.

## Subagent Fleet Architecture

OpenHuman orchestration treats subagents as lightweight, ephemeral processes that inherit configuration from a parent turn but execute within isolated sessions. The parent agent builds a **system prompt** that defines the subagent's archetype—its name, purpose, workspace access, and available tools—through the `render_subagent_system_prompt` function in [`src/openhuman/agent/harness/subagent_runner.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/harness/subagent_runner.rs).

When the parent invokes the **`spawn_subagent`** tool implemented in [`src/openhuman/agent/orchestration/tools/spawn_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/spawn_subagent.rs), the orchestration runtime creates a new session entry in the orchestration store. The subagent then enters its own turn loop, utilizing the same tool-calling infrastructure as standard agents, but isolated to its unique session ID. This design enables true parallelism: the parent continues its own reasoning or pauses via the **`wait_subagent`** tool while the fleet member processes independently.

## The OpenHuman Orchestration Lifecycle

Understanding the lifecycle requires tracing four distinct phases from initialization to completion.

### Spawning and Prompt Generation

The parent turn constructs the subagent’s context in [`src/openhuman/agent/harness/subagent_runner.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/harness/subagent_runner.rs). This includes serializing the workspace state and injecting the "### SUBAGENT" section that the UI renders as a distinct chat bubble, visually separating parent and child reasoning streams.

### Independent Execution

Once spawned, the subagent operates autonomously through the core loop in [`src/openhuman/agent/harness/subagent_runner.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/harness/subagent_runner.rs). It maintains its own transcript under `session_raw/subagent-<id>`, tracked via [`src/openhuman/agent/harness/turn_subagent_usage.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/harness/turn_subagent_usage.rs), ensuring that state mutations do not leak into the parent's context.

### Synchronization and Retrieval

Parents integrate results through two primary tools. The **`wait_subagent`** tool in [`src/openhuman/agent/orchestration/tools/wait_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/wait_subagent.rs) blocks execution until the subagent reports `Completed` or hits a timeout. Alternatively, the **`read_subagent`** tool in [`src/openhuman/agent/orchestration/tools/read_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/read_subagent.rs) retrieves checkpointed outputs without blocking, useful for polling scenarios.

### Background Cleanup

For fire-and-forget operations, the parent spawns the subagent without waiting. The orchestration runtime handles lifecycle management through [`src/openhuman/agent/orchestration/subagent_control.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/subagent_control.rs) and the background delivery logic in [`src/openhuman/platform/service/shutdown.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/platform/service/shutdown.rs), automatically persisting final states and cleaning up completed sessions.

## Reasoning Split: Isolating Parent and Subagent Logic

**OpenHuman orchestration** enforces a strict **reasoning split** that prevents state interleaving. The parent reasoning layer focuses on high-level planning: determining *whether* to spawn a subagent, constructing its initial prompt, and synthesizing results into the broader conversation flow. This logic remains in the primary session thread.

Conversely, **subagent reasoning** operates within its own isolated session, receiving a prompt that includes the parent's "workspace soul" and relevant memory snapshots, but executing independently. The separation is explicit in the storage layer—subagent transcripts live under `session_raw/subagent-<id>`—and in the prompt format, where the "### SUBAGENT" delimiter provides clear cognitive boundaries. This architecture allows the system to reason about parallel task trees without concurrency conflicts.

## Checkpointing Runs for Fault Tolerance

Durability is achieved through the **world-diff** mechanism. Each state transition is checkpointed to the orchestration backend via `POST /orchestration/v1/world-diff`. The uploader in [`src/openhuman/hosted/orchestration/world_diff_uploader.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/hosted/orchestration/world_diff_uploader.rs) batches these diffs, implements retry logic with exponential backoff, and logs upload status under the `"orchestration"` log target.

On process restart, the core re-hydrates the orchestration store from persisted world-diffs, ensuring that subagent progress survives crashes or deployments. This guarantees that long-running background tasks remain intact even when the parent process terminates unexpectedly.

## Implementing Subagent Orchestration in Practice

The following examples demonstrate the primary patterns for interacting with the orchestration API.

### Synchronous Subagent Execution

Use `run_subagent` when the parent requires the subagent's output before continuing:

```rust
use openhuman_core::openhuman::agent::harness::subagent_runner::run_subagent;
use openhuman_core::openhuman::agent::harness::SubagentRunOptions;

// Load your AgentDefinition from configuration
let def = /* ... load AgentDefinition ... */;

// Execute and await completion
let outcome = run_subagent(&def, "research-task", SubagentRunOptions::default())
    .await
    .expect("subagent execution failed");

println!("Subagent answer: {}", outcome.output);

```

*Source:* [`src/openhuman/agent/harness/subagent_runner.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/harness/subagent_runner.rs) (function `run_subagent`).

### Fire-and-Forget Background Tasks

Launch asynchronous work using the spawn tool:

```rust
use openhuman_core::openhuman::agent::orchestration::tools::SpawnAsyncSubagent;

let tool = SpawnAsyncSubagent::new(config.clone());
let result = tool.run(/* args with subagent definition */).await?;
println!("Background subagent launched, ID: {}", result.subagent_id);

```

*Source:* [`src/openhuman/agent/orchestration/tools/spawn_async_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/spawn_async_subagent.rs).

### Waiting for Completion

Block until a specific subagent finishes:

```rust
use openhuman_core::openhuman::agent::orchestration::tools::WaitSubagent;

let wait = WaitSubagent::new(config.clone());
// Returns status when subagent reaches Completed or timeout
let status = wait.run(subagent_id).await?;
println!("Subagent {} status: {}", subagent_id, status);

```

*Source:* [`src/openhuman/agent/orchestration/tools/wait_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/wait_subagent.rs).

### Monitoring Active Fleets

List currently running subagents:

```rust
use openhuman_core::openhuman::agent::orchestration::tools::ListSubagents;

let list = ListSubagents::new(config.clone()).run(()).await?;
println!("Active subagents: {:?}", list.subagents);

```

*Source:* [`src/openhuman/agent/orchestration/tools/list_subagents.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/list_subagents.rs).

## Key Source Files for OpenHuman Orchestration

The implementation spans the agent harness, orchestration domain, and platform service layers:

- **[`src/openhuman/agent/orchestration/subagent_control.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/subagent_control.rs)** – Core lifecycle management and cleanup routines for active subagents.
- **[`src/openhuman/agent/harness/subagent_runner.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/harness/subagent_runner.rs)** – High-level API for spawning and executing subagents, including `run_subagent` and `render_subagent_system_prompt`.
- **[`src/openhuman/agent/harness/turn_subagent_usage.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/harness/turn_subagent_usage.rs)** – Utilities for managing subagent transcript storage under `session_raw/subagent-<id>`.
- **[`src/openhuman/agent/orchestration/tools/spawn_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/spawn_subagent.rs)** – Synchronous subagent spawning tool implementation.
- **[`src/openhuman/agent/orchestration/tools/spawn_async_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/spawn_async_subagent.rs)** – Asynchronous fire-and-forget spawning.
- **[`src/openhuman/agent/orchestration/tools/wait_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/wait_subagent.rs)** – Blocking synchronization primitive for parent agents.
- **[`src/openhuman/agent/orchestration/tools/read_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/read_subagent.rs)** – Non-blocking retrieval of subagent outputs.
- **[`src/openhuman/agent/orchestration/tools/list_subagents.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/list_subagents.rs)** – Fleet introspection and status listing.
- **[`src/openhuman/hosted/orchestration/world_diff_uploader.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/hosted/orchestration/world_diff_uploader.rs)** – Checkpoint persistence and retry logic for world-state diffs.
- **[`src/openhuman/hosted/orchestration/wire.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/hosted/orchestration/wire.rs)** – HTTP DTOs for orchestration events crossing the `/orchestration/v1/events` boundary.
- **[`src/openhuman/threads/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/threads/ops.rs)** – Helper utilities for canceling or discarding subagents bound to specific threads.
- **[`src/openhuman/platform/service/shutdown.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/platform/service/shutdown.rs)** – Background delivery and cleanup orchestration during service shutdown.

## Summary

- **OpenHuman orchestration** enables parent agents to delegate work to isolated subagent fleets that run in parallel without blocking the main reasoning thread.
- The **reasoning split** maintains clean separation between parent planning logic and subagent execution, with transcripts stored under isolated session paths like `session_raw/subagent-<id>`.
- **Checkpointed runs** persist state via the world-diff mechanism in [`world_diff_uploader.rs`](https://github.com/tinyhumansai/openhuman/blob/main/world_diff_uploader.rs), ensuring durability across process restarts through `POST /orchestration/v1/world-diff` batch uploads.
- Developers can spawn subagents synchronously via `run_subagent`, asynchronously via `SpawnAsyncSubagent`, or query status through `ListSubagents` and `WaitSubagent` tools.
- The orchestration domain in `src/openhuman/hosted/orchestration/` coordinates persistence, while [`subagent_control.rs`](https://github.com/tinyhumansai/openhuman/blob/main/subagent_control.rs) handles runtime lifecycle management.

## Frequently Asked Questions

### What is a subagent fleet in OpenHuman?

A subagent fleet is a collection of lightweight agent processes spawned by a parent turn to handle parallel or long-running tasks. Each member operates within its own isolated session, defined by an archetype specifying its purpose, tools, and workspace access, allowing the main agent to distribute cognitive load across multiple independent reasoning contexts.

### How does OpenHuman checkpoint subagent progress?

The system checkpoints progress through the **world-diff uploader** in [`src/openhuman/hosted/orchestration/world_diff_uploader.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/hosted/orchestration/world_diff_uploader.rs), which batches state changes and transmits them to `POST /orchestration/v1/world-diff`. On failure, it retries with backoff, logging to the `"orchestration"` target. If the core restarts, it re-hydrates the orchestration store from these persisted diffs, restoring subagent transcripts exactly where they left off.

### What is the reasoning split between parent and subagent?

The reasoning split is an architectural boundary where the parent agent handles high-level orchestration decisions—such as *whether* to spawn help and how to integrate results—while the subagent performs isolated task execution within its own session. The parent writes subagent prompts containing a "### SUBAGENT" section, and the subagent's reasoning is stored separately under `session_raw/subagent-<id>`, preventing state pollution between the two contexts.

### How do I spawn a background subagent without blocking the parent?

Use the **`SpawnAsyncSubagent`** tool from [`src/openhuman/agent/orchestration/tools/spawn_async_subagent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/orchestration/tools/spawn_async_subagent.rs). This registers the subagent with the orchestration store and returns immediately with a `subagent_id`, allowing the parent to continue processing. The runtime automatically manages the subagent lifecycle and cleanup through [`subagent_control.rs`](https://github.com/tinyhumansai/openhuman/blob/main/subagent_control.rs) without requiring the parent to await completion.