見出し画像
Photo by daisaw33

【第434回】 Agentforce ： カスタム Lightning タイプ（エディタ＋レンダラーオーバーライド版）

Nobuyuki Watanabe

前回の記事では、レンダラーオーバーライド を利用し、カスタム Lightning タイプ を使って、出力でリッチな UI を表示する方法を紹介しました。

複数のホテルが表示される

今回の記事では、Salesforce 公式が用意している別のサンプルシナリオ を実際に試していきます。

公式サンプルは大きく 2 種類 用意されており、前回の記事では ② を扱いました。今回は ① のシナリオを取り上げます。

公式サンプル（2 種類）

① エディタ＋レンダラーオーバーライド
（入力 UI と出力 UI をフルコントロール）
https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-example-full-editor-renderer.html

② レンダラーオーバーライド
（出力 UI のカスタマイズに特化）
https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-example-collection-renderer.html

これらの公式サンプルは、取得データがあらかじめハードコードされている ため、検証のために新しいオブジェクトやレコードを作成する必要がありません。まずは挙動を確認したい、という用途に非常に向いています。

なお、本記事執筆時点で カスタム Lightning タイプに対応しているエージェント は以下のとおりです。

  • Agentforce Service Agent（拡張チャット v2）

  • Agentforce Employee Agent

本記事では、①「エディタ＋レンダラーオーバーライド」 の実装手順を整理していきます。

実際の手順を追いながら確認していただくことで、
・「どの程度の設計・実装コストがかかるのか」
・「自分のプロジェクトで採用できそうか」
といった判断材料として活用していただければと思います。

全体の流れ

作業の全体像は以下のとおりです。

  1. Salesforce CLI をインストール

  2. VS Code + Salesforce Extension Pack をインストール

  3. Salesforce Org にログイン（認証）

  4. プロジェクトを作成

  5. force-app/main/default/ 配下に以下を配置

    • 1. Apex

    • 2. LWC

    • 3. LightningTypeBundle

  6. デプロイ

  7. Agentforce Action の設定

それでは一つずつ手順を確認してみましょう。

① Salesforce CLI をインストール

Salesforce 開発を行うためには、まず Salesforce CLI をインストールします。

インストールが完了したら、ターミナル（Windows：PowerShell / macOS・Linux：Terminal）を開き、正しくインストールされているか確認します。

sf --version

② VS Code + Salesforce 拡張機能をインストール

次に、開発環境として Visual Studio Code（VS Code） をインストールします。

VS Code のインストールが完了したら、VS Code を起動して「Salesforce Extension Pack」をインストールします。

手順

  1. 左側メニューから Extensions（拡張機能） をクリック

  2. 検索ボックスに「Salesforce Extension Pack」を入力し、表示された拡張機能をインストール

この拡張パックには、以下が含まれています。

  • Apex

  • Lightning Web Components（LWC）

  • Salesforce CLI 連携（SFDX）

※ 個別に拡張機能を探して設定する必要はありません。

③ Salesforce Org にログイン（認証）

続いて、Salesforce CLI から Salesforce Org にログイン（認証） します。
ログイン先は Sandbox または Dev Org を想定しています。

手順

  1. VS Code を起動

  2. メニューから
    Terminal → New Terminal

  3. 表示されたターミナルで以下を実行すると、ログイン画面が開きます

Sandbox にログインする場合

sf org login web --instance-url https://test.salesforce.com

本番環境 または Dev Org にログインする場合

sf org login web

ログイン画面が開いたら、通常どおり Salesforce にログインしてください。
認証が成功すると、ターミナルに Org 情報が表示されます。
（※ 表示されるまで 1 分程度かかる場合があります。）

無事ログインできているかは、以下のコマンドでも確認できます。

sf org list

ログイン済みの Org が一覧に表示されていれば、準備完了です。

④ Salesforce プロジェクトを作成

作業用フォルダを作成

1. ローカル PC 上に作業用のフォルダを作成します。
（例：以下は Windows の場合です）

2. VS Code のターミナルを開き、以下のコマンドを入力して、作業フォルダ（work）へ移動します。

C:\work

Salesforce プロジェクトを生成

1. 作成した作業フォルダ（work）に移動した状態で、VS Code のターミナルを使用して、次のコマンドを実行します。

sf project generate --name agentforce-flight

2. 生成される構成は以下のとおりです。

C:\work\
 └─ agentforce-flight\
     ├─ force-app\
     ├─ sfdx-project.json
     └─ ...

3. このコマンドにより、work ディレクトリ配下に
Salesforce 開発用のプロジェクト一式が自動生成されます。

プロジェクトを VS Code で開く

1. 次に以下のコマンドを入力して、プロジェクトフォルダに移動します。

cd agentforce-flight

2. 以下のコマンドを入力して、VS Code でプロジェクトを開いてください。

code .

3. これで、作業場所の VS Code が開きます。こちらにサンプルのコードを配置していきます。

agentforce-hotel/
 ├─ force-app/
 │   └─ main/
 │       └─ default/
 ├─ sfdx-project.json
 └─ ...

⑤-1 force-app/main/default/ に Apex を配置

公式ページからダウンロードした各種データを、ローカルの classes フォルダ にドラッグ＆ドロップして配置します。

配置が完了すると、VS Code にも自動的に反映され、クラスファイルがプロジェクト内に認識されます。

サンプルは こちら（apexClass.zip）からダウンロードできます。

⑤-2 force-app/main/default/ に LWC を配置

公式ページからダウンロードした LWC 配下の
・ flightDetails フォルダ（出力用）
・ flightRequestFilter フォルダ（入力用）
を、そのまま LWC フォルダ にドラッグ＆ドロップして配置します。

フォルダを配置すると、VS Code にも自動的に反映され、特別な操作を行わなくてもファイルが認識されます。

サンプルデータは こちら（flightResponseCLTandLWC.zip / 出力用）とこちら（flightFiltersCLTandLWC.zip / 入力用）からダウンロードできます。

2 つのフォルダ（出力用・入力用）を格納したことを確認してください。

⑤-3 force-app/main/default/ に lightningTypes を配置

lightningTypes については、まだフォルダが存在しないため、まず default 配下 に lightningTypes という名前のフォルダを新規作成します。

次に、公式ページからダウンロードした lightningTypes 配下の
・ flightResponse フォルダ（出力用）
・ flightFilter フォルダ（入力用）
を、そのまま上で作成した lightningTypes フォルダ にドラッグ＆ドロップして配置します。

フォルダを配置すると、VS Code にも自動的に反映され、追加した Lightning Type がプロジェクト内で認識されます。

サンプルデータは こちら（flightResponseCLTandLWC.zip / 出力用）とこちら（flightFiltersCLTandLWC.zip / 入力用）からダウンロードできます。
※ LWC と同じ ZIP なので、そちらに格納されています。

2 つのフォルダ（出力用・入力用）を格納したことを確認してください。

ちなみにこのままだと input 側の表示はあまり変わりません。
もちろん変わりますが、どこが変わったのか？と思う内容になる予定です。

変更前

そこで HTML と CSS を変更してみましょう。

VS Code における lwc 配下の flightRequestFilter.html を、下記で上書きで保存してください。

<template>
    <lightning-card class="price-card">
        <div class="header">
            💰 <span class="title">Price & Discount</span>
        </div>

        <div class="content">
            <lightning-input 
                label="Price (between 1,000 and 20,000)"
                name="price"
                value={price}
                type="number"
                min="1000"
                max="20000"
                step="1"
                onchange={handleInputChange}
                read-only={readOnly}>
            </lightning-input>

            <lightning-input 
                label="Discount Percentage (0% to 100%)"
                name="discountPercentage"
                value={discountPercentage}
                type="number"
                min="0"
                max="100"
                step="1"
                onchange={handleInputChange}
                read-only={readOnly}>
            </lightning-input>
        </div>
    </lightning-card>
</template>

VS Code における lwc 配下の flightRequestFilter.css を、下記で上書きで保存してください。

.price-card {
    border-radius: 12px;
    box-shadow: 0 4px 12px rgba(0,0,0,0.08);
}

.header {
    font-size: 1.1rem;
    font-weight: 600;
    padding: 12px 16px;
    background: linear-gradient(90deg, #e3f2fd, #f9fbff);
    border-bottom: 1px solid #d8dde6;
}

.content {
    padding: 16px;
}

⑥ Salesforce にデプロイする

すべてのコードの配置が完了したら、以下のコマンドを実行します。ユーザー名は、今 Salesforce Org にログインしているユーザー名に変更してください。[ ] は不要です。

sf project deploy start --verbose -o [ユーザー名]

これにより、デプロイが開始されます。デプロイが成功すると、

  • Apex

  • LWC

  • LightningTypeBundle

すべてが org に登録されます。

⑦ Agentforce Action の設定

1. まず、Agentforce Employee Agent を起動し、新規トピックを作成します。

2. トピックの説明として、I'd like to use this topic to find flights. を入力します。

3. 今回は特にカスタマイズせず、そのまま ［次へ］ をクリックし、トピックを作成します。

4. 完了します。

アクションの追加

1. 作成したトピックを開いたら、アクションタブから 新規アクション を追加します。

2. 参照アクション種別で「Apex」を選択します。
※ ここで使用する Apex クラスは、あらかじめ VS Code からデプロイ済みです。

3. 参照アクションカテゴリは「Invocable Method」を選択します。

4. 参照アクションは「Find Flights」を選択して、次へをクリックします。

Agent Action Configuration の設定

1. 次に表示される Agent Action Configuration では、以下のように設定します。

Agent Action Instructions
- Use this action when the user provides an origin city, destination city, and travel date to find available flights.
- ユーザーが出発地、目的地、搭乗日を指定して、利用可能なフライトを検索したい場合にこのアクションを使用します。

Loading Text
- Searching for available flights…
- 利用可能なフライトを検索しています…

dateOfTravel Instructions
- Enter the travel date in YYYY-MM-DD format.
- 搭乗日を YYYY-MM-DD 形式で入力してください。
※ Require input と Collect data from user の両方にチェックを入れる

destinationCity Instructions
- Enter the name of the city you want to travel to.
- 目的地となる都市名を入力してください。
※ Require input と Collect data from user の両方にチェックを入れる

filters Instructions
- (Optional) Enter filters such as maximum price and discount percentage to narrow down results.
- （任意）上限価格や割引率などの条件を入力して、検索結果を絞り込めます。
※ Collect data from user のみにチェックを入れる（任意入力のため）

originCity Instructions
- Enter the name of the city where your flight departs.
- 出発地となる都市名を入力してください。
※ Require input と Collect data from user の両方にチェックを入れる

aFlight Instructions
- Returns a list of available flights that match the specified criteria.
- 指定された条件に一致する利用可能なフライトの一覧を返します。
※ Show in conversation にのみチェックを入れる

標準 Lightning タイプでの動作確認

1. 今回はまず、Output Rendering を デフォルトのまま
@apexClassType/c__AvailableFlight に設定します。

デフォルトのままにすることで、標準 Lightning タイプを使用した表示を確認するためです。左のような表記が期待されます。

2. Input 側も Input Rendering をデフォルトのまま@apexClassType/c__FlightRequestFilter としておきます。

そもそもなぜこの入力フォームを用いるか？ですが、
カスタム Lightning タイプ を使わないと
→ LLM が「テキストで聞こう」と判断するケースがあるためです。

  • カスタム Lightning タイプ を使うと
    → 「これはフォーム入力だ」と LLM が理解し、
    Text ではなく UI コンポーネント経由で入力を集められるようになるため、LLM の解釈を介さず、そのまま Apex に構造化データとして渡り、
    「文章を理解する」から「正確な値を入力する」UXに変わるということです。

3. 設定を保存したら、一度画面を F5 で更新し、プレビューを表示します。
入力欄に 「Find Flights」 と入力してください。

4. すると、入力フォームが表示されます。以下の値を入力します。

  • originCity
    Tokyo

  • destinationCity
    New York

  • dateOfTravel
    2026/03/15

5. フィルター部分においても、入力フォームで表示されていることが確認できますが、これは、まだカスタム Lightning タイプによる表示ではありません。以下の値を入力して「送信」してください。

  • discountPercentage
    20

  • price
    空欄

このサンプルでは、検索条件に関わらず あらかじめハードコードされた結果が返される仕様になっています。

注意：なお、このようなフォーム表示は 「Collect data from user」 にチェックを入れた場合にのみ有効です。
チェックを入れていない場合は、テキストベースの質問形式になります。

6. 結果として、フライト情報が表示されますが、出力も まだカスタム Lightning タイプによる表示ではありません。

カスタム Lightning タイプへの切り替え

1. 続いて、出力表示をカスタム Lightning タイプで上書きするため、
一度このアクションを削除し、再作成します。

2. アクションの作成手順は先ほどと同じですが、
aFlight の Output Rendering で 「FlightResponse」 を選択します。
この設定により、レンダラーを使って出力をオーバーライドしている状態になります。

この変更により、右のような表記が期待されます。

3. また Input 側の filters においても、「FlightFilter」を選択して エディタを使って入力をオーバーライドしている状態にします。

最終確認

1. 設定を保存後、再度 F5 で画面を更新し、プレビューを確認します。こちらも同様に 「Find Flights」 と入力します。

2. 先ほどと同様に、以下を入力します。

  • originCity
    Tokyo

  • destinationCity
    New York

  • dateOfTravel
    2026/03/15

フィルターの箇所も表示が変更されて、若干ですが リッチな UI となり表示されていることが確認できると思います。以下の値を入力して、「送信」してください。

  • discountPercentage
    20

  • price
    空欄

（私がアレンジしたもので HTML と CSS の上書きを行っている場合は、下記の通り「Price & Discount」が表示されていると思います。）

3. すると、出力の方でも、意図したカスタムデザインで表示されることが確認できました。
これで設定は成功です。

いかがでしたでしょうか。

本記事では、エディタ＋レンダラーをオーバーライドするカスタム Lightning タイプ を使い、Agentforce の 入力から出力までをフルコントロールする方法 を確認しました。

カスタム Lightning タイプ を利用することで、
テキスト入力に依存せず 構造化された UI から正確な値を取得 し、
出力も 意図したデザインで表示 できるようになります。

設計・実装の難易度は高めですが、
業務用途や正確性が求められるシナリオ では非常に有効な手法です。

まずは公式サンプルを動かし、
自分のユースケースに適用できるかを見極めてみてください。

今回は以上です。


次の記事はこちら

前回の記事はこちら

私の note のトップページはこちら