Skip to content
WebJs
Menu

Displays a subagent run, with its tool calls and result.

Why does image optimization rerun on every deploy?
Ran the research subagent
Ran grep -rn cacheKey scripts
scripts/optimize-images.ts:14:  const cacheKey = process.env.COMMIT_SHA
Ran sed -n 13,15p scripts/optimize-images.ts
const cacheDir = ".next/cache/images"
const cacheKey = process.env.COMMIT_SHA
const cached = await restoreCache(cacheDir, cacheKey)
Ran ls public/images | wc -l
1240

The cache is keyed on the commit SHA, so every deploy misses it and optimizes all 1,240 images again.

Image optimization reruns because its cache is keyed on the commit SHA, which changes on every deploy. Key the cache on a hash of public/images instead, and unchanged images will be skipped.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, CircleCheckIcon } from '#lib/ui/lucide.ts';

const question = 'Why does image optimization rerun on every deploy?';
const report =
  'The cache is keyed on the commit SHA, so every deploy misses it and optimizes all 1,240 images again.';
const answer =
  'Image optimization reruns because its cache is keyed on the commit SHA, which changes on every deploy. Key the cache on a hash of public/images instead, and unchanged images will be skipped.';

const steps = [
  {
    command: 'grep -rn cacheKey scripts',
    stdout: 'scripts/optimize-images.ts:14:  const cacheKey = process.env.COMMIT_SHA',
  },
  {
    command: 'sed -n 13,15p scripts/optimize-images.ts',
    stdout:
      'const cacheDir = ".next/cache/images"\nconst cacheKey = process.env.COMMIT_SHA\nconst cached = await restoreCache(cacheDir, cacheKey)',
  },
  {
    command: 'ls public/images | wc -l',
    stdout: '1240',
  },
];

const chevron = () => html`<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform [[open]>summary>&]:rotate-90')}>${ChevronRightIcon()}</span>`;

// One finished tool call of the subagent, expanding to its output.
function StepRow(step: { command: string; stdout: string }) {
  return html`
    <details data-slot="trace-collapsible" class=${traceCollapsibleClass()}>
      <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
        <span data-slot="trace-line" class=${traceLineClass()}>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
          <span data-slot="trace-title" class=${traceTitleClass()}>Ran ${step.command}</span>
        </span>
        ${chevron()}
      </summary>
      <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
        <div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
          <pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${step.stdout}</code></pre>
        </div>
      </div>
    </details>
  `;
}

// The conversation once the subagent and the reply have finished, with the
// subagent's run left open.
export default function SubagentDemo() {
  return html`
    <div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>${question}</div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
          <div data-slot="trace" class=${traceClass()}>
            <details data-slot="trace-collapsible" open class=${traceCollapsibleClass()}>
              <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
                <span data-slot="trace-line" class=${traceLineClass()}>
                  <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
                  <span data-slot="trace-title" class=${traceTitleClass()}>Ran the research subagent</span>
                </span>
                ${chevron()}
              </summary>
              <div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'flex flex-col gap-3')}>
                <div data-slot="trace" class=${traceClass()}>
                  ${steps.map((step) => StepRow(step))}
                </div>
                <p>${report}</p>
              </div>
            </details>
          </div>
          <p>${answer}</p>
        </div>
      </div>
      <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
        Replay
      </button>
    </div>
  `;
}
View Code

Subagent is a line for work the agent hands to a subagent. The run is the title, like "Ran the research agent". Open it for the tool calls the subagent made and what it found.

Subagent is built with a trace, with a trace collapsible for the run and a nested trace for its tool calls.

Installation

Subagent is built with the Trace, Code Block and Badge components.

pnpm dlx @webjsdev/ui add trace code-block badge

Usage

import {
  traceClass,
  traceCollapsibleClass,
  traceCollapsibleContentClass,
  traceCollapsibleTriggerClass,
  traceIconClass,
  traceLineClass,
  traceTitleClass,
} from '#components/ui/trace.ts';
<div data-slot="trace" class=${traceClass()}>
  <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
    <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
          ${CircleCheckIcon()}
        </span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Ran the research agent</span>
      </span>
      <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>
        ${ChevronRightIcon()}
      </span>
    </summary>
    <div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'flex flex-col gap-3')}>
      <div data-slot="trace" class=${traceClass()}>
        <span data-slot="trace-line" class=${traceLineClass()}>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
            ${CircleCheckIcon()}
          </span>
          <span data-slot="trace-title" class=${traceTitleClass()}>Ran grep -rn cacheKey scripts</span>
        </span>
      </div>
      <p>The cache is keyed on the commit SHA.</p>
    </div>
  </details>
</div>

Running

While the subagent runs, the line has data-status="running" and its content shows the tool calls so far. Add the result when the subagent finishes.

Running the research agent
Ran grep -rn cacheKey scripts Running sed -n 13,15p scripts/optimize-images.ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, CircleCheckIcon, LoaderCircleIcon } from '#lib/ui/lucide.ts';

export default function SubagentRunning() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <details data-slot="trace-collapsible" open class=${traceCollapsibleClass()}>
        <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
          <span data-slot="trace-line" data-status="running" class=${traceLineClass()}>
            <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${LoaderCircleIcon('animate-spin')}</span>
            <span data-slot="trace-title" class=${traceTitleClass()}>Running the research agent</span>
          </span>
          <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform [[open]>summary>&]:rotate-90')}>${ChevronRightIcon()}</span>
        </summary>
        <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
          <div data-slot="trace" class=${traceClass()}>
            <span data-slot="trace-line" class=${traceLineClass()}>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
              <span data-slot="trace-title" class=${traceTitleClass()}>Ran grep -rn cacheKey scripts</span>
            </span>
            <span data-slot="trace-line" data-status="running" class=${traceLineClass()}>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${LoaderCircleIcon('animate-spin')}</span>
              <span data-slot="trace-title" class=${traceTitleClass()}>Running sed -n 13,15p scripts/optimize-images.ts</span>
            </span>
          </div>
        </div>
      </details>
    </div>
  `;
}
View Code

Details

Put the task the subagent was given at the top of the content, with its model and tools as Badge items. Show how long it ran in a trace description after the title.

Ran the research agent 48s
anthropic/claude-sonnet-4.5 runCommand

Find out why image optimization reruns on every deploy.

Ran grep -rn cacheKey scripts Ran sed -n 13,15p scripts/optimize-images.ts

The cache is keyed on the commit SHA.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { badgeClass } from '#components/ui/badge.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass, traceDescriptionClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, CircleCheckIcon } from '#lib/ui/lucide.ts';

export default function SubagentDetails() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <details data-slot="trace-collapsible" open class=${traceCollapsibleClass()}>
        <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
          <span data-slot="trace-line" class=${traceLineClass()}>
            <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
            <span data-slot="trace-title" class=${traceTitleClass()}>Ran the research agent</span>
            <span data-slot="trace-description" class=${traceDescriptionClass()}>48s</span>
          </span>
          <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform [[open]>summary>&]:rotate-90')}>${ChevronRightIcon()}</span>
        </summary>
        <div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'flex flex-col gap-3')}>
          <div class="flex flex-wrap gap-1.5">
            <span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>anthropic/claude-sonnet-4.5</span>
            <span data-slot="badge" data-variant="outline" class=${cn(badgeClass({ variant: 'outline' }), 'font-mono')}>runCommand</span>
          </div>
          <p>Find out why image optimization reruns on every deploy.</p>
          <div data-slot="trace" class=${traceClass()}>
            <span data-slot="trace-line" class=${traceLineClass()}>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
              <span data-slot="trace-title" class=${traceTitleClass()}>Ran grep -rn cacheKey scripts</span>
            </span>
            <span data-slot="trace-line" class=${traceLineClass()}>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
              <span data-slot="trace-title" class=${traceTitleClass()}>Ran sed -n 13,15p scripts/optimize-images.ts</span>
            </span>
          </div>
          <p>The cache is keyed on the commit SHA.</p>
        </div>
      </details>
    </div>
  `;
}
View Code

AI SDK

With the AI SDK, a subagent is a tool whose execute yields the subagent's UIMessage as it streams. Render the tool part as the line and part.output.parts as the nested trace. Map each nested tool part as in Tool, and see AI SDK for streaming the parts from a 'use server' action.

Each yield is a preliminary output: the part is output-available with preliminary: true. The final output replaces it, so check preliminary before you show "Ran".

Tool part stateTrace line data-statusTitle
input-streaming, input-available"running" while the chat streamsRunning …
output-available with preliminary: true"running" while the chat streamsRunning …
output-availablenoneRan …
output-error, or a running state after the chat stops"error"Failed to run …
function subagentRow(part: SubagentToolPart, streaming: boolean) {
  const done = part.state === 'output-available' && !part.preliminary;
  const running = !done && part.state !== 'output-error' && streaming;
  const parts = part.state === 'output-available' ? part.output.parts : [];

  return html`<details data-slot="trace-collapsible" open class=${traceCollapsibleClass()}>
    <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
      <span data-slot="trace-line" data-status=${done ? null : running ? 'running' : 'error'} class=${traceLineClass()}>
        <span data-slot="trace-title" class=${traceTitleClass()}>${done ? 'Ran' : running ? 'Running' : 'Failed to run'} the research agent</span>
      </span>
    </summary>
    <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
      <div data-slot="trace" class=${traceClass()}>${parts.map((nested) => toolRow(nested, running))}</div>
    </div>
  </details>`;
}

Migrating from AI SDK Elements

If you used Agent from AI SDK Elements, its wrapper lives in components/ai-elements/agent.tsx. In a WebJs app it becomes this pattern, built from WebJs UI components. Each export of the wrapper maps onto a part:

AI SDK ElementsWebJs UI
AgentA trace with a trace collapsible.
AgentHeaderThe collapsible's <summary>, holding a trace line, a trace icon and a trace title with the name, like "Ran the research agent". Show the model in a badge.
AgentContentThe trace collapsible content.
AgentTools, AgentToolA trace, with a trace line for each tool call, instead of an Accordion.
AgentInstructionsA paragraph at the top of the content.
AgentOutputA Code Block with data-size="sm".

API Reference

See Trace.