Vorbereiten auf die Erstellung einer Apex-Aktion

Lernziele

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:

• Vorbereiten Ihrer Organisation auf die Erstellung von Aktionen
  
• Prüfen, ob Ihr Apex-Code für Aktionen bereit ist
  

Hinweis

Lernen Sie auf Deutsch? Beginnen Sie die Aufgabe in einem Trailhead Playground in der Sprache Deutsch und verwenden Sie für die Navigation die in Klammern angegebenen Übersetzungen. Kopieren und fügen Sie nur die Angaben in Englisch ein, da zur Überprüfung der Aufgabe Daten in Englisch benötigt werden. Wenn Sie die Aufgabe in Ihrer deutschen Organisation nicht bestehen, empfehlen wir Ihnen folgende Vorgehensweise: (1) Stellen Sie das Gebietsschema auf USA um, (2) legen Sie Englisch als Sprache fest (Anweisungen dazu finden Sie hier) und (3) klicken Sie erneut auf die Schaltfläche "Check Challenge" (Aufgabe überprüfen).

Weitere Details dazu, wie Sie die übersetzte Trailhead-Umgebung optimal nutzen können, finden Sie unter dem Badge "Trailhead in Ihrer Sprache".

Der neue Agentforce Builder (Agentforce-Generator) ist jetzt allgemein verfügbar!

Agentforce wurde überarbeitet! Seit Februar 2026 ist die neue Agentenerstellungs-Erfahrung allgemein verfügbar. Bei diesem Badge wird zwar noch der bisherige Generator verwendet, die Inhalte werden jedoch bald aktualisiert. Für den Einstieg in den neuen Generator absolvieren Sie den Trail Tour durch den neuen Agentforce-Generator oder lesen in der Agentforce-Dokumentation nach.

Wettervorhersage: Wolkenlos und sonnig

Jeder Urlauber weiß, dass es für eine optimale Reiseplanung wichtig ist, das Wetter im Auge zu behalten. Und im Coral Cloud Resorts können Gäste mit Sonnenschein und warmen Temperaturen rechnen ... bis sich dies plötzlich ändert. Um sicherzustellen, dass die Gäste unabhängig vom Wetter das Beste aus ihrem Aufenthalt machen können, möchte das Team von Coral Cloud die Möglichkeit, Wetterinformationen zu sammeln, zu seinen KI-Agenten hinzufügen. Dazu müssen sie eine Aktion erstellen, die Wetterdaten mithilfe einer externen API aus einer Apex-Klasse abruft.

Registrieren für eine Developer Edition-Organisation mit Agentforce

Für die Durchführung dieses Moduls benötigen Sie eine spezielle Developer Edition-Organisation, die Agentforce und unsere Beispieldaten enthält. Registrieren Sie sich für diese kostenlose, angepasste Developer Edition-Organisation mit Agentforce, indem Sie auf den Link klicken, und verbinden Sie sie jetzt mit Trailhead, damit Sie die Aufgaben in diesem Modul abschließen können. Beachten Sie, dass diese Organisation auf die Aufgaben in diesem Badge ausgelegt ist und eventuell bei anderen Badges nicht funktioniert. Stellen Sie immer sicher, dass Sie die von uns empfohlene Trailhead Playground- oder spezielle Developer Edition-Organisation verwenden.

1. Registrieren Sie sich für eine kostenlose Developer Edition-Organisation mit Agentforce.
   
2. Füllen Sie das Formular aus:
   
   1. Geben Sie im E-Mail-Feld eine aktive E-Mail-Adresse ein.
      
   2. Geben Sie im Feld "Username" (Benutzername) einen Benutzernamen ein, der wie eine E-Mail-Adresse aussieht und eindeutig ist. Er muss jedoch nicht zwingend einen gültigen E-Mail-Account bezeichnen (Beispiel: IhrName@beispiel.com).
      
3. Wenn Sie das Formular ausgefüllt haben, klicken Sie auf Registrieren. Daraufhin wird eine Bestätigungsmeldung angezeigt.
   
4. Warten Sie, bis Sie die Aktivierungs-E-Mail erhalten (dies kann einige Minuten dauern), öffnen Sie diese und klicken Sie darin auf Account bestätigen.
   
5. Schließen Sie die Registrierung ab, indem Sie Ihr Kennwort und die Überprüfungsfrage festlegen. Tipp: Speichern Sie Ihren Benutzernamen, das Kennwort und die Anmelde-URL an einem sicheren Ort – etwa einem Kennwort-Manager –, um später leicht darauf zugreifen zu können.
   
6. Sie sind bei Ihrer Developer Edition angemeldet.
   

Verbinden Sie nun Ihre neue Developer Edition-Organisation mit Trailhead.

1. Stellen Sie sicher, dass Sie bei Ihrem Trailhead-Account angemeldet sind.
   
2. Klicken Sie unten auf dieser Seite im Abschnitt "Challenge (Aufgabe)" auf den Org-Namen und dann auf Connect Org (Organisation verbinden).
   
3. Geben Sie im Anmeldebildschirm den Benutzernamen und das Kennwort für die Developer Edition ein, die Sie gerade eingerichtet haben.
   
4. Klicken Sie im Bildschirm "Zugriff zulassen?" auf Zulassen.
   
5. Klicken Sie im Bildschirm "Möchten Sie diese Organisation für praktische Übungsaufgaben speichern?" auf Ja! Organisation speichern. Sie gelangen wieder zurück zur Aufgabenseite und können nun Ihre neue Developer Edition nutzen, um sich diesen Badge zu verdienen.
   

Vorbereiten der Organisation auf Agenten

Bevor Sie mit dem Anpassen der Agenten beginnen können, aktivieren Sie alle erforderlichen Funktionen der Organisation.

1. Klicken Sie auf Setup und wählen Sie Setup aus.
   
2. Suchen Sie in Setup im Feld "Quick Find" (Schnellsuche) nach Einstein Setup (Einstein-Setup) und wählen Sie diesen Eintrag dann aus.
   
3. Prüfen Sie, ob Einstein aktiviert ist. Ist Einstein bereits aktiviert, stellen Sie den Umschalter auf Off (Aus) und dann wieder auf On (An).
   
   
   

4. Aktualisieren Sie Ihren Browser, um Setup neu zu laden.
   
5. Suchen Sie in Setup im Feld "Quick Find" (Schnellsuche) nach Salesforce Go und wählen Sie diesen Eintrag aus.
   
6. Geben Sie in das Textfeld "Search features... " (Funktionen suchen…) Agentforce (Default) (Agentforce (Standard)) und wählen Sie diesen Eintrag aus.
   
   
   

7. Klicken Sie auf Get Started (Erste Schritte).
   
8. Klicken Sie auf Turn On (Aktivieren).
   
9. Klicken Sie auf Confirm (Bestätigen).
   

Erstellen von Agentenaktionen mit bereits vorhandener Funktionalität

Okay, okay, okay! Sie sind fast bereit, eine benutzerdefinierte Aktion für Ihren Agenten zu erstellen. Eines der wichtigsten Argumente für die Erstellung von KI-Agenten mit Salesforce ist, dass Sie die bereits in Ihre Organisation integrierte Funktionalität nutzen können. In diesem Fall möchten Sie die Wetterinformationen für das Coral Cloud Resort zu einem KI-Agenten hinzufügen. Coral Cloud verfügt bereits über eine Apex-Klasse "WeatherService", um die Wetterdaten für den Standort des Coral Cloud Resorts von einer externen API abzurufen. Sehen wir uns die Anwendung auf eine Aktion an.

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;
    }
}

Dies ist eine unkomplizierte Apex-Klasse, die eine HTTP-Anfrage an einen Wetterdienst sendet, um die Wettervorhersage für den eingegebenen Tag abzurufen. Die Apex-Klasse steht jedoch nicht für die Verwendung durch Agentforce Builder (Agentforce-Generator) zur Verfügung. Sie könnten diese Klasse aktualisieren, um sie zu einer aufrufbaren Methode zu machen, es hat sich jedoch bewährt, eine neue Apex-Klasse zu erstellen, die als "InvocableMethod" festgelegt ist und den ursprünglichen Wetterdienst "WeatherService" aufruft. Mit der Anmerkung "InvocableMethod" können Sie benutzerdefinierten Apex-Code aus deklarativen Tools wie Flows, externen Anwendungen über REST und Agentforce aufrufen.

Die gute Nachricht ist, dass das Coral Cloud-Team eine Apex-Klasse erstellt hat, die bereits Aufrufe an WeatherService sendet. Wir sehen uns nun die Klasse und ihre Impementierung von WeatherService an.

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;
    }
}

Hier sollten wir zuerst die Anmerkung @InvocableMethod für die Methode getWeather beachten. Die zwei übergebenen Parameter werden im Prozess "Create an Agent Action" (Agentenaktion erstellen) verwendet. Der Parameter label wird als "Agent Action Label" (Agentenaktionsbezeichnung) angezeigt. Der Parameter description wird als "Agent Action Instructions" (Agentenaktionsanweisungen) angezeigt. Beschreibungen sind wichtig bei KI-Agenten und dafür, wie der Agent die Methode versteht.

Darüberhinaus gibt es zwei öffentliche Klassen, WeatherRequest und WeatherResponse mit @InvocableVariable-Anmerkungen für "Input" (Eingabe) bzw. "Outputs" (Ausgaben) von "Create an Agent Action" (Agentenaktion erstellen).

In Fall von WeatherRequest ist bei der @InvocableVariable-Anmerkung für dateToCheck der Parameter required auf true festgelegt. Dies erzwingt, dass die "Require Input"-Konfiguration (Eingabe erforderlich) bei "Create an Agent Action" (Agentenaktion erstellen) standardmäßig aktiviert ist. Der Parameter description wird als "Input Instructions" (Eingabeanweisungen) angezeigt. Durch Festlegen des Variablentyps Date für dateToCheck wird zudem der "Input Data Type" (Eingabedatentyp) eingestellt.

Bei WeatherResponse gibt es drei Variablen mit @InvocableVariable-Anmerkung: minTemperature, maxTemperature und temperatureDescription. Bei allen drei ist ein description-Parameter festgelegt, der in "Outputs Instructions" (Ausgabeanweisungen) von "Create an Agent Action" (Agentenaktion erstellen) angezeigt wird. Zudem werden die Variablentypen Decimal, Decimal und String als "Output Rendering" (Ausgabe-Rendering) angezeigt. Der Variablentyp String wird für "Output Rendering" (Ausgabe-Rendering) auf "Text" festgelegt.

Einrichten der Berechtigungen

Wie bei jeder Apex-Funktion müssen Sie über den richtigen Zugriff auf die Apex-Datei verfügen. Dieser Schritt ist in der benutzerdefinierten Developer-Organisation, die Sie für diesen Badge verwenden, bereits erledigt. Die Berechtigungen wurden bereits eingerichtet, sodass der KI-Agent über einen Berechtigungssatz Zugriff auf die Apex-Klasse hat, die die aufrufbare Methode enthält. Wäre dies nicht der Fall, könnte der Agent sie beim Erstellen eines Plans nicht berücksichtigen, selbst wenn Sie eine Aktion erstellt und zu einem Agenten hinzugefügt hätten. Das Fehlen der richtigen Berechtigungen ist einer der Hauptgründe, warum Apex-Aktionen in Agentforce nicht wie erwartet funktionieren.

Sie haben nun eine bessere Vorstellung davon, was erforderlich ist, damit Apex für Aktionen verwendet werden kann. Das war jetzt zwar etwas viel auf einmal – der Nebel wird sich jedoch lichten, wenn Sie die Aktion in der nächsten Lektion erstellen.

Ressourcen

• Apex Developer Guide: Anmerkung "InvocableMethod"
• Apex Developer Guide: Anmerkung "InvocableVariable"
• Salesforce-Hilfe: Agentforce und Einstein Generative AI
• Salesforce-Hilfe: Bewährte Vorgehensweisen für Agentenaktionsanweisungen