Démarrage rapide : Créer un agent

Note

Ce document fait référence au portail Microsoft Foundry (classique).

🔍 Consultez la documentation Microsoft Foundry (nouvelle) pour en savoir plus sur le nouveau portail.

Note

Ce guide de démarrage rapide concerne la version précédente des agents. Consultez le guide de démarrage rapide de Microsoft Foundry pour utiliser la nouvelle version de l’API.

Le service De l’agent Foundry vous permet de créer des agents IA adaptés à vos besoins grâce à des instructions personnalisées et augmentées par des outils avancés tels que l’interpréteur de code et les fonctions personnalisées.

Prerequisites

• Un abonnement Azure : créez-en un gratuitement.
• Assurez-vous que la personne qui crée le compte et le projet possède le rôle Propriétaire du compte Azure AI dans l’étendue de l’abonnement, ce qui accordera les autorisations nécessaires pour la création du projet
  • Vous pouvez également disposer du rôle Contributeur ou Contributeur Cognitive Services au niveau de l’abonnement pour permettre la création du projet
• Une fois le projet créé, assurez-vous que la personne qui crée l’agent au sein du projet a le rôle d’utilisateur Azure AI au niveau du projet

Important

Le portail Microsoft Foundry prend uniquement en charge la configuration de l’agent de base pour l’instant. Si vous souhaitez effectuer une configuration d’agent standard, consultez l’article sur la configuration de l’environnement pour en savoir plus.

Créer un compte et un projet Foundry dans le portail Foundry

Pour créer un compte et un projet dans Foundry, procédez comme suit :

1. Allez à Foundry. Si vous êtes dans un projet, sélectionnez Foundry en haut à gauche de la page pour accéder à la page d’accueil.

2. Utilisez le flux de création de l’agent pour l’expérience la plus rapide. Cliquez sur Créer un agent.

   

3. Entrez un nom pour le projet. Si vous souhaitez personnaliser les valeurs par défaut, sélectionnez Options avancées.

   

4. Cliquez sur Créer.

5. Attendez que vos ressources soient approvisionnées.

   1. Un compte et un projet (ressource enfant de votre compte) sont créés.
   2. Le modèle gpt-4o sera automatiquement déployé
   3. Un agent par défaut est créé

6. Une fois terminé, vous atterrirez directement dans le terrain de jeu de l’agent et vous pouvez commencer à créer des agents. Vous pouvez donner à votre agent des instructions sur ce qu’il faut faire et comment le faire. Par exemple : « Vous êtes un agent utile qui peut répondre à des questions sur la géographie ». Vous pouvez ensuite commencer à discuter avec votre agent.

   

   Note

   Si vous obtenez une erreur d’autorisation lors de la tentative de configuration ou de création d’agents, vérifiez que vous disposez de l’utilisateur Azure AI sur le projet.

| Documentation de référence | Exemples | Code source de la bibliothèque | Package (NuGet) |

Prerequisites

• Un environnement d’agent de configuration
• Attribuer le rôle RBACutilisateur Azure AI à chaque membre de l’équipe qui doit créer ou modifier des agents à l’aide du Kit de développement logiciel (SDK) ou de l’agent Playground
  • Ce rôle doit être attribué à l’étendue du projet
  • Autorisations minimales requises : agents/*/read, agents/*/action, agents/*/delete

Configurer et exécuter un agent

Créez un projet console .NET.

dotnet new console

Installez le package .NET dans votre projet. Par exemple, si vous utilisez l’interface de ligne de commande de .NET, exécutez la commande suivante.

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

Ensuite, pour authentifier vos demandes d’API et exécuter le programme, utilisez la commande az login pour vous connecter à votre abonnement Azure.

az login

Utilisez le code suivant pour créer et exécuter un agent. Pour exécuter ce code, vous devez obtenir le point de terminaison de votre projet. Cette chaîne est dans le format suivant :

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

Important

À compter de mai 2025, le service Azure AI Agent utilise un point de terminaison pour les projets Foundry au lieu de la chaîne de connexion précédemment utilisée pour les projets basés sur le hub. Si vous utilisez un projet hub, vous ne pourrez pas utiliser les versions actuelles du Kit de développement logiciel (SDK) et de l’API REST. Pour plus d’informations, consultez l’utilisation du Kit de développement logiciel (SDK) avec des projets basés sur hub.

Vous trouverez votre point de terminaison dans la vue d’ensemble de votre projet dans le portail Microsoft Foundry, sous Bibliothèques>Foundry.

Définissez ce point de terminaison dans une variable d’environnement nommée ProjectEndpoint.

Vous avez également besoin du nom de déploiement de votre modèle. Vous pouvez le trouver dans Modèles + Points de terminaison dans le menu de navigation de gauche.

Enregistrez le nom de votre nom de déploiement de modèle en tant que variable d’environnement nommée 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);

| Documentation de référence | Exemples | Code source de la bibliothèque | Package (PyPi) |

Prerequisites

• Un environnement d’agent de configuration
• Attribuer le rôle RBACutilisateur Azure AI à chaque membre de l’équipe qui doit créer ou modifier des agents à l’aide du Kit de développement logiciel (SDK) ou de l’agent Playground
  • Ce rôle doit être attribué à l’étendue du projet
  • Autorisations minimales requises : agents/*/read, agents/*/action, agents/*/delete

Configurer et exécuter un agent

Exécutez les commandes suivantes pour installer les packages Python.

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

Ensuite, pour authentifier vos demandes d’API et exécuter le programme, utilisez la commande az login pour vous connecter à votre abonnement Azure.

az login

Utilisez le code suivant pour créer et exécuter un agent. Pour exécuter ce code, vous devez obtenir le point de terminaison de votre projet. Cette chaîne est dans le format suivant :

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

Important

À compter de mai 2025, le service Azure AI Agent utilise un point de terminaison pour les projets Foundry au lieu de la chaîne de connexion précédemment utilisée pour les projets basés sur le hub. Si vous utilisez un projet hub, vous ne pourrez pas utiliser les versions actuelles du Kit de développement logiciel (SDK) et de l’API REST. Pour plus d’informations, consultez l’utilisation du Kit de développement logiciel (SDK) avec des projets basés sur hub.

Vous trouverez votre point de terminaison dans la vue d’ensemble de votre projet dans le portail Microsoft Foundry, sous Bibliothèques>Foundry.

Définissez ce point de terminaison en tant que variable d’environnement nommée PROJECT_ENDPOINT.

Vous avez également besoin du nom de déploiement de votre modèle. Vous pouvez le trouver dans Modèles + Points de terminaison dans le menu de navigation de gauche.

Enregistrez le nom de votre nom de déploiement de modèle en tant que variable d’environnement nommée 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")

| Documentation de référence | Exemples | Code source de la bibliothèque | Package (npm) |

Prerequisites

• Un environnement d’agent de configuration
• Attribuer le rôle RBACutilisateur Azure AI à chaque membre de l’équipe qui doit créer ou modifier des agents à l’aide du Kit de développement logiciel (SDK) ou de l’agent Playground
  • Ce rôle doit être attribué à l’étendue du projet
  • Autorisations minimales requises : agents/*/read, agents/*/action, agents/*/delete

• Node.js LTS

Configurer et exécuter un agent

Les objets clés de ce code sont les suivants :

• AgentsClient

Tout d’abord, initialisez un nouveau projet TypeScript en exécutant :

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

Exécutez les commandes suivantes pour installer les packages npm requis.

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

Ensuite, pour authentifier vos demandes d’API et exécuter le programme, utilisez la commande az login pour vous connecter à votre abonnement Azure.

az login

Utilisez le code suivant pour répondre à la question I need to solve the equation '3x + 11 = 14'. Can you help me?mathématique . Pour exécuter ce code, vous devez obtenir le point de terminaison de votre projet. Cette chaîne est dans le format suivant :

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

Vous trouverez votre point de terminaison dans la vue d’ensemble de votre projet dans le portail Microsoft Foundry, sous Bibliothèques>Foundry.

Définissez ce point de terminaison en tant que variable d’environnement nommée PROJECT_ENDPOINT dans un .env fichier.

Vous avez également besoin du nom de déploiement de votre modèle. Vous pouvez le trouver dans Modèles + Points de terminaison dans le menu de navigation de gauche.

Enregistrez le nom de votre nom de déploiement de modèle en tant que variable d’environnement nommée MODEL_DEPLOYMENT_NAME.

Important

• Ce code de démarrage rapide utilise des variables d’environnement pour la configuration sensible. Ne soumettez jamais votre fichier .env au contrôle de version en vous assurant que .env est répertorié dans votre fichier .gitignore.
• N’oubliez pas : si vous validez accidentellement des informations sensibles, considérez ces identifiants comme compromis et changez-les immédiatement.

Créez un fichier tsconfig.json avec le contenu suivant :

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

Ensuite, créez un index.ts fichier et collez-le dans le code suivant :

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

Exécutez le code à l’aide de npx tsx -r dotenv/config index.ts. Ce code répond à la question I need to solve the equation '3x + 11 = 14'. Can you help me?. Les réponses ne sont pas déterministes, votre sortie ressemble à la sortie ci-dessous :

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

Exemple complet de code source disponible.

| Documentation de référence | Exemples | Code source de la bibliothèque | Package (Maven) |

Prerequisites

• Un environnement d’agent de configuration
• Attribuer le rôle RBACutilisateur Azure AI à chaque membre de l’équipe qui doit créer ou modifier des agents à l’aide du Kit de développement logiciel (SDK) ou de l’agent Playground
  • Ce rôle doit être attribué à l’étendue du projet
  • Autorisations minimales requises : agents/*/read, agents/*/action, agents/*/delete

Configurer et exécuter un agent

Tout d’abord, créez un projet de console Java. Vous aurez besoin des dépendances suivantes pour exécuter le code :

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

Ensuite, pour authentifier vos demandes d’API et exécuter le programme, utilisez la commande az login pour vous connecter à votre abonnement Azure.

az login

Utilisez le code suivant pour créer et exécuter un agent. Pour exécuter ce code, vous devez obtenir le point de terminaison de votre projet. Cette chaîne est dans le format suivant :

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

Important

À compter de mai 2025, le service Azure AI Agent utilise un point de terminaison pour les projets Foundry au lieu de la chaîne de connexion précédemment utilisée pour les projets basés sur le hub. Si vous utilisez un projet hub, vous ne pourrez pas utiliser les versions actuelles du Kit de développement logiciel (SDK) et de l’API REST. Pour plus d’informations, consultez l’utilisation du Kit de développement logiciel (SDK) avec des projets basés sur hub.

Vous trouverez votre point de terminaison dans la vue d’ensemble de votre projet dans le portail Microsoft Foundry, sous Bibliothèques>Foundry.

Définissez ce point de terminaison dans une variable d’environnement nommée PROJECT_ENDPOINT.

Vous avez également besoin du nom de déploiement de votre modèle. Vous pouvez le trouver dans Modèles + Points de terminaison dans le menu de navigation de gauche.

Enregistrez le nom de votre nom de déploiement de modèle en tant que variable d’environnement nommée MODEL_DEPLOYMENT_NAME.

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

| Documentation de référence |

Prerequisites

• Un environnement d’agent de configuration
• Attribuer le rôle RBACutilisateur Azure AI à chaque membre de l’équipe qui doit créer ou modifier des agents à l’aide du Kit de développement logiciel (SDK) ou de l’agent Playground
  • Ce rôle doit être attribué à l’étendue du projet
  • Autorisations minimales requises : agents/*/read, agents/*/action, agents/*/delete

Configurer et exécuter un agent

Pour authentifier vos requêtes d’API, utilisez la commande az login pour vous connecter à votre abonnement Azure.

az login

Ensuite, vous devez récupérer le jeton d’ID Entra pour fournir l’autorisation aux appels d’API. Récupérez le jeton en utilisant la commande CLI :

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

Définissez le jeton d’accès en tant que variable d’environnement nommée AGENT_TOKEN.

Pour effectuer des appels d’API REST au service Foundry Agent, vous devez utiliser le point de terminaison de votre projet :

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

Par exemple, votre point de terminaison ressemble à ceci :

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

Définissez ce point de terminaison en tant que variable d’environnement nommée AZURE_AI_FOUNDRY_PROJECT_ENDPOINT.

Note

• Pour api-version le paramètre, la version de l’API GA est 2025-05-01 et la dernière version de l’API en préversion est 2025-05-15-preview. Vous devez utiliser l’API de préversion pour les outils qui sont en préversion.
• Envisagez de rendre votre version d’API une variable d’environnement, telle que $API_VERSION.

Créer un agent

Note

Avec Azure AI Agents Service, le paramètre model nécessite un nom de modèle de déploiement. Si votre nom de déploiement de modèle est différent du nom du modèle sous-jacent, vous devez ajuster votre code à "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"
  }'

Créer un thread

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

Ajouter une question utilisateur au 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?"
    }'

Exécuter le 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",
  }'

Récupérer l’état de l’exécution

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"

Récupérer la réponse de l’agent

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

Étapes suivantes

Découvrez les outils que vous pouvez utiliser pour étendre les fonctionnalités de vos agents, telles que l’accès au web, fournir des informations de base, etc.