Créer et gérer une boîte à outils dans Foundry

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

# Create Foundry project client
endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
)

# Create toolbox version with web search and MCP tools
toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with web search and an MCP server",
    tools=[
        WebSearchToolboxTool(),
        MCPToolboxTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="never",
            project_connection_id="my-key-auth-connection",
        ),
        ToolSearchToolboxTool(),
    ],
)
print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")

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

// Create Foundry project client
var projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";
AIProjectClient projectClient = new(new Uri(projectEndpoint), new DefaultAzureCredential());
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

WebSearchToolboxTool webTool = new();
MCPToolboxTool mcpTool = new(serverLabel: "myserver")
{
  ServerUri = new Uri("https://your-mcp-server.example.com"),
  ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(
    GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
};

ToolSearchToolboxTool searchTool = new() { Name = "ToolBoxSearch" };

ToolboxVersion toolboxVersion = await toolboxClient.CreateVersionAsync(
  name: "my-toolbox",
    tools: [webTool, mcpTool, searchTool],
    description: "Toolbox with web search, MCP, and tool search"
);
Console.WriteLine($"Created toolbox: {toolboxVersion.Name}, version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/my-toolbox/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Toolbox with web search, MCP, and tool search",
  "tools": [
    {
      "type": "web_search",
      "description": "Search the web for current information"
    },
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "never",
      "project_connection_id": "my-key-auth-connection"
    },
    {
      "type": "toolbox_search"
    }
  ]
}

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

// Create Foundry project client
const projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";

const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [
    {
      type: "web_search",
      description: "Search the web for current information",
    },
    {
      type: "mcp",
      server_label: "myserver",
      server_url: "https://your-mcp-server.example.com",
      require_approval: "never",
      project_connection_id: "my-key-auth-connection",
    },
    { type: "toolbox_search" },
  ],
  {
    description: "Toolbox with web search, MCP, and tool search",
  },
);
console.log(`Created toolbox: ${toolboxVersion.name}, version: ${toolboxVersion.version}`);

Utilisez l’extension Microsoft Foundry Toolkit pour Visual Studio Code pour créer et publier une boîte à outils à partir de la vue Tools.

1. Sélectionnez Foundry Toolkit dans la barre d’activité.
2. Sous Mes ressources, développez Votre nom de projet>Outils.
3. Sélectionnez l’icône + Ajouter une boîte à outils .
4. Sous l’onglet Générer une boîte à outils personnalisée , entrez le nom et la description de la boîte à outils, puis ajoutez les outils souhaités.
5. Pour activer le routage des outils basés sur l’intention, sélectionnez Recherche d’outils.
6. Cliquez sur Publier.

La publication d’une nouvelle boîte à outils crée sa première version. Cette version devient automatiquement la version par défaut.

Avec l’offre groupée d’extensions unifiées microsoft.foundry (voir Conditions préalables), créez une boîte à outils en deux étapes :

1. Utilisez azd ai connection create pour enregistrer chaque connexion au projet à laquelle la boîte à outils fait référence (un appel par entrée d’informations d’identification).
2. Utilisez azd ai toolbox create --from-file <toolbox.yaml> pour créer la boîte à outils. YaML référence les connexions par nom et n’incorpore jamais les informations d’identification.

Le modèle est le même pour chaque type de connexion et type d’authentification :

1. Configurez le projet actif une fois pour chaque shell :

   azd ai project set $PROJECT_ENDPOINT
   

2. Créez une connexion avec azd ai connection create. Les indicateurs diffèrent par type d’authentification, mais la forme de commande est toujours :

   azd ai connection create <name> \
     --kind <remote-tool|remote-a2a|cognitive-search|GroundingWithCustomSearch> \
     --target <endpoint-url> \
     --auth-type <none|custom-keys|api-key|oauth2|user-entra-token|project-managed-identity|agentic-identity> \
     [--custom-key "Header=Value" | --key <key> | --client-id ... --client-secret ... --authorization-url ... --token-url ... | --audience <aad-resource-uri>]
   

   Utilisez azd ai connection list et azd ai connection show <name> pour inspecter les connexions, et azd ai connection delete <name> --force pour les supprimer.

3. Créez une boîte à outils YAML qui référence une ou plusieurs connexions existantes par nom. Le YAML n’incorpore jamais les informations d’identification :

   # my-toolbox.yaml
   description: <human-readable description>
   connections:
     - name: <project-connection-name>   # must already exist in the project
   # Optional: add connectionless built-in tools and policies.
   tools:
     - type: web_search
       name: web
     - type: code_interpreter
       container: { type: auto }
       name: code
     # Tool search is connectionless.
     - type: toolbox_search
     # For Azure AI Search, set the index in the tool entry:
     # - type: azure_ai_search
     #   name: search
     #   azure_ai_search:
     #     indexes:
     #       - project_connection_id: <azure-ai-search-connection-name>
     #         index_name: <search-index-name>
     # For Bing Custom Search, set the instance in the tool entry:
     # - type: web_search
     #   name: bing
     #   custom_search_configuration:
     #     project_connection_id: <bing-connection-name>
     #     instance_name: <bing-instance-name>
   # Optional: attach existing project skills as MCP resources.
   skills:
     - name: <skill-name>          # uses the skill's default version
     - name: <other-skill>
       version: "2"               # pin to a specific skill version (string)
   policies:
     rai_config:
       rai_policy_name: <policy-name>    # must already exist on the project
   

   Au moins un de connections, skillsou tools doit être non vide. Les références de compétence doivent pointer vers les compétences qui existent déjà dans le même projet Foundry ; voir Utiliser des compétences dans Foundry pour les créer avec azd ai skill create. Pour plus d’informations sur la configuration de la recherche d’outils de bout en bout, consultez Utiliser la recherche d’outils.

4. Créez la boîte à outils à partir de ce fichier :

   azd ai toolbox create <toolbox-name> --from-file ./my-toolbox.yaml
   

   La première version devient automatiquement la version par défaut. Utilisez azd ai toolbox list, azd ai toolbox show <name>, azd ai toolbox version list <name>et azd ai toolbox delete <name> --force pour gérer les boîtes à outils.

Exemple : serveur MCP avec authentification basée sur des clés

# 1. Create the connection
azd ai connection create my-gh-conn \
  --kind remote-tool \
  --target https://api.githubcopilot.com/mcp/ \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer $GITHUB_PAT"

# 2. Create the toolbox
azd ai toolbox create my-toolbox \
  --from-file ./my-toolbox.yaml \
  --no-prompt

# my-toolbox.yaml
description: GitHub MCP toolbox
connections:
  - name: my-gh-conn

Dans l’extension Microsoft Foundry Toolkit pour Visual Studio Code, copiez le point de terminaison client de la boîte à outils depuis la vue Toolboxes.

1. Sélectionnez Foundry Toolkit dans la barre d’activité.
2. Sous Mes ressources, développez Votre nom de projet>Outils.
3. Sous l’onglet Boîtes à outils , recherchez votre boîte à outils.
4. Dans la colonne Endpoint URL, copiez l'endpoint.

La valeur de l'URL de point de terminaison est celle du point de terminaison consommateur de la boîte à outils. Pour construire un point de terminaison spécifique à la version, utilisez le modèle de développeur indiqué dans le tableau précédent.

Installez le Kit de développement logiciel (SDK) client MCP :

pip install mcp

Se connecter à la boîte à outils et aux outils de liste

import asyncio
from azure.identity import DefaultAzureCredential
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1"

token = DefaultAzureCredential().get_token("https://ai.azure.com/.default").token
headers = {
    "Authorization": f"Bearer {token}",
}

async def verify_toolbox():
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools_result = await session.list_tools()
            print(f"Tools found: {len(tools_result.tools)}")
            for tool in tools_result.tools:
                print(f"  - {tool.name}: {(tool.description or '')[:80]}")

            # Call a tool (replace with actual tool name and arguments)
            result = await session.call_tool("<tool_name>", arguments={})
            print(result)

asyncio.run(verify_toolbox())

Utilisez le point de terminaison spécifique à la version (/versions/{version}/mcp) pour valider une version avant de la promouvoir.

1. Initialisez la session MCP :

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

2. Envoyez la notification initialisée :

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","method":"notifications/initialized"}

3. Répertorier les outils disponibles :

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

4. Appelez un outil :

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"<TOOL_NAME>","arguments":{}}}

Installez le Kit de développement logiciel (SDK) client MCP :

npm install @modelcontextprotocol/sdk

Se connecter à la boîte à outils et aux outils de liste

import { DefaultAzureCredential } from "@azure/identity";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1";

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");

const transport = new StreamableHTTPClientTransport(
  new URL(url),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${token.token}`,
      },
    },
  },
);

const client = new Client({ name: "test", version: "1.0" });
await client.connect(transport);

// List available tools
const toolsResult = await client.listTools();
console.log(`Tools found: ${toolsResult.tools.length}`);
for (const tool of toolsResult.tools) {
  console.log(`  - ${tool.name}: ${(tool.description || "").slice(0, 80)}`);
}

// Call a tool (replace with actual tool name and arguments)
const result = await client.callTool({ name: "<tool_name>", arguments: {} });
console.log(result);

await client.close();

Utilisez le point de terminaison MCP de la boîte à outils avec un exemple préconfiguré d’agent hébergé pour valider le chargement de Toolbox dans VS Code.

1. Dans Foundry Toolkit, sous My Resources>Your project name>Tools, localisez la boîte à outils que vous souhaitez tester.
2. Sélectionnez le modèle de code scaffold.
3. Choisissez un dossier de projet lorsque vous y êtes invité.
4. Suivez la génération README.md pour installer les dépendances, configurer des variables d’environnement et exécuter l’exemple localement.
5. Utilisez Agent Inspector ou exécutez python main.py pour confirmer le chargement et la réponse des outils de boîte à outils.

Pour une validation spécifique à la version avant de promouvoir une nouvelle version de boîte à outils, utilisez l’onglet Python ou API REST dans cette étape.

LangGraph

Conditions requises pour les fragments d’intégration hébergés : Installez langchain-azure-ai[tools]>1.2.3. Le fragment utilise AzureAIProjectToolbox; utilisez l’exemple LangGraph géré pour l’agent complet, l’ensemble de packages et les fichiers de déploiement.

.env fichier :

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
TOOLBOX_NAME=agent-tools
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (modèle clé) :

from langchain_azure_ai.tools import AzureAIProjectToolbox

toolbox = AzureAIProjectToolbox(toolbox_name=TOOLBOX_NAME)
tools = await toolbox.get_tools()

Infrastructure de l’agent Microsoft

Installez agent-framework-foundry en plus du package prérequis Azure Identity. Pour l’implémentation complète, consultez l’exemple maintenu du framework d’agents.

Utilisez FoundryToolbox du SDK Agent Framework pour vous connecter au point de terminaison de la boîte à outils. La classe gère l’authentification de la boîte à outils et transfère le contexte d’appel de l’agent hébergé.

.env fichier :

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (modèle clé) :

from agent_framework.foundry import FoundryToolbox
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

# Toolbox MCP endpoint (platform-injected at runtime via TOOLBOX_ENDPOINT)
TOOLBOX_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1"

toolbox = FoundryToolbox(
    credential,
    url=TOOLBOX_ENDPOINT,
)

agent = chat_client.as_agent(
    name="my-toolbox-agent",
    instructions="You are a helpful assistant with access to Foundry toolbox tools.",
    tools=[toolbox],
)
ResponsesAgentServerHost().run()

Kit de développement logiciel (SDK) Copilot

Conditions requises pour les fragments d’intégration hébergés : Installez le Kit de développement logiciel (SDK) GitHub Copilot pour votre runtime. Le contour dépend des fonctions utilitaires McpBridge et _get_toolbox_token propres à l’application, qui ne sont pas implémentées ici. Suivez le point de terminaison de boîte à outils et le contrat d’authentification existants et les modèles d’intégration de l’agent hébergé. Un exemple complet maintenu n’est pas encore disponible.

Utilisez le sdk GitHub Copilot pour créer un agent alimenté par la boîte à outils qui relie l'appel d'outils de Copilot au point de terminaison MCP de la boîte à outils Foundry.

.env fichier :

GITHUB_TOKEN=<your-github-token>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

agent.py (modèle clé — Pont MCP) :

# 1. Open an MCP session to the toolbox endpoint
bridge = McpBridge(endpoint=TOOLBOX_ENDPOINT, token=_get_toolbox_token())
await bridge.initialize()
mcp_tools = await bridge.list_tools()

# 2. Map MCP tool list to Copilot SDK tool definitions
#    Dots in tool names are replaced with underscores (Copilot SDK requirement)
copilot_tools = [
    {
        "name": t["name"].replace(".", "_"),
        "description": t.get("description", ""),
        "parameters": t.get("inputSchema", {}),
    }
    for t in mcp_tools
]

# 3. Wire tool calls back to the MCP session
async def tool_handler(name: str, arguments: dict) -> str:
    return await bridge.call_tool(name.replace("_", ".", 1), arguments)

# 4. Run the Copilot SDK agent
agent = Agent(
    tools=copilot_tools,
    tool_handler=tool_handler,
    token=os.environ["GITHUB_TOKEN"],
)

Infrastructure de l’agent Microsoft

Installer Microsoft.Agents.AI.Foundry.Hosting et Azure.Identity. Pour un projet complet, consultez l’exemple de boîte à outils hébergée par Agent Framework public.

Utilisez AddFoundryToolboxes pour enregistrer une ou plusieurs boîtes à outils avec l’agent hébergé. L’intégration résout le point de terminaison MCP géré, authentifie les demandes et inclut l’intégrité de la boîte à outils dans la probe readiness.

Variables d’environnement :

AZURE_AI_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
TOOLBOX_NAME=<toolbox-name>

Program.cs (modèle clé) :

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable(
    "AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
    ?? throw new InvalidOperationException("TOOLBOX_NAME is not set.");

var credential = new DefaultAzureCredential();
AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant with access to toolbox tools.",
        name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxName);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Utilisez l’extension Microsoft Foundry Toolkit for Visual Studio Code afin de générer un exemple d’assistant hébergé déjà configuré pour fonctionner avec votre boîte à outils.

1. Sélectionnez Foundry Toolkit dans la barre d’activité.
2. Sous Mes ressources, développez Votre nom de projet>Outils.
3. Sous l’onglet Boîtes à outils , recherchez la boîte à outils que vous souhaitez utiliser, puis sélectionnez Modèle de code de structure Scaffold.
4. Dans la palette de commandes, choisissez un dossier de projet lorsque vous y êtes invité.
5. Ouvrez le fichier généré README.md et suivez les étapes d’installation, d’exécution locale et de déploiement pour l’échafaudage.

Le projet généré inclut le point d’entrée de l’agent hébergé, les fichiers de déploiement et un README.md contenant les étapes exactes de configuration, d’exécution et de déploiement.

Si vous souhaitez intégrer une boîte à outils dans un projet d’agent hébergé existant au lieu de générer un nouvel exemple, utilisez le point de terminaison MCP de boîte à outils avec les modèles Python ou .NET dans cette section.

Passez le point de terminaison de boîte à outils à votre agent

Après avoir créé la boîte à outils, récupérez son point de terminaison MCP en utilisant azd ai toolbox show et transmettez ce point de terminaison à votre code d’agent en tant que variable d’environnement. L’agent lit la variable au démarrage et l’utilise pour se connecter à la boîte à outils.

1. Obtenez le point de terminaison de la boîte à outils :

   azd ai toolbox show <toolbox-name> --output json
   

   Le endpoint champ de la réponse identifie la version sélectionnée. Utilisez-la pour tester cette version avant la promotion. Pour un agent qui doit utiliser default_version, créez le point de terminaison client sans version indiqué dans Récupérer le point de terminaison MCP de la boîte à outils.

2. Définissez le point de terminaison en tant que variable d’environnement que votre agent lit au démarrage :

   # .env (or however your runtime loads environment variables)
   TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/mcp?api-version=v1
   

3. Dans votre code d’agent, lisez TOOLBOX_ENDPOINT et connectez-vous à celui-ci avec un client MCP. Utilisez les modèles d’intégration Python ou .NET présentés plus haut dans cette section comme référence pour la configuration du client et la portée du jeton Entra (https://ai.azure.com/.default).

from azure.ai.projects.models import MCPToolboxTool

# Set require_approval on an MCP tool
toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    tools=[
        MCPToolboxTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="always",  # "always" | "never"
            project_connection_id="my-connection",
        )
    ],
)

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "always",
      "project_connection_id": "my-connection"
    }
  ]
}

MCPToolboxTool mcpTool = new(serverLabel: "myserver")
{
  ServerUri = new Uri("https://your-mcp-server.example.com"),
  ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(
    GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval),
};

const tools = [
  {
    type: "mcp",
    server_label: "myserver",
    server_url: "https://your-mcp-server.example.com",
    require_approval: "always",
    project_connection_id: "my-connection",
  },
];

Utilisez l’onglet Python, .NET, JavaScript, REST API ou Azure Developer CLI pour configurer require_approval dans la définition de votre boîte à outils. Le workflow d’extension Microsoft Foundry Toolkit pour Visual Studio Code dans cet article se concentre sur la création et l’utilisation de la boîte à outils dans Visual Studio Code.

resources:
  - kind: toolbox
    name: my-toolbox
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com
        require_approval: always
        project_connection_id: my-connection

# Create a new toolbox version
toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

ToolboxVersion toolboxVersion = await toolboxClient.CreateVersionAsync(
  name: "<toolbox-name>",
    tools: [tool],
    description: "Updated tools v2"
);
Console.WriteLine($"Created version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/<toolbox-name>/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Updated tools v2",
  "tools": [...]
}

const toolboxVersion = await project.toolboxes.createVersion(
  "<toolbox-name>",
  [/* tools array */],
  { description: "Updated tools v2" },
);
console.log(`Created version: ${toolboxVersion.version}`);

Utilisez l’onglet Python, .NET, JavaScript ou API REST pour créer une nouvelle version de boîte à outils. Dans cet article, le flux de travail de l’extension Microsoft Foundry Toolkit pour Visual Studio Code se concentre sur la création d’une boîte à outils et la génération du squelette d’un agent hébergé qui l’utilise.

Cette opération n'est pas prise en charge avec l'interface CLI Azure développeur. Pour créer une version de boîte à outils, utilisez l’onglet Python, .NET, API REST ou JavaScript.

# List all toolbox versions
versions = list(project.toolboxes.list_toolbox_versions(name="<toolbox-name>"))
for v in versions:
    print(f"{v.version} — created {v.created_at}")

List<ToolboxVersion> versions = await toolboxClient
    .GetToolboxVersionsAsync("<toolbox-name>")
    .ToListAsync();
Console.WriteLine($"Found {versions.Count} toolbox version(s).");
foreach (ToolboxVersion v in versions)
{
    Console.WriteLine($"  - {v.Name} ({v.Version})");
}

GET {project_endpoint}/toolboxes/<toolbox-name>/versions?api-version=v1
Authorization: Bearer {token}

const versions = project.toolboxes.listVersions("<toolbox-name>");
for await (const v of versions) {
  console.log(`${v.version} — created ${v.created_at}`);
}

Utilisez l’onglet Python, .NET, JavaScript ou API REST pour répertorier les versions de boîte à outils.

# The current default version is marked with *
azd ai toolbox version list <toolbox-name>

# Get a specific toolbox version
version_obj = project.toolboxes.get_toolbox_version(
    toolbox_name="<toolbox-name>",
    version="<version_id>",
)

ToolboxVersion versionObj = await toolboxClient.GetToolboxVersionAsync(
    "<toolbox-name>",
    "<version_id>"
);
Console.WriteLine($"Retrieved toolbox: {versionObj.Name} ({versionObj.Id})");

GET {project_endpoint}/toolboxes/<toolbox-name>/versions/{version}?api-version=v1
Authorization: Bearer {token}

const versionObj = await project.toolboxes.getVersion(
  "<toolbox-name>",
  "<version_id>",
);
console.log(`Retrieved version: ${versionObj.version}`);

Utilisez l’onglet Python, .NET, JavaScript ou API REST pour obtenir une version spécifique de la boîte à outils.

azd ai toolbox version get <toolbox-name> <version_id>

# Promote a version to default
toolbox = project.toolboxes.update(
    toolbox_name="<toolbox-name>",
    default_version="<version_id>",
)
print(f"Active version: {toolbox.default_version}")

ToolboxRecord record = await toolboxClient.UpdateToolboxAsync(
    "<toolbox-name>",
    "<version_id>"
);
Console.WriteLine($"Active version: {record.DefaultVersion}");

PATCH {project_endpoint}/toolboxes/<toolbox-name>?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "default_version": "<version_id>"
}

default_version ne peut pas être vide. Remplacez-le par une nouvelle version.

const toolbox = await project.toolboxes.update(
  "<toolbox-name>",
  "<version_id>",
);
console.log(`Active version: ${toolbox.default_version}`);

Utilisez l’onglet Python, .NET, JavaScript ou API REST pour promouvoir une version de boîte à outils par défaut.

Les versions de boîte à outils sont immuables. Utilisez cette option publish pour rendre toute version existante la nouvelle version par défaut :

# Roll back or forward to a specific version
azd ai toolbox publish <toolbox-name> <version_id> --no-prompt

publish est le seul chemin d’accès qui change default_version à partir de l’interface CLI ; les verbes mutants (connection add/remove, skill add/remove) créent toujours une nouvelle version sans la promouvoir.

# Delete a toolbox version
project.toolboxes.delete_toolbox_version(
    toolbox_name="<toolbox-name>",
    version="<version_id>",
)

await toolboxClient.DeleteToolboxVersionAsync(
    "<toolbox-name>",
    "<version_id>"
);

DELETE {project_endpoint}/toolboxes/<toolbox-name>/versions/{version}?api-version=v1
Authorization: Bearer {token}

await project.toolboxes.deleteVersion(
  "<toolbox-name>",
  "<version_id>",
);

Utilisez l’onglet Python, .NET, JavaScript ou API REST pour supprimer une version de boîte à outils.

Cette opération n'est pas prise en charge avec l'interface CLI Azure développeur. Pour supprimer une version de boîte à outils, utilisez l'onglet Python, .NET, REST API ou JavaScript.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import WebSearchToolboxTool

endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with guardrail",
    tools=[WebSearchToolboxTool()],
    policies={
        "rai_config": {
            "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>"
        }
    },
)
print(f"Created version: {toolbox_version.version}")

POST {endpoint}/toolboxes/{toolbox_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Toolbox with guardrail",
  "tools": [{ "type": "web_search" }],
  "policies": {
    "rai_config": {
      "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>"
    }
  }
}

#pragma warning disable AAIP001
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
DefaultAzureCredential credential = new();
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

var toolboxVersion = toolboxClient.CreateVersion(
  name: "my-toolbox",
    description: "Toolbox with guardrail",
    tools: [new WebSearchToolboxTool()],
    policies: new ToolboxPolicies
    {
        RaiConfig = new RaiConfig { RaiPolicyName = "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>" }
    });
Console.WriteLine($"Created version: {toolboxVersion.Version}");

const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [{ type: "web_search" }],
  {
    description: "Toolbox with guardrail",
    policies: {
      rai_config: {
        rai_policy_name: "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>",
      },
    },
  },
);
console.log(`Created version: ${toolboxVersion.version}`);

name: my-toolbox
description: Toolbox with guardrail
policies:
  rai_config:
    rai_policy_name: /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>
tools:
  - type: web_search

La configuration du garde-fou n’est pas encore disponible dans l’extension VS Code. Utilisez l’API REST, le Kit de développement logiciel (SDK) ou Azure Developer CLI pour configurer des garde-fous.

POST {endpoint}/toolboxes/{toolbox_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Foundry-Features: Skills=V1Preview

{
  "description": "Toolbox with a skill reference",
  "tools": [],
  "skills": [
    {
      "type": "skill_reference",
      "name": "greeting"
    }
  ]
}

Pour épingler une version spécifique :

{
  "skills": [
    {
      "type": "skill_reference",
      "name": "greeting",
      "version": "v1"
    }
  ]
}

from azure.ai.projects.models import ToolboxSkillReference

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with a skill reference",
    tools=[],
    skills=[
        ToolboxSkillReference(name="greeting"),              # use default version
        # ToolboxSkillReference(name="greeting", version="1"),  # pin to version 1
    ],
)
print(f"Created toolbox version: {toolbox_version.id}")

#pragma warning disable AAIP001
// Reuse the AgentToolboxes client (toolboxClient) from Step 1.
ToolboxSkillReference skillRef = new("greeting");
// To pin a version: new ToolboxSkillReference("greeting") { Version = "1" }

ToolboxVersion toolboxVersion = toolboxClient.CreateVersion(
    name: "my-toolbox",
    tools: [],
    skills: [skillRef],
    description: "Toolbox with a skill reference"
);
Console.WriteLine($"Created toolbox version: {toolboxVersion.Id}");

const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [],
  {
    description: "Toolbox with a skill reference",
    skills: [
      { type: "skill_reference", name: "greeting" },
      // { type: "skill_reference", name: "greeting", version: "v1" },  // pin to v1
    ],
  },
);
console.log(`Created toolbox version: ${toolboxVersion.id}`);

Azure Developer CLI prend en charge les références à des compétences à deux endroits : de manière déclarative, sous la forme d’un bloc skills: de niveau supérieur dans le fichier YAML azd ai toolbox create --from-file, et de manière impérative avec les verbes azd ai toolbox skill add/list/remove. Chaque référence prend un name (obligatoire) et une valeur facultative version (chaîne). Omettez version pour suivre le default_version de la compétence ; indiquez une chaîne de version pour verrouiller la toolbox sur un instantané immuable.

Déclarer des compétences lorsque vous créez la boîte à outils

# my-toolbox.yaml
description: Toolbox with skill references
connections:
  - name: my-gh-conn
skills:
  - name: greeting              # follows the skill's default version
  - name: review-checklist
    version: "2"               # pin to skill version 2

azd ai toolbox create my-toolbox --from-file ./my-toolbox.yaml --no-prompt

Ajouter, répertorier et supprimer des compétences sur une boîte à outils existante

# Add a skill (follows default version)
azd ai toolbox skill add my-toolbox greeting

# Add a skill pinned to a specific version
azd ai toolbox skill add my-toolbox review-checklist@2

# Add multiple skills from a file (same shape as the create YAML's skills block)
azd ai toolbox skill add my-toolbox --from-file ./skills.yaml

# List skill references on the current default version
azd ai toolbox skill list my-toolbox --output table

# Remove a skill (--force skips the confirmation prompt; multiple names allowed)
azd ai toolbox skill remove my-toolbox greeting --force

skill list affiche uniquement la version par défaut. Les compétences épinglées affichent leur version ; les compétences non épinglées affichent (default). Pour examiner les compétences d’une version en attente, exécutez azd ai toolbox show <toolbox> --version <n> --output json et lisez le tableau skills.

Les noms de compétence doivent correspondre ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ (lettres minuscules, chiffres et traits d’union ; 64 caractères maximum ; aucun trait d’union de début ou de fin). Une fin @ dans <name>@<version> (une version vide) est rejetée.

Les références de compétence ne sont actuellement pas configurables via l’extension VS Code. Utilisez l’API REST ou le Kit de développement logiciel (SDK) pour configurer des compétences.

Valider la découverte des compétences

Après avoir attaché des compétences à une version de boîte à outils, vérifiez que vous pouvez les découvrir via le point de terminaison MCP de la boîte à outils à l’aide du KIT de développement logiciel (SDK) mcP Python :

import asyncio
from azure.identity import DefaultAzureCredential
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def list_skills():
    credential = DefaultAzureCredential()
    token = credential.get_token("https://ai.azure.com/.default").token
    toolbox_url = "{endpoint}/toolboxes/my-toolbox/mcp?api-version=v1"
    headers = {
        "Authorization": f"Bearer {token}",
    }
    async with streamablehttp_client(toolbox_url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            resources = await session.list_resources()
            for resource in resources.resources:
                print(f"Skill: {resource.uri} - {resource.name}")

asyncio.run(list_skills())

Les compétences apparaissent en tant que ressources MCP avec des URI au format skill://{name}.

Consommer des compétences depuis un agent (Microsoft Agent Framework, .NET)

Dans .NET, utilisez AgentSkillsProviderBuilder().UseMcpSkills(mcpClient) à partir du Kit de développement logiciel (SDK) Microsoft Agent Framework pour découvrir les compétences basées sur MCP à partir d’un point de terminaison de boîte à outils et les injecter en tant que AIContextProviders sur l’agent. L’agent charge ensuite les instructions de chaque compétence lors de l’exécution lorsque le modèle décide qu’il est pertinent. L’hôte suivant Program.cs héberge l’agent avec la couche d’hébergement Responses (AddFoundryResponses et MapFoundryResponses).

using System.Net.Http.Headers;
using Azure.AI.Projects;
using Azure.Core;
using Azure.Identity;
using DotNetEnv;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

// Load .env file if present (for local development).
Env.TraversePath().Load();

string projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT environment variable is not set.");

string deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_MODEL_DEPLOYMENT_NAME environment variable is not set.");

string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
    ?? throw new InvalidOperationException("TOOLBOX_NAME environment variable is not set.");

// Build the Foundry Toolbox MCP URL from the project endpoint and toolbox name.
string toolboxMcpServerUrl = $"{projectEndpoint.TrimEnd('/')}/toolboxes/{toolboxName}/mcp?api-version=v1";

TokenCredential credential = new DefaultAzureCredential();

// HttpClient that attaches a fresh Foundry bearer token to every request.
// CheckCertificateRevocationList = true satisfies CA5399.
using var httpClient = new HttpClient(
    new BearerTokenHandler(credential, "https://ai.azure.com/.default")
    {
        CheckCertificateRevocationList = true,
    });

Console.WriteLine($"Connecting to Foundry Toolbox '{toolboxName}' MCP server...");

// Connect to the Foundry Toolbox MCP endpoint.
await using var mcpClient = await McpClient.CreateAsync(
    new HttpClientTransport(
        new HttpClientTransportOptions
        {
            Endpoint = new Uri(toolboxMcpServerUrl),
            Name = toolboxName,
            TransportMode = HttpTransportMode.StreamableHttp,
        },
        httpClient));

// AgentSkillsProvider implements progressive disclosure over the MCP-discovered skills:
// names and descriptions are advertised in the system prompt, and the full skill body
// (and any supplementary resources) is loaded on demand when the model decides it is
// relevant.
var skillsProvider = new AgentSkillsProviderBuilder()
    .UseMcpSkills(mcpClient)
    .Build();

AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "foundry-toolbox-mcp-skills",
        Description = "Agent that discovers MCP-based skills from a Foundry Toolbox and exposes them via AgentSkillsProvider.",
        ChatOptions = new ChatOptions
        {
            ModelId = deployment,
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [skillsProvider],
    });

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

// HttpClientHandler that attaches a fresh Foundry bearer token to every outgoing request.
internal sealed class BearerTokenHandler(TokenCredential credential, string scope) : HttpClientHandler
{
    private readonly TokenRequestContext _tokenContext = new([scope]);

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        AccessToken token = await credential.GetTokenAsync(this._tokenContext, cancellationToken).ConfigureAwait(false);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
        return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }
}

Pour obtenir l’exemple complet, y compris les fichiers projet et les étapes de déploiement, consultez l’exemple Compétences dans la boîte à outils.