コーディングエージェントとスクリプトで azd ai を使用する

Important

この記事で "(プレビュー)" と付記されている項目は、現在、パブリックプレビュー段階です。このプレビューはサービスレベルアグリーメントなしで提供されており、運用環境ではお勧めしません。特定の機能がサポートされていないか、機能が制限されている可能性があります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

コーディングエージェントやスクリプトから、人間がターミナルで使う場合と同じ動作で azd ai を使用します。信頼性の高い自動化のために、スタンドアロンコンテキストの設定、プロンプトの無効化、JSON 出力の解析、ダイレクトエージェントエンドポイントの呼び出しを行います。

前提条件

azd Foundry 拡張機能がインストールされています。
認証された azd セッション。
実行するコマンドの Microsoft Foundry プロジェクトエンドポイント。詳細については、「 azd プロジェクトコンテキストの設定」を参照してください。
省略可能: エージェントエンドポイントを呼び出す必要がある場合に、デプロイされたホステッドエージェント。セットアップについては、ホストされたエージェントのデプロイに関するページを参照してください。

Microsoft Foundry スキルから始める

コーディングエージェントは、 azd ai 規則を既に認識している場合に最適です。 Microsoft Foundry スキルは、コーディングエージェントにその知識を提供します。正しいazd ai コマンドと Foundry の配線を生成し、この記事のプラクティス (プロジェクトコンテキストの設定、--no-promptの受け渡し、構造化された結果の--output jsonの要求) を適用します。まずコーディングエージェントにそのスキルを参照させ、その後、この先の記事で紹介するパターンを使って、エージェントが生成したものをレビューし、堅牢化します。

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

connection、toolbox、skill、routineなど、すべてのリソースコマンドには、対象となる Foundry プロジェクトエンドポイントが必要です。自動化では、セッション、CI ジョブ、またはコーディングエージェント呼び出しごとに 1 回、そのエンドポイントを設定し、実行の残りの部分に使用します。

2 つのパターンがあります。

`azd ai project set` で 1 回ピン留め

環境変数をエクスポートせずにシェル間でコンテキストを保持する場合は、グローバル構成で設定します。

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt
azd ai project show

azd ai project set <endpoint> は、既に URL がわかっている場合は完全に非対話型です。 azd ai project show は、アクティブなエンドポイントを解決したソースを確認します。ホストの状態がわからない場合は、セッションの上部で使用します。

環境変数を設定する

スクリプトまたはコーディングエージェントが実行される環境で FOUNDRY_PROJECT_ENDPOINT を設定します。すべての azd ai コマンドは、プロジェクト内の azd 環境とグローバル設定に続いて、それを自動的に取得します。

export FOUNDRY_PROJECT_ENDPOINT="https://my-project.services.ai.azure.com/api/projects/my-project"
azd ai connection list --output json

シークレットと構成は通常、環境変数として既に到着し、ジョブ間でクリーンアップするグローバル状態がないため、このパターンは CI に適しています。

CLI がエンドポイントを解決する方法 (優先順位を含む) の詳細については、「 azd プロジェクトコンテキストの設定」を参照してください。

プロンプトを無効にする

すべての azd ai コマンドは --no-promptを受け入れます。これを設定すると、コマンドは対話型入力でブロックされるのではなく、高速で失敗します。必須引数が欠けている場合や、通常であればキー入力待ちになる delete 確認は、構造化出力時には即時エラーになります。

CI およびコーディングエージェント呼び出しでは、常に --no-prompt を設定します。

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --no-prompt

Tip

--no-prompt また、" delete 確認プロンプトをスキップする" ことを意味するため、1 つのプロンプトを非表示にするために --force 必要はありません。

JSON 出力を取得する

ほとんどのazd aiコマンドでは、--output json、connection、toolbox、skill リソースコマンドやroutineなど、azd ai agent showがサポートされています。これを使用して、人間が判読できるテキスト出力を取得する代わりに、 jq、 ConvertFrom-Json、または言語の JSON パーサーを使用して結果を確実に解析します。 azd ai agent invoke コマンドは、変更されていないサーバー応答に--output rawを使用します。

# List connections, extract names with jq
azd ai connection list --output json | jq -r '.[].name'

# Show a single resource as JSON
azd ai routine show daily-digest --output json | jq '.trigger'

# PowerShell example
$conn = azd ai connection show my-search --output json | ConvertFrom-Json
Write-Host $conn.target

テキスト出力は人間向けであり、リリース間で変更される可能性があります。 JSON シェイプは安定したコントラクトです。

冪等にリソースを作成する

create はアップサートではありません。名前付きリソースが既に存在する場合、再実行は失敗します。この既定値は、1 つの呼び出し元が別の呼び出し元の状態を暗黙的に上書きすることを防ぐため、プロジェクトスコープの共有リソースに適しています。

前の状態に関係なく成功する必要がある自動化の場合、 connection コマンドは既存のリソースを置き換える --force を受け入れます。

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --force --no-prompt

Warnung

--force は接続 (ARM PUT) を置き換えるものであり、マージされるわけではありません。同じリソースに対する別の呼び出し元の編集が失われる可能性があるため、共有リソースでは慎重に使用してください。

いくつかのフィールドのみを変更する必要があり、他のすべてを保持する必要がある場合は、 updateを使用します。または、 tool、 tag、 metadata、 keyなどの専用コレクションサブコマンドを使用します。

ファイルからツールボックスを作成する

組み込みのツール、接続、スキルをバンドルするマルチエントリーツールボックスの場合は、完全な定義を YAML ファイルに配置し、 --from-file を azd ai toolbox createに渡します。このファイルは、対応する AgentSchema 図形を使用します。

azd ai toolbox create research --from-file ./resources/research-toolbox.yaml --no-prompt

--from-file は、呼び出し時に読み取られたワンショット入力です。 CLI はファイルを追跡または再読み取りしないため、コマンドを再実行するまで、YAML に対する今後の編集は無効になります。明示的なフラグ (--kind、 --target、 --auth-type、および一致する資格情報フラグ) を使用して接続を作成し、ツールボックスファイルから名前で参照します。

azd プロジェクトなしでデプロイされたエージェントを呼び出す

コーディングエージェントまたはスクリプトが、作業ディレクトリの外部にあるデプロイ済みエージェントを呼び出す必要がある場合は、 --agent-endpoint を使用して直接ターゲットにします。この方法では、 azure.yaml とアクティブな azd env の両方がバイパスされます。 URL だけで十分です。

azd ai agent invoke \
  --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
  "Summarize today's release notes." \
  --no-prompt

この図形は、1 つのリポジトリの CI が別のリポジトリによって所有されているエージェントを呼び出す必要がある場合、または MCP サーバーが複数のエージェントの前にあり、そのエンドポイント URL のみを認識している場合に使用します。 invokeオプションの完全なセットについては、「ホストされたエージェントを呼び出す」を参照してください。

ローカル実行時にシークレットを渡す

シークレットを使用してエージェントをローカルで開始するには、azd環境変数として設定し、envのazure.ai.agent サービスのazure.yaml マップからそれらを参照します。値は .azure/<env>/.envに格納され、既定で gitignor されます。

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

# azure.yaml
services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

ローカル .env ファイルに存在しないシークレットの場合は、Foundry プロジェクト接続に格納し、 ${{connections.<name>.credentials.<field>}} プレースホルダーで参照します。完全なローカル実行サーフェスについては、「ホストされたエージェントをローカルで実行する」を参照してください。

短いセットアップのスクリプトを作成する

この bash スクリプトは、上記のパターンを組み合わせたものです。プロジェクトコンテキストをピン留めし、接続とツールボックスを冪等に作成し、ツールをツールボックスに組み込み、JSON を解析して結果を検証します。

#!/usr/bin/env bash
set -euo pipefail

azd ai project set "$FOUNDRY_PROJECT_ENDPOINT" --no-prompt

# A 'remote-tool' connection holds the URL and credentials for the MCP server.
azd ai connection create tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys \
  --custom-key "x-api-key=$TAVILY_KEY" \
  --force --no-prompt

# Create the toolbox with the connection wired in, in a single shot
cat > research-toolbox.yaml <<'EOF'
description: Research tools
connections:
  - name: tavily
EOF

azd ai toolbox create research --from-file ./research-toolbox.yaml --no-prompt

echo "Toolbox state:"
azd ai toolbox connection list research --output json | jq .

set -euo pipefail は、ステップエラーが発生した場合にスクリプトが高速に失敗することを保証します。 --no-promptと組み合わせることで、CI ゲートに適した確定的な終了コードが提供されます。

エンドポイントの解決を確認する

コーディングエージェントは、この優先順位を歩くことで、コマンドがターゲットとする Foundry プロジェクトを予測できます。値を生成する最初のソースが優先されます。以降のソースは参照されません。

--project-endpoint フラグ（または -p フラグ）（常に優先される）。
azd プロジェクト内: アクティブな azd env 値。
グローバル構成 ( azd ai project set によって設定)。
FOUNDRY_PROJECT_ENDPOINT 環境変数。
azd ai project setを実行したり、--project-endpointを渡したりするための構造化された提案でエラーが発生しました。

スタンドアロンコンテキストがプロジェクト内でどのように動作するかなど、完全な説明については、 azd プロジェクトコンテキストの設定に関するページを参照してください。

コーディングエージェントのヒントを適用する

常に --no-promptを渡し、それをサポートするコマンドに --output json を追加します。一緒に、予測可能な終了コードと解析可能な結果が得られます。
ホストの状態が不明な場合は、セッションの開始時に azd ai project show で解決されたコンテキストを確認します。これは低コストな読み取り専用の呼び出しです。
失敗した場合は、次の手順を決定するよりも、エラー出力の構造化された提案を解析することをお選びください。たとえば、"Foundry プロジェクトエンドポイントが解決されていません" というエラーは、再試行する前に、 azd ai project setを実行するか、 FOUNDRY_PROJECT_ENDPOINTを設定する必要があることを意味します。
--debugは、問題を診断する場合にのみ使用します。冗長な複数行出力を生成し、パースしにくいうえ、プログラム向けのインターフェースとして設計されたものではありません。
"already exists" という create エラーは復旧可能なものとして扱います。そのリソースを置き換えてよい場合は --force を付けて再実行し、一部だけを変更する必要がある場合は update とコレクションのサブコマンドに切り替えてください。

AZD プロジェクトコンテキストを設定して、CLI が Foundry プロジェクトエンドポイントを解決する方法を理解します。
パイプラインでを実行azd aiします。
ホストされたエージェントを呼び出して、azd ai agent invokeを含む完全な--agent-endpoint オプションを指定します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-06-26