How to Configure Subagent Profiles and Set the Delegation Depth in Reasonix

You configure subagent profiles in Reasonix by calling bridge methods like CreateSubagentProfile with a SubagentProfileInput payload, while the global delegation depth is controlled via SetMaxSubagentDepth, which caps nesting at two levels for safety.

Reasonix treats every sub-agent as a configurable profile managed through the front-end ↔ back-end bridge (bridge.ts). In the esengine/DeepSeek-Reasonix repository, these profiles define an agent’s identity, capabilities, and constraints, while the delegation depth setting prevents runaway recursion by limiting how many nested agent levels can spawn.

Understanding Subagent Profiles in Reasonix

A subagent profile is a structured configuration object that encapsulates an agent’s name, description, system prompt, and optional defaults for model selection, effort level, and tool permissions. These profiles persist through the application layer and communicate with the Go kernel via the bridge API.

The SubagentProfileInput Interface

The TypeScript interface that defines the profile payload lives in desktop/frontend/src/lib/types.ts at lines 897–907. According to the source, a valid profile requires a unique name and description, while model, effort, and allowed tools remain optional overrides:

interface SubagentProfileInput {
  name: string;
  description: string;
  systemPrompt: string;
  model?: string;
  effort?: "low" | "medium" | "high";
  allowedTools?: string[];
}

Creating and Managing Subagent Profiles

All profile mutations route through the app proxy (defined in desktop/frontend/src/lib/app.ts), which adds breadcrumb logging before forwarding requests to the Go kernel or mock implementations during development.

Creating a New Profile

To instantiate a profile, invoke app.CreateSubagentProfile with a complete SubagentProfileInput object. This method is implemented in desktop/frontend/src/lib/bridge.ts around lines 4024–4032.

await app.CreateSubagentProfile({
  name: "doc-assistant",
  description: "Helps write technical documentation.",
  systemPrompt: "You are a concise technical writer.",
  model: "deepseek-coder",
  effort: "high",
  allowedTools: ["search", "write"]
});

Updating Existing Profiles

Modify a profile’s configuration using app.UpdateSubagentProfile, specifying the profile name, scope ("project" or "global"), and the updated payload:

await app.UpdateSubagentProfile(
  "doc-assistant",
  "project",
  {
    name: "doc-assistant",
    description: "Helps write technical documentation.",
    systemPrompt: "You are an expert documentation writer with a friendly tone.",
    model: "deepseek-coder",
    effort: "medium",
    allowedTools: ["search", "write", "edit"]
  }
);

Setting Model and Effort Defaults

You can bind specific defaults to a profile without rewriting the entire object. The bridge exposes SetSubagentProfileModel and SetSubagentProfileEffort for granular updates:

// Bind a specific model
await app.SetSubagentProfileModel("doc-assistant", "deepseek-chat");

// Adjust the effort level
await app.SetSubagentProfileEffort("doc-assistant", "medium");

Deleting Profiles

Remove obsolete profiles by calling app.DeleteSubagentProfile with the profile name and scope:

await app.DeleteSubagentProfile("doc-assistant", "project");

Configuring Delegation Depth Limits

The delegation depth determines how many nested sub-agent levels a top-level agent may spawn. This global safety limit is stored in settings.agent.maxSubagentDepth (defined in desktop/frontend/src/lib/bridge.ts at lines 1504–1506) and exposed through the locale key "Subagent nesting depth" in desktop/frontend/src/locales/en.ts (line 1650).

Setting the Maximum Depth

Change the limit at runtime using app.SetMaxSubagentDepth. The implementation (lines 4045–4047 in bridge.ts) enforces a hard safety guard that clamps the value between 1 and 2:

// Allow up to 2 nested agents (Reasonix caps at 2 for safety)
await app.SetMaxSubagentDepth(2);

Internally, the bridge applies the following logic to prevent excessive recursion:

depth <= 1 ? 1 : 2

This ensures that even if you pass a value greater than 2, the system restricts nesting to a maximum of two levels, preventing stack exhaustion or circular delegation loops.

Summary

• Subagent profiles are configured via SubagentProfileInput in types.ts and managed through bridge methods in bridge.ts.
• Creation and deletion use CreateSubagentProfile and DeleteSubagentProfile, while updates can be full or partial via UpdateSubagentProfile, SetSubagentProfileModel, and SetSubagentProfileEffort.
• Delegation depth is a global integer controlled by SetMaxSubagentDepth, hard-capped at 2 levels to prevent runaway recursion.
• All calls route through the app proxy, which provides logging and kernel abstraction.

Frequently Asked Questions

What is the maximum delegation depth allowed in Reasonix?

Reasonix enforces a maximum delegation depth of 2 levels regardless of the value passed to SetMaxSubagentDepth. The bridge implementation explicitly clamps the input using the expression depth <= 1 ? 1 : 2, ensuring that nested agent chains cannot exceed two tiers as a safety guard against infinite recursion.

Can I restrict which tools a subagent profile is allowed to use?

Yes. The SubagentProfileInput interface includes an optional allowedTools array where you can specify a whitelist of tool names. When you create or update a profile, include only the tools that specific agent should access, such as ["search", "write"], to enforce least-privilege access patterns.

How do I change a subagent's default model without recreating the profile?

Use the SetSubagentProfileModel bridge method. Pass the profile name and the new model identifier as arguments. This updates the default model binding immediately without requiring you to fetch and resubmit the entire SubagentProfileInput payload.

Where does Reasonix store the global delegation depth setting?

The setting is stored in the maxSubagentDepth field of the global settings object defined in desktop/frontend/src/lib/bridge.ts at lines 1504–1506. The UI references this value through the localization key "Subagent nesting depth" in desktop/frontend/src/locales/en.ts, and you mutate it programmatically via SetMaxSubagentDepth.

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