---
title: "Agents"
description: "A selectable list of agents, grouped by availability."
category: AiAgent
status: beta
since: 0.3.4
tags: [agents, list, selection]
syncStatus: reviewed
verified: true
---

## Usage

### Basic
The caller owns `selectedId` and writes it back from `select`.
::::TuffDemoWrapper{demo="AgentsAgentsListDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const selectedId = ref<string | null>('chat')
  const agents = [
    { id: 'chat', name: 'Chat Agent', iconClass: 'i-carbon-chat', badgeText: 6 },
    { id: 'code', name: 'Code Agent', iconClass: 'i-carbon-code', badgeText: 12 },
    { id: 'legacy', name: 'Legacy Agent', disabled: true },
  ]
  </script>

  <template>
    <TxAgentsList :agents="agents" :selected-id="selectedId" @select="selectedId = $event" />
  </template>
---
::::

### Best Practices

- Keep the component at the picker layer; start conversations, fetch capabilities, and run agents in the surrounding module.
- On a localized page, pass `enabledTitle`, `disabledTitle`, and `emptyText` together.
- Use stable ids from the backend or registry, never display names that may be localized or renamed.
- Keep `badgeText` to a count, a status initial, or a short label.
- Use `loading` only for the initial fetch; put per-agent run status in that item's description or badge instead of blocking the list.

## API Reference

### TxAgentsList

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `agents` | `AgentItemProps[]` | required | Agent records; enabled items render before disabled ones. |
| `selectedId` | `string \| null` | `null` | Marks the item with this id as selected. |
| `loading` | `boolean` | `false` | Shows four skeleton rows instead of the groups. |
| `enabledTitle` | `string` | `'Enabled'` | Title of the enabled group. |
| `disabledTitle` | `string` | `'Disabled'` | Title of the `disabled=true` group. |
| `emptyText` | `string` | `'No agents'` | Shown when `agents` is empty and the list is not loading. |

#### Events

| Event | Payload | Description |
|------|---------|-------------|
| `select` | `string` | Re-emits the id selected in an enabled `TxAgentItem`. |

### TxAgentItem

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | required | Stable id emitted through `select`. |
| `name` | `string` | required | Primary label. |
| `description` | `string` | `''` | Secondary text. |
| `iconClass` | `string` | `'i-carbon-bot'` | Icon class shown in the avatar area. |
| `selected` | `boolean` | `false` | Applies active styling and `aria-selected=true`. |
| `disabled` | `boolean` | `false` | Blocks click, Enter, and Space selection and applies `aria-disabled=true`. |
| `badgeText` | `string \| number` | `''` | Right-side badge; an empty string, `null`, or `undefined` renders none. |

#### Events

| Event | Payload | Description |
|------|---------|-------------|
| `select` | `string` | Fires when an enabled item is activated by click, Enter, or Space. |

#### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `badge` | - | Replaces the badge content when `badgeText` is set. |

## Overview

- `TxAgentsList` splits `agents` into enabled and disabled groups by `disabled`, keeps the original order within each, and shows each group's count in its header.
- `loading` wins over both the groups and the empty state.
- Each group body is a `role="listbox"` labelled by its title; each item is a `role="option"`.
- Disabled items keep the `option` role; `aria-disabled` and a click guard block their selection.

## Technologies

- `TxAgentItem` is built on `TxCardItem` with a fixed `rounded` avatar shape.
- Source: `packages/tuffex/packages/components/src/agents/`.

<TuffDocSourceLink />