@memberjunction/ai-agent-manager 2.108.0 → 2.109.0

package/src/agent-spec-sync.ts

@@ -109,7 +109,7 @@ export class AgentSpecSync {
             this.spec = {
                 ID: '', // Will be set on save if empty
                 Name: '',
-                StartingPayloadValidationMode: () => 'Fail',
+                StartingPayloadValidationMode: 'Fail',
                 Actions: [],
                 SubAgents: []
             };
@@ -413,7 +413,11 @@ export class AgentSpecSync {
     private mapChildAgentToSpec(childAgent: AIAgentEntity): SubAgentSpec {
         return {
             Type: 'child',
-            SubAgentID: childAgent.ID
+            SubAgent: {
+                ID: childAgent.ID,
+                Name: childAgent.Name || '',
+                StartingPayloadValidationMode: 'Fail'
+            }
         };
     }
 
@@ -427,7 +431,11 @@ export class AgentSpecSync {
     private mapRelatedAgentToSpec(relationship: AIAgentRelationshipEntity): SubAgentSpec {
         return {
             Type: 'related',
-            SubAgentID: relationship.SubAgentID,
+            SubAgent: {
+                ID: relationship.SubAgentID,
+                Name: relationship.SubAgent || '',
+                StartingPayloadValidationMode: 'Fail'
+            },
             AgentRelationshipID: relationship.ID,
             SubAgentInputMapping: this.parseJsonField<Record<string, string>>(relationship.SubAgentInputMapping),
             SubAgentOutputMapping: this.parseJsonField<Record<string, string>>(relationship.SubAgentOutputMapping),
@@ -476,6 +484,9 @@ export class AgentSpecSync {
         // Step 3: Save sub-agents (both child and related)
         await this.saveSubAgents(agentId);
 
+        // Step 4: Save prompts
+        await this.savePrompts(agentId);
+
         this._isDirty = false;
         this._isLoaded = true;
 
@@ -535,7 +546,7 @@ export class AgentSpecSync {
         agentEntity.FinalPayloadValidationMaxRetries = this.spec.FinalPayloadValidationMaxRetries || 3;
 
         agentEntity.StartingPayloadValidation = this.spec.StartingPayloadValidation || null;
-        agentEntity.StartingPayloadValidationMode = this.spec.StartingPayloadValidationMode?.() || 'Fail';
+        agentEntity.StartingPayloadValidationMode = this.spec.StartingPayloadValidationMode || 'Fail';
 
         // Resource limits
         agentEntity.MaxCostPerRun = this.spec.MaxCostPerRun || null;
@@ -655,38 +666,64 @@ export class AgentSpecSync {
      * Save a child sub-agent (ParentID-based relationship).
      *
      * For child agents, the relationship is established by setting the ParentID field
-     * on the child agent entity. If the SubAgentID is empty, this indicates a new
-     * child agent that needs to be created.
+     * on the child agent entity. If the SubAgent.ID is empty, this creates a new
+     * child agent recursively using AgentSpecSync.
+     *
+     * This enables creating complete agent hierarchies in one call - sub-agents are
+     * created first (depth-first), then parent references them via ParentID.
      *
      * @private
      * @param parentId - The parent agent ID
      * @param SubAgentSpec - The sub-agent specification
-     * @throws {Error} If child agent doesn't exist or save fails
+     * @throws {Error} If child agent save fails
      */
     private async saveChildSubAgent(parentId: string, SubAgentSpec: SubAgentSpec): Promise<void> {
-        if (!SubAgentSpec.SubAgentID) {
-            throw new Error('Child sub-agent must have a SubAgentID');
-        }
+        console.log(`🔗 saveChildSubAgent: Processing child "${SubAgentSpec.SubAgent?.Name}", ID="${SubAgentSpec.SubAgent?.ID}"`);
 
-        // For child agents, we just need to ensure the ParentID is set correctly
-        // The sub-agent itself should already exist or be created separately
-        const md = new Metadata();
-        const childEntity = await md.GetEntityObject<AIAgentEntity>(
-            'AI Agents',
-            this._contextUser
-        );
+        // If SubAgent.ID is empty or missing, create the sub-agent recursively
+        if (!SubAgentSpec.SubAgent?.ID || SubAgentSpec.SubAgent.ID === '') {
+            console.log(`🔨 saveChildSubAgent: Creating new child sub-agent "${SubAgentSpec.SubAgent.Name}"...`);
 
-        const loaded = await childEntity.Load(SubAgentSpec.SubAgentID);
-        if (!loaded) {
-            throw new Error(`Child agent ${SubAgentSpec.SubAgentID} not found`);
-        }
+            // Set ParentID in the sub-agent spec before creating it
+            const childSpec: AgentSpec = {
+                ...SubAgentSpec.SubAgent,
+                ParentID: parentId
+            };
 
-        // Update parent ID if needed
-        if (childEntity.ParentID !== parentId) {
-            childEntity.ParentID = parentId;
-            const saved = await childEntity.Save();
-            if (!saved) {
-                throw new Error(`Failed to update ParentID for child agent ${SubAgentSpec.SubAgentID}`);
+            // Recursively create the sub-agent using AgentSpecSync
+            const childSync = new AgentSpecSync(childSpec, this._contextUser);
+            childSync.markDirty();
+            const childId = await childSync.SaveToDatabase();
+
+            // Update the SubAgentSpec with the created ID so parent can reference it
+            SubAgentSpec.SubAgent.ID = childId;
+
+            console.log(`✅ saveChildSubAgent: Created child sub-agent with ID: ${childId}`);
+        } else {
+            // SubAgent already exists - just ensure ParentID is set correctly
+            console.log(`🔗 saveChildSubAgent: Updating existing child sub-agent "${SubAgentSpec.SubAgent.ID}"...`);
+
+            const md = new Metadata();
+            const childEntity = await md.GetEntityObject<AIAgentEntity>(
+                'AI Agents',
+                this._contextUser
+            );
+
+            const loaded = await childEntity.Load(SubAgentSpec.SubAgent.ID);
+            if (!loaded) {
+                throw new Error(`Child agent ${SubAgentSpec.SubAgent.ID} not found in database`);
+            }
+
+            // Update parent ID if needed
+            if (childEntity.ParentID !== parentId) {
+                console.log(`🔗 saveChildSubAgent: Setting ParentID to ${parentId}`);
+                childEntity.ParentID = parentId;
+                const saved = await childEntity.Save();
+                if (!saved) {
+                    throw new Error(`Failed to update ParentID for child agent ${SubAgentSpec.SubAgent.ID}`);
+                }
+            } else {
+                console.log(`✅ saveChildSubAgent: ParentID already correct`);
             }
         }
     }
@@ -716,7 +753,7 @@ export class AgentSpecSync {
 
         // Map fields
         relationshipEntity.AgentID = agentId;
-        relationshipEntity.SubAgentID = SubAgentSpec.SubAgentID;
+        relationshipEntity.SubAgentID = SubAgentSpec.SubAgent.ID;
         relationshipEntity.Status = 'Active';
 
         // Serialize mapping fields
@@ -740,13 +777,101 @@ export class AgentSpecSync {
 
         const saved = await relationshipEntity.Save();
         if (!saved) {
-            throw new Error(`Failed to save relationship for sub-agent ${SubAgentSpec.SubAgentID}`);
+            throw new Error(`Failed to save relationship for sub-agent ${SubAgentSpec.SubAgent.ID}`);
         }
 
         // Update spec with saved ID
         SubAgentSpec.AgentRelationshipID = relationshipEntity.ID;
     }
 
+    /**
+     * Save all prompts for this agent.
+     *
+     * Creates AIPrompt records (with template) and AIAgentPrompt junction records.
+     * Supports simplified prompt format from Architect Agent with just PromptText,
+     * PromptRole, and PromptPosition.
+     *
+     * @private
+     * @param agentId - The parent agent ID
+     * @throws {Error} If any prompt save fails
+     */
+    private async savePrompts(agentId: string): Promise<void> {
+        console.log(`💬 savePrompts: Called with agentId=${agentId}, Prompts=${this.spec.Prompts ? this.spec.Prompts.length : 'undefined'}`);
+
+        if (!this.spec.Prompts || this.spec.Prompts.length === 0) {
+            console.log('💬 savePrompts: No prompts to save, returning early');
+            return;
+        }
+
+        console.log(`💬 savePrompts: Processing ${this.spec.Prompts.length} prompt(s)...`);
+        const md = new Metadata();
+
+        for (let i = 0; i < this.spec.Prompts.length; i++) {
+            const promptSpec = this.spec.Prompts[i];
+
+            // Create AIPrompt entity
+            const promptEntity = await md.GetEntityObject<any>(
+                'AI Prompts',
+                this._contextUser
+            );
+
+            // Set required fields
+            promptEntity.Name = `${this.spec.Name} - Prompt ${i + 1}`;
+            promptEntity.Description = `Agent prompt ${i + 1} for ${this.spec.Name}`;
+            promptEntity.TypeID = 'a6da423e-f36b-1410-8dac-00021f8b792e'; // Chat type
+            promptEntity.Status = 'Active';
+            promptEntity.ResponseFormat = 'JSON';
+
+            // Handle prompt text - supports both string and object formats
+            if (typeof (promptSpec as any).PromptText === 'string') {
+                promptEntity.TemplateText = (promptSpec as any).PromptText;
+            } else if (typeof (promptSpec as any).PromptText === 'object') {
+                // Architect may send PromptText as {text: "...", json: {...}}
+                const promptTextObj = (promptSpec as any).PromptText as any;
+                let combinedText = promptTextObj.text || '';
+                if (promptTextObj.json) {
+                    combinedText += '\n\n```json\n' + JSON.stringify(promptTextObj.json, null, 2) + '\n```';
+                }
+                promptEntity.TemplateText = combinedText;
+            }
+
+            // Set prompt role and position if provided
+            if ((promptSpec as any).PromptRole) {
+                promptEntity.PromptRole = (promptSpec as any).PromptRole;
+            }
+            if ((promptSpec as any).PromptPosition) {
+                promptEntity.PromptPosition = (promptSpec as any).PromptPosition;
+            }
+
+            const saved = await promptEntity.Save();
+            if (!saved) {
+                throw new Error(`Failed to save prompt ${i + 1} for agent ${this.spec.Name}`);
+            }
+
+            console.log(`✅ savePrompts: Created AIPrompt with ID: ${promptEntity.ID}`);
+
+            // Create AIAgentPrompt junction
+            const agentPromptEntity = await md.GetEntityObject<any>(
+                'MJ: AI Agent Prompts',
+                this._contextUser
+            );
+
+            agentPromptEntity.AgentID = agentId;
+            agentPromptEntity.PromptID = promptEntity.ID;
+            agentPromptEntity.ExecutionOrder = i;
+            agentPromptEntity.Status = 'Active';
+
+            const junctionSaved = await agentPromptEntity.Save();
+            if (!junctionSaved) {
+                throw new Error(`Failed to save agent-prompt junction for prompt ${i + 1}`);
+            }
+
+            console.log(`✅ savePrompts: Created AIAgentPrompt junction with ID: ${agentPromptEntity.ID}`);
+        }
+
+        console.log(`✅ savePrompts: Successfully saved all ${this.spec.Prompts.length} prompt(s)`);
+    }
+
     // ===== UTILITY METHODS =====
 
     /**
@@ -804,14 +929,15 @@ export class AgentSpecSync {
             MinExecutionsPerRun: partial.MinExecutionsPerRun,
             MaxExecutionsPerRun: partial.MaxExecutionsPerRun,
             StartingPayloadValidation: partial.StartingPayloadValidation,
-            StartingPayloadValidationMode: partial.StartingPayloadValidationMode || (() => 'Fail'),
+            StartingPayloadValidationMode: partial.StartingPayloadValidationMode || 'Fail',
             DefaultPromptEffortLevel: partial.DefaultPromptEffortLevel,
             ChatHandlingOption: partial.ChatHandlingOption,
             DefaultArtifactTypeID: partial.DefaultArtifactTypeID,
             OwnerUserID: partial.OwnerUserID,
             InvocationMode: partial.InvocationMode || 'Any',
             Actions: partial.Actions || [],
-            SubAgents: partial.SubAgents || []
+            SubAgents: partial.SubAgents || [],
+            Prompts: partial.Prompts || []
         };
     }
 
@@ -871,4 +997,4 @@ export class AgentSpecSync {
     public markDirty(): void {
         this._isDirty = true;
     }
-}
+}

package/src/agents/architect-agent.ts

@@ -0,0 +1,293 @@
+import { BaseAgent, PayloadManager } from '@memberjunction/ai-agents';
+import { ExecuteAgentParams, BaseAgentNextStep, AgentSpec } from '@memberjunction/ai-core-plus';
+import { AIAgentRunEntityExtended, AIAgentRunStepEntityExtended, ActionEntity, AIPromptEntity } from '@memberjunction/core-entities';
+import { Metadata, RunView } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+
+/**
+ * Architect Agent - Transforms technical design into validated AgentSpec JSON
+ *
+ * This agent creates AgentSpec objects from technical designs and validates them
+ * before passing to the Builder Agent for persistence. It overrides validateSuccessNextStep
+ * to ensure the generated AgentSpec is valid before proceeding.
+ *
+ * Key responsibilities:
+ * - Transform design documents into AgentSpec format
+ * - Validate required fields are present
+ * - Verify action IDs exist in database
+ * - Verify prompt IDs exist (if specified)
+ * - Validate SubAgent structure
+ * - Auto-correct minor issues (casing, missing optional fields)
+ * - Force retry with detailed errors if validation fails
+ */
+@RegisterClass(BaseAgent, 'AgentArchitectAgent')
+export class AgentArchitectAgent extends BaseAgent {
+
+    /**
+     * Applies payload changes if any are requested in the next step
+     */
+    protected applyPayloadChanges<P>(payload: P, nextStep: BaseAgentNextStep<P>): P {
+        if (nextStep.payloadChangeRequest) {
+            const pm = new PayloadManager();
+            const result = pm.applyAgentChangeRequest<P>(payload, nextStep.payloadChangeRequest);
+            return result.result || payload;
+        }
+        return payload;
+    }
+
+    protected override async validateSuccessNextStep<P>(
+        params: ExecuteAgentParams,
+        nextStep: BaseAgentNextStep<P>,
+        currentPayload: P,
+        agentRun: AIAgentRunEntityExtended,
+        currentStep: AIAgentRunStepEntityExtended
+    ): Promise<BaseAgentNextStep<P>> {
+        // First call base validation
+        const baseValidation = await super.validateSuccessNextStep(params, nextStep, currentPayload, agentRun, currentStep);
+        if (baseValidation.step === 'Retry') {
+            return baseValidation;
+        }
+
+        // Apply payload changes to get the spec that would be sent forward
+        const payloadWithChanges = this.applyPayloadChanges<P>(currentPayload, nextStep);
+
+        // Extract the agentSpec from the nested payload structure
+        // The payload has structure: { metadata, requirements, design, agentSpec }
+        const agentSpec = (payloadWithChanges as any).agentSpec as AgentSpec;
+
+        console.log('🏗️ Architect Agent: Validating AgentSpec:', agentSpec ? `Name="${agentSpec.Name}"` : 'agentSpec is null/undefined');
+
+        // Validate the AgentSpec
+        const validation = await this.validateAgentSpec(agentSpec, params);
+
+        if (validation.errors.length > 0) {
+            console.log('❌ Architect Agent: Validation failed with errors:', validation.errors);
+            // Return retry with detailed error messages
+            return {
+                ...nextStep,
+                step: 'Retry',
+                retryInstructions: this.formatValidationErrors(validation.errors),
+                newPayload: nextStep.newPayload
+            };
+        }
+
+        // If spec was auto-corrected, update the payload with corrected spec
+        if (validation.correctedSpec) {
+            console.log('✓ Architect Agent: Auto-corrected AgentSpec, updating payload');
+            const updatedPayload = {
+                ...(payloadWithChanges as any),
+                agentSpec: validation.correctedSpec
+            };
+            return {
+                ...nextStep,
+                newPayload: updatedPayload as P
+            };
+        }
+
+        console.log('✅ Architect Agent: AgentSpec validation passed');
+        return nextStep;
+    }
+
+    /**
+     * Validates an AgentSpec object
+     * Returns errors array and potentially a corrected spec
+     */
+    protected async validateAgentSpec(
+        spec: AgentSpec,
+        params: ExecuteAgentParams
+    ): Promise<{ errors: string[]; correctedSpec?: AgentSpec }> {
+        const errors: string[] = [];
+        let corrected = false;
+
+        // Check if spec exists
+        if (!spec) {
+            errors.push('❌ AgentSpec is null or undefined. Ensure you place the AgentSpec in payload.agentSpec (inside a payloadChangeRequest with newElements or replaceElements)');
+            return { errors };
+        }
+
+        const correctedSpec = { ...spec };
+
+        // 1. Validate required fields
+        if (!correctedSpec.Name || correctedSpec.Name.trim().length === 0) {
+            errors.push('❌ AgentSpec.Name is required and cannot be empty');
+        }
+
+        if (!correctedSpec.StartingPayloadValidationMode) {
+            // Auto-correct: add default
+            correctedSpec.StartingPayloadValidationMode = 'Fail';
+            corrected = true;
+            console.log('✓ Auto-corrected: Added default StartingPayloadValidationMode = "Fail"');
+        } else if (correctedSpec.StartingPayloadValidationMode !== 'Fail' && correctedSpec.StartingPayloadValidationMode !== 'Warn') {
+            errors.push(`❌ StartingPayloadValidationMode must be either "Fail" or "Warn", got: "${correctedSpec.StartingPayloadValidationMode}"`);
+        }
+
+        // 2. Validate Actions if specified
+        if (correctedSpec.Actions && correctedSpec.Actions.length > 0) {
+            const actionValidation = await this.validateActions(correctedSpec.Actions, params);
+            if (actionValidation.errors.length > 0) {
+                errors.push(...actionValidation.errors);
+            }
+        }
+
+        // 3. Validate SubAgents if specified
+        if (correctedSpec.SubAgents && correctedSpec.SubAgents.length > 0) {
+            const subAgentValidation = this.validateSubAgents(correctedSpec.SubAgents);
+            if (subAgentValidation.errors.length > 0) {
+                errors.push(...subAgentValidation.errors);
+            }
+            if (subAgentValidation.corrected) {
+                corrected = true;
+            }
+        }
+
+        // 4. Validate optional but important fields
+        if (correctedSpec.FinalPayloadValidationMode &&
+            !['Fail', 'Retry', 'Warn'].includes(correctedSpec.FinalPayloadValidationMode)) {
+            errors.push(`❌ FinalPayloadValidationMode must be "Fail", "Retry", or "Warn", got: "${correctedSpec.FinalPayloadValidationMode}"`);
+        }
+
+        if (correctedSpec.InvocationMode &&
+            !['Any', 'Agent', 'User', 'Never'].includes(correctedSpec.InvocationMode)) {
+            errors.push(`❌ InvocationMode must be "Any", "Agent", "User", or "Never", got: "${correctedSpec.InvocationMode}"`);
+        }
+
+        return {
+            errors,
+            correctedSpec: corrected ? correctedSpec : undefined
+        };
+    }
+
+    /**
+     * Validates that action IDs exist in the database
+     */
+    protected async validateActions(
+        actions: AgentSpec['Actions'],
+        params: ExecuteAgentParams
+    ): Promise<{ errors: string[] }> {
+        const errors: string[] = [];
+
+        if (!actions || actions.length === 0) {
+            return { errors };
+        }
+
+        try {
+            const rv = new RunView();
+            const actionIds = actions
+                .map(a => a.ActionID)
+                .filter(id => id && id.trim().length > 0);
+
+            if (actionIds.length === 0) {
+                errors.push('❌ All actions must have an ActionID');
+                return { errors };
+            }
+
+            // Query database for these action IDs
+            const filter = actionIds.map(id => `ID='${id}'`).join(' OR ');
+            const result = await rv.RunView<ActionEntity>({
+                EntityName: 'Actions',
+                ExtraFilter: filter,
+                ResultType: 'entity_object'
+            }, params.contextUser);
+
+            if (!result.Success) {
+                errors.push(`❌ Failed to validate actions: ${result.ErrorMessage}`);
+                return { errors };
+            }
+
+            const foundIds = new Set(result.Results.map(a => a.ID));
+
+            // Check which actions weren't found
+            for (const action of actions) {
+                if (!action.ActionID) {
+                    errors.push('❌ Action is missing ActionID field');
+                    continue;
+                }
+
+                if (!foundIds.has(action.ActionID)) {
+                    errors.push(`❌ Action with ID "${action.ActionID}" not found in database. Please use "Find Best Action" or "List Actions" to get valid action IDs.`);
+                }
+            }
+
+        } catch (error: any) {
+            errors.push(`❌ Error validating actions: ${error?.message || String(error)}`);
+        }
+
+        return { errors };
+    }
+
+    /**
+     * Validates SubAgent structure
+     */
+    protected validateSubAgents(
+        subAgents: AgentSpec['SubAgents']
+    ): { errors: string[]; corrected: boolean } {
+        const errors: string[] = [];
+        let corrected = false;
+
+        if (!subAgents || subAgents.length === 0) {
+            return { errors, corrected };
+        }
+
+        for (let i = 0; i < subAgents.length; i++) {
+            const subAgent = subAgents[i];
+
+            // Validate Type field
+            if (!subAgent.Type) {
+                errors.push(`❌ SubAgent at index ${i} is missing required "Type" field (must be "child" or "related")`);
+                continue;
+            }
+
+            if (subAgent.Type !== 'child' && subAgent.Type !== 'related') {
+                errors.push(`❌ SubAgent at index ${i} has invalid Type "${subAgent.Type}" (must be "child" or "related")`);
+                continue;
+            }
+
+            // Validate SubAgent.SubAgent field
+            if (!subAgent.SubAgent) {
+                errors.push(`❌ SubAgent at index ${i} is missing required "SubAgent" field`);
+                continue;
+            }
+
+            // SubAgent.ID can be empty string "" for NEW sub-agents (Builder creates them recursively)
+            // Only validate that ID is not null/undefined
+            if (subAgent.SubAgent.ID === null || subAgent.SubAgent.ID === undefined) {
+                errors.push(`❌ SubAgent at index ${i} has null/undefined SubAgent.ID (use empty string "" for new sub-agents, or provide existing agent GUID)`);
+            }
+
+            // Validate SubAgent.SubAgent.Name
+            if (!subAgent.SubAgent.Name || subAgent.SubAgent.Name.trim().length === 0) {
+                errors.push(`❌ SubAgent at index ${i} is missing SubAgent.Name`);
+            }
+
+            // Auto-correct: Add default StartingPayloadValidationMode if missing
+            if (!subAgent.SubAgent.StartingPayloadValidationMode) {
+                subAgent.SubAgent.StartingPayloadValidationMode = 'Fail';
+                corrected = true;
+                console.log(`✓ Auto-corrected: Added SubAgent[${i}].SubAgent.StartingPayloadValidationMode = "Fail"`);
+            }
+
+            // Validate related-specific fields
+            if (subAgent.Type === 'related' && !subAgent.AgentRelationshipID) {
+                // AgentRelationshipID can be empty for new relationships, it will be created on save
+                // This is not an error
+            }
+        }
+
+        return { errors, corrected };
+    }
+
+    /**
+     * Formats validation errors into a clear, actionable message
+     */
+    protected formatValidationErrors(errors: string[]): string {
+        if (errors.length === 0) {
+            return '';
+        }
+
+        const header = '## AgentSpec Validation Errors\n\nThe generated AgentSpec has the following issues that must be fixed:\n\n';
+        const errorList = errors.map((err, idx) => `${idx + 1}. ${err}`).join('\n');
+        const footer = '\n\n**Please fix these issues and regenerate the AgentSpec.**';
+
+        return header + errorList + footer;
+    }
+}

package/src/agents/builder-agent.ts

@@ -0,0 +1,89 @@
+import { BaseAgent } from '@memberjunction/ai-agents';
+import { ExecuteAgentParams, AgentConfiguration, BaseAgentNextStep, AgentSpec } from '@memberjunction/ai-core-plus';
+import { RegisterClass } from '@memberjunction/global';
+import { AgentSpecSync } from '../agent-spec-sync';
+
+/**
+ * Builder Agent - Persists validated AgentSpec to database via AgentSpecSync
+ *
+ * This is a code-based agent that overrides executeAgentInternal to bypass
+ * the normal chat loop and directly execute persistence logic. It receives
+ * a validated AgentSpec from the Architect Agent and saves it to the database
+ * using AgentSpecSync.
+ *
+ * Key responsibilities:
+ * - Receive validated AgentSpec from payload
+ * - Create AgentSpecSync instance
+ * - Persist to database
+ * - Return success with created agent ID, or failure with error details
+ *
+ * This agent does NOT iterate - it runs once and returns Success or Failed.
+ */
+@RegisterClass(BaseAgent, 'AgentBuilderAgent')
+export class AgentBuilderAgent extends BaseAgent {
+
+    /**
+     * Override executeAgentInternal to run code instead of chat loop
+     * This follows the Skip Code Generator pattern
+     */
+    protected override async executeAgentInternal<P = any>(
+        params: ExecuteAgentParams<P>,
+        _config: AgentConfiguration
+    ): Promise<{ finalStep: BaseAgentNextStep<P>; stepCount: number }> {
+
+        console.log('🔨 Builder Agent: Starting agent persistence...');
+
+        try {
+            // Extract AgentSpec from nested payload structure
+            // The payload has structure: { metadata, requirements, design, agentSpec }
+            const agentSpec = (params.payload as any).agentSpec as AgentSpec;
+
+            if (!agentSpec) {
+                throw new Error('No AgentSpec found in payload.agentSpec - ensure Architect Agent placed it there');
+            }
+
+            if (!agentSpec.Name) {
+                throw new Error('AgentSpec is missing required Name field');
+            }
+
+            console.log(`🔨 Builder Agent: Creating agent "${agentSpec.Name}"...`);
+
+            // Create AgentSpecSync instance
+            const specSync = new AgentSpecSync(agentSpec, params.contextUser);
+
+            // Mark as dirty to ensure it saves
+            specSync.markDirty();
+
+            // Save to database
+            const agentId = await specSync.SaveToDatabase();
+
+            console.log(`✅ Builder Agent: Successfully created agent with ID: ${agentId}`);
+
+            // Return success with the created agent ID
+            const updatedSpec = { ...agentSpec, ID: agentId };
+
+            return {
+                finalStep: {
+                    terminate: true,
+                    step: 'Success',
+                    reasoning: `Successfully created agent "${agentSpec.Name}" with ID: ${agentId}`,
+                    newPayload: updatedSpec as P
+                },
+                stepCount: 1
+            };
+
+        } catch (error: any) {
+            console.error('❌ Builder Agent: Failed to create agent:', error);
+
+            // Return failure with error details
+            return {
+                finalStep: {
+                    terminate: true,
+                    step: 'Failed',
+                    reasoning: `Failed to create agent: ${error?.message || String(error)}`
+                },
+                stepCount: 1
+            };
+        }
+    }
+}