fix: restore agent instruction guidance

Localize/lang/strings.json

@@ -1729,6 +1729,7 @@
   "VjvWve": "Microsoft Authored",
   "Vk1TBl": "Function folder name cannot be empty.",
   "VlvlX1": "Certificate",
+  "Vp5rnF": "Tips for writing agent instructions",
   "VptXzY": "Use \"{value}\" as a custom value",
   "Vq9q5J": "Built-in",
   "Vqs8hE": "Actions",
@@ -3691,6 +3692,7 @@
   "_VjvWve.comment": "Label text for Microsoft authored templates tab",
   "_Vk1TBl.comment": "Function folder name empty text",
   "_VlvlX1.comment": "Authentication OAuth Certificate Type Label",
+  "_Vp5rnF.comment": "Description link for agent instruction editor",
   "_VptXzY.comment": "Label for button to allow user to create custom value in combobox from current input",
   "_Vq9q5J.comment": "Filter by In App category of connectors",
   "_Vqs8hE.comment": "Actions button",
@@ -4307,6 +4309,7 @@
   "_hPM6iC.comment": "Label for description of custom sub Function",
   "_hQNVhi.comment": "Fetching data text",
   "_hQp3t6.comment": "The aria label for the connections table",
+  "_hRLAFg.comment": "Description for agent instruction editor",
   "_hRVVdR.comment": "Chatbot undo button for undoing assistant change to flow",
   "_hTjAB+.comment": "Error message when tool name exceeds maximum characters",
   "_hUnLzB.comment": "Chatbot progress message shown while generating the final workflow from connector results",
@@ -5681,6 +5684,7 @@
   "hPM6iC": "Returns the result from subtracting two numbers",
   "hQNVhi": "Fetching data...",
   "hQp3t6": "List of connectors needing connections",
+  "hRLAFg": "Add instructions so the agent understands its role and tasks. Include helpful information about workflow structure, restrictions, tools, and interactions in specific scenarios.",
   "hRVVdR": "Undo",
   "hTjAB+": "Tool name cannot exceed maximum characters",
   "hUnLzB": "Building workflow...",

libs/designer-ui/src/lib/agentinstruction/__test__/agentinstruction.spec.tsx

@@ -0,0 +1,55 @@
+/**
+ * @vitest-environment jsdom
+ */
+import '@testing-library/jest-dom/vitest';
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+import { cleanup, render, screen } from '@testing-library/react';
+import { IntlProvider } from 'react-intl';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AgentInstructionEditor } from '../index';
+
+vi.mock('../../editor/string', () => ({
+  StringEditor: () => <div data-testid="system-instruction-editor" />,
+}));
+
+const renderEditor = (hideSystemInstructions = false) =>
+  render(
+    <FluentProvider theme={webLightTheme}>
+      <IntlProvider locale="en" messages={{}}>
+        <AgentInstructionEditor
+          initialValue={[]}
+          onCastParameter={vi.fn()}
+          hideUserInstructions={true}
+          hideSystemInstructions={hideSystemInstructions}
+        />
+      </IntlProvider>
+    </FluentProvider>
+  );
+
+describe('AgentInstructionEditor', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it('shows guidance and documentation for system instructions', () => {
+    renderEditor();
+
+    expect(
+      screen.getByText(
+        'Add instructions so the agent understands its role and tasks. Include helpful information about workflow structure, restrictions, tools, and interactions in specific scenarios.'
+      )
+    ).toBeInTheDocument();
+
+    const documentationLink = screen.getByRole('link', { name: /tips for writing agent instructions/i });
+    expect(documentationLink).toHaveAttribute('href', 'https://aka.ms/LogicApps/Agents');
+    expect(documentationLink).toHaveAttribute('target', '_blank');
+    expect(documentationLink).toHaveAttribute('rel', 'noreferrer');
+  });
+
+  it('hides system guidance when system instructions are hidden', () => {
+    renderEditor(true);
+
+    expect(screen.queryByText(/add instructions so the agent understands its role and tasks/i)).not.toBeInTheDocument();
+    expect(screen.queryByRole('link', { name: /tips for writing agent instructions/i })).not.toBeInTheDocument();
+  });
+});

libs/designer-ui/src/lib/agentinstruction/index.tsx

@@ -1,4 +1,4 @@
-import { MessageBar, MessageBarBody, MessageBarTitle, Text, mergeClasses } from '@fluentui/react-components';
+import { Link, MessageBar, MessageBarBody, MessageBarTitle, Text, mergeClasses } from '@fluentui/react-components';
 import type { BaseEditorProps, CastHandler, ChangeHandler, ChangeState, GetTokenPickerHandler } from '../editor/base';
 import { useIntl } from 'react-intl';
 import { bundleIcon, Open12Regular, Open12Filled } from '@fluentui/react-icons';
@@ -50,6 +50,17 @@ export const AgentInstructionEditor = ({
       serializeValue?.({ value: reserialized });
     }
   }, [hideSystemInstructions, systemMessage, userMessage, serializeValue]);
+  const systemInstructionDescription = intl.formatMessage({
+    defaultMessage:
+      'Add instructions so the agent understands its role and tasks. Include helpful information about workflow structure, restrictions, tools, and interactions in specific scenarios.',
+    description: 'Description for agent instruction editor',
+    id: 'hRLAFg',
+  });
+  const descriptionLink = intl.formatMessage({
+    defaultMessage: 'Tips for writing agent instructions',
+    description: 'Description link for agent instruction editor',
+    id: 'Vp5rnF',
+  });
   const userInstructionDescription = intl.formatMessage({
     defaultMessage:
       'Add optional prompts or questions for the agent. For better results, focus each item on a single specific prompt or question.',
@@ -89,15 +100,22 @@ export const AgentInstructionEditor = ({
     <div className="msla-agent-instruction-editor-container">
       <div className={mergeClasses(styles.editors)}>
         {!hideSystemInstructions && (
-          <StringEditor
-            {...props}
-            className={mergeClasses(styles.systemEditor, css(className, 'msla-agent-instruction-system-editor editor-custom'))}
-            placeholder={systemPlaceholder}
-            initialValue={systemMessage}
-            editorBlur={(newState: ChangeState) => handleValueChange(newState, AGENT_INSTRUCTION_TYPES.SYSTEM)}
-            valueType={constants.SWAGGER.TYPE.STRING}
-            spellCheck={true}
-          />
+          <>
+            <Text size={200}>{systemInstructionDescription} </Text>
+            <Link href="https://aka.ms/LogicApps/Agents" target="_blank" rel="noreferrer" style={{ fontSize: 12 }}>
+              {descriptionLink}
+              <NavigateIcon style={{ position: 'relative', top: '2px', left: '2px' }} />
+            </Link>
+            <StringEditor
+              {...props}
+              className={mergeClasses(styles.systemEditor, css(className, 'msla-agent-instruction-system-editor editor-custom'))}
+              placeholder={systemPlaceholder}
+              initialValue={systemMessage}
+              editorBlur={(newState: ChangeState) => handleValueChange(newState, AGENT_INSTRUCTION_TYPES.SYSTEM)}
+              valueType={constants.SWAGGER.TYPE.STRING}
+              spellCheck={true}
+            />
+          </>
         )}
         {!hideUserInstructions && (
           <>