Prepararsi alla creazione di un’azione Apex

Obiettivi di apprendimento

Al completamento di questa unità, sarai in grado di:

• Preparare l’organizzazione per la creazione di Azioni.
  
• Verificare che il codice Apex sia pronto per le Azioni.
  

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.

La nuova esperienza del Generatore Agentforce è disponibile per tutti!

Agentforce è stato aggiornato! A febbraio 2026 la nuova esperienza di creazione degli agenti è stata resa disponibile per tutti. Questo badge utilizza il generatore precedente invece di quello nuovo, ma presto verrà aggiornato. Per cominciare a utilizzare subito il nuovo generatore, completa l’itinerario Tour del nuovo Generatore Agentforce oppure consulta la documentazione di Agentforce.

Previsioni meteo: soleggiato

Come sappiamo bene, quando si va in vacanza è essenziale tenere d’occhio le previsioni meteo per elaborare alla perfezione i piani di viaggio. Nei Coral Cloud Resort gli ospiti possono contare su giornate calde e soleggiate… il più delle volte. Per garantire che gli ospiti si godano al meglio il soggiorno, con qualunque condizione meteorologica, il team di Coral Cloud vuole aggiungere agli agenti IA la funzionalità di raccolta delle informazioni sul meteo. Per farlo è necessario creare un’azione che prenda i dati meteo da una classe Apex usando un’API esterna.

Registrarsi per un’organizzazione Developer Edition con Agentforce

Per completare questo modulo hai bisogno di una speciale organizzazione Developer Edition che contenga Agentforce e i nostri dati di esempio. Registrati a questa organizzazione Developer Edition con Agentforce, personalizzata e gratuita, facendo clic sul link, quindi connettila a Trailhead per completare le sfide di questo modulo. Tieni presente che questa organizzazione è destinata a funzionare con le sfide presenti in questo badge e potrebbe non funzionare con altri badge. Controlla sempre se stai utilizzando un Trailhead Playground o la speciale organizzazione Developer Edition consigliata da noi.

1. Registrati per un’organizzazione Developer Edition gratuita con Agentforce.
   
2. Compila il modulo:
   
   1. In Email, inserisci un indirizzo email attivo.
      
   2. In Username (Nome utente), inserisci un nome utente univoco simile a un indirizzo email, che non deve necessariamente corrispondere a un account email valido (ad esempio tuonome@example.com).
      
3. Al termine, fai clic su Sign me up (Registrami). Viene visualizzato un messaggio di conferma.
   
4. Quando ricevi l'email di attivazione (potresti dover attendere qualche minuto), aprila e fai clic su Verifica account.
   
5. Completa la registrazione impostando la password e la domanda di controllo. Suggerimento: salva il nome utente, la password e l'URL di accesso in un posto sicuro, ad esempio un gestore di password, per ritrovarli facilmente in futuro.
   
6. Hai eseguito l'accesso alla tua Developer Edition.
   

Ora collega la nuova organizzazione Developer Edition a Trailhead.

1. Assicurati di aver eseguito l'accesso al tuo account Trailhead.
   
2. Nella sezione della sfida in fondo a questa pagina, fai clic sul nome dell'organizzazione e poi su Connetti organizzazione.
   
3. Nella schermata di accesso, inserisci il nome utente e la password associati alla Developer Edition che hai appena impostato.
   
4. Nella schermata Allow Access? (Consentire l'accesso?), fai clic su Allow (Consenti).
   
5. Nella schermata Vuoi connettere questa organizzazione per le sfide pratiche?, fai clic su Sì! Salva. Il sistema ti reindirizzerà alla pagina della sfida, dove potrai subito iniziare a utilizzare la tua nuova Developer Edition per ottenere questo badge.
   

Preparare l’organizzazione per gli agenti

Per poter iniziare a personalizzare gli agenti, devi prima abilitare tutte le funzionalità dell’organizzazione richieste.

1. Fai clic su e seleziona Setup (Imposta).
   
2. Utilizzando la casella Quick Find (Ricerca veloce) di Setup (Imposta), cerca e seleziona Einstein Setup (Impostazione Einstein).
   
3. Accertati che Einstein sia attivato. Se lo è, imposta il pulsante di alternanza su Off (Disattivato) e poi reimpostalo su On (Attivato).
   
   
   

4. Aggiorna il browser per caricare nuovamente la pagina Setup (Imposta).
   
5. Utilizzando la casella Quick Find (Ricerca veloce) in Setup (Imposta), cerca e seleziona Salesforce Go.
   
6. Nella casella di testo Search features… (Cerca funzioni…), inserisci e seleziona Agentforce (Default) (Agentforce (predefinito)).
   
   
   

7. Fai clic su Get Started (Per iniziare).
   
8. Fai clic su Turn On (Attiva).
   
9. Fai clic su Confirm (Conferma).
   

Creare azioni agente con funzionalità già presenti

Molto bene! È quasi tutto pronto per creare un’azione personalizzata per l’agente. Una delle ottime ragioni per creare gli agenti IA con Salesforce è che puoi utilizzare la funzionalità che è già integrata nell’organizzazione. In questo caso vuoi aggiungere a un agente IA le informazioni meteo per il Coral Cloud Resort. Coral Cloud ha già una classe Apex WeatherService (Servizio Meteo) per la posizione del Coral Cloud Resort da un’API esterna. Vediamo come applicarla a un’azione.

public with sharing class WeatherService {
    /**
     * Gets the weather at Coral Cloud Resorts for the provided date
     */
    public static Weather getResortWeather(Datetime dateToCheck) {
        Integer currentYear = Date.today().year();
        Integer yearDelta = currentYear - dateToCheck.year();
        dateToCheck = dateToCheck.addYears(yearDelta);
        String isoDate = dateToCheck.format('yyyy-MM-dd');
        String dateString = dateToCheck.format('MMMM d');
        // Prepare API request
        HttpRequest req = new HttpRequest();
        req.setEndpoint(
            'callout:Weather_Endpoint/weather?lat=37.789782764570425&lon=-122.39723702244089&date=' +
            isoDate
        );
        req.setMethod('GET');
        // Make callout
        Http http = new Http();
        HttpResponse res = http.send(req);
        if (res.getStatusCode() != 200) {
            throw new CalloutException('Bad response: ' + res);
        }
        // The response contains a list of temperatures for different times of the day
        // We parse the response and find the min and max temperatures
        String body = res.getBody();
        WeatherApiResponse weatherResponse = (WeatherApiResponse) JSON.deserialize(
            body,
            WeatherAPIResponse.class
        );
        List<Decimal> temperatures = new List<Decimal>();
        for (TemperatureWrapper item : weatherResponse.weather) {
            if (item.temperature != null) {
                temperatures.add(item.temperature);
            }
        }
        temperatures.sort();
        // Prepare temperatures and description
        Decimal minTempC = temperatures[0];
        Decimal maxTempC = temperatures[temperatures.size() - 1];
        Decimal minTempF = toFahrenheit(minTempC);
        Decimal maxTempF = toFahrenheit(maxTempC);
        String description =
            'On ' +
            dateString +
            ', temperature should be between ' +
            minTempC +
            '°C (' +
            minTempF +
            '°F) and ' +
            maxTempC +
            '°C (' +
            maxTempF +
            '°F) at Coral Cloud Resorts.';
        // Return weather info
        Weather weather = new Weather();
        weather.minTemperatureC = minTempC;
        weather.minTemperatureF = minTempF;
        weather.maxTemperatureC = maxTempC;
        weather.maxTemperatureF = maxTempF;
        weather.description = description;
        return weather;
    }
    private static Decimal toFahrenheit(Decimal celsius) {
        return (celsius * 9 / 5 + 32).setScale(1);
    }
    private class WeatherApiResponse {
        public List<TemperatureWrapper> weather;
    }
    private class TemperatureWrapper {
        public Decimal temperature;
    }
    public class Weather {
        public Decimal minTemperatureC;
        public Decimal minTemperatureF;
        public Decimal maxTemperatureC;
        public Decimal maxTemperatureF;
        public String description;
    }
}

Questa è una classe Apex semplice, che fa una richiesta HTTP a un servizio meteo per avere le previsioni relative al giorno inserito. Tuttavia, la classe Apex non è disponibile per l’uso da parte di Generatore Agentforce. Potresti aggiornare la classe e renderla di tipo Metodo invocabile, ma è meglio esercitarsi a creare una nuova classe Apex che sia impostata su un InvocableMethod che chiama il WeatherService originario. L’annotazione InvocableMethod consente di chiamare del codice Apex personalizzato da strumenti dichiarativi come i flussi, le applicazioni esterne tramite REST e Agentforce.

La buona notizia è che il team di Coral Cloud ha già creato una classe Apex che effettua chiamate a WeatherService. Diamo un’occhiata alla classe per vedere come implementa WeatherService.

public with sharing class CheckWeather {
    @InvocableMethod(
        label='Check Weather'
        description='Check weather at Coral Cloud Resorts at a specific date'
    )
    public static List<WeatherResponse> getWeather(
        List<WeatherRequest> requests
    ) {
        // Retrieve the date for which we want to check the weather
        Datetime dateToCheck = (Datetime) requests[0].dateToCheck;
        WeatherService.Weather weather = WeatherService.getResortWeather(
            dateToCheck
        );
        // Create the response for Copilot
        WeatherResponse response = new WeatherResponse();
        response.minTemperature = weather.minTemperatureC;
        response.maxTemperature = weather.maxTemperatureC;
        response.temperatureDescription =
            'Temperatures will be between ' +
            weather.minTemperatureC +
            '°C (' +
            weather.minTemperatureF +
            '°F) and ' +
            weather.maxTemperatureC +
            '°C (' +
            weather.maxTemperatureF +
            '°F) at Coral Cloud.';
        return new List<WeatherResponse>{ response };
    }
    public class WeatherRequest {
        @InvocableVariable(
            required=true
            description='Date for which we want to check the temperature. The variable needs to be an Apex Date type with format yyyy-MM-dd.'
        )
        public Date dateToCheck;
    }
    public class WeatherResponse {
        @InvocableVariable(
            description='Minimum temperature in Celsius at Coral Cloud Resorts location for the provided date'
        )
        public Decimal minTemperature;
        @InvocableVariable(
            description='Maximum temperature in Celsius at Coral Cloud Resorts location for the provided date'
        )
        public Decimal maxTemperature;
        @InvocableVariable(
            description='Description of temperatures at Coral Cloud Resorts location for the provided date'
        )
        public String temperatureDescription;
    }
}

La prima cosa da notare è l’annotazione @InvocableMethod relativa al metodo getWeather. I due parametri inseriti vengono usati nel processo Create an Agent Action (Crea un’azione agente). Il parametro label (etichetta) è visualizzato come Agent Action Label (Etichetta azione agente). Il parametro description (descrizione) è visualizzato come Agent Action Instructions (Istruzioni azione agente). Le descrizioni sono importanti per gli agenti IA e per il modo in cui l’agente capisce il metodo.

Poi troviamo due classi pubbliche, WeatherRequest (Richiesta meteo) e WeatherResponse (Risposta meteo) con annotazioni @InvocableVariable rispettivamente per l’input e gli output di Create an Agent Action (Crea un’azione agente).

Per WeatherRequest (Richiesta meteo), l’annotazione @InvocableVariable di dateToCheck (Data da controllare) ha il parametro required (richiesto) impostato su true (vero). Questo fa sì che la configurazione di Require input (Input obbligatorio) del processo Create an Agent Action (Crea un’azione agente) sia selezionata per impostazione predefinita. Il parametro description (descrizione) è visualizzato come Input sotto Instructions (Istruzioni). Inoltre, l’impostazione del tipo di variabile su Date (Data) per dateToCheck (Data da controllare) imposta il Data Type (Tipo di dati) su Input.

Per WeatherResponse (Risposta meteo) sono disponibili tre variabili con annotazione @InvocableVariable: minTemperature (Temperatura min.), maxTemperature (Temperatura max) e temperatureDescription (Descrizione temperatura). Per ciascuna di queste è impostato un parametro description (descrizione) che viene visualizzato in Create an Agent Action (Crea un’azione agente) Outputs (Output) Instructions (Istruzioni). Inoltre, i tipi di variabile Decimal (Decimale) Decimal (Decimale) e String (Stringa) sono visualizzati come Output Rendering (Rendering output). Il tipo di variabile String (Stringa) sarà impostato su Text (Testo) in Output Rendering (Rendering output).

Impostare le autorizzazioni

Come per qualsiasi funzionalità Apex, hai bisogno di autorizzazioni di accesso appropriate al file Apex. Questo passaggio è già stato completato nell’organizzazione Developer personalizzata che usi per questo badge. Le autorizzazioni sono già impostate per dare all’agente IA l’accesso alla classe Apex che contiene il metodo Invocable (Invocabile), tramite un insieme di autorizzazioni. Se così non fosse, l’agente non sarebbe in grado di tenerne conto durante la creazione di un piano, anche se tu creassi un’azione e la aggiungessi a un agente. La mancanza delle autorizzazioni appropriate è uno dei motivi principali per cui le azioni Apex non funzionano come previsto in Agentforce.

A questo punto hai un’idea più precisa di ciò che serve per usare il codice Apex per le azioni. È vero, sono tante informazioni tutte in una volta, ma ti sarà tutto più chiaro quando creerai l’azione nella prossima unità.

Risorse

• Guida per gli sviluppatori Apex: InvocableMethod Annotation (Annotazione Metodo invocabile)
• Guida per gli sviluppatori Apex: InvocableVariable Annotation (Annotazione Variabile Invocabile)
• Guida di Salesforce: Agentforce e l'IA generativa Einstein
• Guida di Salesforce: Procedure consigliate per le istruzioni di azione degli agenti