Agent V2 Configure Interface#

The Agent V2 configure interface lives under web/features/agent-v2/agent-detail/configure/ and drives both the Agent App configure page and the inline configure surface inside Workflow Agent nodes. It composes agent-composer editable state with server synchronization, build chat sessions, version viewing, build draft mode, and the preview side panel 1.

The page renders a split-pane layout:

• Left pane (Orchestrate) — the agent configuration editor (prompt, tools, skills, knowledge, model, environment variables, etc.)
• Right pane (Preview surface) — an interactive chat interface for testing; contains either Build or Preview mode chat

The right panel mode is tracked via URL query parameter ?mode=build|preview using nuqs, defaulting to build and using history: 'replace' so navigation doesn't pollute browser history 2.

Build Mode vs. Preview Mode#

The right panel header exposes a SegmentedControl with Build and Preview tabs 3. The two modes serve distinct purposes:

Preview mode is feature-gated: it is disabled on Community Edition. The page reads deployment_edition from the system-features API and computes previewEnabled = deploymentEdition !== 'COMMUNITY' 4. When disabled, the Preview tab renders in a tooltip-wrapped disabled state 5, and any ?mode=preview URL param is silently overridden to build 6.

Build mode renders AgentBuildChat with draftType="debug_build" and a "Start build" send label. It shows a decorative empty state until the first message is sent 7.

The Build Draft System#

The build draft is a server-side isolated snapshot of the agent's soul config, created and modified conversationally during a build chat session, separate from the normal composer draft the user is editing.

The useAgentConfigureBuildDraftData hook 8 manages the lifecycle:

1. Detection: Queries GET /agents/{agent_id}/build-draft. All build-draft requests are made silently (context silent: true). If the API returns 404, there is no active build draft, and soulSourceOverride is set to 'draft'. Non-404 errors show a toast 9.
2. Active state: When a build draft exists, soulSource resolves to 'build-draft', and the orchestrate pane displays the build draft config rather than the normal draft 10.
3. Change summary: A diff is computed between the build draft and the current composer state across skills, files, and env variables — surfaced as AgentBuildDraftChangeSummary 11. This powers the change indicator UI shown while a build draft is active.

The useAgentConfigureBuildDraftActions hook 12 exposes the terminal actions:

• Apply (applyBuildDraft): Calls POST /agents/{id}/build-chat/finalize, then POST /agents/{id}/build-draft/apply, invalidates query caches, and exits build-draft mode by rebasing the composer to the updated config 13.
• Discard (discardBuildDraft): Calls DELETE /agents/{id}/build-draft and exits build-draft mode without rebasing 14.
• Refresh after build chat (refreshBuildDraftAfterBuildChat): Debounced 1 s after the last build chat message, refetches the build draft and rebases the composer 15.
• Start fresh session (startFreshBuildSession): Resets the build chat conversation and forces a checkout of the current draft before the next run 16.

Soul Source: The Config Source Abstraction#

AgentConfigureSoulSource is a union type with three values that determines which agent config is rendered in the orchestrate pane:

Resolution logic 17: 'view-version' takes precedence → then explicit soulSourceOverride → then build-draft existence → falls back to 'draft'. Critically, if the user switches to Preview mode while a build draft is active, the source is forced back to 'draft' — you cannot preview an uncommitted build draft 18.

Draft Autosave#

The normal composer draft (not the build draft) autosaves via useAgentConfigureSync:

• 5-second debounce after any composer change
• Deduplication via lastAutosavedDraftKeyRef, explicitlySavingDraftKeysRef, and a saveSequence counter to prevent duplicate API calls
• Page-close persistence: saves pending dirty drafts on visibilitychange / beforeunload using keepalive requests
• Autosave is suspended when a build draft is active or a version is being viewed

Version Restore#

The configure interface supports restoring published versions via Restore actions available in:

• Version item menu (three-dot kebab) in the versions panel
• Publish bar at the bottom when a version is open

Before restoring, any pending draft saves complete to prevent autosave from overwriting the restored configuration. The AgentVersionRestore component 19 encapsulates the version restoration interaction, providing both confirmation and upgrade dialog stages while keeping them mutually exclusive. The component automatically resets the restore session when leaving version view (when selectedVersionSnapshot becomes null).

Deployment-specific Restore Behavior#

After successful restoration, the orchestrate pane rebases to the restored config, and the composer returns to editing the draft. Version restore is disabled when a build draft is active, when publishing, or when the user lacks release/version permissions.

Key Source Files#