Delen via

Quickstart: Een nieuwe agent maken

Note

Dit document verwijst naar de Microsoft Foundry-portal (klassiek).

šŸ” Bekijk de documentatie van Microsoft Foundry (nieuw) voor meer informatie over de nieuwe portal.

Note

Deze quickstart is bedoeld voor de vorige versie van agents. Zie de quickstart voor Microsoft Foundry om de nieuwe versie van de API te gebruiken.

Met Foundry Agent Service kunt u AI-agents maken die zijn afgestemd op uw behoeften via aangepaste instructies en uitgebreid met geavanceerde hulpprogramma's zoals code-interpreter en aangepaste functies.

Prerequisites

  • Een Azure-abonnement: maak er gratis een.
  • Zorg ervoor dat de persoon die het account en project maakt, de rol Azure AI-accounteigenaar heeft voor het abonnementsbereik, waarmee de benodigde machtigingen worden verleend voor het maken van het project
    • Als u de rol Bijdrager of Cognitive Services-bijdrager op abonnementsniveau hebt, kan het project ook worden gemaakt.
  • Zodra het project is gemaakt, moet u ervoor zorgen dat de persoon die de agent binnen het project maakt, de Azure AI-gebruikersrol heeft op projectniveau

Important

De Microsoft Foundry-portal biedt momenteel alleen ondersteuning voor het instellen van de basisagent. Als u een standaardagentinstallatie wilt uitvoeren, raadpleegt u het artikel Omgevingsinstellingen voor meer informatie.

Een Foundry-account en -project maken in Foundry Portal

Voer de volgende stappen uit om een account en project te maken in Foundry:

  1. Ga naar Foundry. Als u zich in een project bevindt, selecteert u Foundry linksboven op de pagina om naar de startpagina te gaan.

  2. Gebruik de stroom 'Aan de slag met het maken van agents' voor de snelste ervaring. Klik op Een agent maken.

    Een screenshot van de Foundry-portal.

  3. Voer een naam in voor het project. Als u de standaardwaarden wilt aanpassen, selecteert u Geavanceerde opties.

    Een schermopname van de geavanceerde opties voor het maken van een project.

  4. Klik op Creƫren.

  5. Wacht totdat uw middelen zijn ingericht.

    1. Er wordt een account en project (onderliggende resource van uw account) gemaakt.
    2. Het gpt-4o-model wordt automatisch geĆÆmplementeerd
    3. Er wordt een standaardagent gemaakt

  6. Zodra dit is voltooid, komt u rechtstreeks in de agentspeelplaats terecht en kunt u beginnen met het maken van agents. U kunt uw agent instructies geven over wat u moet doen en hoe u dit doet. Bijvoorbeeld: 'U bent een nuttige agent die vragen over geografie kan beantwoorden'. Vervolgens kunt u chatten met uw agent.

    Schermopname van de agentspeelplaats.

    Note

    Als u een machtigingsfout krijgt bij het configureren of maken van agents, zorgt u ervoor dat u de Azure AI-gebruiker in het project hebt.

| Referentiedocumentatie | Voorbeelden | Bibliotheek broncode | Pakket (NuGet) |

Prerequisites

  • Een agentomgeving instellen
  • Wijs de RBAC-rolvan de Azure AI-gebruiker toe aan elk teamlid dat agents moet maken of bewerken met behulp van de SDK of Agent Playground
    • Deze rol moet worden toegewezen binnen de projectscope
    • Minimale benodigde autorisaties: agents/*/read, agents/*/action, agents/*/delete

Een agent configureren en uitvoeren

Maak een .NET Console-project.

dotnet new console

Installeer het .NET-pakket in uw project. Als u bijvoorbeeld de .NET CLI gebruikt, voert u de volgende opdracht uit.

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

Als u vervolgens uw API-aanvragen wilt verifiƫren en het programma wilt uitvoeren, gebruikt u de opdracht az login om u aan te melden bij uw Azure-abonnement.

az login

Gebruik de volgende code om een agent te maken en uit te voeren. Als u deze code wilt uitvoeren, moet u het eindpunt voor uw project ophalen. Deze tekenreeks is in de volgende indeling:

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

Important

Vanaf mei 2025 gebruikt de Azure AI Agent Service een eindpunt voor Foundry-projecten in plaats van de verbindingsreeks die eerder is gebruikt voor hubprojecten. Als u een hubproject gebruikt, kunt u de huidige versies van de SDK en REST API niet gebruiken. Zie SDK-gebruik met hubprojecten voor meer informatie.

U vindt uw eindpunt in het overzicht van uw project in de Microsoft Foundry-portal, onder Libraries>Foundry.

Een schermopname van het eindpunt in de Foundry-portal.

Stel dit eindpunt in een omgevingsvariabele met de naam ProjectEndpoint.

U hebt ook de implementatienaam van uw model nodig. U vindt deze in Modellen en eindpunten in het navigatiemenu aan de linkerkant.

Een schermopname van het scherm voor modelimplementatie in de Foundry-portal.

Sla de naam van uw modelimplementatienaam op als een omgevingsvariabele met de naam 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);

| Referentiedocumentatie | Samples | Library source code | Package (PyPi) |

Prerequisites

  • Een agentomgeving instellen
  • Wijs de RBAC-rolvan de Azure AI-gebruiker toe aan elk teamlid dat agents moet maken of bewerken met behulp van de SDK of Agent Playground
    • Deze rol moet worden toegewezen binnen de projectscope
    • Minimale benodigde autorisaties: agents/*/read, agents/*/action, agents/*/delete

Een agent configureren en uitvoeren

Voer de volgende opdrachten uit om de Python-pakketten te installeren.

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

Als u vervolgens uw API-aanvragen wilt verifiƫren en het programma wilt uitvoeren, gebruikt u de opdracht az login om u aan te melden bij uw Azure-abonnement.

az login

Gebruik de volgende code om een agent te maken en uit te voeren. Als u deze code wilt uitvoeren, moet u het eindpunt voor uw project ophalen. Deze tekenreeks is in de volgende indeling:

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

Important

Vanaf mei 2025 gebruikt de Azure AI Agent Service een eindpunt voor Foundry-projecten in plaats van de verbindingsreeks die eerder is gebruikt voor hubprojecten. Als u een hubproject gebruikt, kunt u de huidige versies van de SDK en REST API niet gebruiken. Zie SDK-gebruik met hubprojecten voor meer informatie.

U vindt uw eindpunt in het overzicht van uw project in de Microsoft Foundry-portal, onder Libraries>Foundry.

Een schermopname van het eindpunt in de Foundry-portal.

Stel dit eindpunt in als een omgevingsvariabele met de naam PROJECT_ENDPOINT.

U hebt ook de implementatienaam van uw model nodig. U vindt deze in Modellen en eindpunten in het navigatiemenu aan de linkerkant.

Een schermopname van het scherm voor modelimplementatie in de Foundry-portal.

Sla de naam van uw modelimplementatienaam op als een omgevingsvariabele met de naam 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")

| Referentiedocumentatie | Samples | Library source code | Package (npm) |

Prerequisites

  • Een agentomgeving instellen
  • Wijs de RBAC-rolvan de Azure AI-gebruiker toe aan elk teamlid dat agents moet maken of bewerken met behulp van de SDK of Agent Playground
    • Deze rol moet worden toegewezen binnen de projectscope
    • Minimale benodigde autorisaties: agents/*/read, agents/*/action, agents/*/delete

Een agent configureren en uitvoeren

Belangrijke objecten in deze code zijn onder andere:

Initialiseer eerst een nieuw TypeScript-project door het volgende uit te voeren:

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

Voer de volgende opdrachten uit om de vereiste NPM-pakketten te installeren.

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

Als u vervolgens uw API-aanvragen wilt verifiƫren en het programma wilt uitvoeren, gebruikt u de opdracht az login om u aan te melden bij uw Azure-abonnement.

az login

Gebruik de volgende code om de wiskundige vraag I need to solve the equation '3x + 11 = 14'. Can you help me?te beantwoorden. Als u deze code wilt uitvoeren, moet u het eindpunt voor uw project ophalen. Deze tekenreeks is in de volgende indeling:

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

U vindt uw eindpunt in het overzicht van uw project in de Microsoft Foundry-portal, onder Libraries>Foundry.

Een schermopname van het eindpunt in de Foundry-portal.

Stel dit eindpunt in als een omgevingsvariabele met de naam PROJECT_ENDPOINT in een .env bestand.

U hebt ook de implementatienaam van uw model nodig. U vindt deze in Modellen en eindpunten in het navigatiemenu aan de linkerkant.

Een schermopname van het scherm voor modelimplementatie in de Foundry-portal.

Sla de naam van uw modelimplementatienaam op als een omgevingsvariabele met de naam MODEL_DEPLOYMENT_NAME.

Important

  • Deze quickstart-code maakt gebruik van omgevingsvariabelen voor gevoelige configuratie. Voer uw .env bestand nooit door naar versiebeheer door ervoor te zorgen dat .env wordt vermeld in uw .gitignore-bestand.
  • Vergeet niet: als u per ongeluk gevoelige informatie doorvoert, beschouw die referenties als gecompromitteerd en verander ze onmiddellijk.

Maak een tsconfig.json-bestand met de volgende inhoud:

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

Maak vervolgens een index.ts bestand en plak de volgende code:

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

Voer de code uit met behulp van npx tsx -r dotenv/config index.ts. Deze code beantwoordt de vraag I need to solve the equation '3x + 11 = 14'. Can you help me?. Antwoorden zijn niet deterministisch, uw uitvoer ziet er ongeveer als volgt uit:

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

Volledige voorbeeldbroncode beschikbaar.

| Referentiedocumentatie | Voorbeelden | Broncode van de bibliotheek | Pakket (Maven) |

Prerequisites

  • Een agentomgeving instellen
  • Wijs de RBAC-rolvan de Azure AI-gebruiker toe aan elk teamlid dat agents moet maken of bewerken met behulp van de SDK of Agent Playground
    • Deze rol moet worden toegewezen binnen de projectscope
    • Minimale benodigde autorisaties: agents/*/read, agents/*/action, agents/*/delete

Een agent configureren en uitvoeren

Maak eerst een nieuw Java-consoleproject. U hebt de volgende afhankelijkheden nodig om de code uit te voeren:

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

Als u vervolgens uw API-aanvragen wilt verifiƫren en het programma wilt uitvoeren, gebruikt u de opdracht az login om u aan te melden bij uw Azure-abonnement.

az login

Gebruik de volgende code om een agent te maken en uit te voeren. Als u deze code wilt uitvoeren, moet u het eindpunt voor uw project ophalen. Deze tekenreeks is in de volgende indeling:

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

Important

Vanaf mei 2025 gebruikt de Azure AI Agent Service een eindpunt voor Foundry-projecten in plaats van de verbindingsreeks die eerder is gebruikt voor hubprojecten. Als u een hubproject gebruikt, kunt u de huidige versies van de SDK en REST API niet gebruiken. Zie SDK-gebruik met hubprojecten voor meer informatie.

U vindt uw eindpunt in het overzicht van uw project in de Microsoft Foundry-portal, onder Libraries>Foundry.

Een schermopname van het eindpunt in de Foundry-portal.

Stel dit eindpunt in een omgevingsvariabele met de naam PROJECT_ENDPOINT.

U hebt ook de implementatienaam van uw model nodig. U vindt deze in Modellen en eindpunten in het navigatiemenu aan de linkerkant.

Een schermopname van het scherm voor modelimplementatie in de Foundry-portal.

Sla de naam van uw modelimplementatienaam op als een omgevingsvariabele met de naam MODEL_DEPLOYMENT_NAME.

Voorbeeld van code

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

| Referentiedocumentatie |

Prerequisites

  • Een agentomgeving instellen
  • Wijs de RBAC-rolvan de Azure AI-gebruiker toe aan elk teamlid dat agents moet maken of bewerken met behulp van de SDK of Agent Playground
    • Deze rol moet worden toegewezen binnen de projectscope
    • Minimale benodigde autorisaties: agents/*/read, agents/*/action, agents/*/delete

Een agent configureren en uitvoeren

Als u uw API-aanvragen wilt verifiƫren, gebruikt u de opdracht az login om u aan te melden bij uw Azure-abonnement.

az login

Vervolgens moet u het Entra ID-token ophalen om de API-aanroepen als autorisatie op te geven. Haal het token op met behulp van de CLI-opdracht:

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

Stel het toegangstoken in als een omgevingsvariabele met de naam AGENT_TOKEN.

Als u REST API-aanroepen wilt uitvoeren naar Foundry Agent Service, moet u het eindpunt van uw project gebruiken:

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

Uw eindpunt ziet er bijvoorbeeld ongeveer als volgt uit:

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

Stel dit eindpunt in als een omgevingsvariabele met de naam AZURE_AI_FOUNDRY_PROJECT_ENDPOINT.

Note

  • Voor de parameter api-version is de GA API-versie 2025-05-01 en de nieuwste preview-API-versie is 2025-05-15-preview. U moet de preview-API gebruiken voor hulpprogramma's die in preview zijn.
  • Overweeg om uw API-versie een omgevingsvariabele te maken, zoals $API_VERSION.

Een agent maken

Note

Bij Azure AI Agents Service is voor de parameter de naam van de model modelimplementatie vereist. Als de naam van uw modelimplementatie anders is dan de naam van het onderliggende model, past u de code aan. "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"
  }'

Een thread maken

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

Een gebruikersvraag toevoegen aan de thread

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

De thread uitvoeren

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

Haal de status van de run op

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"

Het antwoord van de agent ophalen

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

Volgende stappen

Meer informatie over de tools die u kunt gebruiken om de mogelijkheden van uw agents uit te breiden, zoals toegang tot het web, het bieden van achtergrondinformatie en meer.

  • Last updated on