Add builder wizard for guided agent creation

[heeki]

Add builder wizard for guided agent creation

Summary

Add a step-by-step wizard overlay that guides builders through the full agent creation process. The wizard provides a linear, dependency-aware flow through all configuration steps — from agent identity through deployment — while allowing users to skip optional steps and exit at any time to complete configuration manually. The wizard is an additive feature; all existing functionality on the platform must continue to work without it.

Context

The platform's builder workflow currently lives in AgentRegistrationForm.tsx as a single-page deploy form with collapsible sections. As the platform grows to include memory resources (issue #15), MCP server integrations (issue #18), A2A agent integrations (issue #19), and IAM role management (issue #17), the number of configuration options is increasing significantly. New users may not understand the correct order of operations or which steps depend on others (e.g., an IAM role must exist before memory permissions can be requested for it).

The wizard addresses this by presenting a curated, ordered sequence of steps with clear progress indication, required/optional labeling, and inline guidance. It does not replace the existing pages — it overlays on top of them, navigating the user through the platform's existing UI.

Current Frontend Architecture

• Navigation: Persona-based sidebar in App.tsx with sections: Catalog, Agents (builder), Memory, Security, MCP Servers (disabled), A2A Agents (disabled).
• Agent Deploy Form: AgentRegistrationForm.tsx — single-page form with sections for identity, behavior, model/protocol/network/IAM role, permissions, authorizer, lifecycle, and integrations (memory, MCP, A2A currently disabled).
• Security Admin: SecurityAdminPage.tsx with RoleManagementPanel.tsx, PermissionRequestsPanel.tsx, AuthorizerManagementPanel.tsx.
• Memory Management: MemoryManagementPage.tsx with MemoryManagementPanel.tsx and MemoryCard.tsx.
• No existing wizard or stepper components exist in the codebase.

Wizard Step Order and Dependencies

The wizard steps follow a dependency-aware order. Steps marked "required" must be completed (or confirmed as already done) before the wizard allows proceeding to deployment.

Step 1: Agent Identity & Behavior      [required]  — name, description, system prompt
Step 2: Model & Runtime Configuration  [required]  — model selection, protocol, network mode, lifecycle
Step 3: Security - IAM Role            [required]  — select or create an IAM role
Step 4: Memory                         [optional]  — select or create memory resources, request IAM permissions
Step 5: MCP Servers                    [optional]  — select MCP server integrations
Step 6: A2A Agents                     [optional]  — select A2A agent integrations
Step 7: Authorizer                     [optional]  — select an authorizer configuration
Step 8: Review & Deploy                [required]  — review all selections, deploy the agent

Key dependency: Step 4 (Memory) depends on Step 3 (IAM Role) because memory permissions must be attached to the selected role. Steps 5 and 6 depend on their respective features being available (issues #18 and #19). Step 8 requires Steps 1, 2, and 3 to be complete.

Requirements

R1: Wizard Progress and Step Navigation

The wizard should provide clear progress indication and allow the user to start it easily from the builder page.

Entry Point

• Add a "Launch Wizard" button on the AgentListPage.tsx alongside the existing "Deploy" mode toggle. The button should be visually prominent for new users (e.g., a primary-colored button with a wand/sparkle icon and label like "Guided Setup").
• Clicking "Launch Wizard" opens the wizard overlay.

Progress Indicator

Create a stepper/progress bar component that displays all wizard steps with:

Visual State	Meaning
Completed (checkmark)	Step has been finished
Current (highlighted)	Step the user is currently on
Upcoming (dimmed)	Step not yet reached
Skipped (skip icon)	Optional step that was explicitly skipped
Required badge	Small label indicating the step cannot be skipped
Optional badge	Small label indicating the step can be skipped

The progress indicator should be visible at all times during the wizard — either as a vertical stepper on the left side of the wizard overlay or as a horizontal stepper at the top.

Step Navigation

• "Next" button advances to the next step (disabled if current required step is incomplete).
• "Back" button returns to the previous step, preserving all entered data.
• "Skip" button appears only on optional steps and advances to the next step.
• Clicking a completed step in the progress indicator navigates back to that step for editing.
• Clicking an upcoming step is not allowed (must proceed sequentially).

Wizard State

All wizard state (form values, step completion status, current step) should be held in a single context or state object so that navigating between steps does not lose data.

Files to Create

• frontend/src/components/wizard/BuilderWizard.tsx — Main wizard container managing step state, navigation, and overlay rendering.
• frontend/src/components/wizard/WizardProgress.tsx — Stepper/progress indicator component.
• frontend/src/components/wizard/WizardStepLayout.tsx — Shared layout wrapper for each step (title, description, navigation buttons).
• frontend/src/context/WizardContext.tsx — React context for wizard state management (form values, step status, current step index).

Files to Modify

• frontend/src/pages/AgentListPage.tsx — Add "Launch Wizard" button.

R2: Exit Wizard and Manual Completion

The user should be able to quit the wizard at any point and continue configuring manually using the existing platform pages.

Exit Behavior

• Add an "Exit Wizard" button (e.g., X icon in the top-right corner of the overlay) visible on every step.
• When clicked, show a confirmation dialog: "Exit the wizard? Your progress so far has been saved to the platform. You can continue configuring manually."
• On confirmation, close the wizard overlay and return the user to the builder page (AgentListPage).
• Any resources already created during the wizard (e.g., an IAM role created in Step 3, a memory resource created in Step 4) persist — they were created via the existing backend APIs and are independent of the wizard.
• Form values entered but not yet submitted (e.g., a partially filled agent identity) are discarded on exit, since no backend call was made. The confirmation dialog should note this: "Unsaved changes in the current step will be lost."

No Wizard Lock-In

• The wizard must not create any state that only exists within the wizard. Every action the wizard performs (creating a role, creating a memory resource, deploying an agent) must use the same backend API endpoints that the existing pages use.
• After exiting, all platform pages (Security, Memory, Agents) reflect any changes made during the wizard session.

Files to Modify

• frontend/src/components/wizard/BuilderWizard.tsx — Add exit button, confirmation dialog, and cleanup logic.
• frontend/src/components/wizard/WizardStepLayout.tsx — Include exit button in the shared step layout.

R3: Required and Optional Steps with Skip Logic

Steps in the wizard should be clearly marked as required or optional. Optional steps can be skipped; required steps must be completed before the user can proceed to Review & Deploy.

Step Definitions

Step	Name	Required	Can Skip	Validation to Proceed
1	Agent Identity & Behavior	Yes	No	Agent name is non-empty and valid (matches ^[a-zA-Z][a-zA-Z0-9_]{0,47}$); model is selected
2	Model & Runtime Config	Yes	No	Model selected; protocol and network mode have values (defaults are acceptable)
3	Security - IAM Role	Yes	No	A managed role is selected (existing or newly created)
4	Memory	No	Yes	If not skipped: at least one memory resource is selected or created
5	MCP Servers	No	Yes	If not skipped: at least one MCP server is selected
6	A2A Agents	No	Yes	If not skipped: at least one A2A agent is selected
7	Authorizer	No	Yes	If not skipped: an authorizer config is selected
8	Review & Deploy	Yes	No	Steps 1, 2, and 3 are completed; user confirms and clicks Deploy

Step Content

Each step should render a focused view of the relevant configuration. Rather than duplicating form logic from existing components, each wizard step should either:

1. Embed the existing component (e.g., render RoleManagementPanel inline for Step 3) with wizard-specific props to indicate selection mode, or
2. Create a slim wizard step component that calls the same APIs and reuses the same form patterns but is tailored to the single-step context.

Option 2 is preferred for steps where the existing component is too complex or page-oriented (e.g., SecurityAdminPage has tabs). Option 1 is preferred where components are already self-contained (e.g., MemoryManagementPanel).

Wizard Step Components

Step	Component	Approach
1	WizardStepIdentity.tsx	New — focused agent name, description, and system prompt fields (extract from AgentRegistrationForm)
2	WizardStepRuntime.tsx	New — focused model, protocol, network, lifecycle fields (extract from AgentRegistrationForm)
3	WizardStepSecurity.tsx	New — role selection dropdown with inline "Create New Role" option; shows selected role's policy
4	WizardStepMemory.tsx	New — list existing memory resources with selection checkboxes; inline "Create Memory" form; auto-prompt for IAM permission request if a memory resource is selected
5	WizardStepMcpServers.tsx	New — list registered MCP servers with selection checkboxes (depends on issue #18)
6	WizardStepA2aAgents.tsx	New — list registered A2A agents with selection checkboxes (depends on issue #19)
7	WizardStepAuthorizer.tsx	New — authorizer config selection dropdown with summary display
8	WizardStepReview.tsx	New — read-only summary of all selections with Deploy button

Disabling Unavailable Steps

Steps 5 (MCP Servers) and 6 (A2A Agents) depend on issues #18 and #19 respectively. If those features are not yet available:

• Show the step in the progress indicator as "Coming Soon" with a dimmed state.
• Auto-skip these steps during navigation (Back/Next skips over them).
• Once the features are implemented, the steps become active with no wizard code changes needed — only the step components need to be updated to call the real APIs.

Files to Create

• frontend/src/components/wizard/steps/WizardStepIdentity.tsx
• frontend/src/components/wizard/steps/WizardStepRuntime.tsx
• frontend/src/components/wizard/steps/WizardStepSecurity.tsx
• frontend/src/components/wizard/steps/WizardStepMemory.tsx
• frontend/src/components/wizard/steps/WizardStepMcpServers.tsx
• frontend/src/components/wizard/steps/WizardStepA2aAgents.tsx
• frontend/src/components/wizard/steps/WizardStepAuthorizer.tsx
• frontend/src/components/wizard/steps/WizardStepReview.tsx

R4: Dependency-Aware Step Flow

The wizard step order must reflect real dependencies between platform resources so the user doesn't encounter errors or missing prerequisites.

Dependency Rules

Dependency	Explanation	Wizard Enforcement
Memory requires IAM Role	Memory permissions must be attached to the agent's execution role. Without a role, there is nothing to attach permissions to.	Step 4 (Memory) comes after Step 3 (Security). If the user goes back and changes the IAM role in Step 3, show a warning on Step 4 that the role has changed and permissions may need to be re-requested.
MCP/A2A require registration	MCP servers and A2A agents must already be registered on the platform before they can be selected as integrations.	Steps 5 and 6 show only already-registered resources. Provide a link to the respective management page if no resources exist ("No MCP servers registered. Go to MCP Servers page to add one, or skip this step.").
Deploy requires identity + model + role	The deploy API requires agent name, model ID, and role ARN at minimum.	Step 8 (Review & Deploy) validates that Steps 1, 2, and 3 are all marked complete. The Deploy button is disabled with a message listing any incomplete required steps.

Role Change Propagation

If the user completes Step 4 (Memory) and then goes back to Step 3 (Security) and selects a different IAM role:

• Step 4 should be marked as "needs review" (visual indicator, e.g., a warning icon on the progress step).
• When the user reaches Step 4 again, show a banner: "You changed the IAM role. Memory permissions were requested for the previous role. You may need to re-request permissions for the new role."
• Do not automatically invalidate or delete the previous permission requests — they are backend resources and may still be useful.

Review Step Summary

Step 8 (Review & Deploy) should display a read-only summary organized by step:

Section	Content
Agent Identity	Name, description
System Prompt	Agent description, behavioral guidelines, output expectations (truncated with expand)
Runtime	Model name, protocol, network mode, idle timeout, max lifetime
IAM Role	Role name and ARN
Memory	List of selected memory resource names (or "Skipped")
MCP Servers	List of selected MCP server names (or "Skipped" or "Not available")
A2A Agents	List of selected A2A agent names (or "Skipped" or "Not available")
Authorizer	Authorizer config name (or "None")

Below the summary, a "Deploy" button that calls the same onDeploy handler used by AgentRegistrationForm, assembling the AgentDeployRequest from wizard state. Show the same deployment progress timer as the existing form.

Files to Modify

• frontend/src/context/WizardContext.tsx — Add dependency tracking, "needs review" state per step, and role-change detection logic.
• frontend/src/components/wizard/steps/WizardStepMemory.tsx — Add role-change warning banner.
• frontend/src/components/wizard/steps/WizardStepReview.tsx — Add full summary display and deploy action.
• frontend/src/components/wizard/WizardProgress.tsx — Add "needs review" visual state (warning icon).

R5: Preserve Existing Functionality

The wizard must not break any existing platform functionality. All current pages and workflows must continue to work independently of the wizard.

Non-Breaking Constraints

• The existing AgentRegistrationForm.tsx must remain fully functional. Builders who prefer the single-page form can continue using it without any changes to their workflow.
• The "Deploy" mode toggle on AgentListPage.tsx must continue to show AgentRegistrationForm as it does today. The wizard is a separate entry point.
• All existing pages (Catalog, Security, Memory) must remain accessible and functional regardless of wizard state.
• The wizard does not modify any existing component's behavior. It only adds new components and a new entry point.
• Navigation between personas (sidebar items) must continue to work. If the wizard is open and the user clicks a sidebar item, the wizard should close (with confirmation if there are unsaved changes).

Wizard as Overlay

• The wizard should render as a full-screen or near-full-screen overlay (e.g., a modal or slide-over panel) on top of the existing UI.
• Use a semi-transparent backdrop so the user understands they are in the wizard context.
• The overlay should use z-index layering so it does not interfere with the existing sidebar or page layout when dismissed.

Implementation Approach

• All wizard components live in a new frontend/src/components/wizard/ directory — no existing component files should be modified except to add the wizard entry point.
• Wizard state is isolated in WizardContext — no global state pollution.
• The wizard assembles its output into the same AgentDeployRequest type and calls the same API as the existing deploy form.

Files to Modify

• frontend/src/pages/AgentListPage.tsx — Add "Launch Wizard" button (only addition to existing files).
• frontend/src/App.tsx — Add wizard overlay rendering and WizardContext provider (wrap existing layout, no changes to existing routing or persona logic).

Dependencies

• Issue Add ability to create IAM roles and submit policy permission requests #17 (IAM Role Creation) — Step 3 benefits from the wizard-mode role creation but can fall back to role selection if only import is available.
• Issue Add memory management frontend #15 (Memory Management) — Step 4 requires the memory management backend and frontend to be available.
• Issue Add MCP server integration #18 (MCP Servers) — Step 5 is disabled/auto-skipped until MCP server management is implemented.
• Issue Add A2A agent integration #19 (A2A Agents) — Step 6 is disabled/auto-skipped until A2A agent management is implemented.

Files to Create

File	Description
frontend/src/components/wizard/BuilderWizard.tsx	Main wizard container with overlay, step routing, and navigation
frontend/src/components/wizard/WizardProgress.tsx	Stepper/progress bar component with step states
frontend/src/components/wizard/WizardStepLayout.tsx	Shared layout for each step (title, description, nav buttons, exit)
frontend/src/context/WizardContext.tsx	React context for all wizard state, step status, and dependency tracking
frontend/src/components/wizard/steps/WizardStepIdentity.tsx	Step 1: Agent name, description, system prompt
frontend/src/components/wizard/steps/WizardStepRuntime.tsx	Step 2: Model, protocol, network, lifecycle
frontend/src/components/wizard/steps/WizardStepSecurity.tsx	Step 3: IAM role selection or creation
frontend/src/components/wizard/steps/WizardStepMemory.tsx	Step 4: Memory resource selection and permission requests
frontend/src/components/wizard/steps/WizardStepMcpServers.tsx	Step 5: MCP server integration selection
frontend/src/components/wizard/steps/WizardStepA2aAgents.tsx	Step 6: A2A agent integration selection
frontend/src/components/wizard/steps/WizardStepAuthorizer.tsx	Step 7: Authorizer configuration selection
frontend/src/components/wizard/steps/WizardStepReview.tsx	Step 8: Summary review and deploy action

Files to Modify

File	Description
frontend/src/pages/AgentListPage.tsx	Add "Launch Wizard" button alongside existing deploy toggle
frontend/src/App.tsx	Add WizardContext.Provider wrapper and BuilderWizard overlay rendering

Acceptance Criteria

• A "Guided Setup" / "Launch Wizard" button appears on the Agent list page
• Clicking the button opens a full-screen wizard overlay with a progress stepper
• The stepper shows all 8 steps with required/optional badges and correct visual states (completed, current, upcoming, skipped)
• "Next" is disabled on required steps until validation passes (name, model, IAM role)
• "Back" returns to the previous step with all form data preserved
• "Skip" is available on optional steps (Memory, MCP Servers, A2A Agents, Authorizer) and advances to the next step
• Clicking a completed step in the stepper navigates back to that step
• "Exit Wizard" button is visible on every step and shows a confirmation dialog before closing
• After exiting, all resources created during the wizard (roles, memory, permission requests) persist on the platform
• Unsaved form data in the current step is noted as being lost in the exit confirmation
• Steps 5 and 6 (MCP Servers, A2A Agents) show as "Coming Soon" and are auto-skipped when those features are not yet available
• Step 4 (Memory) comes after Step 3 (Security) and shows a warning if the IAM role is changed after memory permissions were requested
• Step 8 (Review & Deploy) shows a read-only summary of all configured values organized by step
• Step 8 validates that all required steps are complete before enabling the Deploy button
• Deploying from the wizard uses the same AgentDeployRequest and API endpoint as the existing deploy form
• The existing deploy form (AgentRegistrationForm) continues to work identically — no regressions
• All existing pages (Catalog, Security, Memory) remain fully functional
• Sidebar navigation closes the wizard (with confirmation if unsaved changes exist)
• Wizard state is isolated in context — no global state side effects