Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions apps/website/content/docs/react/chat/guides/generative-ui.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ The native React APIs on this page are experimental, private source-build packag

The application continues to use `MessageList`, Markdown, and tool observations for the conversation. For an admitted dashboard specification it adds `RenderSpec` with a closed registry and the matching state. Keeping those paths explicit lets ordinary text remain readable while generated content uses a controlled set of components. This example waits for a confirmed layout rather than promising Angular’s progressive rendering behavior.

The default rendering of `Chat` and `MessageList` hides the tool rows of the dispatcher tools `generate_a2ui_schema`, `generate_json_render_spec` and `render_spec`, because the rendered surface replaces them; pass `genuiToolNames` to change that list, or an empty array to show every call.

The [React conversation walkthrough](/docs/react/langgraph/concepts/conversation-turns) connects this capability to requests, tools, UI state, and saved history.

## Start a conversation
Expand Down
4 changes: 4 additions & 0 deletions libs/react/src/chat/chat.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,8 @@ export interface ChatProps
readonly renderMessage?: MessageListProps['renderMessage'];
readonly className?: string;
readonly groupRelatedTools?: MessageListProps['groupRelatedTools'];
/** Generative UI dispatcher tools whose rows stay hidden; see `MessageListProps.genuiToolNames`. Keep stable. */
readonly genuiToolNames?: MessageListProps['genuiToolNames'];
readonly toolLabel?: MessageListProps['toolLabel'];
/** App-authored confirmed result previews, or `status: 'failed'` to show a completed call as failed; execution and business confirmation remain app-owned. */
readonly toolOutcome?: MessageListProps['toolOutcome'];
Expand Down Expand Up @@ -198,6 +200,7 @@ export function Chat({
renderMessage,
className,
groupRelatedTools,
genuiToolNames,
toolLabel,
toolOutcome,
renderToolCall,
Expand Down Expand Up @@ -388,6 +391,7 @@ export function Chat({
rows={rows}
renderMessage={renderMessage}
groupRelatedTools={groupRelatedTools}
genuiToolNames={genuiToolNames}
toolLabel={toolLabel}
toolOutcome={toolOutcome}
renderToolCall={renderToolCall}
Expand Down
111 changes: 111 additions & 0 deletions libs/react/src/chat/message-list-genui-tools.spec.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
import { cleanup, render } from '@testing-library/react';
import { afterEach, describe, expect, it } from 'vitest';
import {
completeDelivery,
type AgentSnapshot,
type Message,
} from '@threadplane/core';
import { createMessageContent } from '@threadplane/content/messages';
import { MessageList } from './index';

afterEach(cleanup);

type Calls = AgentSnapshot['toolCalls'];
const call = (id: string, name: string) => ({
id,
name,
args: { query: id },
status: 'complete',
result: `${id} result`,
});
function project(names: readonly string[], withToolRows = false) {
const calls = names.map((name, i) => call(`c${i}`, name));
const messages: Message[] = [
{
id: 'a',
role: 'assistant',
content: 'Answer',
delivery: completeDelivery('g', 'success'),
toolCallIds: calls.map((item) => item.id),
},
...(withToolRows
? calls.map(
(item): Message => ({
id: `t-${item.id}`,
role: 'tool',
content: `literal ${item.id}`,
delivery: completeDelivery(`t-${item.id}`, 'success'),
toolCallId: item.id,
})
)
: []),
];
return createMessageContent().project({
status: 'idle',
messages,
toolCalls: calls as unknown as Calls,
});
}
const toolIds = (container: HTMLElement) =>
[...container.querySelectorAll('.tp-tool-activity')].map((el) =>
el.getAttribute('data-tool-id')
);

describe('MessageList generative UI dispatcher tools', () => {
it.each(['generate_a2ui_schema', 'generate_json_render_spec', 'render_spec'])(
'hides the %s call by default',
(name) => {
const view = render(<MessageList rows={project([name])} />);
expect(toolIds(view.container)).toEqual([]);
expect(view.container.textContent).not.toContain(name);
expect(view.queryByText(/Used 1 tool/)).toBeNull();
}
);

it('leaves other tools alone and counts only the visible ones in the group', () => {
const view = render(
<MessageList rows={project(['lookup', 'render_spec', 'search'])} />
);
expect(toolIds(view.container)).toEqual(['c0', 'c2']);
expect(view.getByText('Used 2 tools')).toBeTruthy();
});

it('hides the tool rows that answer a hidden call', () => {
const view = render(
<MessageList rows={project(['render_spec', 'lookup'], true)} />
);
expect(view.container.textContent).not.toContain('literal c0');
expect(toolIds(view.container)).toEqual(['c1']);
});

it('hides the names given to genuiToolNames instead of the defaults', () => {
const view = render(
<MessageList
rows={project(['render_spec', 'my_dispatcher'])}
genuiToolNames={['my_dispatcher']}
/>
);
expect(toolIds(view.container)).toEqual(['c0']);
});

it('shows every call when genuiToolNames is empty', () => {
const view = render(
<MessageList rows={project(['render_spec'])} genuiToolNames={[]} />
);
expect(toolIds(view.container)).toEqual(['c0']);
});

it('keeps a hidden call visible to a custom renderMessage', () => {
const seen: string[] = [];
render(
<MessageList
rows={project(['render_spec'])}
renderMessage={(row) => {
seen.push(...row.toolCalls.map((item) => item.name));
return null;
}}
/>
);
expect(seen).toEqual(['render_spec']);
});
});
36 changes: 33 additions & 3 deletions libs/react/src/chat/message-list.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,14 @@ export interface MessageListProps<TRow extends MessageRow = MessageRow> {
readonly className?: string;
/** Group built-in tool activity by default. False renders separate tools; custom renderers keep full ownership. */
readonly groupRelatedTools?: boolean;
/**
* Names of generative UI dispatcher tools, such as `render_spec`, whose calls produce a rendered
* surface instead of visible text. The default rendering shows no tool row for them and hides the
* tool rows that answer them; a custom `renderMessage` still receives every call. Defaults to
* `generate_a2ui_schema`, `generate_json_render_spec` and `render_spec`; pass `[]` to show them.
* Keep stable like `renderMessage`.
*/
readonly genuiToolNames?: readonly string[];
/** Steps the agent declared (`snapshot.plan`); the current turn's running group lists the pending ones. */
readonly plan?: readonly AgentPlanStep[];
/** Stops the run; the current turn's running group offers it beside the elapsed time. */
Expand Down Expand Up @@ -270,6 +278,15 @@ export function repeatsToolFailure(
);
}
const NONE: ReadonlySet<string> = new Set();
/**
* Dispatcher tools whose calls produce a generated UI surface instead of visible text: the A2UI and
* json-render schema tools. Chat hides their tool rows by default, like the Angular chat.
*/
const DEFAULT_GENUI_TOOL_NAMES: readonly string[] = Object.freeze([
'generate_a2ui_schema',
'generate_json_render_spec',
'render_spec',
]);
/**
* Tool rows whose call an earlier row already shows. That row's activity, or the subagent card in its place,
* carries the result, so the default rendering skips the literal tool row instead of printing it twice.
Expand All @@ -282,6 +299,7 @@ function toolRowsShownElsewhere(
let hidden: Set<string> | undefined;
for (const row of rows) {
if (row.role !== 'tool') {
// A hidden dispatcher call counts as shown here, so the row that answers it hides too.
for (const call of row.toolCalls) shown.add(call.id);
continue;
}
Expand Down Expand Up @@ -375,6 +393,7 @@ function RowView<TRow extends MessageRow>({
prevRole,
renderMessage,
groupRelatedTools,
genuiToolNames,
toolLabel,
toolOutcome,
renderToolCall,
Expand Down Expand Up @@ -411,6 +430,7 @@ function RowView<TRow extends MessageRow>({
context: MessageListRowContext
) => ReactNode;
readonly groupRelatedTools?: boolean;
readonly genuiToolNames: ReadonlySet<string>;
readonly toolLabel?: (name: string, args?: unknown) => string | undefined;
readonly toolOutcome?: (
activity: ToolActivityInfo
Expand Down Expand Up @@ -445,9 +465,13 @@ function RowView<TRow extends MessageRow>({
const stale = new Set(staleRetries ? staleRetries.split('\n') : []);
// A call that started a child is shown as that child's card, not as a tool row.
const delegated = new Set(subagents.map((subagent) => subagent.toolCallId));
const calls = delegated.size
? row.toolCalls.filter((call) => !delegated.has(call.id))
: row.toolCalls;
// A dispatcher call is shown as the generated surface it produces, not as a tool row.
const calls =
delegated.size || genuiToolNames.size
? row.toolCalls.filter(
(call) => !delegated.has(call.id) && !genuiToolNames.has(call.name)
)
: row.toolCalls;
const repeating = new Set(retrying ? retrying.split('\n') : []);
// Read the declared label before a running retry withdraws it.
const retryingLeads = new Map<string, string>();
Expand Down Expand Up @@ -667,6 +691,7 @@ export function MessageList<TRow extends MessageRow = MessageRow>({
label = 'Conversation',
className,
groupRelatedTools = true,
genuiToolNames,
toolLabel,
toolOutcome,
renderToolCall,
Expand Down Expand Up @@ -720,6 +745,10 @@ export function MessageList<TRow extends MessageRow = MessageRow>({
() => (renderMessage ? NONE : toolRowsShownElsewhere(rows)),
[renderMessage, rows]
);
const genuiNames = useMemo<ReadonlySet<string>>(
() => new Set(genuiToolNames ?? DEFAULT_GENUI_TOOL_NAMES),
[genuiToolNames]
);
// Position and the preceding role count only the rows that render.
let lastShown = rows.length - 1;
while (lastShown >= 0 && hidden.has(rows[lastShown].id)) lastShown--;
Expand Down Expand Up @@ -826,6 +855,7 @@ export function MessageList<TRow extends MessageRow = MessageRow>({
prevRole={prevRole}
renderMessage={renderMessage}
groupRelatedTools={groupRelatedTools}
genuiToolNames={genuiNames}
toolLabel={toolLabel}
toolOutcome={toolOutcome}
renderToolCall={renderToolCall}
Expand Down
Loading