Creación y administración de un cuadro de herramientas en Foundry

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Use la extensión Microsoft Foundry Toolkit para Visual Studio Code para crear y publicar un cuadro de herramientas desde la vista Tools.

1. Seleccione Foundry Toolkit en la barra de actividades.
2. En Mis recursos, expanda El nombre> del proyectoHerramientas.
3. Seleccione el icono + Agregar cuadro de herramientas .
4. En la pestaña Crear un cuadro de herramientas personalizado , escriba el nombre y la descripción del cuadro de herramientas y agregue las herramientas que desee.
5. Para habilitar el enrutamiento de herramientas basado en intenciones, seleccione Búsqueda de herramientas.
6. Seleccione Publicar.

Al publicar un nuevo cuadro de herramientas, se genera automáticamente su primera versión. Esa versión se convierte automáticamente en la versión predeterminada.

Con la agrupación de extensiones unificadas microsoft.foundry (consulte Requisitos previos), cree un cuadro de herramientas en dos pasos:

1. Use azd ai connection create para registrar cada conexión de proyecto a la que hace referencia el cuadro de herramientas (una llamada por registro de credencial).
2. Use azd ai toolbox create --from-file <toolbox.yaml> para crear el cuadro de herramientas. YAML hace referencia a las conexiones por nombre y nunca inserta credenciales.

El patrón es el mismo para cada tipo de conexión y tipo de autenticación:

1. Establecer el proyecto activo una vez en cada shell:

   azd ai project set $PROJECT_ENDPOINT
   

2. Cree una conexión con azd ai connection create. Las marcas difieren por tipo de autenticación, pero la forma del comando siempre es:

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

   Use azd ai connection list y azd ai connection show <name> para inspeccionar las conexiones y azd ai connection delete <name> --force para quitarlas.

3. Cree un archivo YAML del cuadro de herramientas que haga referencia a una o varias conexiones existentes por nombre. YaML nunca inserta credenciales:

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

   Al menos uno de connections, skillso tools debe no estar vacío. Las referencias de habilidades deben apuntar a habilidades que ya existan en el mismo proyecto de Foundry; consulte Usar habilidades en Foundry para crearlas con azd ai skill create. Para obtener detalles sobre la configuración integral de la búsqueda de herramientas, consulte Usar la búsqueda de herramientas.

4. Cree el cuadro de herramientas a partir de ese archivo:

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

   La primera versión se convierte automáticamente en el valor predeterminado. Use azd ai toolbox list, azd ai toolbox show <name>, azd ai toolbox version list <name>y azd ai toolbox delete <name> --force para administrar cuadros de herramientas.

Ejemplo: servidor MCP con autenticación basada en claves

# 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

En la extensión Microsoft Foundry Toolkit for Visual Studio Code, copie el punto de conexión del consumidor del cuadro de herramientas desde la vista Cuadros de herramientas.

1. Seleccione Foundry Toolkit en la barra de actividades.
2. En Mis recursos, expanda El nombre> del proyectoHerramientas.
3. En la pestaña Cuadros de herramientas , busque el cuadro de herramientas.
4. En la columna Dirección URL del punto de conexión, copie el punto de conexión.

El valor de la dirección URL del punto de conexión es el punto de conexión del consumidor del cuadro de herramientas. Para construir un punto de conexión específico de la versión, use el patrón de desarrollador que se muestra en la tabla anterior.

Instale el SDK de cliente MCP:

pip install mcp

Conéctate al cuadro de herramientas y enumera las herramientas

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

Use el punto de conexión específico de la versión (/versions/{version}/mcp) para validar una versión antes de promocionarla.

1. Inicialice la sesión de 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. Enviar la notificación inicializada:

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. Enumerar las herramientas disponibles:

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

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

4. Llame a una herramienta:

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

Instale el SDK de cliente MCP:

npm install @modelcontextprotocol/sdk

Conéctate al cuadro de herramientas y enumera las herramientas

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

Utiliza el punto de conexión MCP de la caja de herramientas con un ejemplo de agente hospedado preconfigurado para validar la carga de la caja de herramientas en VS Code.

1. En Foundry Toolkit, dentro de Mis recursos>El nombre de su proyecto>Herramientas, localice el cuadro de herramientas que desea probar.
2. Seleccione Plantilla de código de andamiaje.
3. Elija una carpeta del proyecto cuando se le solicite.
4. Siga el script generado README.md para instalar dependencias, configurar variables de entorno y ejecutar la muestra localmente.
5. Use Agent Inspector o ejecute python main.py para confirmar que las herramientas del cuadro de herramientas se cargan y responden.

Para la validación específica de la versión antes de promover una nueva versión del cuadro de herramientas, use la pestaña API de REST o Python en este paso.

LangGraph

Requisitos de fragmentos de integración hospedados: Instale langchain-azure-ai[tools]>1.2.3. El fragmento utiliza AzureAIProjectToolbox; utiliza el ejemplo LangGraph mantenido para obtener el agente completo, el conjunto de paquetes y los archivos de implementación.

.env archivo:

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 (patrón de clave):

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Framework del Agente de Microsoft

Instala agent-framework-foundry además del paquete Azure Identity, que es un requisito previo. Para obtener la implementación completa, consulte el ejemplo de Marco de agente mantenido.

Usa FoundryToolbox del SDK de Agent Framework para conectarte al punto de conexión de la caja de herramientas. La clase controla la autenticación del cuadro de herramientas y reenvía el contexto de llamada del agente hospedado.

.env archivo:

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 (patrón de clave):

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

credential = DefaultAzureCredential()

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

toolbox = FoundryToolbox(
    credential,
    url=TOOLBOX_ENDPOINT,
)

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

SDK de Copilot

Requisitos de fragmentos de integración hospedados: Instale el SDK de GitHub Copilot para el entorno de ejecución. El esquema depende de las funciones auxiliares McpBridge y _get_toolbox_token, propias de la aplicación, que no están implementadas aquí. Sigue el punto de conexión de la caja de herramientas y el contrato de autenticación existentes, así como los patrones de integración de agentes hospedados. Todavía no hay disponible un ejemplo completo mantenido.

Usar el SDK de GitHub Copilot para crear un agente potenciado por el cuadro de herramientas que sirva de enlace entre la invocación de herramientas de Copilot y el punto de conexión MCP del cuadro de herramientas de Foundry.

.env archivo:

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 (patrón clave : puente 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"],
)

Framework del Agente de Microsoft

Instale Microsoft.Agents.AI.Foundry.Hosting y Azure.Identity. Para ver un proyecto completo, consulte el ejemplo público de hosted-toolbox de Agent Framework.

Use AddFoundryToolboxes para registrar uno o varios cuadros de herramientas con el agente hospedado. La integración resuelve el punto de conexión MCP administrado, autentica las solicitudes e incluye el estado de la caja de herramientas en la prueba de disponibilidad.

Variables de entorno:

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

Program.cs (patrón de clave):

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

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

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

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

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

Usa la extensión Microsoft Foundry Toolkit para Visual Studio Code para crear un ejemplo de agente hospedado que ya está integrado con tu caja de herramientas.

1. Seleccione Foundry Toolkit en la barra de actividades.
2. En Mis recursos, expanda El nombre> del proyectoHerramientas.
3. En la pestaña Cuadros de herramientas, busque el cuadro de herramientas que desea consumir y, a continuación, seleccione plantilla del código de scaffolding.
4. En la paleta de comandos, elija una carpeta del proyecto cuando se le solicite.
5. Abra el archivo generado README.md y siga los pasos de configuración, ejecución local e implementación para el scaffolding.

El proyecto generado incluye el punto de entrada del agente hospedado, los archivos de implementación y un README.md elemento con los pasos exactos de configuración, ejecución e implementación.

Si desea integrar un cuadro de herramientas en un proyecto de agente hospedado existente en lugar de generar un nuevo ejemplo, use el punto de conexión MCP del cuadro de herramientas con los patrones de Python o .NET de esta sección.

Pasa el extremo de la caja de herramientas a tu agente

Después de crear el cuadro de herramientas, recupere su punto de conexión de MCP mediante azd ai toolbox show y pase ese punto de conexión al código del agente como una variable de entorno. El agente lee la variable en el inicio y la usa para conectarse al cuadro de herramientas.

1. Obtenga el extremo de la caja de herramientas:

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

   El endpoint campo de la respuesta identifica la versión seleccionada. Úselo para probar esa versión antes de la promoción. Para un agente que deba seguir default_version, crea el punto de conexión de consumidor sin versionar que se muestra en Obtener el punto de conexión MCP de la caja de herramientas.

2. Establezca el punto de conexión como una variable de entorno que el agente lee en el inicio:

   # .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. En el código del agente, lea TOOLBOX_ENDPOINT y conéctese a él con un cliente MCP. Utilice los patrones de integración de Python o .NET descritos anteriormente en esta sección como referencia para la configuración del cliente y el token de Entra (ámbito de https://ai.azure.com/.default).

from azure.ai.projects.models import MCPToolboxTool

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

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

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

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

Use la pestaña Python, .NET, JavaScript, API REST o Azure CLI para desarrolladores para configurar require_approval en la definición del cuadro de herramientas. El flujo de trabajo de la extensión Microsoft Foundry Toolkit para Visual Studio Code descrito en este artículo se centra en crear y usar la caja de herramientas en Visual Studio Code.

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

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

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

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

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

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

Use la pestaña Python, .NET, JavaScript o API REST para crear una nueva versión del cuadro de herramientas. El flujo de trabajo de la extensión Microsoft Foundry Toolkit para Visual Studio Code descrito en este artículo se centra en crear una caja de herramientas y generar la estructura base de un agente alojado que la consume.

Esta operación no se admite con la CLI para desarrolladores de Azure. Para crear una versión del cuadro de herramientas, use la pestaña 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}`);
}

Use la pestaña Python, .NET, JavaScript o API REST para enumerar las versiones del cuadro de herramientas.

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

Use la pestaña Python, .NET, JavaScript o API REST para obtener una versión específica del cuadro de herramientas.

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 no puede estar vacío. Reemplácela por una nueva versión.

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

Seleccione la pestaña Python, .NET, JavaScript o API REST para establecer una versión del conjunto de herramientas como predeterminada.

Las versiones del cuadro de herramientas son inmutables. Use publish para convertir cualquier versión existente en el nuevo valor predeterminado:

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

publish es la única vía para cambiar default_version desde la CLI; los verbos mutadores (connection add/remove, skill add/remove) siempre crean una nueva versión sin promoverla.

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

Use la pestaña Python, .NET, JavaScript o API REST para eliminar una versión del cuadro de herramientas.

Esta operación no se admite con la CLI para desarrolladores de Azure. Para eliminar una versión del cuadro de herramientas, use la pestaña Python, .NET, API REST o JavaScript .

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

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

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

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

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

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

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

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

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

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

La configuración de guardrails aún no está disponible en la extensión para VS Code. Use la API REST, el SDK o la CLI de Azure Developer para configurar límites de protección.

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

Para anclar una versión específica:

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

from azure.ai.projects.models import ToolboxSkillReference

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

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

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

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

La CLI de Azure Developer admite referencias de aptitudes en dos lugares: declarativamente como un bloque de skills: de nivel superior en el azd ai toolbox create --from-file YAML y de forma imperativa con los verbos azd ai toolbox skill add/list/remove. Cada referencia acepta un name (obligatorio) y un version (cadena) opcional. Omita version para ajustarse a la habilidad default_version; fije una cadena de versión para fijar el conjunto de herramientas en una instantánea inmutable.

Declarar aptitudes al crear el cuadro de herramientas

# 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

Agregar, enumerar y quitar aptitudes en un cuadro de herramientas existente

# 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 muestra solo la versión predeterminada. Las habilidades fijadas muestran su versión; las habilidades no fijadas muestran (default). Para inspeccionar las habilidades de una versión pendiente, ejecute azd ai toolbox show <toolbox> --version <n> --output json y consulte la matriz skills.

Los nombres de las capacidades deben coincidir con ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ (letras minúsculas, dígitos y guiones; máximo 64 caracteres; sin guion al principio ni al final). Se rechaza un @ al final en <name>@<version> (una versión vacía).

Actualmente, las referencias de aptitud no se pueden configurar mediante la extensión de VS Code. Use la API REST o el SDK para configurar aptitudes.

Validación de la detección de aptitudes

Después de adjuntar habilidades a una versión de la caja de herramientas, compruebe que puede descubrirlas a través del endpoint MCP de la caja de herramientas con el SDK de Python para MCP:

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

Las aptitudes aparecen como recursos MCP con URI con el formato skill://{name}.

Usar habilidades de un agente (Microsoft Agent Framework, .NET)

En .NET, use AgentSkillsProviderBuilder().UseMcpSkills(mcpClient) del SDK de Microsoft Agent Framework para descubrir funcionalidades basadas en MCP desde un punto de conexión de la caja de herramientas e inyectarlas como AIContextProviders en el agente. A continuación, el agente carga las instrucciones de cada aptitud en tiempo de ejecución cuando el modelo decide que es relevante. El siguiente Program.cs aloja el agente con la capa de alojamiento de Respuestas (AddFoundryResponses y 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);
    }
}

Para obtener el ejemplo completo, incluidos los archivos de proyecto y los pasos de implementación, consulte el ejemplo Aptitudes en el cuadro de herramientas.