Curare il set di strumenti basato su intenti in Foundry (anteprima)

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool, 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.beta.toolboxes.create_toolbox_version(
    toolbox_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",
        ),
    ],
)
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
    )
));

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [webTool, mcpTool],
    description: "Toolbox with web search and an MCP server"
);
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 and an MCP server",
  "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"
    }
  ]
}

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

Usare Foundry Toolkit in Visual Studio Code per creare e pubblicare una casella degli strumenti dalla visualizzazione Strumenti .

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 una casella degli strumenti personalizzata immettere il nome e la descrizione della casella degli strumenti, aggiungere gli strumenti desiderati e quindi selezionare Pubblica.

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

Usando azd, si dichiarano le risorse del toolbox in un file agent.yaml anziché utilizzare l'SDK. Definire gli strumenti nella sezione resources e distribuire usando azd ai agent init. Per agent.yaml esempi per ogni tipo di strumento, vedere Configurare gli strumenti. Per il flusso di lavoro di distribuzione completo, vedere Distribuire con azd.

# 1. Create a manifest directory with your agent.yaml + source files
mkdir my-agent/manifest
# Copy agent.yaml, main.py, Dockerfile, requirements.txt into my-agent/manifest/

# 2. Initialize the azd project (note: -m is REQUIRED)
cd my-agent
$PROJECT_ID = "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
azd ai agent init -m https://github.com/microsoft/hosted-agents-vnext-private-preview/main/samples/python/toolbox/azd/agent.yaml --project-id $PROJECT_ID -e my-env
# Or equivalently: azd ai agent init -m manifest/ --project-id $PROJECT_ID -e my-env
# ↑ If your agent.yaml declares {{ param }} secrets (e.g., github_pat), you will be prompted to enter
#   them interactively HERE — before init completes. This is the only safe time to supply credentials.
# NOTE: Do NOT use --no-prompt here — it skips the prompt and leaves {{ param }} credentials empty (see Troubleshooting: Credentials Empty with --no-prompt)

# 3. CRITICAL post-init fixes (see "Post-Init Checklist" below)
azd env set enableHostedAgentVNext "true" -e my-env
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4o" -e my-env  # must match the deployment name in azure.yaml

# 4. Provision infrastructure (creates connections via Bicep)
azd provision -e my-env

# 5. Deploy agent (creates toolboxes, container image, agent version)
azd deploy -e my-env

# 6. Invoke the agent (MUST run from the scaffolded project directory)
azd ai agent invoke --new-session "tell me about the latest news in Microsoft Foundry" --timeout 120

Agent.yaml:

kind: hosted
name: toolbox-azd-test
description: LangGraph agent wired for toolbox MCP.
metadata:
  tags:
    - AI Agent Hosting
    - LangGraph

# template: contains the ContainerAgent definition (kind: hosted).
# These fields are used to generate src/<agent>/agent.yaml during init.
template:
  kind: hosted
  protocols:
    - protocol: responses
      version: 1.0.0
  environment_variables:
    # FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_AGENT_TOOLBOX_* are injected
    # automatically by the platform at runtime — do NOT declare them here.
    - name: AZURE_OPENAI_ENDPOINT
      value: ${AZURE_OPENAI_ENDPOINT}
    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
      value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o}
    - name: TOOLBOX_NAME
      value: ${TOOLBOX_NAME=agent-tools}

# parameters: secret values prompted at init time (or set via azd env).
# azd uppercases the param name to find the env var: github_pat → GITHUB_PAT.
parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token (classic ghp_... or fine-grained github_pat_...)

# resources: connections and toolboxes scaffolded into azure.yaml by azd ai agent init.
resources:
  - kind: connection
    name: github-mcp-conn
    target: https://api.githubcopilot.com/mcp
    category: remoteTool
    credentials:
      type: CustomKeys
      keys:
        Authorization: "Bearer {{ github_pat }}"

  - kind: toolbox
    name: agent-tools
    tools:
      - type: web_search
      - type: mcp
        server_label: github
        server_url: https://api.githubcopilot.com/mcp
        project_connection_id: github-mcp-conn

In Foundry Toolkit per Visual Studio Code copiare l'endpoint consumer della casella degli strumenti dalla vista 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}",
    "Foundry-Features": "Toolboxes=V1Preview",
}

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
Foundry-Features: Toolboxes=V1Preview

{"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
Foundry-Features: Toolboxes=V1Preview

{"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
Foundry-Features: Toolboxes=V1Preview

{"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
Foundry-Features: Toolboxes=V1Preview

{"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}`,
        "Foundry-Features": "Toolboxes=V1Preview",
      },
    },
  },
);

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

.env file:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
FOUNDRY_AGENT_TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
TOOLBOX_NAME=agent-tools
FOUNDRY_AGENT_TOOLBOX_FEATURES=Toolboxes=V1Preview
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()

Vedere l'esempio completo per l'implementazione completa.

Microsoft Agent Framework

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

.env file:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
FOUNDRY_AGENT_TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
FOUNDRY_AGENT_TOOLBOX_FEATURES=Toolboxes=V1Preview
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),
    headers={"Foundry-Features": "Toolboxes=V1Preview"},
    timeout=120.0,
)

# Toolbox MCP endpoint (platform-injected at runtime via FOUNDRY_AGENT_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.

.env file:

GITHUB_TOKEN=<your-github-token>
FOUNDRY_AGENT_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 Foundry Toolkit 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. L'agente di scaffolding gestisce automaticamente l'intestazione Foundry-Features: Toolboxes=V1Preview.

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

Distribuire con azd

Usare l'interfaccia della riga di comando per sviluppatori di Azure (azd) per dichiarare le risorse della casella degli strumenti direttamente in un agent.yaml file e distribuire l'agente con un singolo comando. Usando questo approccio, non è necessario creare la casella degli strumenti separatamente tramite SDK o REST. azd esegue il provisioning della casella degli strumenti, delle connessioni e della distribuzione modello.

Struttura delle cartelle:

my-agent/
├── agent.yaml          # Agent, toolbox, and connection declarations
├── main.py             # LangGraph agent
├── requirements.txt    # All dependencies (Azure SDK + PyPI packages)
├── Dockerfile          # Container build

agent.yaml (Esempio di Ricerca Web + GitHub MCP):

name: my-toolbox-agent
description: LangGraph agent with Azure AI Foundry toolbox MCP.
metadata:
  tags:
    - AI Agent Hosting
    - LangGraph
template:
  name: my-toolbox-agent
  kind: hosted
  protocols:
    - protocol: responses
      version: 1.0.0
  environment_variables:
    # FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_AGENT_TOOLBOX_* are injected
    # automatically by the platform at runtime — do NOT declare them here.
    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
      value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o}
    - name: TOOLBOX_NAME
      value: ${TOOLBOX_NAME=agent-tools}
parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token for MCP connection
resources:
  - kind: connection
    name: github-mcp-conn
    target: https://api.githubcopilot.com/mcp
    category: RemoteTool
    authType: CustomKeys
    credentials:
      keys:
        Authorization: "Bearer {{ github_pat }}"
  - kind: toolbox
    name: agent-tools
    description: Web search and GitHub MCP tools
    tools:
      - type: web_search
      - type: mcp
        server_label: github
        server_url: https://api.githubcopilot.com/mcp
        project_connection_id: github-mcp-conn

main.py segue lo stesso modello LangGraph illustrato in precedenza. Utilizzando azd, FOUNDRY_AGENT_TOOLBOX_ENDPOINT e TOOLBOX_{toolbox_name}_MCP_ENDPOINT vengono inseriti automaticamente - nel codice non è necessaria alcuna configurazione dell'endpoint aggiuntiva.

Distribuire:

# 1. Place agent.yaml and source files in a manifest directory
mkdir my-agent/manifest
# Copy agent.yaml, main.py, Dockerfile, requirements.txt into my-agent/manifest/

# 2. Initialize the azd project (-m is required)
cd my-agent
PROJECT_ID="/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
azd ai agent init -m manifest/ --project-id $PROJECT_ID -e my-env
# If agent.yaml declares {{ param }} secrets (for example, github_pat), you are prompted
# to enter them interactively here. Do NOT use --no-prompt — it leaves credentials empty.

# 3. Set required environment variables
azd env set enableHostedAgentVNext "true" -e my-env
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4o" -e my-env

# 4. Provision infrastructure (creates connections via Bicep)
azd provision -e my-env

# 5. Deploy agent (creates toolboxes, container image, agent version)
azd deploy -e my-env

# 6. Invoke the agent
azd ai agent invoke --new-session "Hello, what tools do you have?" --timeout 120

from azure.ai.projects.models import MCPTool

# Set require_approval on an MCP tool
toolbox_version = project.beta.toolboxes.create_toolbox_version(
    toolbox_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 del Foundry Toolkit in questo articolo si concentra sulla creazione e l'utilizzo della toolbox 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.beta.toolboxes.create_toolbox_version(
    toolbox_name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

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

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

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

const toolboxVersion = await project.beta.toolboxes.createVersion(
  "my-toolbox",
  [/* 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 di Foundry Toolkit descritto in questo articolo è incentrato sulla creazione di una toolbox e sulla generazione della struttura di base di un agente Hosted che la utilizza.

Questa operazione non è supportata con azd. Per creare una versione della casella degli strumenti, usare la scheda Python, .NET, API REST o JavaScript .

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

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

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

const versions = project.beta.toolboxes.listVersions("my-toolbox");
for await (const v of versions) {
  console.log(`${v.version} — created ${v.createdAt}`);
}

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

Questa operazione non è supportata con azd. Per elencare le versioni della casella degli strumenti, usare la scheda Python, .NET, API REST o JavaScript .

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

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

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

const versionObj = await project.beta.toolboxes.getVersion(
  "my-toolbox",
  "<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.

Questa operazione non è supportata con azd. Per ottenere una versione specifica della casella degli strumenti, usare la scheda Python, .NET, API REST o JavaScript .

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

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

PATCH {project_endpoint}/toolboxes/my-toolbox?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.beta.toolboxes.update(
  "my-toolbox",
  "<version_id>",
);
console.log(`Active version: ${toolbox.defaultVersion}`);

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

Questa operazione non è supportata con azd. Per impostare una versione come predefinita, usare la scheda Python, .NET, API REST o JavaScript.

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

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

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

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

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

Questa operazione non è supportata con azd. 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), AgenticIdentitye 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",
  },
];

Nessuna autenticazione:

resources:
  - kind: toolbox
    name: mcp-tools
    description: Public MCP server tools
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com

Autenticazione basata su chiave:

parameters:
  mcp_api_key:
    secret: true
    description: API key for the MCP server
resources:
  - kind: connection
    name: mcp-conn
    target: https://your-mcp-server.example.com
    category: RemoteTool
    authType: CustomKeys
    credentials:
      keys:
        Authorization: "Bearer {{ mcp_api_key }}"
  - kind: toolbox
    name: mcp-tools
    description: MCP server tools with key auth
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com
        project_connection_id: mcp-conn

OAuth - Connettore gestito:

Usare questo modello per i server MCP che supportano il flusso OAuth gestito di Foundry. Il connectorName valore deve corrispondere a un connettore gestito disponibile nel catalogo degli strumenti foundry.

resources:
  - kind: connection
    name: github-oauth-conn
    category: RemoteTool
    authType: OAuth2
    target: https://api.githubcopilot.com/mcp
    connectorName: foundrygithubmcp
  - kind: toolbox
    name: oauth-tools
    description: GitHub OAuth MCP toolbox
    tools:
      - type: mcp
        server_label: github
        project_connection_id: github-oauth-conn

OAuth - Registrazione dell'app personalizzata:

Usare questo modello quando si usa la registrazione dell'app OAuth personalizzata per il server MCP.

parameters:
  oauth_client_id:
    secret: true
    description: OAuth client ID
  oauth_client_secret:
    secret: true
    description: OAuth client secret
resources:
  - kind: connection
    name: mcp-oauth-custom-conn
    category: RemoteTool
    authType: OAuth2
    target: https://your-mcp-server.example.com
    authorizationUrl: https://auth.example.com/authorize
    tokenUrl: https://auth.example.com/token
    refreshUrl: https://auth.example.com/token
    scopes: []
    credentials:
      clientID: "{{ oauth_client_id }}"
      clientSecret: "{{ oauth_client_secret }}"
  - kind: toolbox
    name: oauth-custom-tools
    description: MCP toolbox with custom OAuth
    tools:
      - type: mcp
        server_label: myserver
        project_connection_id: mcp-oauth-custom-conn

Identità agente (ENTRA ID):

Usare questo modello per i server MCP che supportano l'autenticazione di Microsoft Entra ID. L'identità dell'agente Foundry esegue l'autenticazione sulla risorsa di destinazione.

resources:
  - kind: connection
    name: language-mcp
    category: RemoteTool
    authType: AgenticIdentity
    audience: <entra-audience>
    target: https://<resource>.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview
  - kind: toolbox
    name: agent-identity-tools
    description: MCP toolbox with agent identity auth
    tools:
      - type: mcp
        server_label: language
        project_connection_id: language-mcp

Token Entra utente (1P OBO):

Usare questo modello per i server MCP che richiedono l'identità utente tramite il flusso OBO (On-Behalf-Of). Foundry esegue il proxy del token Entra dell'utente al server MCP.

resources:
  - kind: connection
    name: workiq-mail-conn
    category: RemoteTool
    authType: UserEntraToken
    audience: <entra-app-id>
    target: https://agent365.svc.cloud.microsoft/agents/servers/mcp_MailTools
  - kind: toolbox
    name: workiq-tools
    description: MCP toolbox with user Entra token auth
    tools:
      - type: mcp
        server_label: workiq
        project_connection_id: workiq-mail-conn

{
  "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>",
  },
];

resources:
  - kind: toolbox
    name: websearch-tools
    description: Web search toolbox
    tools:
      - type: web_search

Con Grounding con Ricerca personalizzata Bing:

parameters:
  bing_api_key:
    secret: true
    description: Bing API key
resources:
  - kind: connection
    name: bing-custom-conn
    category: GroundingWithCustomSearch
    authType: ApiKey
    target: ""
    credentials:
      key: "{{ bing_api_key }}"
    metadata:
      ResourceId: /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Bing/accounts/<bing-account>
      type: bing_custom_search
  - kind: toolbox
    name: bing-custom-tools
    description: Bing Custom Search toolbox
    tools:
      - type: bing_custom_search
        custom_search_configuration:
          instance_name: your-bing-custom-instance
        project_connection_id: bing-custom-conn

{
  "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>",
        },
      ],
    },
  },
];

parameters:
  ai_search_key:
    secret: true
    description: Azure AI Search admin key
resources:
  - kind: connection
    name: aisearch-conn
    category: CognitiveSearch
    authType: ApiKey
    target: https://your-search-service.search.windows.net/
    credentials:
      key: "{{ ai_search_key }}"
  - kind: toolbox
    name: search-tools
    description: Azure AI Search toolbox
    tools:
      - type: azure_ai_search
        index_name: your-index-name
        project_connection_id: aisearch-conn

{
  "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>"],
    },
  },
];

resources:
  - kind: toolbox
    name: codeinterp-tools
    description: Code interpreter toolbox
    tools:
      - type: code_interpreter

{
  "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>"],
    },
  },
];

resources:
  - kind: toolbox
    name: filesearch-tools
    description: File search toolbox
    tools:
      - type: file_search
        vector_store_ids:
          - ${FILE_SEARCH_VECTOR_STORE_ID}

Impostare l'ID dell'archivio vettoriale prima della distribuzione:

azd env set FILE_SEARCH_VECTOR_STORE_ID "vs_xxxxxxxxxxxx"

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

Autenticazione basata su chiave:

parameters:
  api_key:
    secret: true
    description: API key for the target service
resources:
  - kind: connection
    name: api-conn
    category: CustomKeys
    authType: CustomKeys
    target: https://api.example.com
    credentials:
      keys:
        key: "{{ api_key }}"
  - kind: toolbox
    name: openapi-tools
    description: OpenAPI key-auth toolbox
    tools:
      - type: openapi
        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: api-conn

{
  "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>",
  },
];

resources:
  - kind: connection
    name: a2a-conn
    category: RemoteA2A
    authType: None
    target: https://your-remote-agent.azurecontainerapps.io
  - kind: toolbox
    name: a2a-tools
    description: Agent-to-Agent toolbox
    tools:
      - type: a2a_preview
        project_connection_id: a2a-conn

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

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