Démarrage rapide : Créer une boîte à outils et l’utiliser avec un agent hébergé

Important

Les éléments marqués comme préversion dans cet article sont actuellement en préversion. Cette préversion est fournie sans contrat de niveau de service et Microsoft ne le recommande pas pour les charges de travail de production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités contraintes. Pour plus d’informations, consultez Conditions d'utilisation supplémentaires pour les versions préliminaires de Microsoft Azure.

Dans ce guide de démarrage rapide, vous créez une boîte à outils et vous l’utilisez à partir d’un agent hébergé Python. La boîte à outils expose un point de terminaison MCP (Model Context Protocol), afin que l’agent découvre ses outils via une seule connexion.

Les workflows Azure Developer CLI et Visual Studio Code utilisent l’exemple de boîte à outils Foundry. Son azure.yaml déclare la recherche web, l’interpréteur de code et les sources MCP pour les spécifications de l’API REST Azure, GitHub, Azure Language et Microsoft Foundry. Trois connexions de projet fournissent les informations d’identification et les paramètres d’identité des sources authentifiées.

Le flux de travail Python SDK crée une boîte à outils plus petite avec la recherche web et le serveur Microsoft Learn MCP public. Il utilise le code de l’agent de l’exemple sans déployer les déclarations de connexion et de boîte à outils supplémentaires de l’exemple.

Si vous utilisez un agent de codage comme GitHub Copilot, la compétence Microsoft Foundry peut aider à générer le point de terminaison de boîte à outils, à le connecter à un agent hébergé et à ajuster les exemples d’outils.

Prerequisites

Ce guide de démarrage rapide s’appuie sur la chaîne d’outils de l’agent hébergé. Suivez d’abord les conditions préalables dans le guide de démarrage rapide de l’agent hébergé, qui couvrent l’abonnement Azure, les rôles de projet, les Python, l’interface CLI Azure développeur (azd) et l’extensionmicrosoft.foundry.

Installez Python 3.13 ou version ultérieure et préparez les dépendances externes de l'exemple avant l'initialisation :

Saisie ou accès Comment la préparer
GITHUB_MCP_PAT Créez un jeton d’accès personnel GitHub uniquement avec les autorisations de référentiel nécessaires aux outils que vous envisagez d’appeler. Suivez la procédure de configuration du serveur distant du serveur MCP GitHub. Gardez la valeur à portée de main pour l’invite d’initialisation.
AZURE_LANGUAGE_MCP_ENDPOINT Configurez un point de terminaison Azure Language MCP. Utilisez le point de terminaison complet, y compris /language/mcp?api-version=2025-11-15-preview, plutôt que l’URL de base de la ressource.
accès à Azure Language La connexion de l’exemple langmcpconn utilise l’identité managée du projet Foundry. Accordez à cette identité l’accès à la ressource Language avant d’appeler ses outils. Passez en revue l’authentification Microsoft Entra pour les outils. Pour un nouveau projet, finalisez l’autorisation une fois que l’approvisionnement a créé son identité.
Accès à Foundry MCP La connexion de l’exemple foundrymcpconn utilise l’identité Microsoft Entra de l’utilisateur appelant. L’utilisateur a besoin d’accéder aux ressources qu’utilisent les outils Foundry sélectionnés.

L’exemple de code ne crée pas les ressources externes GitHub ou linguistiques. L’initialisation demande des entrées d’environnement non résolues, notamment le jeton et le point de terminaison Language, et stocke les valeurs dans l’environnement azd. Ne validez pas les informations d’identification, les fichiers .env ou les .azure.

Pour le chemin du KIT de développement logiciel (SDK) Python, utilisez la section Python plus loin dans cet article au lieu du flux de travail AZURE Developer CLI ou VS Code. Ce chemin crée la boîte à outils avec project_client.toolboxes.create_version(...), puis charge le code de l’agent hébergé sous la forme d’une nouvelle version et le pointe vers cette boîte à outils par nom.

Installez les packages Python utilisés dans ce chemin d’accès :

pip install "azure-ai-projects>=2.3.0" python-dotenv

Vous avez besoin d’un projet Foundry existant avec un modèle compatible chat déployé. L’option SDK Python dans ce démarrage rapide crée la boîte à outils et la version de l’agent hébergé, mais elle ne génère pas la structure de base d’un nouveau projet Foundry et ne crée pas de déploiement de modèle à votre place.

Pour le chemin d’accès .NET SDK, utilisez la section C# plus loin dans cet article au lieu du flux de travail AZURE Developer CLI ou VS Code. Ce chemin crée la boîte à outils avec AgentToolboxes.CreateVersion(...), puis charge le code de l’agent hébergé C# en tant que nouvelle version et le pointe vers cette boîte à outils par nom.

Vous avez également besoin du sdk .NET 10 ou version ultérieure et d’un projet Foundry existant avec un modèle compatible conversation déployé.

Vous devez également disposer de Visual Studio Code avec l’extension Microsoft Foundry Toolkit, connecté à Azure.

Étape 1 : Initialiser l’agent hébergé

Dans un terminal, créez un répertoire vide et initialisez l’ensemble du projet dans celui-ci :

mkdir my-toolbox-agent && cd my-toolbox-agent
azd ai agent init --template "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml" --src .

Sélectionnez ou créez un projet Foundry et entrez les valeurs d’entrée externes préparées dans Prérequis. Pour réutiliser un déploiement de modèle dans un projet existant, ajoutez --model-deployment <existing-deployment-name> à la commande d’initialisation. L’utilisation du gabarit ne fournit actuellement pas d’outil de sélection d’un déploiement existant.

L’option --src . sélectionne la racine du projet, et non un sous-répertoire source de l’agent. Restez dans my-toolbox-agent, qui contient désormais azure.yaml, pour les commandes azd suivantes. La source de l’agent reste de la responsabilité de src/agent-framework-agent-with-foundry-toolbox-responses.

Passez en revue la déclaration du modèle et les paramètres de l’agent dans azure.yaml avant de procéder au provisionnement. Pour modifier une entrée externe ultérieurement, exécutez azd env set <name> <value> à partir de cette racine du projet ; n’exécutez pas une autre commande azd init.

Ouvrez le dossier de projet initialisé dans Visual Studio Code. Exécutez les commandes suivantes dans le terminal intégré. Ce workflow utilise le azure.yaml de l’exemple pour déployer les connexions, la boîte à outils et l’agent ensemble ; ne créez pas de boîte à outils distincte à la même fin dans le kit de ressources.

Étape 2 : Créer la boîte à outils

L’exemple déclare une agent-tools Toolbox en tant que azure.ai.toolbox service. Ses uses entrées référencent le projet et les connexions ; le service agent fait référence à la boîte à outils. Modifiez ces déclarations dans azure.yaml pour modifier les outils ou les connexions.

Vous n’avez pas besoin d’un toolbox.yaml distinct ni d’exécuter manuellement la commande azd ai toolbox create pour ce flux de travail. L’étape suivante déploie les déclarations dans l’ordre de dépendance. Le provisionnement seul ne crée pas la toolbox, et le démarrage de l’agent local ne crée aucune dépendance distante.

Étape 3 : Approvisionner des ressources Azure

Provisionnez l’infrastructure déclarée, puis déployez les connexions, la boîte à outils et l’agent hébergé :

azd up

Un projet Foundry existant peut toujours avoir besoin de ressources déclarées par le template, telles qu’un déploiement de modèle. Passez en revue la configuration avant d’exécuter cette commande. Si vous avez créé un nouveau projet, accordez à son identité managée l’accès à la ressource Language avant de tester la boîte à outils.

Le déploiement de Toolbox produit TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT. La déclaration de env associe ce point de terminaison versionné à TOOLBOX_ENDPOINT. Inspectez la sortie de la racine du projet :

azd env get-value TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT

Ne remplacez pas cette configuration d’association par un point de terminaison pour une boîte à outils créée séparément.

Étape 4 : Exécuter l’agent localement

Pour l’agent Python, assurez-vous que son service dans azure.yaml inclut PYTHONNOUSERSITE: "1" dans la map env existante avant le démarrage et le déploiement. Ne comptez pas sur le chargement de ce paramètre dans votre application. Pour obtenir des conseils sur la compatibilité des dépendances, consultez Configurer le démarrage de Python.

  1. Une fois les dépendances distantes déployées, démarrez l’agent à partir de la racine du projet :

    azd ai agent run
    

    Cette commande crée un environnement virtuel, installe des dépendances et sert l’agent sur http://localhost:8088. La configuration du service fournit FOUNDRY_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAMEet TOOLBOX_ENDPOINT. Ne remplacez pas ces valeurs par des espaces réservés dans un fichier source .env.

  2. Dans un terminal distinct, à partir de la même racine de projet, inspectez les outils disponibles et effectuez une recherche sur le Web :

    azd ai agent invoke --local "List the tools you can use."
    azd ai agent invoke --local "Find the latest release notes for the Azure CLI on the web."
    

Étape 5 : Déployer vers Foundry Agent Service

L’agent est déjà déployé par azd up. Après avoir modifié les outils, les connexions ou le code de l’agent, déployez tous les services ensemble :

azd deploy --all

Une fois la commande terminée, la sortie affiche des liens vers le playground de l’agent et le point de terminaison de l’agent. Appelez l’agent déployé :

azd ai agent invoke "List the tools you can use."

L’exemple utilise le point de terminaison versionné produit par ce déploiement. Cela ne nécessite pas de promouvoir la version de Toolbox comme version par défaut ou de rediriger d’autres agents qui utilisent une version antérieure.

chemin d’accès du KIT de développement logiciel (SDK) Python

Utilisez les étapes suivantes si vous souhaitez créer la boîte à outils et déployer la version de l’agent hébergé à l’aide du kit de développement logiciel (SDK) Python au lieu du flux CLI Azure développeur ou VS Code.

1. Créer ou choisir un projet Foundry

  1. Ouvrez le portail Foundry et créez un projet Foundry, ou sélectionnez-en un existant.
  2. Dans le projet, déployez un modèle compatible conversation comme gpt-5.4-mini.
  3. Copiez le point de terminaison du projet depuis Vue d’ensemble et le nom du déploiement depuis Build>Deployments.

2. Télécharger l’exemple de boîte à outils pour agent hébergé

Clonez le dépôt d’exemples Foundry :

git clone https://github.com/microsoft-foundry/foundry-samples.git

Créez un dossier de travail pour les scripts de déploiement. Dans ce dossier, créez un .env fichier avec ces valeurs :

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=toolbox-agent
TOOLBOX_NAME=my-toolbox
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/src/agent-framework-agent-with-foundry-toolbox-responses>

3. Créer la boîte à outils avec Python

Créez un fichier nommé create_toolbox.py dans le même dossier de travail que .env:

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, WebSearchToolboxTool
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
toolbox_name = os.environ["TOOLBOX_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    created = project_client.toolboxes.create_version(
        name=toolbox_name,
        description="Toolbox with web search and Microsoft Learn MCP.",
        tools=[
            WebSearchToolboxTool(
                name="web_search",
                search_context_size="medium",
            ),
            MCPToolboxTool(
                server_label="mslearn",
                server_url="https://learn.microsoft.com/api/mcp",
                require_approval="never",
            ),
        ],
    )
    print(f"Created toolbox version {created.version} for {created.name}")

    mcp_endpoint = (
        f"{endpoint}/toolboxes/{created.name}/versions/"
        f"{created.version}/mcp?api-version=v1"
    )
    print(f"Toolbox version: {created.version}")
    print(f"Toolbox MCP endpoint: {mcp_endpoint}")

Exécutez le script :

python create_toolbox.py

L’agent hébergé d’exemple peut localiser la boîte à outils à partir de TOOLBOX_ENDPOINT ou de FOUNDRY_PROJECT_ENDPOINT plus TOOLBOX_NAME. Ce chemin utilise TOOLBOX_NAME: vous n’avez donc pas besoin de stocker le point de terminaison avec version dans .env.

4. Déployer l’agent hébergé avec Python

Créez un fichier nommé deploy_toolbox_agent.py dans le même dossier de travail que .env:

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointConfig,
    CodeConfiguration,
    CodeDependencyResolution,
    FixedRatioVersionSelectionRule,
    HostedAgentDefinition,
    ProtocolConfiguration,
    ProtocolVersionRecord,
    ResponsesProtocolConfiguration,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "toolbox-agent")
toolbox_name = os.environ["TOOLBOX_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
    zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
    excluded = {".git", ".venv", "__pycache__", ".env"}

    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
        for path in source_dir.rglob("*"):
            if not path.is_file():
                continue
            if any(part in excluded for part in path.parts):
                continue
            zip_file.write(path, path.relative_to(source_dir))

    return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
    for attempt in range(60):
        time.sleep(10)
        details = project_client.agents.get_version(
            agent_name=agent_name,
            agent_version=version,
        )
        status = details["status"]
        print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

        if status == "active":
            return

        if status == "failed":
            raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

    raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
    code_zip_path.open("rb") as code_stream,
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    original_agent_endpoint = None
    created = None

    try:
        created = project_client.agents.create_version_from_code(
            agent_name=agent_name,
            description="Hosted agent with Foundry Toolbox integration.",
            definition=HostedAgentDefinition(
                cpu="1",
                memory="2Gi",
                code_configuration=CodeConfiguration(
                    runtime="python_3_13",
                    entry_point=["python", "main.py"],
                    dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
                ),
                environment_variables={
                    "FOUNDRY_PROJECT_ENDPOINT": endpoint,
                    "AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
                    "TOOLBOX_NAME": toolbox_name,
                    "PYTHONNOUSERSITE": "1",
                },
                protocol_versions=[
                    ProtocolVersionRecord(protocol="responses", version="2.0.0")
                ],
            ),
            code=code_stream,
        )

        print(f"Created hosted agent version {created.version}")
        wait_for_active_version(project_client, created.version)

        original_agent_endpoint = project_client.agents.get(
            agent_name=agent_name
        ).agent_endpoint

        project_client.agents.update_details(
            agent_name=agent_name,
            agent_endpoint=AgentEndpointConfig(
                version_selector=VersionSelector(
                    version_selection_rules=[
                        FixedRatioVersionSelectionRule(
                            agent_version=created.version,
                            traffic_percentage=100,
                        ),
                    ]
                ),
                protocol_configuration=ProtocolConfiguration(
                    responses=ResponsesProtocolConfiguration()
                ),
            ),
        )

        with project_client.get_openai_client(agent_name=agent_name) as openai_client:
            response = openai_client.responses.create(
                input=(
                    "How do I create a hosted agent in Microsoft Foundry? "
                    "Use the Microsoft Learn documentation."
                ),
            )
            if response.status != "completed":
                raise RuntimeError(f"Agent invocation failed: {response.error}")
            print(response.output_text)
    finally:
        if original_agent_endpoint is not None:
            project_client.agents.update_details(
                agent_name=agent_name,
                agent_endpoint=original_agent_endpoint,
            )

        if created is not None:
            project_client.agents.delete_version(
                agent_name=agent_name,
                agent_version=created.version,
                force=True,
            )

Exécutez le script :

python deploy_toolbox_agent.py

Ce script télécharge l’exemple de boîte à outils en tant que nouvelle version de l’agent hébergé, fait temporairement pointer l’agent hébergé vers cette version, l’invoque avec une question provenant de Microsoft Learn, puis restaure la configuration précédente du point de terminaison une fois l’opération terminée.

5. Vérifier la réponse prise en charge par la boîte à outils

Si vous configurez correctement la boîte à outils, la réponse indique que l’agent hébergé a découvert les outils de la boîte à outils et a répondu en s’appuyant sur la documentation Microsoft Learn.

Chemin du SDK C#

Utilisez ce chemin d’accès pour créer la boîte à outils et déployer l’exemple d’agent hébergé C# avec le sdk .NET au lieu du flux de travail AZURE Developer CLI ou VS Code.

1. Créer ou choisir un projet Foundry

  1. Ouvrez le portail Foundry et créez un projet Foundry, ou sélectionnez-en un existant.
  2. Dans le projet, déployez un modèle compatible conversation comme gpt-4o.
  3. Copiez le point de terminaison du projet depuis Vue d’ensemble et le nom du déploiement depuis Build>Deployments.

2. Télécharger l’exemple de boîte à outils pour agent hébergé

Clonez le dépôt d’exemples Foundry :

git clone https://github.com/microsoft-foundry/foundry-samples.git

L’exemple d’agent hébergé C# se trouve dans samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/src/foundry-toolbox-server-side-dotnet-agent-framework. Le code de déploiement dans les étapes suivantes définit ces variables d’environnement sur le conteneur :

Variable Description
FOUNDRY_PROJECT_ENDPOINT Point de terminaison du projet Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME Nom du déploiement du modèle conversationnel.
TOOLBOX_NAME Nom de la boîte à outils à laquelle l’agent se connecte.

3. Créer la boîte à outils avec C#

Créez une application console .NET et installez les packages. Les API de boîte à outils sont en préversion. Installez donc le package de préversion Azure.AI.Projects :

dotnet new console --name create-toolbox
cd create-toolbox
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity

Remplacez par le code suivant et définissez Program.csendpoint le point de terminaison de votre projet :

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
AgentToolboxes toolboxes = projectClient.AgentAdministrationClient.GetAgentToolboxes();

ToolboxVersion created = toolboxes.CreateVersion(
    name: toolboxName,
    tools:
    [
        new WebSearchToolboxTool { Name = "web_search", SearchContextSize = WebSearchToolSearchContextSize.Medium },
        new MCPToolboxTool(serverLabel: "mslearn")
        {
            ServerUri = new Uri("https://learn.microsoft.com/api/mcp"),
            ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
        },
    ],
    description: "Toolbox with web search and Microsoft Learn MCP.");
Console.WriteLine($"Created toolbox version {created.Version} for {created.Name}");

Exécutez l’application :

dotnet run

L’exemple d’agent hébergé résout la boîte à outils de FOUNDRY_PROJECT_ENDPOINT plus TOOLBOX_NAME. Vous n’avez donc pas besoin de stocker le point de terminaison versionné.

4. Déployer l’agent hébergé avec C#

Créez une deuxième application console pour le code de déploiement :

dotnet new console --name deploy-toolbox-agent
cd deploy-toolbox-agent
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

Remplacez Program.cs par le code suivant. Définissez endpoint, chatModelet samplePath sur vos valeurs. samplePath est le chemin d’accès complet au dossier source que vous avez cloné à l’étape foundry-toolbox-server-side-dotnet-agent-framework 2 :

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var toolboxName = "my-toolbox";
var agentName = "toolbox-agent";
var samplePath =
    @"<path-to-foundry-samples>\samples\csharp\hosted-agents\agent-framework\foundry-toolbox-server-side\src\foundry-toolbox-server-side-dotnet-agent-framework";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;

HostedAgentDefinition definition = new(cpu: "1", memory: "2Gi")
{
    Versions = { new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0") },
    CodeConfiguration = new(
        runtime: "dotnet_10",
        entryPoint: ["dotnet", "foundry-toolbox-server-side.dll"],
        dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add("FOUNDRY_PROJECT_ENDPOINT", endpoint);
definition.EnvironmentVariables.Add("AZURE_AI_MODEL_DEPLOYMENT_NAME", chatModel);
definition.EnvironmentVariables.Add("TOOLBOX_NAME", toolboxName);

ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;
try
{
    created = agentsClient.CreateAgentVersionFromCode(
        agentName, samplePath, new AgentVersionFromCodeMetadata(definition));
    Console.WriteLine($"Created hosted agent version {created.Version}");

    for (var attempt = 1; attempt <= 60; attempt++)
    {
        Thread.Sleep(TimeSpan.FromSeconds(10));
        created = agentsClient.GetAgentVersion(agentName, created.Version);
        Console.WriteLine($"Provisioning status: {created.Status} (attempt {attempt}/60)");
        if (created.Status == AgentVersionStatus.Active) break;
        if (created.Status == AgentVersionStatus.Failed)
            throw new InvalidOperationException("Hosted agent provisioning failed.");
    }

    ProjectsAgentRecord agent = agentsClient.GetAgent(agentName);
    originalEndpoint = agent.AgentEndpoint;
    agentsClient.PatchAgent(agentName, new PatchAgentOptions
    {
        AgentEndpoint = new AgentEndpointConfiguration
        {
            VersionSelector = new([new FixedRatioVersionSelectionRule(created.Version, 100)]),
            ProtocolConfiguration = new() { Responses = new ResponsesProtocolConfiguration() },
        },
    });

    ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgentEndpoint(agentName);
    ResponseResult response = responsesClient.CreateResponse(
        "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation.");
    Console.WriteLine(response.GetOutputText());
}
finally
{
    if (originalEndpoint is not null)
        agentsClient.PatchAgent(agentName, new PatchAgentOptions { AgentEndpoint = originalEndpoint });
    if (created is not null)
        agentsClient.DeleteAgentVersion(agentName, created.Version, force: true);
}

Exécutez l’application :

dotnet run

Ce code téléverse l’exemple de toolbox en tant que nouvelle version de l’agent hébergé, fait temporairement pointer l’agent hébergé vers cette version, l’invoque avec une question de Microsoft Learn, puis restaure la configuration précédente du point de terminaison à la fin de l’exécution.

5. Vérifier la réponse prise en charge par la boîte à outils

Si vous configurez correctement la boîte à outils, la réponse indique que l’agent hébergé a découvert les outils de la boîte à outils et a répondu en s’appuyant sur la documentation Microsoft Learn.

Nettoyer les ressources

Supprimez les ressources lorsque vous avez terminé afin de cesser d’encourir des frais.

Supprimez la boîte à outils :

azd ai toolbox delete agent-tools --force

Après avoir supprimé la boîte à outils, son point de terminaison cesse de fonctionner. Arrêtez l’agent local et supprimez tout point de terminaison copié des fichiers locaux .env. Exécuter azd deploy --all à nouveau recrée la boîte à outils déclarée dans azure.yaml.

Supprimez l’agent et ses ressources Azure :

Warning

Si l’environnement actuel azd a créé le projet Foundry, azd down supprime définitivement le groupe de ressources du projet et tout ce qu’il contient. Si vous avez sélectionné un projet existant pendant l’initialisation, azd down quitte le projet, son groupe de ressources, l’agent hébergé et d’autres ressources de démarrage rapide en place. Pour supprimer les ressources dont vous n’avez plus besoin à partir du projet existant, supprimez-les séparément.

azd down

Supprimez la boîte à outils par nom :

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        credential=credential,
    ) as project_client,
):
    project_client.toolboxes.delete(name=os.environ["TOOLBOX_NAME"])

Si vous avez créé un groupe de ressources ou un projet dédié pour ce guide de démarrage rapide, supprimez-le du portail Azure une fois que vous n’avez plus besoin de la boîte à outils, du déploiement de conversation ou de l’agent hébergé.

Le code de déploiement supprime déjà la version de l’agent hébergé et restaure la configuration de point de terminaison précédente lorsqu’elle se termine. Pour supprimer la boîte à outils, ajoutez ce code à une application console dans laquelle les packages Azure.AI.Projects (préversion) et Azure.Identity sont installés :

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

#pragma warning disable AAIP001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
projectClient.AgentAdministrationClient.GetAgentToolboxes().Delete(toolboxName);
Console.WriteLine($"Deleted toolbox '{toolboxName}'.");

Si vous avez créé un groupe de ressources ou un projet dédié pour ce guide de démarrage rapide, supprimez-le du portail Azure une fois que vous n’avez plus besoin de la boîte à outils, du déploiement de conversation ou de l’agent hébergé.

Résolution des problèmes

Problème Solution
azd env set signale qu’aucun projet n’existe Exécutez la commande à partir du répertoire initialisé contenant azure.yaml. Avec les commandes de cet article, ce répertoire est my-toolbox-agent.
L’initialisation demande un jeton GitHub ou un point de terminaison Language Préparez les valeurs d’entrée externes dans Conditions préalables. L’exemple CLI complet utilise plus de sources d’outils que le flux de travail Python SDK.
L’agent démarre mais n’a pas d’endpoint Toolbox Terminez azd up avant une exécution locale en CLI. Vérifiez TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT et la liaison TOOLBOX_ENDPOINT de l’agent dans azure.yaml. Pour le flux de travail Python SDK, consultez TOOLBOX_NAME.
La détection des outils échoue pour une source Vérifiez la connexion, la disponibilité du service et les autorisations de la source défaillante. Une source défaillante peut empêcher l’énumération de l’ensemble de la boîte à outils.
Les appels au point de terminaison de boîte à outils échouent avec une erreur d’autorisation Vérifiez que chaque requête inclut un jeton Entra limité à https://ai.azure.com/.default. L’exemple gère cela pour vous.
Connection refused lors de l’exécution locale Vérifiez qu’aucun autre processus n’utilise le port 8088.

Ce que vous avez appris

Dans ce guide de démarrage rapide, vous :

  • Nous avons mis au point une boîte à outils qui regroupe plusieurs outils sous un seul point de terminaison.
  • Utilisez la boîte à outils à partir d’un agent Python hébergé qui se connecte via le Model Context Protocol à l’aide d’Azure Developer CLI ou du SDK Python.
  • Exécuté l’agent localement ou l’avoir validé à distance et l’avoir déployé sur Foundry Agent Service.

Étape suivante