Inicio rápido: Creación de un cuadro de herramientas y uso con un agente hospedado

Importante

Los elementos marcados (versión preliminar) de este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

En esta guía de inicio rápido, creas una caja de herramientas que combina dos herramientas detrás de un único punto de conexión administrado:

Búsqueda web, que fundamenta las respuestas en resultados públicos de la web en tiempo real.
El servidor MCP de Microsoft Learn, que fundamenta las respuestas en la documentación oficial de Microsoft. Es un punto de conexión público que no requiere autenticación.

A continuación, usará el conjunto de herramientas de un agente hospedado escrito en Python. El cuadro de herramientas expone un punto de conexión MCP, por lo que el agente se conecta a una sola dirección URL y detecta todas las herramientas en tiempo de ejecución. Puede cambiar las herramientas más adelante sin cambiar el código del agente.

Prerequisites

Esta guía de inicio rápido se basa en la cadena de herramientas del agente hospedado. Complete primero los requisitos previos del inicio rápido del agente hospedado, que abarcan la suscripción Azure, los roles de proyecto, Python, la CLI de Azure Developer (azd) y la microsoft.foundry extensión.

Para la ruta de acceso del SDK de Python, use la sección Python más adelante en este artículo en lugar del flujo de trabajo de la CLI para desarrolladores de Azure o VS Code. Ese proceso crea la caja de herramientas con project_client.toolboxes.create_version(...) y, a continuación, carga el código del agente alojado como una nueva versión y lo vincula a esa caja de herramientas por nombre.

Instale los paquetes de Python usados en esta ruta de acceso:

pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

Necesita un proyecto de Foundry existente con un modelo implementado compatible con chat. La ruta del SDK de Python de esta guía de inicio rápido crea la caja de herramientas y la versión del agente hospedado, pero no genera un nuevo proyecto de Foundry ni crea una implementación de modelo por usted.

También necesitarás Visual Studio Code con la extensión Microsoft Foundry Toolkit, e iniciar sesión en Azure.

Paso 1: Inicialización del agente hospedado

Inicializa un agente hospedado a partir del ejemplo de caja de herramientas de Foundry, que se conecta a una caja de herramientas mediante MCP y expone sus herramientas al modelo. Cree la caja de herramientas (my-toolbox) en el siguiente paso y configure el agente para que apunte a su punto de conexión. Ejecute estos comandos en un directorio vacío.

mkdir my-toolbox-agent && cd my-toolbox-agent
azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml" --src src/toolbox-agent

Siga las indicaciones para seleccionar el proyecto y una implementación de modelo existente. Cuando se le pida que seleccione la asignación de recursos del contenedor, elija 1 núcleo, 2 Gi de memoria. La imagen de contenedor del agente requiere un nivel superior al predeterminado. El indicador --src preconfigura el agente como src/toolbox-agent.

Note

Los manifiestos del agente (agent.manifest.yaml) y las definiciones de agente independientes (agent.yaml) están en desuso. A partir de las extensiones de Foundry azd (azure.ai.agents 1.0.0-beta.1), toda la configuración de los agentes hospedados se encuentra en un único azure.yaml. Consulte cómo crear azure.yaml para agentes hospedados.

Paso 2: Crear el cuadro de herramientas

Cree el cuadro de herramientas y, a continuación, copie el punto de conexión de MCP que devuelve. Establezca ese punto de conexión como una variable de entorno en pasos posteriores.

El ejemplo azure.yaml define el cuadro de herramientas como servicio azure.ai.toolbox y lo redirige al servicio del agente hospedado con uses:. Si cambia la configuración del cuadro de herramientas, edite el servicio del cuadro de herramientas en azure.yaml, no src/toolbox-agent/agent.yaml.

En primer lugar, dirija los comandos de la caja de herramientas al proyecto de Foundry que seleccionó durante la inicialización. Reutiliza el endpoint que la inicialización ya ha almacenado en tu entorno azd:

azd env set FOUNDRY_PROJECT_ENDPOINT "$(azd env get-value FOUNDRY_PROJECT_ENDPOINT)"

El ejemplo incluye un elemento toolbox.yaml en src/toolbox-agent que define ambas herramientas detrás de un único punto de conexión. Cree el cuadro de herramientas a partir de ese archivo:

azd ai toolbox create my-toolbox --from-file ./src/toolbox-agent/toolbox.yaml

La primera versión se convierte automáticamente en la versión predeterminada. El comando muestra el punto de conexión del MCP con versión de la caja de herramientas. Copie el Endpoint valor de la salida. Establézcalo como variable TOOLBOX_ENDPOINT de entorno en los pasos siguientes. Tiene este aspecto:

https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/my-toolbox/versions/1/mcp?api-version=v1

Abra Visual Studio Code y seleccione Foundry Toolkit en la barra de actividades.
Inicie sesión en su cuenta de Azure si se le solicita.
En Mis recursos, expanda el proyecto y, a continuación, expanda Herramientas.
En la vista Herramientas , seleccione el icono + Agregar cuadro de herramientas .
Escriba el nombre del cuadro de herramientas (my-toolbox) y una descripción.
Seleccione Búsqueda web.
Seleccione + Agregar herramienta, elija agregar un servidor MCP remoto y escriba la dirección URL https://learn.microsoft.com/api/mcpdel servidor . El servidor es público, por lo que no se requiere autenticación.
Seleccione Publicar. La publicación crea la primera versión del cuadro de herramientas.
Copie el punto de conexión MCP del cuadro de herramientas. Ejecute el siguiente comando y copie el endpoint valor de la salida. Establézcalo como la TOOLBOX_ENDPOINT variable de entorno en los pasos siguientes:
```
azd ai toolbox show my-toolbox --output json
```

Paso 3: Aprovisionar recursos de Azure

El agente lee el punto de conexión de MCP de la caja de herramientas desde la variable de entorno TOOLBOX_ENDPOINT, que azure.yaml se obtiene de su entorno azd. Establezca ese valor en los pasos siguientes. Aprovisione los recursos de Azure del agente:

azd provision

Paso 4: Ejecución del agente de forma local

Configure el agente local para que apunte a su caja de herramientas estableciendo estos valores en el archivo .env de src/toolbox-agent. Pegue el punto de conexión que copió en el paso 2:
```
FOUNDRY_MODEL_NAME=<your-model-deployment-name>
TOOLBOX_ENDPOINT=<versioned-endpoint-from-step-2>
```
azd ai agent run inyecta FOUNDRY_PROJECT_ENDPOINT y lee el archivo .env para ejecuciones locales. El ejemplo gestiona por usted la conexión con la caja de herramientas, los encabezados y la autenticación.
Inicie el agente:
```
azd ai agent run
```
Este comando crea un entorno virtual, instala dependencias y sirve al agente en http://localhost:8088. Los paquetes en versión preliminar pueden generar advertencias de pip durante la instalación. Estas advertencias no son bloqueantes.

En otro terminal, envíe instrucciones para poner a prueba las herramientas:

azd ai agent invoke --local "Find the latest release notes for the Azure CLI on the web."
azd ai agent invoke --local "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation."

Paso 5: Implementación en Foundry Agent Service

Almacene el punto de conexión que ha copiado en el paso 2 en tu entorno azd, que azure.yaml se resuelve durante la implementación. A continuación, compile e implemente el contenedor del agente:

azd env set TOOLBOX_ENDPOINT "<versioned-endpoint-from-step-2>"
azd deploy

Una vez finalizado el comando, la salida muestra enlaces al entorno de pruebas del agente y al punto de conexión del agente. Invoque al agente desplegado:

azd ai agent invoke "What's new in Microsoft Foundry? Use the Microsoft Learn documentation."

ruta de acceso del SDK de Python

Siga estos pasos si desea crear el cuadro de herramientas e implementar la versión del agente hospedado mediante el SDK de Python en lugar del flujo de la CLI para desarrolladores de Azure o VS Code.

1. Crear o seleccionar un proyecto de Foundry

Abra el portal de Foundry y cree un proyecto foundry o seleccione uno existente.
En el proyecto, implemente un modelo compatible con chat, como gpt-5.4-mini.
Copie el punto de conexión del proyecto desde Información general y el nombre de implementación de Build>Deployments.

2. Descarga el ejemplo de agente hospedado de Toolbox

Clona el repositorio de ejemplos de Foundry:

git clone https://github.com/microsoft-foundry/foundry-samples.git

Cree una carpeta de trabajo para los scripts de implementación. En esa carpeta, cree un .env archivo con estos valores:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=toolbox-agent
TOOLBOX_NAME=my-toolbox
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/src/agent-framework-agent-with-foundry-toolbox-responses>

Paso 3: Crear el cuadro de herramientas con Python

Cree un archivo denominado create_toolbox.py en la misma carpeta de trabajo que .env:

import os

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

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
toolbox_name = os.environ["TOOLBOX_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    created = project_client.toolboxes.create_version(
        name=toolbox_name,
        description="Toolbox with web search and Microsoft Learn MCP.",
        tools=[
            WebSearchToolboxTool(
                name="web_search",
                search_context_size="medium",
            ),
            MCPToolboxTool(
                server_label="mslearn",
                server_url="https://learn.microsoft.com/api/mcp",
                require_approval="never",
            ),
        ],
    )
    print(f"Created toolbox version {created.version} for {created.name}")

    mcp_endpoint = (
        f"{endpoint}/toolboxes/{created.name}/versions/"
        f"{created.version}/mcp?api-version=v1"
    )
    print(f"Toolbox version: {created.version}")
    print(f"Toolbox MCP endpoint: {mcp_endpoint}")

Ejecute el script:

python create_toolbox.py

El agente hospedado de ejemplo puede resolver el cuadro de herramientas desde TOOLBOX_ENDPOINT o desde FOUNDRY_PROJECT_ENDPOINT más TOOLBOX_NAME. Esta ruta usa TOOLBOX_NAME, por lo que no necesitas guardar el endpoint versionado en .env.

4. Implementación del agente hospedado con Python

Cree un archivo denominado deploy_toolbox_agent.py en la misma carpeta de trabajo que .env:

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointConfig,
    CodeConfiguration,
    CodeDependencyResolution,
    FixedRatioVersionSelectionRule,
    HostedAgentDefinition,
    ProtocolConfiguration,
    ProtocolVersionRecord,
    ResponsesProtocolConfiguration,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "toolbox-agent")
toolbox_name = os.environ["TOOLBOX_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
    zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
    excluded = {".git", ".venv", "__pycache__", ".env"}

    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
        for path in source_dir.rglob("*"):
            if not path.is_file():
                continue
            if any(part in excluded for part in path.parts):
                continue
            zip_file.write(path, path.relative_to(source_dir))

    return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
    for attempt in range(60):
        time.sleep(10)
        details = project_client.agents.get_version(
            agent_name=agent_name,
            agent_version=version,
        )
        status = details["status"]
        print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

        if status == "active":
            return

        if status == "failed":
            raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

    raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
    code_zip_path.open("rb") as code_stream,
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    original_agent_endpoint = None
    created = None

    try:
        created = project_client.agents.create_version_from_code(
            agent_name=agent_name,
            description="Hosted agent with Foundry Toolbox integration.",
            definition=HostedAgentDefinition(
                cpu="1",
                memory="2Gi",
                code_configuration=CodeConfiguration(
                    runtime="python_3_13",
                    entry_point=["python", "main.py"],
                    dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
                ),
                environment_variables={
                    "FOUNDRY_PROJECT_ENDPOINT": endpoint,
                    "AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
                    "TOOLBOX_NAME": toolbox_name,
                },
                protocol_versions=[
                    ProtocolVersionRecord(protocol="responses", version="2.0.0")
                ],
            ),
            code=code_stream,
        )

        print(f"Created hosted agent version {created.version}")
        wait_for_active_version(project_client, created.version)

        original_agent_endpoint = project_client.agents.get(
            agent_name=agent_name
        ).agent_endpoint
        project_client.agents.update_details(
            agent_name=agent_name,
            agent_endpoint=AgentEndpointConfig(
                version_selector=VersionSelector(
                    version_selection_rules=[
                        FixedRatioVersionSelectionRule(
                            agent_version=created.version,
                            traffic_percentage=100,
                        ),
                    ]
                ),
                protocol_configuration=ProtocolConfiguration(
                    responses=ResponsesProtocolConfiguration()
                ),
            ),
        )

        with project_client.get_openai_client(agent_name=agent_name) as openai_client:
            response = openai_client.responses.create(
                input=(
                    "How do I create a hosted agent in Microsoft Foundry? "
                    "Use the Microsoft Learn documentation."
                ),
            )
            if response.status != "completed":
                raise RuntimeError(f"Agent invocation failed: {response.error}")
            print(response.output_text)
    finally:
        if original_agent_endpoint is not None:
            project_client.agents.update_details(
                agent_name=agent_name,
                agent_endpoint=original_agent_endpoint,
            )

        if created is not None:
            project_client.agents.delete_version(
                agent_name=agent_name,
                agent_version=created.version,
                force=True,
            )

Ejecute el script:

python deploy_toolbox_agent.py

Este script carga el ejemplo del cuadro de herramientas como una nueva versión del agente hospedado, apunta al agente hospedado en esa versión temporalmente, lo invoca con una pregunta de Microsoft Learn y restaura la configuración del punto de conexión anterior cuando finaliza.

5. Comprobar la respuesta respaldada por el cuadro de herramientas

Si configura correctamente la caja de herramientas, la respuesta muestra que el agente alojado descubrió las herramientas de la caja de herramientas y respondió utilizando la documentación de Microsoft Learn.

Limpieza de recursos

Elimine los recursos cuando haya terminado para dejar de incurrir en cargos.

Elimine el cuadro de herramientas:

azd ai toolbox delete my-toolbox --force

Después de eliminar el cuadro de herramientas, su punto de conexión deja de funcionar. Quítelo de src/toolbox-agent/.env y elimínelo de su entorno azd:

azd env set TOOLBOX_ENDPOINT ""

Elimine el agente y sus recursos de Azure:

Advertencia

Si el entorno actual azd creó el proyecto Foundry, azd down elimina permanentemente el grupo de recursos del proyecto y todo lo que contiene. Si seleccionó un proyecto existente durante la inicialización, deja el proyecto, azd down su grupo de recursos, el agente hospedado y otros recursos de inicio rápido. Para eliminar los recursos que ya no necesite del proyecto existente, elimínelos por separado.

azd down

Elimine el cuadro de herramientas por nombre:

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        credential=credential,
    ) as project_client,
):
    project_client.toolboxes.delete(name=os.environ["TOOLBOX_NAME"])

Si creó un grupo de recursos dedicado o un proyecto para este inicio rápido, elimínelo desde el portal de Azure después de que ya no necesite el cuadro de herramientas, la implementación de chat o el agente hospedado.

Troubleshooting

Issue	Solución
`tools/list` no devuelve herramientas de Microsoft Learn	Confirme que la herramienta `mslearn` en `toolbox.yaml` apunta a `https://learn.microsoft.com/api/mcp`.
El agente se inicia, pero indica `TOOLBOX_ENDPOINT is set but empty` o no tiene herramientas	Establezca `TOOLBOX_ENDPOINT` en el punto de conexión con versión del paso 2 en `.env` para ejecuciones locales y ejecute `azd env set TOOLBOX_ENDPOINT "<endpoint>"` antes de la implementación.
Las llamadas al punto de conexión del cuadro de herramientas producen un error de autorización	Comprueba que cada solicitud incluya un token de Entra con ámbito `https://ai.azure.com/.default`. El ejemplo se encarga de esto por usted.
`Connection refused` durante la ejecución local	Asegúrese de que ningún otro proceso use el puerto `8088`.

Lo que ha aprendido

En esta guía de inicio rápido:

Se ha creado un cuadro de herramientas que combina la búsqueda web y el servidor MCP de Microsoft Learn detrás de un punto de conexión.
Utiliza Toolbox desde un agente hospedado en Python que se conecte a través del Protocolo de contexto de modelo (Model Context Protocol) mediante la CLI de desarrollador de Azure o el SDK de Python.
Ejecuta el agente localmente o valídalo de forma remota e impleméntalo en Foundry Agent Service.

Paso siguiente

Adición de una base de conocimiento de Foundry IQ a un agente hospedado

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-07-23