Agent 365 CLIは、Azure上でAgent 365アプリケーションを展開・管理するためのクロスプラットフォームのコマンドラインツールです。 この参考文献では、CLIのインストール、更新、アンインストール、そして自動化やトラブルシューティングのための使い方を説明しています。
CLIを手動でインストールする必要はありません。Agent 365 Skillsは CLIの確認、自動インストールまたは更新、必要なコマンドをすべてあなたの代わりに実行します。 この記事は、CLIを直接インストールまたは使用する必要がある開発者のための参考資料です。例えば、CI/CDの自動化を構築する際、特定のステップのトラブルシューティング時、AIコーディングエージェントなしで作業する場合などです。
Note
AI ガイド付きセットアップ、ロール ガイダンス、デプロイ後の手順など、完全な開発者ワークフローについては、「 エージェント 365 開発の概要」を参照してください。 この記事はCLIの参考文献です:インストール、更新、アンインストール、利用可能なコマンド、トラブルシューティング。
一括オンボーディングの代替手段
複数のエージェントを同時にオンボーディングする必要がある場合は、各エージェントごとに a365 CLIオンボーディングワークフローを実行する代わりに、Agent 365の一括オンボーディングPowerShellスクリプトを活用してください。 これらのスクリプトは、CSV ファイルからプロビジョニング ブループリント、エージェント ID、エージェントユーザー、エージェントの登録情報を読み込みます。 CLIとは別で、CLIコマンドではありません。
完全なワークフローについては、 Bulk Agent 365のオンボーディングをご覧ください。 そのガイドは、前提条件、自動化アプリケーションのセットアップ、対応するCSVフィールドと検証ルール、実行、結果、トラブルシューティングをカバーしています。
Prerequisites
CLI には、.NET 8.0 以降が必要です。 Azureサブスクリプションや必要なEntraロールを含むその他の前提条件については、「Quickstart: Agent 365への既存エージェントを接続する」をご覧ください。
Microsoft Entra 認証
デフォルトでは、Agent 365のセットアップはテナント上で利用可能なMicrosoft管理のAgent 365 CLIエンタープライズアプリケーションを使用します。
| プロパティ | Value |
|---|---|
| 表示名 | Agent 365 CLI |
| アプリケーション (クライアント) ID | f54280f4-395e-4ea8-9e48-bf2d4952aa14 |
アプリケーションを検証するには、Microsoft Entra 管理センターにアクセスし、エンタープライズアプリケーション>すべてのアプリケーションを選択し、アプリケーションIDを検索してください。 サービスプリンシパルの オブジェクトID はあなたのテナントに固有のものです。 CLIやドキュメントでアプリケーション(クライアント)IDを求める場合にObject IDは使わないでください。
CLIはテナント内のエンタープライズアプリケーションのサービスプリンシパルをチェックし、アクセストークン内の必要な委任スコープを検証します。 Microsoftのアプリケーション登録を作成・修正するものではありません。 Microsoft管理アプリケーションは、サインインしたユーザーを昇格させたり、条件付きアクセスやセキュリティデフォルトを回避したり、エージェントリソースの同意要件を別々に解除したりしません。
Microsoft管理のエンタープライズアプリケーションが利用できない場合、設定不要のセットアップはAgent 365 CLIというテナント所有のアプリを探します。 カスタム clientAppId を指定する既存の構成は引き続きサポートされています。 手順については、 エージェント365 CLIのカスタムクライアントアプリ登録をご覧ください。
Microsoft管理アプリケーションは以下のインタラクティブ認証方法を使用しています:
| Environment | 認証方法 |
|---|---|
| ネイティブWindows | Web アカウント マネージャー (WAM) |
| Linux 用 Windows サブシステム(WSL)、macOS、Linux | デバイス コード |
テナント所有のカスタムアプリケーションは、WAMが利用できない場合はシステムブラウザを使用します。
Agent 365 CLI をインストールする
次の手順に従って、Agent 365 CLI をオペレーティング システムにグローバルにインストールします。
Prerequisites
.NETがインストールされている必要があります。 (.NET 8.0 をお勧めします)。
「dotnet tool install」コマンドを使用する
次のコマンドを使用して、Agent 365 CLI をインストールします。
dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli
最新の手順と利用可能なバージョンについては、公式の NuGet ページを参照してください: NuGet.org 上の Microsoft.Agents.A365.DevTools.Cli
インストールを検証する
Agent 365 CLIをインストールした後、 --help コマンドを実行して正しくインストールされているか確認してください:
a365 -h
このコマンドはヘルプ情報を表示し、CLI が使用できる状態であることを確認します。
Agent 365のCLIを更新してください
dotnet tool update コマンドを使用して、Agent 365 CLI を更新します:
dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli
Note
エージェント365 CLIを更新するには、最新のNuGetパッケージにアクセスするためにインターネット接続が必要です: Microsoft.Agents.A365.DevTools.Cli。
エージェント365のCLIをアンインストールしてください
dotnet tool uninstall コマンドを使用して、Agent 365 CLI をアンインストールします:
dotnet tool uninstall --global Microsoft.Agents.A365.DevTools.Cli
エージェント365のCLIファイル場所
ツールの実行可能ファイルの既定の場所は、オペレーティング システムによって異なります。
| OS | 経路 |
|---|---|
| Linux または macOS | $HOME/.dotnet/tools |
| Windows | %USERPROFILE%\.dotnet\tools |
SDKは最初に実行したときにこの場所をパスに追加します。 ツールの場所を指定しなくても、どのディレクトリからでもグローバルツールを呼び出すことができます。
ツールへのアクセスは、マシン全体ではなくユーザー固有です。 グローバルツールは、ツールをインストールしたユーザーのみが利用可能です。
米国政府向けクラウド
デフォルトでは、Agent 365 CLIはMicrosoftの商用クラウドをターゲットにしています。
https://login.microsoftonline.comで認証し、https://graph.microsoft.comでMicrosoft Graphを呼び出し、https://agent365.svc.cloud.microsoftでAgent 365サービスを呼び出します。 Microsoft 365米国政府のクラウドでCLIを実行するには、環境をgcc、gcc-high、またはdodに設定し、そのクラウドのエンドポイントを設定してください。
環境名はクラウド固有の設定を選択しますが、それ自体でエンドポイントは変更されません。 GCCでは、Agent 365 Toolsのディスカバリーエンドポイントを設定します。 GCC HighやDoDでは、権限ホストとMicrosoft Graphの基本URLも設定してください。
環境、権威ホスト、グラフ ベース URL を a365.config.json (environment、authorityHost、graphBaseUrl) に設定するか、以下の表に記載されている環境変数を使用してください。 環境スコープ変数は、正規化されたクラウド名の接尾辞（GCC）で終わります。たとえば、GCC_HIGH や <ENV> などです。また、一致する a365.config.json フィールドよりも優先されます。
| Variable | Description |
|---|---|
A365_ENVIRONMENT |
クラウド環境の名前。 CLIは a365.config.json が environmentを設定しない場合や、 a365.config.jsonを読み取らないコマンドに対してこの値を使います。 既定値は prod です。 |
A365_AUTHORITY_HOST_<ENV> |
OAuth 認証ホスト。 この値はauthorityHostではa365.config.jsonよりも優先されます。 |
A365_GRAPH_BASE_URL_<ENV> |
Microsoft Graphの基本URLです。 この値はgraphBaseUrlではa365.config.jsonよりも優先されます。 |
A365_DISCOVER_ENDPOINT_<ENV> |
Agent 365 Toolsのディスカバリーエンドポイント。 CLIはまた、関連するAgent 365サービスコールにもそのオリジンを利用します。 |
A365_CREATE_ENDPOINT_<ENV> |
メッセージングエンドポイントの登録URLです。 |
A365_DELETE_ENDPOINT_<ENV> |
メッセージングエンドポイントの削除URL。 |
A365_MCP_APP_ID_<ENV> |
CLIがツールサーバー用のトークンを取得するために使用するエージェント365 ToolsリソースアプリケーションID。 ほとんどの開発者はこの変数を設定する必要はありません。 |
クラウド エンドポイントの値、サフィックス <ENV> の正規化ルール、完全な例については、米国政府向けクラウド向けの Agent 365 CLI の構成を参照してください。
エージェント365のCLIコマンド
利用可能なコマンドの完全なリストについては、 --help コマンドを使用するか、 Agent 365 CLI Referenceをご覧ください。
Tip
CLI コマンドを手動で実行する必要はありません。 Agent 365 Skills は、AIコーディングエージェントを用いてCLIのインストール、設定、ブループリントの設定、展開、公開など、全ワークフローを自動化します。 CI/CD オートメーションの構築、特定の手順のトラブルシューティング、または AI コーディング エージェントなしで作業する場合は、ここでの CLI リファレンスを使用してください。
CLI を使用してエージェント 365 エージェントを設定する方法の詳細な手順については、「 エージェント 365 の開発を開始する」を参照してください。
Troubleshooting
このセクションでは、エージェント365 CLIでのエラーのトラブルシューティング方法についての情報を提供します。
Tip
Agent 365トラブルシューティングガイドには、Agent 365 の開発ライフサイクルの各段階に対応した高レベルのトラブルシューティング推奨事項、ベストプラクティス、トラブルシューティングコンテンツへのリンクが含まれています。
このセクションで扱うCLI特有の問題:
- Microsoft管理のAgent 365 CLIアプリケーションは利用できません
- デバイスコード認証がブロックされています
- 認証が失敗するAADSTS70007
- 必要な委任範囲が欠落しています
- エージェントはTeamsに表示されません
- Teamsでエージェントインスタンスを作成できません
Microsoft管理のAgent 365 CLIアプリケーションは利用できません
CLIを更新して再度実行 a365 setup requirements 。 段階的な展開がテナントに届いたかどうかを確認するには、Microsoft EntraのエンタープライズアプリケーションでアプリケーションIDf54280f4-395e-4ea8-9e48-bf2d4952aa14を検索してください。
サービスプリンシパルが不在の場合、セットアップは Agent 365 CLIというテナント所有のアプリにフォールバックします。 もしまだそのアプリを持っていなければ、 Agent 365 CLIのカスタムクライアントアプリ登録に従ってください。
デバイスコード認証がブロックされています
Microsoft管理のアプリケーションは、WSL、macOS、Linuxでデバイスコード認証を使用しています。 セキュリティデフォルトや条件付きアクセスポリシーはこのフローをブロックし、返 AADSTS530035返すことができます。
このエラーを回避するために、組織のセキュリティポリシーを無効にしないでください。 ネイティブWindowsでCLIを実行してWAMを使うか、アイデンティティ管理者と連携してテナント所有のカスタムアプリケーションとポリシーで許可された認証フローを使うのが良いでしょう。
AADSTS70007 で認証が失敗する
古いCLIバージョンでは、Microsoft管理アプリケーションでサポートされていないブラウザ応答モードを使い、AADSTS70007を返すこともあります。 最新のCLIバージョンにアップデートして再試行してください:
dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli
必要な委任範囲が欠落しています
CLIは、アクセストークンのscp請求から、Microsoft管理アプリケーションの実効的な委任権限を検証します。 CLIを更新して再実行 a365 setup requirements。
Microsoft管理アプリケーションにリダイレクトURI、任意のクレーム、API権限、テナントローカル権限付与を追加しないでください。 もし検証でスコープの欠如が報告されれば、エラーのトレースIDと相関IDを取得してMicrosoftサポートに連絡してください。 テナント所有のアプリを使用している場合は、 Agent 365 CLIのカスタムクライアントアプリ登録の検証手順に従ってください。
エージェントはTeamsに表示されません
エージェントインスタンスの作成トラブルシューティング:エージェントがTeamsに表示されません