Agents24 Chat React

Last Updated: 2026-07-15

Headless React primitives for Agents24 chat surfaces.

The package owns thread hydration, older-page pagination, stream/reattach state, active run cancellation, normalized message parts, and shadcn MessageScroller primitives for latest-thread chat surfaces. Hosts provide transport routes, cache storage, product rendering, source handling, pagination triggers, and styling.

Public API

• useAgents24ChatController(options)
• MessageScroller
• LatestThreadScroller
• useMessageScroller()
• useMessageScrollerScrollable()
• useMessageScrollerVisibility()
• useStreamingText(options)
• getActiveStreamingTextPartId(message, streamingMessageId)
• isActiveStreamingTextPart(message, part, streamingMessageId)
• createFetchChatTransport(options)
• consumeSseResponse(response, onEvent, { signal })
• appendStableStreamingTurn(messages, userMessage, assistantMessage)
• upsertStableAssistantMessage(messages, input)
• normalized chat message, part, transport, and storage types
• typed V2 pendingHitl, isResolvingHitl, and resumeHitl(...) controller state/actions in the current 0.3.x contract
• strict HITL response-block parsing and waitForMcpOauthComplete(...) for validated host-owned OAuth popup completion
• partsFromResponseBlocks(blocks, fallbackText)
• renderChatPart(part, message, renderOptions)
• @agents24/chat-react/ui for shared shadcn-derived Message, Bubble, Attachment, Marker, MessageResponse, AgentChatMessage, AgentChatComposer, McpConnectRequiredCard, and Agents24 message/attachment adapters
• @agents24/chat-react/templates for the slot-based AgentChatShell starter shell

useAgents24ChatController exposes reactive threads, activeThreadId, activeThread, activeRunId, pendingHitl, isResolvingHitl, isRefreshingThreads, resumeHitl(...), loadThreadById(threadId), attachRun(runId, threadId), and startNewThread() in addition to message and stream state. It hydrates selected threads, detects active runs from active_run/last_run_status, attaches through the host transport, detaches local SSE streams on navigation, and refreshes history after terminal events. V2 resume always reattaches after successful or idempotent resolution so the backend snapshot remains authoritative.

Hosts can pass onRuntimeEvent(event, context) and onThreadDetailLoaded(detail) to layer product-specific runtime UI, trace panels, analytics, or metadata over the shared chat lifecycle without forking stream handling. That surface is enough for running-history badges and read-only live thread inspectors without a separate host-owned reattach state machine.

ChatMessage.parts is the only render model. Backend response_blocks are normalized into ordered parts such as text, tool-get_meteo, ui-blocks, reasoning, hitl, error, and data. The shared HITL action strip renders a neutral, borderless pending state and a compact terminal outcome for Tool review, MCP authentication, User Approval, and app-data permission. Tool review exposes only Allow once and Don't allow; verbose risk metadata, argument details, Edit, and Respond are not part of the chat presentation. Tool UI is client-owned through renderPart, toolRenderers, and fallbackToolRenderer; the package does not infer English tool labels or group tool rows.

MCP OAuth remains a host side effect. startMcpAuth(...) returns both authorization_url and the authoritative callback_origin; hosts open the popup and pass both values to waitForMcpOauthComplete(...) before calling resumeHitl(...). The utility verifies popup identity, callback origin, server identity, and connection UUID and owns timeout/close cleanup.

useStreamingText owns reusable visual pacing for active assistant text. It returns displayedText, isAnimating, mode, and parseIncompleteMarkdown so host renderers can pass those values into their markdown component without the package depending on any markdown/UI library. The package only chooses text timing, cache behavior, reduced-motion handling, and active text-part helpers.

Network access is always injected by the host. This browser package never requires platform API keys.

streamMessage, attachRun, and subscribeThreadEvents require owner-provided abort signals. createFetchChatTransport forwards each signal through connection setup and SSE consumption, and useAgents24ChatController aborts owned requests when it unmounts. Local abort detaches the client stream; use cancelRun when the durable backend run must also stop.

Message Lifecycle

Chat surfaces should keep active assistant turns as stable rows in messages: append the user row and assistant placeholder together, stream updates into that assistant messageId, finalize that same row in place, then clear the streaming marker. appendStableStreamingTurn and upsertStableAssistantMessage centralize that invariant for custom hosts. Avoid host-side synthetic assistant rows because removing and re-adding the same response can flicker and can make MessageScroller treat the turn as new content.

The server owns assistant projection through response_blocks and assistant_output_text. Package version 0.2.0 removes the former public textFromFinalOutput helper; clients must not infer chat text from workflow final_output.

MessageScroller Behavior

The package re-exports shadcn @shadcn/react/message-scroller and provides LatestThreadScroller, a thin native preset around the official primitives. Host chat shells should prefer:

• LatestThreadScroller.Provider
• LatestThreadScroller.Root
• LatestThreadScroller.Viewport
• LatestThreadScroller.Content
• LatestThreadScroller.Item
• LatestThreadScroller.Button
• LatestThreadScroller.Outline

The preset defaults to autoScroll, defaultScrollPosition="last-anchor", scrollPreviousItemPeek={64}, and preserveScrollOnPrepend. Each item requires a stable messageId; callers set scrollAnchor on turn-start rows. MessageScroller owns anchoring, stream follow, detach/reattach, resize handling, visibility, outline jumping, and the latest button state. Hosts keep only product pagination triggers for loading older data and product message rendering.

Shared UI Subpaths

@agents24/chat-react/ui contains package-owned source adapted from the shadcn CLI message, bubble, attachment, and marker components. Base primitive names stay close to shadcn, while Agents24-specific compatibility adapters sit beside them as Message, MessageContent, MessageActions, MessageAction, MessageAttachments, MessageAttachment, and MessageResponse.

AgentChatMessage and AgentChatComposer provide the default customer starter UI used by AgentChatShell consumers that want a platform-playground-like baseline without importing platform internals. Hosts can still replace assistant/user message bodies, actions, HITL side effects, and toolbar controls through composition slots.

AgentChatMessage collapses long user messages by default to keep bubbles compact. The default user bubble shows a four-line preview with Show more / Show less controls, and hosts can tune the threshold, visible lines, or labels through the userMessage* props.

@agents24/chat-react/templates exposes AgentChatShell, a convenience shell that composes LatestThreadScroller, the outline rail, latest button, composer overlay spacing, older-history trigger, scroll-state reporting, and message slots. Product apps still own transport, citations, TTS, source panes, artifact actions, and row-specific rendering.

The starter shell is suitable for public/shared chat pages and customer apps. Internal playground/admin controls such as traces, debug actions, source viewers, citations, TTS, artifacts, and approval side effects remain host-owned extensions.