Avvio rapido: creare una cassetta degli strumenti e usarla con un agente ospitato

Per il percorso Python SDK, usare la sezione Python più avanti in questo articolo invece del flusso di lavoro Azure Developer CLI o VS Code. Questa procedura crea la toolbox con project_client.toolboxes.create_version(...), quindi carica il codice dell'hosted-agent come nuova versione e lo associa a quella toolbox per nome.

Installare i pacchetti Python usati in questo percorso:

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

È necessario un progetto Foundry esistente con un modello con supporto per la chat distribuito. Il percorso Python SDK in questa guida introduttiva crea la casella degli strumenti e la versione dell'agente ospitato, ma non esegue lo scaffolding di un nuovo progetto Foundry o crea automaticamente una distribuzione del modello.

È anche necessario Visual Studio Code con l'estensione Microsoft Foundry Toolkit, connesso a Azure.

L'esempio include un toolbox.yaml in src/toolbox-agent che definisce entrambi gli strumenti dietro un unico endpoint. Crea la cassetta degli attrezzi da quel file:

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

La prima versione diventa automaticamente la versione predefinita. Il comando stampa l'endpoint MCP con versioning della casella degli strumenti. Copiare il valore Endpoint dall'output. Impostarlo come TOOLBOX_ENDPOINT variabile di ambiente nei passaggi successivi. Avrà l'aspetto seguente:

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

1. Aprire Visual Studio Code e selezionare Foundry Toolkit nella barra delle attività.

2. Se richiesto, accedere all'account Azure.

3. In Risorse personali espandere il progetto e quindi Strumenti.

4. Nella visualizzazione Strumenti selezionare l'icona + Aggiungi casella degli strumenti .

5. Immettere il nome della casella degli strumenti (my-toolbox) e una descrizione.

6. Selezionare Ricerca Web.

7. Selezionare + Aggiungi strumento, scegliere di aggiungere un server MCP remoto e immettere l'URL https://learn.microsoft.com/api/mcpdel server . Il server è pubblico, quindi non è necessaria alcuna autenticazione.

8. Seleziona Pubblica. La pubblicazione genera la prima versione della toolbox.

9. Copiare l'endpoint MCP della casella degli strumenti. Eseguire il comando seguente e copiare il endpoint valore dall'output. Impostarlo come TOOLBOX_ENDPOINT variabile di ambiente nei passaggi successivi:

   azd ai toolbox show my-toolbox --output json
   

Percorso dell'SDK di Python

Usare la procedura seguente se si vuole creare la casella degli strumenti e distribuire la versione dell'agente ospitato usando Python SDK anziché il flusso dell'interfaccia della riga di comando per sviluppatori Azure o vs Code.

1. Creare o scegliere un progetto Foundry

1. Aprire il portale di Foundry e creare un progetto Foundry oppure selezionare un progetto esistente.
2. Nel progetto distribuire un modello che supporta la chat, gpt-5.4-miniad esempio .
3. Copia l'endpoint del progetto da Panoramica e il nome della distribuzione da Build>Deployments.

2. Scaricare l'esempio di agente ospitato nella casella degli strumenti

Clonare il repository degli esempi di Foundry:

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

Creare una cartella di lavoro per gli script di distribuzione. In tale cartella creare un .env file con questi valori:

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>

Passaggio 3: Creare la casella degli strumenti con Python

Creare un file denominato create_toolbox.py nella stessa cartella di lavoro di .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}")

    toolbox = project_client.toolboxes.get(name=toolbox_name)
    mcp_endpoint = (
        f"{endpoint}/toolboxes/{toolbox.name}/versions/"
        f"{toolbox.default_version}/mcp?api-version=v1"
    )
    print(f"Default toolbox version: {toolbox.default_version}")
    print(f"Toolbox MCP endpoint: {mcp_endpoint}")

Eseguire lo script:

python create_toolbox.py

L'agente ospitato di esempio può risolvere la casella degli strumenti da TOOLBOX_ENDPOINT o da FOUNDRY_PROJECT_ENDPOINT più TOOLBOX_NAME. Questo percorso usa TOOLBOX_NAME, quindi non è necessario archiviare l'endpoint con versione in .env.

4. Distribuire l'agente ospitato con Python

Creare un file denominato deploy_toolbox_agent.py nella stessa cartella di lavoro di .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."
                ),
            )
            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,
            )

Eseguire lo script:

python deploy_toolbox_agent.py

Questo script carica l'esempio della casella degli strumenti come nuova versione dell'agente ospitato, punta temporaneamente l'agente ospitato a tale versione, lo richiama con una domanda di Microsoft Learn e ripristina la configurazione dell'endpoint precedente al termine.

5. Verifica la risposta generata tramite Toolbox

Se configuri correttamente il toolbox, la risposta mostra che l'agente ospitato ha rilevato gli strumenti del toolbox e ha risposto utilizzando la documentazione di Microsoft Learn.

Eliminare la casella degli strumenti:

azd ai toolbox delete my-toolbox --force

Dopo aver eliminato la casella degli strumenti, l'endpoint smette di funzionare. Rimuoverlo da src/toolbox-agent/.env e cancellarlo dall'ambiente azd:

azd env set TOOLBOX_ENDPOINT ""

Eliminare l'agente e le relative risorse Azure:

azd down

Eliminare la casella degli strumenti in base al nome:

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

Se è stato creato un gruppo di risorse o un progetto dedicato per questa guida introduttiva, eliminarlo dal portale di Azure dopo che la casella degli strumenti, la distribuzione della chat o l'agente ospitato non sono più necessari.