Creare un agente di richiesta con Microsoft Foundry Toolkit per Visual Studio Code

Usare Agent Builder in Microsoft Foundry Toolkit per Visual Studio Code per configurare il modello, le istruzioni e gli strumenti di un agente prompt. Testare l'agente nel playground, salvare le modifiche come versioni e generare il codice client per chiamarlo da un'applicazione.

Questo articolo inizia dagli agenti di prompt salvati in Foundry. Agent Builder supporta anche richieste archiviate in locale, con opzioni di archiviazione, strumenti e valutazione diverse. Per le alternative basate su codice, vedere Creare un agente.

Prerequisiti

• Installare Microsoft Foundry Toolkit per Visual Studio Code.
• Selezionare un progetto Foundry. È necessaria l'autorizzazione per creare agenti e usare i modelli e gli strumenti del progetto. Vedere Controllo degli accessi in base al ruolo di Foundry.
• Distribuzione di un modello in tale progetto. Vedi Configurare le risorse di Foundry.

Lo sviluppo locale di prompt non richiede un progetto Foundry, a meno che non si utilizzino risorse Foundry.

Creare un agente di risposta rapida

Iniziare con un modello e istruzioni, quindi salvare e testare l'agente prima di aggiungere strumenti.

1. Nella visualizzazione Foundry Toolkit, seleziona Strumenti di sviluppo>Compila>Crea agente.

2. Selezionare Compila un agente per aprire Generatore agenti.

3. In Informazioni di base immettere un nome agente. Iniziare e terminare il nome con una lettera o un numero. È possibile usare trattini tra di essi.

4. Selezionare un modello ospitato in Foundry da Modello. Usare Esplora modelli se è necessario aggiungere un modello.

5. In Istruzioni descrivere l'attività, il comportamento richiesto e la risposta prevista. Ad esempio, chiedere all'agente di riepilogare un problema software identificando il problema segnalato, i passaggi di riproduzione e il comportamento previsto. Ditelo di chiedere informazioni mancanti invece di inventare dettagli.

6. Selezionare Salva in Foundry.

7. Nella scheda Playground immettere una richiesta e selezionare Invia messaggio. Porre una domanda di completamento per testare la conversazione.

8. Verificare se la risposta segue le istruzioni. Perfezionare le istruzioni, salvare e ripetere in base alle esigenze.

   

Se Gli strumenti di sviluppo usano Group by Resource, Create Agent è in Agent Dev Tools invece di Build. Un altro punto di accesso è My Resources>>>. Selezionare un agente esistente nell'elenco per modificarlo.

Scegliere dove salvare

Le azioni di salvataggio disponibili dipendono dal modello e dagli strumenti selezionati.

Configuration	Salva destinazione
Modello ospitato da Foundry senza strumenti.	Salva in Foundry, con Salva in locale disponibile nel menu Salva.
Modello ospitato in Foundry con gli strumenti Foundry.	Salva in Foundry.
Un modello di un altro provider o una configurazione con gli strumenti locali.	Salva in locale.

I badge Microsoft Foundry e Local mostrano dove è archiviato l'agente. Un prompt archiviato in locale può comunque chiamare un modello cloud. L'archiviazione locale non significa che l'inferenza venga eseguita nel computer.

Salvare bozze e versioni

Agent Builder separa le bozze di ripristino locale dalle versioni dell'agente salvate.

Action	Result
Modificare la configurazione.	Agent Builder archivia una bozza di ripristino locale. Questa azione non genera una versione Foundry.
Esegui un nuovo agente non ancora salvato.	Agent Builder convalida il nome e il modello dell'agente e salva l'agente prima della prima esecuzione. Preferisce Foundry quando la configurazione supporta tale destinazione.
Selezionare Salva in Foundry dopo aver modificato un agente Foundry salvato.	Agent Builder salva la configurazione come nuova versione nel progetto.

Se Agent Builder trova una bozza di recupero, scegli Ripristina bozza o Scarta. Salvare le modifiche importanti in modo esplicito prima di cambiare agenti o versioni.

È possibile testare le modifiche non salvate in un agente Foundry esistente. L'esecuzione usa la configurazione modificata anziché un riferimento alla versione dell'agente salvato. Salva prima di fare affidamento su conversazioni associate alla versione, tracciamento o codice client generato.

Importante

Salva in Foundry salva una versione dell'agente. Non pubblica un'applicazione agente con un endpoint applicazione stabile. Per questa operazione separata, vedere Pubblicare un'applicazione agente.

Selezionare una versione dell'agente

Usare il selettore di versione accanto al nome dell'agente per caricare una versione salvata. Le versioni dell'agente Foundry non sono modificabili. Per mantenere le modifiche apportate da una versione precedente, selezionare Salva in Foundry per creare una nuova versione.

La versione selezionata determina la cronologia delle conversazioni mostrata in Generatore agenti e la versione a cui fa riferimento il codice client generato. Per informazioni dettagliate sul controllo delle versioni del servizio, vedere Salvare le modifiche come versioni.

Aggiungere strumenti a un agente Foundry

Gli strumenti connettono l'agente alle informazioni e alle azioni esterne al modello. Gli strumenti disponibili dipendono dal modello, dalle autorizzazioni e dalle risorse nel progetto. Usare il catalogo degli strumenti per configurare le connessioni condivise e l'autenticazione, quindi allegarle in Agent Builder.

1. Aprire un agente Foundry salvato nella scheda Playground .
2. In Strumento selezionare +>Aggiungi strumenti.
3. In Selezionare uno strumento scegliere una connessione da Configurato oppure usare Catalogo per trovare uno strumento.
4. Completare la configurazione richiesta, quindi selezionare Aggiungi strumento.
5. Selezionare Salva in Foundry.
6. Inviare una richiesta che richiede lo strumento ed esaminarne gli input e i risultati. Se l'agente richiede l'approvazione, selezionare Approva o Nega per tale chiamata.

Per esaminare le impostazioni di approvazione delle chiamate agli strumenti per uno strumento MCP, aprire le opzioni e selezionare Configura. È possibile richiedere l'approvazione, approvare automaticamente tutti gli strumenti o approvare strumenti specifici. Esaminare la scelta prima del salvataggio.

Le impostazioni di approvazione non concedono l'accesso al servizio sottostante. Per le autorizzazioni del servizio, vedere Concetti relativi all'identità dell'agente.

Usa una cassetta degli attrezzi (anteprima)

Una casella degli strumenti raggruppa strumenti riutilizzabili dietro un endpoint MCP gestito. Le competenze e la ricerca degli strumenti sono funzionalità di anteprima.

Note

L'integrazione della casella degli strumenti negli agenti prompt è in anteprima e disattivata per impostazione predefinita. Nelle impostazioni di Visual Studio Code abilitare windowsaistudio.enableToolboxInPromptAgent per visualizzare i controlli allegati della casella degli strumenti.

Un agente utilizza una cassetta degli strumenti oppure i singoli strumenti Foundry. Collegando una cassetta degli attrezzi si sostituiscono i relativi singoli strumenti. Con una casella degli strumenti collegata, Aggiungi strumenti aggiunge strumenti all'interno di tale casella degli strumenti.

Le modifiche alla toolbox restano in sospeso finché non salvi l'agente; a quel punto viene creata una nuova versione della toolbox. Le cassette degli strumenti sono risorse condivise; controlla sia la cassetta degli strumenti sia le modifiche apportate all'agente prima di salvare.

1. Aprire un agente Foundry salvato.

2. In Strumento selezionare +>Sfoglia casella degli strumenti.

3. Selezionare una casella degli strumenti ed esaminarne la versione, gli strumenti e le competenze.

4. Seleziona Aggiungi.

5. Espandere la scheda della casella degli strumenti per esaminarne il contenuto ed esaminare le impostazioni di approvazione.

6. Seleziona Salva in Foundry, quindi testa una richiesta che utilizza i relativi strumenti.

   

Puoi anche selezionare Aggiungi a Prompt Agent dall'elenco delle risorse di Toolbox. Per la creazione della casella degli strumenti e le connessioni condivise, vedere Catalogo degli strumenti.

Gestire una cassetta degli strumenti allegata

Usare il menu Altre opzioni della scheda della casella degli strumenti e quindi salvare l'agente dopo aver apportato le modifiche.

Action	Effect
Configure	Modifica le impostazioni di approvazione delle chiamate agli strumenti per questo agente.
Cambia versione	Selezionare un'altra versione della casella degli strumenti associata.
Replace	Scegli una cassetta degli attrezzi diversa.
Remove	Scollega la cassetta degli strumenti da questo agente.
Non aderire	Mantieni i suoi strumenti come strumenti agente individuali. L'agente non ha più accesso agli strumenti della casella degli strumenti, alla ricerca degli strumenti e alla gestione delle versioni e al riutilizzo come insieme.

Connettere un altro agente con A2A (anteprima)

Le connessioni Agent-to-Agent (A2A) consentono a un agente che invia il prompt di invocare come strumento un agente compatibile con A2A. È possibile collegarne una direttamente o tramite una casella degli strumenti. L'allegamento diretto non richiede l'impostazione di attivazione di Toolbox.

1. Aprire un agente Foundry salvato.

2. In Strumento selezionare +>Aggiungi agente (A2A).

3. In Connetti un agente A2A scegliere la scheda appropriata.

   Tab	Cosa fornire
   Configurata	Selezionare una connessione A2A esistente. Questa scheda viene visualizzata quando esistono connessioni configurate.
   catalogo	Selezionare un agente dal catalogo dell’account Foundry. Completare i passaggi di autenticazione e scheda agente quando richiesto.
   Personalizzato	Immettere un nome, un endpoint HTTPS valido e il percorso della scheda agente. Selezionare Autenticazione al recupero della scheda dell'agente, se necessario.

4. Completare la finestra di dialogo per connettersi o aggiungere l'agente.

5. Selezionare Salva in Foundry e quindi testare una richiesta che richiede la connessione.

   

Per la configurazione dell'endpoint, le schede agente, le opzioni di identità e le autorizzazioni, vedere Abilitare un endpoint A2A.

Esaminare le conversazioni e cambiare agenti

Playground contiene la conversazione di test corrente. Selezionare Cancella tutti i messaggi per avviare una nuova conversazione.

Per un agente Foundry salvato, selezionare Conversazioni per esaminare la cronologia per la versione selezionata. Selezionare una conversazione per esaminarne i messaggi e i dettagli della risposta. Aprire la cronologia non riprende quella conversazione nel playground.

Usa il selettore dell'agente nella parte alta di Agent Builder per passare tra i prompt locali e gli agenti di prompt di Foundry. Controlla l'indicatore di archiviazione e la versione dopo il cambio. La scheda Conversazioni è disponibile per gli agenti Foundry salvati, non per le richieste locali.

Generare e migliorare le istruzioni

Usare Genera per creare bozze di istruzioni da una descrizione dell'attività o Migliorare per rivedere le istruzioni esistenti. Quando il campo è vuoto, Inspire me può fornire un'idea iniziale.

1. Selezionare un modello che supporta la generazione di istruzioni.
2. In Istruzioni selezionare Genera se il campo è vuoto o Migliora se contiene istruzioni.
3. Descrivere l'attività o la modifica. Per un agente Foundry esistente, i suggerimenti di miglioramento sono facoltativi.
4. Selezionare Genera o Migliora nella finestra di dialogo.
5. Esaminare le istruzioni riviste e testare richieste rappresentative.
6. Selezionare Salva in Foundry per mantenere la configurazione.

Per gli agenti Foundry salvati, queste azioni usano Foundry Prompt Optimizer. Se l'API di ottimizzazione non supporta il modello, il Toolkit ripiega sulla generazione di prompt standard, se supportata. La selezione di un modello Foundry in una nuova bozza, di per sé, non rende la bozza un agente Foundry salvato.

Valutare un agente prompt di Foundry

Salvare la configurazione da valutare e quindi selezionare Valutazione.

• Seleziona Scaffold Evaluation Code per generare un progetto Python locale per la valutazione. Seguire le istruzioni generate per configurarlo ed eseguirlo.
• Selezionare il link Foundry per la configurazione guidata della valutazione.

Esaminare la configurazione di valutazione generata prima di eseguirla. Lo scaffold identifica l'agente per nome; non dare per scontato che blocchi la versione selezionata in Agent Builder.

Questa scheda è diversa dalla visualizzazione del set di dati del prompt locale. Per indicazioni sulla valutazione dei servizi, vedere Valutare gli agenti.

Generare codice client

Dopo aver salvato un agente Foundry, usare il menu Visualizza codice per chiamarlo da un'applicazione.

Action	Output
Visualizza codice	Progetto Python che chiama l'agente esistente. Scegli una cartella, quindi segui le istruzioni in README.md per dipendenze, configurazione e autenticazione.
Visualizzare frammenti di codice	Frammento di codice Python in un editor che chiama l'agente esistente.

Entrambi gli output fanno riferimento alla versione salvata selezionata. Salvare le modifiche prima di generare codice se l'applicazione necessita della configurazione modificata.

Il codice client non converte un agente prompt in un agente ospitato. Per utilizzare direttamente l’SDK, consulta la guida introduttiva di prompt-agent.

Usare le richieste locali

Scegliere l'archiviazione locale per usare un modello da un altro provider o testare gli strumenti locali. Selezionare un modello, immettere le istruzioni e selezionare Salva in locale. Con un modello Foundry, usare il menu salva quando è disponibile l'archiviazione locale.

Usare Salva in locale per mantenere le modifiche locali. I salvataggi locali non creano versioni di Foundry né record della cronologia delle conversazioni di Foundry.

Connettere gli strumenti locali

Per un prompt locale, selezionare Strumento>+>server MCP per scegliere un server e i relativi strumenti. Per i requisiti di configurazione e runtime, vedere Connettere un server MCP locale.

Per testare uno schema di funzione senza implementare un servizio esterno:

1. Selezionare Strumento>+>personalizzato.
2. Scegliere Per esempio o Carica schema esistente.
3. Specificare lo schema, il nome e la descrizione, quindi aggiungere lo strumento.
4. Immettere una risposta fittizia nella scheda degli strumenti.
5. Eseguire il prompt e controllare come il modello usa la risposta.

Una risposta fittizia non chiama un'API esterna. Un server MCP configurato può eseguire i relativi strumenti.

Configurare l'output strutturato

Per un prompt locale con un modello che supporta l'output strutturato:

1. Aprire Impostazioni accanto al selettore del modello.
2. In Output struttura selezionare json_schema.
3. In Seleziona schema JSON scegliere Usa esempio o Carica file.
4. Esamina lo schema e seleziona Seleziona.
5. Salvare il prompt locale ed eseguire una richiesta per esaminarne l'output.

I formati disponibili dipendono dal modello. Questi passaggi si applicano all'esecuzione della richiesta locale, non allo schema di risposta di un agente del prompt di Foundry salvato.

Valutare le richieste locali con le variabili del set di dati

Per un prompt locale salvato, la scheda Valutazione fornisce la valutazione basata su set di dati. Usare le variabili nelle istruzioni per eseguire la stessa richiesta con valori di set di dati diversi.

Ad esempio, Summarize the issue for {{audience}}. usa una colonna del set di dati denominata audience. Inserire un valore per ogni caso di test. Lo strumento di esecuzione batch locale sostituisce tale valore quando esegue il prompt.

Il playground di Agent Builder non ha un pannello Variabili separato. Per l'importazione, l'analizzatore e il confronto dei risultati del set di dati, vedere Valutare modelli, richieste e agenti.

Generare codice per un prompt locale

Selezionare Visualizza codice per generare il codice di integrazione del modello. Le opzioni disponibili per SDK, autenticazione e lingua dipendono dal provider e dal modello. Queste opzioni differiscono dal progetto client dell'agente Foundry e dalle azioni dei frammenti di codice.

Contenuti correlati

Usa queste guide per sviluppare e pubblicare il tuo agente:

• Creare un agente con Microsoft Foundry Toolkit
• Ciclo di vita di sviluppo dell'agente
• Pubblicare un'applicazione agente