Skip to content

Commit ac045ac

Browse files
AbhinRustagiAbhinRustagi
committed
fix: docs
1 parent 2150702 commit ac045ac

3 files changed

Lines changed: 226 additions & 156 deletions

File tree

‎docs/content/docs/agent/guides/migrating.mdx‎

Lines changed: 65 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,11 @@ The legacy chat component took its backend wiring as a flat bag of props — `ap
77

88
The whole migration, in one idea: the flat backend props are **removed** (not deprecated), and their values move into `fetchLLM({ ... })` for the LLM and `restStorage({ ... })` for threads.
99

10-
<Callout type="info">Everything imports from `@openuidev/react-ui`: `AgentInterface`, the `fetchLLM` / `restStorage` / `defineArtifactRenderer` factories, the stream adapters, the message formats, and hooks like `useArtifactList`.</Callout>
10+
<Callout type="info">
11+
Everything imports from `@openuidev/react-ui`: `AgentInterface`, the `fetchLLM` / `restStorage` /
12+
`defineArtifactRenderer` factories, the stream adapters, the message formats, and hooks like
13+
`useArtifactList`.
14+
</Callout>
1115

1216
## The whole diff
1317

@@ -22,13 +26,19 @@ If you were on the common setup — POST to a route, REST-backed threads — the
2226
streamProtocol="openai"
2327
messageFormat="openai"
2428
threadApiUrl="/api/threads"
25-
/>;
29+
/>
2630
```
2731

2832
**After:**
2933

3034
```tsx
31-
import { AgentInterface, fetchLLM, restStorage, openAIAdapter, openAIMessageFormat } from "@openuidev/react-ui";
35+
import {
36+
AgentInterface,
37+
fetchLLM,
38+
restStorage,
39+
openAIAdapter,
40+
openAIMessageFormat,
41+
} from "@openuidev/react-ui";
3242

3343
const llm = fetchLLM({
3444
url: "/api/chat",
@@ -48,23 +58,23 @@ Your route handler doesn't change: `fetchLLM` POSTs the same `{ threadId, messag
4858

4959
## Old → new at a glance
5060

51-
| Legacy flat prop | New home | Notes |
52-
|------------------|----------|-------|
53-
| `apiUrl` | `fetchLLM({ url })` | The LLM endpoint moves into the factory's `url`. |
54-
| `streamProtocol` | `fetchLLM({ streamAdapter })` | String enum → a stream-adapter **factory call** (`openAIAdapter()`). |
55-
| `messageFormat` | `fetchLLM({ messageFormat })` *(and `restStorage({ messageFormat })`)* | String enum → a `MessageFormat` value (`openAIMessageFormat`). |
56-
| `processMessage` | `ChatLLM.send` | Custom send logic becomes a `send` implementation. `abortController` → the `signal` you receive. |
57-
| `threadApiUrl` | `restStorage({ baseUrl })` | The thread REST root moves into `restStorage`. |
58-
| `fetchThreadList` | `storage.thread.listThreads` | Now takes an optional cursor; returns `{ threads, nextCursor? }`. |
59-
| `createThread` | `storage.thread.createThread` | Receives the first `UserMessage`, returns the new `Thread`. |
60-
| `updateThread` | `storage.thread.updateThread` | Takes a full `Thread`, returns the updated `Thread`. |
61-
| `deleteThread` | `storage.thread.deleteThread` | Takes an id. |
62-
| `loadThread` | `storage.thread.getMessages` | Renamed; takes a `threadId`, returns `Message[]`. |
63-
| `appRenderers` | `artifactRenderers` | Prop rename; array of renderer configs. |
64-
| `defineAppRenderer` | `defineArtifactRenderer` | `kind` → `type`; `toolName` is `string \| string[]`; parser returns `{ props, meta }`. |
65-
| `useAppList` | `useArtifactList` | Hook rename; per-thread artifact registry. |
66-
| `Artifact*` panel APIs | `DetailedView*` | The in-thread panel hooks were renamed around "detailed view." |
67-
| legacy chat component | `AgentInterface` | Component rename, same package. |
61+
| Legacy flat prop | New home | Notes |
62+
| ---------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
63+
| `apiUrl` | `fetchLLM({ url })` | The LLM endpoint moves into the factory's `url`. |
64+
| `streamProtocol` | `fetchLLM({ streamAdapter })` | String enum → a stream-adapter **factory call** (`openAIAdapter()`). |
65+
| `messageFormat` | `fetchLLM({ messageFormat })` _(and `restStorage({ messageFormat })`)_ | String enum → a `MessageFormat` value (`openAIMessageFormat`). |
66+
| `processMessage` | `ChatLLM.send` | Custom send logic becomes a `send` implementation. `abortController` → the `signal` you receive. |
67+
| `threadApiUrl` | `restStorage({ baseUrl })` | The thread REST root moves into `restStorage`. |
68+
| `fetchThreadList` | `storage.thread.listThreads` | Now takes an optional cursor; returns `{ threads, nextCursor? }`. |
69+
| `createThread` | `storage.thread.createThread` | Receives the first `UserMessage`, returns the new `Thread`. |
70+
| `updateThread` | `storage.thread.updateThread` | Takes a full `Thread`, returns the updated `Thread`. |
71+
| `deleteThread` | `storage.thread.deleteThread` | Takes an id. |
72+
| `loadThread` | `storage.thread.getMessages` | Renamed; takes a `threadId`, returns `Message[]`. |
73+
| `appRenderers` | `artifactRenderers` | Prop rename; array of renderer configs. |
74+
| `defineAppRenderer` | `defineArtifactRenderer` | `kind` → `type`; `toolName` is `string \| string[]`; parser returns `{ props, meta }`. |
75+
| `useAppList` | `useArtifactList` | Hook rename; per-thread artifact registry. |
76+
| `Artifact*` panel APIs | `DetailedView*` | The in-thread panel hooks were renamed around "detailed view." |
77+
| legacy chat component | `AgentInterface` | Component rename, same package. |
6878

6979
## LLM props → `llm`
7080

@@ -89,7 +99,7 @@ If `processMessage` did something `fetchLLM` can't express — a non-`fetch` tra
8999
signal: abortController.signal,
90100
});
91101
}}
92-
/>;
102+
/>
93103
```
94104

95105
**After** — `send` receives the `signal` directly, and the parser moves onto the object as `streamProtocol`:
@@ -116,7 +126,7 @@ The behavior change to internalize: **you no longer create or own an `AbortContr
116126

117127
## Thread props → `storage`
118128

119-
`threadApiUrl` plus the per-operation callbacks become a single `ChatStorage` whose `thread` member holds the five required methods.
129+
`threadApiUrl` plus the per-operation callbacks become a single `ChatStorage` whose `thread` member implements the interface.
120130

121131
### The REST case → `restStorage`
122132

@@ -132,7 +142,10 @@ const storage = restStorage({ baseUrl: "/api/threads" }); // was threadApiUrl
132142

133143
`restStorage` hits the exact endpoints the old `threadApiUrl` prop did — `GET {baseUrl}/get`, `POST {baseUrl}/create`, `GET {baseUrl}/get/{threadId}`, `PATCH {baseUrl}/update/{id}`, `DELETE {baseUrl}/delete/{id}` — so an existing backend keeps working. Pass `messageFormat` here too if your backend stores messages in a provider shape.
134144

135-
<Callout type="info">If you pass no `storage` at all, `AgentInterface` uses an internal in-memory store — fine for prototyping, but wiped on reload.</Callout>
145+
<Callout type="info">
146+
If you pass no `storage` at all, `AgentInterface` uses an internal in-memory store — fine for
147+
prototyping, but wiped on reload.
148+
</Callout>
136149

137150
### Custom thread callbacks → `storage.thread.*`
138151

@@ -144,10 +157,10 @@ import { AgentInterface, type ChatStorage } from "@openuidev/react-ui";
144157
const storage: ChatStorage = {
145158
thread: {
146159
listThreads: fetchThreadList, // now takes an optional cursor, returns { threads, nextCursor? }
147-
createThread, // receives the first UserMessage, returns the new Thread
148-
getMessages: loadThread, // was loadThread — takes threadId, returns Message[]
149-
updateThread, // takes a full Thread, returns the updated Thread
150-
deleteThread, // takes an id
160+
createThread, // receives the first UserMessage, returns the new Thread
161+
getMessages: loadThread, // was loadThread — takes threadId, returns Message[]
162+
updateThread, // takes a full Thread, returns the updated Thread
163+
deleteThread, // takes an id
151164
},
152165
};
153166

@@ -164,13 +177,13 @@ The "app renderer" concept was renamed to **artifact renderer** throughout — t
164177
import { AgentInterface, defineArtifactRenderer } from "@openuidev/react-ui";
165178

166179
const codeArtifactRenderer = defineArtifactRenderer({
167-
type: "code_artifact", // was kind
168-
toolName: "create_code_artifact", // now string | string[]
180+
type: "code_artifact", // was kind
181+
toolName: "create_code_artifact", // now string | string[]
169182
parser: ({ args, response }, { isStreaming }) => {
170183
const data = response as CodeArtifact | null;
171-
if (!data) return null; // tolerate partial data while streaming
184+
if (!data) return null; // tolerate partial data while streaming
172185
return {
173-
props: data, // props AND meta now come from one return value
186+
props: data, // props AND meta now come from one return value
174187
meta: isStreaming ? null : { id: `code:${data.title}`, version: 1, heading: data.title },
175188
};
176189
},
@@ -185,7 +198,7 @@ The behavior changes inside the renderer:
185198

186199
- **`kind` → `type`.** A literal string that links the renderer to its stored artifacts' `type`.
187200
- **`toolName` is now `string | string[]`.** Register one renderer for several tools by passing an array. Names are **literal only** — no RegExp. First registration wins on a duplicate `toolName`.
188-
- **The parser returns `{ props, meta }` (or `null`), not props alone.** `meta` is `{ id, version, heading } | null`: return the object to render *and* register the artifact in the thread (so it appears in the Workspace rail and artifact lists); return `null` for `meta` to render without registering (the common move while streaming). Returning `null` from the parser entirely skips rendering.
201+
- **The parser returns `{ props, meta }` (or `null`), not props alone.** `meta` is `{ id, version, heading } | null`: return the object to render _and_ register the artifact in the thread (so it appears in the Workspace rail and artifact lists); return `null` for `meta` to render without registering (the common move while streaming). Returning `null` from the parser entirely skips rendering.
189202
- **The parser must tolerate partial data.** It's called on every stream update — `response` is `null` until the result lands, and `args` may be a partial JSON string. Guard accordingly.
190203

191204
## Hooks and panel APIs
@@ -201,7 +214,11 @@ const codeArtifacts = useArtifactList({ type: ["code_artifact"] });
201214

202215
The in-thread panel hooks that used to be named around "Artifact" are now named around **detailed view**: `useActiveDetailedView()`, `useDetailedView(viewId)`, `useDetailedViewStore()`, `useDetailedViewPortalTarget()`. If you reached into the old `Artifact*` panel hooks, swap to these.
203216

204-
<Callout type="info">"Artifact" now consistently means the durable output (a dashboard, report, app); "detailed view" means the in-thread panel that shows one. The old "app" / "Artifact panel" naming conflated the two.</Callout>
217+
<Callout type="info">
218+
"Artifact" now consistently means the durable output (a dashboard, report, app); "detailed view"
219+
means the in-thread panel that shows one. The old "app" / "Artifact panel" naming conflated the
220+
two.
221+
</Callout>
205222

206223
## Migration checklist
207224

@@ -217,9 +234,19 @@ The in-thread panel hooks that used to be named around "Artifact" are now named
217234
## Related
218235

219236
<Cards>
220-
<Card title="AgentInterface props" href="/docs/agent/reference/agentinterface-props">The presentation props that stay flat on the component.</Card>
221-
<Card title="Adapters & formats" href="/docs/agent/reference/adapters-and-formats">Reference for `fetchLLM`, `restStorage`, stream adapters, and message formats.</Card>
222-
<Card title="defineArtifactRenderer" href="/docs/agent/reference/define-artifact-renderer">The renderer config, parser contract, and `meta` shape.</Card>
223-
<Card title="Conversations" href="/docs/agent/core-concepts/conversations">How `llm` and `storage` drive a thread end to end.</Card>
224-
<Card title="Hooks" href="/docs/agent/reference/hooks">`useArtifactList`, the `DetailedView*` hooks, and more.</Card>
237+
<Card title="AgentInterface props" href="/docs/agent/reference/agentinterface-props">
238+
The presentation props that stay flat on the component.
239+
</Card>
240+
<Card title="Adapters & formats" href="/docs/agent/reference/adapters-and-formats">
241+
Reference for `fetchLLM`, `restStorage`, stream adapters, and message formats.
242+
</Card>
243+
<Card title="defineArtifactRenderer" href="/docs/agent/reference/define-artifact-renderer">
244+
The renderer config, parser contract, and `meta` shape.
245+
</Card>
246+
<Card title="Conversations" href="/docs/agent/core-concepts/conversations">
247+
How `llm` and `storage` drive a thread end to end.
248+
</Card>
249+
<Card title="Hooks" href="/docs/agent/reference/hooks">
250+
`useArtifactList`, the `DetailedView*` hooks, and more.
251+
</Card>
225252
</Cards>

0 commit comments

Comments
 (0)