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).
  • Modello e area del progetto che supportano entrambi lo strumento. Vedere Supporto degli strumenti in base all'area geografica e al modello.

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 ulteriori dettagli, consultare tool_choice nel riferimento REST del progetto Foundry.

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:

  • Considerare gli output dello strumento come input non attendibile e convalidare i valori critici prima di agire su di essi.
  • Convalidare gli output strutturati in base a uno schema previsto, consentire solo campi e operazioni noti e richiedere l'approvazione dell'utente prima delle azioni consequenziali.
  • Inviare solo le informazioni necessarie per completare l'attività.
  • Non includere chiavi, token o altre credenziali nelle richieste.
  • Evitare di registrare segreti nelle tracce o nei log delle applicazioni.
  • Se ti connetti a servizi non Microsoft (ad esempio, server MCP di terze parti), esamina le considerazioni sulla gestione dei dati in Creare e gestire una raccolta di strumenti in Foundry.
  • Se è necessario un routing centralizzato e l'applicazione dei criteri per gli strumenti MCP, vedere Strumenti di governance con gateway di intelligenza artificiale (anteprima).

Risoluzione dei problemi

Usare questi controlli per risolvere i problemi comuni:

  • L'agente non richiama alcuno strumento:
    • 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 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 una delle due tabelle mostra No, lo strumento non può essere eseguito, anche se l'altra tabella 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 per verificare se l'agente ha chiamato uno strumento e controllare gli input e gli output degli strumenti. Per istruzioni sulla configurazione, vedere Configurare il tracciamento per gli agenti Foundry.

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