Procedure migliori per il servizio Microsoft Foundry Agent Service

Quando si sviluppano agenti nel servizio Microsoft Foundry Agent, gli strumenti ampliano le funzionalità che l'agente può eseguire: recuperare informazioni, chiamare API e connettersi a servizi esterni. Questo articolo illustra come configurare gli strumenti in modo efficace, controllare quando l'agente li chiama e proteggere i dati.

Suggerimento

Nelle istruzioni dell'agente descrivere il valore di ogni strumento e quando usarlo. Per esempio:

When you need information from my indexed documents, use File Search. When you need to call an API, use the OpenAPI tool. When a tool call fails or returns no results, explain what happened and ask a follow-up question.

Prerequisiti

  • Accedere a un progetto Foundry nel portale Foundry con il ruolo sviluppatore di Azure AI o autorizzazioni equivalenti.
  • Modello distribuito nello stesso progetto.
  • Tutte le connessioni necessarie configurate per gli strumenti che si prevede di usare (ad esempio, Azure AI Search, SharePoint o il servizio di grounding di Bing).

Configurare e convalidare l'utilizzo degli strumenti

Migliorare l'affidabilità delle chiamate agli strumenti

Chiamare lo strumento di controllo con tool_choice

Usare tool_choice per il controllo più deterministico sulle chiamate agli strumenti.

  • auto: il modello decide se chiamare gli strumenti.
  • required: il modello deve chiamare uno o più strumenti.
  • none: Il modello non chiama gli strumenti.

Per dettagli, consultare tool_choice in REST del progetto Foundry (anteprima).

Scrivere istruzioni efficaci per gli strumenti

  • Mantenere le istruzioni specifiche e coerenti con la configurazione dello strumento.
  • Indicare al modello il valore di ogni strumento.
  • Se sono presenti più strumenti che si sovrappongono, aggiungere una regola decisionale, ad esempio "Usa ricerca file prima della ricerca Web per il contenuto interno".

Utilizzo sicuro degli strumenti

Gli strumenti inviano e ricevono dati all'esterno del modello. Ridurre i rischi per la sicurezza e la privacy con queste procedure:

Supporto degli strumenti in base all'area geografica e al modello

Area e modello determinano quali strumenti sono disponibili per l'agente.

Nota

Nelle tabelle seguenti: Sì significa completamente supportato, No significa non supportato e Limited significa supporto parziale che varia in base alla configurazione dello strumento. Per informazioni dettagliate, vedere la documentazione dei singoli strumenti.

La tabella seguente illustra la disponibilità degli strumenti in base all'area.

Nota

Questa tabella di disponibilità regionale riguarda solo la disponibilità del servizio. È necessario assicurarsi che il modello che si vuole usare sia disponibile anche nella stessa area.

Nome area Agent2Agent Azure AI Search Automazione del browser Interprete di codice Uso del computer agente dati di Fabric Ricerca file Funzione Grounding con Ricerca personalizzata Bing Grounding con Ricerca Bing Generazione di immagini MCP OpenAPI SharePoint Ricerca Web
australiaeast Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
brasilesouth Sì Sì Sì Sì no Sì Sì no Sì Sì Sì Sì Sì Sì Sì
Canada orientale Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
eastus Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
eastus2 Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
francecentral Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
germania ovest centrale Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
italynorth Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
japaneast Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
koreacentral Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
northcentralus Sì Sì Sì Sì no Sì Sì no Sì Sì Sì Sì Sì Sì Sì
norvegiaest Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
polandcentral Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
southafricanorth Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
southcentralus Sì Sì Sì no no Sì Sì no Sì Sì Sì Sì Sì Sì Sì
Sud-est asiatico Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
southindia Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
spaincentral Sì Sì Sì no no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
Swedencentral Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
SvizzeraNorth Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
uaenorth Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
uksouth Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì
westus Sì Sì Sì Sì no Sì Sì no Sì Sì Sì Sì Sì Sì Sì
westus3 Sì Sì Sì Sì no Sì Sì Sì Sì Sì Sì Sì Sì Sì Sì

Gli strumenti sono supportati dai modelli seguenti.

Nota

Per lo strumento di generazione di immagini, è necessario sia il modello gpt-image-1 che un modello LLM (Large Language Model) come agente di orchestrazione nello stesso progetto Microsoft Foundry.

Modello Agent2Agent Azure AI Search Funzioni di Azure Grounding personalizzato Bing Fondamenti della Ricerca Bing Automazione del browser Interprete di codice Uso del computer agente dati di Fabric Ricerca file Funzioni Generazione di immagini MCP OpenAPI SharePoint Ricerca Web IQ lavoro (anteprima)
Cohere-command-r No No No No No No Sì No No Sì No No No No No No No
Cohere-command-r-plus No No No No No No Sì No No Sì No No No No No No No
DeepSeek-R1-0528 No No No No No No Sì No No Sì No No No No No No No
DeepSeek-V3-0324 No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
DeepSeek-V3.1 No No No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
FW-DeepSeek-V3.1 No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-DeepSeek-V3.2 No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-GLM-4.7 No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-GLM-5 No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-GLM-5.1 No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-GPT-OSS-120B No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-Kimi-K2-Instruct-0905 No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-Kimi-K2-Thinking No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-Kimi-K2.5 No No No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-Kimi-K2.6 No No No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-MiniMax-M2.5 No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-Qwen3.5-122B-A10B No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
FW-Qwen3.5-397B-A17B No Sì No No No No Sì No Sì Sì No No Sì Sì No Sì Sì
GROK-4-20-REASONING No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
Llama-3.3-70B-Instruct No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
Llama-4-Maverick-17B-128E-Instruct-FP8 No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
Llama-4-Scout-17B-16E-Instruct No No No No No No Sì No No Sì No No No No No No No
MAI-DS-R1 Sì No No No No Sì Sì No No Sì Sì No Sì No No No No
Meta-Llama-3.1-405B-Instruct No No No No No No Sì No No Sì No No No No No No No
Mistral-large-2407 No No No No No No Sì No No Sì No No No No No No No
claude-haiku-4-5 Sì Sì No No No Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
claude-mythos-preview Sì Sì No No No Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
claude-opus-4-1 Sì Sì No No No Sì Sì No Sì Sì No No No Sì Sì Sì Sì
claude-opus-4-5 Sì Sì No No No Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
claude-opus-4-6 Sì Sì No No No Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
claude-opus-4-7 Sì Sì No No No Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
claude-sonnet-4-5 Sì Sì No No No Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
claude-sonnet-4-6 Sì Sì No No No Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
codex-mini No No No No No No Sì No No Sì No No No No No No No
computer-use-preview No No No No No No No Sì No No No No No No No No No
gpt-35-turbo No No No No No No Sì No No Sì No No No No No No No
gpt-4 No No No No No No Sì No No Sì No No No No No No Sì
gpt-4.1 Sì Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
gpt-4.1-mini Sì Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
gpt-4.1-nano Sì Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
gpt-4.5-preview No No No No No No Sì No No Sì No No No No No No No
gpt-4o Sì Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
gpt-4o-mini Sì No No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
gpt-5 Sì Sì No Sì Sì Sì Sì No Sì Sì Sì Sì Sì Sì Sì Sì Sì
gpt-5-chat No No No No No No Sì No No Sì No No No No No No Sì
gpt-5-codex No No No No No No Sì No No Sì No No Sì No No No Sì
gpt-5-mini No No No No No No Sì No No Sì No No Sì No No Sì Sì
gpt-5-nano No No No No No No Sì No No Sì No No No No No No Sì
gpt-5-pro No No No No No No Sì No No Sì No No No No No No No
gpt-5.1 No Sì Sì No Sì No Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
gpt-5.1-chat No No No No No No Sì No No Sì No No No No No No No
gpt-5.1-codex No No No No No No Sì No No Sì No No Sì No No No Sì
gpt-5.1-codex-max No No No No No No Sì No No Sì No No No No No No No
gpt-5.1-codex-mini No No No No No No Sì No No Sì No No No No No No No
gpt-5.2 No Sì Sì No Sì No Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
gpt-5.2-chat Sì Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì No Sì Sì
gpt-5.2-codex No No No No No No Sì No No Sì No No Sì No No No Sì
gpt-5.3-chat Sì Sì No Sì Sì Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
gpt-5.3-codex Sì Sì No Sì Sì Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
gpt-5.4 Sì Sì No Sì Sì Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
gpt-5.4-mini Sì Sì No Sì Sì Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
gpt-5.4-nano Sì Sì No Sì Sì Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
gpt-5.4-pro Sì Sì No Sì Sì Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
gpt-5.5 Sì Sì No Sì Sì Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
gpt-chat-latest Sì Sì No Sì Sì Sì Sì No Sì Sì No No Sì Sì Sì Sì Sì
gpt-oss-120b No No No No No No Sì No No Sì Sì No Sì No No No Sì
grok-3 No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
grok-3-mini No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
grok-4 No No No No No No Sì No No Sì No No No No No No No
grok-4-1-fast-non-reasoning No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
grok-4-1-fast-reasoning No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
grok-4-20-non-reasoning No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
grok-4-20-reasoning No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
grok-4-fast-non-reasoning No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
grok-4-fast-reasoning No Sì No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì Sì Sì
mistral-small-2503 No No No No No No Sì No No Sì No No No No No No No
modello-router No No No Sì Sì Sì Sì No Sì Sì Sì No Sì Sì Sì No Sì
o1 No Sì No Sì No Sì Sì No No Sì Sì No Sì No Sì Sì Sì
o1-mini No No No No No No Sì No No Sì No No No No No No No
o1-preview No No No No No No Sì No No Sì No No No No No No No
o3 Sì Sì No Sì No Sì Sì No Sì Sì Sì No Sì Sì No Sì Sì
o3-deep-research No No No No No No No No No No No No Sì No No Sì Sì
o3-mini Sì No No Sì Sì Sì Sì No Sì Sì No No No No No No Sì
o3-pro No No No No No No Sì No No Sì No No No No No No No
o4-mini Sì No No Sì Sì Sì Sì No Sì Sì Sì No Sì No Sì Sì Sì

Risoluzione dei problemi

Usare questi controlli per risolvere i problemi comuni:

  • L'agente non chiama un'applicazione:
    • Verificare che lo strumento sia collegato all'agente.
    • Verificare che il modello supporti lo strumento.
    • Se è necessario un comportamento deterministico, impostare tool_choice su required.
    • Esaminare le tracce di esecuzione per verificare se il modello ha generato una chiamata allo strumento.
  • Le chiamate degli strumenti restituiscono risultati vuoti o irrilevanti:
    • Migliorare le descrizioni degli strumenti e le istruzioni dell'agente.
    • Per gli strumenti di recupero, assicurati che i tuoi dati siano inseriti e siano ricercabili.
  • Le chiamate agli strumenti hanno esito negativo:
    • Verificare la configurazione e l'autenticazione dello strumento.
    • Per gli strumenti MCP e OpenAPI, verificare che l'endpoint sia raggiungibile e restituisca le risposte previste.
  • Foundry restituisce un errore "strumento non supportato" anche se le tabelle mostrano il supporto:
    • La disponibilità degli strumenti richiede il supporto sia del modello che dell'area. Controllare la tabella di disponibilità dell'area per l'area e la tabella di supporto del modello per il modello. Se uno mostra No, lo strumento non può essere eseguito, anche se l'altro mostra Yes.
    • Verificare che il modello sia effettivamente distribuito nel progetto e nell'area di destinazione. Un modello che supporta uno strumento in generale potrebbe non essere distribuito in ogni area.
    • Provare un'area diversa o una distribuzione del modello diversa che supporti lo strumento. Ad esempio, l'interprete di codice non viene eseguito in aree che mostrano no per l'interprete del codice (ad esempio southcentralus e spaincentral), indipendentemente dal modello usato.

Domande frequenti

Come si verifica se è stato chiamato uno strumento?

Esaminare le tracce di esecuzione per verificare se l'agente ha chiamato uno strumento e controllare gli input e gli output degli strumenti. Per la configurazione del tracciamento end-to-end, consultare Tracciare l'applicazione.

Come si rende più affidabile l'utilizzo degli strumenti?

Iniziare con istruzioni chiare per gli strumenti. Se è necessario chiamare uno strumento deterministico, usare tool_choice. Per informazioni dettagliate, vedere Chiamare lo strumento di controllo con tool_choice.

Contenuto correlato

Gestione degli strumenti

Strumenti di recupero e ricerca

Strumenti di integrazione e dati

Strumenti di automazione e generazione

  • Last updated on