Koala UI

Agent Tree

Pro

The shape of a multi-agent run: who handed work to whom, what each agent is on, where the run is stuck and what it has cost so far.

Batch of 50 invoices

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add agent-tree

Usage#

The tree draws what you give it and fetches nothing. Keep your run in state, from polling, a socket or a stream, and render one node per agent, nesting the agents each one started.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Get the code

Have a license? Unlock it here

Anatomy#

import {  AgentTree,  AgentTreeHeader,  AgentTreeTitle,  AgentTreeSummary,  AgentTreeCount,  AgentTreeContent,  AgentTreeNode,  AgentTreeNodeCard,  AgentTreeNodeHead,  AgentTreeNodeMark,  AgentTreeNodeName,  AgentTreeNodeKind,  AgentTreeNodeStatus,  AgentTreeNodeTask,  AgentTreeNodeMeta,  AgentTreeNodeSources,  AgentTreeNodeElapsed,  AgentTreeNodeCost,  AgentTreeChildren,} from "@/components/ui/agent-tree"

Org chart#

With layout="org" the agents hang below the one that started them, joined by lines. When the tree is wider than its container it scrolls inside itself instead of pushing the page.

Customer ledger migration

  • Running
    Ledger move
    Moving the customer ledger to the new cluster
    Lead19m 00s$0.64
    • Running
      Schema
      Mapping 14 tables, 9 done
      Mapping13m 40s$0.91
      • Done
        Columns
        Widened 6 amount columns
        Types4m 20s$0.07
      • Running
        Indexes
        Rebuilding the invoice index
        Tuning5m 00s$0.05
    • Needs you
      Backfill
      Approve writing 2.1M rows
      Writes10m 10s$0.33
    • Idle
      Verify
      Starts after the backfill
      Checks0s

Layout#

The default, auto, works out how wide the org chart would be and uses it only while it fits. Narrow the window and the same run turns into an indented outline with guide lines, so a sidebar or a phone never scrolls sideways.

Support triage

Outline#

The outline fits a side panel. The guide line leaves each parent from under its mark, and compact density tightens the cards for a dense app shell.

  • Running
    Triage
    120 tickets, 84 sorted
    Lead9m 00s$0.22
    • Done
      Classifier
      Tagged 120 tickets
      3m 40s$0.09
    • Running
      Refunds
      Drafting 12 refund replies
      Drafts5m 00s$0.31
      • Running
        Order lookup
        Reading order #20418
        2m 00s$0.04
    • Failed
      Escalations
      Lost access to the on-call rota
      2m 30s$0.11

Folding#

A folded branch keeps reporting: its toggle rolls up the state of every agent under it, so a sub-agent that needs you still shows. Click the toggle, or press Left and Right on a focused agent.

  • Running
    Ledger move
    Moving the customer ledger to the new cluster
    Lead19m 00s$0.64
    • Running
      Schema
      Mapping 14 tables, 9 done
      Mapping13m 40s$0.91
      • Done
        Columns
        Widened 6 amount columns
        Types4m 20s$0.07
      • Running
        Indexes
        Rebuilding the invoice index
        Tuning5m 00s$0.05
    • Needs you
      Backfill
      Approve writing 2.1M rows
      Writes10m 10s$0.33
    • Idle
      Verify
      Starts after the backfill
      Checks0s

States#

The same five states as Agent Monitor. Only a running agent pings and only one that needs you blinks and turns its card amber, so the eye goes where it is needed.

  • Running
    Capture
    Reading invoice 32 of 50
  • Needs you
    Supplier check
    Approve the new IBAN
  • Failed
    Bank feed
    The bank refused the token
  • Idle
    Reconcile
    Starts after the match
  • Done
    Duplicates
    No duplicate invoices

API reference#

AgentTree

The run and the context every part reads. It counts the agents it holds, so the summary and the folded branches add themselves up. Every part accepts className, merged last.

PropTypeDefaultDescription
layout"auto" | "org" | "outline""auto"org hangs agents below the one that started them, outline indents them in a column, and auto uses org only while it fits the container.
valuestring-The selected agent, when you control it. Setting value, defaultValue or onValueChange makes the cards selectable.
defaultValuestring-The agent selected on the first render.
onValueChange(value: string) => void-An agent was picked with a click, Enter or Space.
nownumber-The current time in epoch milliseconds. Pass it when your runtime owns the clock; otherwise running timers share one internal clock.
formatCost(value: number) => string$0.00Formats every cost, on the cards and in the summary.
labelsPartial<AgentTreeLabels>-Replaces the status names and the summary words, to translate them.
variant"card" | "plain""card"A framed surface, or no chrome for a full page.
density"comfortable" | "compact"-Card padding and spacing. Reads DensityProvider when unset.

AgentTreeSummary

Agents, running, needing you, failed and the total cost, counted from the nodes. The figures roll when they change. Children replace the counts, for instance with your own AgentTreeCounts.

PropTypeDefaultDescription
costbooleantrueShows the total of every AgentTreeNodeCost.

AgentTreeCount

One figure of the summary. Children replace the label.

PropTypeDefaultDescription
count*number-The figure, in tabular numerals.
status"working" | "waiting" | "idle" | "done" | "failed"-Adds the status dot and its default label.

AgentTreeContent

The tree itself (role="tree") and the box layout="auto" measures. In org it scrolls sideways inside itself rather than overflow the page. Arrow keys move between agents, Right opens a branch and Left folds it. Name it with aria-label.

AgentTreeNode

One agent (role="treeitem"). Holds its AgentTreeNodeCard and, when it started others, an AgentTreeChildren.

PropTypeDefaultDescription
value*string-A unique id within the tree.
status"working" | "waiting" | "idle" | "done" | "failed""idle"Tones the card and its mark, and is read out by a screen reader.
defaultOpenbooleantrueWhether its branch starts open.
openboolean-The branch state, when you control it.
onOpenChange(open: boolean) => void-The branch was folded or opened.

AgentTreeNodeCard

The card of an agent. A node with children grows a fold toggle on its lower edge, showing the count when open and a roll-up such as "1 needs you, 2 running" when folded.

AgentTreeNodeMark

A square for the agent's icon, with a status dot on its corner. A running agent gets a ring.

AgentTreeNodeStatus

The status as a word. Needs you and Failed turn into a tinted badge so they stand out. Children replace the label.

AgentTreeNodeTask

The one line that says what the agent is on. A new task slides in where the old one was.

PropTypeDefaultDescription
children*string-The current task.

AgentTreeNodeElapsed

How long the agent has run, in tabular numerals.

PropTypeDefaultDescription
sincenumber-Start time in epoch milliseconds. Ticks until until is set.
untilnumber-Stops the timer at this time.
valuenumber-A duration in milliseconds you already have, in place of since.

AgentTreeNodeCost

What the agent has cost so far, formatted by formatCost. It also feeds the summary total.

PropTypeDefaultDescription
value*number-The amount.

AgentTreeNodeSources

A row of small icons for the tools or sources the agent is using.

FAQ#

From you. The tree has no connection of its own: render your run as nested nodes and it redraws when your state changes. New agents grow in under their parent.