[Agent Builder] add sub-agent configuration

Author: pgayvallet

x-pack/platform/packages/shared/agent-builder/agent-builder-common/agents/agent_ids.test.ts

@@ -72,6 +72,16 @@ describe('validateAgentId', () => {
     const error = validateAgentId({ agentId, builtIn: true });
     expect(error).toBeUndefined();
   });
+
+  test('rejects the reserved id "_self" for user-created agents', () => {
+    const error = validateAgentId({ agentId: '_self', builtIn: false });
+    expect(error).toBe(`Agent id "_self" is reserved and cannot be used.`);
+  });
+
+  test('rejects the reserved id "_self" for built-in agents', () => {
+    const error = validateAgentId({ agentId: '_self', builtIn: true });
+    expect(error).toBe(`Agent id "_self" is reserved and cannot be used.`);
+  });
 });
 
 describe('agentId regexp', () => {

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

@@ -6,6 +6,7 @@
  */
 
 import { hasNamespaceName, isInProtectedNamespace } from '../base/namespaces';
+import { SELF_AGENT_ID } from './constants';
 
 // - Must start and end with letter or digit
 // - Can contain letters, digits, hyphens, underscores and dots
@@ -21,6 +22,9 @@ export const validateAgentId = ({
   agentId: string;
   builtIn: boolean;
 }): string | undefined => {
+  if (agentId === SELF_AGENT_ID) {
+    return `Agent id "${SELF_AGENT_ID}" is reserved and cannot be used.`;
+  }
   if (!agentIdRegexp.test(agentId)) {
     return `Agent ids must start and end with a letter or number, and can only contain lowercase letters, numbers, dots, hyphens and underscores`;
   }

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

@@ -0,0 +1,17 @@
+/*
+ * 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.
+ */
+
+/**
+ * Reserved agent id acting as a self-fork sentinel in
+ * {@link AgentConfiguration.subagent_ids}. Not a real, storable agent id —
+ * `validateAgentId` rejects it on both `builtIn: true` and `builtIn: false`
+ * paths. At runtime, `_self` in a resolved allowlist substitutes to the
+ * executing agent's real id only at the `SubAgentExecutor.executeSubAgent`
+ * call seam; everywhere else the sentinel stays visible so telemetry, logs,
+ * and the LLM tool schema can distinguish self-fork from an explicit id.
+ */
+export const SELF_AGENT_ID = '_self' as const;

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

@@ -152,6 +152,17 @@ export interface AgentConfiguration {
    * the accuracy and token efficiency.
    * */
   ai_indices?: string[];
+
+  /**
+   * Allowlist of agent ids this agent may spawn as sub-agents via the
+   * `run_subagent` tool. Entries are either real agent ids or the sentinel
+   * `SELF_AGENT_ID` (`'_self'`) which resolves to the executing agent itself.
+   *
+   * Missing / empty → the sub-agent tools (`run_subagent`, `send_message`,
+   * `sleep`) are not registered for this agent. Non-empty → the resolved,
+   * access-filtered list becomes the `agent_id` enum on `run_subagent`.
+   */
+  subagent_ids?: string[];
 }
 
 /**

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

@@ -31,6 +31,7 @@ export {
   type AgentAccessControlPrincipalType,
 } from './access_control';
 export { agentIdRegexp, agentIdMaxLength, validateAgentId } from './agent_ids';
+export { SELF_AGENT_ID } from './constants';
 export { AgentExecutionErrorCode } from './execution_errors';
 export { AgentExecutionMode, SubagentExecutionMode } from './execution_mode';
 export { ExecutionStatus, type SerializedExecutionError } from './execution_status';

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

@@ -672,9 +672,30 @@ export interface ConversationInternalState {
   /** Active todo list for the current conversation. Replaced wholesale on each write. */
   todos?: TodoItem[];
   /**
-   * Map of persistent sub-agent name → child conversation id.
+   * Map of persistent sub-agent name → entry describing the child conversation
+   * and the agent id that backs it. The `agent_id` is what the parent's
+   * `subagent_ids` allowlist filters on when deciding whether `send_message`
+   * can still reach the child (§3.5 of the configurable-subagents design).
+   *
+   * `agent_id` is either a real agent id or the sentinel `SELF_AGENT_ID`
+   * (`'_self'`), stored as-is at creation time and matched by exact string.
    */
-  subagents?: Record<string, string>;
+  subagents?: Record<string, SubagentEntry>;
+}
+
+/**
+ * Value stored per persistent sub-agent name on the parent conversation's
+ * {@link ConversationInternalState.subagents} map.
+ */
+export interface SubagentEntry {
+  /** ID of the child conversation. */
+  conversation_id: string;
+  /**
+   * Agent id backing this persistent sub-agent — either a real agent id or
+   * the `SELF_AGENT_ID` sentinel. Written by `run_subagent` at persistent
+   * creation time using the LLM's `agent_id` choice.
+   */
+  agent_id: string;
 }
 
 export interface BackgroundExecutionCompletedAt {

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

@@ -49,6 +49,7 @@ export {
   type TodoStatus,
   type BackgroundExecutionState,
   type BackgroundExecutionCompletedAt,
+  type SubagentEntry,
   type BackgroundAgentCompleteStep,
   isBackgroundAgentCompleteStep,
   type TodosStep,

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

@@ -228,6 +228,7 @@ export {
   isCompactionStep,
   isBackgroundAgentCompleteStep,
   type BackgroundAgentCompleteStep,
+  type SubagentEntry,
   type SubagentRosterEntry,
   type SubagentRosterUpdatedStep,
   type SubagentRosterUpdatedStepData,

x-pack/platform/packages/shared/agent-builder/agent-builder-server/agents/provider.ts

@@ -49,6 +49,7 @@ import type { AgentBuilderHooks } from '../hooks/types';
 import type { ToolRegistry } from '../tools';
 import type { AgentBuilderAnalytics, AgentBuilderTracking } from '../telemetry';
 import type { AiIndexResolver } from './ai_index_resolver';
+import type { AgentRegistry } from './registry';
 
 /**
  * Read/write conversation store contract exposed to agent handlers.
@@ -311,6 +312,12 @@ export interface AgentHandlerContext {
    * Sub-agent executor for spawning child agent executions.
    */
   subAgentExecutor: SubAgentExecutor;
+  /**
+   * Agent registry scoped to the current user. Used to resolve peer agents by
+   * id — e.g. to look up descriptions for entries in `configuration.subagent_ids`
+   * when composing the `run_subagent` tool schema.
+   */
+  agentRegistry: AgentRegistry;
   /**
    * Conversation store client scoped to the current user. Prefer this over
    * issuing raw ES queries against the conversation index.

x-pack/platform/plugins/shared/agent_builder/public/application/components/agents/edit/agent_form_validation.ts

@@ -144,5 +144,6 @@ export const agentFormSchema = z.object({
     plugin_ids: z.array(z.string()).optional(),
     connector_ids: z.array(z.string()).optional(),
     ai_indices: z.array(z.string()).optional(),
+    subagent_ids: z.array(z.string()).optional(),
   }),
 });