Azure Developer CLI を使用してホストされるエージェントの CI/CD を設定する

azd pipeline configを使用して、ホステッド エージェントのデプロイを自動化します。 この記事では、GitHub ActionsまたはAzure DevOpsで継続的インテグレーションと配信を設定し、無人ジョブにパイプラインに適したazd ai フラグを適用します。

前提条件

• azd ai agent runとazd ai agent invoke --localでローカルに動作する初期化されたホステッド エージェント プロジェクト。 セットアップについては、「 エージェント プロジェクトを初期化する」を参照してください。
• azd upで少なくとも 1 回は正常にデプロイされたプロジェクト。 デプロイ手順については、「 ホストされたエージェントをデプロイする」を参照してください。
• azd Foundry 拡張機能は、ローカルおよびパイプライン ランナーにインストールされています。
• 認証された azd セッション。
• GitHubまたはAzure DevOpsでホストされている Git リポジトリ内のコード。

パイプラインを構成する

パイプライン構成コマンドを実行します。

azd pipeline config

この対話型コマンド:

1. GitHubやAzure DevOpsなど、Git プロバイダーを検出します。
2. CI/CD 認証用のサービス プリンシパルを作成します。
3. azd 環境の値を使用して、リポジトリのシークレットと変数を構成します。
4. GitHub Actionsの.github/workflows/azure-dev.ymlやAzure Pipelines YAML ファイルなどのワークフロー ファイルを生成します。

パイプライン フローを確認する

生成されたパイプラインは、既定で main へのプッシュ時に実行され、次を実行します。

1. azd provision -- infra/ Bicep テンプレートから Azure インフラストラクチャを作成または更新する。
2. azd deploy -- コンテナーをビルドし、ACR にプッシュし、新しいホステッド エージェント バージョンを作成します。

これは、ローカルでの azd up 実行と同じフローですが、CI では自動化されます。

GitHub Actions の構成

azd pipeline configすると、.github/workflows/azure-dev.yml ファイルが作成されます。 一般的なワークフローは次のようになります。

name: Azure Developer CLI

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
      AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
      AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
      AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install azd
        uses: Azure/setup-azd@v2

      - name: Install Foundry extensions
        run: azd ext install microsoft.foundry

      - name: Sign in to Azure (federated credentials)
        run: azd auth login --client-id $AZURE_CLIENT_ID --federated-credential-provider github --tenant-id $AZURE_TENANT_ID

      - name: Provision and Deploy
        run: azd up --no-prompt

Azure DevOpsの構成

azd pipeline configでは、Azure DevOpsもサポートされます。

1. メッセージが表示されたら、[Azure DevOps] を選択します。
2. 生成された azure-pipelines.yml ファイルを確認します。
3. 生成されたファイルに、同等のインストール、サインイン、プロビジョニング、デプロイの手順が含まれていることを確認します。

パイプラインに対応するフラグを設定する

ほとんどの azd ai コマンドは、CI で無人で安全に実行できるようにするフラグを受け入れます。 これらは、パイプライン内の関連する azd ai ステップに設定します。

• --no-prompt -- 対話型プロンプトを無効にします。 コマンドは、入力待ちでブロックするのではなく、分かりやすいエラーメッセージを表示して即座に失敗します。 すべての azd ai コマンドでサポートされます。 CI では必ずこれを設定してください。これを設定しないと、必須値が欠けている場合にジョブがタイムアウトするまでハングしたままになることがあります。
• --output json -- jq、PowerShell ConvertFrom-Json、またはその他の JSON ツールを使用して解析できる構造化された出力を出力します。これをサポートするコマンド ( azd ai agent show 、 connection、 toolbox、 skill、 routine コマンドなど)。 azd ai agent invoke 代わりに --output raw を使用します。
• --project-endpoint(-p) -- Microsoft Foundry プロジェクト エンドポイントを 1 つのリソース コマンド (connection、toolbox、skill、またはroutine) にピン留めします。 azd ai agentコマンドは、アクティブなazd環境、グローバル構成、またはFOUNDRY_PROJECT_ENDPOINT環境変数からプロジェクトを解決します。
• --debug -- 詳細な診断情報を出力します。 CI エラーを調査するときに役立ちますが、通常の実行ではノイズが発生します。

Example:

azd ai agent invoke my-agent "ping" --no-prompt --output raw

CI でプロジェクト コンテキストを設定する

パイプラインは対話型の azd プロジェクト コンテキストの外部で実行されるため、直接コマンド azd ai 対象とする Foundry プロジェクトを把握する必要があります。 パイプラインに適合する次の 2 つのパターンのいずれかを選択します。

環境変数を設定する

FOUNDRY_PROJECT_ENDPOINT は、ジョブまたはワークフロー全体で 1 回だけ設定します。 すべての azd ai コマンドは、プロジェクト内の azd env とグローバル設定に続いて、それを自動的に読み込みます。

jobs:
  agent-checks:
    runs-on: ubuntu-latest
    env:
      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
    steps:
      - uses: actions/checkout@v4
      - uses: Azure/setup-azd@v2
      - run: azd ext install microsoft.foundry
      - run: azd ai agent show --no-prompt --output json

エンドポイントをピン留めする azd ai project set

ジョブの早い段階で azd ai project set $FOUNDRY_PROJECT_ENDPOINT --no-prompt を実行します。 エンドポイントをグローバル azd config (~/.azd/config.json) に書き込み、同じジョブ内の後続の azd ai コマンドがそのコンテキストを使用します。

- run: azd ai project set ${{ vars.FOUNDRY_PROJECT_ENDPOINT }} --no-prompt
- run: azd ai agent show --no-prompt --output json

CLI は、--project-endpoint フラグ、azd プロジェクト内のアクティブなazd環境、azd ai project setによって設定されたグローバル構成、最後にFOUNDRY_PROJECT_ENDPOINT環境変数という順序でエンドポイントを解決します。 解決しない場合、コマンドは構造化エラーで終了します。

ディスク上で azd プロジェクトを使用せずに azd ai コマンドを実行する方法の詳細については、「 azd プロジェクト コンテキストを設定する」を参照してください。

CI で eval を使用して検証する

パイプラインがデプロイされた後、またはターゲット プロジェクトにアクセスした後、回帰チェックに azd ai agent eval run を使用します。 現在のエージェントに対して保存済みの評価を実行し、スコアがしきい値を下回った場合はジョブを失敗として扱います。

azd ai agent eval run --no-prompt

eval run は既定でプロジェクト ルートの eval.yaml を解決します。または、--config <path> を渡すこともできます。 データセットとエバリュエーターは副作用として再生成されません。 CI で eval スイートを起動するには、最初に azd ai agent eval generate 実行します。 このコマンドには、呼び出すことができるデプロイ済みのエージェントが必要です。

環境固有のデプロイを構成する

開発、ステージング、運用などの複数の環境の場合:

1. 別の azd 環境を作成します。

   azd env new staging
   azd env set AZURE_LOCATION=eastus2
   

2. 環境ごとにパイプラインを構成するか、ブランチ ベースのトリガーを使用します。

   • main -> 運用
   • develop -> ステージング

3. リソースが分離されるように、各パイプライン実行の独自の azd 環境変数を使用します。

シークレットを管理する

azd pipeline config では、次の値がリポジトリ シークレットまたは変数として格納されます。

• AZURE_CLIENT_ID -- サービス プリンシパル クライアント ID。
• AZURE_TENANT_ID -- Microsoft Entra テナント ID.
• AZURE_SUBSCRIPTION_ID -- ターゲット サブスクリプション。
• AZURE_ENV_NAME -- azd 環境名.
• AZURE_LOCATION -- Azure リージョン。

env内の azure.ai.agent サービスのazure.yaml マップから参照される MCP API キーなどのエージェント固有のシークレットを、より多くのリポジトリ シークレットとして追加します。 それぞれをパイプライン内の azd 環境変数にマップします。

パイプラインの問題のトラブルシューティング

パイプラインを再実行する前に、一般的な問題を確認します。 CI のプロビジョニングでは、Azure ロールに加えて Foundry Owner が必要になる場合があります。

関連するコンテンツ

• ホストされたエージェントをデプロイ して、デプロイ中に何が起こるかを理解します。
• デプロイ構成の詳細を確認するには、Azure YAML リファレンスを参照してください。
• azd パイプラインの完全なリファレンスについては、azd を使用して DevOps パイプラインを構成する を参照してください。