次の方法で共有

クイック スタート: 新しいエージェントを作成する (プレビュー)

  • [アーティクル]

Azure AI Agents Service を使用すると、カスタム指示によってニーズに適合させ、 コード インタープリターやカスタム関数などの高度なツールによって強化された AI エージェントを作成することができます。

前提条件

Basic エージェントのセットアップのサポート

作業を開始する前に、Basic エージェントのセットアップと Standard エージェントのセットアップのどちらを実行するかを決定します。 Azure AI Foundry では、Basic エージェントのセットアップのみをサポートしています。

Basic セットアップ: エージェントは、Microsoft によるフル マネージドのマルチテナント検索リソースとストレージ リソースを使用します。 お客様がこれらの基盤となる Azure リソースの可視化や制御を行うことはできません。 Basic のセットアップは、Azure AI Foundry ポータルまたは自動 bicep テンプレートを使用して作成できます。

Standard セットアップ: エージェントは、お客様所有のシングルテナント検索リソースとストレージ リソースを使用します。 このセットアップでは、これらのリソースの完全な制御と可視化が可能ですが、使用量に基づいたコストをお客様が負担することになります。 Standard のセットアップの実行に使用できるのは、自動 bicep テンプレートのみです。

重要

Azure AI Foundry ポータルでサポートされるのは、現時点で Basic のセットアップのみです。 Standard エージェントのセットアップを実行する場合は、記事の上部にある他のタブを使用して、Standard エージェントの構成について確認してください。

Azure AI Foundry ポータルでハブとプロジェクトを作成する

新しいハブとプロジェクトを作成するには、リソース グループまたは既存のハブでの所有者または共同作成者のロールが必要です。 アクセス許可が理由でハブを作成できない場合は、管理者に連絡してください。

Azure AI Foundry でプロジェクトを作成するには、次の手順に従います。

  1. Azure AI Foundry に移動します。 プロジェクト内にいる場合は、ページの左上にある Azure AI Foundry を選択して、ホーム ページに移動します。

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

  3. プロジェクトの 名前 を入力します。

  4. ハブがある場合は、最近選択したハブが表示されます。

  5. 複数のハブにアクセスできる場合は、ドロップダウンから別のハブを選択できます。

  6. 新しく作成する場合は、[新しいハブの作成] を選択し、名前を指定します。 既定値をカスタマイズする場合は、Azure AI Foundry のドキュメントを参照してください。

    [プロジェクトの作成] ダイアログ内のプロジェクトの詳細ページのスクリーンショット。

  7. ［作成］ を選択します

モデルをデプロイする

  1. Azure AI Foundry にサインインします。

  2. ご自分のプロジェクトに移動するか、Azure AI Foundry で新しいプロジェクトを作成します。

  3. プロジェクトの概要から、[Build and customize] (ビルドおよびカスタマイズ) の下にある [エージェント] を選択します。

  4. Azure OpenAI リソースを選択します。

    [エージェント] の初期画面のスクリーンショット。

  5. 使用するエージェントのモデル デプロイを選択します。 それがない場合、新しいモデルをデプロイするための画面が開きます。 そうでない場合は、[Deploy a model] (モデルのデプロイ) を選択できます。

    モデルの選択画面のスクリーンショット。

    選択可能なモデルのスクリーンショット。

エージェント プレイグラウンドを使用する

エージェント プレイグラウンドを使用すると、コードを実行する必要なく、エージェントの探索、プロタイプ作成、テストを行うことができます。 このページから、新しいアイデアを簡単に反復して、実験できます。

  1. [Create and debug your agents] (エージェントの作成とデバッグ) 画面で、エージェントを作成するか [新しいエージェント] を使用して新たに作成します。 右側の [設定] ペインでは、パラメーターとツールを変更できます。

    必要に応じて、エージェントに対して生成されたもの以外の名前を付け、パフォーマンスの向上に役立つ指示を追加できます。 エージェントに対し、実行する内容とその方法について明確な指示を与えます。 具体的なタスク、それらの順序、さらにトーンやエンゲージメント スタイルなどの特別な指示を含めます。

    [Create and debug your agents] (エージェントの作成とデバッグ) 画面のスクリーンショット。

    ヒント

    エージェントでは、その機能 (たとえば、Bing を使用した Web の検索、コードの実行などを行う機能) を拡張する、コード インタープリターなどの複数のツールにアクセスできます。 [設定] ペインで、[knowledge] (ナレッジ) と [アクション] までスクロール ダウンし、[追加] を選択して使用可能なツールを確認します。 エージェントのツールの選択肢を示すスクリーンショット。

関連項目

エージェントで使用できるモデルを確認します。

| リファレンス ドキュメント | サンプル | ライブラリ ソース コード | パッケージ (NuGet) |

前提条件

Azure AI ハブとエージェント プロジェクトを設定する

次のセクションでは、Azure AI エージェント サービスを使い始めるために必要なリソースを設定する方法について説明します。

  1. Azure AI ハブ を作成して、アプリ環境と Azure リソースを設定します。

  2. ハブに Azure AI プロジェクトを作成すると、アプリが呼び出すエンドポイントが作成され、テナント内のリソースにアクセスするアプリ サービスが設定されます。

  3. Azure OpenAI リソースまたは Azure AI サービス リソースを接続します

Basic エージェント セットアップまたは Standard エージェント セットアップを選択する

Basic セットアップ: エージェントは、Microsoft によるフル マネージドのマルチテナント検索リソースとストレージ リソースを使用します。 お客様がこれらの基盤となる Azure リソースの可視化や制御を行うことはできません。

Standard セットアップ: エージェントは、お客様が保有するシングルテナント検索リソースとストレージ リソースを使用します。 このセットアップでは、これらのリソースの完全な制御と可視化が可能ですが、使用量に基づいたコストをお客様が負担することになります。

Note

次の自動 bicep テンプレートを使用して、Standard または Basic エージェントを実行できます。 また、Azure AI Foundry ポータルを使用して、Basic エージェントを作成することもできます。 Azure AI Foundry では現在、Standard エージェントのセットアップをサポートしていません。

説明と自動デプロイ 図 (クリックすると拡大します)
認証にマネージド ID を使う基本的なエージェントのセットアップをデプロイします。 AI ハブ、AI プロジェクト、ストレージ アカウント、AI サービスのリソースが自動的に作成されます。

AI サービス アカウントはユーザーのプロジェクトとハブに接続され、gpt-4o-mini モデルが eastus リージョンにデプロイされます。 Microsoft が管理するキー コンテナーが既定で使われます。

Azure に展開する 		Basic エージェント セットアップのアーキテクチャ図。
認証にマネージド ID を使う標準的なエージェントのセットアップをデプロイします。

AI ハブ、AI プロジェクト、キー コンテナー、ストレージ アカウント、AI サービス、AI 検索の適切なリソースが作成されます。

AI サービス、AI 検索、キー コンテナー、ストレージ アカウントがプロジェクトとハブに接続されます。 gpt-4o-mini モデルが eastus リージョンにデプロイされます。

Azure に展開する 		Standard エージェント セットアップのアーキテクチャ図。

[オプション] 自動デプロイ テンプレートでのモデルの選択

自動デプロイ テンプレートのモデル パラメーターを編集することで、エージェントで使用されるモデルをカスタマイズすることができます。 異なるモデルをデプロイするには、少なくとも modelName パラメーターと modelVersion パラメーターを更新する必要があります。

既定では、展開テンプレートは次の値で構成されます。

モデル パラメーター Default Value
modelName gpt-4o-mini
modelFormat OpenAI (Azure OpenAI 用)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

重要

modelFormat パラメーターは変更しないでください。

これらのテンプレートは、Azure OpenAI モデルのデプロイのみをサポートしています。 どの Azure OpenAI モデルがサポートされているかは、「Azure AI エージェント サービス モデルのサポート」ドキュメントを参照してください。

[省略可能] エージェントのセットアップ時に独自のリソースを使用する

Note

既存の AI サービスまたは Azure OpenAI リソースを使用する場合、モデルはデプロイされません。 モデルは、エージェントのセットアップ完了後にリソースにデプロイできます。

既存の AI サービス、Azure OpenAI、AI 検索、Azure Blob Storage リソースを使用するには、パラメーター ファイルに完全な arm リソース ID を指定します。

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

既存の Azure OpenAI リソースを使用する場合は、パラメーター ファイル内の aiServiceAccountResourceId および aiServiceKind パラメーターを更新する必要があります。 aiServiceKind パラメーターは AzureOpenAI に設定する必要があります。

詳細については、独自のリソースを使用する方法に関する記事を参照してください。

エージェントを構成して実行する

コンポーネント 説明
エージェント AI モデルをツールと組み合わせて使うカスタム AI。
ツール エージェントが会話中に確実かつ正確に応答する機能を拡張するのに役立つツール。 ユーザー定義のナレッジ ベースに接続してモデルに基盤となる知識を提供したり、Web 検索によって最新の情報を提供したりします。
Thread エージェントとユーザーの間の会話セッション。 スレッドはメッセージを格納し、コンテンツをモデルのコンテキストに合わせるために切り捨てを自動的に処理します。
メッセージ エージェントまたはユーザーによって作成されたメッセージ。 メッセージにはテキスト、画像、その他のファイルを含めることができます。 メッセージはスレッド上にリストとして格納されます。
[ファイル名を指定して実行] スレッドの内容に基づいて実行を開始するエージェントのアクティブ化。 エージェントは、その構成とスレッドのメッセージを使い、モデルとツールを呼び出してタスクを実行します。 実行の一部として、エージェントはスレッドにメッセージを追加します。
実行ステップ エージェントが実行の一部として行ったステップの詳細なリスト。 エージェントは、実行中にツールの呼び出しやメッセージの作成を行えます。 実行ステップを調べると、エージェントがどのように結果に到達したかを把握できます。

.NET パッケージをプロジェクトにインストールします。 たとえば、.NET CLI を使用する場合は、次のコマンドを実行します。

dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

次に、API 要求を認証してプログラムを実行するために、az login コマンドを使用して Azure サブスクリプションにサインインします。

az login

次のコードを使用して、エージェントを作成し実行します。 このコードを実行するには、プロジェクトの情報を用いて接続文字列を作成する必要があります。 この文字列の形式は次のとおりです。

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

ヒント

接続文字列は、Azure AI Foundry ポータルのプロジェクトの [プロジェクトの詳細]>[プロジェクトの接続文字列] にある [概要] でも確認できます。 Azure AI Foundry ポータルで接続文字列が表示されているスクリーンショット。

discovery_url に移動し、先頭の https:// と末尾の /discovery を削除すれば HostName がわかります。 discovery_url を検索するには、次の CLI コマンドを実行します。

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

たとえば、次のような接続文字列になります。

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

この接続文字列を PROJECT_CONNECTION_STRING という名前の環境変数として設定します。

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

#nullable disable

using Azure.Identity;

namespace Azure.AI.Projects.Tests;

public class Sample_Agent
{
    static async Task Main()
    {
        var connectionString = Environment.GetEnvironmentVariable("PROJECT_CONNECTION_STRING");

        AgentsClient client = new AgentsClient(connectionString, new DefaultAzureCredential());

        // Step 1: Create an agent
        Response<Agent> agentResponse = await client.CreateAgentAsync(
            model: "gpt-4o-mini",
            name: "My Agent",
            instructions: "You are a helpful agent.",
            tools: new List<ToolDefinition> { new CodeInterpreterToolDefinition() });
        Agent agent = agentResponse.Value;

        // Intermission: agent should now be listed

        Response<PageableList<Agent>> agentListResponse = await client.GetAgentsAsync();

        //// Step 2: Create a thread
        Response<AgentThread> threadResponse = await client.CreateThreadAsync();
        AgentThread thread = threadResponse.Value;

        // Step 3: Add a message to a thread
        Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
            thread.Id,
            MessageRole.User,
            "I need to solve the equation `3x + 11 = 14`. Can you help me?");
        ThreadMessage message = messageResponse.Value;

        // Intermission: message is now correlated with thread
        // Intermission: listing messages will retrieve the message just added

        Response<PageableList<ThreadMessage>> messagesListResponse = await client.GetMessagesAsync(thread.Id);
        //Assert.That(messagesListResponse.Value.Data[0].Id == message.Id);

        // Step 4: Run the agent
        Response<ThreadRun> runResponse = await client.CreateRunAsync(
            thread.Id,
            agent.Id,
            additionalInstructions: "");
        ThreadRun run = runResponse.Value;

        do
        {
            await Task.Delay(TimeSpan.FromMilliseconds(500));
            runResponse = await client.GetRunAsync(thread.Id, runResponse.Value.Id);
        }
        while (runResponse.Value.Status == RunStatus.Queued
            || runResponse.Value.Status == RunStatus.InProgress);

        Response<PageableList<ThreadMessage>> afterRunMessagesResponse
            = await client.GetMessagesAsync(thread.Id);
        IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;

        // Note: messages iterate from newest to oldest, with the messages[0] being the most recent
        foreach (ThreadMessage threadMessage in messages)
        {
            Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
            foreach (MessageContent contentItem in threadMessage.ContentItems)
            {
                if (contentItem is MessageTextContent textItem)
                {
                    Console.Write(textItem.Text);
                }
                else if (contentItem is MessageImageFileContent imageFileItem)
                {
                    Console.Write($"<image from ID: {imageFileItem.FileId}");
                }
                Console.WriteLine();
            }
        }
    }
}

| リファレンス ドキュメント | サンプル | ライブラリ ソース コード | パッケージ (PyPi) |

前提条件

Azure AI ハブとエージェント プロジェクトを設定する

次のセクションでは、Azure AI エージェント サービスを使い始めるために必要なリソースを設定する方法について説明します。

  1. Azure AI ハブ を作成して、アプリ環境と Azure リソースを設定します。

  2. ハブに Azure AI プロジェクトを作成すると、アプリが呼び出すエンドポイントが作成され、テナント内のリソースにアクセスするアプリ サービスが設定されます。

  3. Azure OpenAI リソースまたは Azure AI サービス リソースを接続します

Basic エージェント セットアップまたは Standard エージェント セットアップを選択する

Basic セットアップ: エージェントは、Microsoft によるフル マネージドのマルチテナント検索リソースとストレージ リソースを使用します。 お客様がこれらの基盤となる Azure リソースの可視化や制御を行うことはできません。

Standard セットアップ: エージェントは、お客様が保有するシングルテナント検索リソースとストレージ リソースを使用します。 このセットアップでは、これらのリソースの完全な制御と可視化が可能ですが、使用量に基づいたコストをお客様が負担することになります。

Note

次の自動 bicep テンプレートを使用して、Standard または Basic エージェントを実行できます。 また、Azure AI Foundry ポータルを使用して、Basic エージェントを作成することもできます。 Azure AI Foundry では現在、Standard エージェントのセットアップをサポートしていません。

説明と自動デプロイ 図 (クリックすると拡大します)
認証にマネージド ID を使う基本的なエージェントのセットアップをデプロイします。 AI ハブ、AI プロジェクト、ストレージ アカウント、AI サービスのリソースが自動的に作成されます。

AI サービス アカウントはユーザーのプロジェクトとハブに接続され、gpt-4o-mini モデルが eastus リージョンにデプロイされます。 Microsoft が管理するキー コンテナーが既定で使われます。

Azure に展開する 		Basic エージェント セットアップのアーキテクチャ図。
認証にマネージド ID を使う標準的なエージェントのセットアップをデプロイします。

AI ハブ、AI プロジェクト、キー コンテナー、ストレージ アカウント、AI サービス、AI 検索の適切なリソースが作成されます。

AI サービス、AI 検索、キー コンテナー、ストレージ アカウントがプロジェクトとハブに接続されます。 gpt-4o-mini モデルが eastus リージョンにデプロイされます。

Azure に展開する 		Standard エージェント セットアップのアーキテクチャ図。

[オプション] 自動デプロイ テンプレートでのモデルの選択

自動デプロイ テンプレートのモデル パラメーターを編集することで、エージェントで使用されるモデルをカスタマイズすることができます。 異なるモデルをデプロイするには、少なくとも modelName パラメーターと modelVersion パラメーターを更新する必要があります。

既定では、展開テンプレートは次の値で構成されます。

モデル パラメーター Default Value
modelName gpt-4o-mini
modelFormat OpenAI (Azure OpenAI 用)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

重要

modelFormat パラメーターは変更しないでください。

これらのテンプレートは、Azure OpenAI モデルのデプロイのみをサポートしています。 どの Azure OpenAI モデルがサポートされているかは、「Azure AI エージェント サービス モデルのサポート」ドキュメントを参照してください。

[省略可能] エージェントのセットアップ時に独自のリソースを使用する

Note

既存の AI サービスまたは Azure OpenAI リソースを使用する場合、モデルはデプロイされません。 モデルは、エージェントのセットアップ完了後にリソースにデプロイできます。

既存の AI サービス、Azure OpenAI、AI 検索、Azure Blob Storage リソースを使用するには、パラメーター ファイルに完全な arm リソース ID を指定します。

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

既存の Azure OpenAI リソースを使用する場合は、パラメーター ファイル内の aiServiceAccountResourceId および aiServiceKind パラメーターを更新する必要があります。 aiServiceKind パラメーターは AzureOpenAI に設定する必要があります。

詳細については、独自のリソースを使用する方法に関する記事を参照してください。

エージェントを構成して実行する

コンポーネント 説明
エージェント AI モデルをツールと組み合わせて使うカスタム AI。
ツール エージェントが会話中に確実かつ正確に応答する機能を拡張するのに役立つツール。 ユーザー定義のナレッジ ベースに接続してモデルに基盤となる知識を提供したり、Web 検索によって最新の情報を提供したりします。
Thread エージェントとユーザーの間の会話セッション。 スレッドはメッセージを格納し、コンテンツをモデルのコンテキストに合わせるために切り捨てを自動的に処理します。
メッセージ エージェントまたはユーザーによって作成されたメッセージ。 メッセージにはテキスト、画像、その他のファイルを含めることができます。 メッセージはスレッド上にリストとして格納されます。
[ファイル名を指定して実行] スレッドの内容に基づいて実行を開始するエージェントのアクティブ化。 エージェントは、その構成とスレッドのメッセージを使い、モデルとツールを呼び出してタスクを実行します。 実行の一部として、エージェントはスレッドにメッセージを追加します。
実行ステップ エージェントが実行の一部として行ったステップの詳細なリスト。 エージェントは、実行中にツールの呼び出しやメッセージの作成を行えます。 実行ステップを調べると、エージェントがどのように結果に到達したかを把握できます。

次のコマンドを実行して、Python パッケージをインストールします。

pip install azure-ai-projects
pip install azure-identity

次に、API 要求を認証してプログラムを実行するために、az login コマンドを使用して Azure サブスクリプションにサインインします。

az login

次のコードを使用して、エージェントを作成し実行します。 このコードを実行するには、プロジェクトの情報を用いて接続文字列を作成する必要があります。 この文字列の形式は次のとおりです。

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

ヒント

接続文字列は、Azure AI Foundry ポータルのプロジェクトの [プロジェクトの詳細]>[プロジェクトの接続文字列] にある [概要] でも確認できます。 Azure AI Foundry ポータルで接続文字列が表示されているスクリーンショット。

discovery_url に移動し、先頭の https:// と末尾の /discovery を削除すれば HostName がわかります。 discovery_url を検索するには、次の CLI コマンドを実行します。

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

たとえば、次のような接続文字列になります。

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

この接続文字列を PROJECT_CONNECTION_STRING という名前の環境変数として設定します。

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import CodeInterpreterTool
from azure.identity import DefaultAzureCredential
from typing import Any
from pathlib import Path

# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>"
# HostName can be found by navigating to your discovery_url and removing the leading "https://" and trailing "/discovery"
# To find your discovery_url, run the CLI command: az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
# Project Connection example: eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(), conn_str=os.environ["PROJECT_CONNECTION_STRING"]
)

with project_client:
    # Create an instance of the CodeInterpreterTool
    code_interpreter = CodeInterpreterTool()

    # The CodeInterpreterTool needs to be included in creation of the agent
    agent = project_client.agents.create_agent(
        model="gpt-4o-mini",
        name="my-agent",
        instructions="You are helpful agent",
        tools=code_interpreter.definitions,
        tool_resources=code_interpreter.resources,
    )
    print(f"Created agent, agent ID: {agent.id}")

    # Create a thread
    thread = project_client.agents.create_thread()
    print(f"Created thread, thread ID: {thread.id}")

    # Create a message
    message = project_client.agents.create_message(
        thread_id=thread.id,
        role="user",
        content="Could you please create a bar chart for the operating profit using the following data and provide the file to me? Company A: $1.2 million, Company B: $2.5 million, Company C: $3.0 million, Company D: $1.8 million",
    )
    print(f"Created message, message ID: {message.id}")

    # Run the agent
    run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
    print(f"Run finished with status: {run.status}")

    if run.status == "failed":
        # Check if you got "Rate limit is exceeded.", then you want to get more quota
        print(f"Run failed: {run.last_error}")

    # Get messages from the thread
    messages = project_client.agents.list_messages(thread_id=thread.id)
    print(f"Messages: {messages}")

    # Get the last message from the sender
    last_msg = messages.get_last_text_message_by_role("assistant")
    if last_msg:
        print(f"Last Message: {last_msg.text.value}")

    # Generate an image file for the bar chart
    for image_content in messages.image_contents:
        print(f"Image File ID: {image_content.image_file.file_id}")
        file_name = f"{image_content.image_file.file_id}_image_file.png"
        project_client.agents.save_file(file_id=image_content.image_file.file_id, file_name=file_name)
        print(f"Saved image file to: {Path.cwd() / file_name}")

    # Print the file path(s) from the messages
    for file_path_annotation in messages.file_path_annotations:
        print(f"File Paths:")
        print(f"Type: {file_path_annotation.type}")
        print(f"Text: {file_path_annotation.text}")
        print(f"File ID: {file_path_annotation.file_path.file_id}")
        print(f"Start Index: {file_path_annotation.start_index}")
        print(f"End Index: {file_path_annotation.end_index}")
        project_client.agents.save_file(file_id=file_path_annotation.file_path.file_id, file_name=Path(file_path_annotation.text).name)

    # Delete the agent once done
    project_client.agents.delete_agent(agent.id)
    print("Deleted agent")

| リファレンス ドキュメント | ライブラリのソース コード | パッケージ (PyPi) |

前提条件

  • Azure サブスクリプション。無料で作成できます。
  • Python 3.8 以降
  • Azure AI 開発者の RBAC ロール が適切なレベルで割り当てられていることを確認する。
  • Azure AI サービス リソースを使用するには、Cognitive Services OpenAI ユーザー ロールが割り当てられている必要があります。
  • Azure CLI と 機械学習の拡張機能がインストールされている。 既に CLI がインストールされている場合は、最新のバージョンに更新されていることを確認する。

Azure AI ハブとエージェント プロジェクトを設定する

次のセクションでは、Azure AI エージェント サービスを使い始めるために必要なリソースを設定する方法について説明します。

  1. Azure AI ハブ を作成して、アプリ環境と Azure リソースを設定します。

  2. ハブに Azure AI プロジェクトを作成すると、アプリが呼び出すエンドポイントが作成され、テナント内のリソースにアクセスするアプリ サービスが設定されます。

  3. Azure OpenAI リソースまたは Azure AI サービス リソースを接続します

Basic エージェント セットアップまたは Standard エージェント セットアップを選択する

Basic セットアップ: エージェントは、Microsoft によるフル マネージドのマルチテナント検索リソースとストレージ リソースを使用します。 お客様がこれらの基盤となる Azure リソースの可視化や制御を行うことはできません。

Standard セットアップ: エージェントは、お客様が保有するシングルテナント検索リソースとストレージ リソースを使用します。 このセットアップでは、これらのリソースの完全な制御と可視化が可能ですが、使用量に基づいたコストをお客様が負担することになります。

Note

次の自動 bicep テンプレートを使用して、Standard または Basic エージェントを実行できます。 また、Azure AI Foundry ポータルを使用して、Basic エージェントを作成することもできます。 Azure AI Foundry では現在、Standard エージェントのセットアップをサポートしていません。

説明と自動デプロイ 図 (クリックすると拡大します)
認証にマネージド ID を使う基本的なエージェントのセットアップをデプロイします。 AI ハブ、AI プロジェクト、ストレージ アカウント、AI サービスのリソースが自動的に作成されます。

AI サービス アカウントはユーザーのプロジェクトとハブに接続され、gpt-4o-mini モデルが eastus リージョンにデプロイされます。 Microsoft が管理するキー コンテナーが既定で使われます。

Azure に展開する 		Basic エージェント セットアップのアーキテクチャ図。
認証にマネージド ID を使う標準的なエージェントのセットアップをデプロイします。

AI ハブ、AI プロジェクト、キー コンテナー、ストレージ アカウント、AI サービス、AI 検索の適切なリソースが作成されます。

AI サービス、AI 検索、キー コンテナー、ストレージ アカウントがプロジェクトとハブに接続されます。 gpt-4o-mini モデルが eastus リージョンにデプロイされます。

Azure に展開する 		Standard エージェント セットアップのアーキテクチャ図。

[オプション] 自動デプロイ テンプレートでのモデルの選択

自動デプロイ テンプレートのモデル パラメーターを編集することで、エージェントで使用されるモデルをカスタマイズすることができます。 異なるモデルをデプロイするには、少なくとも modelName パラメーターと modelVersion パラメーターを更新する必要があります。

既定では、展開テンプレートは次の値で構成されます。

モデル パラメーター Default Value
modelName gpt-4o-mini
modelFormat OpenAI (Azure OpenAI 用)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

重要

modelFormat パラメーターは変更しないでください。

これらのテンプレートは、Azure OpenAI モデルのデプロイのみをサポートしています。 どの Azure OpenAI モデルがサポートされているかは、「Azure AI エージェント サービス モデルのサポート」ドキュメントを参照してください。

[省略可能] エージェントのセットアップ時に独自のリソースを使用する

Note

既存の AI サービスまたは Azure OpenAI リソースを使用する場合、モデルはデプロイされません。 モデルは、エージェントのセットアップ完了後にリソースにデプロイできます。

既存の AI サービス、Azure OpenAI、AI 検索、Azure Blob Storage リソースを使用するには、パラメーター ファイルに完全な arm リソース ID を指定します。

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

既存の Azure OpenAI リソースを使用する場合は、パラメーター ファイル内の aiServiceAccountResourceId および aiServiceKind パラメーターを更新する必要があります。 aiServiceKind パラメーターは AzureOpenAI に設定する必要があります。

詳細については、独自のリソースを使用する方法に関する記事を参照してください。

エージェントを構成して実行する

コンポーネント 説明
エージェント AI モデルをツールと組み合わせて使うカスタム AI。
ツール エージェントが会話中に確実かつ正確に応答する機能を拡張するのに役立つツール。 ユーザー定義のナレッジ ベースに接続してモデルに基盤となる知識を提供したり、Web 検索によって最新の情報を提供したりします。
Thread エージェントとユーザーの間の会話セッション。 スレッドはメッセージを格納し、コンテンツをモデルのコンテキストに合わせるために切り捨てを自動的に処理します。
メッセージ エージェントまたはユーザーによって作成されたメッセージ。 メッセージにはテキスト、画像、その他のファイルを含めることができます。 メッセージはスレッド上にリストとして格納されます。
[ファイル名を指定して実行] スレッドの内容に基づいて実行を開始するエージェントのアクティブ化。 エージェントは、その構成とスレッドのメッセージを使い、モデルとツールを呼び出してタスクを実行します。 実行の一部として、エージェントはスレッドにメッセージを追加します。
実行ステップ エージェントが実行の一部として行ったステップの詳細なリスト。 エージェントは、実行中にツールの呼び出しやメッセージの作成を行えます。 実行ステップを調べると、エージェントがどのように結果に到達したかを把握できます。

次のコマンドを実行して、Python パッケージをインストールします。

pip install azure-ai-projects
pip install azure-identity
pip install openai

次に、API 要求を認証してプログラムを実行するために、az login コマンドを使用して Azure サブスクリプションにサインインします。

az login

次のコードを使用して、エージェントを作成し実行します。 このコードを実行するには、プロジェクトの情報を用いて接続文字列を作成する必要があります。 この文字列の形式は次のとおりです。

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

ヒント

接続文字列は、Azure AI Foundry ポータルのプロジェクトの [プロジェクトの詳細]>[プロジェクトの接続文字列] にある [概要] でも確認できます。 Azure AI Foundry ポータルで接続文字列が表示されているスクリーンショット。

discovery_url に移動し、先頭の https:// と末尾の /discovery を削除すれば HostName がわかります。 discovery_url を検索するには、次の CLI コマンドを実行します。

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

たとえば、次のような接続文字列になります。

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

この接続文字列を PROJECT_CONNECTION_STRING という名前の環境変数として設定します。

import os, time
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from openai import AzureOpenAI


with AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
) as project_client:

    # Explicit type hinting for IntelliSense
    client: AzureOpenAI = project_client.inference.get_azure_openai_client(
        # The latest API version is 2024-10-01-preview
        api_version = os.environ.get("AZURE_OPENAI_API_VERSION"),
    )

    with client:
        agent = client.beta.assistants.create(
            model="gpt-4o-mini", name="my-agent", instructions="You are a helpful agent"
        )
        print(f"Created agent, agent ID: {agent.id}")

        thread = client.beta.threads.create()
        print(f"Created thread, thread ID: {thread.id}")

        message = client.beta.threads.messages.create(thread_id=thread.id, role="user", content="Hello, tell me a joke")
        print(f"Created message, message ID: {message.id}")

        run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=agent.id)

        # Poll the run while run status is queued or in progress
        while run.status in ["queued", "in_progress", "requires_action"]:
            time.sleep(1)  # Wait for a second
            run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
            print(f"Run status: {run.status}")

        client.beta.assistants.delete(agent.id)
        print("Deleted agent")

        messages = client.beta.threads.messages.list(thread_id=thread.id)
        print(f"Messages: {messages}")

| リファレンス ドキュメント | サンプル | ライブラリ ソース コード | パッケージ (npm) |

前提条件

Azure AI ハブとエージェント プロジェクトを設定する

次のセクションでは、Azure AI エージェント サービスを使い始めるために必要なリソースを設定する方法について説明します。

  1. Azure AI ハブ を作成して、アプリ環境と Azure リソースを設定します。

  2. ハブに Azure AI プロジェクトを作成すると、アプリが呼び出すエンドポイントが作成され、テナント内のリソースにアクセスするアプリ サービスが設定されます。

  3. Azure OpenAI リソースまたは Azure AI サービス リソースを接続します

Basic エージェント セットアップまたは Standard エージェント セットアップを選択する

Basic セットアップ: エージェントは、Microsoft によるフル マネージドのマルチテナント検索リソースとストレージ リソースを使用します。 お客様がこれらの基盤となる Azure リソースの可視化や制御を行うことはできません。

Standard セットアップ: エージェントは、お客様が保有するシングルテナント検索リソースとストレージ リソースを使用します。 このセットアップでは、これらのリソースの完全な制御と可視化が可能ですが、使用量に基づいたコストをお客様が負担することになります。

Note

次の自動 bicep テンプレートを使用して、Standard または Basic エージェントを実行できます。 また、Azure AI Foundry ポータルを使用して、Basic エージェントを作成することもできます。 Azure AI Foundry では現在、Standard エージェントのセットアップをサポートしていません。

説明と自動デプロイ 図 (クリックすると拡大します)
認証にマネージド ID を使う基本的なエージェントのセットアップをデプロイします。 AI ハブ、AI プロジェクト、ストレージ アカウント、AI サービスのリソースが自動的に作成されます。

AI サービス アカウントはユーザーのプロジェクトとハブに接続され、gpt-4o-mini モデルが eastus リージョンにデプロイされます。 Microsoft が管理するキー コンテナーが既定で使われます。

Azure に展開する 		Basic エージェント セットアップのアーキテクチャ図。
認証にマネージド ID を使う標準的なエージェントのセットアップをデプロイします。

AI ハブ、AI プロジェクト、キー コンテナー、ストレージ アカウント、AI サービス、AI 検索の適切なリソースが作成されます。

AI サービス、AI 検索、キー コンテナー、ストレージ アカウントがプロジェクトとハブに接続されます。 gpt-4o-mini モデルが eastus リージョンにデプロイされます。

Azure に展開する 		Standard エージェント セットアップのアーキテクチャ図。

[オプション] 自動デプロイ テンプレートでのモデルの選択

自動デプロイ テンプレートのモデル パラメーターを編集することで、エージェントで使用されるモデルをカスタマイズすることができます。 異なるモデルをデプロイするには、少なくとも modelName パラメーターと modelVersion パラメーターを更新する必要があります。

既定では、展開テンプレートは次の値で構成されます。

モデル パラメーター Default Value
modelName gpt-4o-mini
modelFormat OpenAI (Azure OpenAI 用)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

重要

modelFormat パラメーターは変更しないでください。

これらのテンプレートは、Azure OpenAI モデルのデプロイのみをサポートしています。 どの Azure OpenAI モデルがサポートされているかは、「Azure AI エージェント サービス モデルのサポート」ドキュメントを参照してください。

[省略可能] エージェントのセットアップ時に独自のリソースを使用する

Note

既存の AI サービスまたは Azure OpenAI リソースを使用する場合、モデルはデプロイされません。 モデルは、エージェントのセットアップ完了後にリソースにデプロイできます。

既存の AI サービス、Azure OpenAI、AI 検索、Azure Blob Storage リソースを使用するには、パラメーター ファイルに完全な arm リソース ID を指定します。

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

既存の Azure OpenAI リソースを使用する場合は、パラメーター ファイル内の aiServiceAccountResourceId および aiServiceKind パラメーターを更新する必要があります。 aiServiceKind パラメーターは AzureOpenAI に設定する必要があります。

詳細については、独自のリソースを使用する方法に関する記事を参照してください。

エージェントを構成して実行する

コンポーネント 説明
エージェント AI モデルをツールと組み合わせて使うカスタム AI。
ツール エージェントが会話中に確実かつ正確に応答する機能を拡張するのに役立つツール。 ユーザー定義のナレッジ ベースに接続してモデルに基盤となる知識を提供したり、Web 検索によって最新の情報を提供したりします。
Thread エージェントとユーザーの間の会話セッション。 スレッドはメッセージを格納し、コンテンツをモデルのコンテキストに合わせるために切り捨てを自動的に処理します。
メッセージ エージェントまたはユーザーによって作成されたメッセージ。 メッセージにはテキスト、画像、その他のファイルを含めることができます。 メッセージはスレッド上にリストとして格納されます。
[ファイル名を指定して実行] スレッドの内容に基づいて実行を開始するエージェントのアクティブ化。 エージェントは、その構成とスレッドのメッセージを使い、モデルとツールを呼び出してタスクを実行します。 実行の一部として、エージェントはスレッドにメッセージを追加します。
実行ステップ エージェントが実行の一部として行ったステップの詳細なリスト。 エージェントは、実行中にツールの呼び出しやメッセージの作成を行えます。 実行ステップを調べると、エージェントがどのように結果に到達したかを把握できます。

次のコマンドを実行して、npm パッケージをインストールします。

npm install @azure/ai-projects
npm install @azure/identity

次に、API 要求を認証してプログラムを実行するために、az login コマンドを使用して Azure サブスクリプションにサインインします。

az login

次のコードを使用して、エージェントを作成し実行します。 このコードを実行するには、プロジェクトの情報を用いて接続文字列を作成する必要があります。 この文字列の形式は次のとおりです。

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

ヒント

接続文字列は、Azure AI Foundry ポータルのプロジェクトの [プロジェクトの詳細]>[プロジェクトの接続文字列] にある [概要] でも確認できます。 Azure AI Foundry ポータルで接続文字列が表示されているスクリーンショット。

discovery_url に移動し、先頭の https:// と末尾の /discovery を削除すれば HostName がわかります。 discovery_url を検索するには、次の CLI コマンドを実行します。

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

たとえば、次のような接続文字列になります。

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

この接続文字列を PROJECT_CONNECTION_STRING という名前の環境変数として設定します。

// index.js

import {
  AIProjectsClient,
  DoneEvent,
  ErrorEvent,
  isOutputOfType,
  MessageStreamEvent,
  RunStreamEvent,
  ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

export async function main() {
  const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
  );

  // Step 1 code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();

  // Step 2 an agent
  const agent = await client.agents.createAgent("gpt-4o-mini", {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });

  // Step 3 a thread
  const thread = await client.agents.createThread();

  // Step 4 a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
  });

  // Intermission is now correlated with thread
  // Intermission messages will retrieve the message just added

  // Step 5 the agent
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // 6. Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType(m.content[0], "text")) {
      const textContent = m.content[0];
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

  // 7. Delete the agent once done
  await client.agents.deleteAgent(agent.id);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

出力にはプロンプトと回答が含まれます。

I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).

To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\). 

Therefore, the value of \(x\) that satisfies the equation is 1. 

Let me know if you need help with anything else!
---------------------------------

| リファレンス ドキュメント | サンプル | ライブラリ ソース コード | パッケージ (npm) |

前提条件

Azure AI ハブとエージェント プロジェクトを設定する

次のセクションでは、Azure AI エージェント サービスを使い始めるために必要なリソースを設定する方法について説明します。

  1. Azure AI ハブ を作成して、アプリ環境と Azure リソースを設定します。

  2. ハブに Azure AI プロジェクトを作成すると、アプリが呼び出すエンドポイントが作成され、テナント内のリソースにアクセスするアプリ サービスが設定されます。

  3. Azure OpenAI リソースまたは Azure AI サービス リソースを接続します

Basic エージェント セットアップまたは Standard エージェント セットアップを選択する

Basic セットアップ: エージェントは、Microsoft によるフル マネージドのマルチテナント検索リソースとストレージ リソースを使用します。 お客様がこれらの基盤となる Azure リソースの可視化や制御を行うことはできません。

Standard セットアップ: エージェントは、お客様が保有するシングルテナント検索リソースとストレージ リソースを使用します。 このセットアップでは、これらのリソースの完全な制御と可視化が可能ですが、使用量に基づいたコストをお客様が負担することになります。

Note

次の自動 bicep テンプレートを使用して、Standard または Basic エージェントを実行できます。 また、Azure AI Foundry ポータルを使用して、Basic エージェントを作成することもできます。 Azure AI Foundry では現在、Standard エージェントのセットアップをサポートしていません。

説明と自動デプロイ 図 (クリックすると拡大します)
認証にマネージド ID を使う基本的なエージェントのセットアップをデプロイします。 AI ハブ、AI プロジェクト、ストレージ アカウント、AI サービスのリソースが自動的に作成されます。

AI サービス アカウントはユーザーのプロジェクトとハブに接続され、gpt-4o-mini モデルが eastus リージョンにデプロイされます。 Microsoft が管理するキー コンテナーが既定で使われます。

Azure に展開する 		Basic エージェント セットアップのアーキテクチャ図。
認証にマネージド ID を使う標準的なエージェントのセットアップをデプロイします。

AI ハブ、AI プロジェクト、キー コンテナー、ストレージ アカウント、AI サービス、AI 検索の適切なリソースが作成されます。

AI サービス、AI 検索、キー コンテナー、ストレージ アカウントがプロジェクトとハブに接続されます。 gpt-4o-mini モデルが eastus リージョンにデプロイされます。

Azure に展開する 		Standard エージェント セットアップのアーキテクチャ図。

[オプション] 自動デプロイ テンプレートでのモデルの選択

自動デプロイ テンプレートのモデル パラメーターを編集することで、エージェントで使用されるモデルをカスタマイズすることができます。 異なるモデルをデプロイするには、少なくとも modelName パラメーターと modelVersion パラメーターを更新する必要があります。

既定では、展開テンプレートは次の値で構成されます。

モデル パラメーター Default Value
modelName gpt-4o-mini
modelFormat OpenAI (Azure OpenAI 用)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

重要

modelFormat パラメーターは変更しないでください。

これらのテンプレートは、Azure OpenAI モデルのデプロイのみをサポートしています。 どの Azure OpenAI モデルがサポートされているかは、「Azure AI エージェント サービス モデルのサポート」ドキュメントを参照してください。

[省略可能] エージェントのセットアップ時に独自のリソースを使用する

Note

既存の AI サービスまたは Azure OpenAI リソースを使用する場合、モデルはデプロイされません。 モデルは、エージェントのセットアップ完了後にリソースにデプロイできます。

既存の AI サービス、Azure OpenAI、AI 検索、Azure Blob Storage リソースを使用するには、パラメーター ファイルに完全な arm リソース ID を指定します。

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

既存の Azure OpenAI リソースを使用する場合は、パラメーター ファイル内の aiServiceAccountResourceId および aiServiceKind パラメーターを更新する必要があります。 aiServiceKind パラメーターは AzureOpenAI に設定する必要があります。

詳細については、独自のリソースを使用する方法に関する記事を参照してください。

エージェントを構成して実行する

コンポーネント 説明
エージェント AI モデルをツールと組み合わせて使うカスタム AI。
ツール エージェントが会話中に確実かつ正確に応答する機能を拡張するのに役立つツール。 ユーザー定義のナレッジ ベースに接続してモデルに基盤となる知識を提供したり、Web 検索によって最新の情報を提供したりします。
Thread エージェントとユーザーの間の会話セッション。 スレッドはメッセージを格納し、コンテンツをモデルのコンテキストに合わせるために切り捨てを自動的に処理します。
メッセージ エージェントまたはユーザーによって作成されたメッセージ。 メッセージにはテキスト、画像、その他のファイルを含めることができます。 メッセージはスレッド上にリストとして格納されます。
[ファイル名を指定して実行] スレッドの内容に基づいて実行を開始するエージェントのアクティブ化。 エージェントは、その構成とスレッドのメッセージを使い、モデルとツールを呼び出してタスクを実行します。 実行の一部として、エージェントはスレッドにメッセージを追加します。
実行ステップ エージェントが実行の一部として行ったステップの詳細なリスト。 エージェントは、実行中にツールの呼び出しやメッセージの作成を行えます。 実行ステップを調べると、エージェントがどのように結果に到達したかを把握できます。

次のコマンドを実行して、npm パッケージをインストールします。

npm install @azure/ai-projects
npm install @azure/identity

次に、API 要求を認証してプログラムを実行するために、az login コマンドを使用して Azure サブスクリプションにサインインします。

az login

次のコードを使用して、エージェントを作成し実行します。 このコードを実行するには、プロジェクトの情報を用いて接続文字列を作成する必要があります。 この文字列の形式は次のとおりです。

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

ヒント

接続文字列は、Azure AI Foundry ポータルのプロジェクトの [プロジェクトの詳細]>[プロジェクトの接続文字列] にある [概要] でも確認できます。 Azure AI Foundry ポータルで接続文字列が表示されているスクリーンショット。

discovery_url に移動し、先頭の https:// と末尾の /discovery を削除すれば HostName がわかります。 discovery_url を検索するには、次の CLI コマンドを実行します。

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

たとえば、次のような接続文字列になります。

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

この接続文字列を PROJECT_CONNECTION_STRING という名前の環境変数として設定します。

// index.ts

import type {
  MessageDeltaChunk,
  MessageDeltaTextContent,
  MessageTextContentOutput,
} from "@azure/ai-projects";
import {
  AIProjectsClient,
  DoneEvent,
  ErrorEvent,
  isOutputOfType,
  MessageStreamEvent,
  RunStreamEvent,
  ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

export async function main(): Promise<void> {
  const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
  );

  // Step 1: Create code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();

  // Step 2: Create an agent
  const agent = await client.agents.createAgent("gpt-4o-mini", {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });

  // Step 3: Create a thread
  const thread = await client.agents.createThread();

  // Step 4: Add a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
  });

  // Intermission: message is now correlated with thread
  // Intermission: listing messages will retrieve the message just added

  // Step 5: Run the agent
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data as MessageDeltaChunk;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart as MessageDeltaTextContent;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // 6. Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
      const textContent = m.content[0] as MessageTextContentOutput;
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

  // 7. Delete the agent once done
  await client.agents.deleteAgent(agent.id);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

出力にはプロンプトと回答が含まれます。

I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).

To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\). 

Therefore, the value of \(x\) that satisfies the equation is 1. 

Let me know if you need help with anything else!
---------------------------------

| リファレンス ドキュメント |

前提条件

  • Azure サブスクリプション。無料で作成できます。
  • Azure AI 開発者の RBAC ロール が適切なレベルで割り当てられていることを確認する。
  • Azure AI サービス リソースを使用するには、Cognitive Services OpenAI ユーザー ロールが割り当てられている必要があります。
  • Azure CLI と 機械学習の拡張機能がインストールされている。 既に CLI がインストールされている場合は、最新のバージョンに更新されていることを確認する。

Azure AI ハブとエージェント プロジェクトを設定する

次のセクションでは、Azure AI エージェント サービスを使い始めるために必要なリソースを設定する方法について説明します。

  1. Azure AI ハブ を作成して、アプリ環境と Azure リソースを設定します。

  2. ハブに Azure AI プロジェクトを作成すると、アプリが呼び出すエンドポイントが作成され、テナント内のリソースにアクセスするアプリ サービスが設定されます。

  3. Azure OpenAI リソースまたは Azure AI サービス リソースを接続します

Basic エージェント セットアップまたは Standard エージェント セットアップを選択する

Basic セットアップ: エージェントは、Microsoft によるフル マネージドのマルチテナント検索リソースとストレージ リソースを使用します。 お客様がこれらの基盤となる Azure リソースの可視化や制御を行うことはできません。

Standard セットアップ: エージェントは、お客様が保有するシングルテナント検索リソースとストレージ リソースを使用します。 このセットアップでは、これらのリソースの完全な制御と可視化が可能ですが、使用量に基づいたコストをお客様が負担することになります。

Note

次の自動 bicep テンプレートを使用して、Standard または Basic エージェントを実行できます。 また、Azure AI Foundry ポータルを使用して、Basic エージェントを作成することもできます。 Azure AI Foundry では現在、Standard エージェントのセットアップをサポートしていません。

説明と自動デプロイ 図 (クリックすると拡大します)
認証にマネージド ID を使う基本的なエージェントのセットアップをデプロイします。 AI ハブ、AI プロジェクト、ストレージ アカウント、AI サービスのリソースが自動的に作成されます。

AI サービス アカウントはユーザーのプロジェクトとハブに接続され、gpt-4o-mini モデルが eastus リージョンにデプロイされます。 Microsoft が管理するキー コンテナーが既定で使われます。

Azure に展開する 		Basic エージェント セットアップのアーキテクチャ図。
認証にマネージド ID を使う標準的なエージェントのセットアップをデプロイします。

AI ハブ、AI プロジェクト、キー コンテナー、ストレージ アカウント、AI サービス、AI 検索の適切なリソースが作成されます。

AI サービス、AI 検索、キー コンテナー、ストレージ アカウントがプロジェクトとハブに接続されます。 gpt-4o-mini モデルが eastus リージョンにデプロイされます。

Azure に展開する 		Standard エージェント セットアップのアーキテクチャ図。

[オプション] 自動デプロイ テンプレートでのモデルの選択

自動デプロイ テンプレートのモデル パラメーターを編集することで、エージェントで使用されるモデルをカスタマイズすることができます。 異なるモデルをデプロイするには、少なくとも modelName パラメーターと modelVersion パラメーターを更新する必要があります。

既定では、展開テンプレートは次の値で構成されます。

モデル パラメーター Default Value
modelName gpt-4o-mini
modelFormat OpenAI (Azure OpenAI 用)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

重要

modelFormat パラメーターは変更しないでください。

これらのテンプレートは、Azure OpenAI モデルのデプロイのみをサポートしています。 どの Azure OpenAI モデルがサポートされているかは、「Azure AI エージェント サービス モデルのサポート」ドキュメントを参照してください。

[省略可能] エージェントのセットアップ時に独自のリソースを使用する

Note

既存の AI サービスまたは Azure OpenAI リソースを使用する場合、モデルはデプロイされません。 モデルは、エージェントのセットアップ完了後にリソースにデプロイできます。

既存の AI サービス、Azure OpenAI、AI 検索、Azure Blob Storage リソースを使用するには、パラメーター ファイルに完全な arm リソース ID を指定します。

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

既存の Azure OpenAI リソースを使用する場合は、パラメーター ファイル内の aiServiceAccountResourceId および aiServiceKind パラメーターを更新する必要があります。 aiServiceKind パラメーターは AzureOpenAI に設定する必要があります。

詳細については、独自のリソースを使用する方法に関する記事を参照してください。

エージェントを構成して実行する

コンポーネント 説明
エージェント AI モデルをツールと組み合わせて使うカスタム AI。
ツール エージェントが会話中に確実かつ正確に応答する機能を拡張するのに役立つツール。 ユーザー定義のナレッジ ベースに接続してモデルに基盤となる知識を提供したり、Web 検索によって最新の情報を提供したりします。
Thread エージェントとユーザーの間の会話セッション。 スレッドはメッセージを格納し、コンテンツをモデルのコンテキストに合わせるために切り捨てを自動的に処理します。
メッセージ エージェントまたはユーザーによって作成されたメッセージ。 メッセージにはテキスト、画像、その他のファイルを含めることができます。 メッセージはスレッド上にリストとして格納されます。
[ファイル名を指定して実行] スレッドの内容に基づいて実行を開始するエージェントのアクティブ化。 エージェントは、その構成とスレッドのメッセージを使い、モデルとツールを呼び出してタスクを実行します。 実行の一部として、エージェントはスレッドにメッセージを追加します。
実行ステップ エージェントが実行の一部として行ったステップの詳細なリスト。 エージェントは、実行中にツールの呼び出しやメッセージの作成を行えます。 実行ステップを調べると、エージェントがどのように結果に到達したかを把握できます。

API 要求を認証するために、az login コマンドを使用して Azure サブスクリプションにサインインします。

az login

次に、API 呼び出しに対する認可として提供する Entra ID トークンをフェッチする必要があります。 トークンのフェッチには次の CLI コマンドを使用します。

az account get-access-token --resource 'https://ml.azure.com/' | jq -r .accessToken | tr -d '"'

このアクセス トークンを AZURE_AI_AGENTS_TOKEN という名前の環境変数として設定します。

Azure AI Agents Service への REST API 呼び出しを正常に行うには、以下のようにエンドポイントを使用する必要があります。

https://<HostName>/agents/v1.0/subscriptions/<AzureSubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.MachineLearningServices/workspaces/<ProjectName>

discovery_url に移動し、先頭の https:// と末尾の /discovery を削除すれば HostName がわかります。 discovery_url を検索するには、次の CLI コマンドを実行します。

az ml workspace show -n {project_name} --subscription {subscription_name} --resource-group {resource_group_name} --query discovery_url

たとえば、エンドポイントは次のようになります。

https://eastus.api.azureml.ms/agents/v1.0/subscriptions/12345678-abcd-1234-abcd-123456789000/resourceGroups/my-resource-group/providers/Microsoft.MachineLearningServices/workspaces/my-project-name

このエンドポイントを AZURE_AI_AGENTS_ENDPOINT という名前の環境変数として設定します。

エージェントを作成する

Note

Azure AI Agents Service では、model パラメーターにモデル デプロイ名が必要です。 モデル デプロイ名が基になるモデルの名前と異なる場合は、コードを "model": "{your-custom-model-deployment-name}" に調整します。

curl $AZURE_AI_AGENTS_ENDPOINT/assistants?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a helpful agent.",
    "name": "my-agent",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4o-mini"
  }'

スレッドを作成する

curl $AZURE_AI_AGENTS_ENDPOINT/threads?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

ユーザーの質問をスレッドに追加する

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

スレッドを実行する

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

実行の状態を取得する

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

エージェントの応答を取得する

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"