クイック スタート: 新しいエージェントを作成する

[前提条件]

• Azure サブスクリプション。無料で作成できます。
• アカウントとプロジェクトを作成する個々のユーザーが、サブスクリプション スコープで Azure AI アカウント所有者 ロールを持っていることを確認します
  • または、サブスクリプション レベルで 共同作成者 ロールまたは Cognitive Services 共同作成者 ロールを持つことも、この要件を満たします。

Azure AI Foundry ポータルで Foundry アカウントとプロジェクトを作成する

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

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

2. 動作を最速にするために、エージェントの概要作成フローを使用します。 [ エージェントの作成] をクリックします。

   

3. プロジェクトの名前を入力します。 既定値をカスタマイズする場合は、[ 詳細オプション] を選択します。

   

4. を選択してを作成します。

5. リソースがプロビジョニングされるまで待ちます。

   1. アカウントとプロジェクト (アカウントの子リソース) が作成されます。
   2. gpt-4o モデルが自動的にデプロイされます
   3. 既定のエージェントが作成されます

6. 完了すると、エージェントのプレイグラウンドに直接着陸し、エージェントの作成を開始できます。

   

   注

   エージェントを構成または作成しようとしたときにアクセス許可エラーが発生する場合は、プロジェクトに Azure AI ユーザー があることを確認します。

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

[前提条件]

• エージェント環境のセットアップ
• SDK または Agent Playground を使用してエージェントを作成または編集する必要がある各チーム メンバーに Azure AI ユーザーRBAC ロール を割り当てる
  • このロールはプロジェクト スコープで割り当てる必要があります
  • 最低限必要なアクセス許可: agents/*/read、 agents/*/action、 agents/*/delete

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

.NET コンソール プロジェクトを作成します。

dotnet new console

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

dotnet add package Azure.AI.Agents.Persistent
dotnet add package Azure.Identity

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

az login

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

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

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

https://myresource.services.ai.azure.com/api/projects/myproject

このエンドポイントを、 ProjectEndpointという名前の appsetting 変数に設定します。

using Azure;
using Azure.AI.Agents.Persistent;
using Azure.Identity;
using Microsoft.Extensions.Configuration;
using System.Diagnostics;

IConfigurationRoot configuration = new ConfigurationBuilder()
    .SetBasePath(AppContext.BaseDirectory)
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .Build();

var projectEndpoint = configuration["ProjectEndpoint"];
var modelDeploymentName = configuration["ModelDeploymentName"];

//Create a PersistentAgentsClient and PersistentAgent.
PersistentAgentsClient client = new(projectEndpoint, new DefaultAzureCredential());

//Give PersistentAgent a tool to execute code using CodeInterpreterToolDefinition.
PersistentAgent agent = client.Administration.CreateAgent(
    model: modelDeploymentName,
    name: "My Test Agent",
    instructions: "You politely help with math questions. Use the code interpreter tool when asked to visualize numbers.",
    tools: [new CodeInterpreterToolDefinition()]
);

//Create a thread to establish a session between Agent and a User.
PersistentAgentThread thread = client.Threads.CreateThread();

//Ask a question of the Agent.
client.Messages.CreateMessage(
    thread.Id,
    MessageRole.User,
    "Hi, Agent! Draw a graph for a line with a slope of 4 and y-intercept of 9.");

//Have Agent beging processing user's question with some additional instructions associated with the ThreadRun.
ThreadRun run = client.Runs.CreateRun(
    thread.Id,
    agent.Id,
    additionalInstructions: "Please address the user as Jane Doe. The user has a premium account.");

//Poll for completion.
do
{
    Thread.Sleep(TimeSpan.FromMilliseconds(500));
    run = client.Runs.GetRun(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued
    || run.Status == RunStatus.InProgress
    || run.Status == RunStatus.RequiresAction);

//Get the messages in the PersistentAgentThread. Includes Agent (Assistant Role) and User (User Role) messages.
Pageable<PersistentThreadMessage> messages = client.Messages.GetMessages(
    threadId: thread.Id,
    order: ListSortOrder.Ascending);

//Display each message and open the image generated using CodeInterpreterToolDefinition.
foreach (PersistentThreadMessage threadMessage in messages)
{
    foreach (MessageContent content in threadMessage.ContentItems)
    {
        switch (content)
        {
            case MessageTextContent textItem:
                Console.WriteLine($"[{threadMessage.Role}]: {textItem.Text}");
                break;
            case MessageImageFileContent imageFileContent:
                Console.WriteLine($"[{threadMessage.Role}]: Image content file ID = {imageFileContent.FileId}");
                BinaryData imageContent = client.Files.GetFileContent(imageFileContent.FileId);
                string tempFilePath = Path.Combine(AppContext.BaseDirectory, $"{Guid.NewGuid()}.png");
                File.WriteAllBytes(tempFilePath, imageContent.ToArray());
                client.Files.DeleteFile(imageFileContent.FileId);

                ProcessStartInfo psi = new()
                {
                    FileName = tempFilePath,
                    UseShellExecute = true
                };
                Process.Start(psi);
                break;
        }
    }
}

//Clean up test resources.
client.Threads.DeleteThread(threadId: thread.Id);
client.Administration.DeleteAgent(agentId: agent.Id);

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

[前提条件]

• エージェント環境のセットアップ
• SDK または Agent Playground を使用してエージェントを作成または編集する必要がある各チーム メンバーに Azure AI ユーザーRBAC ロール を割り当てる
  • このロールはプロジェクト スコープで割り当てる必要があります
  • 最低限必要なアクセス許可: agents/*/read、 agents/*/action、 agents/*/delete

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

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

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

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

az login

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

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

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

https://myresource.services.ai.azure.com/api/projects/myproject

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

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import CodeInterpreterTool

# Create an Azure AI Client from an endpoint, copied from your Azure AI Foundry project.
# You need to login to Azure subscription via Azure CLI and set the environment variables
project_endpoint = os.environ["PROJECT_ENDPOINT"]  # Ensure the PROJECT_ENDPOINT environment variable is set

# Create an AIProjectClient instance
project_client = AIProjectClient(
    endpoint=project_endpoint,
    credential=DefaultAzureCredential(),  # Use Azure Default Credential for authentication
)

code_interpreter = CodeInterpreterTool()
with project_client:
    # Create an agent with the Bing Grounding tool
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],  # Model deployment name
        name="my-agent",  # Name of the agent
        instructions="You are a helpful agent",  # Instructions for the agent
        tools=code_interpreter.definitions,  # Attach the tool
    )
    print(f"Created agent, ID: {agent.id}")

    # Create a thread for communication
    thread = project_client.agents.threads.create()
    print(f"Created thread, ID: {thread.id}")
    
    # Add a message to the thread
    message = project_client.agents.messages.create(
        thread_id=thread.id,
        role="user",  # Role of the message sender
        content="What is the weather in Seattle today?",  # Message content
    )
    print(f"Created message, ID: {message['id']}")
    
    # Create and process an agent run
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
    print(f"Run finished with status: {run.status}")
    
    # Check if the run failed
    if run.status == "failed":
        print(f"Run failed: {run.last_error}")
    
    # Fetch and log all messages
    messages = project_client.agents.messages.list(thread_id=thread.id)
    for message in messages:
        print(f"Role: {message.role}, Content: {message.content}")
    
    # Delete the agent when done
    project_client.agents.delete_agent(agent.id)
    print("Deleted agent")

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

[前提条件]

• エージェント環境のセットアップ
• SDK または Agent Playground を使用してエージェントを作成または編集する必要がある各チーム メンバーに Azure AI ユーザーRBAC ロール を割り当てる
  • このロールはプロジェクト スコープで割り当てる必要があります
  • 最低限必要なアクセス許可: agents/*/read、 agents/*/action、 agents/*/delete

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

このコードの主なオブジェクトは次のとおりです。

• AgentsClient
• ToolUtility

まず、次を実行して新しいプロジェクトを初期化します。

npm init -y

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

npm install @azure/ai-agents @azure/identity
npm install dotenv

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

az login

次のコードを使用して、 データの CSV ファイル をアップロードし、そのデータから棒グラフを生成するエージェントを作成して実行します。 このコードを実行するには、プロジェクトのエンドポイントを取得する必要があります。 この文字列の形式は次のとおりです。

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

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

https://myresource.services.ai.azure.com/api/projects/myproject

このエンドポイントを、PROJECT_ENDPOINT ファイル内の .env という名前の環境変数として設定します。

次に、 index.js ファイルを作成し、次のコードを貼り付けます。

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

/**
 * This sample demonstrates how to use agent operations with code interpreter from the Azure Agents service.
 *
 * @summary demonstrates how to use agent operations with code interpreter.
 */
// @ts-nocheck
import type {
  MessageDeltaChunk,
  MessageDeltaTextContent,
  MessageImageFileContent,
  MessageTextContent,
  ThreadRun,
} from "@azure/ai-agents";
import {
  RunStreamEvent,
  MessageStreamEvent,
  DoneEvent,
  ErrorEvent,
  AgentsClient,
  isOutputOfType,
  ToolUtility,
} from "@azure/ai-agents";
import { DefaultAzureCredential } from "@azure/identity";

import * as fs from "fs";
import path from "node:path";
import "dotenv/config";

const projectEndpoint = process.env["PROJECT_ENDPOINT"] || "<project endpoint>";
const modelDeploymentName = process.env["MODEL_DEPLOYMENT_NAME"] || "gpt-4o";

export async function main(): Promise<void> {
  // Create an Azure AI Client
  const client = new AgentsClient(projectEndpoint, new DefaultAzureCredential());

  // Upload file and wait for it to be processed
  const filePath = "./data/nifty500QuarterlyResults.csv";
  const localFileStream = fs.createReadStream(filePath);
  const localFile = await client.files.upload(localFileStream, "assistants", {
    fileName: "myLocalFile",
  });

  console.log(`Uploaded local file, file ID : ${localFile.id}`);

  // Create code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool([localFile.id]);

  // Notice that CodeInterpreter must be enabled in the agent creation, otherwise the agent will not be able to see the file attachment
  const agent = await client.createAgent(modelDeploymentName, {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });
  console.log(`Created agent, agent ID: ${agent.id}`);

  // Create a thread
  const thread = await client.threads.create();
  console.log(`Created thread, thread ID: ${thread.id}`);

  // Create a message
  const message = await client.messages.create(
    thread.id,
    "user",
    "Could you please create a bar chart in the TRANSPORTATION sector for the operating profit from the uploaded CSV file and provide the file to me?",
  );

  console.log(`Created message, message ID: ${message.id}`);

  // Create and execute a run
  const streamEventMessages = await client.runs.create(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        console.log(`ThreadRun status: ${(eventMessage.data as ThreadRun).status}`);
        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";
              console.log(`Text delta received:: ${textValue}`);
            }
          });
        }
        break;

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

  // Delete the original file from the agent to free up space (note: this does not delete your version of the file)
  await client.files.delete(localFile.id);
  console.log(`Deleted file, file ID : ${localFile.id}`);

  // Print the messages from the agent
  const messagesIterator = client.messages.list(thread.id);
  const messagesArray = [];
  for await (const m of messagesIterator) {
    messagesArray.push(m);
  }
  console.log("Messages:", messagesArray);

  // Get most recent message from the assistant
// Get most recent message from the assistant
  const assistantMessage = messagesArray.find((msg) => msg.role === "assistant");
  if (assistantMessage) {
    // Look for an image file in the assistant's message
    const imageFileOutput = assistantMessage.content.find(content => 
      content.type === "image_file" && content.imageFile?.fileId);
    
    if (imageFileOutput) {
      try {
        // Save the newly created file
        console.log(`Saving new files...`);
        const imageFile = imageFileOutput.imageFile.fileId;
        const imageFileName = path.resolve(
          "./data/" + (await client.files.get(imageFile)).filename + "ImageFile.png",
        );
        console.log(`Image file name : ${imageFileName}`);

        const fileContent = await client.files.getContent(imageFile).asNodeStream();
        if (fileContent && fileContent.body) {
          const chunks = [];
          for await (const chunk of fileContent.body) {
            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
          }
          const buffer = Buffer.concat(chunks);
          fs.writeFileSync(imageFileName, buffer);
          console.log(`Successfully saved image to ${imageFileName}`);
        } else {
          console.error("No file content available in the response");
        }
      } catch (error) {
        console.error("Error saving image file:", error);
      }
    } else {
      console.log("No image file found in assistant's message");
    }
  } else {
    console.log("No assistant message found");
  }

  // Iterate through messages and print details for each annotation
  console.log(`Message Details:`);
  messagesArray.forEach((m) => {
    console.log(`File Paths:`);
    console.log(`Type: ${m.content[0].type}`);
    if (isOutputOfType<MessageTextContent>(m.content[0], "text")) {
      const textContent = m.content[0] as MessageTextContent;
      console.log(`Text: ${textContent.text.value}`);
    }
    console.log(`File ID: ${m.id}`);
    // firstId and lastId are properties of the paginator, not the messages array
    // Removing these references as they don't exist in this context
  });

  // Delete the agent once done
  await client.deleteAgent(agent.id);
  console.log(`Deleted agent, agent ID: ${agent.id}`);
}

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

node index.jsを使用してコードを実行します。 アップロードされたCSVファイルから営業利益のデータを基にTRANSPORTATIONセクター用の縦棒グラフのPNG画像ファイルを生成し、そのファイルをあなたに提供します。 完全な サンプル ソース コード を使用できます。

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

[前提条件]

• エージェント環境のセットアップ
• SDK または Agent Playground を使用してエージェントを作成または編集する必要がある各チーム メンバーに Azure AI ユーザーRBAC ロール を割り当てる
  • このロールはプロジェクト スコープで割り当てる必要があります
  • 最低限必要なアクセス許可: agents/*/read、 agents/*/action、 agents/*/delete

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

API 呼び出し情報

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

az login

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

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

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

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

https://<your_ai_service_name>.services.ai.azure.com/api/projects/<your_project_name>

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

https://exampleaiservice.services.ai.azure.com/api/projects/project

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

エージェントを作成する

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_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 --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

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

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

スレッドを実行する

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

実行の状態を取得する

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN"

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

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN"