Implementation Plan: Agent Workflow Framework Namespace and Versioning System

This plan integrates three core concepts: Namespacing, Semantic Versioning, and Deployment Pruning.

Phase 1: Foundational Changes - The New Agent Identifier (Unchanged)

The cornerstone of this system is a new, structured agent identifier. We will move from a simple agent_name string to a path-like string.

1.1. Define the New Identifier Schema:
The new agent identifier will be a string with the format:
/{namespace}/{sub-namespace/...}/{agent_base_name}/v{MAJOR}.{MINOR}

• Examples:

  • /protocol/database/postgres_query/v1.0

  • /protocol/networking/smb_put/v1.1

  • /ai/text_completion/ollama_generate/v2.0

  • /data/string/regex_extractor/v1.0

1.2. Update config.json Structure:
The top-level agents object will now be keyed by these full, unique identifiers. All existing agents must be manually migrated to this new format. This is a one-time breaking change to the config structure, but the file remains a flat dictionary.

• Example config.json snippet:

• {
    "agents": {
      "/protocol/database/postgres_query/v1.0": { ... },
      "/protocol/database/postgres_query/v1.1": { ... },
      "/protocol/database/postgres_query/v2.0": { ... }
    }
  }
    

1.3. Core Engine (dynamic_workflows_agents.py) Modifications:

• CLI: The command-line argument for the agent name must now accept the full path-like identifier.

• exec_agent: No changes needed. It already accepts the full agent name.

• Workflow Steps: Steps in a workflow will now store the full, specific versioned identifier (e.g., /protocol/database/postgres_query/v1.1). This "pins" the workflow to a specific, stable version, which is crucial for reliability.

---

Phase 2: IDE User Interface Overhaul (Revised)

This phase focuses on making the new system intuitive and powerful for developers within the editor.

2.1. Agent List (Agent Panel) - Flat List with Smart Filtering:
The agent list will remain a flat CTkScrollableFrame. The full, versioned names (e.g., /protocol/database/postgres_query/v1.0) will be displayed for every agent. The existing search box functionality will naturally allow users to filter this list (e.g., typing postgres will show all versions of that agent). This keeps the implementation simple while leveraging the descriptive power of the new naming convention.

2.2. Drag-and-Drop Enhancement (The "Version Selector" Dialog):

• Modify _on_agent_drag_start: When a user drags any version of an agent (e.g., /protocol/database/postgres_query/v1.1), the drag payload will be the agent's base name (e.g., /protocol/database/postgres_query).

• Modify _on_drop: When the drop occurs:

  1. The IDE will find all available MAJOR versions for that base name (e.g., v1, v2).

  2. It will display a small, modal dialog under the mouse pointer with buttons for each Major version: [v1], [v2].

  3. When the user clicks a version (e.g., v1), the IDE finds the latest MINOR version within that major branch (e.g., v1.1 is chosen over v1.0).

  4. A new step is inserted into the workflow, pinned to that specific latest minor version (.../postgres_query/v1.1).
     

2.2.5. The "Interface-Aware" Editor and "Never Overwrite" Save Logic:

• On Editor Load: The editor still creates the initial_interface snapshot.

• On Save (save_agent in ui_app_shell.py):

  1. Get current form data and compare its interface to the initial_interface snapshot.

  2. If a breaking change is detected:
     a. Force a Major Version Bump: Calculate the new identifier by incrementing MAJOR and resetting MINOR to 0 (e.g., .../v1.1 -> .../v2.0).
     b. Notify and Save: Inform the user that a new MAJOR version is being created. Save the changes as a new agent under the new identifier. The original agent is untouched.

  3. If no breaking change is detected:
     a. Force a Minor Version Bump: Calculate the new identifier by incrementing MINOR (e.g., .../v1.1 -> .../v1.2).
     b. Notify and Save: Inform the user that a new MINOR version is being created. Save the changes as a new agent under the new identifier. The original agent is untouched.

• Result: Every single save action that modifies an agent's logic or interface results in a new, immutable agent definition being added to the config.json. The history is automatically preserved.

• 
  

2.3. Step Editor (ui_step_editor.py) Enhancement:

• "Version" Dropdown: In the Step Editor, for any step using a versioned agent, add a new dropdown field labeled "Version".

• Populate Dropdown: This dropdown will be populated with all available versions of the same agent (e.g., v1.0, v1.1, v2.0).

• Behavior: When a user changes the version, the Step Editor should immediately refresh, showing the correct inputs for the newly selected version and using the existing "orphaned parameter" UI to flag any incompatibilities.

2.3.5. Step Editor (ui_step_editor.py) Enhancement (Revised):

• "Version" Dropdown: This dropdown is now even more critical.

• Populate Dropdown: It will be populated with all available versions of the agent, PLUS the special @latest option for each major version (e.g., v1.0, v1.1, v1.2, v1@latest, v2.0, v2@latest).

• Behavior: The user can explicitly pin a workflow step to a specific version (v1.1) for absolute stability, or they can choose a "floating" reference (v1@latest) to automatically get the newest non-breaking updates for that major version branch.

2.4. Automatic Versioning on Save:

• Action: Remove the manual "Create New Version" buttons. The save_agent function in ui_app_shell.py will now handle versioning automatically and intelligently.

• On Editor Load: The editor creates an in-memory snapshot of the agent's interface (inputs, optional_inputs, outputs).

• On Save:

  1. The IDE compares the current state of the interface fields to the initial snapshot.

  2. If a breaking change is detected (any difference in the input or output interface, or deleting an optional input, but you are free to add optional inputs):
     a. Force a Major Version Bump: A new agent identifier is calculated by incrementing the MAJOR version (e.g., .../v1.1 -> .../v2.0).
     b. Notify A  floating dialog informs the user that the save increased the major version number.
     c. The changes are saved as a new agent under the new identifier.

  3. If no breaking change is detected:
     a.  create a new MINOR version (e.g., .../v1.1 -> .../v1.2).
     b. The changes are saved according to the user's choice.
     c. A floating dialog announces a save with a minor version update. 

  
  
  

2.5  Only keep the last x number of changes and keep any version that are specified in an interface.      

To keep from having hundreds of versions of every agent with every little change we can create a policy that only keeps a specific number of minor agent versions of each major version.  This would not delete any agents that are specifically named in a step with that exact minor version.  

Phase 3: Deployment Tooling

This phase introduces a new, standalone utility script for creating production-ready service configurations.

3.1. Create deployment_tool.py:

• Purpose: To take a development config.json and "prune" it to create a lean, production-ready config.release.json.

• Command-Line Interface:

      python deployment_tool.py --source config.dev.json --output config.prod.json --service public_api
    

3.2. Tool Logic:

• Input: Takes a source config file path and an optional --service <tag> argument.

• Agent Discovery:

  1. It first finds all agents that match the --service tag.

  2. It then recursively scans the steps of these entry-point workflows to discover every single agent version that is actually used by that service.

• Pruning Process:

  1. It creates a new, empty config dictionary.

  2. It copies over only the agents that were found in the dependency graph.

  3. For each agent it copies, it strips out development-only keys: run_config and gui.

• Output: Writes the new, pruned config.release.json file.