Erstellung und Bereitstellung von Invocable Apex, Flows und MuleSoft-APIs als benutzerdefinierte Aktionen in Agentforce

Salesforce Agentforce revolutioniert die Unternehmens-KI durch den Übergang von rein passiven Chatbots zu autonomen Agenten (Autonomous Agents). In realen Geschäftsszenarien beantwortet ein autonomer Agent nicht bloß Anfragen anhand statischer Wissensdatenbanken, sondern erfasst die Absicht des Kunden präzise, wählt spezialisierte Tools aus, führt Transaktionen in Echtzeit aus und bewertet das Ergebnis, um die nächsten Prozessschritte zu steuern.

Vorkonfigurierte Standardaktionen decken elementare CRM-Aufgaben wie das Verfassen von E-Mails oder Zusammenfassen von Datensätzen ab. In der betrieblichen Praxis sind jedoch proprietäre Geschäftsregeln, mehrstufige Transaktionen über heterogene Altsysteme hinweg und Echtzeitdaten aus externen Quellen unerlässlich. Salesforce-Entwickler und Unternehmensarchitekten müssen Agentforce erweitern, indem sie benutzerdefinierte Aktionen (Custom Actions) auf Basis dreier Kernsäulen bereitstellen:

1. Invocable Apex-Methoden: Deterministische, codebasierte Logik für anspruchsvolle Berechnungen, komplexe Validierungen und sichere Datenbankoperationen.
2. Headless Autolaunched Flows: Deklarative Low-Code-Automatisierungen zur Ausführung von Standard-CRM-Operationen und Genehmigungsprozessen ohne manuellen Code.
3. MuleSoft-APIs über External Services und API Catalog: Unternehmensweite Integrationsbrücken, die ERP-Systeme (wie SAP oder Oracle), Zahlungsdienstleister und verteilte Microservices direkt an die Agenten-Laufzeit anbinden.

Dieser Leitfaden erläutert die End-to-End-Architektur, die technischen Implementierungsschritte, Best Practices für Context Engineering und die Sicherheitsvorgaben zur Bereitstellung dieser drei Aktionstypen in Agentforce.

1. Kernarchitektur: Wie die Atlas Reasoning Engine Aktionen versteht und ausführt

Um zuverlässige Aktionen ohne Halluzinationen zu entwickeln, müssen Entwickler die Funktionsweise des zentralen Gehirns von Agentforce verstehen: der Atlas Reasoning Engine.

[ Benutzerinteraktion / Omni-Channel-Eingang ]
                       │
                       ▼
          [ Atlas Reasoning Engine ]
         (ReAct: Reason - Act - Observe)
                       │
       ┌───────────────┼───────────────┐
       ▼               ▼               ▼
[ Themenklassifizierung ] │ [ Kontext- und Sicherheitsfilter ]
       │               │
       └───────┬───────┘
               ▼
     [ Aktions- / Tool-Auswahl ]
               │
   ┌───────────┼───────────┐
   ▼           ▼           ▼
[ Apex ]    [ Flow ]   [ MuleSoft / API ]
   │           │           │
   └───────────┼───────────┘
               ▼
[ Strukturierte Ausgabe wird von Atlas beobachtet ]
               │
               ▼
[ Finale Antwort oder nachfolgende Aktion ]

Das ReAct-Muster und Context Engineering

Die Atlas Reasoning Engine arbeitet in einer iterativen Reason-Act-Observe (Schlussfolgern - Handeln - Beobachten) Schleife:

• Reason (Schlussfolgern): Bewertet den Dialog anhand der konfigurierten Themen (Topics) und ermittelt, welches Werkzeug (Aktion) das Anliegen des Nutzers lösen kann.
• Act (Handeln): Extrahiert die erforderlichen Parameter aus dem Kontext, ordnet sie den Eingabevariablen der Aktion zu und stößt die Ausführung an.
• Observe (Beobachten): Wertet die strukturierte Rückgabe der Aktion aus, prüft die Zielerreichung und entscheidet, ob eine Folgeaktion erforderlich ist oder eine Antwort in natürlicher Sprache formuliert wird.

In der klassischen Softwareentwicklung kommunizieren Module über strikte Typen und direkte Methodenaufrufe. In der Welt autonomer Agenten gilt: Metadaten sind der Prompt. Das Sprachmodell liest nicht den inneren Apex-Code, sondern interpretiert label, description, Parameter-Annotationen und die natürlichen Aktionsanweisungen (Action Instructions). Unklare Beschreibungen führen zu Tool-Fehlzuordnungen und fehlerhafter Parameterbelegung, während präzise Beschreibungen deterministische Ausführungen garantieren.

2. Erstellung und Bereitstellung von Invocable Apex als benutzerdefinierte Aktionen

Invocable Apex ist das Mittel der Wahl, wenn Geschäftsprozesse komplexe Algorithmen, mehrstufige Datenabfragen oder strikte Transaktions- und Sicherheitsgrenzen erfordern.

Schritt 1: Entwurf der Invocable Apex-Klasse

Agentforce erkennt Methoden über die @InvocableMethod-Annotation. Die Methode muss public oder global und statisch sein, eine Liste (List) von Eingabe-Wrapper-Objekten annehmen und eine Liste (List) von Ausgabe-Wrapper-Objekten zurückgeben.

Beispiel für eine unternehmensgerechte Implementierung zur Auftragsstornierung:

public with sharing class OrderCancellationService {

    // Eingabe-Wrapper: Definiert die vom Agenten geforderten Parameter
    public class OrderCancellationRequest {
        @InvocableVariable(
            label = 'Order Number' 
            description = 'Eindeutige alphanumerische Auftragsnummer, z. B. ORD-10023.' 
            required = true
        )
        public String orderNumber;

        @InvocableVariable(
            label = 'Cancellation Reason' 
            description = 'Vom Kunden angegebener Grund für die Stornierung.' 
            required = false
        )
        public String reason;
    }

    // Ausgabe-Wrapper: Strukturierte Rückgabedaten an die Atlas Reasoning Engine
    public class OrderCancellationResult {
        @InvocableVariable(
            label = 'Is Success' 
            description = 'Boolescher Wert, der angibt, ob die Stornierung erfolgreich war.'
        )
        public Boolean isSuccess;

        @InvocableVariable(
            label = 'Cancellation Reference Code' 
            description = 'Revisionssicherer Bestätigungscode für die Stornierung.'
        )
        public String referenceCode;

        @InvocableVariable(
            label = 'Status Message' 
            description = 'Ergebnisbeschreibung oder konkrete Fehlerursache im Detail.'
        )
        public String message;
    }

    @InvocableMethod(
        label = 'Cancel Customer Order'
        description = 'Storniert einen ausstehenden Auftrag und generiert einen Prüfcode. Nur verwenden, wenn der Auftragsstatus Pending oder Processing ist und der Kunde die Stornierung ausdrücklich verlangt.'
        category = 'Order Management'
    )
    public static List<OrderCancellationResult> cancelOrders(List<OrderCancellationRequest> requests) {
        List<OrderCancellationResult> results = new List<OrderCancellationResult>();

        for (OrderCancellationRequest req : requests) {
            OrderCancellationResult res = new OrderCancellationResult();
            
            try {
                // Sicherheitsabfrage im User Mode
                List<Order> orders = [
                    SELECT Id, Status, TotalAmount 
                    FROM Order 
                    WHERE OrderNumber = :req.orderNumber 
                    WITH USER_MODE 
                    LIMIT 1
                ];

                if (orders.isEmpty()) {
                    res.isSuccess = false;
                    res.message = 'Kein aktiver Auftrag mit der Nummer gefunden: ' + req.orderNumber;
                    results.add(res);
                    continue;
                }

                Order targetOrder = orders[0];
                if (targetOrder.Status == 'Activated' || targetOrder.Status == 'Completed') {
                    res.isSuccess = false;
                    res.message = 'Auftrag ' + req.orderNumber + ' ist bereits abgeschlossen oder versandt und kann nicht automatisch storniert werden.';
                    results.add(res);
                    continue;
                }

                targetOrder.Status = 'Cancelled';
                targetOrder.Description = 'Storniert über Agentforce. Grund: ' + (req.reason != null ? req.reason : 'Keine Angabe');

                Database.SaveResult sr = Database.update(targetOrder, AccessLevel.USER_MODE);
                if (sr.isSuccess()) {
                    res.isSuccess = true;
                    res.referenceCode = 'CAN-' + System.currentTimeMillis();
                    res.message = 'Auftrag erfolgreich storniert.';
                } else {
                    res.isSuccess = false;
                    res.message = 'Aktualisierung des Datensatzes in der Datenbank fehlgeschlagen.';
                }
            } catch (Exception ex) {
                res.isSuccess = false;
                res.message = 'Interner Fehler während der Stornierung: ' + ex.getMessage();
            }

            results.add(res);
        }

        return results;
    }
}

Wichtige Apex-Best-Practices für Agentforce

• Atomare Aktionen statt monolithischer Alleskönner (God Classes): Fassen Sie nicht Abfrage, Zahlungsabwicklung, Lagerbuchung und Versand in einer einzigen Riesenmethode zusammen. Halten Sie Aktionen modular, damit die Atlas Engine Teilschritte nachvollziehbar kombinieren kann.
• Strukturierte Fehlerobjekte statt unbehandelter Exceptions: Unbehandelte Laufzeitfehler führen zum Abbruch des Dialogs. Fangen Sie Fehler per try-catch ab und übergeben Sie isSuccess = false mit einer klaren message. So kann der Agent dem Kunden die Situation erläutern oder fehlende Details gezielt nachfragen.
• User Mode erzwingen: Verwenden Sie WITH USER_MODE in SOQL und AccessLevel.USER_MODE bei DML-Operationen, damit der Agent strikt innerhalb der Feld- und Objektberechtigungen des konfigurierten Agent Users agiert.

Schritt 2: Registrierung der Apex-Aktion im Setup

1. Öffnen Sie in Salesforce das Setup, tippen Sie Agent in das Schnellsuche-Feld und wählen Sie Agentforce Assets (oder Agent Actions).
2. Klicken Sie auf New Agent Action.
3. Wählen Sie als Reference Action Type den Typ Apex.
4. Selektieren Sie die Klasse OrderCancellationService und die Methode Cancel Customer Order.
5. Überprüfen Sie die automatisch aus den Code-Annotationen übernommenen Bezeichnungen und Beschreibungen.
6. Ergänzen Sie die Action Instructions (Aktionsanweisungen) (z. B.: „Nur ausführen, wenn ein authentifizierter Kunde die Stornierung ausdrücklich verlangt. Bei fehlender Auftragsnummer gezielt nachfragen“).
7. Speichern Sie die Aktion ab.

3. Bereitstellung von Headless Flows als benutzerdefinierte Aktionen

Für standardmäßige CRM-Datensatzänderungen, das Auslösen bestehender Genehmigungsverfahren und deklarative Geschäftslogiken bieten Autolaunched Flows eine entwicklungsarme, hochgradig wartbare Alternative.

Einschränkung des Flow-Typs

Agentforce unterstützt ausschließlich Autolaunched Flows (No Trigger) (automatisch gestartete Flows ohne Trigger). Screen Flows setzen eine menschliche Bildschirminteraktion voraus, während Record-Triggered Flows an Datenbankereignisse gekoppelt sind. Ein Headless Flow bietet eine klare Request-Response-Schnittstelle, die ideal zum ReAct-Laufzeitmodell passt.

[ Nutzeranfrage: "Bitte ändere meine Lieferadresse auf Hauptstraße 10" ]
                               │
                               ▼
               [ Agentforce Aktionsplaner ]
                               │
       (Extrahiert Parameter: orderId, streetAddress, city)
                               │
                               ▼
     [ Autolaunched Flow: Lieferadresse des Auftrags ändern ]
              ┌─────────────────────────┐
              │ Get Record: Auftrag     │
              ├─────────────────────────┤
              │ Decision: Lieferstatus  │
              ├─────────────────────────┤
              │ Update Record: Adresse  │
              └─────────────────────────┘
                               │
      (Ausgabevariablen: isUpdated = True, Rückmeldung)
                               │
                               ▼
              [ Atlas formuliert finale Antwort ]

Schrittweise Flow-Konfiguration

1. Flow anlegen: Öffnen Sie den Flow Builder und wählen Sie Autolaunched Flow (No Trigger).
2. Eingabevariablen deklarieren:
   • Erstellen Sie die Textvariable var_orderId.
   • Aktivieren Sie das Kontrollkästchen Available for input (Für Eingabe verfügbar).
   • Tragen Sie unter Description (Beschreibung) ein: „Die 18-stellige Salesforce-Datensatz-ID des Auftrags“.
   • Erstellen Sie weitere Eingabevariablen (var_streetAddress etc.) mit präzisen Beschreibungen.
3. Ausgabevariablen deklarieren:
   • Erstellen Sie die boolesche Variable var_isUpdated, markieren Sie sie als Available for output (Für Ausgabe verfügbar) und beschreiben Sie sie: „True, wenn die Adressänderung erfolgreich gespeichert wurde“.
   • Erstellen Sie die Textvariable var_statusMessage und markieren Sie sie ebenfalls als für die Ausgabe verfügbar.
4. Logik aufbauen:
   • Fügen Sie ein Get Records-Element zum Laden des Auftrags ein.
   • Prüfen Sie per Decision-Element, ob der Auftrag noch bearbeitbar ist.
   • Aktualisieren Sie die Adresse über ein Update Records-Element.
   • Weisen Sie die Ergebniswerte den Ausgabevariablen per Assignment-Element zu.
5. Speichern und aktivieren: Speichern Sie den Flow unter Agent_Update_Order_Address und aktivieren Sie ihn.

Schritt 3: Registrierung der Flow-Aktion

1. Navigieren Sie zu Setup > Agentforce Assets > New Agent Action.
2. Wählen Sie Reference Action Type = Flow.
3. Selektieren Sie Agent_Update_Order_Address.
4. Stellen Sie sicher, dass alle für Ein- und Ausgabe freigegebenen Variablenbeschreibungen für das Sprachmodell verständlich sind.
5. Hinterlegen Sie Aktionsanweisungen und speichern Sie die Aktion.

4. Bereitstellung von MuleSoft-APIs über External Services und den API Catalog

Unternehmensagenten müssen oft auf Systeme außerhalb von Salesforce zugreifen, etwa auf ERP-Systeme (SAP, Oracle), Lagerverwaltungssysteme oder Bezahldienstleister. MuleSoft übernimmt dabei die Integrationsschicht und Sicherheit, während Salesforce diese APIs über External Services und den Salesforce API Catalog als Agentforce-Aktionen verfügbar macht.

Integrationspfade im Vergleich

[ ERP-System / SAP / Lokale Datenbank ]
                   │
                   ▼
     [ MuleSoft Anypoint Platform ]
  (System, Process, Experience APIs)
                   │
     (Topic Center / OAS 3.0-Spezifikation)
                   │
                   ▼
   [ Salesforce Anypoint-Setup / Sync ]
                   │
      ┌────────────┴────────────┐
      ▼                         ▼
[ Named Credentials ]   [ Salesforce API Catalog ]
 (Sichere Authentifizierung) (Zentraler API-Katalog)
      │                         │
      └────────────┬────────────┘
                   ▼
       [ External Services ]
    (Generiert Invocable Actions)
                   │
                   ▼
   [ Agentforce-Aktionsbibliothek ]

Schritt 1: Konzeption KI-gerechter OpenAPI-Spezifikationen (OAS)

Die Atlas Reasoning Engine parst die OpenAPI-Spezifikation, um Endpunkte, Abfrageparameter und Nutzlasten zu identifizieren. Für Agenten-APIs gelten folgende Leitlinien:

• Lückenlose Beschreibungen: Jeder Pfad- und Abfrageparameter sowie jedes JSON-Attribut muss ein verständliches description-Feld besitzen.
• Flache Schemata: Vermeiden Sie polymorphe Konstrukte (oneOf, anyOf) sowie übermäßig tief verschachtelte Arrays, um Extraktionsfehler des Sprachmodells zu minimieren.
• Aussagekräftige Statuscodes und Fehlerkörper: Definieren Sie für Fehlerfälle (400, 404, 500) strukturierte JSON-Fehlermeldungen.

Beispiel einer OpenAPI 3.0-Spezifikation für Bestandsabfragen:

openapi: 3.0.3
info:
  title: Enterprise Warehouse API
  version: 1.0.0
  description: Echtzeit-Lagerbestands- und Verfügbarkeitsabfrage.
paths:
  /inventory/{sku}:
    get:
      summary: Lagerbestand nach Artikelnummer (SKU) abfragen
      description: Liefert verfügbare Stückzahl, Lagerstandort und Wiederbeschaffungszeit für eine Produkt-SKU.
      operationId: getInventoryBySku
      parameters:
        - name: sku
          in: path
          required: true
          description: Eindeutige Artikelnummer, z. B. PROD-WIDGET-99.
          schema:
            type: string
      responses:
        '200':
          description: Bestandsabfrage erfolgreich
          content:
            application/json:
              schema:
                type: object
                properties:
                  sku:
                    type: string
                    description: Die abgefragte Produkt-SKU.
                  quantityOnHand:
                    type: integer
                    description: Physisch im Lager verfügbarer Bestand.
                  isAvailableToShip:
                    type: boolean
                    description: Gibt an, ob der Artikel sofort versandbereit ist.
                  warehouseRegion:
                    type: string
                    description: Region des zuständigen Logistikzentrums.
        '404':
          description: Artikelnummer im System nicht gefunden

Schritt 2: Synchronisation und Aktionserstellung in Salesforce

1. Anypoint-Verbindung einrichten: Richten Sie im Salesforce-Setup unter Anypoint Platform Setup die Authentifizierung über Ihre Organisations-ID und Client-Zugangsdaten ein.
2. API Catalog synchronisieren: Versehen Sie die API im MuleSoft Topic Center oder Exchange mit dem Tag sf-api-catalog. Aktivieren Sie im Salesforce API Catalog die gewünschten Operationen als Aktionen.
3. Named Credentials konfigurieren: Weisen Sie der Schnittstelle eine Named Credential mit OAuth 2.0 zu, um ausgehende HTTP-Aufrufe abzusichern.
4. Agenten-Aktion anlegen: Erstellen Sie in den Agentforce Assets eine Aktion vom Typ External Service und verknüpfen Sie die Operation.

5. Konfiguration im Agentforce Builder (Die Themen-Ebene)

Benutzerdefinierte Aktionen existieren nicht isoliert, sondern müssen im Agentforce Builder einem Thema (Topic) zugewiesen werden. Themen strukturieren die Domänen und steuern, welche Werkzeuge dem Agenten in welchem Kontext zur Verfügung stehen.

[ Autonomer Agent: Kundenservice-Agent ]
                   │
   ┌───────────────┴───────────────┐
   ▼                               ▼
[ Thema: Auftragslogistik ]    [ Thema: Technischer Support ]
 (Zuständigkeit und Routing)    (Zuständigkeit und Routing)
   │
   ├───┬───────────────────────────┐
   ▼   ▼                           ▼
[ Status abfragen ]         [ Auftrag stornieren ]
(Autolaunched Flow)         (Invocable Apex)

Konfigurationsschritte

1. Öffnen Sie den Agentforce Builder im Setup und bearbeiten Sie den gewünschten Agenten.
2. Wählen Sie ein bestehendes Thema oder erstellen Sie ein neues (New Topic, z. B. Order Logistics and Changes).
3. Formulieren Sie die Topic Classification Description: Erläutern Sie präzise, welche Anfragen in dieses Themenfeld fallen.
4. Klicken Sie im Reiter Actions auf Add Action und fügen Sie die erstellten Apex-, Flow- oder MuleSoft-Aktionen hinzu.

Verfassen effektiver Themen- und Aktionsanweisungen

Instruktionen in natürlicher Sprache bilden die Leitplanken für die Entscheidungsfindung des Modells:

### Themenanweisungen: Order Logistics and Changes
- Unterstütze Kunden bei Sendungsverfolgung, Statusfragen, Adressänderungen und Stornierungen.
- Vor einer Stornierung stets den aktuellen Bearbeitungsstatus prüfen und den Kunden ausdrücklich um Bestätigung bitten.
- Kann ein Auftrag nicht storniert werden, weil er bereits versandt wurde, die Rückgaberichtlinien erklären.

### Aktionsanweisungen: Cancel Customer Order
- Diese Aktion erst ausführen, wenn der Kunde die Auftragsnummer genannt und der Stornierung zugestimmt hat.
- Fehlt die Auftragsnummer, nachfragen: „Könnten Sie mir bitte die Auftragsnummer nennen, die storniert werden soll?“
- Nach erfolgreicher Ausführung den Rückgabecode (referenceCode) an den Kunden übermitteln.

Human-in-the-Loop und Vorabbestätigung

Für zustandsverändernde Operationen (Datensatzaktualisierungen, Stornierungen, Zahlungen) sollte in den Aktionseinstellungen die Option Require Confirmation (Bestätigung anfordern) aktiviert werden. Dadurch holt Agentforce vor der eigentlichen Ausführung eine ausdrückliche Bestätigung ein (z. B.: „Sind Sie sicher, dass Sie Auftrag ORD-10023 stornieren möchten? Dies kann nicht rückgängig gemacht werden.“).

6. Entscheidungsmatrix für die Architekturauswahl

Die fundierte Wahl zwischen den drei Aktionstypen optimiert Entwicklungsgeschwindigkeit, Systemstabilität und Reaktionszeit.

7. Teststrategie, Berechtigungen und Produktivsetzung

1. Berechtigungen des Agent Users

Aktionen laufen im Kontext des konfigurierten Agent Users. Viele Fehlerursachen nach dem Deployment beruhen auf unzureichenden Rechten:

• Apex-Klassenberechtigung: Weisen Sie dem Profil oder Permission Set des Agent Users Zugriff auf die Apex-Klassen zu.
• Flow-Berechtigungen: Prüfen Sie, ob der Agent User die Systemberechtigung Run Flows besitzt und Zugriff auf den spezifischen Flow hat.
• Named Credentials und Feldebene (FLS): Hinterlegen Sie Zugriff auf die genutzten Named Credentials und gewähren Sie Lese- und Schreibrechte (FLS) auf die betroffenen Felder und Objekte.

2. Mehrstufige Qualitätssicherung

1. Apex-Unit-Tests: Schreiben Sie Unit-Tests mit mindestens 85 % Codeabdeckung, die insbesondere Null-Werte, Exception-Handling und User-Mode-Sicherheit abdecken.
2. Interaktive Tests im Agentforce Builder: Nutzen Sie das Vorschaufenster, um echte Kundenanfragen einzugeben. Beobachten Sie im Reasoning-Protokoll, ob Atlas das richtige Thema wählt, alle Parameter extrahiert und Rückgabewerte korrekt verarbeitet.
3. Massenprüfungen im Agentforce Testing Center: Validieren Sie Hunderte von Fragevarianten automatisiert, um Tool-Auswahlgenauigkeit, Parameterpräzision und Halluzinationsraten quantitativ zu messen.

Durch die Symbiose aus programmatischer Präzision (Invocable Apex), deklarativer Flexibilität (Autolaunched Flows) und unternehmensweiter Vernetzung (MuleSoft APIs) schaffen Entwicklungsteams ein sicheres und zukunftssicheres Fundament für autonome KI-Agenten auf der Salesforce-Plattform.

Referenzen

• Agent Customization with Apex | Salesforce Trailhead
• Learn How to Make Agent-Ready Flows | Salesforce Trailhead
• How to Write Effective Natural Language Instructions for Agentforce | Salesforce Developers Blog
• A Developer’s Guide to Context Engineering with Agentforce | Salesforce Developers Blog
• Salesforce Agentforce Specialist Certification Guide & Tips | Salesforce Ben
• External Services | Salesforce Help