feat(agent-builder): add AttachmentGroup and group_id to the attachment system

Introduces AttachmentGroup as a client-side grouping primitive and group_id
as a first-class field on Attachment, VersionedAttachment, and AttachmentInput.
group_id is persisted server-side and threads through the full pipeline so
grouped batches survive round-trips and render as a single entry in chat history.

Key changes:
- AttachmentGroup type + isAttachmentGroup predicate in versioned_attachment.ts
- flattenAttachments stamps group_id and description at the serialization boundary
- RoundAttachmentReferences deduplicates refs by group_id (actor-filter ordering fix included)
- AttachmentGroupPill component for rendering group chips
- remove_attachment_from_list handles group_id-based bulk removal
- buildOptimisticAttachments preserves group_id and description on fallback attachments
- Server pipeline (chat.ts, validate_attachment.ts, attachment_state_manager, prepare_conversation)
  threads group_id and description through to VersionedAttachment
- Per-attachment maxContentLength support in attachment_presentation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jonwalstedt

x-pack/platform/packages/shared/agent-builder/agent-builder-browser/plugin_contract.ts

@@ -6,7 +6,11 @@
  */
 
 import type { ComponentType } from 'react';
-import type { AttachmentInput, UpdateOriginResponse } from '@kbn/agent-builder-common/attachments';
+import type {
+  AttachmentInput,
+  ConversationAttachment,
+  UpdateOriginResponse,
+} from '@kbn/agent-builder-common/attachments';
 import type { BrowserApiToolDefinition } from './tools/browser_api_tool';
 import type {
   AgentsServiceStartContract,
@@ -72,7 +76,7 @@ export interface EmbeddableConversationProps {
    * Content will be fetched when starting a new conversation round.
    * It will be appended only if it has changed since previous conversation round.
    */
-  attachments?: AttachmentInput[];
+  attachments?: ConversationAttachment[];
 
   /**
    * Browser API tools that the agent can use to interact with the page.

x-pack/platform/packages/shared/agent-builder/agent-builder-common/attachments/attachments.ts

@@ -20,6 +20,8 @@ export interface Attachment<
   type: Type;
   /** data bound to the attachment */
   data: DataType;
+  /** Human-readable description of the attachment */
+  description?: string;
   /** should the attachment be hidden from the user - e.g. for screen context */
   hidden?: boolean;
   /**
@@ -28,6 +30,13 @@ export interface Attachment<
    * Undefined for by-value attachments.
    */
   origin?: string;
+  /**
+   * Stable identifier for the logical group this attachment belongs to.
+   * Attachments sharing the same group_id were submitted together as a single
+   * logical entity (e.g. multiple alert batches from one bulk-add action).
+   * Undefined for standalone attachments.
+   */
+  group_id?: string;
 }
 
 /**

x-pack/platform/packages/shared/agent-builder/agent-builder-common/attachments/index.ts

@@ -48,6 +48,8 @@ export type {
   AttachmentRefActor,
   AttachmentDiff,
   AttachmentInput,
+  AttachmentGroup,
+  ConversationAttachment,
   UpdateOriginResponse,
 } from './versioned_attachment';
 export {
@@ -59,7 +61,9 @@ export {
   attachmentRefOperationSchema,
   attachmentRefActorSchema,
   attachmentInputSchema,
+  attachmentGroupSchema,
   attachmentDiffSchema,
+  isAttachmentGroup,
   getLatestVersion,
   getVersion,
   createVersionId,

x-pack/platform/packages/shared/agent-builder/agent-builder-common/attachments/versioned_attachment.test.ts

@@ -19,8 +19,12 @@ import {
   versionedAttachmentSchema,
   attachmentVersionRefSchema,
   attachmentDiffSchema,
+  attachmentGroupSchema,
+  isAttachmentGroup,
   type VersionedAttachment,
   type AttachmentVersion,
+  type AttachmentGroup,
+  type AttachmentInput,
   attachmentInputSchema,
 } from './versioned_attachment';
 
@@ -527,5 +531,75 @@ describe('versioned_attachment', () => {
         expect(result.success).toBe(false);
       });
     });
+
+    describe('attachmentGroupSchema', () => {
+      const validGroup = {
+        type: 'group',
+        id: 'g1',
+        label: '3 Alerts',
+        items: [
+          { type: 'security.alerts', data: { alertIds: ['a', 'b'] } },
+          { type: 'security.alerts', data: { alertIds: ['c'] } },
+        ],
+      };
+
+      it('validates a correct AttachmentGroup', () => {
+        expect(attachmentGroupSchema.safeParse(validGroup).success).toBe(true);
+      });
+
+      it('rejects when type is not "group"', () => {
+        const result = attachmentGroupSchema.safeParse({ ...validGroup, type: 'text' });
+        expect(result.success).toBe(false);
+      });
+
+      it('rejects when id is missing', () => {
+        const { id: _omit, ...rest } = validGroup;
+        expect(attachmentGroupSchema.safeParse(rest).success).toBe(false);
+      });
+
+      it('rejects when label is missing', () => {
+        const { label: _omit, ...rest } = validGroup;
+        expect(attachmentGroupSchema.safeParse(rest).success).toBe(false);
+      });
+
+      it('accepts an empty items array', () => {
+        expect(attachmentGroupSchema.safeParse({ ...validGroup, items: [] }).success).toBe(true);
+      });
+    });
+
+    describe('attachmentInputSchema — no groupId field', () => {
+      it('parses a minimal attachment input', () => {
+        const result = attachmentInputSchema.safeParse({ type: 'text' });
+        expect(result.success).toBe(true);
+      });
+
+      it('strips unknown fields including groupId', () => {
+        const parsed = attachmentInputSchema.safeParse({
+          type: 'text',
+          groupId: 'should-be-stripped',
+        });
+        expect(parsed.success).toBe(true);
+        if (parsed.success) {
+          expect(parsed.data).not.toHaveProperty('groupId');
+        }
+      });
+    });
+  });
+
+  describe('isAttachmentGroup', () => {
+    it('returns true for an AttachmentGroup', () => {
+      const g: AttachmentGroup = {
+        type: 'group',
+        id: 'g1',
+        label: '2 Alerts',
+        items: [{ type: 'security.alerts', data: {} }],
+      };
+      expect(isAttachmentGroup(g)).toBe(true);
+    });
+
+    it('returns false for an AttachmentInput', () => {
+      const a: AttachmentInput = { type: 'text', data: {} };
+      expect(isAttachmentGroup(a)).toBe(false);
+    });
   });
 });

x-pack/platform/packages/shared/agent-builder/agent-builder-common/attachments/versioned_attachment.ts

@@ -50,6 +50,13 @@ export interface VersionedAttachment<
   readonly?: boolean;
   /** The client-provided ID if this attachment was created with one (e.g., via flyout configuration) */
   client_id?: string;
+  /**
+   * Stable identifier for the logical group this attachment belongs to.
+   * Attachments sharing the same group_id were submitted together as a single
+   * logical entity (e.g. multiple alert batches from one bulk-add action).
+   * Undefined for standalone attachments.
+   */
+  group_id?: string;
   /**
    * Origin/reference info for attachments created from external sources.
    * For saved-object-backed types this is the saved object ID.
@@ -153,6 +160,16 @@ export interface AttachmentInput<
   hidden?: boolean;
   /** Whether the attachment should be read-only */
   readonly?: boolean;
+  /**
+   * Stable identifier for the logical group this attachment belongs to.
+   * Attachments sharing the same group_id were submitted together as a single
+   * logical entity (e.g. multiple alert batches from one bulk-add action).
+   * Undefined for standalone attachments.
+   *
+   * When this input is part of an AttachmentGroup, flattenAttachments always
+   * stamps this field with the group's id, overriding any value set here.
+   */
+  group_id?: string;
 }
 
 // Zod schemas for validation
@@ -198,6 +215,7 @@ export const versionedAttachmentSchema = z.object({
   client_id: z.string().optional(),
   origin: z.string().optional(),
   origin_snapshot_at: z.string().optional(),
+  group_id: z.string().optional(),
 });
 
 export const attachmentInputSchema = z.object({
@@ -208,8 +226,41 @@ export const attachmentInputSchema = z.object({
   description: z.string().optional(),
   hidden: z.boolean().optional(),
   readonly: z.boolean().optional(),
+  group_id: z.string().optional(),
+});
+
+/**
+ * A named group of attachments that appears as a single chip in the UI.
+ * The group is a client-side-only concept — it is flattened to individual
+ * AttachmentInput items at the serialization boundary before being sent to the server.
+ */
+export interface AttachmentGroup {
+  type: 'group';
+  /** Stable identifier for the group */
+  id: string;
+  /** Display label shown on the chip, e.g. "5 Alerts" */
+  label: string;
+  /** The individual attachment items that make up this group */
+  items: AttachmentInput[];
+}
+
+export const attachmentGroupSchema = z.object({
+  type: z.literal('group'),
+  id: z.string(),
+  label: z.string(),
+  items: z.array(attachmentInputSchema),
 });
 
+export const isAttachmentGroup = (a: ConversationAttachment): a is AttachmentGroup =>
+  a.type === 'group';
+
+/**
+ * Union of a single attachment or a group of attachments.
+ * This is the type used in client-side conversation state.
+ * Groups are flattened to AttachmentInput[] before being sent to the server.
+ */
+export type ConversationAttachment = AttachmentInput | AttachmentGroup;
+
 export const attachmentDiffSchema = z.object({
   change_type: z.enum(['create', 'update', 'delete', 'restore']),
   summary: z.string(),

x-pack/platform/packages/shared/agent-builder/agent-builder-common/telemetry/agent_builder_events.ts

@@ -66,6 +66,8 @@ export interface ReportOptOutParams {
 export interface ReportAddToChatClickedParams {
   pathway: string;
   attachments?: string[];
+  /** Number of items added when using bulk add-to-chat. Absent for single-item pathways. */
+  item_count?: number;
 }
 
 export type AgentBuilderUiClickElementKind =
@@ -480,6 +482,13 @@ const ADD_TO_CHAT_CLICKED_EVENT: AgentBuilderTelemetryEvent = {
         optional: true,
       },
     },
+    item_count: {
+      type: 'integer',
+      _meta: {
+        description: 'Number of items added via bulk add-to-chat. Absent for single-item pathways.',
+        optional: true,
+      },
+    },
   },
 };
 

x-pack/platform/packages/shared/agent-builder/agent-builder-server/attachments/attachment_state_manager.ts

@@ -349,13 +349,14 @@ class AttachmentStateManagerImpl implements AttachmentStateManager {
       versions: [version],
       current_version: 1,
       active: true,
-      ...(input.description && { description: input.description }),
+      ...(input.description !== undefined && { description: input.description }),
       ...(input.hidden !== undefined && { hidden: input.hidden }),
       readonly: input.readonly ?? this.getDefaultReadonly(input.type),
       ...(input.origin !== undefined && { origin: input.origin }),
       // When created with origin (by-reference), record snapshot time for isStale comparison.
       // By-value attachments leave this undefined.
       ...(input.origin !== undefined && { origin_snapshot_at: now }),
+      ...(input.group_id !== undefined && { group_id: input.group_id }),
     };
 
     this.attachments.set(id, attachment);

x-pack/platform/packages/shared/agent-builder/agent-builder-server/attachments/type_definition.ts

@@ -73,6 +73,12 @@ export interface AttachmentTypeDefinition<TType extends string = string, TConten
    * Whether attachments of this type are read-only. Defaults to false.
    */
   isReadonly?: boolean;
+  /**
+   * Maximum content length (in characters) for attachments of this type when presented inline
+   * to the LLM. Applied per-attachment — each attachment is truncated to its own type's limit.
+   * Defaults to the global DEFAULT_MAX_CONTENT_LENGTH (10 000).
+   */
+  maxContentLength?: number;
 }
 
 /**

x-pack/platform/packages/shared/agent-builder/kbn-evals-suite-agent-builder/.gitignore

@@ -0,0 +1 @@
+test-results/

x-pack/platform/plugins/shared/agent_builder/public/application/components/conversations/conversation_input/attachment_group_pill.tsx

@@ -0,0 +1,95 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { css } from '@emotion/css';
+import {
+  EuiPanel,
+  EuiFlexGroup,
+  EuiFlexItem,
+  EuiText,
+  EuiButtonIcon,
+  EuiIcon,
+  useEuiTheme,
+} from '@elastic/eui';
+import { i18n } from '@kbn/i18n';
+import React, { useState } from 'react';
+import type { AttachmentGroup } from '@kbn/agent-builder-common/attachments';
+
+const removeAriaLabel = i18n.translate('xpack.agentBuilder.attachmentGroupPill.removeAriaLabel', {
+  defaultMessage: 'Remove attachment group',
+});
+
+const DEFAULT_ICON = 'layers';
+
+export interface AttachmentGroupPillProps {
+  group: AttachmentGroup;
+  onRemove?: () => void;
+}
+
+export const AttachmentGroupPill: React.FC<AttachmentGroupPillProps> = ({ group, onRemove }) => {
+  const { euiTheme } = useEuiTheme();
+  const [isHovered, setIsHovered] = useState(false);
+
+  const iconContainerStyles = css`
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: ${euiTheme.size.xl};
+    height: ${euiTheme.size.xl};
+    border-radius: ${euiTheme.border.radius.small};
+    background-color: ${euiTheme.colors.backgroundBasePrimary};
+  `;
+
+  const titleStyles = css`
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    word-break: break-word;
+  `;
+
+  return (
+    <EuiPanel
+      hasShadow={false}
+      hasBorder
+      color="subdued"
+      paddingSize="s"
+      css={css`
+        max-width: 200px;
+        border: ${euiTheme.border.width.thin} solid ${euiTheme.colors.darkShade};
+      `}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+      data-test-subj={`agentBuilderAttachmentGroupPill-${group.id}`}
+    >
+      <EuiFlexGroup alignItems="center" gutterSize="s" responsive={false}>
+        <EuiFlexItem grow={false}>
+          <div className={iconContainerStyles}>
+            <EuiIcon type={DEFAULT_ICON} size="m" color="primary" aria-hidden={true} />
+          </div>
+        </EuiFlexItem>
+        <EuiFlexItem style={{ minWidth: 0 }}>
+          <EuiText size="xs" className={titleStyles}>
+            <strong>{group.label}</strong>
+          </EuiText>
+        </EuiFlexItem>
+        {onRemove && isHovered && (
+          <EuiFlexItem grow={false}>
+            <EuiButtonIcon
+              iconType="cross"
+              size="xs"
+              color="text"
+              aria-label={removeAriaLabel}
+              onClick={onRemove}
+            />
+          </EuiFlexItem>
+        )}
+      </EuiFlexGroup>
+    </EuiPanel>
+  );
+};