azd toolの–host廃止に対応する方法｜–agent移行とJSON変更を解説

Azure Developer CLI（azd）の更新後に、azd tool installなどで「unknown flag: --host」と表示される場合は、--hostを--agentへ変更してください。

ただし、修正が必要なのはコマンドだけではありません。azd tool list --output jsonとazd tool check --output jsonでは、インストール済みのskillがエージェントごとに別の行へ展開され、agentフィールドも追加されました。そのため、JSONの行数、集計方法、重複判定に依存するスクリプトも見直す必要があります。(Microsoft for Developers)

2026年7月30日に公開された公式ロールアップはAzure Developer CLI 1.27.0～1.29.0を対象としていますが、今回の破壊的変更が入ったのはバージョン1.28.0です。1.27.xではまだ--hostが使われていたため、開発端末とCI/CD環境でazdのバージョンが異なる場合は特に注意してください。(GitHub)

azd toolで何が変わったのか

今回の変更点を整理すると、次のとおりです。

対象	1.27.xまで	1.28.0以降	必要な対応
`azd tool install`	`--host`	`--agent`	コマンドやスクリプトを置換
`azd tool upgrade`	`--host`	`--agent`	コマンドやスクリプトを置換
`azd tool uninstall`	`--host`	`--agent`	コマンドやスクリプトを置換
`tool list`のJSON	skill単位で扱う前提になりやすい	エージェントごとに1行	行数や一意キーの見直し
`tool check`のJSON	tool単位で扱う前提になりやすい	エージェントごとに1行	更新判定をエージェント単位に変更
JSONの識別キー	`id`だけで管理できる場合がある	同じ`id`が複数行に現れる	`id`と`agent`の複合キーを使用

この変更は、GitHub CopilotやClaudeなど、skillを利用する対象を「host」ではなく「agent」という用語で統一するために行われました。PR #9045では、フラグ名の変更に加えて、一覧表示と更新確認の出力もエージェント単位へ整理されています。(GitHub)

`unknown flag: --host`を解消する方法

install、upgrade、uninstallのフラグを置き換える

従来のコマンドが次のようになっている場合は、--hostを--agentへ変更します。

変更前は次のとおりです。

azd tool install azure-skills --host copilot
azd tool upgrade azure-skills --host copilot
azd tool uninstall azure-skills --host copilot

変更後は次のようになります。

azd tool install azure-skills --agent copilot
azd tool upgrade azure-skills --agent copilot
azd tool uninstall azure-skills --agent copilot

複数のエージェントを指定する場合は、--agentを繰り返して指定できます。

azd tool install azure-skills \
  --agent copilot \
  --agent claude

検出されたすべてのエージェントを対象にする場合は、allを指定します。

azd tool install azure-skills --agent all
azd tool upgrade azure-skills --agent all

--agentはskillに対して使用するオプションです。また、--agent allと個別のエージェント名を同時に指定することはできません。利用できるエージェント名は今後増える可能性があるため、実際の環境では--helpの表示を確認してください。(GitHub)

`host`という文字列を一括置換しない

リポジトリ全体で「host」を「agent」へ機械的に一括置換するのは避けてください。

今回変更されたのは、主に次のコマンドでskillの対象を指定するフラグです。

azd tool install
azd tool upgrade
azd tool uninstall

一方、azure.yamlなどには、デプロイ先の種類を表す別のhost設定が存在する場合があります。

services:
  web:
    project: ./src
    host: appservice

このhost: appserviceは今回の--hostフラグとは無関係です。誤ってagent: appserviceへ変更すると、別の設定エラーを引き起こします。

置換対象は、次のようにコマンドまで含めて絞り込むのが安全です。

git grep -n -E -- \
  'azd tool (install|upgrade|uninstall).*--host|azd tool (list|check).*--output[ =]json'

PowerShellでは、次のように検索できます。

Get-ChildItem -Recurse -File |
    Select-String -Pattern `
        'azd tool (install|upgrade|uninstall).*--host',
        'azd tool (list|check).*--output(=|\s+)json'

最初のパターンは廃止されたフラグを探し、2つ目のパターンはJSON出力を利用している処理を探します。

uninstallでは対象エージェントを明示する

azd tool uninstallでは、--agentを省略すると、そのskillがインストールされているすべてのエージェントから削除されます。

特定のエージェントだけから削除したい場合は、必ず対象を指定してください。

azd tool uninstall azure-skills --agent copilot

次のコマンドは、Copilotだけでなく、インストール済みのほかのエージェントにも影響する可能性があります。

azd tool uninstall azure-skills

「Copilotからだけ削除するつもりだったのに、Claude側からも削除された」という事故を避けるには、アンインストール処理で--agentを省略しない運用が安全です。(GitHub)

使用中のazdバージョンを確認する

最初に、ローカル環境とCI/CD環境の両方でazdのバージョンを確認します。

azd version

続けて、各コマンドのヘルプを確認します。

azd tool install --help
azd tool upgrade --help
azd tool uninstall --help

判断の目安は次のとおりです。

確認結果	環境の状態	対応
ヘルプに`--host`がある	1.27.x以前の可能性が高い	旧形式の環境
ヘルプに`--agent`がある	1.28.0以降	新形式へ移行
ローカルとCIで結果が違う	azdのバージョンが不統一	バージョンを統一する
どちらも表示されない	対象コマンドやtool種別が異なる可能性	tool IDとコマンドを再確認

バージョン番号を文字列として比較するより、実際のヘルプに--agentが存在するかを確認したほうが、移行期間中の互換処理を作りやすくなります。

`azd tool list`のJSON行数が増える理由

skillがエージェントごとに展開される

変更前は、利用側のスクリプトが1つのskillを1行として扱っていた可能性があります。

主要なフィールドだけに簡略化すると、従来は次のようなデータを想定しやすい構造でした。

[
  {
    "id": "azure-skills",
    "name": "Azure Skills",
    "status": "Installed",
    "version": "1.0.0"
  }
]

1.28.0以降は、同じskillが複数のエージェントにインストールされている場合、エージェントごとに行が分かれます。

[
  {
    "id": "azure-skills",
    "name": "Azure Skills",
    "agent": "copilot",
    "status": "Installed",
    "version": "1.0.0"
  },
  {
    "id": "azure-skills",
    "name": "Azure Skills",
    "agent": "claude",
    "status": "Installed",
    "version": "1.0.0"
  }
]

この例では、toolの種類は1つでもJSONの行数は2行です。

公式実装では、skillのインストール先ごとに行を作成し、それぞれにagent、status、versionを設定します。一方、通常のtoolではagentフィールドが省略される場合があります。(GitHub)

`id`だけでは一意にならない

従来、次のような処理でidをキーにしていた場合は注意が必要です。

azd tool list --output json |
  jq 'map({(.id): .}) | add'

同じidの行が複数あると、後から処理された行で前の行が上書きされます。その結果、CopilotとClaudeの両方にインストールされていても、片方しか残らない可能性があります。

移行後は、idとagentを組み合わせて一意のキーを作ります。

azd tool list --output json |
  jq '
    map({
      key: (.id + "::" + (.agent // "_")),
      value: .
    })
    | from_entries
  '

生成されるキーは、次のようになります。

azure-skills::copilot
azure-skills::claude

agentがない通常のtoolには_を補い、欠落したフィールドでもエラーにならないようにしています。

JSONの件数集計を修正する

配列の長さはtool数ではなく行数になる

次の処理はJSONの行数を返します。

azd tool list --output json | jq 'length'

skillが2つのエージェントへ展開されれば、同じtool IDでも2件として数えられます。そのため、これを「インストール済みtool数」として監視している場合、更新直後に件数が増える可能性があります。

tool IDの種類数を数えたい場合は、重複を除外します。

azd tool list --output json |
  jq '[.[].id] | unique | length'

エージェントごとのskillインストール数を数える場合は、agentフィールドを持つ行だけを集計します。

azd tool list --output json |
  jq '[.[] | select(has("agent"))] | length'

同じtool IDが複数行に展開されているものを確認するには、次のコマンドが便利です。

azd tool list --output json |
  jq -r '
    group_by(.id)[]
    | select(length > 1)
    | "\(.[0].id)\t\([.[] | (.agent // "-")] | join(","))"
  '

出力例は次のようになります。

azure-skills    copilot,claude

`azd tool check`の更新判定もエージェント単位にする

azd tool check --output jsonでも、skillはエージェントごとに行へ展開されます。

主なフィールドには、次の情報が含まれます。

id
name
agent
installedVersion
latestVersion
updateAvailable

同じskillでも、エージェントごとにインストール済みバージョンが異なる可能性があります。そのため、idだけを見て更新の有無を判断するのではなく、agentも含めて処理します。(GitHub)

更新が必要な行だけを抽出する例は次のとおりです。

azd tool check --output json |
  jq '
    .[]
    | select(.updateAvailable == true)
    | {
        id,
        agent: (.agent // "non-skill"),
        installedVersion,
        latestVersion
      }
  '

通知メッセージも、tool名だけではなくエージェント名を含めると状況が分かりやすくなります。

azure-skills / copilot: 1.0.0 → 1.1.0
azure-skills / claude: 1.0.1 → 1.1.0

PowerShellでJSONを安全に正規化する

Windows環境やAzure PipelinesでPowerShellを利用している場合は、agentフィールドが存在しない行も処理できるようにします。

$rows = azd tool list --output json | ConvertFrom-Json

$normalized = $rows | ForEach-Object {
    $agent = if ($_.PSObject.Properties.Name -contains 'agent') {
        $_.agent
    }
    else {
        '_'
    }

    [pscustomobject]@{
        Key      = "$($_.id)::$agent"
        Id       = $_.id
        Agent    = $agent
        Status   = $_.status
        Version  = $_.version
    }
}

$normalized

tool IDの種類数だけを取得する場合は、次のように重複を除外します。

$distinctToolCount = (
    $rows |
        Select-Object -ExpandProperty id -Unique
).Count

Write-Host "Distinct tools: $distinctToolCount"

$_.agentが必ず存在すると仮定すると、通常のtoolを処理したときに空値やプロパティ欠落を原因とする問題が起きます。JSONスキーマとしてはagentを任意項目として扱うのが安全です。

ローカルとCIでazdのバージョンが異なる場合の対応

基本は1.28.0以降へ統一する

最も安全なのは、開発端末、ビルド用コンテナ、セルフホステッドランナー、CI/CDサービスで使用するazdを同じバージョン帯へ統一し、スクリプトを--agentへ移行する方法です。

特に、次の環境を確認してください。

開発者のローカルPC
Dev Container
Dockerfile
GitHub Actions
Azure Pipelines
セルフホステッドランナー
定期実行用の管理サーバー
社内配布しているセットアップスクリプト

CIの冒頭でバージョンを出力しておくと、障害発生時に原因を特定しやすくなります。

azd version
azd tool install --help

移行期間だけ新旧フラグを判定する

すべての環境を同時に更新できない場合は、--agentの有無を判定する互換処理を一時的に利用できます。

Bashの例は次のとおりです。

if azd tool install --help 2>&1 | grep -q -- '--agent'; then
  target_flag='--agent'
else
  target_flag='--host'
fi

azd tool install azure-skills \
  "$target_flag" copilot \
  --no-prompt

PowerShellでは次のように書けます。

$helpText = azd tool install --help | Out-String

$targetFlag = if ($helpText -match '--agent') {
    '--agent'
}
else {
    '--host'
}

azd tool install azure-skills `
    $targetFlag copilot `
    --no-prompt

この互換処理は、移行期間中の一時対応としては有効です。ただし、長期間残すとテスト対象が増えます。全環境を1.28.0以降へ統一できた段階で、--host側の分岐は削除してください。

よくある移行失敗と対処方法

症状	主な原因	対処
`unknown flag: --host`になる	1.28.0以降で旧フラグを使用	`--agent`へ変更
ローカルでは成功しCIで失敗する	azdのバージョンが異なる	両環境で`azd version`を確認
JSONの件数が突然増えた	skillがエージェントごとに展開	`length`をtool数として使わない
同じtoolの情報が1件しか残らない	`id`をキーにして上書き	`id + agent`を複合キーにする
`agent`の参照でエラーになる	通常のtoolには項目がない場合がある	欠落時の既定値を用意
1つだけ削除するつもりがすべて削除された	uninstallで`--agent`を省略	対象エージェントを明示
`--agent all`がエラーになる	個別名と`all`を同時指定	`all`または個別指定のどちらかに統一
Azureのデプロイ設定が壊れた	`azure.yaml`の`host`まで置換	azd toolのフラグだけを修正

移行時に確認するチェックリスト

ローカルとCIでazd versionを実行する
azd tool install --helpで--agentの有無を確認する
install、upgrade、uninstallの--hostを--agentへ置換する
azure.yamlなど、無関係なhost設定を変更していないか確認する
tool listとtool checkのJSON利用箇所を検索する
idだけを一意キーにしている処理を修正する
lengthをtool数として扱っている集計を修正する
agentが存在しないJSON行も処理できるようにする
1つのskillを複数エージェントへインストールした状態でテストする
uninstallが意図したエージェントだけに作用するか確認する

コマンドとJSON処理をセットで移行する

azdの--hostから--agentへの変更では、コマンドの置換だけで対応を終えないことが重要です。

まず、1.28.0以降の環境では、次の3コマンドを--agentへ変更します。

azd tool install
azd tool upgrade
azd tool uninstall

続けて、azd tool list --output jsonとazd tool check --output jsonを利用する処理を確認し、次の点を修正します。

同じidが複数行に現れる前提にする
一意キーにはidとagentを使う
配列の行数とtoolの種類数を分けて集計する
agentがない通常のtoolも扱えるようにする
更新判定や通知をエージェント単位で行う

最後に、ローカル環境だけでなくCI/CD上でも、単一エージェントと複数エージェントの両方をテストしてください。これにより、フラグ変更によるコマンドエラーだけでなく、JSONの上書きや誤集計もまとめて防止できます。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

azd toolの–host廃止に対応する方法｜–agent移行とJSON変更を解説

azd toolで何が変わったのか

`unknown flag: --host`を解消する方法

install、upgrade、uninstallのフラグを置き換える

`host`という文字列を一括置換しない

uninstallでは対象エージェントを明示する

使用中のazdバージョンを確認する

`azd tool list`のJSON行数が増える理由

skillがエージェントごとに展開される

`id`だけでは一意にならない

JSONの件数集計を修正する

配列の長さはtool数ではなく行数になる

`azd tool check`の更新判定もエージェント単位にする

PowerShellでJSONを安全に正規化する

ローカルとCIでazdのバージョンが異なる場合の対応

基本は1.28.0以降へ統一する

移行期間だけ新旧フラグを判定する

よくある移行失敗と対処方法

移行時に確認するチェックリスト

コマンドとJSON処理をセットで移行する

この記事を書いた人

コメント

コメントするコメントをキャンセル

azd toolの–host廃止に対応する方法｜–agent移行とJSON変更を解説

azd toolで何が変わったのか

unknown flag: --hostを解消する方法

install、upgrade、uninstallのフラグを置き換える

hostという文字列を一括置換しない

uninstallでは対象エージェントを明示する

使用中のazdバージョンを確認する

azd tool listのJSON行数が増える理由

skillがエージェントごとに展開される

idだけでは一意にならない

JSONの件数集計を修正する

配列の長さはtool数ではなく行数になる

azd tool checkの更新判定もエージェント単位にする

PowerShellでJSONを安全に正規化する

ローカルとCIでazdのバージョンが異なる場合の対応

基本は1.28.0以降へ統一する

移行期間だけ新旧フラグを判定する

よくある移行失敗と対処方法

移行時に確認するチェックリスト

コマンドとJSON処理をセットで移行する

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

`unknown flag: --host`を解消する方法

`host`という文字列を一括置換しない

`azd tool list`のJSON行数が増える理由

`id`だけでは一意にならない

`azd tool check`の更新判定もエージェント単位にする

コメントするコメントをキャンセル