{Cognitive Services} Add agent status command (#32691)

Co-authored-by: GitHub Copilot <copilot@users.noreply.github.com>

Author: zzn2

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

@@ -697,6 +697,18 @@
     text: az cognitiveservices agent stop --account-name myAccount --project-name myProject --name myAgent --agent-version 1
 """
 
+helps[
+    "cognitiveservices agent status"
+] = """
+type: command
+short-summary: Get the status of a hosted agent deployment.
+long-summary: |
+    Calls the agent container status endpoint and returns the raw service payload.
+examples:
+  - name: Get hosted agent deployment status.
+    text: az cognitiveservices agent status --account-name myAccount --project-name myProject --name myAgent --agent-version 1
+"""
+
 helps[
     "cognitiveservices agent update"
 ] = """

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

@@ -387,6 +387,13 @@ def load_arguments(self, _):
         )
         c.argument("agent_version", help="Cognitive Services hosted agent version")
 
+    with self.argument_context("cognitiveservices agent status") as c:
+        c.argument(
+            "agent_version",
+            help="Cognitive Services hosted agent version",
+            required=True,
+        )
+
     with self.argument_context('cognitiveservices agent create') as c:
         c.argument(
             'agent_name',

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

@@ -124,6 +124,7 @@ def load_command_table(self, _):
         g.custom_command('update', 'agent_update')
         g.custom_command('stop', 'agent_stop')
         g.custom_command('start', 'agent_start')
+        g.custom_show_command('status', 'agent_status')
         g.custom_command('delete-deployment', 'agent_delete_deployment')
         g.custom_command('delete', 'agent_delete')
         g.custom_command('list', 'agent_list')

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

@@ -1672,6 +1672,17 @@ def agent_show(
     return response.json()
 
 
+def agent_status(
+    client,
+    account_name,
+    project_name,
+    agent_name,
+    agent_version,
+):  # pylint: disable=unused-argument
+    """Get the status of a hosted agent deployment (default container)."""
+    return _get_agent_container_status(client, agent_name, agent_version)
+
+
 def _get_resource_group_by_account_name(cmd, account_name):
     """
     Get resource group name for a Cognitive Services account by querying ARM.

src/azure-cli/azure/cli/command_modules/cognitiveservices/tests/latest/test_agent.py

@@ -39,6 +39,8 @@
 import os
 import tempfile
 import shutil
+from unittest import mock
+from urllib.parse import urlparse, parse_qs
 
 from azure.cli.testsdk import ScenarioTest, ResourceGroupPreparer
 from azure.cli.testsdk.decorators import serial_test
@@ -55,12 +57,42 @@
     _is_docker_running,
     _is_fully_qualified_image,
     _validate_path_for_subprocess,
+    _get_agent_container_status,
+    AGENT_API_VERSION_PARAMS,
 )
 from azure.cli.command_modules.cognitiveservices._params import _environment_variables_type
 
 
 class CognitiveServicesAgentHelperTests(unittest.TestCase):
     """Unit tests for agent helper functions."""
+
+    def test_get_agent_container_status_builds_expected_request(self):
+        """Test that agent status calls the default container endpoint and returns payload."""
+        expected_payload = {"status": "Running"}
+
+        client = mock.Mock()
+        response = mock.Mock()
+        response.json.return_value = expected_payload
+        client.send_request.return_value = response
+
+        result = _get_agent_container_status(client, "myAgent", "10")
+
+        self.assertEqual(result, expected_payload)
+        client.send_request.assert_called_once()
+        response.raise_for_status.assert_called_once()
+
+        request = client.send_request.call_args[0][0]
+        self.assertEqual(getattr(request, "method", None), "GET")
+
+        parsed = urlparse(getattr(request, "url", ""))
+        self.assertEqual(
+            parsed.path,
+            "/agents/myAgent/versions/10/containers/default",
+        )
+        self.assertEqual(
+            parse_qs(parsed.query).get("api-version"),
+            [AGENT_API_VERSION_PARAMS["api-version"]],
+        )
 
     def test_validate_image_tag_valid(self):
         """Test tag validation and extraction from valid image URIs."""