Technical Specification: Agent Platform Deployment & Lifecycle Management System

J. Rogers, SE Ohio, 03 Aug 2025, 1445

1. Overview

This document specifies the architecture and functionality of a two-part system designed for the secure, versioned, and auditable deployment of Agent Platform configurations. The system consists of:

• The Agent Build & Packaging Utility (agent-builder): A development-side tool that compiles heavyweight, developer-focused agent configurations into a minimal, secure, versioned deployment package. Also includes other files as needed for a complete upgrade tool.

• The Agent Deployment Manager (adm): A production-side CLI tool that manages the lifecycle of these packages, including deployment, atomic activation, rollbacks, and auditing.

A key feature of this system is the ability for a deployment package to declaratively orchestrate its required filesystem structure on the target server, ensuring that all necessary directories and data files are in place upon deployment.

2. Goals and Scope

• Goals:

  • To provide a clear separation between development and production agent configurations.

  • To create self-contained, versioned, and portable deployment packages ("flat packs").

  • To ensure deployments are atomic and minimize service interruption.

  • To provide a full, auditable history of all deployment and rollback activities.

  • To enable declarative management of required production server files and directories.

  • To enforce security through minimalism and access control.

• Non-Goals:

  • This system does not manage the underlying server infrastructure (VMs, containers, networking).

  • It does not manage the installation of the core Python engine or its dependencies.

  • It is not a real-time secrets management system (though it can place pre-defined config files).

3. System Component 1: The Agent Build & Packaging Utility (agent-builder)

This is a command-line tool used in the development environment.

• Purpose: To consume the full developer configuration and produce a lightweight production deployment package.

• Inputs:

  1. --config <path>: Path to the heavyweight dev_config.json.

  2. --entry-points <agent1,agent2,...>: A comma-separated list of the top-level agents to be included.

  3. --version <x.y.z>: The semantic version for this build.

  4. --output-dir <path>: Directory to save the final package.

• Process:

  1. Dependency Resolution: The tool starts with the --entry-points and recursively scans all workflow steps to build a complete, minimal set of all required agent dependencies.

  2. Configuration Stripping: For each agent in the final dependency set, it creates a lean, execution-only definition by removing keys such as gui_proc_def, gui_manifest, help, and function_def.

  3. Asset Collection: It reads the manifest.json from the source directory (if one exists) to find a filesystem_spec. It collects all local files specified in copy_file actions and places them into an assets/ directory within the package.

  4. Packaging: It creates a versioned .zip file (e.g., deploy-package-v1.2.0.zip) containing:

     • config.json: The final, stripped-down agent configurations.

     • manifest.json: Metadata about the build, including the filesystem spec.

     • assets/: A directory containing all files needed for copy_file operations.

• Output: A single, versioned .zip deployment package.

4. The Deployment Package Specification

The .zip artifact is the "flat pack," a self-contained unit of deployment.

Example Structure (deploy-package-v1.2.0.zip):

Generated code

/
├── config.json
├── version.json
├── manifest.json
└── assets/
    └── rag_data.csv
    └── templates/
        └── welcome_email.txt
    

5. The Manifest File Specification (manifest.json)

This file is central to the deployment process, containing both metadata and orchestration instructions.

Structure:
      {

  "package_version": "1.2.0",
  "build_timestamp_utc": "2023-10-27T14:30:00Z",
  "entry_points": [
    "daily_finance_report",
    "user_onboarding_workflow"
  ],
  "source_info": {
    "git_commit_hash": "a1b2c3d4e5f6g7h8",
    "build_user": "dev-builder"
  },
  "filesystem_spec": {
    "allowed_base_paths": [ "/var/data/agent_platform/", "/var/log/agent_platform/" ],
    "operations": [
      {
        "action": "create_dir",
        "path": "/var/log/agent_platform/finance_reports",
        "permissions": "0755"
      },
      {
        "action": "copy_file",
        "source": "assets/rag_data.csv",
        "destination": "/var/data/agent_platform/rag/finance_data.csv",
        "permissions": "0644"
      },
      {
        "action": "copy_file",
        "source": "assets/templates/welcome_email.txt",
        "destination": "/var/data/agent_platform/templates/welcome_email.txt",
        "permissions": "0644"
      }
    ]
  }
}
    

• filesystem_spec.allowed_base_paths: A security feature. The adm tool will refuse to perform any operation on a path that does not start with one of these prefixes.

• filesystem_spec.operations: An ordered list of filesystem actions to be performed by the adm tool upon deployment.

6. System Component 2: The Agent Deployment Manager (adm)

This is a production-side CLI for managing the entire deployment lifecycle. It operates on a standardized server directory structure (e.g., /opt/agent_platform/).

CLI Specification:

• adm deploy <version> --user <username> --reason "<message>"

  • Purpose: Deploys and activates a new version.

  • Workflow:

    1. Verifies the existence of packages/deploy-package-v<version>.zip.

    2. Performs pre-flight checks: validates zip integrity and manifest.json.

    3. Creates a new release directory: releases/<version>/.

    4. Unzips the package contents into the new release directory.

    5. Executes Filesystem Orchestration:
       a. Iterates through the filesystem_spec.operations in the manifest.
       b. For each operation, it verifies the destination path is within the allowed_base_paths.
       c. It performs the create_dir or copy_file action with the specified permissions.
       d. If any operation fails, the entire deployment is aborted, the releases/<version>/ directory is cleaned up, and an error is logged.

    6. Atomic Activation: Atomically updates the active symlink to point to the new releases/<version>/ directory.

    7. Logs the event (user, reason, version, timestamp) and sends notifications.

• adm rollback --user <username> --reason "<message>" --deploy "<deployment id>"

  • Purpose: Reverts the active symlink to the previous valid deployment.

  • Workflow:

    1. Identifies the last active version if the deployment id is last from the deployment log. Otherwise it finds the file with the given deployment id.  

    2. Checks to make sure that version is complete and it was also not rolled back.

    3. Says that it is going to do and asks for permission.

    4. Atomically updates the active symlink.

    5. The last files that were deployed are deleted.
       The previous version is rolled back out to disk. 

    6. Logs the rollback event and sends notifications.

• adm history

  • Purpose: Displays the immutable deployment and rollback log, including dates, users, and reasons.

• adm status

  • Purpose: Shows the currently active version and deployment details.

• adm prune --keep <N>

  • Purpose: Safely removes old, inactive release directories to free up space, keeping the specified number of recent releases plus the active one.

7. Security Considerations

• The adm tool must be run by a specific system user with restricted permissions.

• The filesystem_spec.allowed_base_paths provides a critical safeguard against directory traversal and modification of sensitive system files. This configuration should be locked down on the production server.

• Deployment packages should have their checksums verified upon upload and before deployment to ensure integrity.

• The deployment log provides a non-repudiable audit trail for all changes to the production environment.