Agentforce における Invocable Apex、Flow、MuleSoft API をカスタムアクションとして構築・公開する方法

Salesforce Agentforce は、企業向け AI を単なる受動的なチャットボットから、自律的に判断しタスクを実行するエージェント（Autonomous Agent）へと進化させています。実際のビジネス環境において、エージェントにはナレッジベースに基づく回答だけでなく、顧客の意図を正確に理解し、バックエンドのツールを選択し、リアルタイムにトランザクションを実行してその結果に基づき次のステップを決定する能力が求められます。

標準で提供される標準アクション（Standard Actions）は、メールのドラフト作成やレコードの要約など、汎用的な CRM タスクに対応しています。しかし、エンタープライズの現場では、独自ビジネスロジックの適用、基幹システムをまたぐ多段階のトランザクション、外部データのリアルタイム参照が不可欠です。Salesforce 開発者やエンタープライズアーキテクトは、以下の 3 つの主要な技術基盤を用いて**カスタムアクション（Custom Actions）**を構築し、Agentforce を拡張する必要があります。

1. Invocable Apex メソッド: 複雑な計算、厳格なバリデーション、高度な SOQL クエリなど、決定論的な実行が求められるプログラマティックロジック。
2. ヘッドレス自動起動フロー（Autolaunched Flow）: 管理者やローコード開発者が迅速にメンテナンス可能な、標準 CRM レコードの作成・更新および承認プロセス。
3. External Services および API Catalog 経由の MuleSoft API: SAP や Oracle などの ERP、決済基盤、外部マイクロサービスをエージェントに直接接続する統合インターフェース。

本ガイドでは、これら 3 種類のアクションのアーキテクチャ、具体的な実装ステップ、コンテキストエンジニアリングの勘所、およびセキュリティガバナンスについて網羅的に解説します。

1. コアアーキテクチャ: Atlas 推論エンジンがアクションを理解・実行する仕組み

高い信頼性を持ち、ハルシネーション（幻覚）を起こさないアクションを構築するには、Agentforce の頭脳である Atlas 推論エンジン（Atlas Reasoning Engine） の動作原理を把握することが不可欠です。

[ ユーザーとの対話 / オムニチャネル接点 ]
                    │
                    ▼
          [ Atlas 推論エンジン ]
       (ReAct: 推論 - 行動 - 観察)
                    │
       ┌────────────┼────────────┐
       ▼            ▼            ▼
[ トピック分類 ]    │   [ ガードレールとコンテキスト ]
       │            │
       └─────┬──────┘
             ▼
      [ アクション選択 ]
             │
   ┌─────────┼─────────┐
   ▼         ▼         ▼
[ Apex ]  [ Flow ]  [ MuleSoft / API ]
   │         │         │
   └─────────┼─────────┘
             ▼
    [ 実行結果の観察と評価 ]
             │
             ▼
  [ 最終応答の生成または次アクション実行 ]

ReAct パターンとコンテキストエンジニアリング

Atlas 推論エンジンは、Reason-Act-Observe（推論・行動・観察） のループに沿って動作します。

• Reason（推論）: ユーザーからの発話や外部イベントを評価し、設定された**トピック（Topics）**に基づいて対応可能なアクション（ツール）を特定します。
• Act（行動）: 会話コンテキストから必要なパラメータを抽出し、アクションの入力スキーマにマッピングして実行します。
• Observe（観察）: アクションから返された構造化出力を解析し、ユーザーの目的が達成されたかを検証します。追加の処理が必要であれば次のアクションを呼び出し、完了していれば自然言語の回答を生成します。

従来のプログラミングでは厳密な型定義と直接的なメソッド呼び出しで連携しますが、自律型エージェントの世界ではメタデータこそがプロンプトとなります。LLM は Apex クラスの内部コードを直接読むのではなく、アクションの label、description、入力変数の注釈、および自然言語によるアクション指示（Action Instructions）を解釈します。曖昧な説明はツールの誤選択を招き、具体的かつ明確な説明が決定論的で安定した動作を保証します。

2. Invocable Apex によるカスタムアクションの構築と公開

複雑な分岐処理、複数オブジェクトにまたがるトランザクション、高いパフォーマンスが求められるシナリオでは、Invocable Apex が最も強力な手段となります。

ステップ 1: Invocable Apex クラスの実装

Agentforce は @InvocableMethod アノテーションを通じて Apex を検出します。メソッドは public または global の static メソッドであり、入力ラッパークラスの List を受け取り、出力ラッパークラスの List を返す必要があります。

以下は、注文キャンセルのビジネスロジックを実装した標準的なコード例です。

public with sharing class OrderCancellationService {

    // エージェントが必要とする入力パラメータを定義するラッパークラス
    public class OrderCancellationRequest {
        @InvocableVariable(
            label = 'Order Number' 
            description = 'キャンセル対象の注文番号（例: ORD-10023）。' 
            required = true
        )
        public String orderNumber;

        @InvocableVariable(
            label = 'Cancellation Reason' 
            description = '顧客から申告されたキャンセルの理由。' 
            required = false
        )
        public String reason;
    }

    // Atlas 推論エンジンに構造化データを返す出力ラッパークラス
    public class OrderCancellationResult {
        @InvocableVariable(
            label = 'Is Success' 
            description = '注文のキャンセル処理が正常に完了したかを示す真偽値。'
        )
        public Boolean isSuccess;

        @InvocableVariable(
            label = 'Cancellation Reference Code' 
            description = 'キャンセル処理完了時に発行された監査用追跡コード。'
        )
        public String referenceCode;

        @InvocableVariable(
            label = 'Status Message' 
            description = '処理結果の説明、またはエラー時の詳細メッセージ。'
        )
        public String message;
    }

    @InvocableMethod(
        label = 'Cancel Customer Order'
        description = '未完了状態の顧客注文をキャンセルし、追跡コードを発行します。注文ステータスが Pending または Processing であり、顧客が明示的にキャンセルを要求した場合にのみ実行してください。'
        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 {
                // ユーザーモードでのセキュリティチェック
                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 = '指定された注文番号が見つかりません: ' + req.orderNumber;
                    results.add(res);
                    continue;
                }

                Order targetOrder = orders[0];
                if (targetOrder.Status == 'Activated' || targetOrder.Status == 'Completed') {
                    res.isSuccess = false;
                    res.message = '注文 ' + req.orderNumber + ' はすでに発送済みまたは完了しているため、自動キャンセルできません。';
                    results.add(res);
                    continue;
                }

                targetOrder.Status = 'Cancelled';
                targetOrder.Description = 'Agentforce 経由でキャンセル。理由: ' + (req.reason != null ? req.reason : '未指定');

                Database.SaveResult sr = Database.update(targetOrder, AccessLevel.USER_MODE);
                if (sr.isSuccess()) {
                    res.isSuccess = true;
                    res.referenceCode = 'CAN-' + System.currentTimeMillis();
                    res.message = '注文が正常にキャンセルされました。';
                } else {
                    res.isSuccess = false;
                    res.message = 'データベースのレコード更新に失敗しました。';
                }
            } catch (Exception ex) {
                res.isSuccess = false;
                res.message = '注文キャンセル処理中に例外が発生しました: ' + ex.getMessage();
            }

            results.add(res);
        }

        return results;
    }
}

Apex 開発における重要ベストプラクティス

• 単一責任の原則: 1 つのクラスに複数の無関係な操作を詰め込む「神クラス（God Class）」化を避けてください。アクションを単一の明確な責務に絞り込むことで、Atlas が適切な順序でツールを組み合わせて推論できるようになります。
• 未処理例外を投げず構造化エラーを返す: 未処理の Exception がスローされると、エージェントは会話を中断するか異常終了します。try-catch で捕捉し、isSuccess = false とわかりやすい message を返すことで、エージェントはユーザーに理由を説明し、再試行やパラメータの再確認を行えます。
• ユーザーモードの徹底: クラス定義に with sharing を付与し、SOQL では WITH USER_MODE、DML では AccessLevel.USER_MODE を指定して、エージェント実行ユーザーの権限外のデータへの不正アクセスを防止します。

ステップ 2: 設定画面でのアクション登録

1. Salesforce の 設定（Setup） に移動し、クイック検索で Agent と入力して Agentforce Assets（または Agent Actions）を選択します。
2. New Agent Action（新規エージェントアクション） をクリックします。
3. Reference Action Type（参照アクションタイプ） で Apex を選択します。
4. 対象クラス OrderCancellationService とメソッド Cancel Customer Order を選択します。
5. アノテーションから自動抽出された表示ラベルや説明文を確認し、Action Instructions（アクション指示） に詳細な利用条件を記載します（例: 「認証済み顧客が注文キャンセルを明示した場合にのみ実行。注文番号が不明な場合は必ず聞き返すこと」）。
6. 保存します。

3. ヘッドレス Flow によるカスタムアクションの構築と公開

標準オブジェクトのレコード操作、既存の承認申請、宣言的な業務ロジックの再利用には、Autolaunched Flow が迅速でメンテナンス性の高い選択肢となります。

フロータイプの制約

Agentforce がアクションとして呼び出せるのは、トリガーなしの自動起動フロー（Autolaunched Flow - No Trigger） のみです。画面フロー（Screen Flow）は人間による UI 操作を前提としており、レコードトリガーフローはデータベースイベントによって発火するため、エージェントの呼び出し対象にはできません。ヘッドレスな要求・応答インターフェースが必須です。

[ ユーザーの発話:「配送先住所を東京都千代田区1-1に変更してください」 ]
                               │
                               ▼
                   [ Agentforce アクション計画 ]
                               │
       (パラメータ抽出: orderId, streetAddress, city)
                               │
                               ▼
         [ 自動起動フロー: 注文配送先住所の更新 ]
                ┌─────────────────────────┐
                │ レコード取得: 対象の注文 │
                ├─────────────────────────┤
                │ 決定要素: 配送状況の確認 │
                ├─────────────────────────┤
                │ レコード更新: 住所の更新 │
                └─────────────────────────┘
                               │
         (出力変数: isUpdated = True, confirmationMsg)
                               │
                               ▼
                   [ Atlas が自然言語応答を生成 ]

フローの作成手順

1. フローの新規作成: Flow Builder を開き、Autolaunched Flow (No Trigger) を選択します。
2. 入力変数の定義:
   • テキスト変数 var_orderId を作成し、入力可能（Available for input） にチェックを入れます。
   • 説明（Description）: 「対象注文レコードの 18 桁の Salesforce レコード ID。」 と記載します。
   • 同様に var_streetAddress などの必要な入力変数を定義し、説明を充実させます。
3. 出力変数の定義:
   • ブール変数 var_isUpdated を作成し、出力可能（Available for output） にチェックを入れます。説明: 「住所変更が正常に保存された場合 True。」
   • テキスト変数 var_statusMessage を作成し、出力可能にチェックを入れます。
4. ロジックの構築:
   • レコードを取得 要素で注文を照会。
   • 決定 要素で変更可能な配送ステータスか判定。
   • レコードを更新 要素で新しい住所を反映。
   • 割り当て 要素で出力変数に結果を代入。
5. 保存と有効化: Agent_Update_Order_Address として保存し、有効化（Activate）します。

ステップ 3: フローアクションの登録

1. 設定 > Agentforce Assets > New Agent Action に移動します。
2. Reference Action Type で Flow を選択します。
3. 作成した Agent_Update_Order_Address を選択します。
4. 入力可能・出力可能として設定された各変数の説明が、LLM にとって分かりやすい表現になっているか確認します。
5. アクション指示を設定し保存します。

4. MuleSoft API を External Services および API Catalog 経由で公開

エンタープライズの現場では、Salesforce 外部の基幹 ERP（SAP、Oracle）、外部倉庫システム、決済プロバイダーなどのデータ連携が頻繁に発生します。MuleSoft は統合とデータガバナンスを担い、Salesforce は External Services（外部サービス） と API Catalog（API カタログ） を介してこれらをエージェントが呼び出せるアクションへと変換します。

2 つの統合アプローチの比較

[ 基幹 ERP / SAP / 社内データベース ]
                  │
                  ▼
    [ MuleSoft Anypoint Platform ]
 (System, Process, Experience APIs)
                  │
   (Topic Center 管理 / OAS 3.0 仕様)
                  │
                  ▼
  [ Salesforce Anypoint 連携と同期 ]
                  │
     ┌────────────┴────────────┐
     ▼                         ▼
[ 指定ログイン情報 ]    [ Salesforce API カタログ ]
 (認証と資格情報管理)     (企業 API の統合ディスカバリ)
     │                         │
     └────────────┬────────────┘
                  ▼
      [ External Services ]
      (Invocable アクション自動生成)
                  │
                  ▼
   [ Agentforce カスタムアクションライブラリ ]

ステップ 1: AI 向け OpenAPI 仕様（OAS）の設計

Atlas 推論エンジンは、OpenAPI 仕様書を読み解いてエンドポイントやパラメータを把握します。エージェント向け API の設計では以下の点に留意します。

• 全パラメータへの説明付与: パス変数、クエリ文字列、JSON オブジェクトの各フィールドに、具体的で理解しやすい description を記述します。
• スキーマの単純化: 複雑な多態性（oneOf、anyOf）や過度に深いネスト構造を避け、フラットで明確なデータ構造を保ちます。
• 明確な HTTP ステータスとエラーボディ: 正常系（200）だけでなく、エラー時（400、404、500）にも原因を明確に記述した JSON レスポンスを定義します。

倉庫在庫照会 API の OpenAPI 3.0 仕様スニペット:

openapi: 3.0.3
info:
  title: Enterprise Warehouse API
  version: 1.0.0
  description: リアルタイム倉庫在庫照会サービス。
paths:
  /inventory/{sku}:
    get:
      summary: SKU に基づく倉庫在庫数の照会
      description: 指定された製品 SKU の利用可能在庫数、保管拠点、再入荷リードタイムを返します。
      operationId: getInventoryBySku
      parameters:
        - name: sku
          in: path
          required: true
          description: 製品の一意な SKU コード（例: PROD-WIDGET-99）。
          schema:
            type: string
      responses:
        '200':
          description: 在庫照会成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  sku:
                    type: string
                    description: 照会対象の製品 SKU。
                  quantityOnHand:
                    type: integer
                    description: 倉庫に物理的に存在する実在庫数。
                  isAvailableToShip:
                    type: boolean
                    description: 即時出荷が可能であるかを示すフラグ。
                  warehouseRegion:
                    type: string
                    description: 対象製品を保管する配送拠点地域。
        '404':
          description: 該当する SKU が見つかりません

ステップ 2: Salesforce への同期とアクション生成

1. Anypoint 接続の設定: Salesforce 設定 の Anypoint Platform Setup で、組織 ID とクライアント資格情報を用いて接続を確立します。
2. API カタログへの同期: MuleSoft Topic Center または Exchange で対象 API に sf-api-catalog タグを付与し、Salesforce の API Catalog 画面で該当エンドポイントをアクションとして有効化します。
3. 指定ログイン情報（Named Credentials）の構成: セキュアな外部通信のため、適切な認証プロトコル（OAuth 2.0 など）を設定します。
4. エージェントアクションの生成: Agentforce Assets で新規作成し、タイプに External Service を指定して API 操作を関連付けます。

5. Agentforce Builder でのトピックへの組み込みと制御

作成したカスタムアクションは、Agentforce Builder 内の**トピック（Topics）**に割り当てることで、初めて実行可能な状態になります。トピックは、Atlas 推論エンジンが業務領域を分離し、アクションの適用範囲を限定するための境界です。

[ 自律型エージェント: カスタマーサービスエージェント ]
                       │
       ┌───────────────┴───────────────┐
       ▼                               ▼
[ トピック: 注文の変更と配送 ]      [ トピック: 返品と保証サポート ]
   (業務範囲の限定と分類)             (業務範囲の限定と分類)
       │
   ┌───┴───────────────────────────────┐
   ▼                                   ▼
[ アクション: 注文状態の照会 ]     [ アクション: 注文のキャンセル ]
(Autolaunched Flow)                (Invocable Apex)

トピックへの割り当て手順

1. Agentforce Builder を開き、対象のエージェントを選択して編集モードに入ります。
2. 既存のトピックを選択するか、New Topic（新規トピック） を作成します（例: Order Logistics and Changes）。
3. トピック分類の説明（Topic Classification Description） を入力し、どのような質問や要望がこのトピックに該当するかを定義します。
4. トピック内の Actions タブで Add Action をクリックし、作成した Apex、Flow、MuleSoft のアクションを追加します。

高品質なトピック指示とアクション指示の記述

指示（Instructions）は、エージェントの自律的な判断を誘導する重要なガイドラインです。

### トピック指示: Order Logistics and Changes
- 顧客からの注文状況の照会、配送先の変更、注文キャンセルの手続きをサポートします。
- 注文をキャンセルする前に、必ず現在の状況を確認し、顧客に対してキャンセルの意思を再確認してください。
- 既に出荷済みでキャンセルできない場合は、理由を丁寧に説明し、返品手続きを案内してください。

### アクション指示: Cancel Customer Order
- 顧客が注文番号を明示し、キャンセルの確認に同意した後にのみ実行してください。
- 注文番号が提供されていない場合は、「キャンセルをご希望の注文番号を教えていただけますでしょうか？」と尋ねてください。
- 処理が完了したら、返却された確認コード（referenceCode）を必ず顧客に伝えてください。

Human-in-the-Loop（人間の介在と事前確認）

レコードの更新や削除、決済処理、キャンセルなどの取り消しが難しいアクションでは、アクション設定の Require Confirmation（確認を要求） を有効にします。これにより、エージェントはアクションを直接実行する前に「注文 ORD-10023 をキャンセルしてもよろしいですか？この操作は取り消せません」といった確認を必ずユーザーに求め、明示的な承認を得てからバックエンド処理を実行します。

6. 技術選定の比較マトリクス

要件に応じて適切な実装方式を選択することで、保守性、セキュリティ、実行速度のバランスを最適化できます。

7. テスト検証、権限管理、および本番展開

1. エージェント実行ユーザー（Agent User）の権限設定

エージェントがアクションを実行する際、そのアクセス権限は構成された Agent User に依存します。導入時のトラブルで最も多い原因は権限不足です。

• Apex クラスのアクセス権: Agent User のプロファイルまたは権限セットに対象 Apex クラスのアクセスを許可します。
• フローの実行権限: Agent User に フローを実行（Run Flows） 権限が付与されていることを確認します。
• 指定ログイン情報と FLS: MuleSoft を呼び出す場合は Named Credential へのアクセスを付与し、更新対象のオブジェクトおよび項目レベルセキュリティ（FLS）の参照・更新権限を解放します。

2. 段階的なテスト検証

1. Apex 単体テスト: テストクラスを作成し（コードカバレッジ 85% 以上を推奨）、null 入力や権限不足時の例外処理が正しくハンドリングされることを検証します。
2. Agentforce Builder での対話テスト: テストパネルで顧客の様々な質問を入力し、Reasoning（推論）タブで Atlas が意図通りにトピックを認識し、パラメータを抽出してアクションを呼び出しているかを追跡します。
3. Agentforce Testing Center での回帰テスト: 大量のテストケースを用意し、アクションの選択精度や意図の認識率、ハルシネーションの発生有無を自動評価・測定します。

Invocable Apex の決定論的な制御力、Autolaunched Flow のローコード開発スピード、そして MuleSoft API の強力な外部接続性を組み合わせることで、堅牢で拡張性の高いエンタープライズ AI エージェントの基盤を構築できます。

参考文献

• 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