How Subagent Profiles and Concurrency Limits Function in DeepSeek-Reasonix

Subagent profiles in Reasonix configure isolated AI workers with specific models, tools, and safety constraints, while the concurrency limit enforces a hard cap on simultaneous executions through a scheduler-backed queue system.

Reasonix, the multi-agent orchestration framework developed in the esengine/DeepSeek-Reasonix repository, implements a sophisticated subagent architecture that isolates specialized AI tasks while preventing resource exhaustion. Understanding how subagent profiles and concurrency limits function is essential for building scalable multi-agent workflows that remain responsive under load. This system allows developers to define tailored agent capabilities while the backend scheduler maintains strict execution boundaries per session.

Understanding Subagent Profiles

Subagent profiles act as configuration blueprints that determine how each isolated AI worker behaves when invoked from a parent chat session. These profiles are stored in the user's settings and retrieved whenever a new subagent is instantiated.

Profile Metadata and Localization

Each profile defines fundamental identity fields including name, description, color, and system prompt. In desktop/frontend/src/locales/en.ts, these UI labels are defined under the subagents namespace:

• subagents.name – Display identifier for the profile
• subagents.systemPrompt – Instructions that define the subagent's role and boundaries
• subagents.description – Human-readable summary shown in the selection interface

These localized strings power the profile editor interface, ensuring consistent labeling across the application.

Model Overrides and Tool Whitelisting

Profiles can override the parent session's inference parameters through specific settings exposed in the UI. According to desktop/frontend/src/locales/en.ts, the relevant configuration keys include:

• subagentModel – Specifies which base model the subagent uses (e.g., deepseek-chat, deepseek-reasoner)
• subagentEffort – Controls inference depth/compute allocation (low, medium, high)

Tool access is governed by whitelist selection. The profile editor (desktop/frontend/src/components/subagents/SettingsPanel.tsx) renders a ToolListPicker component that allows users to restrict which functions the subagent may invoke. By default, subagents inherit the full toolset available to the parent session, but administrators can limit access to specific capabilities such as file reading, web search, or code execution.

Read-Only Safety Controls

The readOnly flag provides a critical safety mechanism for untrusted or review-oriented subagents. When enabled in the profile editor, this boolean strips write-capable tools from the subagent's execution context, preventing modifications to files, databases, or external systems. This is implemented as a preprocessing step in the profile validation logic before the subagent receives its final tool configuration.

Concurrency Limits and Session Management

Reasonix enforces strict resource boundaries through configurable concurrency controls that prevent a single session from spawning unlimited simultaneous subagents.

The subagentConcurrency Setting

The primary control mechanism is the subagentConcurrency parameter, configurable per session with a default value of 6 and an allowable range of 1 to 32. This setting is exposed in the frontend through localization keys in desktop/frontend/src/locales/en.ts:

• settings.subagentConcurrency – The numeric input label
• settings.subagentConcurrencyHint – Description explaining the 1-32 range limit

Additionally, the subagentDepth setting (typically defaulting to 1 or 2) determines nesting capabilities—whether a subagent may invoke its own child subagents, creating hierarchical task trees.

Scheduler Enforcement in stats.ts

The actual enforcement occurs in workers/crash-report/src/stats.ts, where the Task Scheduler tracks active executions per session. When a new subagent is requested through workers/crash-report/src/registry/app.ts, the scheduler checks the current running count against the configured limit:

// workers/crash-report/src/stats.ts (simplified)
function tryLaunchSubAgent(run: SubAgentRun) {
  const sess = getSession(run.parentSessionId);
  if (sess.subagentRunningCount >= sess.settings.subagentConcurrency) {
    sess.subagentQueue.push(run);
    return; // wait in queue
  }
  sess.subagentRunningCount++;
  launchInference(run).finally(() => {
    sess.subagentRunningCount--;
    // after finishing, try to launch next queued run
    if (sess.subagentQueue.length) {
      tryLaunchSubAgent(sess.subagentQueue.shift()!);
    }
  });
}

This implementation maintains a FIFO queue for pending subagents. When an active subagent completes, fails, or is cancelled, the scheduler automatically decrements subagentRunningCount and attempts to launch the next queued SubAgentRun object, ensuring optimal resource utilization without exceeding the configured cap.

Practical Implementation Examples

Creating a Subagent Profile via the Frontend

The React component responsible for profile creation collects configuration through a form interface defined in desktop/frontend/src/components/subagents/SettingsPanel.tsx:

// Profile creation form excerpt
<FormField label={t('subagents.name')} name="name" rules={nameRules} />
<FormField label={t('subagents.model')} name="model" selector={modelOptions} />
<FormField label={t('subagents.effort')} name="effort" selector={effortOptions} />
<ToolListPicker
  label={t('subagents.tools')}
  defaultAll={true}
  onChange={setSelectedTools}
/>
<Checkbox
  label={t('subagents.readOnly')}
  checked={isReadOnly}
  onChange={toggleReadOnly}
/>

Upon submission, the frontend persists the profile and can immediately invoke it:

// Invoking a subagent with the created profile
await fetch('/api/subagents', {
  method: 'POST',
  body: JSON.stringify({ 
    profileId: 'custom-reviewer',
    task: 'Analyze the authentication module for security issues',
    parentSessionId: 'sess_abc123'
  }),
});

The backend receives this request in workers/crash-report/src/registry/app.ts, instantiates a SubAgentRun object containing the profile reference and task payload, and passes it to the scheduler for concurrency-gated execution.

Summary

• Subagent profiles encapsulate model selection (subagentModel), inference effort (subagentEffort), tool whitelists, and read-only safety flags, all configurable through the frontend settings panel backed by desktop/frontend/src/locales/en.ts.
• Concurrency limits are enforced per session via the subagentConcurrency setting (default 6, max 32), with the scheduler in workers/crash-report/src/stats.ts maintaining a running count and FIFO queue to manage active executions.
• The architecture separates profile configuration (frontend) from execution governance (backend), allowing flexible agent specialization while preventing resource exhaustion through strict SubAgentRun queue management.

Frequently Asked Questions

What is the default concurrency limit for subagents in Reasonix?

The default concurrency limit is 6 simultaneous subagents per session, configurable within a range of 1 to 32 through the subagentConcurrency setting. This default prevents resource exhaustion while allowing meaningful parallel execution of worker and reviewer agents.

How does the read-only flag restrict subagent capabilities?

When the readOnly flag is enabled in a subagent profile, the system automatically filters out all write-capable tools from the agent's execution context before launching. This ensures the subagent can only perform read operations such as analysis, search, or code review without modifying files or external systems.

What happens when the concurrency limit is reached?

When a session's active subagent count equals the subagentConcurrency limit, new SubAgentRun requests are placed into a FIFO queue in workers/crash-report/src/stats.ts rather than executing immediately. The scheduler automatically launches queued subagents as soon as active ones complete, maintaining sequential order while respecting the configured cap.

Can subagents create their own child subagents?

Yes, but only up to the depth specified by the subagentDepth setting (typically 1 or 2). A depth of 1 allows only the parent session to spawn subagents, while depth 2 permits subagents to spawn their own children, enabling hierarchical workflows such as a manager agent delegating to worker agents that then consult specialist agents.

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