Panoramica degli strumenti per agenti per il servizio Agente Fonderia

Gli strumenti estendono le operazioni che gli agenti possono eseguire nel servizio Microsoft Foundry Agent. Un agente da solo può generare testo, ma gli strumenti consentono di intervenire, eseguendo ricerche nel Web, eseguendo codice, eseguendo query sui dati o chiamando le proprie API. Questo articolo illustra quali strumenti sono, i tipi di strumenti disponibili, come usare uno strumento in un agente e come gestire l'autenticazione. Introduce anche il catalogo degli strumenti Foundry in cui è possibile individuare e configurare gli strumenti. Per usare gli strumenti, è necessario accedere a un progetto Foundry e all'autorizzazione per gestire gli strumenti in tale progetto.

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 decide se chiamare uno strumento in base alle istruzioni dell'agente e alle definizioni degli strumenti disponibili. L'agente invia la richiesta dello strumento, e la vostra applicazione o il servizio la esegue, e il risultato viene reintegrato 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 il codice Python per analizzare un set di dati e generare un grafico.
• Effettuare una query su un archivio di vettori dei documenti per basare la risposta sui dati.
• Chiamare un'API esterna per cercare un record del cliente o creare un ticket di supporto.

Tipi di strumenti

Il servizio agente Foundry offre due categorie di strumenti: strumenti predefiniti pronti per l'uso dopo la configurazione di base e strumenti personalizzati che consentono di usare le proprie funzionalità.

Strumenti predefiniti

Gli strumenti predefiniti sono funzionalità preconfigurate fornite dal servizio agente Foundry. Puoi attivarli nel tuo agente e il servizio si occupa dell'esecuzione. Non è necessario alcun hosting esterno o 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 è il metodo raccomandato per integrare il grounding web. Per scenari avanzati, come il filtraggio specifico per mercato, consultare Grounding con gli strumenti di Bing e la panoramica del web grounding.
• Interprete del codice: consente 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. Ideale per gli 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, includerlo nell'elenco degli strumenti dell'agente quando si crea o si aggiorna la definizione dell'agente. L'esempio seguente crea un agente con lo strumento di ricerca Web abilitato e invia una query:

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

project = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# Create an agent with web search enabled
agent = project.agents.create_version(
    agent_name="web-search-agent",
    definition=PromptAgentDefinition(
        model=os.environ["MODEL_NAME"],
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)

# Start a conversation and send a query
openai = project.get_openai_client()
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, ad esempio gli ID dei file, gli ID dell'archivio vettoriale e gli endpoint 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 predefiniti

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, Ricerca di intelligenza artificiale di Azure o SharePoint) usano le connessioni 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 di 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 di progetto, 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 integrati

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'utilizzo di servizi e server non Microsoft connessi ("servizi non Microsoft") è soggetto alle condizioni tra l'utente e il provider di servizi. I servizi non Microsoft sono prodotti non Microsoft ai sensi del contratto che regola l'uso di Microsoft online services. Quando ci si connette a servizi non 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 dati e servizi non Microsoft, oltre a eventuali addebiti associati a tale utilizzo.

Terze parti (non Microsoft) creano servizi non Microsoft, tra cui server MCP remoti, a cui si sceglie di connettersi. Microsoft non testa o verifica questi server. Microsoft non ha alcuna responsabilità per l'utente o altri utenti 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. Considerare le credenziali come segreti:

• 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 tuo progetto e selezionare Build>Tools per aprire Foundry Tools. Da qui è possibile esplorare il catalogo degli strumenti, configurare gli strumenti e aggiungerli agli agenti o ai flussi di lavoro. Se sono necessari strumenti visibili solo all'interno dell'organizzazione, creare un catalogo di strumenti privati.

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

Tipi di strumenti nel catalogo

Il catalogo degli strumenti include tre tipi 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.

Filtro e ricerca

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 e ai flussi di lavoro.

Prima di eliminare uno strumento, verificare quali agenti o flussi di lavoro usarlo. 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 delle regioni per gli strumenti, vedere 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 >.
• Lo strumento è visibile ma non configurabile: esaminare gli input di autenticazione e configurazione necessari dello strumento e verificare di avere accesso a qualsiasi servizio dipendente.
• 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.

Contenuti correlati

• Procedure consigliate per il servizio Foundry Agent
• 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