Agents | Tuff Docs

Usage

Bind selectedId in the caller and update it from select. Use custom group titles when the list is shown outside an English-only surface.

Loading demo...

Keep this component at the picker layer. Start conversations, fetch capabilities, and run agents in the surrounding feature module.
Provide localized enabledTitle, disabledTitle, and emptyText when the surrounding page is localized.
Use stable ids from backend or registry data; avoid display names as ids because names may be localized or renamed.
Keep badgeText short: counts, status initials, or compact labels. Use the badge slot only when the badge needs custom visuals.
Use loading for initial data fetches. For per-agent execution status, add status text or badges to each agent record instead of blocking the whole list.

Prop	Type	Default	Description
`agents`	`AgentItemProps[]`	required	Agent records. Enabled items render before disabled items.
`selectedId`	`string \| null`	`null`	Marks the matching agent item as selected.
`loading`	`boolean`	`false`	Shows four list-item skeleton rows instead of agent groups.
`enabledTitle`	`string`	`'Enabled'`	Section title for agents where `disabled` is not set.
`disabledTitle`	`string`	`'Disabled'`	Section title for agents where `disabled=true`.
`emptyText`	`string`	`'No agents'`	Empty-state text when `agents` is empty and the list is not loading.

Event	Payload	Description
`select`	`string`	Re-emitted from enabled `TxAgentItem` rows with the selected id.

Prop	Type	Default	Description
`id`	`string`	required	Stable id emitted through `select`.
`name`	`string`	required	Primary label.
`description`	`string`	`''`	Optional secondary text.
`iconClass`	`string`	`'i-carbon-bot'`	Icon class rendered in the generated avatar area.
`selected`	`boolean`	`false`	Applies active styling and `aria-selected=true`.
`disabled`	`boolean`	`false`	Prevents click / Enter / Space selection and applies `aria-disabled=true`.
`badgeText`	`string \| number`	`''`	Optional right-side badge. Empty string, `null`, and `undefined` hide the badge slot.

TxAgentsList does not expose custom slots. Customize row-level badge visuals through TxAgentItem data/slot usage when composing items directly.

Slot	Props	Description
`badge`	-	Replaces the default right-side badge content when `badgeText` is present.

Event	Payload	Description
`select`	`string`	Emitted only when an enabled item is activated by click, Enter, or Space.

TxAgentsList computes enabled and disabled groups from the same agents array; it does not mutate or sort inside each group.
Loading state wins over list and empty rendering; agents content is ignored while loading=true.
Each group body has role="listbox" and an aria-label equal to the group title.
TxAgentItem is built on TxCardItem with role="option", avatarShape="rounded", and clickable always on so disabled rows keep their option role in the listbox; selection on disabled rows is blocked by aria-disabled and the click guard, not by dropping the role.
Disabled items suppress click, Enter, and Space selection; enabled items emit the item id for all three activation paths.

Source: packages/tuffex/packages/components/src/agents/src/TxAgentsList.vue confirms loading skeletons, enabled/disabled grouping, group badges, empty state, and select re-emit behavior.
Source: packages/tuffex/packages/components/src/agents/src/TxAgentItem.vue confirms TxCardItem composition, role="option", disabled guards, aria-selected, aria-disabled, and badge slot rendering.
Type contracts: packages/tuffex/packages/components/src/agents/src/types.ts defines AgentItemProps, AgentsListGroup, and AgentsListProps.
Verified coverage: Coverage: packages/tuffex/packages/components/src/agents/__tests__/agents.test.ts covers group titles, empty text, enabled-only selection, keyboard activation, and disabled suppression.

packages/tuffex/packages/components/src/agents/index.ts