Bagikan melalui

Mulai cepat: Membuat agen baru

Note

Dokumen ini mengacu pada portal Microsoft Foundry (klasik ).

šŸ” Lihat dokumentasi Microsoft Foundry (baru) untuk mempelajari tentang portal baru.

Note

Panduan cepat ini diperuntukkan bagi versi agen sebelumnya. Lihat panduan mulai cepat untuk Microsoft Foundry untuk menggunakan versi baru API tersebut.

Foundry Agent Service memungkinkan Anda membuat agen AI yang disesuaikan dengan kebutuhan Anda melalui instruksi kustom dan ditambah oleh alat canggih seperti penerjemah kode, dan fungsi kustom.

Prerequisites

  • Langganan Azure - Buat langganan gratis.
  • Pastikan bahwa individu yang membuat akun dan proyek memiliki peran Pemilik Akun Azure AI di cakupan langganan, yang akan memberikan izin yang diperlukan untuk membuat proyek
    • Atau, memiliki peran Kontributor atau Kontributor Cognitive Services di tingkat langganan akan memungkinkan pembuatan proyek
  • Setelah proyek dibuat, pastikan bahwa individu yang membuat agen dalam proyek memiliki peran Pengguna Azure AI di tingkat proyek

Important

Portal Microsoft Foundry hanya mendukung penyiapan agen dasar saat ini. Jika Anda ingin melakukan penyiapan agen standar, lihat artikel Penyiapan lingkungan untuk mempelajari selengkapnya.

Membuat akun dan proyek Foundry di portal Foundry

Untuk membuat akun dan proyek di Foundry, ikuti langkah-langkah berikut:

  1. Pergi ke Foundry. Jika Anda berada dalam proyek, pilih Foundry di kiri atas halaman untuk masuk ke halaman Beranda.

  2. Gunakan alur pembuatan agen pemula untuk pengalaman tercepat. Klik Buat Agen.

    Cuplikan layar portal Foundry.

  3. Masukkan nama untuk proyek tersebut. Jika Anda ingin menyesuaikan nilai default, pilih Opsi tingkat lanjut.

    Cuplikan layar opsi tingkat lanjut untuk membuat proyek.

  4. Pilih Buat.

  5. Tunggu hingga sumber daya Anda diprovisikan.

    1. Akun dan proyek (sumber daya anak akun Anda) akan dibuat.
    2. Model gpt-4o akan secara otomatis disebarkan
    3. Agen default akan dibuat

  6. Setelah selesai, Anda akan mendarat langsung di taman bermain agen dan Anda dapat mulai membuat agen. Anda dapat memberikan instruksi agen Anda tentang apa yang harus dilakukan dan cara melakukannya. Misalnya: "Anda adalah agen bermanfaat yang dapat menjawab pertanyaan tentang geografi." Kemudian Anda dapat mulai mengobrol dengan agen Anda.

    Cuplikan layar taman bermain agen.

    Note

    Jika Anda mendapatkan kesalahan izin saat mencoba mengonfigurasi atau membuat agen, pastikan Anda memiliki Pengguna Azure AI pada proyek.

| Dokumentasi referensi | Contoh | Kode sumber pustaka | Paket (NuGet) |

Prerequisites

  • Menyiapkan lingkungan agen
  • Tetapkan peran RBACPengguna Azure AI untuk setiap anggota tim yang perlu membuat atau mengedit agen menggunakan SDK atau Agent Playground
    • Peran ini harus ditetapkan pada cakupan proyek
    • Izin minimum yang diperlukan: agents/*/read, agents/*/action, agents/*/delete

Mengonfigurasi dan menjalankan agen

Buat proyek Konsol .NET.

dotnet new console

Instal paket .NET ke proyek Anda. Misalnya jika Anda menggunakan .NET CLI, jalankan perintah berikut.

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

Selanjutnya, untuk mengautentikasi permintaan API Anda dan menjalankan program, gunakan perintah az login untuk masuk ke langganan Azure Anda.

az login

Gunakan kode berikut untuk membuat dan menjalankan agen. Untuk menjalankan kode ini, Anda harus mendapatkan titik akhir untuk proyek Anda. String ini dalam format:

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

Important

Mulai Mei 2025, Azure AI Agent Service menggunakan titik akhir untuk proyek Foundry alih-alih string koneksi yang sebelumnya digunakan untuk proyek berbasis hub. Jika Anda menggunakan proyek berbasis hub, Anda tidak akan dapat menggunakan versi SDK dan REST API saat ini. Untuk informasi selengkapnya, lihat Penggunaan SDK dengan proyek berbasis hub.

Anda dapat menemukan titik akhir Anda di gambaran umum untuk proyek Anda di portal Microsoft Foundry, di bawah Pustaka>Foundry.

Cuplikan layar memperlihatkan titik akhir di portal Foundry.

Atur titik akhir ini dalam variabel lingkungan bernama ProjectEndpoint.

Anda juga memerlukan nama penyebaran model Anda. Anda dapat menemukannya di Model + Titik Akhir di menu navigasi kiri.

Sebuah cuplikan layar memperlihatkan layar portal Foundry untuk penyebaran model.

Simpan nama penyebaran model Anda sebagai variabel lingkungan bernama ModelDeploymentName.

using Azure;
using Azure.AI.Agents.Persistent;
using Azure.Identity;
using System.Diagnostics;

var projectEndpoint = System.Environment.GetEnvironmentVariable("ProjectEndpoint");
var modelDeploymentName = System.Environment.GetEnvironmentVariable("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 begin 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;
        }
    }
}

//If you want to delete your agent, uncomment the following lines:
//client.Threads.DeleteThread(threadId: thread.Id);
//client.Administration.DeleteAgent(agentId: agent.Id);

| Referensi dokumentasi | Sampel | Kode sumber pustaka | Paket (PyPi) |

Prerequisites

  • Menyiapkan lingkungan agen
  • Tetapkan peran RBACPengguna Azure AI untuk setiap anggota tim yang perlu membuat atau mengedit agen menggunakan SDK atau Agent Playground
    • Peran ini harus ditetapkan pada cakupan proyek
    • Izin minimum yang diperlukan: agents/*/read, agents/*/action, agents/*/delete

Mengonfigurasi dan menjalankan agen

Jalankan perintah berikut untuk menginstal paket python.

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

Selanjutnya, untuk mengautentikasi permintaan API Anda dan menjalankan program, gunakan perintah az login untuk masuk ke langganan Azure Anda.

az login

Gunakan kode berikut untuk membuat dan menjalankan agen. Untuk menjalankan kode ini, Anda harus mendapatkan titik akhir untuk proyek Anda. String ini dalam format:

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

Important

Mulai Mei 2025, Azure AI Agent Service menggunakan titik akhir untuk proyek Foundry alih-alih string koneksi yang sebelumnya digunakan untuk proyek berbasis hub. Jika Anda menggunakan proyek berbasis hub, Anda tidak akan dapat menggunakan versi SDK dan REST API saat ini. Untuk informasi selengkapnya, lihat Penggunaan SDK dengan proyek berbasis hub.

Anda dapat menemukan titik akhir Anda di gambaran umum untuk proyek Anda di portal Microsoft Foundry, di bawah Pustaka>Foundry.

Cuplikan layar memperlihatkan titik akhir di portal Foundry.

Atur titik akhir ini sebagai variabel lingkungan bernama PROJECT_ENDPOINT.

Anda juga memerlukan nama penyebaran model Anda. Anda dapat menemukannya di Model + Titik Akhir di menu navigasi kiri.

Sebuah cuplikan layar memperlihatkan layar portal Foundry untuk penyebaran model.

Simpan nama penyebaran model Anda sebagai variabel lingkungan bernama MODEL_DEPLOYMENT_NAME.

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

# Create an AIProjectClient instance
project_client = AIProjectClient(
    endpoint=os.getenv("PROJECT_ENDPOINT"),
    credential=DefaultAzureCredential(),  
    # Use Azure Default Credential for authentication
)

with project_client:

    code_interpreter = CodeInterpreterTool()

    agent = project_client.agents.create_agent(
        model=os.getenv("MODEL_DEPLOYMENT_NAME"),  # Model deployment name
        name="my-agent",  # Name of the agent
        instructions="""You politely help with math questions. 
        Use the Code Interpreter tool when asked to visualize numbers.""",  
        # Instructions for the agent
        tools=code_interpreter.definitions,  # Attach the tool
        tool_resources=code_interpreter.resources,  # Attach tool resources
    )
    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}")

    question = """Draw a graph for a line with a slope of 4 
    and y-intercept of 9 and provide the file to me?"""

    # Add a message to the thread
    message = project_client.agents.messages.create(
        thread_id=thread.id,
        role="user",  # Role of the message sender
        content=question,  # 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,
        additional_instructions="""Please address the user as Jane Doe.
        The user has a premium account.""",
    )

    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)
    print(f"Messages: {messages}")

    for message in messages:
        print(f"Role: {message.role}, Content: {message.content}")
        for this_content in message.content:
            print(f"Content Type: {this_content.type}, Content Data: {this_content}")
            if this_content.text.annotations:
                for annotation in this_content.text.annotations:
                    print(f"Annotation Type: {annotation.type}, Text: {annotation.text}")
                    print(f"Start Index: {annotation.start_index}")
                    print(f"End Index: {annotation.end_index}")
                    print(f"File ID: {annotation.file_path.file_id}")
                    # Save every image file in the message
                    file_id = annotation.file_path.file_id
                    file_name = f"{file_id}_image_file.png"
                    project_client.agents.files.save(file_id=file_id, file_name=file_name)
                    print(f"Saved image file to: {Path.cwd() / file_name}")
    #Uncomment these lines to delete the agent when done
    #project_client.agents.delete_agent(agent.id)
    #print("Deleted agent")

| Dokumentasi referensi | Contoh | Kode sumber pustaka | Paket (npm) |

Prerequisites

  • Menyiapkan lingkungan agen
  • Tetapkan peran RBACPengguna Azure AI untuk setiap anggota tim yang perlu membuat atau mengedit agen menggunakan SDK atau Agent Playground
    • Peran ini harus ditetapkan pada cakupan proyek
    • Izin minimum yang diperlukan: agents/*/read, agents/*/action, agents/*/delete

Mengonfigurasi dan menjalankan agen

Objek kunci dalam kode ini meliputi:

Pertama, inisialisasi proyek TypeScript baru dengan menjalankan:

npm init -y
npm pkg set type="module"

Jalankan perintah berikut untuk menginstal paket npm yang diperlukan.

npm install @azure/ai-agents @azure/identity
npm install @types/node typescript --save-dev

Selanjutnya, untuk mengautentikasi permintaan API Anda dan menjalankan program, gunakan perintah az login untuk masuk ke langganan Azure Anda.

az login

Gunakan kode berikut untuk menjawab pertanyaan I need to solve the equation '3x + 11 = 14'. Can you help me?matematika . Untuk menjalankan kode ini, Anda harus mendapatkan titik akhir untuk proyek Anda. String ini dalam format:

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

Anda dapat menemukan titik akhir Anda di gambaran umum untuk proyek Anda di portal Microsoft Foundry, di bawah Pustaka>Foundry.

Cuplikan layar memperlihatkan titik akhir di portal Foundry.

Atur titik akhir ini sebagai variabel lingkungan bernama PROJECT_ENDPOINT dalam .env file.

Anda juga memerlukan nama penyebaran model Anda. Anda dapat menemukannya di Model + Titik Akhir di menu navigasi kiri.

Sebuah cuplikan layar memperlihatkan layar portal Foundry untuk penyebaran model.

Simpan nama penyebaran model Anda sebagai variabel lingkungan bernama MODEL_DEPLOYMENT_NAME.

Important

  • Kode mulai cepat ini menggunakan variabel lingkungan untuk konfigurasi sensitif. Jangan pernah mengunggah file .env Anda ke kontrol versi dengan memastikan bahwa .env tercatat dalam file .gitignore Anda.
  • Ingat: Jika Anda secara tidak sengaja mengunggah informasi sensitif, anggap kredensial tersebut sudah disusupi dan segera ubah.

Buat file tsconfig.json dengan konten berikut:

{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "types": ["node"],
    "lib": ["esnext"],
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "strict": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true,
  }
}

Selanjutnya, buat index.ts file dan tempelkan dalam kode berikut:

import { AgentsClient } from "@azure/ai-agents";
import { DefaultAzureCredential } from "@azure/identity";

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());

  // Create an agent
  const agent = await client.createAgent(modelDeploymentName, {
    name: "my-agent",
    instructions: "You are a helpful agent specialized in math. When providing mathematical explanations, use plain text formatting with simple characters like +, -, *, / for operations. Do not use LaTeX formatting with backslashes or special notation. Make your explanations clear and easy to read in a terminal.",
  });
  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}`);

  // List all threads for the agent
  const threads = client.threads.list();
  console.log(`Threads for agent ${agent.id}:`);
  for await (const t of threads) {
    console.log(`Thread ID: ${t.id} created at: ${t.createdAt}`);
  }

  // Create a message
  const message = await client.messages.create(thread.id, "user", "I need to solve the equation `3x + 11 = 14`. Can you help me?");
  console.log(`Created message, message ID : ${message.id}`);

  // Create and poll a run
  console.log("Creating run...");
  const run = await client.runs.createAndPoll(thread.id, agent.id, {
    pollingOptions: {
      intervalInMs: 2000,
    },
    onResponse: (response): void => {
      const parsedBody =
        typeof response.parsedBody === "object" && response.parsedBody !== null
          ? response.parsedBody
          : null;
      const status = parsedBody && "status" in parsedBody ? parsedBody.status : "unknown";
      console.log(`Received response with status: ${status}`);
    },
  });
  console.log(`Run finished with status: ${run.status}`);

  const messagesIterator = client.messages.list(thread.id);
  console.log("\n\n========================================================");
  console.log("=================== CONVERSATION RESULTS ===================");
  console.log("========================================================\n");
  
  // Collect all messages first
  const messages = [];
  for await (const m of messagesIterator) {
    messages.push(m);
  }
  
  // Reverse the order of messages (or sort by timestamp if available)
  messages.reverse();
  
  // Display messages in the new order
  for (const m of messages) {
    if (m.role === "user") {
      console.log(`\nā“ USER QUESTION: ${
        Array.isArray(m.content) && m.content[0]?.type === "text" && 'text' in m.content[0]
          ? m.content[0].text.value
          : JSON.stringify(m.content)
      }`);
    } else if (m.role === "assistant") {
      console.log("\nšŸ¤– ASSISTANT'S ANSWER:");
      console.log("--------------------------------------------------");
      
      // Extract and print the text content in a more readable format
      if (m.content && Array.isArray(m.content)) {
        for (const content of m.content) {
          if (content.type === "text" && 'text' in content) {
            console.log(content.text?.value);
          } else {
            console.log(content);
          }
        }
      } else {
        console.log(JSON.stringify(m.content, null, 2));
      }
      console.log("--------------------------------------------------\n");
    }
  }
  
  console.log("\n========================================================");
  console.log("====================== END OF RESULTS ======================");
  console.log("========================================================\n");

  // Clean up
  await client.threads.delete(thread.id);
  await client.deleteAgent(agent.id);
}

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

Jalankan kode menggunakan npx tsx -r dotenv/config index.ts. Kode ini menjawab pertanyaan I need to solve the equation '3x + 11 = 14'. Can you help me?. Respons tidak deterministik, output Anda akan terlihat mirip dengan output di bawah ini:

Created agent, agent ID : asst_X4yDNWrdWKb8LN0SQ6xlzhWk
Created thread, thread ID : thread_TxqZcHL2BqkNWl9dFzBYMIU6
Threads for agent asst_X4yDNWrdWKb8LN0SQ6xlzhWk:
...
Created message, message ID : msg_R0zDsXdc2UbfsNXvS1zeS6hk
Creating run...
Received response with status: queued
Received response with status: in_progress
Received response with status: completed
Run finished with status: completed


========================================================
=================== CONVERSATION RESULTS ===================
========================================================


ā“ USER QUESTION: I need to solve the equation `3x + 11 = 14`. Can you help me?

šŸ¤– ASSISTANT'S ANSWER:
--------------------------------------------------
Certainly! Let's solve the equation step by step:

We have:
3x + 11 = 14

### Step 1: Eliminate the constant (+11) on the left-hand side.
Subtract 11 from both sides:
3x + 11 - 11 = 14 - 11
This simplifies to:
3x = 3

We have:
3x + 11 = 14

### Step 1: Eliminate the constant (+11) on the left-hand side.
Subtract 11 from both sides:
3x + 11 - 11 = 14 - 11
This simplifies to:
3x = 3

### Step 2: Solve for x.
Divide both sides by 3:
3x / 3 = 3 / 3
This simplifies to:
x = 1

### Final Answer:
x = 1
--------------------------------------------------


========================================================
====================== END OF RESULTS ======================
========================================================

Sampel lengkap kode sumber tersedia.

| Dokumentasi referensi | Sampel | Kode | sumber pustakaPaket (Maven) |

Prerequisites

  • Menyiapkan lingkungan agen
  • Tetapkan peran RBACPengguna Azure AI untuk setiap anggota tim yang perlu membuat atau mengedit agen menggunakan SDK atau Agent Playground
    • Peran ini harus ditetapkan pada cakupan proyek
    • Izin minimum yang diperlukan: agents/*/read, agents/*/action, agents/*/delete

Mengonfigurasi dan menjalankan agen

Pertama, buat proyek konsol Java Baru. Anda akan memerlukan dependensi berikut untuk menjalankan kode:

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-ai-agents-persistent</artifactId>
        <version>1.0.0-beta.2</version>
    </dependency>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-identity</artifactId>
        <version>1.17.0-beta.1</version>
    </dependency>
</dependencies>

Selanjutnya, untuk mengautentikasi permintaan API Anda dan menjalankan program, gunakan perintah az login untuk masuk ke langganan Azure Anda.

az login

Gunakan kode berikut untuk membuat dan menjalankan agen. Untuk menjalankan kode ini, Anda harus mendapatkan titik akhir untuk proyek Anda. String ini dalam format:

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

Important

Mulai Mei 2025, Azure AI Agent Service menggunakan titik akhir untuk proyek Foundry alih-alih string koneksi yang sebelumnya digunakan untuk proyek berbasis hub. Jika Anda menggunakan proyek berbasis hub, Anda tidak akan dapat menggunakan versi SDK dan REST API saat ini. Untuk informasi selengkapnya, lihat Penggunaan SDK dengan proyek berbasis hub.

Anda dapat menemukan titik akhir Anda di gambaran umum untuk proyek Anda di portal Microsoft Foundry, di bawah Pustaka>Foundry.

Cuplikan layar memperlihatkan titik akhir di portal Foundry.

Atur titik akhir ini dalam variabel lingkungan bernama PROJECT_ENDPOINT.

Anda juga memerlukan nama penyebaran model Anda. Anda dapat menemukannya di Model + Titik Akhir di menu navigasi kiri.

Sebuah cuplikan layar memperlihatkan layar portal Foundry untuk penyebaran model.

Simpan nama penyebaran model Anda sebagai variabel lingkungan bernama MODEL_DEPLOYMENT_NAME.

Contoh kode

package com.example.agents;

import com.azure.ai.agents.persistent.MessagesClient;
import com.azure.ai.agents.persistent.PersistentAgentsAdministrationClient;
import com.azure.ai.agents.persistent.PersistentAgentsClient;
import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;
import com.azure.ai.agents.persistent.RunsClient;
import com.azure.ai.agents.persistent.ThreadsClient;
import com.azure.ai.agents.persistent.models.CodeInterpreterToolDefinition;
import com.azure.ai.agents.persistent.models.CreateAgentOptions;
import com.azure.ai.agents.persistent.models.CreateRunOptions;
import com.azure.ai.agents.persistent.models.MessageImageFileContent;
import com.azure.ai.agents.persistent.models.MessageRole;
import com.azure.ai.agents.persistent.models.MessageTextContent;
import com.azure.ai.agents.persistent.models.PersistentAgent;
import com.azure.ai.agents.persistent.models.PersistentAgentThread;
import com.azure.ai.agents.persistent.models.RunStatus;
import com.azure.ai.agents.persistent.models.ThreadMessage;
import com.azure.ai.agents.persistent.models.ThreadRun;
import com.azure.ai.agents.persistent.models.MessageContent;
import com.azure.core.http.rest.PagedIterable;
import com.azure.identity.DefaultAzureCredentialBuilder;
import java.util.Arrays;

public class AgentSample {

    public static void main(String[] args) {
        // variables for authenticating requests to the agent service 
        String projectEndpoint = System.getenv("PROJECT_ENDPOINT");
        String modelName = System.getenv("MODEL_DEPLOYMENT_NAME");

        // initialize clients to manage various aspects of agent runtime
        PersistentAgentsClientBuilder clientBuilder = new PersistentAgentsClientBuilder()
            .endpoint(projectEndpoint)
            .credential(new DefaultAzureCredentialBuilder().build());
        PersistentAgentsClient agentsClient = clientBuilder.buildClient();
        PersistentAgentsAdministrationClient administrationClient = agentsClient.getPersistentAgentsAdministrationClient();
        ThreadsClient threadsClient = agentsClient.getThreadsClient();
        MessagesClient messagesClient = agentsClient.getMessagesClient();
        RunsClient runsClient = agentsClient.getRunsClient();
        
        
        String agentName = "my-agent"; // the name of the agent
        CreateAgentOptions createAgentOptions = new CreateAgentOptions(modelName)
            .setName(agentName)
            .setInstructions("You are a helpful agent") // system insturctions
            .setTools(Arrays.asList(new CodeInterpreterToolDefinition()));
        PersistentAgent agent = administrationClient.createAgent(createAgentOptions);

        PersistentAgentThread thread = threadsClient.createThread();
        ThreadMessage createdMessage = messagesClient.createMessage(
            thread.getId(),
            MessageRole.USER,
            "I need to solve the equation `3x + 11 = 14`. Can you help me?"); // The message to the agent

        try {
            //run the agent
            CreateRunOptions createRunOptions = new CreateRunOptions(thread.getId(), agent.getId())
                .setAdditionalInstructions("");
            ThreadRun threadRun = runsClient.createRun(createRunOptions);
            // wait for the run to complete before printing the message
            waitForRunCompletion(thread.getId(), threadRun, runsClient);
            printRunMessages(messagesClient, thread.getId());
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        } finally {
            //cleanup - uncomment these lines if you want to delete the agent
            //threadsClient.deleteThread(thread.getId());
            //administrationClient.deleteAgent(agent.getId());
        }
    }

    // A helper function to print messages from the agent
    public static void printRunMessages(MessagesClient messagesClient, String threadId) {

        PagedIterable<ThreadMessage> runMessages = messagesClient.listMessages(threadId);
        for (ThreadMessage message : runMessages) {
            System.out.print(String.format("%1$s - %2$s : ", message.getCreatedAt(), message.getRole()));
            for (MessageContent contentItem : message.getContent()) {
                if (contentItem instanceof MessageTextContent) {
                    System.out.print((((MessageTextContent) contentItem).getText().getValue()));
                } else if (contentItem instanceof MessageImageFileContent) {
                    String imageFileId = (((MessageImageFileContent) contentItem).getImageFile().getFileId());
                    System.out.print("Image from ID: " + imageFileId);
                }
                System.out.println();
            }
        }
    }

    // a helper function to wait until a run has completed running
    public static void waitForRunCompletion(String threadId, ThreadRun threadRun, RunsClient runsClient)
        throws InterruptedException {

        do {
            Thread.sleep(500);
            threadRun = runsClient.getRun(threadId, threadRun.getId());
        }
        while (
            threadRun.getStatus() == RunStatus.QUEUED
                || threadRun.getStatus() == RunStatus.IN_PROGRESS
                || threadRun.getStatus() == RunStatus.REQUIRES_ACTION);

        if (threadRun.getStatus() == RunStatus.FAILED) {
            System.out.println(threadRun.getLastError().getMessage());
        }
    }
}

| Dokumentasi rujukan |

Prerequisites

  • Menyiapkan lingkungan agen
  • Tetapkan peran RBACPengguna Azure AI untuk setiap anggota tim yang perlu membuat atau mengedit agen menggunakan SDK atau Agent Playground
    • Peran ini harus ditetapkan pada cakupan proyek
    • Izin minimum yang diperlukan: agents/*/read, agents/*/action, agents/*/delete

Mengonfigurasi dan menjalankan agen

Untuk mengautentikasi permintaan API Anda, gunakan perintah az login untuk masuk ke langganan Azure Anda.

az login

Selanjutnya, Anda harus mengambil token ID Entra untuk diberikan sebagai otorisasi ke panggilan API. Ambil token menggunakan perintah CLI:

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

Atur token akses sebagai variabel lingkungan bernama AGENT_TOKEN.

Agar berhasil melakukan panggilan REST API ke Foundry Agent Service, Anda harus menggunakan titik akhir proyek Anda:

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

Misalnya, titik akhir Anda akan terlihat seperti:

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

Atur titik akhir ini sebagai variabel lingkungan bernama AZURE_AI_FOUNDRY_PROJECT_ENDPOINT.

Note

  • Untuk api-version parameter, versi GA API adalah 2025-05-01 dan versi API pratinjau terbaru adalah 2025-05-15-preview. Anda harus menggunakan API pratinjau untuk alat yang sedang dalam pratinjau.
  • Pertimbangkan untuk menjadikan versi API Anda sebagai variabel lingkungan, seperti $API_VERSION.

Membuat agen

Note

Dengan layanan Azure AI Agents model parameter memerlukan nama penyebaran model. Jika nama penyebaran model Anda berbeda dari nama model yang mendasar, maka Anda akan menyesuaikan kode Anda dengan "model": "{your-custom-model-deployment-name}".

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"
  }'

Buat utas

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 ''

Tambahkan pertanyaan pengguna ke topik

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?"
    }'

Jalankan thread

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",
  }'

Mengambil status proses

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"

Dapatkan respons agen

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

Langkah selanjutnya

Pelajari tentang alat yang dapat Anda gunakan untuk memperluas kemampuan agen Anda, seperti mengakses web, memberikan informasi dasar, dan banyak lagi.

  • Last updated on