Entity Versioning

​

Overview

Key Concepts

• Base Version: The initial version created when you first save an agent, automatically named “base”. This version can be continuously updated and saved without creating new versions.
• Named Versions: Specific snapshots of your agent configuration that are saved with custom names for easy identification and management. Named versions can also be edited and saved independently when selected.
• Default Version: A designated version that is automatically used when the agent is added to conversations, other agents, pipelines, or as an MCP toolkit. The default version is marked with a pin icon in the version dropdown.
• Version History: A complete record of all versions created for an agent, including creation dates, status, and author information.
• Version Sharing: The ability to share a specific version with others either via a direct URL link or by exporting the version as a file.

​

Creating and Managing Agent Versions

​

Initial Save (“Base” Version)

1. Create Your Agent: Configure instructions, tools, settings, and other parameters.
2. Click Save: This creates the initial “base” version of your agent.
3. Continue Editing: You can modify and save changes to the initial “base” version

​

Creating New Versions

When you want to preserve a specific configuration:

1. Click “Save As Version” button in the top toolbar
2. Enter Version Name: Provide a descriptive name for your version
   • Keep names under 20 characters
   • Only alphanumeric characters, hyphens (-), and underscores (_) are allowed
   • Use clear, descriptive names (e.g., “prod-v1”, “beta-test”)
3. Click Save: The new version is created and becomes the current active version. The system automatically navigates to the newly created version, updates the version dropdown to show the new version, and updates the URL to reflect the new version ID. You can immediately continue editing the new version or switch to another version.

​

Version Selection and Navigation

The version dropdown is located in the top toolbar. Click any version to switch and view its configuration. When you switch, the system loads the selected version’s complete configuration, updates the URL to include the new version ID, updates all form fields to show the selected version’s data, and updates the breadcrumb navigation. Any unsaved changes in the previous version are preserved (you’ll see them if you switch back).

• Each version displays:
  • Version name (e.g., “v1.0”, “base”)
  • Creation metadata in format: “Month DD, YYYY, HH:MM · by Author Name” (e.g., “Mar 15, 2024, 14:30 · by John Smith”)
  • Visual indicators: Pin icon for default version, publish icon for published versions
• Includes a search field with placeholder to quickly find specific versions

Versions are sorted by creation date (newest first), with “base” always appearing at the bottom:

​

Editing and Saving Changes

• All versions (including “base” and named versions) are editable. Click Save to persist changes to the version that is currently selected.
• To branch off without modifying the current version, use Save As Version to create a new version instead of overwriting the selected one.

​

Default Version Management

​

What is a Default Version?

The default version is a special designation that determines which version of your agent is automatically used in various contexts. When you set a version as default, it becomes the version that is automatically selected when:

• Adding the agent to new conversations
• Adding the agent to existing conversations
• Using the agent as a toolkit in other agents or pipelines
• Accessing the agent as an MCP (Model Context Protocol) toolkit

​

How to Set a Default Version

There are two ways to set a version as default: Option 1: Using the Version Dropdown

1. Click the version dropdown in the top toolbar
2. Find the version you want to set as default
3. Click the pin icon (📌) next to the version name
4. Review the confirmation dialog explaining the impact
5. Click “Set as a default” to confirm

Option 2: Using the Three-Dot Menu

1. Navigate to the version you want to designate as default
2. Click the three-dot menu (⋮) in the toolbar
3. Select “Set as default”
4. Review the confirmation dialog explaining the impact
5. Click “Set as a default” to confirm

The default version will now be marked with a pin icon (📌) in the version dropdown.

​

Publishing Versions

Publishing makes an agent version available in Agent HUB, where it can be discovered and used by all ELITEA users. Key Features:

• Guided Three-Step Wizard: Publish through preparation, AI-powered validation, and submission steps
• AI-Powered Validation: Automated validation identifies issues and improvement areas before publishing
• Category Selection: Agents are organized by category for easy discovery in Agent HUB
• Publishing Terms: Review what’s included/excluded and best-practice requirements
• Permission Required: You must have models.applications.publish.post permission

Quick Publishing Flow:

1. Open the agent and select the version to publish
2. Click the three-dot menu (⋮) and select Publish
3. Complete the three-step wizard:
   • Preparation: Enter version name, select category, agree to terms
   • Validation: AI review checks configuration and provides feedback
   • Submission: Review and submit for moderation

Unpublishing: Published agents can be unpublished at any time through the three-dot menu. This immediately removes the agent from Agent HUB.

​

Sharing Versions

ELITEA provides two complementary ways to share a specific version of an agent or pipeline with other users: copying a direct link to the version and exporting the version as a file.

​

Copy Link

The Copy link option generates a direct URL to the currently selected version and copies it to your clipboard. Anyone with project access can open the link and land directly on that version. How to Copy a Version Link:

1. Select the version you want to share using the version dropdown in the top toolbar.
2. Open the three-dot menu (⋮) in the toolbar.
3. Click ”🔗 Share” — the menu icon changes to a checkmark briefly and a toast notification confirms: “The link has been copied to the clipboard.”
4. Paste and share the copied URL with your colleagues.

​

Export Version

The Export option downloads the currently selected version as a Markdown (.md) file. The exported file contains the full configuration of the version — instructions, tools, LLM settings, and all other parameters — and can be stored, shared, or imported into another project. How to Export a Version:

1. Select the version you want to export using the version dropdown.
2. Open the three-dot menu (⋮) in the toolbar.
3. Click “Export” — the browser immediately downloads a .md file named after the agent or pipeline.
4. Share the file via email, a Git repository, a shared drive, or any other channel.
5. The recipient can import the file into their own project.

​

Using Versions in Conversations and Nested Agents

Version Selection in Conversations When you add an agent to a conversation:

• The default version (if set) is automatically selected
• If no default version is set, the “base” version is used
• You can switch to a different version at any time during the conversation using the version dropdown in the chat interface
• Each conversation maintains its own version selection independently

Version Selection in Nested Agents/Pipelines When adding an agent as a toolkit in another agent or pipeline:

• The default version (if set) is automatically selected during the initial setup
• If no default version is set, the “base” version is used
• You can manually select a specific version from the version dropdown when configuring the toolkit
• The selected version is saved with the parent agent/pipeline configuration
• Changing the default version in the source agent does not automatically update nested references - you must manually update the version selection in each parent agent/pipeline

​

Compare Versions

The Compare Versions feature allows you to view side-by-side differences between two versions of an agent or skill and selectively adopt changes from one version to the other.

​

Access Compare Versions

To compare two versions:

1. Open any saved agent or skill with at least two versions.
2. Select the three-dot menu (⋮) in the entity tab bar.
3. Select Compare Versions.
4. The Compare Versions dialog opens with the current version pre-selected under the Base version.
5. From the Compare with dropdown, select the version you want to compare against.
6. Select Compare to load both versions and enter the comparison wizard.

​

How Compare Versions Works

The wizard presents a step-by-step comparison across different configuration areas: For Agents:

1. Instructions: View a diff of the instructions field showing added, removed, and unchanged text.
2. User Interaction: Compare Welcome Message and Conversation Starters side-by-side.
3. Tools & Skills: See which toolkits, MCPs, agents, pipelines, and skills were added, removed, or kept the same between versions.

For Skills:

1. Instructions: View a diff of the instructions field showing added, removed, and unchanged text.

​

Making Changes

For each comparison step, you can:

• View differences: See what changed between the two versions with visual highlighting.
• Adopt changes: Copy changes from either version to the other by selecting the desired content.
• Save individually: Each editable section (Instructions, Welcome Message, Conversation Starters) has its own Save button. Changes are applied immediately when you save.

​

Deleting Versions

How to Delete a Version The deletion process depends on whether the version is being used by other agents or pipelines: Option 1: Version NOT in Use

1. Select the version you want to delete
2. Click “Delete Version” button
3. Confirm deletion in the dialog
4. The version is deleted and you’re redirected to the default version (if set) or “base” version

Option 2: Version IS in Use

1. Select the version you want to delete
2. Click “Delete Version” button
3. Version Replacement modal appears showing:
   • List of all agents/pipelines currently using this version
   • Count of affected entities
4. Select a replacement version from the dropdown (defaults to default version or “base”)
5. Confirm deletion
6. The system will:
   • Delete the selected version
   • Automatically update all references to use the replacement version
   • Show success message with count of updated references
7. You’re redirected to the default version (if set) or “base” version

​

Best Practices

Version Naming Conventions

• Use Semantic Versioning: v1.0, v1.1, v2.0
• Include Purpose: production-release, beta-test, hotfix-001
• Date-based: 2024-01-15-release, jan-2024-update
• Feature-based: enhanced-search, multi-lang-support

Version Management Strategy

1. Keep “base” for Development: Use for ongoing work and experimentation
2. Create Named Versions for Milestones: Save stable configurations
3. Set a Default Version: Designate your most stable version as default for production use
4. Publish Tested Versions: Only submit well-tested versions for publication
5. Document Changes: Use descriptive names that indicate what changed

Sharing Best Practices

• Use Copy Link for quick sharing: When collaborating within the same project, copy the link to a specific version and send it directly — your colleague lands on exactly the right version.
• Use Export for cross-project sharing: Export the version and import it into a different project or share the .md file in a code repository.
• Version before sharing: Create a named version (rather than sharing the base version) so the shared state cannot accidentally change.
• Store exports in version control: Keep exported .md files in a Git repository alongside your project code to track the history of your agents.

Workflow Recommendations

Development Workflow:

1. Work on changes in “base” version
2. Test thoroughly in Chat interface
3. Create named version when stable (e.g., “v1.0”)
4. Set the stable version as default for production use
5. Continue development in “base”
6. When ready for next release, create new named version (e.g., “v1.1”)
7. Test the new version
8. Update default version to roll out changes to all users

Team Collaboration:

• Create versions before major changes
• Use consistent naming conventions
• Set clear default versions for production
• Document version purposes and changes
• Test versions before setting as default or publishing
• Communicate default version changes to team members

​

Troubleshooting

Cannot Delete Version

• Ensure you’re not trying to delete the “base” version (base cannot be deleted)
• Cannot delete the default version - set a different version as default first
• Check that you have proper delete permissions
• If version is in use by other agents/pipelines, you must select a replacement version

Version Name Validation Errors

• Version names must be 20 characters or less
• Only alphanumeric characters, hyphens (-), and underscores (_) are allowed
• Version name must be unique within the agent/pipeline
• Cannot use “base” as a version name (reserved)

Version Not Found

• Refresh the page to reload version list
• Check if version was deleted by another user
• Verify project permissions

Publishing Issues

• Ensure you have applications.publish permission
• Only Draft status versions can be published
• Version must belong to an Agent (Pipelines cannot be published)
• Ensure all required fields are completed
• Check that tools are properly configured
• Verify model settings are valid

Copy Link Not Working

• Make sure your browser allows clipboard access — some browsers block clipboard writes unless the page is served over HTTPS or the user has explicitly granted permission.
• If the link does not copy, check for a browser extension that may be blocking clipboard API calls.
• Alternatively, copy the URL directly from the browser’s address bar while on the specific version page.

Export Fails or Downloads Empty File

• Confirm that you are on a version detail page (a version must be selected in the dropdown).
• For Agent Studio (public project) exports, at least one version must be in Published status; otherwise the export file will be empty.
• Check your network connection and try again — the export is a live download from the ELITEA server.
• If the problem persists, open the browser developer console and check for any network errors on the export request.

---