Tipi di strumenti nel servizio agente Foundry

Gli strumenti ampliano ciò che gli agenti possono fare nel servizio Microsoft Foundry Agent. Anche se un agente può usare un modello Foundry per generare risposte, gli strumenti consentono di eseguire azioni come la ricerca nel Web, l'esecuzione di codice, l'accesso ai dati aziendali e la chiamata di servizi esterni o API. Questo articolo presenta i tipi di strumenti disponibili, illustra come connettere gli strumenti agli agenti e descrive le considerazioni sull'autenticazione e sull'autorizzazione.

Il modo consigliato per rendere disponibili gli strumenti per gli agenti consiste nell'usare una casella degli strumenti. Una casella degli strumenti espone gli strumenti tramite un endpoint MCP gestito, centralizza la gestione delle credenziali e dei criteri e consente di aggiornare o aggiornare gli strumenti della versione senza modificare il codice dell'agente. Anche se gli strumenti possono essere collegati direttamente ai singoli agenti, una casella degli strumenti semplifica la gestione e promuove il riutilizzo degli strumenti tra gli agenti. Per usare gli strumenti, è necessario disporre delle autorizzazioni nel progetto Foundry per gestire gli strumenti e accedere al catalogo degli strumenti Foundry. Per altre informazioni, vedere Che cos'è una casella degli strumenti?e Creare e gestire una casella degli strumenti in Foundry.

Il catalogo degli strumenti Foundry e le caselle degli strumenti sono disponibili a livello generale. Alcuni singoli strumenti sono in anteprima e sono identificati negli elenchi di strumenti e nella documentazione specifica dello strumento. Gli strumenti di anteprima sono soggetti a condizioni supplementari per l'utilizzo.

Che cosa sono gli strumenti?

Uno strumento è una funzionalità che un agente può richiamare durante una conversazione per eseguire un'attività specifica. Quando un agente riceve un messaggio utente, il modello Foundry che alimenta l'agente decide se chiamare uno strumento in base alle istruzioni dell'agente e alle definizioni degli strumenti disponibili. L'agente invia la richiesta dello strumento, l'applicazione o il servizio lo esegue e il risultato viene reintrodotto nella conversazione in modo che l'agente possa continuare con informazioni accurate e aggiornate.

Gli strumenti consentono agli agenti di andare oltre la generazione di testo. Ad esempio, un agente può:

• Cercare le informazioni correnti sul Web prima di rispondere.
• Eseguire Python codice per analizzare un set di dati e generare un grafico.
• Eseguire una query su un archivio vettoriale dei documenti per basare la risposta sui tuoi dati.
• Chiamare un'API esterna per cercare un record del cliente o creare un ticket di supporto.

Tipi di strumenti

Foundry Agent Service raggruppa gli strumenti in due categorie: strumenti predefiniti pronti per l'uso dopo la configurazione di base e strumenti personalizzati che consentono di usare le proprie funzionalità. Indipendentemente dalla categoria a cui appartiene uno strumento, il modo consigliato per renderlo disponibile per un agente è tramite una casella degli strumenti.

Strumenti integrati

Il servizio Foundry Agent offre strumenti integrati come funzionalità preconfigurate. Questi strumenti vengono abilitati sul tuo agente e il servizio gestisce l'esecuzione. Questi strumenti non richiedono l'hosting esterno o il codice personalizzato.

Gli strumenti predefiniti più comunemente usati includono:

• Ricerca Web : aggiungere la ricerca Web all'agente. L'agente recupera informazioni in tempo reale dal Web pubblico e restituisce risposte con citazioni inline. Questo metodo è il modo consigliato per aggiungere il web grounding. Per scenari avanzati, come il filtro specifico del mercato, vedere Grounding con strumenti Bing e la panoramica sul grounding web.
• Code Interpreter : consentire agli agenti di scrivere ed eseguire codice Python in un ambiente in modalità sandbox per l'analisi dei dati, la matematica e la generazione di grafici.
• Ricerca file : aumentare le conoscenze degli agenti dai file caricati o dai documenti proprietari usando la ricerca vettoriale.
• Chiamata di funzioni : definire funzioni personalizzate che l'agente può chiamare. L'applicazione esegue la funzione e restituisce il risultato.

Per l'elenco completo degli strumenti predefiniti, vedere Tutti gli strumenti predefiniti.

Strumenti personalizzati

Gli strumenti personalizzati consentono di estendere l'agente con API, servizi o altri agenti personalizzati. Usare strumenti personalizzati quando gli strumenti predefiniti non coprono lo scenario.

Le opzioni più comuni degli strumenti personalizzati includono:

• Model Context Protocol (MCP): connettere l'agente agli strumenti ospitati in un endpoint server MCP. È consigliabile usare strumenti condivisi tra più agenti o gestiti da un team diverso.
• Da agente a agente (A2A) (anteprima): connettere l'agente ad altri agenti tramite endpoint compatibili con A2A per la comunicazione tra agenti.
• Strumento OpenAPI : connettere l'agente alle API HTTP esterne usando una specifica OpenAPI 3.0 o 3.1.

Per l'elenco completo delle opzioni degli strumenti personalizzati, vedere Tutti gli strumenti personalizzati.

Usare uno strumento in un agente

Per aggiungere uno strumento a un agente, inserire lo strumento in una casella degli strumenti e collegare la casella degli strumenti all'agente come strumento MCP. L'esempio seguente crea una casella degli strumenti con lo strumento di ricerca Web, collega la casella degli strumenti a un agente e invia una query:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool, MCPTool

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# 1. Add the tool to a toolbox. Using a toolbox is the recommended way to give
#    agents tools: you curate tools once and reuse the toolbox across agents.
toolbox = project.toolboxes.create_toolbox_version(
    name="web-search-toolbox",
    description="Toolbox with the web search tool",
    tools=[WebSearchTool()],
)

# 2. The toolbox exposes an MCP-compatible endpoint.
TOOLBOX_MCP_URL = (
    f"{PROJECT_ENDPOINT}/toolboxes/{toolbox.name}"
    f"/versions/{toolbox.version}/mcp?api-version=v1"
)

# 3. Create a remote-tool project connection that points at the toolbox endpoint.
#    Call a user Entra token so the caller's identity is passed through.
#    Create the connection once with the Azure Developer CLI:
#    
#    azd ai connection create web-search-toolbox-conn \
#      --kind remote-tool \
#      --target "<TOOLBOX_MCP_URL>" \
#      --auth-type user-entra-token \
#      --audience https://ai.azure.com
TOOLBOX_CONNECTION_NAME = "web-search-toolbox-conn"

# 4. Attach the toolbox to the agent as an MCP tool.
agent = project.agents.create_version(
    agent_name="web-search-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[
            MCPTool(
                server_label="toolbox",
                server_url=TOOLBOX_MCP_URL,
                require_approval="never",
                project_connection_id=TOOLBOX_CONNECTION_NAME,
            )
        ],
    ),
)

# Send a query
response = openai.responses.create(
    input="What are the latest updates to Microsoft Foundry?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

Ogni tipo di strumento ha una propria configurazione. Per informazioni dettagliate sull'installazione e sugli esempi di codice in tutti i linguaggi supportati, vedere le singole guide pratiche dello strumento collegate nella sezione Tipi di strumenti .

Personalizzare il comportamento dello strumento in fase di esecuzione con input strutturati

Per impostazione predefinita, le configurazioni degli strumenti, come gli ID dei file, gli ID dell'archivio vettoriale e gli endpoint del server MCP, sono fissati quando si crea l'agente. Gli input strutturati nelle proprietà degli strumenti consentono di eseguire l'override di questi valori in fase di esecuzione senza creare una nuova versione dell'agente.

Gli input strutturati sono utili quando:

• Diversi utenti necessitano di archivi vettoriali o file diversi in base al contesto.
• Si vuole riutilizzare la stessa definizione dell'agente tra ambienti (sviluppo, gestione temporanea, produzione).
• Gli endpoint server MCP o i token di autenticazione variano in base alla richiesta.

Le proprietà dello strumento seguenti supportano la personalizzazione tramite input strutturati:

Ad esempio, una definizione di agente con un archivio vettoriale basato su modelli:

{
  "tools": [
    {
      "type": "file_search",
      "vector_store_ids": ["vs_base_kb", "{{customer_kb}}"]
    }
  ],
  "structured_inputs": {
    "customer_kb": {
      "description": "Vector store ID for the customer's knowledge base",
      "required": true,
      "schema": { "type": "string" }
    }
  }
}

In fase di esecuzione specificare il valore effettivo:

{
  "agent": { "type": "agent_reference", "name": "support-agent", "version": "1" },
  "input": [{ "type": "text", "text": "How do I upgrade my account?" }],
  "structured_inputs": {
    "customer_kb": "vs_premium_kb_2024"
  }
}

Gestire l'autenticazione per gli strumenti

Diversi strumenti richiedono approcci di autenticazione diversi. Comprendere queste opzioni consente di connettere gli strumenti in modo sicuro.

Strumenti integrati

La maggior parte degli strumenti predefiniti, ad esempio Interprete codice e Ricerca file, esegue automaticamente l'autenticazione tramite il servizio agente Foundry e non richiede alcuna configurazione aggiuntiva. Gli strumenti che si connettono a origini dati esterne, ad esempio Azure AI Search o SharePoint, usano le connections configurate nel progetto Foundry.

Server MCP

I server MCP supportano più metodi di autenticazione a seconda del server: autenticazione basata su chiave (chiave API o token), autenticazione Microsoft Entra (identità gestita) e OAuth per il pass-through delle identità a livello di utente.

L'esempio seguente si connette a un server MCP usando l'autenticazione basata su chiave. Archiviare le credenziali in una connessione al progetto e quindi fare riferimento al nome della connessione quando si crea lo strumento:

from azure.ai.projects.models import MCPTool

tool = MCPTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="always",
    project_connection_id="my-github-connection",
)

Per l'autenticazione di Microsoft Entra, usare l'identità dell'agente o l'identità gestita del progetto anziché una connessione. Il servizio richiede automaticamente un token. Per il pass-through dell'identità OAuth (autenticazione per utente), il servizio Agent genera un collegamento di consenso che gli utenti autorizzano al primo utilizzo.

Per i passaggi di configurazione dettagliati per tutti i metodi, vedere Configurare l'autenticazione server MCP.

Strumenti OpenAPI

Gli strumenti OpenAPI supportano l'autenticazione anonima, della chiave API e dell'identità gestita. La configurazione dell'autenticazione fa parte della definizione dello strumento.

Autenticazione anonima : usare quando l'API non richiede credenziali:

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

weather_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_weather",
        spec=openapi_spec,
        description="Retrieve weather information for a location.",
        auth=OpenApiAnonymousAuthDetails(),
    )
)

Autenticazione con chiave API : archiviare la chiave in una connessione di progetto e quindi farvi riferimento. La specifica OpenAPI deve includere securitySchemes e security sezioni:

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiKeyAuthDetails,
)

api_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_orders",
        spec=openapi_spec,
        description="Look up customer orders.",
        auth=OpenApiKeyAuthDetails(
            project_connection_id="my-api-connection"
        ),
    )
)

Per la configurazione dell'identità gestita, vedere Connettere gli agenti agli strumenti OpenAPI.

Tutti gli strumenti predefiniti

Nella tabella seguente sono elencati tutti gli strumenti predefiniti disponibili nel servizio Agente Foundry.

Tutti gli strumenti personalizzati

Nella tabella seguente sono elencate tutte le opzioni personalizzate degli strumenti per la connessione di funzionalità personalizzate a un agente.

Concetti chiave

Usare queste definizioni per mantenere coerente la terminologia:

Considerazioni sull'uso di servizi e server non Microsoft

L'uso di servizi e server non Microsoft connessi ("servizi non Microsoft") è soggetto ai termini tra l'utente e il fornitore di servizi. I servizi non Microsoft sono servizi non Microsoft ai sensi del contratto che regola l'uso dei servizi online Microsoft. Quando ci si connette a un servizio non servizi Microsoft, alcuni dati, ad esempio il contenuto della richiesta, vengono inviati al servizio non Microsoft oppure l'applicazione potrebbe ricevere dati dal servizio non Microsoft. L'utente è responsabile dell'uso di servizi non Microsoft e dati, oltre a eventuali addebiti associati a tale utilizzo.

Terze parti (non Microsoft) creano i servizi non Microsoft, inclusi i server MCP remoti, a cui si sceglie di connettersi. Microsoft non testa o verifica questi server. Microsoft non ha alcuna responsabilità nei confronti dell'utente o di altri in relazione all'uso di servizi non Microsoft.

Esaminare attentamente e tenere traccia dei server MCP aggiunti al servizio Agente Foundry. Si basano su server ospitati da provider di servizi attendibili stessi anziché proxy.

Lo strumento MCP può trasmettere intestazioni personalizzate che un server MCP remoto potrebbe richiedere per l'autenticazione. Trattare le credenziali come informazioni riservate.

• Specificare solo le intestazioni minime obbligatorie.
• Non includere le credenziali nelle richieste.
• Se si registrano richieste di controllo, evitare di registrare segreti o contenuti sensibili del prompt.
• Esaminare le procedure di gestione dei dati del provider, inclusa la conservazione e la posizione dei dati.

Individuare e gestire gli strumenti nel portale

Nel portale Foundry, passare al progetto e selezionare Build>Strumenti per aprire Foundry Tools. Da qui è possibile esplorare il catalogo degli strumenti, configurare gli strumenti e aggiungerli agli agenti. Se sono necessari strumenti visibili solo all'interno dell'organizzazione, creare un catalogo di strumenti privati.

Per esplorare gli strumenti durante la compilazione, usare Agents playground. Per altre informazioni, vedere Microsoft Foundry Playgrounds.

Tipi di strumenti nel catalogo

Il catalogo degli strumenti include tre tipologie di voci:

Server MCP remoto: il server di pubblicazione ospita il server e fornisce un endpoint statico o dinamico. Seguire le indicazioni di configurazione per fornire le impostazioni necessarie, ad esempio un endpoint e i dettagli di autenticazione.

Server MCP locale: si ospita il server manualmente, quindi lo si connette a Foundry fornendone l'endpoint. Per compilare e registrare il proprio server, vedere Creare e registrare un server MCP. Per connettere un endpoint MCP a un agente, vedere Connettersi ai server MCP.

Personalizzato: server MCP convertiti da connettori di Azure Logic Apps. Questi server richiedono una configurazione aggiuntiva per la conversione in server MCP remoti.

Filtrare e cercare

Foundry Tools fornisce i filtri seguenti per trovare gli strumenti appropriati:

Quando si seleziona uno strumento, Foundry Tools mostra i dettagli di configurazione necessari per configurarlo.

Gestire gli strumenti configurati

Nell'elenco degli strumenti è possibile trovare gli strumenti configurati, insieme a dettagli come endpoint e impostazioni di autenticazione. È anche possibile aggiungere strumenti agli agenti.

Prima di eliminare uno strumento, controllare quali agenti lo usano. L'eliminazione di uno strumento può interrompere le esecuzioni che dipendono da esso.

Disponibilità e limitazioni

La disponibilità degli strumenti varia in base al modello e all'area.

Per i dettagli più recenti sul supporto del modello e della regione tra gli strumenti, consultare Procedure consigliate per l'uso degli strumenti nel servizio Foundry Agent.

Risoluzione dei problemi

Usare questi controlli per risolvere i problemi comuni:

• Non è possibile trovare il catalogo degli strumenti: verificare di trovarsi nel progetto corretto e quindi passare aStrumenti di >.
• Uno strumento è visibile, ma non è possibile configurarlo: esaminare gli input di autenticazione e configurazione necessari dello strumento e verificare di avere accesso a tutti i servizi dipendenti.
• L'agente non chiama uno strumento: utilizzare le linee guida per la convalida in Migliori pratiche per l'uso degli strumenti nel Servizio Agente Fonderia.

Contenuto correlato

• Procedure ottimali per il servizio agente di Foundry
• Creare e usare una casella degli strumenti Foundry
• Configurare l'autenticazione server MCP
• Gestire gli strumenti MCP usando un gateway di intelligenza artificiale
• Creare un catalogo di strumenti privati
• Compilare e registrare un server MCP
• Linee guida per la sicurezza e le procedure consigliate per il server MCP Foundry