Python version option for agents-cli deploy

[joar]

What is your feature suggestion?

Add a python version option to the agents-cli deploy command when deploying with agent runtime.

What will this enable you to do?

This will enable users to pick a python version that their dependencies are compatible with.

Additional context

vertexai._genai.AgentEngineConfig has a python_version field, but today it's impossible to set that field via agents-cli. This means that some users can't deploy their code with their existing dependencies to agent runtime via agents-cli because they have dependencies that are incompatible with e.g. Python 3.14, so they need to be able to configure agents-cli deploy to use Python 3.12.

[optimization2026]

I think this should be part of a deployment environment contract.

The deploy command needs to distinguish:

CLI interpreter Python
project declared Python
build Python
runtime Python
dependency wheel compatibility

A user-facing --python-version option would solve the immediate need, but the CLI should also validate that the chosen version is consistent with project metadata.

A standard AISP V1.0.0 companion contract could express this:

[
  {
    "role": "system",
    "content": {
      "protocol": "AISP V1.0.0",
      "axiom_0": "Human_Sovereignty_and_Wellbeing",
      "id": "google_agents_cli_deploy_python_version_aisp",
      "name": "Google Agents CLI Deploy Python Version Contract",
      "version": "1.0.0",
      "license": "Apache-2.0",
      "summary": "A machine-checkable AISP package for selecting and validating deployment Python versions.",
      "description": "Ensures Agent Runtime deployment uses a Python version compatible with the project metadata and dependencies, not merely the CLI interpreter.",
      "flow_format": "mermaid",
      "loading_mode": "node",
      "tools": ["filesystem", "shell"],
      "params": {
        "project_root": "string",
        "python_version": "string?"
      },
      "system_prompt": ""
    }
  },
  {
    "role": "user",
    "content": {
      "instruction": "STRICTLY OBEY aisp_contract; its non_negotiable rules are inviolable; then RUN aisop.main",
      "user_input": "{user_input}",
      "aisp_contract": {
        "profile": "aisp.skill.v1",
        "invocation": {
          "mode": "deploy_environment_validation",
          "when_to_use": [
            "before deploying to Agent Runtime",
            "when --python-version is provided",
            "when project pyproject.toml declares requires-python",
            "when dependency compatibility may differ from CLI interpreter Python"
          ],
          "when_not_to_use": [
            "local-only run with no remote build",
            "deployment target that does not use Python"
          ]
        },
        "non_negotiable": [
          {
            "rule": "Deployment Python version must be explicit or derived from project metadata, not silently from the CLI interpreter.",
            "enforced_by": "select_version.step2:sys.assert"
          },
          {
            "rule": "Chosen deployment Python version must satisfy project requires-python.",
            "enforced_by": "validate_project.step2:sys.assert"
          },
          {
            "rule": "Deploy request must pass the chosen Python version into AgentEngineConfig when target supports it.",
            "enforced_by": "build_config.step2:sys.assert"
          }
        ],
        "discovery": {
          "category": "deployment",
          "tags": ["agents-cli", "deploy", "python-version", "agent-runtime", "aisp"]
        },
        "risk_level": "high",
        "resources": [
          {
            "id": "project_root",
            "path": "{project_root}",
            "kind": "repository",
            "mode": "read_only",
            "when": "Read before deployment environment validation.",
            "scope": "skill"
          }
        ]
      },
      "aisop": {
        "main": "graph TD\n    read_project[Read project metadata] --> select_version[Select deployment Python]\n    select_version --> validate_project[Validate project compatibility]\n    validate_project --> build_config[Build AgentEngineConfig]\n    build_config --> trace[Record deployment environment trace]\n    trace --> end_node((End))"
      },
      "functions": {
        "read_project": {
          "step1": "Read pyproject.toml, requirements, lock files, and existing manifest.",
          "output_mapping": "project_metadata"
        },
        "select_version": {
          "step1": "Select python_version from CLI flag, manifest, or project requires-python.",
          "step2": "sys.assert('deployment python version not silently derived from CLI interpreter', 'Deploy Python must be explicit or project-derived')",
          "output_mapping": "selected_python_version"
        },
        "validate_project": {
          "step1": "Check selected_python_version against requires-python and known dependency constraints.",
          "step2": "sys.assert('selected python satisfies project requires-python', 'Selected deploy Python incompatible with project')",
          "output_mapping": "python_version_validation"
        },
        "build_config": {
          "step1": "Pass selected_python_version into AgentEngineConfig.python_version if supported.",
          "step2": "sys.assert('AgentEngineConfig includes selected Python version', 'Deploy config must carry Python version')",
          "output_mapping": "agent_engine_config_status"
        },
        "trace": {
          "step1": "Record CLI Python, project requires-python, selected deploy Python, source of selection, and validation result.",
          "output_mapping": "deployment_python_trace"
        },
        "end_node": {
          "step1": "Return deployment_python_trace."
        }
      }
    }
  }
]

This would make --python-version a user override on top of a clearer model:

CLI Python:
  runs agents-cli

Project Python:
  declared by the agent project

Deploy Python:
  used by remote Agent Runtime build

Those should not be silently conflated.

[joar]

This would make --python-version a user override on top of a clearer model:

@optimization2026 I don't see how your proposed model is clearer than adding a --python-version flag for a few reasons:

"sys.assert('deployment python version not silently derived from CLI interpreter', 'Deploy Python must be explicit or project-derived')"

• deriving python version from CLI interpreter is not a problem in this case, and was not proposed
• I don't see how asserting this via an LLM would help when deterministic tests can be used.

I also found that you seem to be automating these posts with little concern about relevance:

• Add AI Skill Protocol Engineer agent msitarzewski/agency-agents#633
• Add a standard AISP agency index for routing, validation, and host-specific exports msitarzewski/agency-agents#632
• Add a standard AISP/AISOP contract for /autoplan phase gates, evidence labels, and task aggregation garrytan/gstack#2137
• Use a standard AISP package as the source of truth for the bundled hermes-agent skill NousResearch/hermes-agent#55375
• [IMPROVE] Add skill quality validator for tags, workflow completeness, prerequisite consistency, and safety gates mukul975/Anthropic-Cybersecurity-Skills#86
• # Add optional skill-index.json for large skill catalogs and plugin packs openai/skills#498
• # Add optional machine-readable workflow companions for image-to-code and redesign quality gates Leonxlnx/taste-skill#57
• Add optional machine-readable workflow companion specs for complex gated skills addyosmani/agent-skills#309
• ## Feature: Role-aware scanning for structured skill formats such as AISOP/AISP NVIDIA/SkillSpector#130
• [Community Integration Proposal] Minimal AISOP execution graph for the OpenSpec propose workflow Fission-AI/OpenSpec#1217
  • [Community Integration Proposal] Minimal AISOP execution graph for the OpenSpec propose workflow Fission-AI/OpenSpec#1217 (comment) - poorly formatted self-reply
• agent-spec/.github/workflows /tests.yaml use aisop by any llm to run oracle/agent-spec#198
• [Feature]: Add a standard AISP/AISOP proposal contract for Skill Workshop openclaw/openclaw#98002
  • [Feature]: Add runtime testing for skill workshop proposals before apply openclaw/openclaw#98069 (comment)

[eliasecchig]

Hi @joar - thanks for flagging this. We just release in 0.6 support for Agent Runtime Container Based deployment.

Going forward, every scaffold with Agent Runtime will include a Dockerfile. This brings full flexibility to your deployment. It also means you are free to set the desired python version there, defaulting to 3.12.