Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

💬 feat: Conversation Starters in Agent Builder (#16523)

Marco Beretta9d55dde46a71
diff --git a/client/src/common/agents-types.ts b/client/src/common/agents-types.ts
index 72834a7585..eaffe6ee17 100644
--- a/client/src/common/agents-types.ts
+++ b/client/src/common/agents-types.ts
@@ -64,6 +64,9 @@ export type AgentForm = {
[AgentCapabilities.artifacts]?: ArtifactModes | string;
recursion_limit?: number;
support_contact?: SupportContact;
+ conversation_starters?: string[];
+ /** Unsent starter text; builder-only, never sent to the API. */
+ conversation_starter_draft?: string;
category: string;
// Avatar management fields
avatar_file?: File | null;
diff --git a/client/src/components/SidePanel/Agents/AgentConfig.tsx b/client/src/components/SidePanel/Agents/AgentConfig.tsx
index 89d182583d..6e4de70689 100644
--- a/client/src/components/SidePanel/Agents/AgentConfig.tsx
+++ b/client/src/components/SidePanel/Agents/AgentConfig.tsx
@@ -12,6 +12,7 @@ import { validateEmail, cn } from '~/utils';
import Instructions from './Instructions';
import FileContext from './FileContext';
import AgentAvatar from './AgentAvatar';
+import Starters from './Starters';
import { Panel } from '~/common';
const fieldClass = 'h-9';
@@ -155,6 +156,9 @@ export default function AgentConfig() {
</div>
)}
+ {/* CONVERSATION STARTERS */}
+ <Starters />
+
{/* SUPPORT CONTACT */}
<div className="mb-3 flex flex-col">
<Label className="text-text-secondary mb-1 block text-[11px] font-medium tracking-wide uppercase">
diff --git a/client/src/components/SidePanel/Agents/AgentPanel.tsx b/client/src/components/SidePanel/Agents/AgentPanel.tsx
index 28ddc9ff72..0c5e795e1f 100644
--- a/client/src/components/SidePanel/Agents/AgentPanel.tsx
+++ b/client/src/components/SidePanel/Agents/AgentPanel.tsx
@@ -63,6 +63,57 @@ function getUpdateToastMessage(
return localize('com_assistants_update_success_name', { name: name ?? localize('com_ui_agent') });
}
+/**
+ * Starters to send with a save, or `undefined` to leave the stored list alone.
+ * An untouched list is omitted rather than rewritten: the API accepts more than
+ * the builder renders and keeps surrounding whitespace, so an unrelated save
+ * must not trim or truncate what another client stored. An edited list is sent
+ * trimmed and without blanks; the builder already stops additions at the cap.
+ */
+export function resolveConversationStarters(
+ starters: string[] | undefined,
+ stored: string[] | undefined,
+): string[] | undefined {
+ if (!Array.isArray(starters) || isEqual(starters, stored ?? [])) {
+ return undefined;
+ }
+ return starters.map((starter) => starter.trim()).filter((starter) => starter !== '');
+}
+
+/** The starters a save was submitted with, and the agent they belong to (empty for a create). */
+export type SubmittedStarters = { agentId: string; starters: string[] | undefined };
+
+/**
+ * Whether a finished save may replace the starter rows with the stored list.
+ * Only when the form still shows the agent the save was for and the rows still
+ * hold what was submitted; edits made while the request was in flight, or rows
+ * of another agent selected meanwhile, stay as they are.
+ */
+export function shouldSyncSavedStarters(
+ submitted: SubmittedStarters | null,
+ current: SubmittedStarters,
+ savedId: string,
+): boolean {
+ if (!submitted) {
+ return false;
+ }
+ const sameAgent =
+ current.agentId === submitted.agentId || (!submitted.agentId && current.agentId === savedId);
+ return sameAgent && isEqual(current.starters ?? [], submitted.starters ?? []);
+}
+
+/**
+ * Whether a finished save may be merged into the selected agent option. The
+ * option is the baseline for untouched fields such as starters, so a save that
+ * finishes after another agent was selected must not overwrite it.
+ */
+export function isSavedAgentOption(
+ option: AgentForm['agent'],
+ savedId: string,
+): option is NonNullable<AgentForm['agent']> {
+ return option != null && typeof option !== 'string' && option.id === savedId;
+}
+
/**
* Normalizes the payload sent to the agent update/create endpoints.
* Handles avatar reset requests for persistent agents independently of avatar uploads.
@@ -97,6 +148,7 @@ export function composeAgentUpdatePayload(
recursion_limit,
category,
support_contact,
+ conversation_starters,
tool_options,
skills,
skills_enabled,
@@ -169,6 +221,10 @@ export function composeAgentUpdatePayload(
recursion_limit,
category,
support_contact,
+ conversation_starters: resolveConversationStarters(
+ conversation_starters,
+ data.agent?.conversation_starters,
+ ),
tool_options: normalizedToolOptions,
skills,
skills_enabled,
@@ -225,7 +281,7 @@ export async function persistAvatarChanges({
}
const AVATAR_ONLY_DIRTY_FIELDS = new Set(['avatar_action', 'avatar_file', 'avatar_preview']);
-const IGNORED_DIRTY_FIELDS = new Set(['agent']);
+const IGNORED_DIRTY_FIELDS = new Set(['agent', 'conversation_starter_draft']);
const isNestedDirtyField = (
value: FieldNamesMarkedBoolean<AgentForm>[keyof AgentForm],
@@ -385,8 +441,26 @@ export default function AgentPanel() {
reset,
getValues,
setValue,
+ resetField,
formState: { dirtyFields },
} = methods;
+ const submittedStartersRef = useRef<SubmittedStarters | null>(null);
+ /** The save may trim or drop starters; show what was stored, not what was typed. */
+ const syncSavedStarters = useCallback(
+ (saved: Agent) => {
+ const submitted = submittedStartersRef.current;
+ submittedStartersRef.current = null;
+ const current = {
+ agentId: getValues('id') ?? '',
+ starters: getValues('conversation_starters'),
+ };
+ if (!shouldSyncSavedStarters(submitted, current, saved.id)) {
+ return;
+ }
+ resetField('conversation_starters', { defaultValue: saved.conversation_starters ?? [] });
+ },
+ [getValues, resetField],
+ );
const [isAvatarUploadInFlight, setIsAvatarUploadInFlight] = useState(false);
const uploadAvatarMutation = useUploadAgentAvatarMutation({
@@ -398,7 +472,7 @@ export default function AgentPanel() {
setValue('avatar_action', null, { shouldDirty: false });
const agentOption = getValues('agent');
- if (agentOption && typeof agentOption !== 'string') {
+ if (isSavedAgentOption(agentOption, updatedAgent.id)) {
setValue('agent', { ...agentOption, ...updatedAgent }, { shouldDirty: false });
}
},
@@ -538,8 +612,10 @@ export default function AgentPanel() {
showToast({ message: toastMessage, status: noVersionChange ? 'info' : undefined });
}
+ syncSavedStarters(data);
+
const agentOption = getValues('agent');
- if (agentOption && typeof agentOption !== 'string') {
+ if (isSavedAgentOption(agentOption, data.id)) {
setValue('agent', { ...agentOption, ...data }, { shouldDirty: false });
}
@@ -577,6 +653,7 @@ export default function AgentPanel() {
const create = useCreateAgentMutation({
onSuccess: async (data) => {
+ syncSavedStarters(data);
setCurrentAgentId(data.id);
showToast({
message: `${localize('com_assistants_create_success')} ${
@@ -637,6 +714,7 @@ export default function AgentPanel() {
}
return;
}
+ submittedStartersRef.current = { agentId: agent_id, starters: data.conversation_starters };
update.mutate({ agent_id, data: { ...basePayload, tools } });
return;
}
@@ -666,6 +744,7 @@ export default function AgentPanel() {
});
}
+ submittedStartersRef.current = { agentId: '', starters: data.conversation_starters };
create.mutate({
...basePayload,
git_identity: basePayload.git_identity ?? undefined,
diff --git a/client/src/components/SidePanel/Agents/AgentSelect.tsx b/client/src/components/SidePanel/Agents/AgentSelect.tsx
index 728180518f..c0975b98b2 100644
--- a/client/src/components/SidePanel/Agents/AgentSelect.tsx
+++ b/client/src/components/SidePanel/Agents/AgentSelect.tsx
@@ -107,6 +107,8 @@ function AgentSelect({
category: fullAgent.category || 'general',
// Make sure support_contact is properly loaded
support_contact: fullAgent.support_contact,
+ conversation_starters: fullAgent.conversation_starters ?? [],
+ conversation_starter_draft: '',
avatar_file: null,
avatar_preview: fullAgent.avatar?.filepath ?? '',
avatar_action: null,
diff --git a/client/src/components/SidePanel/Agents/Starters.tsx b/client/src/components/SidePanel/Agents/Starters.tsx
new file mode 100644
index 0000000000..0a12437391
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/Starters.tsx
@@ -0,0 +1,147 @@
+import { Plus, X } from 'lucide-react';
+import { Constants } from 'librechat-data-provider';
+import { Controller, useFormContext } from 'react-hook-form';
+import { Input, Label, Button, TooltipAnchor } from '@librechat/client';
+import type { AgentForm } from '~/common';
+import { useLocalize } from '~/hooks';
+
+function StartersField({
+ value,
+ onChange,
+ draft,
+ setDraft,
+}: {
+ value: string[];
+ onChange: (value: string[]) => void;
+ draft: string;
+ setDraft: (draft: string) => void;
+}) {
+ const localize = useLocalize();
+ const hasReachedMax = value.length >= Constants.MAX_CONVO_STARTERS;
+ const canAdd = !hasReachedMax && draft.trim() !== '';
+ const addLabel = hasReachedMax
+ ? localize('com_assistants_max_starters_reached')
+ : localize('com_ui_add');
+
+ const addStarter = () => {
+ if (!canAdd) {
+ return;
+ }
+ onChange([...value, draft.trim()]);
+ setDraft('');
+ };
+
+ return (
+ <div className="space-y-2">
+ <div className="flex items-center gap-1">
+ <Input
+ id="conversation-starters"
+ value={draft}
+ disabled={hasReachedMax}
+ className="h-9 flex-1"
+ type="text"
+ placeholder={
+ hasReachedMax
+ ? localize('com_assistants_max_starters_reached')
+ : localize('com_assistants_conversation_starters_placeholder')
+ }
+ onChange={(e) => setDraft(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key !== 'Enter') {
+ return;
+ }
+ /** Enter also commits an IME candidate; Safari reports it only through keyCode 229 */
+ if (e.nativeEvent.isComposing || e.keyCode === 229) {
+ return;
+ }
+ /** Enter would otherwise submit the whole agent form */
+ e.preventDefault();
+ addStarter();
+ }}
+ />
+ <TooltipAnchor
+ side="top"
+ description={addLabel}
+ render={
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon-sm"
+ aria-label={addLabel}
+ onClick={addStarter}
+ disabled={!canAdd}
+ >
+ <Plus className="size-4" aria-hidden="true" />
+ </Button>
+ }
+ />
+ </div>
+ {value.map((starter, index) => {
+ const deleteLabel = `${localize('com_ui_delete')}: ${starter}`;
+ return (
+ <div key={index} className="flex items-center gap-1">
+ <Input
+ value={starter}
+ className="h-9 flex-1"
+ type="text"
+ aria-label={`${localize('com_assistants_conversation_starters')} ${index + 1}`}
+ onChange={(e) => {
+ const next = [...value];
+ next[index] = e.target.value;
+ onChange(next);
+ }}
+ />
+ <TooltipAnchor
+ side="top"
+ description={localize('com_ui_delete')}
+ render={
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon-sm"
+ aria-label={deleteLabel}
+ onClick={() => onChange(value.filter((_, i) => i !== index))}
+ >
+ <X className="size-4" aria-hidden="true" />
+ </Button>
+ }
+ />
+ </div>
+ );
+ })}
+ </div>
+ );
+}
+
+export default function Starters() {
+ const localize = useLocalize();
+ const { control } = useFormContext<AgentForm>();
+
+ /** The draft is form state rather than component state: it survives switching to the
+ * Model or Advanced panel, and the reset that loads another agent clears it. */
+ return (
+ <div className="mb-3 flex flex-col">
+ <Label variant="section" className="mb-1 block" htmlFor="conversation-starters">
+ {localize('com_assistants_conversation_starters')}
+ </Label>
+ <Controller
+ name="conversation_starter_draft"
+ control={control}
+ render={({ field: draftField }) => (
+ <Controller
+ name="conversation_starters"
+ control={control}
+ render={({ field }) => (
+ <StartersField
+ value={field.value ?? []}
+ onChange={field.onChange}
+ draft={draftField.value ?? ''}
+ setDraft={draftField.onChange}
+ />
+ )}
+ />
+ )}
+ />
+ </div>
+ );
+}
diff --git a/client/src/components/SidePanel/Agents/__tests__/AgentPanel.helpers.spec.ts b/client/src/components/SidePanel/Agents/__tests__/AgentPanel.helpers.spec.ts
index b88dc7bb4f..a1466d7ae2 100644
--- a/client/src/components/SidePanel/Agents/__tests__/AgentPanel.helpers.spec.ts
+++ b/client/src/components/SidePanel/Agents/__tests__/AgentPanel.helpers.spec.ts
@@ -15,6 +15,8 @@ import {
isAvatarUploadOnlyDirty,
hasPersistedDirtyFields,
mayHavePersistedChange,
+ shouldSyncSavedStarters,
+ isSavedAgentOption,
} from '../AgentPanel';
test('the create identity contract excludes the update-only clear sentinel', () => {
@@ -282,6 +284,44 @@ describe('composeAgentUpdatePayload', () => {
expect(payload.model_parameters).toEqual(form.model_parameters);
});
+
+ it('sends edited starters trimmed and without blanks', () => {
+ const form = createForm();
+ form.agent = { conversation_starters: ['Plan my week'] } as AgentForm['agent'];
+ form.conversation_starters = [' Plan my week ', '', ' ', 'Summarize'];
+
+ const { payload } = composeAgentUpdatePayload(form, 'agent_123');
+
+ expect(payload.conversation_starters).toEqual(['Plan my week', 'Summarize']);
+ });
+
+ it('sends an empty list so removing every starter clears them', () => {
+ const form = createForm();
+ form.agent = { conversation_starters: ['Plan my week'] } as AgentForm['agent'];
+ form.conversation_starters = [];
+
+ const { payload } = composeAgentUpdatePayload(form, 'agent_123');
+
+ expect(payload.conversation_starters).toEqual([]);
+ });
+
+ it('leaves untouched stored starters alone, even past the builder cap', () => {
+ const stored = [' Padded ', 'Two', 'Three', 'Four', 'Five', 'Six'];
+ const form = createForm();
+ form.agent = { conversation_starters: stored } as AgentForm['agent'];
+ form.conversation_starters = [...stored];
+ form.name = 'Renamed';
+
+ const { payload } = composeAgentUpdatePayload(form, 'agent_123');
+
+ expect(payload.conversation_starters).toBeUndefined();
+ });
+
+ it('omits starters when the form never loaded them', () => {
+ const { payload } = composeAgentUpdatePayload(createForm(), 'agent_123');
+
+ expect(payload.conversation_starters).toBeUndefined();
+ });
});
describe('persistAvatarChanges', () => {
@@ -474,3 +514,56 @@ describe('mayHavePersistedChange', () => {
).toBe(false);
});
});
+
+describe('shouldSyncSavedStarters', () => {
+ const submitted = { agentId: 'agent_a', starters: [' Plan my week', ''] };
+
+ it('syncs when the rows still hold what the save sent for the same agent', () => {
+ expect(shouldSyncSavedStarters(submitted, { ...submitted }, 'agent_a')).toBe(true);
+ });
+
+ it('keeps starter edits made while the save was in flight', () => {
+ const current = { agentId: 'agent_a', starters: [' Plan my week', 'Typed during save'] };
+ expect(shouldSyncSavedStarters(submitted, current, 'agent_a')).toBe(false);
+ });
+
+ it('leaves the rows alone after switching to another agent during the save', () => {
+ const current = { agentId: 'agent_b', starters: submitted.starters };
+ expect(shouldSyncSavedStarters(submitted, current, 'agent_a')).toBe(false);
+ });
+
+ it('syncs a create once the form carries the new id, but not another agent', () => {
+ const created = { agentId: '', starters: ['Hi'] };
+ expect(shouldSyncSavedStarters(created, { agentId: '', starters: ['Hi'] }, 'agent_new')).toBe(
+ true,
+ );
+ expect(
+ shouldSyncSavedStarters(created, { agentId: 'agent_new', starters: ['Hi'] }, 'agent_new'),
+ ).toBe(true);
+ expect(
+ shouldSyncSavedStarters(created, { agentId: 'agent_b', starters: ['Hi'] }, 'agent_new'),
+ ).toBe(false);
+ });
+
+ it('does nothing without a submitted snapshot', () => {
+ expect(shouldSyncSavedStarters(null, { agentId: 'agent_a', starters: [] }, 'agent_a')).toBe(
+ false,
+ );
+ });
+});
+
+describe('isSavedAgentOption', () => {
+ const option = { id: 'agent_b', conversation_starters: [' B '] } as AgentForm['agent'];
+
+ it('merges a save into the option of the agent it was for', () => {
+ expect(isSavedAgentOption(option, 'agent_b')).toBe(true);
+ });
+
+ it('keeps another agent selected while the save was in flight as its own baseline', () => {
+ expect(isSavedAgentOption(option, 'agent_a')).toBe(false);
+ });
+
+ it('ignores a missing option', () => {
+ expect(isSavedAgentOption(undefined, 'agent_a')).toBe(false);
+ });
+});
diff --git a/client/src/components/SidePanel/Agents/__tests__/Starters.spec.tsx b/client/src/components/SidePanel/Agents/__tests__/Starters.spec.tsx
new file mode 100644
index 0000000000..610509deb2
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/__tests__/Starters.spec.tsx
@@ -0,0 +1,151 @@
+import userEvent from '@testing-library/user-event';
+import { Constants } from 'librechat-data-provider';
+import { FormProvider, useForm } from 'react-hook-form';
+import { act, render, screen, fireEvent } from '@testing-library/react';
+import type { AgentForm } from '~/common';
+import Starters from '../Starters';
+
+jest.mock('~/hooks', () => ({
+ useLocalize: () => (key: string) => key,
+}));
+
+let latest: string[] | undefined;
+const onSubmit = jest.fn();
+
+let formMethods: ReturnType<typeof useForm<AgentForm>> | undefined;
+
+function StartersHarness({ initial = [] }: { initial?: string[] }) {
+ const methods = useForm<AgentForm>({
+ defaultValues: { id: 'agent_a', conversation_starters: initial },
+ });
+ formMethods = methods;
+ latest = methods.watch('conversation_starters');
+ return (
+ <FormProvider {...methods}>
+ <form onSubmit={methods.handleSubmit(onSubmit)}>
+ <Starters />
+ </form>
+ </FormProvider>
+ );
+}
+
+/** Mirrors AgentPanel: the form outlives the builder section, which unmounts for other panels. */
+function PanelHarness({ showBuilder }: { showBuilder: boolean }) {
+ const methods = useForm<AgentForm>({
+ defaultValues: { id: 'agent_a', conversation_starters: [] },
+ });
+ return <FormProvider {...methods}>{showBuilder ? <Starters /> : <div />}</FormProvider>;
+}
+
+const draftInput = () =>
+ screen.getByPlaceholderText('com_assistants_conversation_starters_placeholder');
+
+describe('Agent conversation starters', () => {
+ beforeEach(() => {
+ latest = undefined;
+ onSubmit.mockClear();
+ });
+
+ it('adds a trimmed starter on Enter without submitting the agent form', async () => {
+ const user = userEvent.setup();
+ render(<StartersHarness />);
+
+ await user.type(draftInput(), ' Plan my week {Enter}');
+
+ expect(latest).toEqual(['Plan my week']);
+ expect(draftInput()).toHaveValue('');
+ expect(onSubmit).not.toHaveBeenCalled();
+ });
+
+ it('ignores blank drafts', async () => {
+ const user = userEvent.setup();
+ render(<StartersHarness />);
+
+ await user.type(draftInput(), ' {Enter}');
+
+ expect(latest).toEqual([]);
+ expect(screen.getByRole('button', { name: 'com_ui_add' })).toBeDisabled();
+ });
+
+ it('edits and deletes an existing starter', async () => {
+ const user = userEvent.setup();
+ render(<StartersHarness initial={['First', 'Second']} />);
+
+ const second = screen.getByRole('textbox', { name: 'com_assistants_conversation_starters 2' });
+ await user.type(second, '!');
+ expect(latest).toEqual(['First', 'Second!']);
+
+ await user.click(screen.getByRole('button', { name: 'com_ui_delete: First' }));
+ expect(latest).toEqual(['Second!']);
+ });
+
+ it('drops an unsent draft when the form switches to another agent', async () => {
+ const user = userEvent.setup();
+ render(<StartersHarness initial={['Kept']} />);
+
+ await user.type(draftInput(), 'Half-typed for agent A');
+ act(() => {
+ formMethods?.reset({ id: '', conversation_starters: [] });
+ });
+
+ expect(draftInput()).toHaveValue('');
+ expect(latest).toEqual([]);
+ });
+
+ it('keeps each delete control on the same row as its starter', () => {
+ render(<StartersHarness initial={['First']} />);
+
+ const input = screen.getByRole('textbox', { name: 'com_assistants_conversation_starters 1' });
+ const remove = screen.getByRole('button', { name: 'com_ui_delete: First' });
+ expect(remove.parentElement).toBe(input.parentElement);
+ expect(input.parentElement).toHaveClass('flex', 'items-center');
+ });
+
+ it('does not add a starter when Enter commits an IME composition', () => {
+ render(<StartersHarness />);
+
+ const input = draftInput();
+ fireEvent.change(input, { target: { value: '会話' } });
+ fireEvent.keyDown(input, { key: 'Enter', isComposing: true });
+ fireEvent.keyDown(input, { key: 'Enter', keyCode: 229 });
+
+ expect(latest).toEqual([]);
+ expect(input).toHaveValue('会話');
+ });
+
+ it('keeps the draft when the section unmounts for another builder panel', async () => {
+ const user = userEvent.setup();
+ const { rerender } = render(<PanelHarness showBuilder />);
+
+ await user.type(draftInput(), 'Keep me');
+ rerender(<PanelHarness showBuilder={false} />);
+ expect(
+ screen.queryByPlaceholderText('com_assistants_conversation_starters_placeholder'),
+ ).toBeNull();
+ rerender(<PanelHarness showBuilder />);
+
+ expect(draftInput()).toHaveValue('Keep me');
+ });
+
+ it('accepts starters longer than 64 characters in the draft and existing rows', async () => {
+ const user = userEvent.setup();
+ const long = 'Summarize the attached quarterly report and list the three largest risks';
+ render(<StartersHarness initial={['Short']} />);
+
+ await user.type(draftInput(), `${long}{Enter}`);
+ const row = screen.getByLabelText('com_assistants_conversation_starters 1');
+ await user.type(row, ` ${long}`);
+
+ expect(latest).toEqual([`Short ${long}`, long]);
+ });
+
+ it('locks the draft input at the maximum', () => {
+ const full = Array.from({ length: Number(Constants.MAX_CONVO_STARTERS) }, (_, i) => `S${i}`);
+ render(<StartersHarness initial={full} />);
+
+ expect(screen.getByPlaceholderText('com_assistants_max_starters_reached')).toBeDisabled();
+ expect(
+ screen.getByRole('button', { name: 'com_assistants_max_starters_reached' }),
+ ).toBeDisabled();
+ });
+});
diff --git a/client/src/utils/forms.tsx b/client/src/utils/forms.tsx
index 8d019cea32..11d481adf8 100644
--- a/client/src/utils/forms.tsx
+++ b/client/src/utils/forms.tsx
@@ -52,6 +52,7 @@ export const getDefaultAgentFormValues = (
avatar_file: null,
avatar_preview: '',
avatar_action: null,
+ conversation_starter_draft: '',
});
export const processAgentOption = ({
diff --git a/e2e/specs/mock/scenarios/agent-conversation-starters.spec.ts b/e2e/specs/mock/scenarios/agent-conversation-starters.spec.ts
new file mode 100644
index 0000000000..e166609edf
--- /dev/null
+++ b/e2e/specs/mock/scenarios/agent-conversation-starters.spec.ts
@@ -0,0 +1,396 @@
+import { expect, test } from '@playwright/test';
+import type { Locator, Page } from '@playwright/test';
+import type { AgentDetail } from '../agents.helpers';
+import {
+ cleanupAgent,
+ openAgentBuilder,
+ selectMockModel,
+ uniqueAgentName,
+} from '../agents.helpers';
+import { MOCK_ENDPOINTS, NEW_CHAT_PATH, fetchJson, getAccessToken, requestJson } from '../helpers';
+
+type StarterAgent = AgentDetail & { conversation_starters?: string[] };
+
+const FORM_NAME = 'Agent configuration form';
+const DRAFT_PLACEHOLDER = 'Enter a conversation starter';
+
+const builderForm = (page: Page) => page.getByRole('form', { name: FORM_NAME });
+
+const createAgentViaApi = async (page: Page, name: string, starters: string[]) => {
+ const token = await getAccessToken(page);
+ return requestJson<StarterAgent>(page, {
+ path: '/api/agents',
+ token,
+ method: 'POST',
+ body: {
+ name,
+ description: 'Agent conversation starters acceptance fixture.',
+ instructions: 'Keep this fixture deterministic.',
+ provider: MOCK_ENDPOINTS[0].label,
+ model: MOCK_ENDPOINTS[0].model,
+ conversation_starters: starters,
+ },
+ });
+};
+
+const fetchStarters = async (page: Page, agentId: string) => {
+ const token = await getAccessToken(page);
+ const agent = await fetchJson<StarterAgent>(
+ page,
+ `/api/agents/${encodeURIComponent(agentId)}/expanded`,
+ token,
+ );
+ return agent.conversation_starters ?? [];
+};
+
+/** Picks another agent in the open builder, without navigating away. */
+const switchAgent = async (form: Locator, name: string) => {
+ await form.getByRole('combobox', { name: 'Agent', exact: true }).click();
+ await form.page().getByRole('option', { name, exact: true }).click();
+ await expect(form.getByLabel('Agent name')).toHaveValue(name);
+ return form;
+};
+
+const selectAgentInBuilder = async (page: Page, name: string) =>
+ switchAgent(await openAgentBuilder(page), name);
+
+const saveAgent = async (form: Locator, agentId: string) => {
+ const page = form.page();
+ const [response] = await Promise.all([
+ page.waitForResponse(
+ (candidate) =>
+ candidate.request().method() === 'PATCH' &&
+ new URL(candidate.url()).pathname === `/api/agents/${agentId}` &&
+ candidate.ok(),
+ { timeout: 30000 },
+ ),
+ form.getByRole('button', { name: 'Save', exact: true }).click(),
+ ]);
+ return response;
+};
+
+const addStarter = async (form: Locator, text: string) => {
+ const draft = form.getByPlaceholder(DRAFT_PLACEHOLDER);
+ await draft.fill(text);
+ await draft.press('Enter');
+ await expect(
+ form.getByRole('textbox', { name: /^Conversation Starters \d+$/ }).last(),
+ ).toHaveValue(text);
+};
+
+test.describe('agent conversation starters', () => {
+ test('starters added in the builder appear on the agent chat landing @scenario:builder-starters-appear-on-agent-landing', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const name = uniqueAgentName('E2E Starters Create');
+ const starters = ['Plan my week', 'Summarize this article'];
+ let agentId: string | undefined;
+
+ try {
+ let form = await openAgentBuilder(page);
+ const createNew = form.getByRole('button', { name: 'Create New Agent' });
+ if (await createNew.isVisible().catch(() => false)) {
+ await createNew.click();
+ }
+ form = builderForm(page);
+ await form.getByLabel('Agent name').fill(name);
+ await form.getByLabel('Instructions').fill('Answer with the mock model.');
+ await selectMockModel(page, true);
+ form = builderForm(page);
+
+ for (const starter of starters) {
+ await addStarter(form, starter);
+ }
+ /** Enter adds a starter; it must not submit the agent form on its own. */
+ await expect(form.getByRole('button', { name: 'Create', exact: true })).toBeVisible();
+
+ const [response] = await Promise.all([
+ page.waitForResponse(
+ (candidate) =>
+ candidate.request().method() === 'POST' &&
+ new URL(candidate.url()).pathname === '/api/agents' &&
+ candidate.status() === 201,
+ { timeout: 30000 },
+ ),
+ form.getByRole('button', { name: 'Create', exact: true }).click(),
+ ]);
+ const created = (await response.json()) as StarterAgent;
+ agentId = created.id;
+ expect(created.conversation_starters).toEqual(starters);
+
+ await page.goto(`${NEW_CHAT_PATH}?agent_id=${encodeURIComponent(agentId)}`, {
+ timeout: 10000,
+ });
+ for (const starter of starters) {
+ await expect(page.getByRole('button', { name: starter, exact: true })).toBeVisible({
+ timeout: 30000,
+ });
+ }
+ } finally {
+ await cleanupAgent(page, agentId);
+ }
+ });
+
+ test('saving an unrelated field keeps stored starters byte for byte @scenario:unrelated-save-preserves-stored-starters', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const name = uniqueAgentName('E2E Starters Preserve');
+ /** Legal through the API: more than the builder renders, with padding. */
+ const stored = [' Padded starter ', 'Two', 'Three', 'Four', 'Five beyond the cap'];
+ let agentId: string | undefined;
+
+ try {
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ const agent = await createAgentViaApi(page, name, stored);
+ agentId = agent.id;
+
+ const form = await selectAgentInBuilder(page, name);
+ await form.getByLabel('Agent description').fill('Only the description changed.');
+ const response = await saveAgent(form, agentId);
+
+ expect(response.request().postDataJSON()).not.toHaveProperty('conversation_starters');
+ expect(await fetchStarters(page, agentId)).toEqual(stored);
+ } finally {
+ await cleanupAgent(page, agentId);
+ }
+ });
+
+ test('deleting every starter in the builder clears them @scenario:builder-clears-all-starters', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const name = uniqueAgentName('E2E Starters Clear');
+ const stored = ['First starter', 'Second starter'];
+ let agentId: string | undefined;
+
+ try {
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ const agent = await createAgentViaApi(page, name, stored);
+ agentId = agent.id;
+
+ const form = await selectAgentInBuilder(page, name);
+ for (const starter of stored) {
+ await form.getByRole('button', { name: `Delete: ${starter}`, exact: true }).click();
+ }
+ await expect(form.getByRole('textbox', { name: /^Conversation Starters \d+$/ })).toHaveCount(
+ 0,
+ );
+ await saveAgent(form, agentId);
+
+ expect(await fetchStarters(page, agentId)).toEqual([]);
+ await page.goto(`${NEW_CHAT_PATH}?agent_id=${encodeURIComponent(agentId)}`, {
+ timeout: 10000,
+ });
+ await expect(page.getByRole('textbox', { name: 'Message input' })).toBeVisible({
+ timeout: 30000,
+ });
+ for (const starter of stored) {
+ await expect(page.getByRole('button', { name: starter, exact: true })).toBeHidden();
+ }
+ } finally {
+ await cleanupAgent(page, agentId);
+ }
+ });
+
+ test('an unsent draft does not follow the user to another agent @scenario:starter-draft-stays-with-its-agent', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const name = uniqueAgentName('E2E Starters Draft');
+ let agentId: string | undefined;
+
+ try {
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ const agent = await createAgentViaApi(page, name, ['Existing starter']);
+ agentId = agent.id;
+
+ let form = await selectAgentInBuilder(page, name);
+ await form.getByPlaceholder(DRAFT_PLACEHOLDER).fill('Half-typed for the first agent');
+
+ await form.getByRole('button', { name: 'Create New Agent' }).click();
+ form = builderForm(page);
+ await expect(form.getByRole('button', { name: 'Create', exact: true })).toBeVisible();
+ await expect(form.getByPlaceholder(DRAFT_PLACEHOLDER)).toHaveValue('');
+ await expect(form.getByRole('textbox', { name: /^Conversation Starters \d+$/ })).toHaveCount(
+ 0,
+ );
+ } finally {
+ await cleanupAgent(page, agentId);
+ }
+ });
+
+ test('an unsent draft survives a trip to the model panel @scenario:starter-draft-survives-panel-switch', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const name = uniqueAgentName('E2E Starters Panel');
+ let agentId: string | undefined;
+
+ try {
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ const agent = await createAgentViaApi(page, name, []);
+ agentId = agent.id;
+
+ let form = await selectAgentInBuilder(page, name);
+ await form.getByPlaceholder(DRAFT_PLACEHOLDER).fill('Typed before opening the model panel');
+ await form.getByRole('button', { name: /^Model/ }).click();
+ await builderForm(page).getByRole('button', { name: 'Back to builder' }).click();
+ form = builderForm(page);
+
+ await expect(form.getByPlaceholder(DRAFT_PLACEHOLDER)).toHaveValue(
+ 'Typed before opening the model panel',
+ );
+ } finally {
+ await cleanupAgent(page, agentId);
+ }
+ });
+
+ test('after saving, the builder shows the starters that were stored @scenario:saved-starters-replace-edited-rows', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const name = uniqueAgentName('E2E Starters Sync');
+ const stored = ['One', 'Two', 'Three', 'Four'];
+ let agentId: string | undefined;
+
+ try {
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ const agent = await createAgentViaApi(page, name, stored);
+ agentId = agent.id;
+
+ const form = await selectAgentInBuilder(page, name);
+ const rows = form.getByRole('textbox', { name: /^Conversation Starters \d+$/ });
+ await expect(
+ form.getByPlaceholder('Max number of conversation starters reached'),
+ ).toBeDisabled();
+ await rows.nth(1).fill(' ');
+ await rows.nth(2).fill(' Three padded ');
+ await saveAgent(form, agentId);
+
+ expect(await fetchStarters(page, agentId)).toEqual(['One', 'Three padded', 'Four']);
+ await expect(rows).toHaveCount(3);
+ await expect(rows.nth(1)).toHaveValue('Three padded');
+ await expect(form.getByPlaceholder(DRAFT_PLACEHOLDER)).toBeEnabled();
+ } finally {
+ await cleanupAgent(page, agentId);
+ }
+ });
+
+ test('a starter edited while a save is in flight is kept @scenario:starter-edits-during-save-survive', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const name = uniqueAgentName('E2E Starters In Flight');
+ let agentId: string | undefined;
+
+ try {
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ const agent = await createAgentViaApi(page, name, ['One']);
+ agentId = agent.id;
+ const id = agentId;
+
+ let releaseSave: () => void = () => undefined;
+ const saveHeld = new Promise<void>((resolve) => {
+ releaseSave = resolve;
+ });
+ await page.route(`**/api/agents/${id}`, async (route) => {
+ if (route.request().method() !== 'PATCH') {
+ return route.fallback();
+ }
+ await saveHeld;
+ return route.fallback();
+ });
+
+ const form = await selectAgentInBuilder(page, name);
+ const rows = form.getByRole('textbox', { name: /^Conversation Starters \d+$/ });
+ await addStarter(form, 'Sent with the save');
+
+ const saved = page.waitForResponse(
+ (candidate) =>
+ candidate.request().method() === 'PATCH' &&
+ new URL(candidate.url()).pathname === `/api/agents/${id}` &&
+ candidate.ok(),
+ { timeout: 30000 },
+ );
+ await form.getByRole('button', { name: 'Save', exact: true }).click();
+ await addStarter(form, 'Typed during the save');
+ releaseSave();
+ await saved;
+
+ expect(await fetchStarters(page, id)).toEqual(['One', 'Sent with the save']);
+ await expect(page.getByText(`Successfully updated ${name}`).first()).toBeVisible();
+ await expect(rows).toHaveCount(3);
+ await expect(rows.nth(2)).toHaveValue('Typed during the save');
+ await page.unroute(`**/api/agents/${id}`);
+
+ await saveAgent(form, id);
+ expect(await fetchStarters(page, id)).toEqual([
+ 'One',
+ 'Sent with the save',
+ 'Typed during the save',
+ ]);
+ } finally {
+ await cleanupAgent(page, agentId);
+ }
+ });
+
+ test('switching agents while a save is in flight keeps the other agent starters @scenario:save-finishing-after-switch-keeps-other-agent-starters', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const firstName = uniqueAgentName('E2E Starters Switch A');
+ const secondName = uniqueAgentName('E2E Starters Switch B');
+ /** Padded, so a rewrite through the builder would be visible in storage. */
+ const secondStored = [' Padded B starter ', 'B two'];
+ let firstId: string | undefined;
+ let secondId: string | undefined;
+
+ try {
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ firstId = (await createAgentViaApi(page, firstName, ['A starter'])).id;
+ secondId = (await createAgentViaApi(page, secondName, secondStored)).id;
+ const id = firstId;
+
+ let releaseSave: () => void = () => undefined;
+ const saveHeld = new Promise<void>((resolve) => {
+ releaseSave = resolve;
+ });
+ await page.route(`**/api/agents/${id}`, async (route) => {
+ if (route.request().method() !== 'PATCH') {
+ return route.fallback();
+ }
+ await saveHeld;
+ return route.fallback();
+ });
+
+ const form = await selectAgentInBuilder(page, firstName);
+ await form.getByLabel('Agent description').fill('First agent saved slowly.');
+ const saved = page.waitForResponse(
+ (candidate) =>
+ candidate.request().method() === 'PATCH' &&
+ new URL(candidate.url()).pathname === `/api/agents/${id}` &&
+ candidate.ok(),
+ { timeout: 30000 },
+ );
+ await form.getByRole('button', { name: 'Save', exact: true }).click();
+
+ /** A navigation would abort the held save, so the switch stays in place. */
+ await switchAgent(form, secondName);
+ releaseSave();
+ await saved;
+ await page.unroute(`**/api/agents/${id}`);
+ await expect(form.getByLabel('Agent name')).toHaveValue(secondName);
+
+ await form.getByLabel('Agent description').fill('Second agent, unrelated edit.');
+ const response = await saveAgent(form, secondId);
+
+ expect(response.request().postDataJSON()).not.toHaveProperty('conversation_starters');
+ expect(await fetchStarters(page, secondId)).toEqual(secondStored);
+ } finally {
+ await cleanupAgent(page, firstId);
+ await cleanupAgent(page, secondId);
+ }
+ });
+});
diff --git a/packages/data-provider/src/schemas.ts b/packages/data-provider/src/schemas.ts
index 7916b0c75f..471c0c5f0a 100644
--- a/packages/data-provider/src/schemas.ts
+++ b/packages/data-provider/src/schemas.ts
@@ -430,6 +430,7 @@ export const defaultAgentFormValues = {
name: '',
email: '',
},
+ conversation_starters: [] as string[],
/** Optional allowlist. Only applies when `skills_enabled === true`.
* Empty/undefined + enabled = full catalog; non-empty + enabled = narrow to ids. */
skills: undefined as string[] | undefined,
diff --git a/packages/data-provider/src/types/agents.ts b/packages/data-provider/src/types/agents.ts
index af0579c057..e210c75c94 100644
--- a/packages/data-provider/src/types/agents.ts
+++ b/packages/data-provider/src/types/agents.ts
@@ -1112,6 +1112,7 @@ export type AgentCreateParams = {
| 'recursion_limit'
| 'category'
| 'support_contact'
+ | 'conversation_starters'
| 'tool_options'
| 'skills'
| 'skills_enabled'
@@ -1148,6 +1149,7 @@ export type AgentUpdateParams = {
| 'recursion_limit'
| 'category'
| 'support_contact'
+ | 'conversation_starters'
| 'tool_options'
| 'skills'
| 'skills_enabled'