Add builder wizard for guided agent creation #20
Description
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.tsxwith 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.tsxwithRoleManagementPanel.tsx,PermissionRequestsPanel.tsx,AuthorizerManagementPanel.tsx. - Memory Management:
MemoryManagementPage.tsxwithMemoryManagementPanel.tsxandMemoryCard.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.tsxalongside 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:
- Embed the existing component (e.g., render
RoleManagementPanelinline for Step 3) with wizard-specific props to indicate selection mode, or - 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.tsxfrontend/src/components/wizard/steps/WizardStepRuntime.tsxfrontend/src/components/wizard/steps/WizardStepSecurity.tsxfrontend/src/components/wizard/steps/WizardStepMemory.tsxfrontend/src/components/wizard/steps/WizardStepMcpServers.tsxfrontend/src/components/wizard/steps/WizardStepA2aAgents.tsxfrontend/src/components/wizard/steps/WizardStepAuthorizer.tsxfrontend/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.tsxmust 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.tsxmust continue to showAgentRegistrationFormas 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-indexlayering 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
AgentDeployRequesttype 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
AgentDeployRequestand 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