Partage via

Démarrage rapide : Créer un agent

  • Article

Azure AI Agent Service vous permet de créer des agents IA adaptés à vos besoins par le biais d’instructions personnalisées et enrichies par des outils avancés tels qu’un interpréteur de code et des fonctions personnalisées.

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

Prérequis

Configurer votre projet Hub Azure AI et Agent

La section suivante vous montre comment configurer les ressources nécessaires pour commencer à utiliser Azure AI Agents Service :

  1. Création d’un Hub Azure AI pour configurer votre environnement d’application et vos ressources Azure.

  2. La création d’un projet Azure AI sous votre hub crée un point de terminaison pour que votre application appelle, et configure les services d’application pour accéder aux ressources de votre locataire.

  3. Connexion d’une ressource Azure OpenAI ou d’une ressource Azure AI Services

Choisir une configuration d’agent de base ou standard

Configuration de base : Les agents utilisent des ressources de recherche et de stockage multilocataires complètement managées par Microsoft. Vous n’avez pas de visibilité ou de contrôle sur ces ressources Azure sous-jacentes.

Configuration standard : Les agents utilisent des ressources de recherche et de stockage monolocataires appartenant au client. Avec cette configuration, vous disposez d’un contrôle total et d’une visibilité totale sur ces ressources, mais votre utilisation peut engendrer des coûts.

Description et déploiement automatique Diagramme (cliquez pour faire un zoom avant)
Déployez une configuration d’agent de base qui utilise une identité managée pour l’authentification. Les ressources pour le hub IA, le projet IA, le compte de stockage et AI Services sont créées pour vous.

Le compte AI Services est connecté à votre projet et à votre hub, et un modèle gpt-4o-mini est déployé dans la région eastus. Un coffre de clés géré par Microsoft est utilisé par défaut.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent de base.
Déployez une configuration d’agent standard qui utilise une identité managée pour l’authentification.

Les ressources pour le hub IA, le projet IA, le coffre de clés, le compte de stockage, AI Services et la Recherche IA sont créées pour vous.

AI Services, la Recherche IA, le coffre de clés et le compte de stockage sont connectés à votre projet et votre hub. Un modèle gpt-4o-mini est déployé dans la région eastus.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent standard.

[Facultatif] Sélection de modèle dans le modèle d’auto-déploiement

Vous pouvez personnaliser le modèle utilisé par votre agent en modifiant les paramètres du modèle dans le modèle d’auto-déploiement. Pour déployer un autre modèle, vous devez mettre à jour au moins les paramètres modelName et modelVersion.

Par défaut, le modèle de déploiement est configuré avec les valeurs suivantes :

Paramètre de modèle Valeur par défaut
modelName gpt-4o-mini
modelFormat OpenAI (pour Azure OpenAI)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Important

Ne changez pas le paramètre modelFormat.

Les modèles prennent en charge seulement le déploiement de modèles Azure OpenAI. Découvrez les modèles Azure OpenAI pris en charge dans la documentation Prise en charge des modèles Azure AI Agent Service.

[Facultatif] Utiliser vos propres ressources lors de la configuration de l’agent

Remarque

Si vous utilisez une ressource AI Services ou Azure OpenAI existante, aucun modèle ne sera déployé. Vous pouvez déployer un modèle sur la ressource une fois l’installation de l’agent terminée.

Utilisez une ressource AI Services, Azure OpenAI, Recherche AI et/ou Stockage Blob Azure existante en fournissant l’ID de ressource ARM complet dans le fichier de paramètres :

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Si vous voulez utiliser une ressource Azure OpenAI existante, vous devez mettre à jour les paramètres aiServiceAccountResourceId et aiServiceKind dans le fichier de paramètres. Le paramètre aiServiceKind doit être défini sur AzureOpenAI.

Pour plus d’informations, consultez Comment utiliser vos propres ressources.

Configurer et exécuter un agent

Composant Description
Agent IA personnalisée qui utilise des modèles d’IA conjointement avec des outils.
Outil Les outils permettent d’étendre la capacité d’un agent à répondre de manière fiable et exacte pendant la conversation. Par exemple, connecter des bases de connaissances définies par l’utilisateur pour fournir des bases au modèle ou permettre à la recherche web de fournir des informations à jour.
Thread Session de conversation entre un agent et un utilisateur. Les threads stockent les messages et gèrent automatiquement la troncature pour adapter le contenu au contexte d'un modèle.
Message Message créé par un agent ou un utilisateur. Les messages peuvent contenir du texte, des images et d’autres fichiers. Les messages sont stockés sous forme de liste dans le thread.
Exécuter Activation d’un agent pour qu’il commence à s’exécuter sur la base du contenu du thread. L’agent utilise sa configuration et les messages du thread pour effectuer des tâches en appelant des modèles et des outils. Dans le cadre d’une exécution, l’agent ajoute des messages au thread.
Étape d’exécution Liste détaillée des étapes de l’agent dans le cadre d’une exécution. Un agent peut appeler des outils ou créer des messages pendant son exécution. L’examen des étapes d’exécution vous permet de comprendre comment l’agent parvient à ses résultats.

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.Projects
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 créer une chaîne de connexion en utilisant les informations de votre projet. Cette chaîne est dans le format suivant :

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

Conseil

Vous trouverez également votre chaîne de connexion dans la Vue d’ensemble de votre projet dans le portail Azure AI Foundry, sous Détails du projet>Chaîne de connexion du projet. Capture d’écran montrant la chaîne de connexion dans le portail Azure AI Foundry.

Vous trouverez HostName en accédant à votre discovery_url et en supprimant le https:// de début et le /discoveryde fin. Pour rechercher votre discovery_url, exécutez cette commande CLI :

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

Par exemple, votre chaîne de connexion pourrait ressembler à ceci :

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

Définissez cette chaîne de connexion comme variable d’environnement appelée PROJECT_CONNECTION_STRING.

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

#nullable disable

using Azure.Identity;

namespace Azure.AI.Projects.Tests;

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

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

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

        // Intermission: agent should now be listed

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

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

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

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

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

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

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

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

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

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

Prérequis

Configurer votre projet Hub Azure AI et Agent

La section suivante vous montre comment configurer les ressources nécessaires pour commencer à utiliser Azure AI Agents Service :

  1. Création d’un Hub Azure AI pour configurer votre environnement d’application et vos ressources Azure.

  2. La création d’un projet Azure AI sous votre hub crée un point de terminaison pour que votre application appelle, et configure les services d’application pour accéder aux ressources de votre locataire.

  3. Connexion d’une ressource Azure OpenAI ou d’une ressource Azure AI Services

Choisir une configuration d’agent de base ou standard

Configuration de base : Les agents utilisent des ressources de recherche et de stockage multilocataires complètement managées par Microsoft. Vous n’avez pas de visibilité ou de contrôle sur ces ressources Azure sous-jacentes.

Configuration standard : Les agents utilisent des ressources de recherche et de stockage monolocataires appartenant au client. Avec cette configuration, vous disposez d’un contrôle total et d’une visibilité totale sur ces ressources, mais votre utilisation peut engendrer des coûts.

Description et déploiement automatique Diagramme (cliquez pour faire un zoom avant)
Déployez une configuration d’agent de base qui utilise une identité managée pour l’authentification. Les ressources pour le hub IA, le projet IA, le compte de stockage et AI Services sont créées pour vous.

Le compte AI Services est connecté à votre projet et à votre hub, et un modèle gpt-4o-mini est déployé dans la région eastus. Un coffre de clés géré par Microsoft est utilisé par défaut.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent de base.
Déployez une configuration d’agent standard qui utilise une identité managée pour l’authentification.

Les ressources pour le hub IA, le projet IA, le coffre de clés, le compte de stockage, AI Services et la Recherche IA sont créées pour vous.

AI Services, la Recherche IA, le coffre de clés et le compte de stockage sont connectés à votre projet et votre hub. Un modèle gpt-4o-mini est déployé dans la région eastus.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent standard.

[Facultatif] Sélection de modèle dans le modèle d’auto-déploiement

Vous pouvez personnaliser le modèle utilisé par votre agent en modifiant les paramètres du modèle dans le modèle d’auto-déploiement. Pour déployer un autre modèle, vous devez mettre à jour au moins les paramètres modelName et modelVersion.

Par défaut, le modèle de déploiement est configuré avec les valeurs suivantes :

Paramètre de modèle Valeur par défaut
modelName gpt-4o-mini
modelFormat OpenAI (pour Azure OpenAI)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Important

Ne changez pas le paramètre modelFormat.

Les modèles prennent en charge seulement le déploiement de modèles Azure OpenAI. Découvrez les modèles Azure OpenAI pris en charge dans la documentation Prise en charge des modèles Azure AI Agent Service.

[Facultatif] Utiliser vos propres ressources lors de la configuration de l’agent

Remarque

Si vous utilisez une ressource AI Services ou Azure OpenAI existante, aucun modèle ne sera déployé. Vous pouvez déployer un modèle sur la ressource une fois l’installation de l’agent terminée.

Utilisez une ressource AI Services, Azure OpenAI, Recherche AI et/ou Stockage Blob Azure existante en fournissant l’ID de ressource ARM complet dans le fichier de paramètres :

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Si vous voulez utiliser une ressource Azure OpenAI existante, vous devez mettre à jour les paramètres aiServiceAccountResourceId et aiServiceKind dans le fichier de paramètres. Le paramètre aiServiceKind doit être défini sur AzureOpenAI.

Pour plus d’informations, consultez Comment utiliser vos propres ressources.

Configurer et exécuter un agent

Composant Description
Agent IA personnalisée qui utilise des modèles d’IA conjointement avec des outils.
Outil Les outils permettent d’étendre la capacité d’un agent à répondre de manière fiable et exacte pendant la conversation. Par exemple, connecter des bases de connaissances définies par l’utilisateur pour fournir des bases au modèle ou permettre à la recherche web de fournir des informations à jour.
Thread Session de conversation entre un agent et un utilisateur. Les threads stockent les messages et gèrent automatiquement la troncature pour adapter le contenu au contexte d'un modèle.
Message Message créé par un agent ou un utilisateur. Les messages peuvent contenir du texte, des images et d’autres fichiers. Les messages sont stockés sous forme de liste dans le thread.
Exécuter Activation d’un agent pour qu’il commence à s’exécuter sur la base du contenu du thread. L’agent utilise sa configuration et les messages du thread pour effectuer des tâches en appelant des modèles et des outils. Dans le cadre d’une exécution, l’agent ajoute des messages au thread.
Étape d’exécution Liste détaillée des étapes de l’agent dans le cadre d’une exécution. Un agent peut appeler des outils ou créer des messages pendant son exécution. L’examen des étapes d’exécution vous permet de comprendre comment l’agent parvient à ses résultats.

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 créer une chaîne de connexion en utilisant les informations de votre projet. Cette chaîne est dans le format suivant :

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

Conseil

Vous trouverez également votre chaîne de connexion dans la Vue d’ensemble de votre projet dans le portail Azure AI Foundry, sous Détails du projet>Chaîne de connexion du projet. Capture d’écran montrant la chaîne de connexion dans le portail Azure AI Foundry.

Vous trouverez HostName en accédant à votre discovery_url et en supprimant le https:// de début et le /discoveryde fin. Pour rechercher votre discovery_url, exécutez cette commande CLI :

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

Par exemple, votre chaîne de connexion pourrait ressembler à ceci :

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

Définissez cette chaîne de connexion comme variable d’environnement appelée PROJECT_CONNECTION_STRING.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Prérequis

Configurer votre projet Hub Azure AI et Agent

La section suivante vous montre comment configurer les ressources nécessaires pour commencer à utiliser Azure AI Agents Service :

  1. Création d’un Hub Azure AI pour configurer votre environnement d’application et vos ressources Azure.

  2. La création d’un projet Azure AI sous votre hub crée un point de terminaison pour que votre application appelle, et configure les services d’application pour accéder aux ressources de votre locataire.

  3. Connexion d’une ressource Azure OpenAI ou d’une ressource Azure AI Services

Choisir une configuration d’agent de base ou standard

Configuration de base : Les agents utilisent des ressources de recherche et de stockage multilocataires complètement managées par Microsoft. Vous n’avez pas de visibilité ou de contrôle sur ces ressources Azure sous-jacentes.

Configuration standard : Les agents utilisent des ressources de recherche et de stockage monolocataires appartenant au client. Avec cette configuration, vous disposez d’un contrôle total et d’une visibilité totale sur ces ressources, mais votre utilisation peut engendrer des coûts.

Description et déploiement automatique Diagramme (cliquez pour faire un zoom avant)
Déployez une configuration d’agent de base qui utilise une identité managée pour l’authentification. Les ressources pour le hub IA, le projet IA, le compte de stockage et AI Services sont créées pour vous.

Le compte AI Services est connecté à votre projet et à votre hub, et un modèle gpt-4o-mini est déployé dans la région eastus. Un coffre de clés géré par Microsoft est utilisé par défaut.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent de base.
Déployez une configuration d’agent standard qui utilise une identité managée pour l’authentification.

Les ressources pour le hub IA, le projet IA, le coffre de clés, le compte de stockage, AI Services et la Recherche IA sont créées pour vous.

AI Services, la Recherche IA, le coffre de clés et le compte de stockage sont connectés à votre projet et votre hub. Un modèle gpt-4o-mini est déployé dans la région eastus.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent standard.

[Facultatif] Sélection de modèle dans le modèle d’auto-déploiement

Vous pouvez personnaliser le modèle utilisé par votre agent en modifiant les paramètres du modèle dans le modèle d’auto-déploiement. Pour déployer un autre modèle, vous devez mettre à jour au moins les paramètres modelName et modelVersion.

Par défaut, le modèle de déploiement est configuré avec les valeurs suivantes :

Paramètre de modèle Valeur par défaut
modelName gpt-4o-mini
modelFormat OpenAI (pour Azure OpenAI)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Important

Ne changez pas le paramètre modelFormat.

Les modèles prennent en charge seulement le déploiement de modèles Azure OpenAI. Découvrez les modèles Azure OpenAI pris en charge dans la documentation Prise en charge des modèles Azure AI Agent Service.

[Facultatif] Utiliser vos propres ressources lors de la configuration de l’agent

Remarque

Si vous utilisez une ressource AI Services ou Azure OpenAI existante, aucun modèle ne sera déployé. Vous pouvez déployer un modèle sur la ressource une fois l’installation de l’agent terminée.

Utilisez une ressource AI Services, Azure OpenAI, Recherche AI et/ou Stockage Blob Azure existante en fournissant l’ID de ressource ARM complet dans le fichier de paramètres :

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Si vous voulez utiliser une ressource Azure OpenAI existante, vous devez mettre à jour les paramètres aiServiceAccountResourceId et aiServiceKind dans le fichier de paramètres. Le paramètre aiServiceKind doit être défini sur AzureOpenAI.

Pour plus d’informations, consultez Comment utiliser vos propres ressources.

Configurer et exécuter un agent

Composant Description
Agent IA personnalisée qui utilise des modèles d’IA conjointement avec des outils.
Outil Les outils permettent d’étendre la capacité d’un agent à répondre de manière fiable et exacte pendant la conversation. Par exemple, connecter des bases de connaissances définies par l’utilisateur pour fournir des bases au modèle ou permettre à la recherche web de fournir des informations à jour.
Thread Session de conversation entre un agent et un utilisateur. Les threads stockent les messages et gèrent automatiquement la troncature pour adapter le contenu au contexte d'un modèle.
Message Message créé par un agent ou un utilisateur. Les messages peuvent contenir du texte, des images et d’autres fichiers. Les messages sont stockés sous forme de liste dans le thread.
Exécuter Activation d’un agent pour qu’il commence à s’exécuter sur la base du contenu du thread. L’agent utilise sa configuration et les messages du thread pour effectuer des tâches en appelant des modèles et des outils. Dans le cadre d’une exécution, l’agent ajoute des messages au thread.
Étape d’exécution Liste détaillée des étapes de l’agent dans le cadre d’une exécution. Un agent peut appeler des outils ou créer des messages pendant son exécution. L’examen des étapes d’exécution vous permet de comprendre comment l’agent parvient à ses résultats.

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

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

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 créer une chaîne de connexion en utilisant les informations de votre projet. Cette chaîne est dans le format suivant :

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

Conseil

Vous trouverez également votre chaîne de connexion dans la Vue d’ensemble de votre projet dans le portail Azure AI Foundry, sous Détails du projet>Chaîne de connexion du projet. Capture d’écran montrant la chaîne de connexion dans le portail Azure AI Foundry.

Vous trouverez HostName en accédant à votre discovery_url et en supprimant le https:// de début et le /discoveryde fin. Pour rechercher votre discovery_url, exécutez cette commande CLI :

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

Par exemple, votre chaîne de connexion pourrait ressembler à ceci :

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

Définissez cette chaîne de connexion comme variable d’environnement appelée PROJECT_CONNECTION_STRING.

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


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

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

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

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

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

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

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

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

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

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

Prérequis

Configurer votre projet Hub Azure AI et Agent

La section suivante vous montre comment configurer les ressources nécessaires pour commencer à utiliser Azure AI Agents Service :

  1. Création d’un Hub Azure AI pour configurer votre environnement d’application et vos ressources Azure.

  2. La création d’un projet Azure AI sous votre hub crée un point de terminaison pour que votre application appelle, et configure les services d’application pour accéder aux ressources de votre locataire.

  3. Connexion d’une ressource Azure OpenAI ou d’une ressource Azure AI Services

Choisir une configuration d’agent de base ou standard

Configuration de base : Les agents utilisent des ressources de recherche et de stockage multilocataires complètement managées par Microsoft. Vous n’avez pas de visibilité ou de contrôle sur ces ressources Azure sous-jacentes.

Configuration standard : Les agents utilisent des ressources de recherche et de stockage monolocataires appartenant au client. Avec cette configuration, vous disposez d’un contrôle total et d’une visibilité totale sur ces ressources, mais votre utilisation peut engendrer des coûts.

Description et déploiement automatique Diagramme (cliquez pour faire un zoom avant)
Déployez une configuration d’agent de base qui utilise une identité managée pour l’authentification. Les ressources pour le hub IA, le projet IA, le compte de stockage et AI Services sont créées pour vous.

Le compte AI Services est connecté à votre projet et à votre hub, et un modèle gpt-4o-mini est déployé dans la région eastus. Un coffre de clés géré par Microsoft est utilisé par défaut.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent de base.
Déployez une configuration d’agent standard qui utilise une identité managée pour l’authentification.

Les ressources pour le hub IA, le projet IA, le coffre de clés, le compte de stockage, AI Services et la Recherche IA sont créées pour vous.

AI Services, la Recherche IA, le coffre de clés et le compte de stockage sont connectés à votre projet et votre hub. Un modèle gpt-4o-mini est déployé dans la région eastus.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent standard.

[Facultatif] Sélection de modèle dans le modèle d’auto-déploiement

Vous pouvez personnaliser le modèle utilisé par votre agent en modifiant les paramètres du modèle dans le modèle d’auto-déploiement. Pour déployer un autre modèle, vous devez mettre à jour au moins les paramètres modelName et modelVersion.

Par défaut, le modèle de déploiement est configuré avec les valeurs suivantes :

Paramètre de modèle Valeur par défaut
modelName gpt-4o-mini
modelFormat OpenAI (pour Azure OpenAI)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Important

Ne changez pas le paramètre modelFormat.

Les modèles prennent en charge seulement le déploiement de modèles Azure OpenAI. Découvrez les modèles Azure OpenAI pris en charge dans la documentation Prise en charge des modèles Azure AI Agent Service.

[Facultatif] Utiliser vos propres ressources lors de la configuration de l’agent

Remarque

Si vous utilisez une ressource AI Services ou Azure OpenAI existante, aucun modèle ne sera déployé. Vous pouvez déployer un modèle sur la ressource une fois l’installation de l’agent terminée.

Utilisez une ressource AI Services, Azure OpenAI, Recherche AI et/ou Stockage Blob Azure existante en fournissant l’ID de ressource ARM complet dans le fichier de paramètres :

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Si vous voulez utiliser une ressource Azure OpenAI existante, vous devez mettre à jour les paramètres aiServiceAccountResourceId et aiServiceKind dans le fichier de paramètres. Le paramètre aiServiceKind doit être défini sur AzureOpenAI.

Pour plus d’informations, consultez Comment utiliser vos propres ressources.

Configurer et exécuter un agent

Composant Description
Agent IA personnalisée qui utilise des modèles d’IA conjointement avec des outils.
Outil Les outils permettent d’étendre la capacité d’un agent à répondre de manière fiable et exacte pendant la conversation. Par exemple, connecter des bases de connaissances définies par l’utilisateur pour fournir des bases au modèle ou permettre à la recherche web de fournir des informations à jour.
Thread Session de conversation entre un agent et un utilisateur. Les threads stockent les messages et gèrent automatiquement la troncature pour adapter le contenu au contexte d'un modèle.
Message Message créé par un agent ou un utilisateur. Les messages peuvent contenir du texte, des images et d’autres fichiers. Les messages sont stockés sous forme de liste dans le thread.
Exécuter Activation d’un agent pour qu’il commence à s’exécuter sur la base du contenu du thread. L’agent utilise sa configuration et les messages du thread pour effectuer des tâches en appelant des modèles et des outils. Dans le cadre d’une exécution, l’agent ajoute des messages au thread.
Étape d’exécution Liste détaillée des étapes de l’agent dans le cadre d’une exécution. Un agent peut appeler des outils ou créer des messages pendant son exécution. L’examen des étapes d’exécution vous permet de comprendre comment l’agent parvient à ses résultats.

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

npm install @azure/ai-projects
npm 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 créer une chaîne de connexion en utilisant les informations de votre projet. Cette chaîne est dans le format suivant :

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

Conseil

Vous trouverez également votre chaîne de connexion dans la Vue d’ensemble de votre projet dans le portail Azure AI Foundry, sous Détails du projet>Chaîne de connexion du projet. Capture d’écran montrant la chaîne de connexion dans le portail Azure AI Foundry.

Vous trouverez HostName en accédant à votre discovery_url et en supprimant le https:// de début et le /discoveryde fin. Pour rechercher votre discovery_url, exécutez cette commande CLI :

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

Par exemple, votre chaîne de connexion pourrait ressembler à ceci :

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

Définissez cette chaîne de connexion comme variable d’environnement appelée PROJECT_CONNECTION_STRING.

// index.js

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

La sortie contient l'invite et les réponses.

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

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

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

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

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

Prérequis

Configurer votre projet Hub Azure AI et Agent

La section suivante vous montre comment configurer les ressources nécessaires pour commencer à utiliser Azure AI Agents Service :

  1. Création d’un Hub Azure AI pour configurer votre environnement d’application et vos ressources Azure.

  2. La création d’un projet Azure AI sous votre hub crée un point de terminaison pour que votre application appelle, et configure les services d’application pour accéder aux ressources de votre locataire.

  3. Connexion d’une ressource Azure OpenAI ou d’une ressource Azure AI Services

Choisir une configuration d’agent de base ou standard

Configuration de base : Les agents utilisent des ressources de recherche et de stockage multilocataires complètement managées par Microsoft. Vous n’avez pas de visibilité ou de contrôle sur ces ressources Azure sous-jacentes.

Configuration standard : Les agents utilisent des ressources de recherche et de stockage monolocataires appartenant au client. Avec cette configuration, vous disposez d’un contrôle total et d’une visibilité totale sur ces ressources, mais votre utilisation peut engendrer des coûts.

Description et déploiement automatique Diagramme (cliquez pour faire un zoom avant)
Déployez une configuration d’agent de base qui utilise une identité managée pour l’authentification. Les ressources pour le hub IA, le projet IA, le compte de stockage et AI Services sont créées pour vous.

Le compte AI Services est connecté à votre projet et à votre hub, et un modèle gpt-4o-mini est déployé dans la région eastus. Un coffre de clés géré par Microsoft est utilisé par défaut.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent de base.
Déployez une configuration d’agent standard qui utilise une identité managée pour l’authentification.

Les ressources pour le hub IA, le projet IA, le coffre de clés, le compte de stockage, AI Services et la Recherche IA sont créées pour vous.

AI Services, la Recherche IA, le coffre de clés et le compte de stockage sont connectés à votre projet et votre hub. Un modèle gpt-4o-mini est déployé dans la région eastus.

Déployer dans Azure 		Diagramme d’architecture pour la configuration d’agent standard.

[Facultatif] Sélection de modèle dans le modèle d’auto-déploiement

Vous pouvez personnaliser le modèle utilisé par votre agent en modifiant les paramètres du modèle dans le modèle d’auto-déploiement. Pour déployer un autre modèle, vous devez mettre à jour au moins les paramètres modelName et modelVersion.

Par défaut, le modèle de déploiement est configuré avec les valeurs suivantes :

Paramètre de modèle Valeur par défaut
modelName gpt-4o-mini
modelFormat OpenAI (pour Azure OpenAI)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Important

Ne changez pas le paramètre modelFormat.

Les modèles prennent en charge seulement le déploiement de modèles Azure OpenAI. Découvrez les modèles Azure OpenAI pris en charge dans la documentation Prise en charge des modèles Azure AI Agent Service.

[Facultatif] Utiliser vos propres ressources lors de la configuration de l’agent

Remarque

Si vous utilisez une ressource AI Services ou Azure OpenAI existante, aucun modèle ne sera déployé. Vous pouvez déployer un modèle sur la ressource une fois l’installation de l’agent terminée.

Utilisez une ressource AI Services, Azure OpenAI, Recherche AI et/ou Stockage Blob Azure existante en fournissant l’ID de ressource ARM complet dans le fichier de paramètres :

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Si vous voulez utiliser une ressource Azure OpenAI existante, vous devez mettre à jour les paramètres aiServiceAccountResourceId et aiServiceKind dans le fichier de paramètres. Le paramètre aiServiceKind doit être défini sur AzureOpenAI.

Pour plus d’informations, consultez Comment utiliser vos propres ressources.

Configurer et exécuter un agent

Composant Description
Agent IA personnalisée qui utilise des modèles d’IA conjointement avec des outils.
Outil Les outils permettent d’étendre la capacité d’un agent à répondre de manière fiable et exacte pendant la conversation. Par exemple, connecter des bases de connaissances définies par l’utilisateur pour fournir des bases au modèle ou permettre à la recherche web de fournir des informations à jour.
Thread Session de conversation entre un agent et un utilisateur. Les threads stockent les messages et gèrent automatiquement la troncature pour adapter le contenu au contexte d'un modèle.
Message Message créé par un agent ou un utilisateur. Les messages peuvent contenir du texte, des images et d’autres fichiers. Les messages sont stockés sous forme de liste dans le thread.
Exécuter Activation d’un agent pour qu’il commence à s’exécuter sur la base du contenu du thread. L’agent utilise sa configuration et les messages du thread pour effectuer des tâches en appelant des modèles et des outils. Dans le cadre d’une exécution, l’agent ajoute des messages au thread.
Étape d’exécution Liste détaillée des étapes de l’agent dans le cadre d’une exécution. Un agent peut appeler des outils ou créer des messages pendant son exécution. L’examen des étapes d’exécution vous permet de comprendre comment l’agent parvient à ses résultats.

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

npm install @azure/ai-projects
npm 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 créer une chaîne de connexion en utilisant les informations de votre projet. Cette chaîne est dans le format suivant :

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

Conseil

Vous trouverez également votre chaîne de connexion dans la Vue d’ensemble de votre projet dans le portail Azure AI Foundry, sous Détails du projet>Chaîne de connexion du projet. Capture d’écran montrant la chaîne de connexion dans le portail Azure AI Foundry.

Vous trouverez HostName en accédant à votre discovery_url et en supprimant le https:// de début et le /discoveryde fin. Pour rechercher votre discovery_url, exécutez cette commande CLI :

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

Par exemple, votre chaîne de connexion pourrait ressembler à ceci :

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

Définissez cette chaîne de connexion comme variable d’environnement appelée PROJECT_CONNECTION_STRING.

// index.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

La sortie contient l'invite et les réponses.

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

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

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

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