# Subagent (/docs/agent-ui/components/subagent)

Use a subagent when an agent hands part of its work to another agent. It shows the subagent's avatar, name and status, the steps it takes nested under it, a Stop button while you offer one, and its result once it's done.

<Example caption="Press Code reviewer, or focus it and press Enter or Space, to hide the tools it called. The result stays in view.">
<i />

```tsx
import type { ToolCall } from "@kind-ui/agent-ui";
import { Subagent } from "@/components/ui/subagent";
import { Tool } from "@/components/ui/tool";

const calls: ToolCall[] = [
  {
    toolCallId: "call_1",
    name: "read_file",
    dynamic: false,
    input: { state: "ready", value: { path: "src/retry.ts" } },
    output: { state: "available", value: "export async function retry(fn, attempts = 3) { … }" },
  },
  {
    toolCallId: "call_2",
    name: "run_tests",
    dynamic: false,
    input: { state: "ready", value: { filter: "retry" } },
    output: { state: "available", value: { passed: 12, failed: 0 } },
  },
];

export default function SubagentExample() {
  return (
    <Subagent
      agentName="Code reviewer"
      status="complete"
      durationSeconds={14}
      defaultOpen
      result="Looks good. `retry` waits **twice as long** after each failure, and all 12 tests pass."
    >
      {calls.map((call) => (
        <Tool key={call.toolCallId} call={call} />
      ))}
    </Subagent>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/subagent
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/subagent-web
```

## Composition [#composition]

```text
Subagent
├── SubagentTrigger
│   ├── SubagentAvatar
│   ├── SubagentTitle
│   ├── SubagentIcon
│   └── SubagentMeta
├── SubagentContent
│   └── SubagentChildren
├── SubagentCancel
└── SubagentResult
```

`Subagent` renders these parts, and puts its children, the subagent's steps, in `SubagentChildren`. The trigger is a native button that shows or hides them. `SubagentAvatar` is a UI SDK Avatar of `avatarSrc`, showing the initials of `agentName` until the image loads or without one. `SubagentTitle` shows the `label`, else the `agentName`. `SubagentIcon` is the status mark, and `SubagentMeta` the status in words, like "Working" or "Done in 14 s". `SubagentCancel` renders only while the subagent can be stopped, and `SubagentResult` only once it's complete. To arrange the parts yourself, render them inside `SubagentRoot`.

## Usage [#usage]

### Steps [#steps]

Pass the subagent's steps as children, like a [Tool](./tool.mdx) for each call it makes, and append new ones as they arrive. Each is its own Tab stop; to make them one, wrap them in a [StepList](./step.mdx) and join each trigger to it with `StepListItem`. A step you remove leaves at once.

```tsx
<Subagent agentName="Code reviewer" status="running">
  <StepList aria-label="Code reviewer's steps">
    {calls.map((call) => (
      <Tool key={call.toolCallId} call={call}>
        <StepListItem value={call.toolCallId} render={<ToolTrigger />}>
          <ToolIcon />
          <ToolTitle />
        </StepListItem>
        <ToolContent>
          <ToolInput />
          <ToolOutput />
        </ToolContent>
      </Tool>
    ))}
  </StepList>
</Subagent>
```

### Result [#result]

Pass the subagent's final answer as `result`, in Markdown. It shows under the steps once the status is `complete`, and stays in view when the steps close. Pass `SubagentResult` children to render it yourself.

### Stopping [#stopping]

Pass `onCancel` to show **Stop** while the status is `pending`, `running` or `awaiting-input`. Return a promise to keep the button pending until it settles: a second press does nothing meanwhile, and a rejection makes it available again. Once the subagent stops, set its `status` to `cancelled`, and the button goes away. If it had focus, focus moves to the trigger.

### Opening and Closing [#opening-and-closing]

The subagent opens and closes like a [Step](./step.mdx): it opens while it runs or waits for input and closes when it completes, until someone opens or closes it. Pass `open` with `onOpenChange` to control it.

### Streaming [#streaming]

New steps grow the content below the ones before, so the header and earlier steps never move. A status change morphs only the mark and the words beside it, and the result fades in once, when the subagent completes. Screen readers hear the subagent's name and its outcome when it needs input, completes, fails or is cancelled.

### Motion [#motion]

The mark morphs between statuses, the steps grow open and shut, and the result fades in. Under `prefers-reduced-motion`, or with `motion="reduced"`, the steps and result fade over 120 ms instead and nothing moves or spins, and with `motion="none"` everything changes at once.

## API Reference [#api-reference]

### SubagentOptions

| Prop               | Type                                                                                   | Description                                                                                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status?`          | `"awaiting-input" \| "cancelled" \| "complete" \| "error" \| "pending" \| "running"`   | What the step is doing. The icon shows it. Default: `"pending"`                                                                                                                                      |
| `kind?`            | `string \| undefined`                                                                  | Written as `data-kind`, for styling by step type.                                                                                                                                                    |
| `label?`           | `string \| undefined`                                                                  | Names the step in announcements. Defaults to the title part's text.                                                                                                                                  |
| `open?`            | `boolean \| undefined`                                                                 | Whether the content shows. Passing it controls it: change it in `onOpenChange`.                                                                                                                      |
| `defaultOpen?`     | `boolean \| undefined`                                                                 | Whether the content shows at first, when `open` isn't passed. Defaults to open while `status` is `running` or `awaiting-input`, unless `autoOpen` is `"never"`.                                      |
| `onOpenChange?`    | `((open: boolean, details: ChangeDetails<StepOpenChangeReason>) => void) \| undefined` | Called when the step opens or closes, with what caused it.                                                                                                                                           |
| `autoOpen?`        | `"never" \| "running"`                                                                 | With `"running"`, the step opens while running or awaiting input and closes on completion, until someone toggles it. With `"never"`, only a person or your code opens it. Default: `"running"`       |
| `durationSeconds?` | `number \| undefined`                                                                  | Written as `--kind-step-duration`.                                                                                                                                                                   |
| `motion?`          | `"auto" \| "none" \| "reduced"`                                                        | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                         |
| `agentName?`       | `string \| undefined`                                                                  | The subagent's name: the title, unless `label` replaces it, and the avatar's initials. Without one, the title is "Subagent" and the avatar shows "?".                                                |
| `avatarSrc?`       | `string \| undefined`                                                                  | The avatar image. Without it, or until it loads, the avatar shows the name's initials.                                                                                                               |
| `result?`          | `string \| undefined`                                                                  | The subagent's final answer, as markdown, shown once the status is `complete`.                                                                                                                       |
| `onCancel?`        | `(() => unknown) \| undefined`                                                         | Called when the subagent is stopped. Shows the Stop button while set and the subagent hasn't finished. Return a promise to keep Stop pending until it settles: a rejection makes it available again. |
| `agentConfirm?`    | `boolean \| undefined`                                                                 | Whether an agent needs a person to approve its actions on the subagent. UI SDK marks a whole component, so `expand` and `collapse` ask too. Default: `true`                                          |

### Agent [#agent]

An agent connected with `createAgent` finds the subagent by its title and reads its `open` and `status`. It can run these actions, and `cancel` only while Stop shows. While `agentConfirm` is on, every one of them waits for a person to confirm, unless the host's `allow` lets it through.

### SubagentAgentActions

| Prop       | Type                        | Description                                                                                            |
| ---------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
| `expand`   | `() => boolean`             | Opens the step. Returns whether the change was accepted.                                               |
| `collapse` | `() => boolean`             | Closes the step. Returns whether the change was accepted.                                              |
| `cancel`   | `(() => void) \| undefined` | Calls `onCancel`. Offered only while it's set, the subagent hasn't finished, and no cancel is pending. |

<Caption>
Runs in React and Web Components. On `<kind-subagent>`, props are kebab-case attributes, so `agentName` is `agent-name` and `avatarSrc` is `avatar-src`, and `onOpenChange` fires `openchange`. Stop needs the `can-cancel` attribute and fires `subagentcancel`: call `event.detail.waitUntil(promise)` to keep it pending. Write the steps inside a `<kind-subagent-content>`: the element adds its trigger before it and its Stop button and result after it, unless you wrote a trigger of its own.
</Caption>