What unstable_ means, when APIs become stable, and how to track changes.
assistant-ui ships some APIs with an unstable_ prefix.
What unstable_ means
An unstable_ prefix tells you that the API is exposed publicly so you can build against it, but the surface (signature, naming, semantics, return shape) may change in any release including patch releases.
If you depend on an unstable API:
- Pin your dependency range so an automatic minor or patch update cannot rewrite the contract under you.
- Isolate the call site behind a small wrapper in your code so you can adapt to upstream changes in one place.
- Expect renames or removals when the API stabilizes; the prefix gets dropped on the stable form.
In your editor
Every experimental API carries a @deprecated tag in this form, so your editor strikes it through:
/** @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release. */Hover a struck-through API to see which kind of tag it carries. An experimental API reads Experimental since <date>; an API on its way out names its replacement instead.
typescript-eslint's @typescript-eslint/no-deprecated rule, which its strict-type-checked config enables, reports experimental APIs as well. List the ones you use in the rule's allow option.
Why we ship them
Three reasons something stays unstable_:
- The design is still in flux and we want feedback on the current shape before committing.
- The API depends on internals we are still rearranging, so the surface tracks that motion.
- The use case is real today but stable-api expectations (semver discipline, comprehensive coverage, docs) have not been met yet.
Currently unstable APIs
A non-exhaustive list of unstable_ exports surfaced in the runtime docs.
| API | Package | Notes |
|---|---|---|
unstable_createMessageConverter | @assistant-ui/react | Message-format converter used by AssistantTransport and DataStream. |
unstable_humanToolNames | @assistant-ui/react | Tool names that pause the run until a result is added via addResult. Only available on LocalRuntime; not supported in DataStream. |
unstable_threadListAdapter | @assistant-ui/react-langgraph | LangGraph thread-list adapter slot on useLangGraphRuntime. |
unstable_createLangGraphStream | @assistant-ui/react-langgraph | End-to-end cancellation primitive. |
unstable_Provider | Various adapters | Deprecated; will be removed in a future minor release. React-component face on RemoteThreadListAdapter. Must render children synchronously. useRemoteThreadListRuntime renders it only when the adapter it mounts with has one; the RemoteThreadList store entry ignores it. Prefer unstable_useAdapters. |
unstable_useAdapters | Various adapters | Hook face on RemoteThreadListAdapter. The RemoteThreadList store entry calls it. useRemoteThreadListRuntime calls it except while it renders unstable_Provider. |
unstable_capabilities | ExternalStoreRuntime | Toggle copy and other thread capabilities. |
unstable_state, unstable_annotations, unstable_data | Message metadata | Runtime-internal fields exposed for advanced use cases. |
unstable_assistantMessageId, unstable_threadId, unstable_parentId, unstable_getMessage | ChatModelRunOptions | Identifiers and accessors passed to your ChatModelAdapter.run. |
Framework adapters list their own unstable surface in the corresponding adapter pages.
When something stabilizes
Stabilization usually drops the prefix. If unstable_foo becomes stable, the new export is foo, the old name is kept as a deprecated alias for at least one minor cycle, and the changelog calls out the change.
Watch the release notes and the migration guides for transitions.