Skip to content

Conversation

@eamonoreilly
Copy link

Related command
az cognitiveservices

Description
This adds the ability to create and deploy hosted agents in AI Foundry. It enables customers to upload and build their local agent code to Azure Container Registry or point to an existing container image on ACR to use as part of the hosted agent creation. It can be used in conjunction with existing az cognitive services agent * commands to manage a hosted agent within AI Foundry.

Testing Guide

Create agent from existing container image
    az cognitiveservices agent create \
      --account-name myAccount \
      --project-name myProject \
      --name my-agent \
      --image myregistry.azurecr.io/my-agent:v1.0


Create agent by building from source (auto-detect build method)
    az cognitiveservices agent create \
      --account-name myAccount \
      --project-name myProject \
      --name my-agent \
      --source ./my-agent-code \
      --registry myregistry


Create agent by building from source with custom Dockerfile name
    az cognitiveservices agent create \
      --account-name myAccount \
      --project-name myProject \
      --name my-agent \
      --source ./my-agent-code \
      --dockerfile Dockerfile.prod \
      --registry myregistry


Create agent by building remotely with ACR Task
    az cognitiveservices agent create \
      --account-name myAccount \
      --project-name myProject \
      --name my-agent \
      --source ./my-agent-code \
      --registry myregistry \
      --build-remote


Create agent with custom CPU and memory
    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


Create agent with scaling configuration
    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


Create agent with environment variables
    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


Create agent with streaming protocol
    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


Create agent using short registry name
    az cognitiveservices agent create \
      --account-name myAccount \
      --project-name myProject \
      --name my-agent \
      --image my-agent:v1.0 \
      --registry myregistry


Create agent with extended timeout for large images
    az cognitiveservices agent create \
      --account-name myAccount \
      --project-name myProject \
      --name my-agent \
      --image myregistry.azurecr.io/my-large-agent:v1.0 \
      --timeout 1200

History Notes
[cognitiveservices] az cognitiveservices agent create: Adds ability to create and deploy hosted agent in AI Foundry


This checklist is used to make sure that common guidelines for a pull request are followed.

Copilot AI review requested due to automatic review settings November 17, 2025 14:53
@azure-client-tools-bot-prd
Copy link

azure-client-tools-bot-prd bot commented Nov 17, 2025

️✔️AzureCLI-FullTest
️✔️acr
️✔️latest
️✔️3.12
️✔️3.13
️✔️acs
️✔️latest
️✔️3.12
️✔️3.13
️✔️advisor
️✔️latest
️✔️3.12
️✔️3.13
️✔️ams
️✔️latest
️✔️3.12
️✔️3.13
️✔️apim
️✔️latest
️✔️3.12
️✔️3.13
️✔️appconfig
️✔️latest
️✔️3.12
️✔️3.13
️✔️appservice
️✔️latest
️✔️3.12
️✔️3.13
️✔️aro
️✔️latest
️✔️3.12
️✔️3.13
️✔️backup
️✔️latest
️✔️3.12
️✔️3.13
️✔️batch
️✔️latest
️✔️3.12
️✔️3.13
️✔️batchai
️✔️latest
️✔️3.12
️✔️3.13
️✔️billing
️✔️latest
️✔️3.12
️✔️3.13
️✔️botservice
️✔️latest
️✔️3.12
️✔️3.13
️✔️cdn
️✔️latest
️✔️3.12
️✔️3.13
️✔️cloud
️✔️latest
️✔️3.12
️✔️3.13
️✔️cognitiveservices
️✔️latest
️✔️3.12
️✔️3.13
️✔️compute_recommender
️✔️latest
️✔️3.12
️✔️3.13
️✔️computefleet
️✔️latest
️✔️3.12
️✔️3.13
️✔️config
️✔️latest
️✔️3.12
️✔️3.13
️✔️configure
️✔️latest
️✔️3.12
️✔️3.13
️✔️consumption
️✔️latest
️✔️3.12
️✔️3.13
️✔️container
️✔️latest
️✔️3.12
️✔️3.13
️✔️containerapp
️✔️latest
️✔️3.12
️✔️3.13
️✔️core
️✔️latest
️✔️3.12
️✔️3.13
️✔️cosmosdb
️✔️latest
️✔️3.12
️✔️3.13
️✔️databoxedge
️✔️latest
️✔️3.12
️✔️3.13
️✔️dls
️✔️latest
️✔️3.12
️✔️3.13
️✔️dms
️✔️latest
️✔️3.12
️✔️3.13
️✔️eventgrid
️✔️latest
️✔️3.12
️✔️3.13
️✔️eventhubs
️✔️latest
️✔️3.12
️✔️3.13
️✔️feedback
️✔️latest
️✔️3.12
️✔️3.13
️✔️find
️✔️latest
️✔️3.12
️✔️3.13
️✔️hdinsight
️✔️latest
️✔️3.12
️✔️3.13
️✔️identity
️✔️latest
️✔️3.12
️✔️3.13
️✔️iot
️✔️latest
️✔️3.12
️✔️3.13
️✔️keyvault
️✔️latest
️✔️3.12
️✔️3.13
️✔️lab
️✔️latest
️✔️3.12
️✔️3.13
️✔️managedservices
️✔️latest
️✔️3.12
️✔️3.13
️✔️maps
️✔️latest
️✔️3.12
️✔️3.13
️✔️marketplaceordering
️✔️latest
️✔️3.12
️✔️3.13
️✔️monitor
️✔️latest
️✔️3.12
️✔️3.13
️✔️mysql
️✔️latest
️✔️3.12
️✔️3.13
️✔️netappfiles
️✔️latest
️✔️3.12
️✔️3.13
️✔️network
️✔️latest
️✔️3.12
️✔️3.13
️✔️policyinsights
️✔️latest
️✔️3.12
️✔️3.13
️✔️privatedns
️✔️latest
️✔️3.12
️✔️3.13
️✔️profile
️✔️latest
️✔️3.12
️✔️3.13
️✔️rdbms
️✔️latest
️✔️3.12
️✔️3.13
️✔️redis
️✔️latest
️✔️3.12
️✔️3.13
️✔️relay
️✔️latest
️✔️3.12
️✔️3.13
️✔️resource
️✔️latest
️✔️3.12
️✔️3.13
️✔️role
️✔️latest
️✔️3.12
️✔️3.13
️✔️search
️✔️latest
️✔️3.12
️✔️3.13
️✔️security
️✔️latest
️✔️3.12
️✔️3.13
️✔️servicebus
️✔️latest
️✔️3.12
️✔️3.13
️✔️serviceconnector
️✔️latest
️✔️3.12
️✔️3.13
️✔️servicefabric
️✔️latest
️✔️3.12
️✔️3.13
️✔️signalr
️✔️latest
️✔️3.12
️✔️3.13
️✔️sql
️✔️latest
️✔️3.12
️✔️3.13
️✔️sqlvm
️✔️latest
️✔️3.12
️✔️3.13
️✔️storage
️✔️latest
️✔️3.12
️✔️3.13
️✔️synapse
️✔️latest
️✔️3.12
️✔️3.13
️✔️telemetry
️✔️latest
️✔️3.12
️✔️3.13
️✔️util
️✔️latest
️✔️3.12
️✔️3.13
️✔️vm
️✔️latest
️✔️3.12
️✔️3.13

@azure-client-tools-bot-prd
Copy link

Hi @eamonoreilly,
Since the current milestone time is less than 7 days, this pr will be reviewed in the next milestone.

@azure-client-tools-bot-prd
Copy link

azure-client-tools-bot-prd bot commented Nov 17, 2025

⚠️AzureCLI-BreakingChangeTest
⚠️cognitiveservices
rule cmd_name rule_message suggest_message
⚠️ 1001 - CmdAdd cognitiveservices agent create cmd cognitiveservices agent create added
⚠️ 1010 - ParaPropUpdate cognitiveservices agent delete cmd cognitiveservices agent delete update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate cognitiveservices agent delete-deployment cmd cognitiveservices agent delete-deployment update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate cognitiveservices agent list cmd cognitiveservices agent list update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate cognitiveservices agent list-versions cmd cognitiveservices agent list-versions update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate cognitiveservices agent show cmd cognitiveservices agent show update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate cognitiveservices agent start cmd cognitiveservices agent start update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate cognitiveservices agent stop cmd cognitiveservices agent stop update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate cognitiveservices agent update cmd cognitiveservices agent update update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']

@yonzhan
Copy link
Collaborator

yonzhan commented Nov 17, 2025

Thank you for your contribution! We will review the pull request and get back to you soon.

@github-actions
Copy link

The git hooks are available for azure-cli and azure-cli-extensions repos. They could help you run required checks before creating the PR.

Please sync the latest code with latest dev branch (for azure-cli) or main branch (for azure-cli-extensions).
After that please run the following commands to enable git hooks:

pip install azdev --upgrade
azdev setup -c <your azure-cli repo path> -r <your azure-cli-extensions repo path>

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds the az cognitiveservices agent create command to enable creation and deployment of hosted agents in Azure AI Foundry. The implementation supports both using existing container images and building from source code, with automatic image building via local Docker or Azure Container Registry Tasks.

Key changes:

  • New agent_create command with comprehensive parameter validation and error handling
  • Image building support with local Docker fallback to ACR Task for remote builds
  • ACR access validation to ensure project managed identity has pull permissions
  • Deployment waiting mechanism with progress indicators and configurable timeouts

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 14 comments.

Show a summary per file
File Description
test_agent.py Comprehensive test suite with 9 unit tests for helper functions and 8 integration tests for agent lifecycle operations
custom.py Core implementation including parameter validation, image building/pushing, ACR access checks, and deployment orchestration
commands.py Command registration for agent create in the cognitiveservices command group
_params.py Parameter definitions including environment variable parsing and extensive argument help text
_help.py Detailed documentation with examples covering various usage scenarios
Comments suppressed due to low confidence (1)

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

  • Line 1539 has a missing f prefix for the f-string. It should be f\"Unable to verify ACR access: {str(e)}. \" to properly interpolate the exception message. Without the f prefix, the literal string {str(e)} will be displayed instead of the actual error message.
# --------------------------------------------------------------------------------------------

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- Fix suspicious patterns validation: remove ../ and ~/ (legitimate paths), only check shell expansion
- Improve Windows path handling with pathlib.Path().as_posix()
- Document sys.executable ACR login approach for dev/prod compatibility
- Move PACK_TASK_YAML constant to module level for maintainability
- Rename protocol_records to protocol_record (singular, more accurate)
- Add Limitations section to _check_project_acr_access docstring
- Fix test exception types: CLIError → InvalidArgumentValueError (7 assertions)
- Fix capitalization: 'AI Project name' → 'AI project name'

All tests passing: azdev style, azdev linter, unit tests (17/17)
@kairu-ms
Copy link
Contributor

/azp run

@azure-pipelines
Copy link

Azure Pipelines successfully started running 3 pipeline(s).

@eamonoreilly
Copy link
Author

@kairu-ms , do you know if there is anything else I need to do in order to get this merged into the CLI? Please let me know if I can do anything else to help. Thanks for the help in getting this merged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Auto-Assign Auto assign by bot Cognitive Services az cognitiveservices

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants