GitHub Copilot と Microsoft Foundry によるホステッド エージェントの構築

ローコード エージェントは動作をすばやく実証するのに適していますが、ほとんどのチームはやがてコード、デプロイ、統合に対するより強力な制御を必要とするようになります。この章では、コードファーストのワークフローに移行し、ローカルでの開発、ツールによるデバッグ、Microsoft Foundry へのデプロイが可能なホステッド エージェントを構築します。

この章を読み終える頃には、プロンプトのアイデアから本番向けのホステッド実行に至るまでの実用的な設計図が手に入ります。

ここから、エージェント開発が本格的なエンジニアリングのように感じられ始めます。

このフローの各ステップはそれ単体でも有用ですが、真の魔法が起こるのは、スキャフォールド、デバッグ、ツール、デプロイのすべてが 1 つの再現可能なシステムに統合されたときです。

問題の定義: コードファーストのエージェントが運用上の信頼性を向上させる

この章における最大の転換点は、単にプロンプトの代わりにコードを書くことではなく、運用上信頼性の高いライフサイクルへと移行することです。ローコード モードでは動作をすばやく検証できますが、デプロイの構成、ツールの統合、デバッグの深さが制限されることがよくあります。

コードファースト モードでは再現性を獲得できます。つまり、単一のリポジトリでランタイムの動作、ツールの配線、デプロイ フローが定義されます。

1 つのリポジトリ。単一の信頼できる情報源 (Single Source of Truth)。予期せぬトラブルの削減。

その価値を実感しやすい方法として、問題の診断方法の比較があります。コードファーストのワークフローでは、トレース、構成、ソースの変更をまとめてレビューできるため、ホステッド環境で動作がドリフト（逸脱）した際の修正時間を通常は短縮できます。

前提条件

開始する前に、ご使用の環境がローカル デバッグとホステッド デプロイの両方をサポートしていることを確認してください。この章では GitHub Copilot CLI、Foundry Toolkit、Azure デプロイ アセットを組み合わせるため、セットアップの抜け漏れがあると途中で作業が停滞しがちになります。

最初にこれらの前提条件を検証しておけば、残りの章では環境のトラブルシューティングではなくエージェント エンジニアリングに集中できます。

• エディターと拡張機能: Foundry Toolkit がインストールされた Visual Studio Code。
• GitHub Copilot へのアクセス: Visual Studio Code およびターミナル ワークフローで利用可能な GitHub Copilot。
• クラウド コンテキスト: Azure サブスクリプションと Microsoft Foundry プロジェクト。
• モデルのデプロイ: プロジェクトにすでにデプロイされている GPT-5 モデル インスタンス。
• CLI の準備: Azure Developer CLI と、Azure へのサインイン機能。

学習内容

この章では、開発者向けコンテンツの作成を目的としたコードベースのソーシャル キャンペーン アシスタントを作成します。プロンプトのみのプロトタイプとは異なり、このバージョンはソース管理され、検査可能であり、ホステッド エージェントとしてデプロイできます。

実験と、本番対応のチーム ワークフローとの架け橋と考えてください。

ここでは以下の方法を学びます:

• エージェント プロジェクトのスキャフォールディング: GitHub Copilot CLI のプロンプトを使用して、コード化されたプロジェクトを生成します。
• 再利用可能なツールの追加: Microsoft Learn MCP と Web 検索を使用して Foundry ツールボックスを構成します。
• ローカル ランタイム ループの実行: 呼び出しおよびデバッグのサイクルのために HTTP ベースのローカル エージェント サービスを使用します。
• ホステッド ターゲットへのデプロイ: Foundry 内の管理されたホステッド エージェントに公開します。

実践に入る前に、チームがこのモデルを選択する実用的な理由を整理しておきましょう。

コードベースのエージェントへ移行する理由

チームがコードベースのエージェントを選択するのは、ローコード ビルダーよりも詳細な制御が必要になる場合です。通常、これにはビジネス固有のロジック、決定論的な構成ファイル、再現可能なデプロイ、アプリケーション コードとの直接統合が含まれます。

言い換えれば、コードベースのエージェントは複雑さそれ自体が目的ではありません。制御性、信頼性、そしてチーム規模での保守性を確保するためのものです。

「環境間でこのエージェントの動作を予測可能にするにはどうすればよいか？」と疑問に思ったことがあるなら、まさにこのワークフローがその答えになります。

• 制御 (コントロール): ソース管理でプロンプト、ランタイム設定、依存関係をバージョン管理します。
• 拡張性: カスタム ロジックや、より高度なツール オーケストレーション パターンを追加できます。
• 再現性: 構成ファイルやインフラストラクチャ ファイルを通じて環境を正確に再現できます。
• 本番環境への適合: ホステッド エージェントのライフサイクルを通じてデプロイと運用を行えます。

ステップ 1: GitHub Copilot CLI でソリューションをスキャフォールディングする

まずはターミナルで GitHub Copilot CLI を起動し、対象のソリューションを自然言語で記述します。この章のスキャフォールディング プロンプトには、キャンペーン アシスタントの動作、確認用の質問（クロリフィケーション）の動作、取得ツール、GPT-5 モデルの使用、ホステッド環境へのデプロイ性が含まれています。

最初に考慮すべき点は次のとおりです。

• プロンプト: 動作、ツール、モデル、デプロイの意図を記述します。
• GitHub Copilot CLI: GitHub Copilot に、中断を最小限に抑えながらマルチステップのセットアップを実行させます。これには「オートパイロット モード」を使用します。

新しいエージェント プロジェクトをスキャフォールディングする手順を見ていきましょう

1. 作業フォルダーでターミナルを開きます。

2. 該当のフォルダーで GitHub Copilot CLI を起動します。copilot を実行します。

3. セットアップが中断なく実行できるように、オートパイロット モード（/autopilot on）を有効にします。

4. Autopilot mode enabled with all permissions. というメッセージが表示されていることを確認します。

5. エージェントの動作、ツール、デプロイの意図を記述した自然言語のプロンプトを入力します。

   サンプル画像の以下のプロンプトを使用します

   Create a Foundry agent solution for a developer social media campaign assistant promoting developer productivity tools. The agent should ask clarifying questions, use data retrieval tools to extract the right context for the campaign and generate social post options. The agent should be configured to use a Foundry toolbox, including the MS MCP Learn server to retrieve Microsoft official documentation and the web search tool to access fresh data. It should be deployable as a hosted agent. Use a gpt-5 model instance. Open project folder when done.
   

6. 生成されたファイルが目的のプロジェクト保存先に作成されていることを確認します。

以下のサンプル プロンプトを参照してください

図 01: GitHub Copilot CLI のスキャフォールディング プロンプトと生成されたプロジェクトの出力。

この時点で、ディスク上にはすでにプロジェクトの骨組みが作成されているはずです。次に、生成された内容を確認し、自分の意図と一致しているかチェックしてみましょう。

ステップ 2: GitHub Copilot が生成した内容の確認

生成された内容を見ていきましょう。プロジェクト フォルダーには次のようなファイルが含まれているはずです

• Main runtime: main.py には、アシスタントのコアロジックとランタイムの配線が含まれています。
• エージェント構成: agent.yaml は、動作、ホスティング、プロトコル、ランタイム設定を定義します。
• ツール構成: toolbox.yaml は、接続されたツールとツールのエンドポイントを記述します。
• デプロイ構成: azure.yaml および infra/ 配下の Bicep テンプレートが、プロビジョニングとデプロイを駆動します。

ファイルの役割が不明確な場合は、デプロイする前に必ず確認して解決してください。この段階での曖昧さは、クラウド リソースが絡むようになると後々大きな手戻りコストにつながります。

ステップ 3: ツールの作成とセットアップの検証

スキャフォールディングされた全体像を確認したところで、次はスキャフォールディングの一環として設定されたツールについて詳しく見ていきましょう。

プロジェクト内で toolbox.yaml ファイルを開き、少なくとも 2 つのツール（Microsoft Learn MCP 用と Web 検索用）が作成されていることを確認します。

これらのツールは次のような役割を果たします

• Web 検索: 時限性のある情報やトレンド情報に関する最新の Web コンテキストを取得します。
• Microsoft Learn MCP: 信頼性の高い製品情報やドキュメントのコンテキストを取得します。

これらのツールがどのように構成されているかを以下に示します

図 02: Foundry ツールボックスの構成。

ツールが追加されたら、生成されたアセットに目を通し、実行前に挙動を予測できるようにしておきましょう。

ステップ 4: エージェントのローカルでの実行と呼び出し

デプロイする前に、ターミナルベースのコマンドでローカルの動作を検証します。これにより高速なフィードバック ループが実現し、クラウド リソースが関係する前に指示やランタイムの問題を検知できます。

この章のフローでは、ローカルでの呼び出しにより、期待どおりの「確認用の質問」の挙動が行われることを検証します。

1. プロジェクトのルートから azd ai agent run を実行します。

   このコマンドにより、必要な依存関係がインストールされ、ローカル ランタイムが起動し、エージェントが HTTP サービスとして提供されます。

2. ローカル ランタイムの準備完了が通知されるまで待ってから、新しいターミナルを開いてエージェントを呼び出します。

3. 別のターミナルで azd ai agent invoke を実行し、実際のシナリオに沿ったキャンペーン プロンプトを入力してエージェントを呼び出します。

   次のような結果が表示されます

   

   図 03: ローカル エージェントの実行とプロンプトの呼び出し。

ステップ 5: Agent Inspector 統合の構成

詳細な検査やトラブルシューティングを行うために、プロジェクトを Agent Inspector 向けに構成します。この章では、GitHub Copilot を使って HTTP 配信要件の検証、依存関係のインストール、Visual Studio Code のデバッグ構成の準備を行います。

これにより、プロジェクトは「1 回動くだけ」ではなく、何度でも簡単にデバッグできる状態になります。

1. ローカル エージェントをインスペクターに接続する方法を記述したプロンプトを GitHub Copilot Chat で実行し、インスペクターをセットアップします。

   以下の画像を参考にしてください。要するに、ツールのインストールを行い、Visual Studio Code 用の tasks.json と launch.json を構成するよう指示する必要があります。

   

インスペクターの連携が完了すると、最終的な出力テキストから推測するのではなく、原因と結果を直接検証できるようになります。

ステップ 6: Agent Inspector を使用したデバッグ

それでは、インスペクターを実行してみましょう

デバッグを開始し、Agent Inspector を開いてライブのランタイム動作を観察します。これにより、イベント、ストリーミングの差分（デルタ）、メタデータ、トレース、ツール呼び出しを直接確認できるようになります。

インタラクティブなプレイグラウンドと、右側にトレースが表示されるはずです。画面は下の画像のような外観になっているはずです。

図 04: イベント タイムラインとトレース ビューが表示された Agent Inspector のデバッグ セッション。

ここに至って、エージェント開発は「ブラックボックスの推測」から「検査可能なエンジニアリング」へと移行します。

プロンプトをテストしながら、イベント タイムラインとトレース ビューを確認し、応答が期待どおりに進行しているか、取得ロジックが暗黙的にスキップされていないかを検証します。

• イベント タイムライン: 応答のライフサイクル状態やトークンの進行状況を検査します。
• ツールの可視性: 各ツール呼び出しの入力、出力、呼び出し理由を確認します。
• トレース分析: トレース ビューを使用して、期待される動作からの乖離を素早く診断します。
• イテレーション ループ: プロンプトの入力、検査、指示の洗練、再テストを繰り返します。

ヒント: クリーンなトレースを 1 回取得したら、取得機能（検索）を使わなければうまく答えられないプロンプトを入力し、ツールの配線に実戦的なストレステストを実施してみてください。

ステップ 7: 取得動作を確認するためのフォローアップ プロンプト

この時点でエージェントは起動しており、追加の質問（フォローアップ）を求めてきます。ここでは、エージェントが設定した取得ツールを実際に使用していることを確認しながら、何らかの返答を行ってみましょう。

次のようなプロンプトを入力します

Highlight the mobile chat feature, drive installs, general dev audience, technical tone, #github copilot

これでツールが呼び出され、次のような応答が生成されるはずです

図 05: ツール呼び出しと構造化出力を含むフォローアップ プロンプトの応答。

ステップ 8: ホステッド エージェントとしてのデプロイ

次に、エージェントをホステッド環境にデプロイします。このステップでは、先ほどローカルでデバッグしたものと同じプロジェクト アセットを使用するため、動作が一貫しているという確信を持てます。

1. 右上隅にある Agent Inspector の [Deploy] ボタンをクリックします。

   次のような画面が表示されます

   

   図 06: Agent Inspector を介したデプロイ。

2. [Next] をクリックします。

3. [Review and Deploy] で [Select Existing Dockerfile] を選択し、コンピューター上のファイルを指定します。最後に [Deploy] をクリックしてデプロイプロセスを開始します。

簡単な質問

ローカルでの実行は正常に見えるにもかかわらず、ホステッド環境での応答にズレ（ドリフト）が生じる場合、最初に何をチェックすべきでしょうか？（プロンプトの文言、ツール呼び出し、あるいはランタイム/デプロイ構成のどれでしょうか？）

回答

まずはランタイム/デプロイ構成とツール呼び出しのトレースを確認し、その後にプロンプトの文言を見直してください。ホステッド環境でのズレは、プロンプトのテキストだけでは見えない環境や統合の差異に起因することが多いためです。ランタイムの同等性が確認できれば、プロンプトのブラッシュアップも非常に確実なものになります。

今後の展望

ホステッド型のコードベースのエージェントをリリースした後の次のステップは、継続的なリリースに向けてライフサイクルを強化（ハードニング）することです。エージェントのスコープが拡大するにつれて、より強力な評価パイプライン、トレース駆動のデバッグ手法、デプロイや回帰テストの自動化に注力しましょう。

次の章は、リセットではなく、このワークフローの自然な延長線上にあると感じられるはずです。

あなたの課題

ホステッド フローの全体像を把握できたところで、本番を想定した小さな演習をご自身で試してみましょう。目標は、推測に頼ることなく、スキャフォールディングから再現可能な検証へと移行できることを証明することです。このチェックリストをアクションプランとして活用してください。

1. GitHub Copilot CLI を使用して、別のシナリオに向けた新しいホステッド エージェントをスキャフォールディングします。
2. 少なくとも 1 つのグラウンディング（根拠付け）ツールと、それをいつ使用すべきかを指定する 1 つのルールを追加します。
3. ツールの使用を強制する少なくとも 2 つのプロンプトを用いて、ローカル環境で動作を検証します。
4. エージェントをデプロイし、ローカルのトレース 1 件とホステッド環境のトレース 1 件を比較します。
5. 動作の差異を 1 つ挙げ、それに適用した修正内容を文書化します。

達成目標: プロンプト入力からホステッド出力までの全プロセスを説明でき、各ステージの証拠（エビデンス）を提示できること。

詳細情報

この章を終えた後により深く学習を進めたい場合は、プラットフォームのガイダンスとホステッド エージェントのデプロイ リファレンスを組み合わせて参照するのが最適です。これにより、本番環境に関するコンテキストと、次に行うべき実用的なステップを把握できます。以下のリンクを実践的な学習の継続パスとしてご活用ください。

• Visual Studio Code における GitHub Copilot: Visual Studio Code のドキュメントで Copilot のワークフローを確認する。
• Azure AI Foundry の概要: Azure AI Foundry のプラットフォームとワークフロー全体を理解する。
• Azure AI エージェントの概要: ホステッド エージェントの概念とライフサイクルに関するガイダンスを確認する。
• Azure Developer CLI のドキュメント: 再現可能なセットアップおよびデプロイ ワークフローに azd を使用する。