Skip to content

Getting Started

ワークショップの種類を選択します:

Self-Guided Learners (自己学習者向け)

このページは、Self-Guided Learners (自己学習者向け) のコンテンツです。以下の手順に従って環境をセットアップし、ワークショップを開始してください。

はじめに

このワークショップは、Azure AI Agents サービスと関連 SDK について学ぶことを目的としています。複数のラボで構成されており、各ラボでは Azure AI Agents サービスの特定の機能に焦点を当てています。各ラボは前のラボの知識と作業に基づいて構築されるため、順番に完了することを想定しています。

前提条件

  • GitHub アカウントが必要です。お持ちでない場合は、こちらの GitHub 公式ページで作成してください。
  • Azure サブスクリプションへのアクセス。Azure サブスクリプションをお持ちでない場合は以下どちらかをお選びください。
  • COGBOT コミュニティより Azure AI Fundory を利用するためのキーなどを提供していただく。
  • Azure の無料アカウントを作成する。

ワークショップのプログラミング言語を選択

ワークショップは Python と C# の両方で利用可能です。該当箇所では、言語セレクタータブを使用して希望の言語を選択してください。注意：ラボの途中で言語を切り替えないでください。

希望する言語のタブを選択してください：

ワークショップのデフォルト言語は Python に設定されています。

ワークショップのデフォルト言語は C# に設定されています。

ワークショップを開く

このワークショップを実行する推奨方法は、GitHub Codespaces を使用することです。このオプションは、ワークショップを完了するために必要なすべてのツールとリソースを備えた事前設定済みの環境を提供します。 または、Visual Studio Code の Dev Container を使用してローカルでワークショップを開くこともできます。

Open in GitHub Codespaces をクリックして、GitHub Codespaces でプロジェクトを開きます。

Open in GitHub Codespaces

Codespace のビルドには数分かかります。ビルド中に指示を読み進めることができます。

ローカル環境でのトラブルが発生すると、ワークショップが全く進行できずタイムアップになる可能性があるため、ローカルで VS Code から Dev Container の利用に精通している方のみが利用してください。

Apple Silicon ユーザー

まもなく実行する自動デプロイスクリプトは Apple Silicon ではサポートされていません。デプロイスクリプトは、Dev コンテナーではなく Codespaces または macOS から実行してください。

Visual Studio Code Dev コンテナーを使用してローカルでプロジェクトを開くこともできます。これにより、Dev Containers 拡張機能を使用して、ローカルの VS Code 開発環境でプロジェクトが開かれます。

  1. Docker Desktop を起動します（まだインストールされていない場合はインストールします）。

  2. Dev Containers Open を選択して、VS Code Dev コンテナーでプロジェクトを開きます。

    Dev Containers で開く

ローカルシステムでのダウンロードとセットアップを含む Dev コンテナーのビルドプロセスには数分かかります。この間、指示を読み進めることができます。

Azure の認証

COGBOT コミュニティより Azure サブスクリプションの情報を提供いただく方は、「Azure の認証」「Azure のリソースをデプロイ」のセクションを飛ばして、「言語ワークスペースの選択」へ進みます。

Agent App が Azure AI Agents Service とモデルにアクセスできるように、Azure に認証する必要があります。以下の手順に従ってください：

  1. Codespace が作成されていることを確認します。
  2. Codespace で、VS Code メニューからターミナル > 新しいターミナルを選択して、新しいターミナルウィンドウを開きます。

  3. 次のコマンドを実行して Azure に認証します：

    az login --use-device-code

    Note

    ブラウザリンクを開き、Azure アカウントにログインするように求められます。最初に認証コードをコピーしてください。

    1. ブラウザウィンドウが自動的に開き、アカウントの種類を選択して次へをクリックします。
    2. Azure サブスクリプションのユーザー名とパスワードでサインインします。
    3. 認証コードを貼り付けます。
    4. OK、次に完了を選択します。

    Warning

    複数の Azure テナントをお持ちの場合は、認証時に適切なテナントを選択する必要があります。

    az login --use-device-code --tenant <tenant_id>

  4. 次に、コマンドラインから適切なサブスクリプションを選択します。

  5. 次のステップのためにターミナルウィンドウを開いたままにしておきます。

Azure のリソースをデプロイ

以下のリソースが、Azure サブスクリプションの rg-contoso-agent-workshop リソースグループに作成されます。

  • agent-wksp という名前の Azure AI Foundry Hub
  • Agent Service Workshop という名前の Azure AI Foundry project
  • gpt-4o (Global 2024-08-06) という名前の サーバーレス (従量課金制) GPT-4o モデルのデプロイメント。価格の詳細はこちらこちら。
  • Grounding with Bing Search というリソース。ドキュメントと価格で詳細をご覧ください。

gpt-4o Global Standard SKU で 140K TPM のクォータ可用性が必要です。これは、エージェントが大量のトークンを使用するためではなく、エージェントがモデルに対して行う呼び出しの頻度のためです。AI Foundry Management Centerでクォータの可用性を確認してください。

ワークショップに必要なリソースのデプロイを自動化するための bash スクリプトを提供しています。または、Azure AI Foundry スタジオを使用して手動でリソースをデプロイすることもできます。希望するタブを選択してください。

スクリプト deploy.sh は、デフォルトで eastus2 リージョンにデプロイします。リージョンまたはリソース名を変更するには、ファイルを編集してください。スクリプトを実行するには、VS Code ターミナルを開き、次のコマンドを実行します：

cd infra && ./deploy.sh

ワークショップ構成

デプロイスクリプトは、プロジェクト接続文字列、モデルデプロイメント名、および Bing 接続名を含む .env ファイルを生成します。

.env ファイルは、プロジェクト接続文字列を除いて、次のように表示されるはずです。

MODEL_DEPLOYMENT_NAME="gpt-4o"
BING_CONNECTION_NAME="groundingwithbingsearch"
PROJECT_CONNECTION_STRING="<your_project_connection_string>"

自動デプロイスクリプトは、ASP.NET Core での開発におけるアプリシークレットの安全な保存のためのシークレットマネージャー機能を使用して、プロジェクト変数を安全に保存します。

次のコマンドを実行してシークレットを表示できます：

dotnet user-secrets list

または、deploy.sh スクリプトを使用したくない場合は、次のように Azure AI Foundry ポータルを使用して手動でリソースをデプロイできます：

  1. ブラウザを使用して Azure AI Foundry Web ポータルに移動し、アカウントでサインインします。

  2. + プロジェクトを作成を選択します。

    • プロジェクトに名前を付けます

      agent-workshop

    • 次の名前で新しいハブを作成します

      agent-workshop-hub

    • 作成を選択し、プロジェクトが作成されるのを待ちます。

  3. マイ アセットから、モデル + エンドポイントを選択します。

  4. モデルのデプロイ / 基本モデルのデプロイを選択します。

    • モデルリストから gpt-4o を選択し、確認を選択します。

    • デプロイメントに名前を付けます

      gpt-4o

    • デプロイメントタイプ：Global Standard を選択します。

    • カスタマイズを選択します。
    • モデルバージョン：2024-08-06 を選択します。
    • 1分あたりのトークン数レート制限：140k を選択します。
    • デプロイを選択します。

Note

プロジェクトをデプロイしたリージョンによっては、特定のバージョンの GPT-4o が必要になる場合があります。 詳細はモデル: アシスタント (プレビュー)を参照してください。

ワークショップ構成

エージェントアプリを Azure AI Foundry プロジェクトに接続するには、プロジェクト接続文字列が必要です。この文字列は、Azure AI Foundry ポータルのプロジェクト agent-workshop の概要ページ（プロジェクト詳細セクション内）にあります。

次のコマンドを使用してワークショップ構成ファイルを作成します：

cp src/workshop/.env.sample src/workshop/.env

次に、ファイル src/workshop/.env を編集して、プロジェクト接続文字列を指定します。

  1. VS Code で新しいターミナルウィンドウを開きます。

  2. 次のコマンドを実行して、C# プロジェクトパス $CSHARP_PROJECT_PATH 変数を設定します：

    CSHARP_PROJECT_PATH="src/csharp/workshop/AgentWorkshop.Client/AgentWorkshop.Client.csproj"

  3. 次のコマンドを実行して、プロジェクト接続文字列の ASP.NET Core 安全なシークレットを設定します：

    <your_project_connection_string> を実際の接続文字列に置き換えてください

    dotnet user-secrets set "ConnectionStrings:AiAgentService" "<your_project_connection_string>" --project "$CSHARP_PROJECT_PATH"

  4. 次のコマンドを実行して、モデルデプロイメント名の ASP.NET Core 安全なシークレットを設定します：

    dotnet user-secrets set "Azure:ModelName" "gpt-4o" --project "$CSHARP_PROJECT_PATH"

言語ワークスペースの選択

COGBOT コミュニティより Azure サブスクリプションの情報を提供いただく方は、その情報をもとに .env ファイルを作成します。作成方法は講師が解説します。

ワークショップには、Python 用と C# 用の 2 つのワークスペースがあります。ワークスペースには、各言語のラボを完了するために必要なソースコードとすべてのファイルが含まれています。使用したい言語に一致するワークスペースを選択してください。

  1. VS Code メニューから、ファイル > ファイルでワークスペースを開くを選択します。
  2. .vscode/python-workspace.code-workspace ファイルを選択します。

プロジェクト構造

ワークショップ全体を通して作業する主要なサブフォルダとファイルについてよく理解しておいてください。

workshop フォルダ

  • main.py ファイル：アプリのエントリポイントで、主要なロジックが含まれています。
  • sales_data.py ファイル：SQLite データベースに対して動的 SQL クエリを実行する関数ロジック。
  • stream_event_handler.py ファイル：トークンストリーミングのイベントハンドラーロジックが含まれています。

shared フォルダ

  • files フォルダ：エージェントアプリによって作成されたファイルが含まれています。
  • fonts フォルダ：コードインタープリターで使用される多言語フォントが含まれています。
  • instructions フォルダ：LLM に渡される指示が含まれています。

ラボフォルダ構造

  1. VS Code メニューから、ファイル > ファイルでワークスペースを開くを選択します。
  2. .vscode/csharp-workspace.code-workspace ファイルを選択します。

プロジェクト構造

ワークショップ全体を通して作業する主要なサブフォルダとファイルについてよく理解しておいてください。

workshop フォルダ

  • Lab1.cs, Lab2.cs, Lab3.cs ファイル：各ラボのエントリポイントで、そのエージェントロジックが含まれています。
  • Program.cs ファイル：アプリのエントリポイントで、主要なロジックが含まれています。
  • SalesData.cs ファイル：SQLite データベースに対して動的 SQL クエリを実行する関数ロジック。

shared フォルダ

  • files フォルダ：エージェントアプリによって作成されたファイルが含まれています。
  • fonts フォルダ：コードインタープリターで使用される多言語フォントが含まれています。
  • instructions フォルダ：LLM に渡される指示が含まれています。

ラボフォルダ構造

Microsoft Build Attendees

Warning

こちらはアメリカのシアトルで開催の Microsoft Build 2025 に参加している方向けのページです。 🚧通常のワークショップに参加している方は "Self-Guided Learners" のコンテンツをご利用ください。🚧

The instructions on this page assume you are attending Microsoft Build 2025 and have access to a pre-configured lab environment. This environment provides an Azure subscription with all the tools and resources needed to complete the workshop.

Introduction

This workshop is designed to teach you about the Azure AI Agents Service and the associated SDK. It consists of multiple labs, each highlighting a specific feature of the Azure AI Agents Service. The labs are meant to be completed in order, as each one builds on the knowledge and work from the previous lab.

Select Workshop Programming Language

The workshop is available in both Python and C#. Please make sure to select the language that fits the lab room you are in, by using the language selector tabs. Note, don't switch languages mid-lab.

Select the language tab that matches your lab room:

The default language for the workshop is set to Python.

The default language for the workshop is set to C#.

Authenticate with Azure

You need to authenticate with Azure so the agent app can access the Azure AI Agents Service and models. Follow these steps:

  1. Open a terminal window. The terminal app is pinned to the Windows 11 taskbar.

    Open the terminal window

  2. Run the following command to authenticate with Azure:

    az login

    Note

    You'll be prompted to open a browser link and log in to your Azure account.

    1. A browser window will open automatically, select Work or school account and click Next.

    2. Use the Username and Password found in the top section of the Resources tab in the lab environment.

    3. Select OK, then Done.

  3. Then select the Default subscription from the command line, by clicking on Enter.

  4. Once you've logged in, run the following command to assign the user role to the resource group:

    $subId = $(az account show --query id --output tsv) `
;$objectId = $(az ad signed-in-user show --query id -o tsv) `
; az role assignment create --role "f6c7c914-8db3-469d-8ca1-694a8f32e121" --assignee-object-id $objectId --scope /subscriptions/$subId/resourceGroups/"rg-agent-workshop" --assignee-principal-type 'User'

  5. Leave the terminal window open for the next steps.

Open the Workshop

Follow these steps to open the workshop in Visual Studio Code:

  1. From the terminal window, execute the following commands to clone the workshop repository, navigate to the relevant folder, set up a virtual environment, activate it, and install the required packages:

    git clone https://github.com/microsoft/build-your-first-agent-with-azure-ai-agent-service-workshop.git `
; cd build-your-first-agent-with-azure-ai-agent-service-workshop `
; python -m venv src/python/workshop/.venv `
; src\python\workshop\.venv\Scripts\activate `
; pip install -r src/python/workshop/requirements.txt `
; code --install-extension tomoki1207.pdf

  2. Open in VS Code. From the terminal window, run the following command:

    code .vscode\python-workspace.code-workspace

    When the project opens in VS Code, two notifications appear in the bottom right corner. Click ✖ to close both notifications.

  1. From a terminal window, execute the following commands to clone the workshop repository: 
    git clone https://github.com/microsoft/build-your-first-agent-with-azure-ai-agent-service-workshop.git

  1. Open the workshop in Visual Studio Code. From the terminal window, run the following command:

    code build-your-first-agent-with-azure-ai-agent-service-workshop\.vscode\csharp-workspace.code-workspace

When the project opens in VS Code, a notification will appear in the bottom right corner to install the C# extension. Click Install to install the C# extension, as this will provide the necessary features for C# development.

  1. Open the workshop in Visual Studio 2022. From the terminal window, run the following command:

    start build-your-first-agent-with-azure-ai-agent-service-workshop\src\csharp\workshop\AgentWorkshop.sln

    You may be asked what program to open the solution with. Select Visual Studio 2022.

Project Connection String

Next, we log in to Azure AI Foundry to retrieve the project connection string, which the agent app uses to connect to the Azure AI Agents Service.

  1. Navigate to the Azure AI Foundry website.
  2. Select Sign in and use the Username and Password found in the top section of the Resources tab in the lab environment. Click on the Username and Password fields to automatically fill in the login details. Azure credentials
  3. Read the introduction to the Azure AI Foundry and click Got it.

  4. Ensure you are on the AI Foundry home page. Click the AI Foundry tab in the top left corner.

    AI Foundry home page

  5. Select the project name that starts with aip-.

    Select project

  6. Review the introduction guide and click Close.

  7. Locate the Project details section, click the Copy icon to copy the Project connection string.

    Copy connection string

Configure the Workshop

  1. Switch back to the workshop you opened in VS Code.

  2. Rename the .env.sample file to .env.

    • Select the .env.sample file in the VS Code Explorer panel.
    • Right-click the file and select Rename, or press F2.
    • Change the file name to .env and press Enter.

  3. Paste the Project connection string you copied from Azure AI Foundry into the .env file.

    PROJECT_CONNECTION_STRING="<your_project_connection_string>"

    Your .env file should look similar to this but with your project connection string.

    MODEL_DEPLOYMENT_NAME="gpt-4o"
BING_CONNECTION_NAME="groundingwithbingsearch"
PROJECT_CONNECTION_STRING="<your_project_connection_string>"

  4. Save the .env file.

Project Structure

Be sure to familiarize yourself with the key subfolders and files you’ll be working with throughout the workshop.

  1. The main.py file: The entry point for the app, containing its main logic.
  2. The sales_data.py file: The function logic to execute dynamic SQL queries against the SQLite database.
  3. The stream_event_handler.py file: Contains the event handler logic for token streaming.
  4. The shared/files folder: Contains the files created by the agent app.
  5. The shared/instructions folder: Contains the instructions passed to the LLM.

Lab folder structure

Configure the Workshop

  1. Open a terminal and navigate to the src/csharp/workshop/AgentWorkshop.Client folder.

    cd build-your-first-agent-with-azure-ai-agent-service-workshop\src\csharp\workshop\AgentWorkshop.Client

  2. Add the Project connection string you copied from Azure AI Foundry to the user secrets.

    dotnet user-secrets set "ConnectionStrings:AiAgentService" "<your_project_connection_string>"

  3. Add the Model deployment name to the user secrets.

    dotnet user-secrets set "Azure:ModelName" "gpt-4o"

Project Structure

Be sure to familiarize yourself with the key subfolders and files you’ll be working with throughout the workshop.

The workshop folder

  • The Lab1.cs, Lab2.cs, Lab3.cs files: The entry point for each lab, containing its agent logic.
  • The Program.cs file: The entry point for the app, containing its main logic.
  • The SalesData.cs file: The function logic to execute dynamic SQL queries against the SQLite database.

The shared folder

  • The files folder: Contains the files created by the agent app.
  • The fonts folder: Contains the multilingual fonts used by Code Interpreter.
  • The instructions folder: Contains the instructions passed to the LLM.

Lab folder structure

Pro Tips

Tips

  1. The Burger Menu in the right-hand panel of the lab environment offers additional features, including the Split Window View and the option to end the lab. The Split Window View allows you to maximize the lab environment to full screen, optimizing screen space. The lab's Instructions and Resources panel will open in a separate window.
  2. If the lab instructions are slow to scroll in the lab environment, try copying the instructions’ URL and opening it in your computer’s local browser for a smoother experience.
  3. If you have trouble viewing an image, simply click the image to enlarge it.