Skip to main content

​
Subagent Component

The <Subagent> component wraps child components in a named execution boundary. This provides better organization, debugging visibility, and optional parallel execution.
Stable. The parallel prop is currently metadata-only and does not enforce execution semantics.
Current Implementation: Subagent provides named grouping for debugging and plan visualization. The parallel prop is currently a metadata hint only—it does not enforce parallel or sequential execution. For actual parallel execution, use the <Parallel> component which wraps children in a parallel StepRegistryProvider.

​
Usage

import { Subagent } from "smithers-orchestrator";

<Subagent name="researcher">
  <Claude>Research the topic thoroughly.</Claude>
</Subagent>

​
Props

​
name
string
A descriptive name for this subagent group. Used for debugging and logging.
​
parallel
boolean
default:"false"
When true, child Claude components execute in parallel rather than sequentially.
​
children
ReactNode
The Claude components or other content to group.

​
Examples

​
Named Groups for Organization

<SmithersProvider db={db} executionId={executionId}>
  <Subagent name="analysis">
    <Claude allowedTools={["Read", "Grep"]}>
      Analyze the codebase structure.
    </Claude>
  </Subagent>

  <Subagent name="implementation">
    <Claude allowedTools={["Read", "Edit", "Write"]}>
      Implement the feature based on analysis.
    </Claude>
  </Subagent>

  <Subagent name="testing">
    <Claude allowedTools={["Bash"]}>
      Run tests and verify implementation.
    </Claude>
  </Subagent>
</SmithersProvider>

​
Parallel Execution

The parallel prop is a metadata hint for debugging and visualization. For actual parallel execution, use the <Parallel> component: 
import { Parallel } from "smithers-orchestrator";

{/* Actual parallel execution */}
<Parallel>
  <Claude>Research React performance patterns.</Claude>
  <Claude>Research database optimization techniques.</Claude>
  <Claude>Research caching strategies.</Claude>
</Parallel>

{/* Metadata-only (does not enforce parallel execution) */}
<Subagent name="parallel-research" parallel={true}>
  <Claude>Research React performance patterns.</Claude>
</Subagent>

​
Combining Sequential and Parallel

Use <Parallel> for actual parallel execution within a workflow: 
<SmithersProvider db={db} executionId={executionId}>
  {/* Sequential: analyze first */}
  <Subagent name="analysis">
    <Claude>Analyze the current architecture.</Claude>
  </Subagent>

  {/* Parallel: research topics simultaneously */}
  <Subagent name="research">
    <Parallel>
      <Claude>Research frontend optimization.</Claude>
      <Claude>Research backend optimization.</Claude>
      <Claude>Research infrastructure options.</Claude>
    </Parallel>
  </Subagent>

  {/* Sequential: synthesize and implement */}
  <Subagent name="synthesis">
    <Claude>
      Combine the research findings and create an implementation plan.
    </Claude>
  </Subagent>
</SmithersProvider>

​
With Phase Control

function ResearchWorkflow() {
  const [phase, setPhase] = useState("gather");

  return (
    <SmithersProvider db={db} executionId={executionId} maxIterations={5}>
        <If condition={phase === "gather"}>
          <Subagent name="data-gathering" parallel={true}>
            <Claude onFinished={() => setPhase("analyze")}>
              Gather requirements from the codebase.
            </Claude>
            <Claude>
              Gather similar implementations from open source.
            </Claude>
          </Subagent>
        </If>

        <If condition={phase === "analyze"}>
          <Subagent name="analysis">
            <Claude onFinished={() => setPhase("done")}>
              Analyze gathered data and create recommendations.
            </Claude>
          </Subagent>
        </If>
    </SmithersProvider>
  );
}

​
Best Practices

Names should clearly indicate the subagent’s purpose:
// Good - descriptive
<Subagent name="security-audit">
<Subagent name="frontend-implementation">
<Subagent name="api-integration">

// Less helpful
<Subagent name="step1">
<Subagent name="agent">
Use <Parallel> (not parallel={true}) for actual parallel execution of independent tasks:
// Good - independent research tasks with actual parallel execution
<Subagent name="research">
  <Parallel>
    <Claude>Research topic A</Claude>
    <Claude>Research topic B</Claude>
  </Parallel>
</Subagent>

// Bad - second task depends on first
<Parallel>
  <Claude>Create the database schema</Claude>
  <Claude>Write queries for the schema</Claude>  {/* Needs schema first! */}
</Parallel>

SmithersProvider

Top-level workflow orchestration

Phase

Phase-based workflow control