[Cognitiveservices] Add agent create to az cognitiveservices command for hosted agents: az cognitiveservices agent create (#32430)

Author: eamonoreilly

src/azure-cli/azure/cli/command_modules/cognitiveservices/_help.py

@@ -483,6 +483,160 @@
 short-summary: Control foundry agents.
 """
 
+helps[
+    "cognitiveservices agent create"
+] = """
+type: command
+short-summary: Create a new hosted agent from a container image or source code.
+long-summary: |
+    Create a new hosted agent deployment by either specifying a pre-built container image
+    or by building one from source code. When using --source, the container image is
+    automatically built and pushed to Azure Container Registry. Configure compute resources,
+    scaling behavior, environment variables, and communication protocols.
+parameters:
+  - name: --account-name -a
+    short-summary: Name of the Cognitive Services account.
+  - name: --project-name -p
+    short-summary: Name of the AI Foundry project.
+  - name: --name -n
+    short-summary: Name of the agent to create.
+  - name: --image
+    short-summary: Docker image URI with tag to use for the agent.
+    long-summary: |
+        Full Docker image URI including tag (e.g., myregistry.azurecr.io/myagent:v1.0).
+        The tag identifies which container image version to use. The AI Foundry service
+        automatically creates and manages the agent version independently.
+        Mutually exclusive with --source.
+  - name: --source
+    short-summary: Path to source directory containing Dockerfile.
+    long-summary: |
+        When provided, builds the Docker image from source code and pushes to ACR.
+        The image is built either locally (if Docker is available) or remotely using ACR Task.
+        Mutually exclusive with --image.
+  - name: --dockerfile
+    short-summary: Name of the Dockerfile in source directory (default is 'Dockerfile').
+    long-summary: Only used when --source is specified.
+  - name: --build-remote
+    short-summary: Force remote build using Azure Container Registry Task.
+    long-summary: |
+        By default, the CLI attempts to build locally if Docker is available,
+        otherwise builds remotely. Use this flag to force remote build.
+        Only used when --source is specified.
+  - name: --registry
+    short-summary: Azure Container Registry name or full URI.
+    long-summary: |
+        Short name (e.g., 'myregistry') will be expanded to myregistry.azurecr.io.
+        Full URIs (myregistry.azurecr.io) are also accepted.
+        Required when using --source.
+  - name: --cpu
+    short-summary: CPU allocation (default is 1 core).
+  - name: --memory
+    short-summary: Memory allocation with unit (default is 2Gi).
+    long-summary: Use units like '2Gi' for 2 gibibytes or '512Mi' for 512 mebibytes.
+  - name: --min-replicas
+    short-summary: Minimum number of replicas for scaling (default is 0).
+  - name: --max-replicas
+    short-summary: Maximum number of replicas for scaling (default is 3).
+  - name: --env --environment-variables
+    short-summary: Environment variables in key=value format.
+    long-summary: Space-separated list in format 'key1=value1 key2=value2'.
+  - name: --protocol
+    short-summary: Communication protocol (responses or streaming).
+  - name: --protocol-version
+    short-summary: Protocol version (default is v1).
+  - name: --timeout
+    short-summary: Maximum time in seconds to wait for deployment to be ready.
+    long-summary: |
+        Default is 600 seconds (10 minutes). Increase for large container images
+        or slow network conditions. The deployment process includes pulling the
+        container image, starting the container, and health checks.
+examples:
+  - name: Create agent from existing container image
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --image myregistry.azurecr.io/my-agent:v1.0
+  - name: Create agent by building from source (auto-detect build method)
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --source ./my-agent-code \\
+          --registry myregistry
+  - name: Create agent by building from source with custom Dockerfile name
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --source ./my-agent-code \\
+          --dockerfile Dockerfile.prod \\
+          --registry myregistry
+  - name: Create agent by building remotely with ACR Task
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --source ./my-agent-code \\
+          --registry myregistry \\
+          --build-remote
+  - name: Create agent with custom CPU and memory
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --image myregistry.azurecr.io/my-agent:v2.0 \\
+          --cpu 2 \\
+          --memory 4Gi
+  - name: Create agent with scaling configuration
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --image myregistry.azurecr.io/my-agent:v1.0 \\
+          --min-replicas 2 \\
+          --max-replicas 10
+  - name: Create agent with environment variables
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --image myregistry.azurecr.io/my-agent:v1.0 \\
+          --env MODEL_NAME=gpt-4 API_TIMEOUT=30 LOG_LEVEL=info
+  - name: Create agent with streaming protocol
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --image myregistry.azurecr.io/my-agent:v1.0 \\
+          --protocol streaming \\
+          --protocol-version v1
+  - name: Create agent using short registry name
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --image my-agent:v1.0 \\
+          --registry myregistry
+  - name: Create agent with extended timeout for large images
+    text: |
+        az cognitiveservices agent create \\
+          --account-name myAccount \\
+          --project-name myProject \\
+          --name my-agent \\
+          --image myregistry.azurecr.io/my-large-agent:v1.0 \\
+          --timeout 1200
+"""
+
 helps[
     "cognitiveservices agent start"
 ] = """

src/azure-cli/azure/cli/command_modules/cognitiveservices/_params.py

@@ -32,6 +32,41 @@
 name_arg_type = CLIArgumentType(options_list=["--name", "-n"], metavar="NAME")
 
 
+def _environment_variables_type(value: str) -> dict:
+    """
+    Parse environment variable in key=value format.
+
+    Args:
+        value: String in format 'KEY=value'
+
+    Returns:
+        dict: Dictionary with 'key' and 'value' keys
+
+    Raises:
+        ValueError: If format is invalid
+
+    Examples:
+        >>> _environment_variables_type('FOO=bar')
+        {'key': 'FOO', 'value': 'bar'}
+        >>> _environment_variables_type('CONNECTION_STRING=Server=localhost;Database=mydb')
+        {'key': 'CONNECTION_STRING', 'value': 'Server=localhost;Database=mydb'}
+    """
+    if '=' not in value:
+        raise ValueError(
+            f"Environment variable must be in 'key=value' format. Got: '{value}'"
+        )
+
+    # Split on first equals sign only (value might contain '=')
+    key, _, val = value.partition('=')
+
+    if not key:
+        raise ValueError(
+            f"Environment variable key cannot be empty. Got: '{value}'"
+        )
+
+    return {'key': key, 'value': val}
+
+
 def extract_key_values_pairs(api_properties):
     api_properties_dict = {}
     for item in api_properties:
@@ -340,14 +375,143 @@ def load_arguments(self, _):
             options_list=["--account-name", "-a"],
             help="cognitive service account name."
         )
-        c.argument("project_name", help="AI Project name")
+        c.argument(
+            "project_name",
+            options_list=["--project-name", "-p"],
+            help="AI project name"
+        )
         c.argument(
             "agent_name",
             options_list=["--name", "-n"],
             help="Cognitive Services hosted agent name",
         )
         c.argument("agent_version", help="Cognitive Services hosted agent version")
 
+    with self.argument_context('cognitiveservices agent create') as c:
+        c.argument(
+            'agent_name',
+            options_list=['--name', '-n'],
+            help='Name of the agent to create',
+            required=True
+        )
+        c.argument(
+            'image',
+            help=(
+                'Container image URI including tag '
+                '(e.g., myregistry.azurecr.io/myagent:v1 or myagent:v1 if using --registry). '
+                'The image tag becomes the agent version. Mutually exclusive with --source.'
+            )
+        )
+        c.argument(
+            'source',
+            help=(
+                'Path to source directory containing Dockerfile. '
+                'When provided, the image will be built and pushed automatically. '
+                'Mutually exclusive with --image.'
+            )
+        )
+        c.argument(
+            'dockerfile',
+            help=(
+                'Name of the Dockerfile in the source directory. '
+                'Default: "Dockerfile". Only used with --source.'
+            )
+        )
+        c.argument(
+            'build_remote',
+            options_list=['--build-remote'],
+            action='store_true',
+            help=(
+                'Force remote build using Azure Container Registry Task. '
+                'By default, builds locally if Docker is available, '
+                'otherwise builds remotely. Only used with --source.'
+            )
+        )
+        c.argument(
+            'registry',
+            help=(
+                'Azure Container Registry name (e.g., myregistry). '
+                'If provided, the full ACR URI will be constructed. '
+                'Required when using --source.'
+            )
+        )
+        c.argument(
+            'cpu',
+            help='CPU cores allocation (e.g., "1", "2", "0.5"). Default: "1"',
+            default='1'
+        )
+        c.argument(
+            'memory',
+            help='Memory allocation with units (e.g., "2Gi", "4Gi", "512Mi"). Default: "2Gi"',
+            default='2Gi'
+        )
+        c.argument(
+            'environment_variables',
+            options_list=['--environment-variables', '--env'],
+            nargs='+',
+            type=_environment_variables_type,
+            help="Space-separated environment variables in 'key=value' format (e.g., FOO=bar LOG_LEVEL=debug)"
+        )
+        c.argument(
+            'protocol',
+            help='Agent communication protocol. Default: "responses"',
+            arg_type=get_enum_type(['responses', 'streaming']),
+            default='responses'
+        )
+        c.argument(
+            'protocol_version',
+            help='Protocol version. Default: "v1"',
+            default='v1'
+        )
+        c.argument(
+            'description',
+            help='Human-readable description of the agent'
+        )
+        c.argument(
+            'min_replicas',
+            type=int,
+            help='Minimum number of replicas for horizontal scaling. Default: 0'
+        )
+        c.argument(
+            'max_replicas',
+            type=int,
+            help='Maximum number of replicas for horizontal scaling. Default: 3'
+        )
+        c.argument(
+            'skip_acr_check',
+            action='store_true',
+            help=(
+                'Skip validation that project managed identity has access to '
+                'container registry. Use when access is configured via user-assigned '
+                'identity, service principal, network-level permissions, or other methods '
+                'the check cannot detect.'
+            )
+        )
+        c.argument(
+            'no_wait',
+            action='store_true',
+            help='Do not wait for the long-running operation to finish'
+        )
+        c.argument(
+            'no_start',
+            action='store_true',
+            help=(
+                'Skip automatic deployment after agent version creation. '
+                'Use this to create the agent version without starting the deployment. '
+                'Cannot be used with --min-replicas or --max-replicas.'
+            )
+        )
+        c.argument(
+            'timeout',
+            type=int,
+            help=(
+                'Maximum time in seconds to wait for deployment to be ready. '
+                'Default: 600 seconds (10 minutes). '
+                'Increase for large container images or slow network conditions.'
+            ),
+            default=600
+        )
+
     with self.argument_context("cognitiveservices agent update") as c:
         c.argument(
             "min_replicas",

src/azure-cli/azure/cli/command_modules/cognitiveservices/commands.py

@@ -120,6 +120,7 @@ def load_command_table(self, _):
         g.command('list', 'list')
 
     with self.command_group('cognitiveservices agent', client_factory=cf_ai_projects, is_preview=True) as g:
+        g.custom_command('create', 'agent_create')
         g.custom_command('update', 'agent_update')
         g.custom_command('stop', 'agent_stop')
         g.custom_command('start', 'agent_start')