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

In questa guida introduttiva creerai una toolbox che combina due strumenti dietro a un unico endpoint gestito:

• Ricerca Web, che giustifica le risposte nei risultati Web pubblici in tempo reale.
• Il server MCP Microsoft Learn, che giustifica le risposte nella documentazione ufficiale Microsoft. Si tratta di un endpoint pubblico che non richiede l'autenticazione.

Si usa quindi la toolbox da un agente ospitato che è scritto in Python. La casella degli strumenti espone un endpoint MCP, quindi l'agente si connette a un singolo URL e individua ogni strumento in fase di esecuzione. È possibile modificare gli strumenti in un secondo momento senza modificare il codice dell'agente.

Prerequisiti

Questa guida rapida si basa sulla toolchain dell'agente ospitato. Completare prima i prerequisiti nella guida introduttiva dell'agente ospitato, che illustrano la sottoscrizione Azure, i ruoli del progetto, Python, l'interfaccia della riga di comando di Azure Developer (azd) e l'estensionemicrosoft.foundry.

Per il percorso di VS Code è necessario anche Visual Studio Code con l'estensione Microsoft Foundry Toolkit, connesso a Azure.

Passaggio 1: Inizializzare l'agente ospitato

Inizializzare un agente ospitato dall'esempio della casella degli strumenti Foundry, che si connette a una casella degli strumenti tramite MCP ed espone i relativi strumenti al modello. Nel passaggio successivo, crei la toolbox (my-toolbox) e indirizzi l'agente al suo endpoint. Eseguire questi comandi in una directory vuota.

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/agent.manifest.yaml" --src src/toolbox-agent

Segui le indicazioni per selezionare il tuo progetto e una distribuzione di modello esistente. Quando viene richiesto di selezionare l'allocazione delle risorse del contenitore, scegliere 1 core, 2Gi memoria. L'immagine del container dell'agente richiede un livello superiore a quello predefinito. Il --src flag consente di eseguire lo scaffolding dell'agente in src/toolbox-agent.

Passaggio 2: Creare la casella degli strumenti

Creare la casella degli strumenti, quindi copiare l'endpoint MCP restituito. L'endpoint viene impostato come variabile di ambiente nei passaggi successivi.

In primo luogo, puntare i comandi della casella degli strumenti nel progetto Foundry selezionato durante l'inizializzazione. Riutilizza l'endpoint già memorizzato durante l'inizializzazione nell'ambiente azd:

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

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

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

Passaggio 3: Effettuare il provisioning delle risorse di Azure

L'agente legge l'endpoint MCP della toolbox dalla variabile di ambiente TOOLBOX_ENDPOINT, che src/toolbox-agent/agent.yaml viene ricavata dal tuo ambiente azd. Questo valore viene impostato nei passaggi successivi. Effettuare il provisioning delle risorse Azure dell'agente:

azd provision

Passaggio 4: Eseguire l'agente localmente

1. Indirizzare l'agente locale al toolbox impostando questi valori nel file .env in src/toolbox-agent. Incollare l'endpoint copiato nel passaggio 2:

   AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>
   TOOLBOX_ENDPOINT=<versioned-endpoint-from-step-2>
   

   azd ai agent run inietta FOUNDRY_PROJECT_ENDPOINT e legge il file .env per le esecuzioni in locale. L'esempio gestisce automaticamente per te la connessione al toolbox, gli header e l'autenticazione.

2. Avvia l'agente:

   azd ai agent run
   

   Questo comando crea un ambiente virtuale, installa le dipendenze e gestisce l'agente in http://localhost:8088. I pacchetti di anteprima possono generare avvisi pip durante l'installazione. Questi avvisi non sono bloccanti.

3. In un terminale separato inviare richieste che eseguino gli strumenti:

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

Passaggio 5: Distribuire nel servizio agente Foundry

Salva l'endpoint che hai copiato al passaggio 2 nel tuo azd ambiente, che agent.yaml viene risolto al momento della distribuzione. Compilare e distribuire quindi il contenitore dell'agente:

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

Al termine dell'esecuzione del comando, nell'output vengono visualizzati i collegamenti al playground dell'agente e all'endpoint dell'agente. Richiamare l'agente distribuito:

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

Pulire le risorse

Elimina le risorse quando hai finito, per evitare ulteriori addebiti.

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

Troubleshooting

Cosa si è appreso

Questo avvio rapido spiega come:

• È stato creato un set di strumenti che combina la ricerca sul Web e il server MCP di Microsoft Learn in un unico endpoint.
• Ha usato il toolbox da un agente Python ospitato che si connette tramite il Model Context Protocol.
• Ho eseguito l'agente in locale e l'ho distribuito in Foundry Agent Service.

Passo successivo

Contenuti correlati

• Che cosa sono gli agenti ospitati?
• Creare una cassetta degli strumenti basata sugli intenti in Foundry
• Strumento di ricerca Web
• Connettere gli agenti ai server del Model Context Protocol
• Guida introduttiva: Implementare il primo agente ospitato