Sviluppare un agente con Agent Script

Obiettivi di apprendimento

Gli obiettivi di questo badge sono i seguenti:

Scoprire Agent Script e i pacchetti di authoring.
Visualizzare l’anteprima di un agente utilizzando il file Agent Script.
Sviluppare un agente aggiornando e convalidando il relativo file Agent Script.
Pubblicare un agente in un’organizzazione.
Visualizzare l’agente dopo la pubblicazione nell’interfaccia utente del Generatore Agentforce dell’organizzazione.

Per questa fase, usa la stessa organizzazione Developer Edition che hai creato nella fase 1.

Nota

Stai seguendo la formazione in italiano? Inizia la sfida in un Trailhead Playground in italiano e utilizza le traduzioni fornite tra parentesi per la navigazione. Per quanto riguarda i valori da inserire, copia e incolla solo quelli in lingua inglese, perché la convalida della sfida è basata sul fatto che i dati siano in inglese. Se non superi la sfida nella tua organizzazione italiana, ti consigliamo di (1) selezionare Stati Uniti per le impostazioni internazionali, (2) selezionare Inglese per la lingua seguendo le istruzioni riportate qui e, successivamente, (3) fare nuovamente clic sul pulsante "Controlla la sfida".

Visita il badge Trailhead nella tua lingua per informazioni dettagliate su come usufruire dell'esperienza Trailhead in altre lingue.

Introduzione a Agent Script, il progetto dell’agente

La creazione di un agente ha un ciclo di vita ben preciso.

Sviluppo: sviluppare il file Agent Script per definire le istruzioni e la logica dell’agente.
Pubblicazione: implementare il file Agent Script in un’organizzazione di sviluppo per creare i metadati dell’agente.
Testing: verificare il comportamento dell’agente in un’organizzazione sandbox o vuota.
Implementazione: eseguire la migrazione dei metadati dell’agente verso l’ambiente di produzione.
Attivazione: attivare l’agente per metterlo a disposizione dei clienti.

Questo badge è incentrato sulle fasi di sviluppo e pubblicazione.

Agent Script è alla base della prossima generazione di agenti Agentforce. È un linguaggio che combina la flessibilità dell’uso del linguaggio naturale per lo sviluppo vibe con l’affidabilità delle espressioni programmatiche per la gestione delle regole di business. Agent Script offre tutti i vantaggi derivanti dall’accesso a un Large Language Model (LLM) e, allo stesso tempo, fornisce soluzioni per aggiungere all’agente comportamenti più deterministici.

Come spesso accade in Salesforce, il file Agent Script di un agente è parte di un componente di metadati denominato AiAuthoringBundle o, più semplicemente, pacchetto di authoring (authoring bundle). È possibile generare un pacchetto di authoring partendo da zero mediante i comandi CLI o VS Code nel proprio progetto DX oppure tramite vibe coding. In alternativa, puoi prima creare un agente nella tua organizzazione utilizzando il Generatore Agentforce e poi importare il pacchetto di authoring nel progetto DX. Il pacchetto di authoring include un file con l’estensione .agent; si tratta del file Agent Script che funge da progetto per l’agente.

In questo badge Trailhead inizierai con un pacchetto di authoring e un file Agent Script già esistenti nel repository che hai clonato nell’unità precedente. Cominciamo?

In VS Code, apri il file Agent Script denominato Local_Info_Agent.agent, che si trova nella directory force-app/main/default/aiAuthoringBundles/Local_Info_Agent del progetto DX che hai clonato nell’unità precedente.

VS Code in cui è aperto un file Agent Script denominato Local_Info_Agent.agent.

Nota che il file Agent Script mostra una forte evidenziazione a colori della sintassi, indicazioni visive (come i segni rossi) per gli errori di sintassi, la navigazione nel codice e così via. Questi colori vengono visualizzati perché le estensioni di Salesforce VS Code supportano Agent Script come linguaggio di programmazione, proprio come supportano Apex e LWC.

L’apprendimento del linguaggio Agent Script in sé non rientra tra le finalità di questo badge, ma vale la pena dedicare qualche minuto a dare un’occhiata al file. Ad esempio, il file è composto da blocchi, come system, config e variables. Il blocco config contiene parametri di configurazione che definiscono l’agente. Più avanti in questo badge dovrai cambiare uno di questi parametri.

Per maggiori dettagli e ulteriori informazioni, consulta Introduzione ad Agent Script.

Visualizzare l’anteprima dell’agente utilizzando solo il file Agent Script correlato

È utile interagire ogni tanto con l’agente mentre scrivi il codice del file Agent Script correlato, per verificare come reagisce man mano che apporti modifiche e aggiornamenti in tempo reale. Queste anteprime di conversazioni fungono da test interattivi per verificare che l’agente si comporti come previsto.

Per iniziare, visualizza l’anteprima dell’agente in modalità simulata, che usa solo il file Agent Script per conversare ed eseguire simulazioni di tutti gli strumenti. Questa modalità è particolarmente utile se le classi Apex, i flussi o i modelli di prompt che implementano gli strumenti non sono ancora disponibili. L’LLM utilizza le informazioni sugli agenti secondari che hai inserito nel file Agent Script per simulare il modo in cui lo strumento funziona o reagisce. L’accesso all’LLM avviene tramite la tua organizzazione, quindi devi comunque disporre delle autorizzazioni necessarie per accedere all’organizzazione anche in modalità simulata.

In VS Code, apri il menu contestuale (clic con il tasto destro) nel file Agent Script Local_Info_Agent.agent.
Seleziona AFDX: Preview This Agent (Visualizza in anteprima questo agente).
Sulla sinistra si apre un riquadro Agentforce DX.
Nell’elenco a discesa Seleziona agente…, seleziona Local_Info_Agent, che potrebbe essere già selezionato.
Nota la sua posizione, ovvero la sezione Agent Script dell’elenco. A meno che tu non abbia creato un nuovo agente, Local_Info_Agent è l’unico agente nell’elenco.
Nell’elenco a discesa, seleziona Simulation (Simulazione) e fai clic su Start Simulation (Avvia simulazione) per avviare l’anteprima.
Nella chatbox, digita questa domanda per vedere cosa può fare l’agente: What can you help me with? (In cosa puoi aiutarmi?).
L’agente riflette per un attimo e poi risponde.
Digita questa domanda:
```
What’s the weather like?
```

Ti viene fornita una sintesi delle previsioni del tempo, ma hai notato che l’agente parla in gergo piratesco? Ad esempio, è possibile che le sue risposte inizino con Ehi, ciurma!. Che strano... Il motivo per cui l’agente risponde in questo modo è che il suo file Agent Script gli impone di parlare come un pirata quando descrive le condizioni meteorologiche locali.

Anche se la figura del pirata è un modo divertente per testare la personalità, gli agenti professionisti devono mantenere una voce coerente con il marchio di appartenenza. Scopri come modificare il file Agent Script per perfezionare le risposte conversazionali dell’agente.

Scrivere il codice del file Agent Script

Se vuoi cambiare il comportamento dell’agente, devi modificare il codice del file Agent Script correlato. Man mano che scrivi il codice, convalida il file per accertarti di non aver inserito errori. Probabilmente è il momento giusto per fare in modo che l’agente non risponda parlando come un pirata: ecco come fare.

In VS Code, analizza il file Agent Script per capire se riesci a trovare l’istruzione che porta l’agente a usare il gergo piratesco quando parla delle condizioni meteorologiche locali.
Suggerimento: controlla le istruzioni per il ragionamento relative a local_weather. Se ancora non riesci a trovare l’istruzione, cerca intorno alla riga 117 una riga che inizia con Finally, ALWAYS give answers (Infine, fornisci SEMPRE delle risposte).
Per modificare il file, rimuovi l’intera riga che inizia con Finally, ALWAYS give answers (Infine, fornisci SEMPRE delle risposte). Non apportare altre modifiche se non hai ben chiaro cosa stai facendo!
Salva il file.
Apri il menu contestuale (clic con il tasto destro) del file Agent Script e scegli AFDX: Validate this Agent (AFDX: convalida questo agente).
Mentre il file viene convalidato, nell’angolo in basso a destra di VS Code viene visualizzata una piccola finestra. Se la convalida non riesce, si apre la scheda Problems (Problemi) con i messaggi di errore e i suggerimenti per risolvere i problemi. Tuttavia, se stai seguendo questa procedura, la convalida del file Agent Script dovrebbe andare a buon fine.
Nell’angolo superiore destro della finestra di anteprima di Agentforce DX, fai clic su Restart Options (Opzioni riavvio) e poi su Compile & Restart (Compila & riavvia).
Inserisci la stessa domanda (What’s the weather like? ) (Che tempo fa?) nella chatbox. Puoi anche selezionare la freccia su per utilizzare la cronologia della chat.
Questa volta la risposta dovrebbe essere più professionale, il che è positivo, anche se un po’ meno divertente.
Quando hai finito di porre domande, fai clic su Stop Simulation (Arresta simulazione).

Visualizzare l’anteprima dell’agente in modalità Live

Quando visualizzi l’anteprima dell’agente in modalità Live, vengono utilizzate le classi Apex, i flussi e i modelli di prompt effettivi presenti nell’organizzazione di sviluppo per offrire una visione il più accurata possibile del comportamento dell’agente.

Nell’ambito dell’impostazione iniziale di questo badge Trailhead, hai già distribuito nell’organizzazione le classi Apex necessarie e le risorse correlate. Se in un secondo momento le modifichi nel progetto DX locale, dovrai ripeterne la distribuzione per assicurarti che siano utilizzate nell’anteprima live.

Nell’anteprima live utilizzerai anche un utente reale dell’organizzazione, ossia l’utente che hai creato nell’unità precedente. Per farlo è necessario modificare il file Agent Script. Cominciamo!

In VS Code, apri il file Agent Script Local_Info_Agent.agent nell’editor.
Nella sezione config (intorno alla riga 11), individua la proprietà default_agent_user.
Modifica il file Agent Script aggiornando il segnaposto UPDATE_WITH_YOUR_DEFAULT_AGENT_USER con il nome utente generato dallo script nell’unità precedente.
- Ad esempio, se il nome utente generato è afdx-agent@testdrive.org98eca4a312-3456xyz, la proprietà aggiornata avrà un aspetto simile al seguente:
  default_agent_user: “afdx-agent@testdrive.org98eca4a312-3456xyz”
Convalida l’agente (best practice da seguire ogni volta che modifichi un file Agent Script).
Se il riquadro Agentforce DX non è aperto, seleziona il menu contestuale (clic con il tasto destro) in un punto qualsiasi del file di script, quindi seleziona AFDX: Preview This Agent (AFDX: Visualizza l‘anteprima di questo agente).
Nell’elenco a discesa, seleziona Live Test (Test live), quindi fai clic su Start Live Test (Avvia test live) per visualizzare l’anteprima dell’agente.
Ripeti la domanda: What’s the weather like? (Che tempo fa?).

La risposta è simile a quella che hai ottenuto con la simulazione, ma questa volta l’intervallo di temperatura dovrebbe essere compreso esattamente tra 18,5 e 27,2 °C. Questo perché l’agente utilizza la vera classe Apex (WeatherService) presente nell’organizzazione, che, a scopo di test, specifica a livello di codice la temperatura in questo intervallo. Se vuoi constatarlo di persona, dai un’occhiata al file force-app/main/default/classes/WeatherService.cls.

Visualizzare e modificare l’agente nel Generatore Agentforce

Torna all’interfaccia utente del Generatore Agentforce della tua organizzazione. Qui puoi visualizzare l’anteprima dell’agente e svilupparlo, proprio come hai fatto in VS Code. In realtà, modificherai l’agente in modo che si comporti come un pagliaccio, perché abbiamo deciso che preferiamo la leggerezza alla professionalità!

Prima, però, ricorda che hai apportato qualche modifica al file Agent Script locale. Per assicurarti di lavorare con lo stesso codice quando utilizzi il generatore interno dell’organizzazione, devi distribuire il pacchetto di authoring Local_Info_Agent nell’organizzazione. Quando si utilizzano sia strumenti pro-code che low-code, è importante mantenere sincronizzati il progetto DX e l’organizzazione.

In VS Code, distribuisci il pacchetto di authoring aggiornato alla tua organizzazione eseguendo questo comando CLI nel terminal integrato.
sf project deploy start --metadata aiAuthoringBundle:Local_Info_Agent
Nel terminal viene visualizzato il seguente stato di distribuzione.
Per aprire Agentforce Studio in un browser, esegui il seguente comando CLI nel terminal integrato di VS Code.
sf org open authoring-bundle
Se viene visualizzato un messaggio relativo a un errore della posizione, fai clic su Take Me There (Portami qui).
Nella tabella, fai clic su Local Info Agent (Agente info locali) per aprirlo nel Generatore Agentforce. Se l’agente non è disponibile nella tabella, esegui di nuovo il comando sf org open authoring-bundle in VS Code.

Se non hai dimestichezza con il Generatore Agentforce, esplora le sue funzionalità. Nota che la versione del Local Info Agent (Agente info locali) è Version 1 (Draft) (Versione 1 (Bozza)). Il Generatore Agentforce aperto sul Local Info Agent (Agente info locali), con evidenziata la dicitura Version 1 (Draft) (Versione 1 (Bozza)). Anche l’elenco a discesa per il passaggio dalla visualizzazione Canvas a quella Script è evidenziato.

Nel Generatore Agentforce, seleziona la visualizzazione Script e aggiungi la seguente istruzione su una nuova riga immediatamente dopo la riga ALWAYS Provide forecasts that include a temperature range (Fornire SEMPRE previsioni che includano un intervallo di temperature), intorno alla riga 116:
```
Finally, ALWAYS give answers like you're a clown in a circus, using clown-themed language and expressions to make the interaction more engaging and fun for the user.
```
Fai clic su Save (Salva).
In via facoltativa, utilizza il pulsante Preview (Anteprima) per visualizzare l’anteprima dell’agente direttamente all’interno dell’organizzazione.
In VS Code, recupera il pacchetto di authoring aggiornato nel progetto DX dalla tua organizzazione eseguendo questo comando CLI nel terminal.
sf project retrieve start --metadata AiAuthoringBundle:Local_Info_Agent
Compila e riavvia l’anteprima in modalità Live, quindi fai di nuovo domande sul tempo. L’agente dovrebbe rispondere come un pagliaccio!

Pubblicare il pacchetto di authoring

Quando pubblichi un pacchetto di authoring nell’organizzazione, questa utilizza il file Agent Script per generare i metadati agente associati, nella loro versione iniziale o in nuove versioni. Tra i metadati agente sono inclusi componenti come Bot, BotVersion, GenAiPlannerBundle, GenAiFunction e altri. Questi metadati dell’agente portano come risultato un nuovo agente nell’organizzazione o una nuova versione di un agente esistente. A questo punto puoi testare l’agente pubblicato e, in seguito, distribuirlo nell’organizzazione di produzione in modo da poterlo attivare e rendere disponibile ai tuoi utenti. Infine, il progetto DX recupera tutti i metadati, nuovi o aggiornati, dall’organizzazione.

In VS Code, apri il file Agent Script Local_Info_Agent.agent nell’editor.
Apri il menu contestuale (clic con il tasto destro) del file Agent Script e scegli AFDX: Publish this Agent (AFDX: pubblica questo agente).
Guarda la scheda Output per vedere l’avanzamento delle fasi della pubblicazione in tempo reale. Assicurati di utilizzare l’elenco a discesa per filtrare le informazioni relative a Agentforce DX.
Utilizza l’explorer per visualizzare i metadati che sono stati recuperati nella directory del pacchetto force-app/main/default del progetto DX. L’esempio mostra il file XML del componente dei metadati GenAiPlannerBundle aperto nell’editor.
Torna al Generatore Agentforce dell’organizzazione e aggiorna la pagina. Ora dovresti avere una versione confermata del Local Info Agent (Agente info locali): Version 1 (Committed) (Versione 1 (confermata)).

La pubblicazione di un pacchetto di authoring genera nuove versioni dei metadati dell’agente, tra cui BotVersion e GenAiPlannerBundle. Nell’immagine precedente sono identificate come v1.

Attivare l’agente

Rendi disponibile l’agente Local Info affinché possa essere utilizzato dagli ospiti di Coral Clouds Resort. Da VS Code puoi attivare un agente utilizzando il suo file di metadati BotVersion.

In VS Code, usa l’explorer per passare alla directory force-app/main/default/bots/Local_Info_Agent.
Apri il menu contestuale (clic con il tasto destro) del file Local_Info_Agent.bot-meta.xml e scegli AFDX: Activate Agent (AFDX: attiva agente).
Nell’elenco a discesa nella parte superiore della finestra VS Code, fai clic su Version 1 (Versione 1).
Vai al Generatore Agentforce dell’organizzazione e aggiorna la pagina di Local Info Agent (Agente informazioni locali). Ora la versione agente dovrebbe essere attiva, come Version 1 (Active) (Versione 1 (Attiva)).

Congratulazioni! Hai utilizzato con successo Agentforce DX per programmare il file Agent Script, visualizzarne l’anteprima e pubblicarlo nella tua organizzazione. Con questi strumenti pro-code a disposizione nel toolkit, ora puoi iniziare a creare i tuoi agenti. Prima di pubblicare un agente in ambiente di produzione, ricordati di perfezionarne il tono per assicurarti che sia adeguato al caso d’uso specifico.

Tempo stimato

Argomenti

Hai bisogno di aiuto?

Risorse per Agentforce