Important
この記事で "(プレビュー)" と付記されている項目は、現在、パブリック プレビュー段階です。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境ではお勧めしません。 特定の機能がサポートされていないか、機能が制限されている可能性があります。 詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。
Azure Developer CLI (azd) とそのazd ai agent拡張機能を使用すると、アイデアから、Microsoft Foundry 上の運用準備完了のホステッド エージェントに移行するための 1 つのコマンドライン ワークフローが提供されます。 この記事では、開発者体験、エージェントを定義するファイル、および途中で発生する主要な概念について説明します。
この記事は、Foundry ポータルまたは言語 SDK よりもターミナル優先のスクリプト可能なワークフローを好む開発者を対象としています。
開発者体験
azd ai ワークフローは、小規模なプロトタイプを構築する場合でも運用エージェントを構築する場合でも、同じライフサイクルに従います。 プロジェクトをスキャフォールディングしてから、プロジェクトの拡大に合わせてコマンドを組み合わせます。
| 段階 | あなたの活動内容 | 詳細については、こちらをご覧ください |
|---|---|---|
| Install |
azdと Foundry 拡張機能をインストールします。 |
開発環境を設定する |
| スキャフォールディング | テンプレートまたは既存のコードからプロジェクトを初期化します。 | クイック スタート: ホストされたエージェントをデプロイする |
| 定義 |
agent.yamlでモデル、手順、およびツールを構成します。 |
ホステッド エージェント ランタイム コントラクト |
| 開発 | エージェント ロジックを記述し、ツールを追加し、ローカルでテストします。 | ツールの概要 |
| 展開 | インフラストラクチャをプロビジョニングし、Foundry にデプロイします。 | ホストされるエージェントをデプロイする |
| 操作する | ログの監視、バージョンの管理、実行の自動化。 | ホストされているエージェントを管理する |
| Evaluate | エージェントの品質を測定し、プロンプトを改善します。 | azd CLI を使用してエージェント評価を実行する |
エージェントの種類
azd ai agent拡張機能では、ホストされているエージェントに重点を置いています。
| タイプ | Description | いつ使用するか |
|---|---|---|
| ホスト型エージェント | コードでビルドし、Docker イメージとしてパッケージ化し、Foundry にデプロイするコンテナー化されたアプリケーション。 | カスタム ロジック、フレームワーク統合、または動作を完全に制御する必要があります。 |
| プロンプトエージェント | カスタム コードを使用せず、命令とツール構成によって完全に定義されたエージェント。 | アプリケーション コードを記述せずに、構成に基づく迅速なエージェントが必要です。 |
ホスト型エージェントを使用すると、ランタイム、フレームワーク、およびツールの統合を完全に制御でき、Foundry はインフラストラクチャ、スケーリング、セッション管理を処理します。
構成ファイル
3 つのファイルによって、エージェントの構築とデプロイ方法が定義されます。
| File | Purpose | 誰が管理する |
|---|---|---|
agent.yaml |
エージェントの ID (モデル、命令、ツール、プロトコル、環境変数) を定義します。 | 直接編集します。 |
agent.manifest.yaml |
テンプレート作成者が使用する agent.yaml のパラメーター化されたテンプレート。 これには、初期化中に解決される {{ parameter }} プレースホルダーが含まれています。 |
テンプレート作成者が作成します。
azd ai agent init が読み取ります。 |
azure.yaml |
Azure リソースのプロビジョニングとデプロイ方法 (サービス、インフラストラクチャ、コンテナーの設定) を定義します。 | 初期化によって生成されます。 必要に応じてカスタマイズします。 |
主な違いは、agent.yamlがエージェントの内容を説明し、azure.yamlはエージェントがどのようにデプロイされるかを説明することです。
接続、ツールボックス、スキル、ルーチンなど、Foundry プロジェクト自体に存在するリソースは、azd aiで宣言されるのではなく、直接のagent.yaml コマンドを使用して管理されます。
変数の置換
エージェント プロジェクト ファイルには、次の 2 つの変数構文が表示されます。
-
${VAR_NAME}は、azd環境変数プレースホルダーです。 デプロイ時に.azure/<env>/.envから解決されるため、開発、ステージング、運用などの環境で同じagent.yamlが機能します。 -
{{ parameter }}はマニフェスト テンプレート パラメーターです。 テンプレートから実際のプロジェクトが生成される際、azd ai agent initの中で解決されます。
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環境変数を読み取ります。 - プロジェクト内環境は常にグローバル コンテキストよりも優先されるため、ディレクトリをプロジェクトに変更すると、そのプロジェクトのエンドポイントで CLI が再ターゲットされます。
プロトコル
プロトコルは、Foundry とエージェント コンテナーの間の HTTP コントラクトを定義します。 エージェントはポート 8088 で待ち受けし、プロトコルに関係なく正常性プローブに応答します。
| プロトコル | API スタイル | いつ使用するか |
|---|---|---|
responses |
OpenAI Responses API (POST /responses) |
OpenAI API エコシステムと互換性のある標準的な選択肢。 |
invocations |
カスタム JSON コントラクト (POST /invocations) |
要求と応答のペイロードを完全に制御する必要がある場合。 |
完全な仕様については、 ホストされるエージェントのランタイム コントラクトに関するページを参照してください。
セッションと会話
| 概念 | Description |
|---|---|
| Session | 単一のエージェント操作用の分離された実行環境。 各セッションは、専用リソースを使用して独自のサンドボックスで実行されます。 |
| 会話 | セッション内のメッセージのシーケンス。 Foundry は会話履歴を管理し、要求間でハイドレートできます。 |
セッションは、 session_idによって識別されます。
azd ai agent invokeを実行すると、Foundry は既定で最後の呼び出しからのセッションを再利用します。
--new-sessionを使用して新しいセッションを開始するか、--session-id <id>して特定のセッションをターゲットにします。
Foundry プロジェクトのリソース
Foundry プロジェクトでは、エージェント以上のものをホストします。 また、エージェントが実行時に参照する共有リソースも保持されます。 CLI は、専用のコマンド グループを使用して各コマンドを管理します。
| Resource | それは何か | で管理 |
|---|---|---|
| Connection | Foundry プロジェクトを外部リソース (MCP サーバー、Azure AI 検索、Bingでのグラウンドなど) にリンクします。 |
azd ai connection コマンド |
| ツールボックス | エージェントが実行時に使用するツールの名前付きコレクション。 |
azd ai toolbox コマンド |
| Skill | プロジェクト上のエージェント間で共有される再利用可能な動作ガイドライン。 |
azd ai skill コマンド |
| ルーチン | トリガーとエージェントを呼び出すアクション。 |
azd ai routine コマンド |
これらのリソースは、同じプロジェクトの開発者とエージェント間で共有されます。 各コマンド グループは、標準の create、 update、 delete、 show、および list 動詞を公開します。
エージェントを評価し、改善する
エージェントの実行後、次の 2 つの関連ワークフローを使用して、その品質の測定と改善に役立ちます。
- 評価は、データセットに対してエージェントを実行し、1 つ以上のエバリュエーターを使用して応答をスコア付けし、集約品質シグナルを報告します。
azd ai agent evalを使用して管理します。 - 最適化により、評価シグナルを持ち上げるというエージェントのプロンプトが繰り返し書き換えられます。 評価がその目的関数として使用され、レビューして受け入れる候補プロンプトが生成されます。
azd ai agent optimizeを使用して管理します。
詳細については、azd CLI と Optimize エージェントプロンプトを使用したエージェント評価の実行を参照してください。
デプロイのライフサイクル
完全な開発者ループは、コマンドの短いシーケンスに凝縮されます。 スキャフォールディングを 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