# Agents24 React

Last Updated: 2026-08-24

`@agents24/react` is the DOM-free React state layer for `@agents24/client`. It owns providers, hooks, stable optimistic message identity, thread hydration and pagination, runtime-event state projection, attach/detach/cancel behavior, attachment state, repeated HITL resume, MCP authorization state, and unmount aborts.

It does not render elements, construct routes, fetch directly, parse SSE, refresh credentials, or reference browser DOM globals. Hosts inject an `AbortControllerFactory`; `@agents24/chat-react/runtime` supplies the shared browser orchestration and `@agents24/chat-react/scaffold` supplies the complete application.

## Public API

- `Agents24Provider`
- `useAgentClient`
- `useAgentChat`
- `useAgentThreads`
- `useAgentThread`
- `useAgentRun`
- `useAgentAttachments`
- `useAgentHitl`
- `useAgentMcp`
- chat state, message, part, storage, and abort-capability types
- `getThreadActivity`, which interprets canonical `active_run` and terminal `last_run_status` summary state

```tsx
<Agents24Provider
  client={client}
  createAbortController={() => myPortableAbortController()}
>
  <MyChat />
</Agents24Provider>
```

Use `@agents24/chat-react` when the host needs the accessible browser UI or complete default application layout.

## Canonical chat parts

`ChatMessage.parts` is the canonical ordered, UI-ready projection of backend
`response_blocks`. `partsFromResponseBlocks` preserves backend order and gives
every projected part a stable `id`; tool and HITL lifecycle updates retain that
identity and position. Parts also carry optional `runId`, sequence/timestamp
metadata, and typed tool presentation data for labels, activity, grouping,
detail, child-run progress, and thread links.

This package owns the canonical state only. A host may derive a copied display
sequence, but must never mutate `message.parts`. Use
`AgentResponseTimeline` from `@agents24/chat-react/ui` for the default
presentation or its exported part primitives for a custom host timeline.

Agent-requested questions are typed `ChatHitlPart` values with `hitlKind: "user_input"`, ordered `questions`, and `allowedActions: ["respond"]`. A custom host may present the pending part in its composer and call `useAgentChat().resumeHitl(part, { action: "respond", answers })`; preserve the canonical part and let the controller reattach to the run.

Hosts may control selection with `activeThreadId`. An explicit `null` means New Chat and must not fall through to stored selection; a non-null initial value is hydrated even when it is already the initial state value. The controller adopts the backend `thread_id` from the first runtime event so a host can update its URL before the stream completes. URL shape and History API behavior remain host-owned.

`useAgentChat().submit(...)` accepts optional `requestedAgentId` and
`requestedModelId`. In a conversation-scoped BFF flow, these are preferences
only; the server validates the Agent/model against the current allowed
selection and persists preferred runtime restoration separately from the thread
identity.
