Azure Developer CLI を使用したエージェント開発

Important

この記事でプレビューとしてマークされているアイテムは、現在プレビュー段階です。 このプレビューはサービス レベル アグリーメント(SLA)なしで提供されており、Microsoft はこれを運用ワークロードでの使用に推奨していません。 特定の機能がサポートされていないか、機能が制限されている可能性があります。 詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

Azure Developer CLI (azd) とそのazd ai agent拡張機能を使用すると、アイデアから Microsoft Foundry 上の実稼働対応エージェントに移行するための単一のコマンドライン ワークフローが提供されます。 コード ベースのホステッド エージェントと宣言型プロンプト ベースの音声エージェントを開発できます。 この記事では、開発者体験、エージェントを定義するファイル、および途中で発生する主要な概念について説明します。

この記事は、Foundry ポータルまたは言語 SDK よりもターミナル優先のスクリプト可能なワークフローを好む開発者を対象としています。

開発者体験

azd ai ワークフローは、小規模なプロトタイプを構築する場合でも運用エージェントを構築する場合でも、同じライフサイクルに従います。 プロジェクトをスキャフォールディングしてから、プロジェクトの拡大に合わせてコマンドを組み合わせます。

段階 あなたの活動内容 詳細については、こちらをご覧ください
Install azdと Foundry 拡張機能をインストールします。 開発環境を設定する
スキャフォールディング テンプレートまたは既存のコードからホストされるエージェントを初期化するか、プロンプトベースの音声エージェントを作成します。 クイックスタート: ホストされたエージェントをデプロイする または クイックスタート: プロンプト音声エージェントを作成する
定義 azure.yamlでエージェント、モデルデプロイの依存関係、プロトコル、ツール、環境を構成します。 ホステッド エージェント用の azure.yaml を作成する
開発 エージェント ロジックを記述し、ツールボックスを使用してツールを追加し、ローカルでテストします。 ツールボックスの概要
展開 インフラストラクチャをプロビジョニングし、Foundry にデプロイします。 ホストされるエージェントをデプロイする
操作する ログの監視、バージョンの管理、実行の自動化。 ホストされているエージェントを管理する
Evaluate エージェントの品質を測定し、プロンプトを改善します。 azd CLI を使用してエージェント評価を実行する

エージェントの種類

azd ai agent拡張機能では、ホステッド エージェント、プロンプト エージェント、および音声エージェントがサポートされます。

タイプ Description いつ使用するか
ホスト型エージェント ソース コードまたはコンテナー イメージとしてデプロイされるアプリケーション。 カスタム ロジック、フレームワーク統合、または動作を完全に制御する必要があります。
プロンプトエージェント カスタム コードを使用せず、命令とツール構成によって完全に定義されたエージェント。 アプリケーション コードを記述せずに、構成に基づく迅速なエージェントが必要です。
音声エージェント 宣言型プロンプト音声エージェント、またはホストされるエージェントに接続する音声ラッパー。 Voice Live クライアントを介したリアルタイムの音声エクスペリエンスが必要です。

ホスト型エージェントを使用すると、ランタイム、フレームワーク、およびツールの統合を完全に制御でき、Foundry はインフラストラクチャ、スケーリング、セッション管理を処理します。

プロンプト ベースの音声エージェントでは、カスタム コンテナーは必要ありません。 独自のコンテナーでカスタム音声合成またはカスケード オーディオ パイプラインを実行する必要がある場合は、 ホストされたエージェントを使用して音声エージェント を構築し、 invocations_ws プロトコルを使用します。

Voice Live がオーディオを処理している間、ホストされたテキスト エージェントで会話ロジックを保持するには、 ホストされた音声ラッパー ワークフローを使用します。 ラッパーとターゲットは、同じ azure.yaml プロジェクト内の個別のサービスです。 このフローでは、既存のカスタム invocations_ws オーディオ パイプライン フローは置き換えられません。

パブリック プレビュー音声 CLI オプションを使用する前に、 音声エージェントのクイック スタートの前提条件の説明に従って、インストールされている拡張機能を確認してください。

構成ファイル

ホストされるエージェント プロジェクトでは、プロジェクト ルートにある 1 つの azure.yaml ファイルを使用して、エージェントとそのプロビジョニングとデプロイ モデルの両方を宣言します。 このファイルは分割サービス モデルを使用します。各名前付きサービスには、host、azure.ai.project、azure.ai.agent、azure.ai.connection、azure.ai.toolbox、azure.ai.skillなどのazure.ai.routine値があります。

File Purpose 誰が管理する
azure.yaml Foundry プロジェクト、モデルデプロイ、ホステッド エージェント サービス、依存関係、プロトコル、ツール、環境変数、コンテナー リソース、デプロイ設定を宣言します。 エージェント ID、モデル、プロトコル、ツール、環境の値は、 azure.ai.agent サービスに格納されます。 初期化によって生成されます。 必要に応じてカスタマイズします。

azure.ai.agent サービスでは、エージェントをインラインで定義するか、または直接的な YAML または JSON 定義への明示的なルート $ref を通じて定義します。 ファイルベースのサービスには azd ai agent add <service> --file <path> を使用します。 パラメーター化された AgentManifest ラッパーは、現在の初期化ではサポートされていません。 サービスの uses: リストは、プロジェクト、接続、ツールボックスなどの依存関係を参照します。

プロンプト ベースの音声エージェントの場合、 azure.yaml は宣言型エージェント定義 ( kind: prompt-voice、モデル、モデルの種類、エージェント名など) を格納します。 ホストエージェント コンテナー ランタイムは含まれません。 指示、音声、ターン検出、文字起こし、音声出力、ツール、案内応答をカスタマイズするには、「 音声エージェントの構成」を参照してください。

ホストされた音声ラッパーの場合、 conversationEngine.name はホスト対象のサービス名を参照します。 ラッパーの uses 依存関係によってデプロイ順序が決まり、conversationEngine.version の既定値は現在の環境にデプロイされているバージョンです。 構成フィールドについては、 音声サービスリファレンスを参照 してください。

変数の置換

${VAR_NAME}環境ごとに異なる値には、azure.yamlでazdを使用します。 プレースホルダーはデプロイ時または実行時に .azure/<env>/.env から解決されるため、開発、ステージング、運用環境などの環境で同じ azure.yaml が機能します。

CLI の実行場所

azd ai コマンドは、azd プロジェクト ディレクトリの内部と外部の両方で機能します。

  • azd プロジェクト内で、コマンドはアクティブなazd環境から Foundry プロジェクト エンドポイントを解決します。
  • azd プロジェクトの外部で、azd ai project set <endpoint>を使用してアクティブ コンテキストを 1 回設定するか、個々のリソース コマンド (--project-endpoint、connection、toolbox、またはskill) にroutineを渡します。 フォールバックとして、 azd ai は FOUNDRY_PROJECT_ENDPOINT 環境変数を読み取ります。
  • アクティブな環境から解決された空でないエンドポイントは、グローバル コンテキストよりも優先されます。 シェルのフォールバックとコマンド固有の動作については、「プロジェクト コンテキストの設定」を参照してください。

プロトコル

プロトコルは、Foundry とエージェント コンテナーの間の HTTP コントラクトを定義します。 エージェントはポート 8088 で待ち受けし、プロトコルに関係なく正常性プローブに応答します。

プロトコル API スタイル いつ使用するか
responses OpenAI Responses API (POST /responses) OpenAI API エコシステムと互換性のある標準的な選択肢。
invocations カスタム JSON コントラクト (POST /invocations) 要求と応答のペイロードを完全に制御する必要がある場合。

完全な仕様については、 ホストされるエージェントのランタイム コントラクトに関するページを参照してください。

これらのプロトコル設定は、hosted-agent コンテナーに適用されます。 プロンプト ベースの音声エージェントでは、ホステッド エージェント プロトコルは構成されません。

azd ai agent invoke は、プロンプトベースの音声エージェントまたはホスト型音声ラッパー向けの音声会話に対応していません。 CLI の動作とテストのガイダンスについては、「 音声エージェントの制限事項」を参照してください。

セッションと会話

概念 Description
Session 単一のエージェント操作用の分離された実行環境。 各セッションは、専用リソースを使用して独自のサンドボックスで実行されます。
会話 応答プロトコルのメッセージ履歴。 呼び出しでは、会話履歴は自動的に保持されません。

セッションは、 session_idによって識別されます。 CLI では、エージェントごとにセッション選択が保存され、既定で再利用されます。 --new-sessionを使用して新しいセッションを開始するか、--session-id <id>して特定のセッションをターゲットにします。 キャッシュは委任されたユーザーごとにキー化されません。--user-identityを使用する場合は、ユーザーとセッションの明示的な対応付けを維持してください。

Foundry プロジェクトのリソース

Foundry プロジェクトでは、エージェント以上のものをホストします。 また、エージェントが実行時に参照する共有リソースも保持されます。 CLI は、専用のコマンド グループを使用して各コマンドを管理します。

Resource それは何か で管理
Connection Foundry プロジェクトを外部リソース (MCP サーバー、Azure AI 検索、Bingでのグラウンドなど) にリンクします。 azd ai connection コマンド
ツールボックス エージェントが実行時に使用するツールの名前付きコレクション。 azd ai toolbox コマンド
Skill プロジェクト上のエージェント間で共有される再利用可能な動作ガイドライン。 azd ai skill コマンド
ルーチン トリガーとエージェントを呼び出すアクション。 azd ai routine コマンド

これらのリソースは、同じプロジェクトの開発者とエージェント間で共有されます。 それぞれのコマンドは異なります。接続とルーチンでは update が使用され、スキルでは update を通じて新しいバージョンが公開され、ツールボックスではバージョンを生成する接続とスキルの変更に続いて publish が使用されます。

エージェントを評価し、改善する

エージェントの実行後、次の 2 つの関連ワークフローを使用して、その品質の測定と改善に役立ちます。

  • クイック エージェントの評価では、オプティマイザー ワークフローを含め、 azd ai agent eval とローカル eval.yamlが使用されます。 Project評価では、個別にインストールされたazd ai eval拡張機能とevals/azure.eval.yamlを使用し、トレースまたはデータセット ソースと明示的な CI 品質ゲートを使用します。 2 つの構成形式は相互に置き換え可能ではありません。
  • 最適化により、評価シグナルを持ち上げるというエージェントのプロンプトが繰り返し書き換えられます。 評価がその目的関数として使用され、レビューして受け入れる候補プロンプトが生成されます。 azd ai agent optimizeを使用して管理します。

詳細については、azd CLI と Optimize エージェントプロンプトを使用したエージェント評価の実行を参照してください。

開発者ジョブ別のコマンド グループ

必要な結果を得るために、コマンドを選択してください。 --help を追加して、そのフラグやサポートされている出力形式を確認してください。

Job Commands ガイダンス
プロジェクトと管理対象モデルの構成 azd ai project add、azd ai project deployment add プロジェクトの構成と背景
エンドポイントコンテキストを選択または確認する azd ai project set、azd ai project show、azd ai project unset、azd ai project context グローバル エンドポイントの選択は、インフラストラクチャ宣言とは別です。 コンテキスト出力にはシークレットが含まれることがあります。
サンプルを参照するか、エージェントを初期化する azd ai agent sample list、azd ai agent init、azd ai agent add ホステッド エージェント、プロンプト エージェント、および音声エージェントを初期化する
エージェント向けにドキュメントとコンテンツを解析、抽出、分類する azd ai cu analyze、azd ai cu analyzer Azure Content Understanding CLI のクイック スタート (プレビュー)
ローカルで実行して確認する azd ai agent run、azd ai inspector launch ローカル開発
呼び出し、ユーザー ID の委任、またはカスタム ヘッダーの送信 azd ai agent invoke 呼び出しオプション
作業の確認、追跡、またはキャンセル azd ai agent invocations show、azd ai agent invocations follow、azd ai agent invocations cancel 実行時間の長い呼び出し
エンドポイントを検査または更新する azd ai agent endpoint show、azd ai agent endpoint update エンドポイントとカードの更新
状態の検査、問題の診断、ログの読み取り azd ai agent show、azd ai agent doctor、azd ai agent monitor 診断 と ログ
サンドボックスの作成、一覧表示、確認、停止、または削除 azd ai agent sessions create、azd ai agent sessions list、azd ai agent sessions show、azd ai agent sessions stop、azd ai agent sessions delete セッション管理
サンドボックスファイルの作成、取得、または維持 azd ai agent files upload、 azd ai agent files download、 azd ai agent files list、 azd ai agent files mkdir、 azd ai agent files stat、 azd ai agent files delete セッション ファイルの操作
デプロイされたソースを復元 azd ai agent code download コードまたは ZIP をダウンロードする
永続ストアを点検し、共有された項目を管理する azd ai agent state-stores list、azd ai agent state-stores select、azd ai agent state-stores show、azd ai agent state-stores items 状態ストアの操作と制限
エージェントの依存関係をデプロイ構成に追加する azd ai agent connection add、azd ai agent toolbox add 両方のサービスが既に azure.yamlに存在する必要があります。これらのコマンドは、リモート リソースではなく、 uses エントリを追加します。
接続の資格情報とメタデータを管理する azd ai connection create、azd ai connection list、azd ai connection show、azd ai connection update、azd ai connection delete 接続の認証とメンテナンス
再利用可能なスキルの作成、バージョン管理、またはダウンロード azd ai skill add、azd ai skill create、azd ai skill update、azd ai skill list、azd ai skill show、azd ai skill download、azd ai skill delete スキルワークフロー
ツールボックスの作成と管理 azd ai toolbox add、azd ai toolbox create、azd ai toolbox list、azd ai toolbox show、azd ai toolbox delete ツールボックスの構成
ツール コレクションの進化と促進 azd ai toolbox connection、azd ai toolbox skill、azd ai toolbox versions list、azd ai toolbox publish マージは最新バージョンから分岐し、マージの承認は明示的に行われます。
ルーチンのスケジュール設定、実行、または検査 azd ai routine add、azd ai routine create、azd ai routine list、azd ai routine show、azd ai routine update、azd ai routine enable、azd ai routine disable、azd ai routine dispatch、azd ai routine run list、azd ai routine delete ルーチンのワークフロー
簡易評価を生成して実行する azd ai agent eval generate、azd ai agent eval update、azd ai agent eval run、azd ai agent eval list、azd ai agent eval show 迅速な評価とオプティマイザー用アセット
最適化候補を改善してデプロイ azd ai agent optimize、 azd ai agent optimize status、 azd ai agent optimize list、 azd ai agent optimize cancel、 azd ai agent optimize apply、 azd ai agent optimize deploy 最適化ワークフロー
Teams のアクティビティ エージェントをパッケージ化または発行する azd ai agent pack、azd ai agent publish Teams のディストリビューション
ホストされているバージョンまたはエージェントを削除する azd ai agent delete エージェントの削除
プロジェクトを評価し、品質ゲートを適用する azd ai eval init、azd ai eval generate、azd ai eval create、azd ai eval run、azd ai eval dataset、azd ai eval evaluator、azd ai eval job プロジェクトの評価、azure.ai.evaluationsを個別にインストールする。
再利用可能なデータセットの登録とバージョン管理 azd ai dataset データセットのライフサイクル、azure.ai.dataset を個別にインストールする。
微調整ジョブの送信、一時停止、再開、キャンセル、またはデプロイ azd ai finetuning init、azd ai finetuning jobs 微調整、azure.ai.finetuneを個別にインストールする。
カスタム モデルの重みをアップロードして管理する azd ai models カスタム モデルのインポートとメンテナンス;azure.ai.models は別途インストール。

コマンドを追加する各拡張機能は、version を公開します。代わりに、azd ext list を使用して microsoft.foundry バンドルを検査します。 接続、ルーチン、およびスキル グループも、ローカル プロジェクトや環境の検査のために context を公開しています。この出力は機密情報を含む可能性があるため、取り扱いには注意してください。

アクティビティ エージェントの分布

アクティビティ プロトコル エージェントをデプロイした後、azd ai agent pack はサイドローディング用に appPackage.zip を作成します。 パッケージをカスタマイズするには、 --output-dir、 --display-name、および --app-version を使用します。 パッケージ化は公開と同じではありません。

azd ai agent publish は Microsoft 365 を通じて公開しています。 Simple Activity エージェントは、特に構成されていない限り、デフォルトで shared の配布設定になります。--scope tenant の場合は、管理者の承認が必要です。 デジタル ワーカーにはテナント スコープが必要です。 既存の境界を削除するには、繰り返し可能な --access-boundary 値と --clear-access-boundaries を使用し、オプションのアクセス許可には繰り返し可能な --optional-permission-scope <resource-app-id>=<scope> 値を使用してください。 personal は発行スコープではありません。pack --scope personal を使用し、ユーザーごとのテスト用にパッケージをサイドロードしてください。

デプロイのライフサイクル

完全な開発者ループは、コマンドの短いシーケンスに凝縮されます。 スキャフォールディングを 1 回行い、プロジェクトの拡大に合わせて直接コマンドを使用します。

管理対象の音声エージェント パスについては、「 クイック スタート: プロンプト音声エージェントを作成する」を参照してください。

# Scaffold a project from a template or your existing code
azd ai agent init

# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"

# Provision infrastructure and deploy the agent
azd up

# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent

# Evaluate quality
azd ai agent eval generate
azd ai agent eval run

# Tear down all Azure resources
azd down