Mantenimiento del cuadro de herramientas basado en intenciones en Foundry (versión preliminar)

import os
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, MCP, tool search, Work IQ, and Fabric IQ tools.
# Work IQ and Fabric IQ are dict-shaped here because they require a project_connection_id
# pointing at the corresponding connection. See work-iq.md and fabric-iq.md for setup details.
toolbox_version = project.beta.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with web search, MCP, tool search, Work IQ, and Fabric IQ",
    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(),
        {
            "type": "work_iq_preview",
            "name": "workiq",
            "project_connection_id": os.environ["WORK_IQ_PROJECT_CONNECTION_ID"],
        },
        {
            "type": "fabric_iq_preview",
            "server_label": "fabriciq",
            "project_connection_id": os.environ["FABRIC_IQ_PROJECT_CONNECTION_ID"],
            "require_approval": "never",
            # For Power BI semantic models, restrict the tool surface so the agent reasons
            # over the schema and runs queries directly instead of pre-generating DAX.
            # "allowed_tools": [
            #     "GetInstructions",
            #     "DiscoverArtifacts",
            #     "GetReportMetadata",
            #     "GetSemanticModelSchema",
            #     "ExecuteQuery",
            #     "ValueSearch",
            # ],
        },
    ],
)
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>";
var workIqConnectionId = Environment.GetEnvironmentVariable("WORK_IQ_PROJECT_CONNECTION_ID");
var fabricIqConnectionId = Environment.GetEnvironmentVariable("FABRIC_IQ_PROJECT_CONNECTION_ID");
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" };
WorkIQPreviewTool workIqTool = new(workIqConnectionId) { Name = "workiq" };
FabricIQPreviewTool fabricIqTool = new(fabricIqConnectionId)
{
    ServerLabel = "fabriciq",
    RequireApproval = BinaryData.FromObjectAsJson("never"),
};

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [webTool, mcpTool, searchTool, workIqTool, fabricIqTool],
    description: "Toolbox with web search, MCP, tool search, Work IQ, and Fabric IQ"
);
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, tool search, Work IQ, and Fabric IQ",
  "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"
    },
    {
      "type": "work_iq_preview",
      "name": "workiq",
      "project_connection_id": "{workiq-connection-id}"
    },
    {
      "type": "fabric_iq_preview",
      "server_label": "fabriciq",
      "project_connection_id": "{fabric-iq-connection-id}",
      "require_approval": "never"
    }
  ]
}

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 workIqProjectConnectionId = process.env["WORK_IQ_PROJECT_CONNECTION_ID"];
const fabricIqProjectConnectionId = process.env["FABRIC_IQ_PROJECT_CONNECTION_ID"];

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",
    },
    { type: "toolbox_search_preview" },
    {
      type: "work_iq_preview",
      name: "workiq",
      project_connection_id: workIqProjectConnectionId,
    },
    {
      type: "fabric_iq_preview",
      server_label: "fabriciq",
      project_connection_id: fabricIqProjectConnectionId,
      require_approval: "never",
    },
  ],
  {
    description: "Toolbox with web search, MCP, tool search, Work IQ, and Fabric IQ",
  },
);
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. Para agregar Herramientas de Work IQ o Fabric IQ, seleccione + Agregar herramienta y elija el tipo de herramienta correspondiente. Proporcione la conexión de proyecto necesaria cuando se le solicite. Para obtener más información sobre la configuración de un extremo a otro, consulte Use la herramienta Work IQ y Use la herramienta Fabric IQ.
7. 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_preview
     # Work IQ requires project_connection_id plus a unique name.
     - type: work_iq_preview
       name: workiq
       project_connection_id: <work-iq-connection-name>
     # Fabric IQ requires project_connection_id plus server_label.
     - type: fabric_iq_preview
       server_label: fabriciq
       project_connection_id: <fabric-iq-connection-name>
       require_approval: never
       # For Power BI semantic models, restrict the tool surface with allowed_tools
       # so the agent reasons over the schema and runs queries directly instead of
       # pre-generating DAX. See fabric-iq.md for the full guidance.
       # allowed_tools:
       #   - GetInstructions
       #   - DiscoverArtifacts
       #   - GetReportMetadata
       #   - GetSemanticModelSchema
       #   - ExecuteQuery
       #   - ValueSearch
     # 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
   

   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 información detallada sobre la configuración integral de la búsqueda de herramientas, Work IQ y Fabric IQ, consulte Usar la búsqueda de herramientas, Usar la herramienta Work IQ y Usar la herramienta Fabric IQ.

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}",
    "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())

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

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

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

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

{"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}`,
        "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();

Use el punto de conexión del paso 2 junto con un ejemplo del agente hospedado con scaffolding para validar la carga del cuadro de herramientas de 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

Consulte el ejemplo completo para obtener la implementación completa.

.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
FOUNDRY_AGENT_TOOLBOX_FEATURES=Toolboxes=V1Preview
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

Usa MCPStreamableHTTPTool desde el SDK de Agent Framework para conectarse directamente al punto de conexión MCP de la caja de herramientas.

.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
FOUNDRY_AGENT_TOOLBOX_FEATURES=Toolboxes=V1Preview
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (patrón de clave):

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

Consulte el ejemplo completo para obtener la implementación completa.

SDK de Copilot

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

Use ResponsesServer desde el SDK de Agent Framework con un ToolboxMcpClient personalizado para explorar e invocar herramientas del cuadro de herramientas a través del punto de conexión de MCP.

Variables de entorno:

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

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 encapsula las llamadas directas de JSON-RPC al punto de conexión de MCP. ToolboxHandler conecta las llamadas de la herramienta LLM al cliente de MCP mediante un bucle estándar de llamada a herramientas. Para obtener la implementación completa de ambas clases, consulte el ejemplo completo.

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 con los pasos exactos de configuración, ejecución e implementación. El agente de scaffolding controla el encabezado Foundry-Features: Toolboxes=V1Preview.

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 copiado del paso 2 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 en el paso 1, recupere su punto de conexión de MCP con 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 campo mcp_endpoint de la respuesta es el punto de conexión del consumidor que siempre se resuelve como la default_version 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, el encabezado Foundry-Features: Toolboxes=V1Preview y el token de Entra (alcance https://ai.azure.com/.default).

from azure.ai.projects.models import MCPTool

# Set require_approval on an MCP tool
toolbox_version = project.beta.toolboxes.create_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",
  },
];

Use la pestaña azd, Python, .NET, JavaScript o REST API 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.beta.toolboxes.create_version(
    name="<toolbox-name>",
    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.beta.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.beta.toolboxes.list_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.beta.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.beta.toolboxes.get_version(
    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.beta.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.beta.toolboxes.update(
    "<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.beta.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.beta.toolboxes.delete_version(
    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.beta.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 .

Autenticación basada en claves:

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

Sin autenticación (servidor MCP público):

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

Autenticación basada en identidad o OAuth:

En el caso de OAuth (conector administrado, registro de aplicaciones personalizado), identidad del agente o autenticación del token entra de usuario, cree primero la conexión adecuada en el proyecto Foundry y, a continuación, haga referencia a ella 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 conexión authType determina el flujo de autenticación. Los tipos de autenticación de conexión admitidos para MCP incluyen CustomKeys, OAuth2 (administrado o personalizado), AgenticIdentityTokeny UserEntraToken. Consulte la pestaña azd para ver ejemplos de configuración de conexión según el tipo de autenticación.

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

Cree una conexión de proyecto para el servidor MCP con el tipo de autenticación que coincida con el escenario y, a continuación, haga referencia a ella desde un archivo YAML de cuadro de herramientas mínimo.

Paso 1. Creación de la conexión

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

Elija la variante de autenticación que necesita:

# No auth — public MCP server
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://mms.heiai.top/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

Para la autenticación basada en identidades (user-entra-token, project-managed-identity, agentic-identity), asigne a la identidad correspondiente el rol RBAC necesario en el recurso de destino antes de llamar a la caja de herramientas.

Paso 2. Definición del cuadro de herramientas

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

Paso 3. Creación del cuadro de herramientas

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 conexión de grounding con Bing Custom Search:

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

Predeterminado (basado en Bing Search, no requiere conexión):

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

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

Fundamento con Bing Custom Search:

# 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 requiere la sintaxis exacta de 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 las conexiones también aceptan --auth-type project-managed-identity (sin clave). Al usar la identidad administrada por el proyecto, asigne a la identidad administrada asignada por el sistema del proyecto el rol Lector de datos de índice de búsqueda en el servicio de búsqueda.

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

El intérprete de código no tiene conexión. Declárelo directamente debajo de 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>"],
    },
  },
];

La búsqueda de archivos funciona sin conexión, pero requiere el ID de un almacén de vectores existente. Declárelo directamente debajo de 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

Autenticación anónima:

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

Autenticación de conexión de proyecto:

Use este patrón cuando la API requiera una clave o un token almacenados en una conexión de proyecto 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>"
          }
        }
      }
    }
  ]
}

Autenticación de identidad administrada:

Use este patrón cuando la API de destino se autentique a través de Microsoft Entra ID. La identidad administrada del proyecto Foundry llama a la API en nombre del agente. Asegúrese de que la identidad administrada tiene el rol RBAC necesario en el servicio de destino antes de usar este patrón.

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

Las herramientas de OpenAPI insertan la especificación directamente en tools:. La autenticación basada en conexión (connection_auth) hace referencia a una conexión de proyecto; las herramientas anónimas de OpenAPI no necesitan conexión.

Paso 1. (Opcional) Creación de la conexión de autenticación

Omita este paso para herramientas anónimas de OpenAPI.

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

Las herramientas de OpenAPI también aceptan --auth-type oauth2 conexiones. Consulte la sección MCP más arriba para ver la lista completa de indicadores azd ai connection create.

Paso 2. Definición del cuadro de herramientas

La especificación de OpenAPI está insertada en 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

En el caso de las API anónimas, reemplace el auth: bloque por:

      auth:
        type: anonymous
        security_scheme:
          type: anonymous

Paso 3. Creación del cuadro de herramientas

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

Cree una conexión remote-a2a para el agente remoto y, a continuación, haga referencia a ella desde un archivo YAML mínimo de la caja de herramientas.

Paso 1. Creación de la conexión

Elija la variante de autenticación que necesita:

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

Paso 2. Definición del cuadro de herramientas

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

Paso 3. Creación del cuadro de herramientas

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 se sirve como punto de conexión de MCP. Cree una conexión remote-tool al servidor de Fabric IQ con user-entra-token (recomendado; la identidad del autor de la llamada se reenvía a Fabric) y, a continuación, haga referencia a ella desde un archivo YAML de cuadro de herramientas mínimo.

# 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

remote-tool las conexiones también aceptan --auth-type oauth2. Para obtener el conjunto de marcas completo, consulte la sección MCP anterior.

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

Tool Search no requiere conexión. Declárelo directamente debajo de 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

En Foundry Toolkit for Visual Studio Code, seleccione Tool search en la Build a Custom Toolbox pestaña al crear o editar un cuadro de herramientas. Para obtener más información, consulte Habilitación de la búsqueda de herramientas en un cuadro de herramientas.

{
  "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 se ofrece como punto de conexión A2A. Cree una remote-a2a conexión con el servidor Work IQ con oauth2 y, a continuación, haga referencia a ella desde un cuadro de herramientas mínimo de YAML.

# 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 requiere la sintaxis exacta de 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
Foundry-Features: Toolboxes=V1Preview

{
  "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 configuración de guardrails aún no está disponible en la extensión para VS Code. Use la API REST, el SDK o azd 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: Toolboxes=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.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 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 se pueden descubrir a través del punto de conexión MCP de la caja de herramientas mediante el SDK de Python de 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}",
        "Foundry-Features": "Toolboxes=V1Preview",
    }
    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.
// The Foundry-Features: Toolboxes=V1Preview opt-in header is required while the
// toolbox MCP surface is in preview.
await using var mcpClient = await McpClient.CreateAsync(
    new HttpClientTransport(
        new HttpClientTransportOptions
        {
            Endpoint = new Uri(toolboxMcpServerUrl),
            Name = toolboxName,
            TransportMode = HttpTransportMode.StreamableHttp,
            AdditionalHeaders = new Dictionary<string, string>
            {
                ["Foundry-Features"] = "Toolboxes=V1Preview",
            },
        },
        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.