Usare una cassetta degli strumenti con un agente ospitato

Usa Microsoft Agent Framework

L'esempio di Python gestito usa FoundryToolbox dal pacchetto di hosting di Agent Framework. La classe risolve la casella degli strumenti da TOOLBOX_ENDPOINT o da FOUNDRY_PROJECT_ENDPOINT e TOOLBOX_NAME. Autentica anche le richieste MCP e inoltra l'ID di chiamata per richiesta del runtime ospitato.

Installare Python 3.12 o versione successiva, Azure Developer CLI (azd) 1.25 o versione successiva e l'estensione microsoft.foundry prima di inizializzare l'esempio.

1. Inizializzare un progetto dall'esempio della casella degli strumenti dell'agente ospitato:

   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
   

2. Impostare il nome della casella degli strumenti. L'esempio costruisce l'endpoint consumatore dall'endpoint del progetto e questo nome:

   azd env set TOOLBOX_NAME <toolbox-name>
   

3. Eseguire l'agente in locale:

   azd ai agent run
   

4. In un altro terminale, verifica che l'agente rilevi gli strumenti della toolbox:

   azd ai agent invoke --local "List the tools you can use and briefly describe each one."
   

La risposta elenca gli strumenti che la toolbox restituisce da MCP tools/list. Se la risposta non contiene strumenti della casella degli strumenti, vedere Risolvere i problemi di connessione.

Usare LangGraph

Usare AzureAIProjectToolbox quando il codice dell'agente ospitato viene compilato con LangGraph. L'integrazione carica gli strumenti della casella degli strumenti come strumenti LangChain e gestisce l'autenticazione nell'endpoint consumatore.

1. Installare l'integrazione del Azure LangChain e le relative dipendenze di hosting:

   pip install "langchain-azure-ai[hosting]>=1.2.8"
   

2. Impostare FOUNDRY_PROJECT_ENDPOINT nell'ambiente dell'agente ospitato. Il runtime fornisce questo valore dopo la distribuzione. Impostarlo in proprio per lo sviluppo locale.

3. Caricare gli strumenti in base al nome della casella degli strumenti:

import asyncio

from langchain_azure_ai.tools import AzureAIProjectToolbox

async def load_tools():
   toolbox = AzureAIProjectToolbox(toolbox_name="<toolbox-name>")
   tools = await toolbox.get_tools()
   print("\n".join(tool.name for tool in tools))

asyncio.run(load_tools())

L'output contiene i nomi che il toolbox restituisce da MCP tools/list:

<tool-name>
<tool-name>

Informazioni di riferimento:AzureAIProjectToolbox

1. Passare gli strumenti caricati all'agente LangGraph ed eseguire un prompt che richiede uno degli strumenti della casella degli strumenti. Per un'implementazione completa, vedere l'esempio della casella degli strumenti LangGraph.

Usa l'integrazione di hosting di Agent Framework Foundry per registrare un toolbox per nome. AddFoundryToolboxes costruisce l'endpoint consumer da FOUNDRY_PROJECT_ENDPOINT, chiama MCP tools/list durante l'avvio e aggiunge gli strumenti individuati a ogni richiesta dell'agente.

Installare .NET 10 SDK e interfaccia della riga di comando di Azure prima di eseguire l'esempio gestito.

1. Iniziare dall'esempio pubblico della casella degli strumenti ospitata o aggiungere il pacchetto host Foundry a un host di Agent Framework esistente.

2. Impostare queste variabili di ambiente per lo sviluppo locale:

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

   Foundry fornisce FOUNDRY_PROJECT_ENDPOINT al contenitore distribuito. Mantenere il nome della casella degli strumenti in TOOLBOX_NAME. Altri FOUNDRY_* nomi di variabile sono riservati dal runtime ospitato.

3. In Program.csregistrare l'agente con AddFoundryResponsese quindi registrare la casella degli strumenti con AddFoundryToolboxes(credential, toolboxName). Dopo aver compilato l'applicazione Web, chiamare MapFoundryResponses prima di Run. L'esempio pubblico include le importazioni, i pacchetti, la creazione dell'agente e la configurazione delle credenziali necessari.

4. Avvia l'host e quindi richiamalo con un prompt che richiede uno strumento della toolbox. L'endpoint /readiness restituisce uno stato non integro quando l'host non è in grado di enumerare gli strumenti della casella degli strumenti.

Le integrazioni della casella degli strumenti dell'agente ospitato in questo articolo sono disponibili per Python e .NET. Per chiamare l'endpoint MCP da un altro runtime, usare un client HTTP mcp streamable, eseguire l'autenticazione con un token per https://ai.azure.com/.defaulte implementare il contratto di runtime dell'agente ospitato.

Le integrazioni della casella degli strumenti dell'agente ospitato in questo articolo sono disponibili per Python e .NET. Per chiamare l'endpoint MCP da un altro runtime, usare un client HTTP mcp streamable, eseguire l'autenticazione con un token per https://ai.azure.com/.defaulte implementare il contratto di runtime dell'agente ospitato.

Usa il Microsoft Foundry Toolkit per Visual Studio Code per creare un esempio di agente ospitato connesso a un toolbox.

Installa Visual Studio Code, l'estensione Microsoft Foundry Toolkit e il pacchetto di estensioni per il tuo linguaggio di programmazione prima di generare la struttura del progetto.

1. Nella barra delle attività selezionare Foundry Toolkit.
2. In Risorse personali espandere il progetto e quindi Strumenti.
3. Nella scheda Caselle degli strumenti, individua la casella degli strumenti e quindi seleziona Modello di codice scaffold.
4. Nel riquadro comandi selezionare una cartella del progetto.
5. Aprire l'oggetto generato README.mde quindi completare i passaggi di esecuzione e distribuzione locali.
6. Eseguire un prompt che richiede uno strumento della casella degli strumenti e verificare che l'agente chiami lo strumento previsto.

Passare il nome della casella degli strumenti a un esempio di agente ospitato che costruisce l'endpoint consumatore da FOUNDRY_PROJECT_ENDPOINT:

Installare Azure Developer CLI (azd) versione 1.25 o successiva e l'estensione microsoft.foundry prima di eseguire questi comandi.

1. Esaminare la casella degli strumenti e la versione predefinita corrente:

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

   L'output usa la proprietà endpoint. L'endpoint restituito da questo comando identifica la versione selezionata ed è utile per testare tale versione.

2. Archiviare il nome della casella degli strumenti nell'ambiente azd :

   azd env set TOOLBOX_NAME <toolbox-name>
   

3. Per eseguire l'agente ospitato in locale, usare:

   azd ai agent run
   

   Per distribuire invece l'agente ospitato, usare:

   azd deploy
   

Se l'applicazione accetta solo un URL completo, impostare TOOLBOX_ENDPOINT sull'endpoint consumatore senza versione da Scegli endpoint casella degli strumenti.