Configurare e gestire gli agenti in Visual Studio Code

Dopo aver creato un agente dichiarativo (creato nel portale foundry o tramite l'SDK), inizia il lavoro reale, configurandone il comportamento, le istruzioni e le proprietà in base ai requisiti. L'estensione Microsoft Foundry VS Code offre opzioni di configurazione complete tramite Visual Agent Designer e la modifica diretta dei file YAML, offrendo flessibilità nel funzionamento.

Configurazione delle proprietà dell'agente

La Designer di agenti offre un'interfaccia intuitiva per configurare le proprietà principali dell'agente. Queste impostazioni definiscono aspetti fondamentali del comportamento e delle prestazioni dell'agente.

Opzioni di configurazione essenziali

In Progettazione agenti vengono configurate diverse proprietà chiave:

Nome agente : immettere un nome descrittivo che identifichi chiaramente lo scopo dell'agente. Questo nome viene visualizzato in elenchi, log e quando altri sviluppatori lavorano con gli agenti.

Selezione del modello : scegliere la distribuzione del modello dall'elenco a discesa. Questa selezione determina il modello di intelligenza artificiale che supporta le risposte dell'agente. L'elenco a discesa mostra solo i modelli già distribuiti nel progetto.

Descrizione : aggiungere una descrizione chiara e concisa delle operazioni dell'agente. Descrizioni valide aiutano i membri del team a comprendere lo scopo dell'agente senza leggere le istruzioni o il codice.

Istruzioni di sistema : definire il comportamento, la personalità e lo stile di risposta dell'agente. In questo modo si forma il modo in cui l'agente riconosce il ruolo e interagisce con gli utenti.

ID agente : generato automaticamente dall'estensione quando si crea l'agente. Questo identificatore univoco viene usato quando si chiama l'agente tramite le API.

Opzioni di configurazione del modello

Oltre a selezionare un modello, è possibile ottimizzarne il comportamento tramite parametri aggiuntivi:

Temperatura : controlla la creatività della risposta e la casualità. I valori inferiori (0.1-0.3) producono output coerenti e incentrati. I valori più alti (0,7-1,0) generano risposte più creative e diverse. Per gli agenti aziendali che gestiscono attività strutturate, i valori compresi tra 0,3 e 0,7 funzionano in genere correttamente.

Top P : controlla la diversità limitando le scelte del vocabolario durante la generazione. La maggior parte degli scenari funziona correttamente con il valore predefinito 1,0, ma è possibile ridurlo per output più vincolati e prevedibili.

Queste impostazioni vengono visualizzate sia nell'interfaccia della finestra di progettazione che nel file YAML, che rimangono sincronizzate tra entrambe le visualizzazioni.

Informazioni sulla struttura YAML dell'agente

Il file YAML contiene tutta la configurazione dell'agente dichiarativo in un formato strutturato e leggibile. Comprendere questa struttura consente di apportare modifiche precise e lavorare in modo efficiente quando l'interfaccia visiva non è la scelta migliore.

Esempio di YAML completo

Ecco un file YAML dell'agente completamente configurato:

# yaml-language-server: $schema=https://aka.ms/ai-foundry-vsc/agent/1.0.0
version: 1.0.0
name: healthcare-assistant
description: Assists healthcare staff with patient appointment scheduling and information retrieval
id: 'agent-abc123xyz'
metadata:
  authors:
    - developer-name
  tags:
    - healthcare
    - customer-service
    - scheduling
model:
  id: 'gpt-4.1'
  options:
    temperature: 0.5
    top_p: 1
instructions: |
  You're a healthcare assistant helping staff schedule patient appointments and retrieve information.
  
  Your responsibilities:
  - Help staff find available appointment slots
  - Answer questions about patient scheduling policies
  - Provide information about different appointment types
  - Assist with rescheduling and cancellations
  
  Important guidelines:
  - Never access or share patient medical information
  - Always verify appointment details before confirming
  - Be professional but friendly in all interactions
  - If you're unsure about policies, advise staff to check with management
tools: []

La struttura YAML divide naturalmente in sezioni: metadati, configurazione del modello, istruzioni e strumenti. Questa organizzazione semplifica l'individuazione e la modifica di impostazioni specifiche.

Vantaggi della configurazione YAML

La modifica diretta di YAML offre diversi vantaggi:

• Controllo della versione : tenere traccia delle modifiche in Git insieme al codice dell'applicazione
• Aggiornamenti in blocco: esegui più modifiche contemporaneamente con sicurezza
• Modelli - Creare modelli di agente riutilizzabili per configurazioni coerenti
• Revisione del codice - Includere le configurazioni dell'agente nei processi di revisione del codice standard
• Automazione - Compilare script che generano o modificano le configurazioni dell'agente a livello di codice

L'estensione convalida la sintassi YAML in tempo reale, evidenziando gli errori e fornendo suggerimenti durante la digitazione.

Procedure consigliate per la configurazione dell'agente

Man mano che si creano agenti più complessi, queste procedure consentono di mantenere la qualità e l'affidabilità:

Controllo della versione dei file YAML : eseguire il commit delle configurazioni dell'agente in Git insieme al codice dell'applicazione. In questo modo è possibile eseguire il rollback, la revisione del codice e il rilevamento delle modifiche.

Usare nomi e tag descrittivi - Nominare e taggare chiaramente semplifica la ricerca e l'identificazione degli agenti con la crescita della raccolta.

Documentare istruzioni complesse : includere commenti nei file YAML che spiegano perché sono stati scelti modelli o configurazioni di istruzioni specifici.

Test dopo ogni modifica : usare il playground integrato per verificare il comportamento dopo la modifica della configurazione. Piccole modifiche possono avere effetti imprevisti.

Iniziare con semplicità, quindi eseguire l'iterazione : iniziare con le istruzioni di base e aggiungere complessità in base ai risultati dei test. Le istruzioni iniziali eccessivamente complesse sono più difficili da eseguire per il debug.

Mantenere incentrate le istruzioni : ogni agente deve avere uno scopo chiaro e specifico. Gli agenti che cercano di fare troppe cose finiscono per avere prestazioni incoerenti.

La configurazione degli agenti in Visual Studio Code offre potenti funzionalità per la creazione di un'automazione sofisticata. La combinazione di strumenti di progettazione visiva e modifica YAML diretta consente uno sviluppo rapido mantenendo al tempo stesso la precisione necessaria per le distribuzioni di produzione.