@dex-ai/sub-agents

Subagent profiles, durable run artifacts, and SDK tools for Dex coding agents.

Tools

The extension exposes three core tools:

• subagent — run/list/status/result/interrupt/resume subagent runs.
• subagent_worker — hidden ToolGateway worker used to execute persisted background runs.
• subagent_assign_task — compatibility/manual path for assigning existing task items or ad-hoc task text to a profile; the primary flow is creating task items with assignment.agent and starting the task.

Task-bound orchestration tools (task_delegate, task_join, task_delegations, and related helpers) can link subagent runs to task-list items and join canonical result artifacts.

The extension also contributes a subagents skill. Dex injects extension skills into the parent agent system prompt, so the main agent receives operational guidance for when to delegate, how to use async status/result flows, and how to judge subagent evidence.

import { subAgentsExtension } from "@dex-ai/sub-agents";

const extension = subAgentsExtension();

Install this package as a Dex extension instead of adding it as a built-in dependency of host packages. For local development, install it from the workspace path:

dex extension install file:/Users/klankfor/workspaces/dex/dex-ai-sub-agents

Then configure extension options through the normal Dex extension configuration mechanism. @dex-ai/sub-agents may depend on @dex-ai/coding-agent-sdk internally to construct child coding agents, but @dex-ai/coding-agent-sdk, the CLI, and other host packages should not depend on @dex-ai/sub-agents.

Profiles

Profiles are Markdown files with simple YAML-like frontmatter:

---
id: research
name: Research
description: Gather information without modifying files.
tools:
  - read
  - search
disabledTools:
  - bash
---

You are a focused research subagent.

Discovery order is:

1. Built-in profiles from this package.
2. User profiles from ~/.dex/agents.
3. Project profiles from .dex/agents.
4. Explicit profileDirs passed to subAgentsExtension().

Later profiles override earlier profiles with the same id.

Built-in profiles include research, coding, and goal. The goal profile is optional and is used when a separate validation run is useful; the orchestrating agent can also judge task completion directly from worker-provided evidence.

Result schema

There is one canonical subagent result schema. Every worker writes schemaVersion: 2 with a universal envelope:

{
  "schemaVersion": 2,
  "run": {
    "runId": "subrun_...",
    "profile": "research",
    "displayName": "Research",
    "status": "completed"
  },
  "decision": {
    "outcome": "inventoried",
    "summary": "Inventoried repositories.",
    "confidence": "high"
  },
  "findings": [
    {
      "id": "finding-1",
      "claim": "There are 15 repositories.",
      "confidence": "high",
      "evidence": ["evidence-1"]
    }
  ],
  "evidence": [
    {
      "id": "evidence-1",
      "kind": "command",
      "ref": "find . -maxdepth 1 -type d"
    }
  ],
  "changes": {
    "filesRead": [],
    "filesChanged": [],
    "commandsRun": [],
    "toolsUsed": []
  },
  "decisions": [],
  "risks": [],
  "nextSteps": []
}

Workers provide evidence-rich results but do not self-certify whether the task is complete. The orchestrating agent judges completion from the result. A separate goal run may add a validation block when stronger validation is needed for ambiguous, high-risk, or complex work.

Run artifacts

Runs are stored under dataDir or ~/.dex/subagents by default:

runs/<run-id>/request.json   # immutable request
runs/<run-id>/status.json    # atomic status/result updates
runs/<run-id>/events.jsonl   # append-only event log
assignments/<id>.json        # durable task assignments

Foreground child agents

Use createCodingAgentRunner() to execute foreground subagents by constructing child coding agents with profile-specific prompt and tool filters:

import { createCodingAgentRunner, subAgentsExtension } from "@dex-ai/sub-agents";
import { CodingAgent } from "@dex-ai/coding-agent-sdk";

subAgentsExtension({
  runner: createCodingAgentRunner({
    provider,
    model,
    providerExtension,
    createAgent: CodingAgent.create,
  }),
});

Profile tools are passed as child enabledTools; disabledTools are passed as child disabledTools.

Background runs, parallel assignment, and ToolGateway

By default, background subagent runs delegate to the hidden subagent_worker tool through the SDK ToolGateway. The worker uses the configured runner when present, otherwise it records a stub completion. You can still override backgroundToolName to delegate to a custom worker:

subAgentsExtension({
  backgroundToolName: "my_custom_subagent_worker",
});

The subagent tool persists the returned gatewayRunId, mirrors status/result updates when queried, and stops the gateway run on interrupt. backgroundToolName must not be "subagent" to avoid recursion.

Task-native assignment is the primary flow: create or update a task item with assignment.agent, then start the task. Starting the assigned task creates the subagent run and mirrors progress/final output back to task assignment status and response fields.

subagent_assign_task remains available for compatibility and ad-hoc fanout. It can create and start several assignments concurrently:

{
  "profile": "research",
  "start": true,
  "tasks": ["Investigate option A", "Investigate option B"]
}

Each started assignment gets a background run and gatewayRunId; the runs complete independently through subagent_worker.

Subagent worker events are appended to the run events.jsonl transcript and returned from subagent status/result, including progress, assistant messages, and nested tool-call inputs/outputs. This keeps subagent conversation/tool details under the parent subagent tool result instead of leaking them into the supervisor conversation.

Subagent-specific process isolation, supervisor IPC, and optional goal-validation flows should be implemented as worker tools/runners on top of these artifacts rather than duplicating generic background tool execution.