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

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" azure-identity 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.

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

L’exemple comprend un élément toolbox.yaml dans src/toolbox-agent qui définit les deux outils via un même point de terminaison. Créez la boîte à outils à partir de ce fichier :

azd ai toolbox create my-toolbox --from-file ./src/toolbox-agent/toolbox.yaml

La première version devient automatiquement la version par défaut. La commande imprime le point de terminaison MCP versionné de la boîte à outils. Copiez la valeur Endpoint de la sortie. Définissez-la comme variable d’environnement TOOLBOX_ENDPOINT dans les étapes suivantes. Il ressemble à ceci :

https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/my-toolbox/versions/1/mcp?api-version=v1

1. Ouvrez Visual Studio Code et sélectionnez Foundry Toolkit dans la barre d’activité.

2. Connectez-vous à votre compte Azure si vous y êtes invité.

3. Sous Mes ressources, développez votre projet, puis développez Outils.

4. Dans la vue Outils , sélectionnez l’icône + Ajouter une boîte à outils .

5. Entrez le nom de la boîte à outils (my-toolbox) et une description.

6. Sélectionnez Recherche web.

7. Sélectionnez + Ajouter un outil, choisissez d’ajouter un serveur MCP distant, puis entrez l’URL https://learn.microsoft.com/api/mcpdu serveur. Le serveur est public, donc aucune authentification n’est requise.

8. Cliquez sur Publier. La publication crée la première version de la boîte à outils.

9. Copiez le point de terminaison MCP de la boîte à outils. Exécutez la commande suivante et copiez la endpoint valeur à partir de la sortie. Définissez-la comme variable d’environnement TOOLBOX_ENDPOINT dans les étapes suivantes :

   azd ai toolbox show my-toolbox --output json
   

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>

Étape 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,
                },
                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.

Supprimez la boîte à outils :

azd ai toolbox delete my-toolbox --force

Après avoir supprimé la boîte à outils, son point de terminaison cesse de fonctionner. Retirez-le de src/toolbox-agent/.env et supprimez-le de votre environnement azd :

azd env set TOOLBOX_ENDPOINT ""

Supprimez l’agent et ses ressources Azure :

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