Creare, testare e distribuire una casella degli strumenti in Foundry

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool, ToolboxSearchPreviewTool, WebSearchTool

# 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_toolbox_version(
    name="my-toolbox",
    description="Toolbox with web search and an MCP server",
    tools=[
        WebSearchTool(),
        MCPTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="never",
            project_connection_id="my-key-auth-connection",
        ),
        ToolboxSearchPreviewTool(),
    ],
)
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();

ProjectsAgentTool webTool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool());

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com"),
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.NeverRequireApproval
    )
));

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

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "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_preview"
    }
  ]
}

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_preview" },
  ],
  {
    description: "Toolbox with web search, MCP, and tool search",
  },
);
console.log(`Created toolbox: ${toolboxVersion.name}, version: ${toolboxVersion.version}`);

Usare l'estensione Microsoft Foundry Toolkit for Visual Studio Code per creare e pubblicare una casella degli strumenti dalla visualizzazione Tools.

1. Selezionare Foundry Toolkit nella barra delle attività.
2. Sotto Risorse personali, espandere Il nome del tuo progetto>Strumenti.
3. Selezionare l'icona + Aggiungi casella degli strumenti .
4. Nella scheda Compila casella degli strumenti personalizzata immettere il nome e la descrizione della casella degli strumenti e aggiungere gli strumenti desiderati.
5. Per abilitare il routing degli strumenti basato sulle finalità, selezionare Ricerca degli strumenti.
6. Seleziona Pubblica.

La pubblicazione di una nuova casella degli strumenti crea la prima versione. Tale versione diventa automaticamente la versione predefinita.

Con il bundle di estensioni unificato microsoft.foundry (vedere Prerequisiti), creare una casella degli strumenti in due passaggi:

1. Usare azd ai connection create per registrare ogni connessione di progetto a cui fa riferimento la casella degli strumenti (una chiamata per ogni record di credenziali).
2. Usare azd ai toolbox create --from-file <toolbox.yaml> per creare la casella degli strumenti. YAML fa riferimento alle connessioni in base al nome e non incorpora mai le credenziali.

Il modello è lo stesso per ogni tipo di connessione e tipo di autenticazione:

1. Impostare il progetto attivo una volta per ogni shell:

   azd ai project set $PROJECT_ENDPOINT
   

2. Creare una connessione con azd ai connection create. I flag differiscono per tipo di autenticazione, ma la forma del comando è sempre:

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

   Usare azd ai connection list e azd ai connection show <name> per controllare le connessioni e azd ai connection delete <name> --force rimuoverle.

3. Creare uno standard YAML della casella degli strumenti che faccia riferimento a una o più connessioni esistenti in base al nome. Il file YAML non include mai credenziali:

   # 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_preview
     # 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: bing_custom_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
   

   Almeno uno di connections, skillso tools deve essere non vuoto. I riferimenti alle competenze devono puntare alle competenze già esistenti nello stesso progetto Foundry; vedere Usare le competenze in Foundry per crearle con azd ai skill create. Per informazioni dettagliate sulla configurazione della ricerca degli strumenti end-to-end, vedere Usare la ricerca degli strumenti.

4. Crea la cassetta degli attrezzi da quel file:

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

   La prima versione diventa automaticamente l'impostazione predefinita. Usare azd ai toolbox list, azd ai toolbox show <name>azd ai toolbox version list <name>, e azd ai toolbox delete <name> --force per gestire le caselle degli strumenti.

Esempio: server MCP con autenticazione basata su chiave

# 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

Nell'estensione Microsoft Foundry Toolkit for Visual Studio Code, copiare l'endpoint consumer della casella degli strumenti dalla visualizzazione Caselle degli strumenti.

1. Selezionare Foundry Toolkit nella barra delle attività.
2. Sotto Risorse personali, espandere Il nome del tuo progetto>Strumenti.
3. Nella scheda Barra degli strumenti, trova la tua barra degli strumenti.
4. Nella colonna ENDPOINT URL copiare l'endpoint.

Il valore URL endpoint è l'endpoint consumer della casella degli strumenti. Per costruire un endpoint specifico della versione, usare il modello di sviluppo illustrato nella tabella precedente.

Installare l'SDK client MCP:

pip install mcp

Connettersi agli strumenti ed elencarli

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

Usare l'endpoint specifico della versione (/versions/{version}/mcp) per convalidare una versione prima di promuoverla.

1. Inizializzare la sessione 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. Inviare la notifica inizializzata:

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. Elencare gli strumenti disponibili:

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. Chiamare uno strumento:

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

Installare l'SDK client MCP:

npm install @modelcontextprotocol/sdk

Connettersi agli strumenti ed elencarli

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

Usare l'endpoint del Passaggio 2 con un esempio di agente ospitato sottoposto a scaffolding per convalidare il caricamento della casella degli strumenti in VS Code.

1. In Foundry Toolkit, sotto Le mie risorse>Il nome del progetto>Strumenti, individua la casella degli strumenti che vuoi testare.
2. Selezionare Modello di codice scaffold.
3. Scegliere una cartella del progetto quando richiesto.
4. Seguire le istruzioni README.md generate per installare le dipendenze, configurare le variabili di ambiente ed eseguire l'esempio in locale.
5. Usare Agent Inspector o eseguire python main.py per confermare il caricamento e la risposta degli strumenti della casella degli strumenti.

Per la convalida specifica della versione prima di alzare di livello una nuova versione della casella degli strumenti, usare la scheda API REST o Python in questo passaggio.

LangGraph

Vedere l'esempio completo per l'implementazione completa.

File .env:

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 (modello chiave):

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Microsoft Agent Framework

Utilizzare MCPStreamableHTTPTool dall'Agent Framework SDK per connettersi direttamente all'endpoint MCP del toolbox.

File .env:

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 (modello chiave):

# Auth: wrap token provider in an httpx.Auth subclass
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
http_client = httpx.AsyncClient(
    auth=_ToolboxAuth(token_provider),
    timeout=120.0,
)

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

# Connect MCPStreamableHTTPTool to the toolbox endpoint
mcp_tool = MCPStreamableHTTPTool(
    name="toolbox",
    url=TOOLBOX_ENDPOINT,
    http_client=http_client,
    load_prompts=False,
)

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

Vedere l'esempio completo per l'implementazione completa.

COPILOT SDK

Usare GitHub Copilot SDK per creare un agente basato sulla casella degli strumenti che collega la chiamata dello strumento di Copilot all'endpoint MCP della casella degli strumenti Foundry.

File .env:

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 (modello chiave — bridge 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"],
)

Microsoft Agent Framework

Usare ResponsesServer da Agent Framework SDK con un ToolboxMcpClient personalizzato per individuare e richiamare gli strumenti della casella tramite l'endpoint MCP.

Variabili di ambiente:

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

Program.cs (modello chiave):

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

// Azure OpenAI endpoint and model deployment
var openAiEndpoint = "https://<account>.services.ai.azure.com";
var deployment = "gpt-4o";  // supports all toolbox tool types

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

// Azure OpenAI client
var credential = new DefaultAzureCredential();
var openAIClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential);
var chatClient = openAIClient.GetChatClient(deployment);

// Toolbox MCP client — discovers tools via tools/list, calls them via tools/call
var toolboxClient = new ToolboxMcpClient(toolboxEndpoint, credential);

ResponsesServer.Run<ToolboxHandler>(configure: builder =>
{
    builder.Services.AddSingleton(new AgentConfig(chatClient, toolboxClient));
});

ToolboxMcpClient avvolge le chiamate dirette JSON-RPC verso l'endpoint MCP. ToolboxHandler connette le chiamate dello strumento LLM al client MCP usando un ciclo standard per la chiamata degli strumenti. Per l'implementazione completa di entrambe le classi, vedere l'esempio completo.

Usare l'estensione Microsoft Foundry Toolkit for Visual Studio Code per eseguire lo scaffolding di un esempio di agente ospitato già collegato alla casella degli strumenti.

1. Selezionare Foundry Toolkit nella barra delle attività.
2. Sotto Risorse personali, espandere Il nome del tuo progetto>Strumenti.
3. Nella scheda Caselle degli strumenti, individuare la casella degli strumenti da usare, quindi selezionare Scaffolding modello di codice.
4. Nel riquadro comandi scegliere una cartella di progetto quando richiesto.
5. Aprire il file generato README.md e seguire i passaggi di installazione, esecuzione locale e distribuzione per il scaffold.

Il progetto generato include il punto di ingresso dell'agente ospitato, i file di distribuzione e un oggetto README.md con la procedura esatta di installazione, esecuzione e distribuzione.

Se si vuole integrare una casella degli strumenti in un progetto agente ospitato esistente anziché generare un nuovo esempio, usare l'endpoint copiato dal passaggio 2 con i modelli Python o .NET in questa sezione.

Passa l'endpoint del toolbox al tuo agente

Dopo aver creato la casella degli strumenti nel passaggio 1, recuperare l'endpoint MCP con azd ai toolbox show e passare tale endpoint al codice dell'agente come variabile di ambiente. L'agente legge la variabile all'avvio e la usa per connettersi alla casella degli strumenti.

1. Recupera l'endpoint di Toolbox:

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

   Il campo mcp_endpoint nella risposta è l'endpoint consumer che si risolve sempre nella default_version della casella degli strumenti.

2. Impostare l'endpoint come variabile di ambiente che l'agente legge all'avvio:

   # .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. Nel codice dell'agente, leggi TOOLBOX_ENDPOINT e connettiti ad esso con un client MCP. Usa i modelli di integrazione di Python o di .NET presentati in precedenza in questa sezione come riferimento per la configurazione del client e per il token Entra (ambito https://ai.azure.com/.default).

from azure.ai.projects.models import MCPTool

# Set require_approval on an MCP tool
toolbox_version = project.toolboxes.create_toolbox_version(
    name="my-toolbox",
    tools=[
        MCPTool(
            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"
    }
  ]
}

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    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",
  },
];

Usare la scheda Python, .NET, JavaScript, API REST o azd per configurare require_approval nella definizione della casella degli strumenti. Il flusso di lavoro dell'estensione Microsoft Foundry Toolkit per Visual Studio Code in questo articolo è incentrato sulla creazione e l'utilizzo della casella degli strumenti in 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_toolbox_version(
    name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "<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}`);

Usare la scheda Python, .NET, JavaScript o API REST per creare una nuova versione della casella degli strumenti. Il flusso di lavoro dell'estensione Microsoft Foundry Toolkit per Visual Studio Code in questo articolo è incentrato sulla creazione di una casella degli strumenti e sullo scaffolding di un agente ospitato che lo utilizza.

Questa operazione non è supportata con l'interfaccia della riga di comando per sviluppatori Azure. Per creare una versione della casella degli strumenti, usare la scheda Python, .NET, API REST o 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}`);
}

Usare la scheda Python, .NET, JavaScript o API REST per elencare le versioni della casella degli strumenti.

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

Usare la scheda Python, .NET, JavaScript o API REST per ottenere una versione specifica della casella degli strumenti.

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 non può essere vuoto. Sostituirlo con una nuova versione.

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

Usare la scheda Python, .NET, JavaScript o API REST per impostare la versione della casella degli strumenti come impostazione predefinita.

Le versioni della casella degli strumenti non sono modificabili. Usare publish per rendere qualsiasi versione esistente il nuovo valore predefinito:

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

publish è l'unico percorso che cambia default_version dall'interfaccia della riga di comando; la modifica dei verbi (connection add/remove, skill add/remove) crea sempre una nuova versione senza promuoverla.

# 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>",
);

Usare la scheda Python, .NET, JavaScript o API REST per eliminare una versione della casella degli strumenti.

Questa operazione non è supportata con l'interfaccia della riga di comando per sviluppatori Azure. Per eliminare una versione della casella degli strumenti, usare la scheda Python, .NET, API REST o JavaScript .

Autenticazione basata su chiave:

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

Nessuna autenticazione (server MCP pubblico):

{
  "description": "Public MCP server",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com"
    }
  ]
}

Autenticazione OAuth o basata su identità:

Per OAuth (connettore gestito, registrazione app personalizzata), identità dell'agente o autenticazione del token Entra utente, creare prima di tutto la connessione appropriata nel progetto Foundry, quindi farvi riferimento con project_connection_id:

{
  "description": "MCP server with OAuth/identity auth",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "project_connection_id": "<OAUTH_OR_IDENTITY_CONNECTION_NAME>"
    }
  ]
}

La connessione authType determina il flusso di autenticazione. I tipi di autenticazione di connessione supportati per MCP includono CustomKeys, OAuth2 (gestito o personalizzato), AgenticIdentityTokene UserEntraToken. Vedere la scheda azd per esempi di configurazione della connessione per ogni tipo di autenticazione.

from azure.ai.projects.models import MCPTool

tools = [
    MCPTool(
        server_label="myserver",
        server_url="https://your-mcp-server.example.com",
        project_connection_id="my-mcp-connection",
    )
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com")
));

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "my-mcp-toolbox"
);

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

Crea una connessione di progetto per il tuo server MCP con il tipo di autenticazione adatto al tuo scenario, quindi fai riferimento a essa in un file YAML minimale del toolbox.

Passaggio 1: Creare la connessione

PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
azd ai project set $PROJECT_ENDPOINT

Selezionare la variante di autenticazione necessaria:

# No auth — public MCP server
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://learn.microsoft.com/api/mcp \
  --auth-type none

# Custom-keys header (for example, GitHub PAT)
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://api.githubcopilot.com/mcp/ \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer $GITHUB_PAT"

# OAuth — bring your own app registration
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://your-mcp-server.example.com \
  --auth-type oauth2 \
  --authorization-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "<scope1> <scope2>"

# User Entra token (managed user identity passthrough; for example, Microsoft Fabric)
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://api.fabric.microsoft.com/v1/mcp/fabricaihub/integrations/m365 \
  --auth-type user-entra-token \
  --audience https://analysis.windows.net/powerbi/api

# Project managed identity — the project's system-assigned MI
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://<resource>.cognitiveservices.azure.com/language/mcp \
  --auth-type project-managed-identity \
  --audience https://cognitiveservices.azure.com

# Agentic identity — the agent's per-project identity
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://<resource>.cognitiveservices.azure.com/language/mcp \
  --auth-type agentic-identity \
  --audience https://cognitiveservices.azure.com

Per l'autenticazione basata sull'identità (user-entra-token, project-managed-identity, agentic-identity), assegnare all'identità corrispondente il ruolo RBAC richiesto sulla risorsa di destinazione prima di chiamare la casella degli strumenti.

Passaggio 2: Definire la casella degli strumenti

# my-toolbox.yaml
description: MCP server tools
connections:
  - name: my-mcp-conn

Passaggio 3. Creare la casella degli strumenti

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Built-in web search",
  "tools": [
    {
      "type": "web_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>"
    }
  ]
}

Con una connessione Grounding con Ricerca personalizzata Bing:

{
  "description": "Custom Bing Search instance",
  "tools": [
    {
      "type": "web_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "web_search": {
        "custom_search_configuration": {
          "project_connection_id": "<BING_CONNECTION_NAME>",
          "instance_name": "<BING_INSTANCE_NAME>"
        }
      }
    }
  ]
}

from azure.ai.projects.models import WebSearchTool

tools = [
    WebSearchTool()
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool()
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Built-in web search"
);

const tools = [
  {
    type: "web_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
  },
];

Predefinito (ancoraggio con Ricerca Bing, nessuna connessione necessaria):

# my-toolbox.yaml
description: Web search toolbox
tools:
  - type: web_search

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Grounding con Ricerca personalizzata Bing:

# Step 1. Create the Bing Custom Search connection
azd ai connection create my-bing-custom \
  --kind GroundingWithCustomSearch \
  --target https://api.bing.microsoft.com/ \
  --auth-type api-key \
  --key "<bing-custom-search-key>"

--kind GroundingWithCustomSearch richiede l'uso esatto delle maiuscole e minuscole (PascalCase).

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Bing Custom Search toolbox
connections:
  - name: my-bing-custom
    instance_name: your-bing-custom-instance

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Azure AI Search over my data",
  "tools": [
    {
      "type": "azure_ai_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<INDEX_NAME>",
            "project_connection_id": "<CONNECTION_NAME>"
          }
        ]
      }
    }
  ]
}

from azure.ai.projects.models import AzureAISearchTool

tools = [
    AzureAISearchTool(
        index_name="<INDEX_NAME>",
        project_connection_id="<CONNECTION_NAME>",
    )
]

ProjectsAgentTool tool = new AzureAISearchTool(
    new AzureAISearchToolOptions(
        indexes: [
            new AzureAISearchIndexResource(
                indexName: "<INDEX_NAME>",
                projectConnectionId: "<CONNECTION_NAME>"
            )
        ]
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Azure AI Search over my data"
);

const tools = [
  {
    type: "azure_ai_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    azure_ai_search: {
      indexes: [
        {
          index_name: "<INDEX_NAME>",
          project_connection_id: "<CONNECTION_NAME>",
        },
      ],
    },
  },
];

# Step 1. Create the Azure AI Search connection
azd ai connection create my-search \
  --kind cognitive-search \
  --target "https://<your-search>.search.windows.net/" \
  --auth-type api-key \
  --key "<aisearch-admin-key>"

cognitive-search connessioni accettano anche --auth-type project-managed-identity (senza chiave). Quando si usa l'identità gestita del progetto, assegnare all'identità gestita assegnata dal sistema del progetto il ruolo Search Index Data Reader nel servizio di ricerca.

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Azure AI Search toolbox
connections:
  - name: my-search
    index: your-index-name

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Code interpreter for data analysis",
  "tools": [
    {
      "type": "code_interpreter",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "container": {
            "type": "auto",
            "file_ids": ["<FILE_ID>"]
        }
    }
  ]
}

from azure.ai.projects.models import CodeInterpreterTool

tools = [
    CodeInterpreterTool()
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateCodeInterpreterTool(
        new CodeInterpreterToolContainer()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Code interpreter for data analysis"
);

const tools = [
  {
    type: "code_interpreter",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    container: {
      type: "auto",
      file_ids: ["<FILE_ID>"],
    },
  },
];

L'interprete del codice è senza connessione. Dichiararlo direttamente sotto tools:.

# my-toolbox.yaml
description: Code interpreter toolbox
tools:
  - type: code_interpreter
    container: { type: auto }

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Search over uploaded documents",
  "tools": [
    {
      "type": "file_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "file_search": {
        "vector_store_ids": ["<VECTOR_STORE_ID>"]
      }
    }
  ]
}

from azure.ai.projects.models import FileSearchTool

tools = [
    FileSearchTool(
        vector_store_ids=["<VECTOR_STORE_ID>"]
    )
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateFileSearchTool(
        vectorStoreIds: ["<VECTOR_STORE_ID>"]
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Search over uploaded documents"
);

const tools = [
  {
    type: "file_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    file_search: {
      vector_store_ids: ["<VECTOR_STORE_ID>"],
    },
  },
];

Ricerca file è senza connessione, ma richiede un ID archivio vettoriale esistente. Dichiararlo direttamente sotto tools:.

# my-toolbox.yaml
description: File search toolbox
tools:
  - type: file_search
    vector_store_ids:
      - vs_xxxxxxxxxxxx

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Autenticazione anonima:

{
  "description": "REST API via OpenAPI spec",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "anonymous"
        }
      }
    }
  ]
}

Autenticazione connessione progetto:

Usare questo modello quando l'API richiede una chiave o un token archiviato in una connessione di progetto Foundry.

{
  "description": "REST API with connection-based auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "connection",
          "security_scheme": {
            "project_connection_id": "<CONNECTION_NAME>"
          }
        }
      }
    }
  ]
}

Autenticazione dell'identità gestita:

Usare questo modello quando l'API di destinazione esegue l'autenticazione tramite Microsoft Entra ID. L'identità gestita del progetto Foundry chiama l'API per conto dell'agente. Assicurarsi che l'identità gestita disponga del ruolo di controllo degli accessi in base ai ruoli necessario nel servizio di destinazione prima di usare questo schema.

{
  "description": "REST API with managed identity auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "managed_identity",
          "security_scheme": {
            "audience": "<TARGET_SERVICE_AUDIENCE>"
          }
        }
      }
    }
  ]
}

from azure.ai.projects.models import OpenAPITool

tools = [
    OpenAPITool(
        name="my-api",
        spec={"<paste OpenAPI spec object here>"},
        auth={"type": "anonymous"},
    )
]

BinaryData specBytes = BinaryData.FromString("<OpenAPI spec JSON>");
ProjectsAgentTool tool = new OpenAPITool(
    new OpenApiFunctionDefinition(
        name: "my-api",
        spec: specBytes,
        openApiAuthentication: new OpenApiAnonymousAuthDetails()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "REST API via OpenAPI spec"
);

const tools = [
  {
    type: "openapi",
    openapi: {
      name: "my-api",
      spec: { /* paste OpenAPI spec object here */ },
      auth: {
        type: "anonymous",
      },
    },
  },
];

Gli strumenti OpenAPI incorporano la specifica direttamente in tools:. L'autenticazione basata sulla connessione (connection_auth) fa riferimento a una connessione di progetto. Gli strumenti OpenAPI anonimi non necessitano di alcuna connessione.

Passaggio 1: (Facoltativo) Creare la connessione di autenticazione

Ignorare questo passaggio per gli strumenti OpenAPI anonimi.

# API-key auth (passed by the platform on every call)
azd ai connection create my-api-conn \
  --kind remote-tool \
  --target https://api.example.com \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer <token>"

Gli strumenti OpenAPI accettano anche connessioni --auth-type oauth2. Vedere la sezione MCP precedente per il set completo di azd ai connection create flag.

Passaggio 2: Definire la casella degli strumenti

La specifica OpenAPI è in linea sotto tools[].openapi.spec.

# my-toolbox.yaml
description: OpenAPI toolbox
tools:
  - type: openapi
    name: my-api
    openapi:
      name: my-api
      spec:
        openapi: "3.0.1"
        info:
          title: "My API"
          version: "1.0"
        servers:
          - url: https://api.example.com/v1
        paths:
          /search:
            get:
              operationId: search
              parameters:
                - name: query
                  in: query
                  required: true
                  schema:
                    type: string
              responses:
                "200":
                  description: OK
      auth:
        type: connection_auth
        connection_id: my-api-conn

Per le API anonime, sostituire il auth: blocco con:

      auth:
        type: anonymous
        security_scheme:
          type: anonymous

Passaggio 3. Creare la casella degli strumenti

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Delegate tasks to a specialist agent",
  "tools": [
    {
      "type": "a2a_preview",
      "name": "<AGENT_NAME>",
      "description": "<What this agent does>",
      "base_url": "<AGENT_BASE_URL>",
      "project_connection_id": "<CONNECTION_NAME>"
    }
  ]
}

from azure.ai.projects.models import A2APreviewTool

tools = [
    A2APreviewTool(
        name="<AGENT_NAME>",
        description="<What this agent does>",
        base_url="<AGENT_BASE_URL>",
        project_connection_id="<CONNECTION_NAME>",
    )
]

ProjectsAgentTool tool = new A2APreviewTool()
{
    ProjectConnectionId = "<CONNECTION_NAME>",
};

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Delegate tasks to a specialist agent"
);

const tools = [
  {
    type: "a2a_preview",
    name: "<AGENT_NAME>",
    description: "<What this agent does>",
    base_url: "<AGENT_BASE_URL>",
    project_connection_id: "<CONNECTION_NAME>",
  },
];

Creare una connessione remote-a2a per l'agente remoto, quindi farvi riferimento in un file YAML minimale della casella degli strumenti.

Passaggio 1: Creare la connessione

Selezionare la variante di autenticazione necessaria:

# No auth
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type none

# Custom-keys header
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer <token>"

# OAuth — bring your own app registration
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type oauth2 \
  --authorization-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "<scope1> <scope2>"

# User Entra token (managed user identity passthrough)
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type user-entra-token \
  --audience "<entra-audience>"

# Project managed identity
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type project-managed-identity \
  --audience "<entra-audience>"

# Agentic identity
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type agentic-identity \
  --audience "<entra-audience>"

Passaggio 2: Definire la casella degli strumenti

# my-toolbox.yaml
description: Agent-to-Agent toolbox
connections:
  - name: my-a2a-conn

Passaggio 3. Creare la casella degli strumenti

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Fabric IQ for enterprise Fabric data access",
  "tools": [
    {
      "type": "fabric_iq_preview",
      "project_connection_id": "<CONNECTION_NAME>",
      "server_label": "<SERVER_LABEL>",
      "server_url": "<SERVER_URL>"
    }
  ]
}

tools = [
    {
        "type": "fabric_iq_preview",
        "project_connection_id": "<CONNECTION_NAME>",
        "server_label": "<SERVER_LABEL>",
        "server_url": "<SERVER_URL>",
    }
]

Fabric IQ è gestito come endpoint MCP. Crea una connessione remote-tool al server Fabric IQ con user-entra-token (opzione consigliata; l'identità del chiamante viene inoltrata a Fabric), quindi fai riferimento a essa da un file YAML minimo del toolbox.

# Step 1. Create the Fabric IQ connection
azd ai connection create my-fabric-conn \
  --kind remote-tool \
  --target https://api.fabric.microsoft.com/v1/mcp/fabricaihub/integrations/m365 \
  --auth-type user-entra-token \
  --audience https://analysis.windows.net/powerbi/api

Le connessioni remote-tool accettano anche --auth-type oauth2. Per il set di flag completo, vedere la sezione MCP precedente.

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Fabric IQ (semantic model)
tools:
  - type: fabric_iq_preview
    project_connection_id: my-fabric-conn

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Toolbox with intent-based tool routing",
  "tools": [
    {
      "type": "toolbox_search_preview"
    }
  ]
}

tools = [
    {"type": "toolbox_search_preview"}
]

La ricerca degli strumenti è senza connessione. Dichiararlo direttamente sotto tools:.

# my-toolbox.yaml
description: Toolbox with intent-based tool routing
tools:
  - type: toolbox_search_preview

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

In Foundry Toolkit for Visual Studio Code selezionare Tool search nella scheda Build a Custom Toolbox quando si crea o si modifica una casella degli strumenti. Per altre informazioni, vedere Abilitare la ricerca degli strumenti in una casella degli strumenti.

{
  "description": "Work IQ for Microsoft 365 data access",
  "tools": [
    {
      "type": "work_iq_preview",
      "project_connection_id": "<CONNECTION_NAME>"
    }
  ]
}

tools = [
    {
        "type": "work_iq_preview",
        "project_connection_id": "<CONNECTION_NAME>",
    }
]

Work IQ è gestito come endpoint A2A. Crea una connessione remote-a2a al server Work IQ con oauth2, quindi fai riferimento a essa da un file YAML minimo del toolbox.

# Step 1. Create the Work IQ connection
azd ai connection create my-workiq-conn \
  --kind remote-a2a \
  --target https://agent365.svc.cloud.microsoft/agents/agents/workiq \
  --auth-type oauth2 \
  --authorization-url https://login.microsoftonline.com/common/oauth2/v2.0/authorize \
  --token-url https://login.microsoftonline.com/common/oauth2/v2.0/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "<scope1> <scope2>"

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Work IQ toolbox
tools:
  - type: work_iq_preview
    project_connection_id: my-workiq-conn

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Perform actions using a real web browser",
  "tools": [
    {
      "type": "browser_automation_preview",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "browser_automation_preview": {
        "connection": {
          "project_connection_id": "<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>"
        }
      }
    }
  ]
}

from azure.ai.projects.models import (
    BrowserAutomationPreviewTool,
    BrowserAutomationToolParameters,
    BrowserAutomationToolConnectionParameters,
)

tools = [
    BrowserAutomationPreviewTool(
        browser_automation_preview=BrowserAutomationToolParameters(
            connection=BrowserAutomationToolConnectionParameters(
                project_connection_id="<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>",
            )
        )
    )
]

ProjectsAgentTool tool = new BrowserAutomationPreviewTool(
    new BrowserAutomationToolOptions(
        new BrowserAutomationToolConnectionParameters("<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>")
    )
);

const tools = [
  {
    type: "browser_automation_preview",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    browser_automation_preview: {
      connection: {
          project_connection_id: "<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>"
      }
    }
  },
];

# Step 1. Create the Playwright Workspace connection
azd ai connection create my-browser-conn \
  --kind PlaywrightWorkspace \
  --target wss://your-browser-endpoint.api.playwright.microsoft.com/playwrightworkspaces/browsers \
  --auth-type api-key \
  --key "<playwright-workspaces-access-token>"

--kind PlaywrightWorkspace richiede l'uso esatto delle maiuscole e minuscole (PascalCase).

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Browser Automation toolbox
tools:
  - type: browser_automation_preview
    project_connection_id: my-browser-conn

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

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

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

toolbox_version = project.beta.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with guardrail",
    tools=[WebSearchTool()],
    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.CreateToolboxVersion(
    toolboxName: "my-toolbox",
    description: "Toolbox with guardrail",
    tools: [new WebSearchTool()],
    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.beta.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 configurazione di Guardrail non è ancora disponibile nell'estensione VS Code. Usare l'API REST, l'SDK o azd per configurare le protezioni.

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"
    }
  ]
}

Per aggiungere una versione specifica:

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

from azure.ai.projects.models import ToolboxSkillReference

toolbox_version = project.beta.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with a skill reference",
    tools=[],
    skills=[
        ToolboxSkillReference(name="greeting"),              # use default version
        # ToolboxSkillReference(name="greeting", version="v1"),  # pin to v1
    ],
)
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 = "v1" }

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

const toolboxVersion = await project.beta.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}`);

La CLI di Azure Developer supporta i riferimenti alle skill in due punti: in modo dichiarativo come blocco skills: di primo livello nel file YAML azd ai toolbox create --from-file e in modo imperativo tramite i verbi azd ai toolbox skill add/list/remove. Ogni riferimento richiede un name (obbligatorio) e un version facoltativo (stringa). Omettere version per seguire la default_version della skill; specificare una stringa di versione per bloccare la casella degli strumenti su uno snapshot immutabile.

Dichiarare le competenze quando si crea la casella degli strumenti

# 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

Aggiungere, elencare e rimuovere competenze in una casella degli strumenti esistente

# 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 mostra solo la versione predefinita. Le skill aggiunte mostrano la propria versione; quelle non aggiunte mostrano la dicitura (default). Per esaminare le skill in una versione in attesa, eseguire azd ai toolbox show <toolbox> --version <n> --output json e leggere la matrice skills.

I nomi delle competenze devono corrispondere ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ (lettere minuscole, cifre e trattini, massimo 64 caratteri; nessun trattino iniziale o finale). Un @ finale in <name>@<version> (una versione vuota) è rifiutato.

I riferimenti alle competenze non sono attualmente configurabili tramite l'estensione VS Code. Usare l'API REST o l'SDK per configurare le competenze.

Convalidare l'individuazione delle competenze

Dopo aver collegato le competenze a una versione della casella degli strumenti, verificare che siano individuabili tramite l'endpoint MCP della casella degli strumenti usando MCP Python SDK:

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

Le competenze vengono visualizzate come risorse MCP con URI nel formato skill://{name}.

Usare le skill di un agente (Microsoft Agent Framework, .NET)

In .NET usare AgentSkillsProviderBuilder().UseMcpSkills(mcpClient) da Microsoft Agent Framework SDK per individuare le competenze basate su MCP da un endpoint della casella degli strumenti e inserirle come AIContextProviders nell'agente. L'agente carica quindi, in fase di esecuzione, le istruzioni di ciascuna abilità quando il modello stabilisce che è rilevante. Di seguito è Program.cs ospitato l'agente con il livello di hosting Responses (AddFoundryResponses e 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);
    }
}

Per l'esempio completo, inclusi i file di progetto e i passaggi di distribuzione, vedere l'esempio Competenze nella casella degli strumenti.